Default Access Policy
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.
![c85788e-AppAccess_OOTB_Allow_access_from_all_devices.png 2306](https://files.readme.io/c85788e-AppAccess_OOTB_Allow_access_from_all_devices.png)
In many cases a predefined or custom Access policy is required and must be manually selected and assigned.
![70807a9-AppAccess_Access_Policy_Selection.png 948](https://files.readme.io/70807a9-AppAccess_Access_Policy_Selection.png)
Following selection, the chosen Access policy will be evaluated once the changes to the application have been saved.
![ebafc93-AppAccess_Custom_Access_Policy_Adaptive_Access.png 2316](https://files.readme.io/ebafc93-AppAccess_Custom_Access_Policy_Adaptive_Access.png)
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.
![4b2e871-API_Client_Manage_Access_Policies.png 2318](https://files.readme.io/4b2e871-API_Client_Manage_Access_Policies.png)
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 datavalidations
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 thelabel
update above) a new revision may be created and therevision
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.
![4834ca3-AppAccess_Tenant_Default_Access_Policy.png 2304](https://files.readme.io/4834ca3-AppAccess_Tenant_Default_Access_Policy.png)
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 labelAllow 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 toAllow 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 3 months ago