Managing earlier access policies with the APIs

An access policy is a set of rules and conditions that are evaluated to determine the access decision. You can create customized access policies. All customized access policies are displayed as options in the application configuration.

About this task

Note: Version 1.0 of the access policy schema is deprecated. Newly created and updated v1.0 schema policies are converted to the latest schemaVersion format and the converted access policy are evaluated at run time. Use the latest schemaVersion that enables a number of new conditions in access policies. Access policies that are created or updated with the latest schemaVersion are not compatible with an earlier version. Changes are not reflected on the /v1.0/policyvault/accesspolicy endpoint or the associated policies. See Managing access policies through the APIs.

Some default access policies are provided for immediate use and cannot be modified. Tenants can add customized access policies according to their needs.

Access policies are in the following JSON format:

{
	"name": "policy_name",
	"description": "Description of the policy",
	"schemaVersion": "access:policy:1.0:schema",
	"format": "json",
	"rules": [
		{
			"name": "allow_with_conditions",
			"conditions": {
				"devicePlatform": [
					"IOS",
					"ANDROID",
					"OTHER_MOBILE",
					"MACOS",
					"WINDOWS",
					"OTHER_DESKTOP"
				],
				"deviceCompliance": [
					"COMPLIANT",
					"NONCOMPLIANT",
					"UNKNOWN"
				],
				"contextAttributes": {
					"attributes": [
						{
							"name": "attrName",
							"values": [
								"value1",
								"value2"
							],
							"op": "EQ"
						}
					]
				},
				"subjectAttributes": {
					"attributes": [
						{
							"name": "realmName",
							"values": [
								"cloudIdentityRealm",
								"www.ibm.com"
							],
							"op": "IN"
						},
						{
							"name": "customAttr1",
							"values": [
								"val1"
							],
							"op": "NEQ"
						}
					]
				}
			},
			"actions": {
				"allowAccess": true
			}
		},
		{
			"name": "mfa_once_per_session",
			"conditions": {},
			"actions": {
				"allowAccess": true,
				"requireFactor": true,
				"factorFrequency": "PER_SESSION"
			}
		},
		{
			"name": "deny_otherwise",
			"conditions": {},
			"actions": {
				"allowAccess": false
			}
		}
	]
}

Note: Most of the API is already described in the swagger documentation. You can access the swagger documentation from the administrator console Settings > API Access > API documentation. For more information about the swagger APIs, see Verify Application programming interfaces (APIs)

The following information applies to the API rules.

Each rule consists of these properties:

name

A name for the rule.

actions

The action to run when all the conditions are met.

conditions

More than one condition can be present per rule. All conditions in the rule must evaluate to true for the rule to match and the result to be applied. The default rule contains an empty condition.

result

The outcome of the rule that includes the action and authentication mechanism.
The conditions contain the following properties:

devicePlatform

The operating system and device platforms such as iOS, Android, Mac OS X. The allowed values are IOS, ANDROID, OTHER_MOBILE, MACOS, WINDOWS, OTHER_DESKTOP. This condition requires the Device Management subscription, see Configuring conditional access.

deviceCompliance

The compliance level of the device. The allowed values are COMPLIANT, NONCOMPLIANT, and UNKNOWN. This condition requires the Device Management subscription, see Configuring conditional access.

contextAttributes

The attributes that are contextual to the flow in which the access policy was run. These attributes include Device management, OpenID Connect, and HTTP request attributes.

subjectAttributes

The login session attributes that are associated with the authenticated user subject.
The attributes contain the following properties:

name

A name of the attribute.

values

The values of the attribute.

opCode

The operator.
The operators for the evaluation of attribute values:

EQ

All of the values are present.

NEQ

None of the values are present.

IN

One or more of the values are present.
The actions contain the following properties:

allowAccess

Specifies whether to allow access.

requireFactor

Specifies whether to require multifactor authentication.

factorFrequency

Specifies the frequency that is required for the multifactor authentication. Valid values are ALWAYS for every request and PER_SESSION for every login session.

OpenID Connect context attributes

Most of the following context attributes that are available to OpenID Connect applications are OIDC request parameters. Those attributes that do not match 1-1 with the request parameter names are provided with an explanation. For more information, see https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest and https://tools.ietf.org/html/rfc7636#section-4.3.

scope: An arbitrary space-separated list of scopes that this token receives. An example of a well-known scope is emailaddressprofileopenid.
response_type: One or more of the following values, codetokenid_token. For the supported values, see https://oidc-dev-test.ite1.idng.ibmcloudsecurity.com/developer/explorer/#!/OpenID_Connect/handleAuthorizeGet.
acr_values: Ties a specific ARC to a specific authentication.
method: A list of strings that contain the policies that were run, in the format urn:ibm:security:policy:id:<policy-id>.
claims: A complex JSON.
response_mode: A string, one of query fragment form_post.
response_method: Specifies the method that is returned from a request to a URI.
code_challenge_exist: A Boolean choice in a PKCE flow that specifies whether a code_challenge was sent in the request.
redirect_uri_scheme: The scheme component of the redirect URI that detects a non-browser user agent and the response.
client_type: Specifies whether a client is a public or confidential client. Confidential clients have a client secret.
request_type: Identifies the endpoint that the request came from, device_authorize, user_authorize, authorization, access_token, introspect, user_info, revoke, or client_registration.
realmName: The identity source that the user came from. This value is always cloudIdentityRealm for non-federated Cloud Directory users.

Cloud Directory subject attributes

The following subject attributes are available for users from Cloud Directory identity source.

displayName: The name that is displayed for the user.
name: The given name followed by the surname.
family_name: The surname of the user.
given_name: The given name of the user.
email: The email of the user.
emailAddress: The email of the user.
groupIds: The group IDs.
preferred_username: A changeable user name.
uuid: A unique identifier for the user.
uniqueSecurityName: A unique identifier for the user.
realmName: This value is always cloudIdentityRealm for non-federated Cloud Directory users.
userType: This value is always regular for non-federated Cloud Directory users.

Procedure

Get an access token.

Use an API client that has the manageAccessPolicies (Manage access policies) entitlement to generate an access token.

Request:

curl https://<tenant-hostname>/oidc/endpoint/default/token 
-d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

Response:

{
  "access_token": <access_token>,
  "token_type": "Bearer",
  "expires_in": 7199
}

Save the access token for subsequent requests.

Send the access policy as part of the request body.

Request:

curl -X POST \
  https://<tenant-hostname>/v1.0/policyvault/accesspolicy \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
	"name": "policy_name",
	"description": "Description of the policy",
	"schemaVersion": "access:policy:1.0:schema",
	"format": "json",
	"rules": [
		{
			"name": "allow_with_conditions",
			"conditions": {
				"devicePlatform": [
					"IOS",
					"ANDROID",
					"OTHER_MOBILE",
					"MACOS",
					"WINDOWS",
					"OTHER_DESKTOP"
				],
				"deviceCompliance": [
					"COMPLIANT",
					"NONCOMPLIANT",
					"UNKNOWN"
				],
				"contextAttributes": {
					"attributes": [
						{
							"name": "attrName",
							"values": [
								"value1",
								"value2"
							],
							"op": "EQ"
						}
					]
				},
				"subjectAttributes": {
					"attributes": [
						{
							"name": "realmName",
							"values": [
								"cloudIdentityRealm",
								"www.ibm.com"
							],
							"op": "IN"
						},
						{
							"name": "customAttr1",
							"values": [
								"val1"
							],
							"op": "NEQ"
						}
					]
				}
			},
			"actions": {
				"allowAccess": true
			}
		},
		{
			"name": "mfa_once_per_session",
			"conditions": {},
			"actions": {
				"allowAccess": true,
				"requireFactor": true,
				"factorFrequency": "PER_SESSION"
			}
		},
		{
			"name": "deny_otherwise",
			"conditions": {},
			"actions": {
				"allowAccess": false
			}
		}
	]
}'