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 .
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
, andUNKNOWN
. 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 andPER_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
orconfidential
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
, orclient_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.
- 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.