HomeUse CasesConceptsConfig GuidesDeveloper GuidesAPI Reference

Default Access Policy

Suggest Edits

Introduction

Access policies in IBM Security Verify provide a context rich authorization framework to facilitate a frictionless user experience whilst protecting your critical business applications from unauthorized access.

When a new application is created, the Use default policy box is checked under Access policies in the Sign-on tab. By default, the Allow access from all devices Access policy is selected and no evaluation will occur when the application is accessed.

2306

In many cases a predefined or custom Access policy is required and must be manually selected and assigned.

948

Following selection, the chosen Access policy will be evaluated once the changes to the application have been saved.

2316

This process is sufficient for a small number of applications and demonstrations, however can become tedious to apply to more than a few applications and can lead to missed configuration and therefore unauthorized access and audit exposures when manual assignment is required across a large number of applications.

Updating a custom Access policy using the Access Policy Vault API enables all applications that have Use default policy assigned to evaluate that Access policy during the Federated Single Sign On flow.

❗️

Predefined Access policies cannot be assigned as the default.

Assigning the default Access policy requires an update (PUT) to the policy JSON which is not permitted for predefined Access policies.

The mitigation is to create a custom Access policy with the same rules or default rule as the predefined version.
The JSON of predefined Access policies 1 - 18 can be retrieved using the Access Policy Vault API and the payload copied to create a new custom Access policy with the same contents.

Refer to Table 2. Predefined access policies in the Access Policies topic for descriptions and features of the predefined Access policy logic.

Pre-requisites

The steps in this guide will use a custom Access policy to require 2FA for all users once per session, recreating the logic of predefined Access policy ID 18 Require 2FA each session in all devices and setting this as the default policy.

Calling the Access Policy Vault APIs will require an Access Token with Manage access policies entitlement.

Create API client

You can create, or reuse an existing API client.

Refer to Create an API client and follow the steps for Option 1 - Stand-alone API client.

When selecting the Entitlements only Manage access policies is required for this scenario.

2318

Obtain an Access Token

Using the client_id and client_secret from the connection details obtained in Create API client, you can now Acquire an Access Token by following the steps in Client Credentials.

For example 

curl --location 'https://<tenant.verify.ibm.com>/v1.0/endpoint/default/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy' \
--data-urlencode 'client_secret=zzzzzzzzzz'

which will respond similar to 

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "grant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 7200
}

Ensure you save the value of the returned access_token as this will be required as input to the Access Policy Vault APIs.

Select an Access policy that will become the default

If you have an existing custom Access policy, you can skip ahead to Update the custom Access policy to be the default. You will need to know the Access Policy ID so it can be updated using the APIs.

📘

Note

It does not matter if your custom Access policy was created the Access policy APIs or in the Access Policy Editor within the Administration User Interface of your Verify instance.

❗️

Check your Access policy assigned to Portal Access for Administration console access and Home page access.

The default Access policy configuration currently only applies to Applications.

Whilst an assigned default Access policy is not currently enforced for Portal Access of Administration console access or Home page access is it recommended individual Access policies are manually assigned to these items to prevent any confusion of which Access policy will be enforced.

At minimum an Access policy requiring Require MFA once per session in all devices for all users or Adaptive Access` should be applied to Administration console access.

The following steps will retrieve predefined Access policy ID 18 Require 2FA each session in all devices and create a new custom Access policy with the same logic, using the APIs.

Retrieve Access policy ID 18 Require 2FA each session in all devices

Using the access_token from Obtain an Access Token, retrieve (GET) Access policy ID 18

curl --location 'https://<tenant.verify.ibm.com>/policyvault/v5.0/policyvault/accesspolicy/18' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

The response will be

{
    "id": 18,
    "name": "Require 2FA each session in all devices",
    "description": "Prompt users to complete a second factor authentication one-time, on the first access attempt in an authenticated session with IBM Security Verify. Second factor authentication is not required on subsequent logins to other applications when the users access the applications within the same authenticated session.",
    "containsFirstFactor": false,
    "rules": [
        {
            "id": "100",
            "name": "mfa_once_per_session",
            "description": "",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "serverSideActions": [],
                "authnMethods": [
                    "urn:ibm:security:authentication:asf:macotp"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "revision": 0,
        "label": "system migration",
        "predefined": true,
        "created": 1524201037854,
        "createdBy": "admin",
        "lastActive": 1524201037854,
        "modified": 1524201037854,
        "modifiedBy": "admin",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO",
        "tenantDefaultPolicy": false
    },
    "validations": {
        "subscriptionsNeeded": [
            "civ.subscription"
        ]
    }
}

Keep a copy of the response JSON as this will be used as input for creating the custom Access policy with some minor updates.

Create custom Access Policy Require MFA once per session in all devices for all users

We will use the Access Policy Vault APIs, however you can also create a custom Access Policy in the Administration User Interface of your Verify instance.

Whilst it is possible to create a new Access policy and assign it as the default in a single operation, for the purposes of this article we will create the policy first and update it as the default so the same steps can be applied where a custom Access policy already exists.

Using the same access_token as above, create (POST) a new Access policy with a slightly reduced and modified version of the JSON response from Retrieve Access policy ID 18 Require 2FA each session in all devices.
The JSON payload is subset of the retrieved Access policy ID 18, providing the minimum parameter requirements for the V5 syntax.

curl --location 'https://<tenant.verify.ibm.com>/policyvault/v5.0/policyvault/accesspolicy' \
--header 'Accept: application/json; charset=utf-8' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
    "name": "Require MFA once per session in all devices for all users",
    "description": "Clone of Access policy ID 18",
    "rules": [
        {
            "id": "100",
            "name": "Default rule",
            "description": "MFA once per session with any factor",
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "authnMethods": [
                    "anyFactor"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "label": "Initial version",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO"
    }
}'

A HTTP status of 201 should be returned and the created Access policy JSON echoed back with similar notation to the retrieval of policy ID 18.

{
    "id": 1108755,
    "name": "Require MFA once per session in all devices for all users",
    "description": "Clone of Access policy ID 18",
    "containsFirstFactor": false,
    "rules": [
        {
            "id": "100",
            "name": "Default rule",
            "description": "MFA once per session with any factor",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "serverSideActions": [],
                "authnMethods": [
                    "anyFactor"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "revision": 0,
        "label": "Initial version",
        "predefined": false,
        "created": 1700632889971,
        "createdBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "lastActive": 1700632889971,
        "modified": 1700632889971,
        "modifiedBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO",
        "tenantDefaultPolicy": false
    },
    "validations": {
        "subscriptionsNeeded": [
            "civ.subscription"
        ]
    }
}

The response JSON has been augmented with

  • an id for the policy has been generated. This is required when updating (PUT) to assign as the default
  • meta has been enhanced with additional audit data
  • validations have been added to indicate the subscription requirements that must be maintained for this Access policy to be evaluated
  • helper fields such as containsFirstFactor, alwaysRun, firstFactor, serverSideActions have been added

Update the custom Access policy to be the default

In the returned Access policy JSON in Create custom Access Policy Require MFA once per session in all devices for all users, the meta field contained a parameter "tenantDefaultPolicy": false.

We will update (PUT) this value by including it with the entire Access policy JSON.

For convenience we will retrieve the full contents of the Access policy with our ID of 1108755.
If you saved the response from Create custom Access Policy Require MFA once per session in all devices for all users you can skip the retrieval of the Access policy. 

curl --location 'https://<tenant.verify.ibm.com>/policyvault/v5.0/policyvault/accesspolicy/1108755' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

which will return similar to 

{
    "id": 1108755,
    "name": "Require MFA once per session in all devices for all users",
    "description": "Clone of Access policy ID 18",
    "containsFirstFactor": false,
    "rules": [
        {
            "id": "100",
            "name": "Default rule",
            "description": "MFA once per session with any factor",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "serverSideActions": [],
                "authnMethods": [
                    "anyFactor"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "revision": 0,
        "label": "Initial version",
        "predefined": false,
        "created": 1700632889971,
        "createdBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "lastActive": 1700632889971,
        "modified": 1700632889971,
        "modifiedBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO",
        "tenantDefaultPolicy": true
    },
    "validations": {
        "subscriptionsNeeded": [
            "civ.subscription"
        ]
    }
}

Next we will update the policy using the entire payload returned from the GET. Note the only change made only for cosmetics is to update "label": "Tenant default" however this is optional and is for the purpose of this demonstration only.

curl --location --request PUT 'https://<tenant.verify.ibm.com>/policyvault/v5.0/policyvault/accesspolicy/1108755' \
--header 'Accept: application/json; charset=utf-8' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--data '{
    "id": 1108755,
    "name": "Require MFA once per session in all devices for all users",
    "description": "Clone of Access policy ID 18",
    "containsFirstFactor": false,
    "rules": [
        {
            "id": "100",
            "name": "Default rule",
            "description": "MFA once per session with any factor",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "serverSideActions": [],
                "authnMethods": [
                    "anyFactor"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "revision": 0,
        "label": "Tenant default",
        "predefined": false,
        "created": 1700632889971,
        "createdBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "lastActive": 1700632889971,
        "modified": 1700632889971,
        "modifiedBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO",
        "tenantDefaultPolicy": true
    },
    "validations": {
        "subscriptionsNeeded": [
            "civ.subscription"
        ]
    }
}'

A HTTP status of 201 should be returned with the response body echoed the input payload with the "tenantDefaultPolicy": true and updated meta parameters including "modified": 1700638825445, whereas the created has remained as the original value.

{
    "id": 1108755,
    "name": "Require MFA once per session in all devices for all users",
    "description": "Clone of Access policy ID 18",
    "containsFirstFactor": false,
    "rules": [
        {
            "id": "100",
            "name": "Default rule",
            "description": "MFA once per session with any factor",
            "alwaysRun": false,
            "firstFactor": false,
            "conditions": [],
            "result": {
                "action": "ACTION_MFA_PER_SESSION",
                "serverSideActions": [],
                "authnMethods": [
                    "anyFactor"
                ]
            }
        }
    ],
    "meta": {
        "state": "ACTIVE",
        "schema": "urn:access:policy:5.0:schema",
        "revision": 0,
        "label": "Tenant default",
        "predefined": false,
        "created": 1700632889971,
        "createdBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "lastActive": 0,
        "modified": 1700638825445,
        "modifiedBy": "4f2becf9-f203-4a31-b77e-2cebc9b42385",
        "scope": [
            "administrators"
        ],
        "enforcementType": "fedSSO",
        "tenantDefaultPolicy": true
    },
    "validations": {
        "subscriptionsNeeded": [
            "civ.subscription"
        ]
    }
}

❗️

Do not use Access policy revisions API https://<tenant.verify.ibm.com>/policyvault/v5.0/policyvault/accesspolicy/<access_policy_id>/revision/<revision> to update a revision and setting "tenantDefaultPolicy": true and "state": "ACTIVE".

The tenantDefaultPolicy can only be set on the main revision /policyvault/v5.0/policyvault/accesspolicy/<access_policy_id>.
If additional changes are made to the Access policy (in addition to the label update above) a new revision may be created and the revision value of the main policy incremented.

Test the default Access policy

The "tenantDefaultPolicy": true setting will take immediate effect and will overwrite any previously assigned default Access policy.

You can validate the update by creating a new application, or editing an application where the Use default policy box is checked, ensuing the Access policy name of the updated policy is displayed.

2304

When accessing that application, the assigned Access policy will be evaluated.

To reinstate usage of the default in applications, instead of manually assigning an Access policy, simply edit the application, check Use default policy and save the changes.

❗️

The assigned default Access policy is not currently enforced for Portal Access of Administration console access or Home page access.

In Portal Access, when Use default policy is checked the label Allow access from all devices is displayed indicating an updated application application default policy is not applied here.
Manually select the Access policy and save changes to override the Portal access policies.

Remove or modify the default Access policy

If you need to change the behavior of the default Access policy you can

  • Update the Access policy currently assigned using APIs or the Access Policy Editor; if you don't provide the tenantDefaultPolicy the currently assigned value will remain
  • Assign a new Access Policy by following the steps in Update the custom Access policy to be the default with a different Access policy ID
  • Update the Access policy currently assigned using APIs to set "tenantDefaultPolicy": false which will revert back to Allow access from all devices

Conclusion

Updating the default Access policy can be as simple as a single API call to create or update tenantDefaultPolicy in a custom Access policy.

The enforcement is immediate and removes the potential of inconsistencies where an incorrect Access policy is selected, or the application owner forgets to update the desired Access policy which in turn reduces unauthorized access and audit exposure.

Updated 27 days ago