PingOne Advanced Identity Cloud

Request policy decisions over REST

You can request policy decisions from PingOne Advanced Identity Cloud by using the REST API. PingOne Advanced Identity Cloud evaluates requests based on the context and the policies configured and returns decisions that indicate what actions are allowed or denied, as well as any attributes or advice for the resources specified.

This section does not apply to OAuth 2.0 policies.

Use the /json/realms/root/realms/realm-name/policies endpoints to request policy evaluation.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

To request decisions for specific resources, refer to Request policy decisions for specific resources.

To request decisions for a resource and all resources beneath it, refer to Request policy decisions for a tree of resources.

Access the endpoint

The REST calls to request policy decisions require that the subjects have the appropriate privileges:

  1. Create a group that grants the privileges required to request policy decisions.

    Under Native Consoles > Access Management, select Realms > Realm Name > Identities > Groups > + Add Group to create a group with the following settings:

    Group ID

    am-policy-evaluators

    Members

    Users that will perform policy evaluations

    Privileges

    Entitlement Rest Access

  2. Before making REST calls to evaluate policies, authenticate as the user whose access you want to evaluate:

    $ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <subject-username>' \
--header 'X-OpenAM-Password: <subject-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{"tokenId":"<subject-tokenId>","successUrl":"/enduser/?realm=/alpha","realm":"/alpha"}

    For additional details, refer to Session tokens after authentication.

    Use the <subject-tokenId> as the value of the <session-cookie-name> header to access the REST endpoints.

Request policy decisions for specific resources

To request policy decisions for specific resources, send an HTTP POST request to the policies endpoint with the evaluate action, for example: /json/realms/root/realms/alpha/policies?_action=evaluate.

The payload for the HTTP POST is a JSON object that specifies at least the resources and takes the following form.

{
    "resources": [
        "resource1",
        "resource2",
        ...,
        "resourceN"
    ],
    "application": "The policy set that contains the policies to evaluate against",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The values for the fields shown above are explained below:

resources

This required field specifies the list of resources for which to return decisions.

For example, depending on the patterns defined in the policy set, you could request decisions for resource URLs.

{
    "resources": [
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ]
}
application

This field holds the name of the policy set, for example, samplePolicySet.

For more on policy sets, refer to Policy sets over REST.

subject

This optional field holds an object that represents the subject.

If you do not specify the subject, PingOne Advanced Identity Cloud uses the SSO token ID of the subject making the request.

You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.

ssoToken

The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.

You can use an OpenID Connect ID token if the client that the token was issued for is authorized to use ID tokens as session tokens. For more information, refer to ID tokens as session tokens.

jwt

The value is a JWT string.

claims

The value is an object (map) of JWT claims to their values. Any string is permitted, but you must include the sub claim.

environment

This optional field holds a map of keys to lists of values.

If you do not specify the environment, the default is an empty map.

The example below requests policy decisions for two URL resources. The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "Accept-API-Version: resource=2.1" \
--header "<session-cookie-name>: AQIC5..." \
--data '{
    "resources":[
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ],
    "application":"iPlanetAMWebAgentService"
}' \
"https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies/?_action=evaluate"
[
    {
        "resource":"http://www.example.com/do?action=run",
        "actions":{

        },
        "attributes":{

        },
        "advices":{
            "AuthLevelConditionAdvice":[
                "3"
            ]
        }
    },
    {
        "resource":"http://www.example.com/index.html",
        "actions":{
            "POST":false,
            "GET":true
        },
        "attributes":{
            "cn":[
                "demo"
            ]
        },
        "advices":{

        }
    }
]

In the JSON list of decisions returned for each resource, PingOne Advanced Identity Cloud includes these fields.

resource

A resource specified in the request.

The decisions returned are not guaranteed to be in the same order as the resources were requested.

actions

A map of action name keys to Boolean values that indicate whether the action is allowed (true) or denied (false) for the specified resource.

In the example, for resource http://www.example.com:80/index.html HTTP GET is allowed, whereas HTTP POST is denied.

attributes

A map of attribute names to their values if any response attributes are returned according to applicable policies.

In the example, the policy that applies to http://www.example.com:80/index.html causes the value of the subject’s "cn" profile attribute to be returned.

advices

A map of advice names to their values if any advice is returned according to applicable policies.

The advices field can provide hints regarding what PingOne Advanced Identity Cloud needs to take the authorization decision.

In the example, the policy that applies to http://www.example.com:80/do?action=run requests that the subject be authenticated at an authentication level of at least 3.

{
    "advices": {
        "AuthLevelConditionAdvice": [
            "3"
        ]
    }
}

Refer to Policy decision advice for details.

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name...] to limit the fields returned in the output.

Policy decision advice

When PingOne Advanced Identity Cloud returns a policy decision, the JSON for the decision can include an "advices" field. This field contains hints for the policy enforcement point.

{
    "advices": {
        "type": [
            "advice"
        ]
    }
}

The "advices" returned depend on policy conditions. For more information about policy conditions, refer to Policies over REST.

This section shows examples of the different types of policy decision advice and the conditions that cause PingOne Advanced Identity Cloud to return the advice.

AuthLevel and LEAuthLevel condition failures can result in advice showing the expected or maximum possible authentication level. For example, failure against the following condition:

{
    "type": "AuthLevel",
    "authLevel": 2
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "2"
    ]
}

An AuthenticateToRealm condition failure can result in advice showing the name of the realm to which authentication is required. For example, failure against the following condition:

{
    "type": "AuthenticateToRealm",
    "authenticateToRealm": "alpha"
}

Leads to this advice:

{
    "AuthenticateToRealmConditionAdvice": [
        "/alpha"
    ]
}

An AuthenticateToService condition failure can result in advice showing the name of the required authentication journey. For example, failure against the following condition:

{
    "type": "AuthenticateToService",
    "authenticateToService": "MyIdentityCloudJourney"
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyIdentityCloudJourney"
    ]
}

A ResourceEnvIP condition failure can result in advice that indicates corrective action to be taken. The advice varies, depending on what the condition tests. For example, failure against the following condition:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.12] THEN authlevel=4"
    ]
}

Leads to this advice:

{
    "AuthLevelConditionAdvice": [
        "4"
    ]
}

Failure against a different type of ResourceEnvIP condition, such as the following:

{
    "type": "ResourceEnvIP",
    "resourceEnvIPConditionValue": [
        "IF IP=[127.0.0.11] THEN service=MyIdentityCloudJourney"
    ]
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyIdentityCloudJourney"
    ]
}

A Session condition failure can result in advice showing that access was denied because the user’s session was active longer than allowed by the condition. The advice also shows if the user’s session was terminated and reauthentication is required. For example, failure against the following condition:

{
    "type": "Session",
    "maxSessionTime": "10",
    "terminateSession": false
}

Leads to this advice:

{
    "SessionConditionAdvice": [
        "deny"
    ]
}

When policy evaluation denials occur against the following conditions, PingOne Advanced Identity Cloud does not return any advice:

  • IPv4

  • IPv6

  • LDAPFilter

  • OAuth2Scope

  • SessionProperty

  • SimpleTime

When policy evaluation is requested for a nonexistent or inactive subject, PingOne Advanced Identity Cloud returns an HTTP 200 code and a response that contains no actions or advice. Access to the resource is denied.

Request policy decisions for a tree of resources

This section shows how you can request policy decisions over REST for a resource and all other resources in the subtree beneath it.

When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/alpha.

To request policy decisions for a tree of resources, send an HTTP POST request to the policies endpoint with the evaluateTree action; for example /json/realms/root/realms/alpha/policies?_action=evaluateTree. The payload for the HTTP POST is a JSON object that specifies at least the root resource and takes the following form.

{
    "resource": "resource string",
    "application": "policy set that contains the policies to evaluate against",
    "subject": {
        "ssoToken": "SSO token ID string",
        "jwt": "JSON Web Token string",
        "claims": {
            "key": "value",
            ...
        }
    },
    "environment": {
        "optional key1": [
            "value",
            "another value",
            ...
        ],
        "optional key2": [
            "value",
            "another value",
            ...
        ],
        ...
    }
}

The values for the fields shown above are explained below:

resource

This required field specifies the root resource for the decisions to return.

For example, depending on the patterns defined in the policy set, you could request decisions for resource URLs.

{
    "resource": "http://www.example.com/"
}
application

This field holds the name of the policy set, for example, samplePolicySet.

For more on policy sets, refer to Policy sets over REST.

subject

This optional field holds an object that represents the subject. You can specify one or more of the following keys. If you specify multiple keys, the subject can have multiple associated principals, and you can use subject conditions corresponding to any type in the request.

ssoToken

The value is the SSO token ID string for the subject, returned for example on successful authentication as described in Authenticate using REST.

jwt

The value is a JWT string.

claims

The value is an object (map) of JWT claims to their values. If you do not specify the subject, PingOne Advanced Identity Cloud uses the SSO token ID of the subject making the request.

environment

This optional field holds a map of keys to lists of values.

If you do not specify the environment, the default is an empty map.

The example below requests policy decisions for http://www.example.com/. The <session-cookie-name> header sets the SSO token for a user who has access to perform the operation, and the subject takes the SSO token of the user who wants to access a resource.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: AQIC5...NDU1*" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "resource": "http://www.example.com/",
    "subject": { "ssoToken": "AQIC5...zE4*" }
}' \
"https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies/?_action=evaluateTree"
[
    {
        "resource":"http://www.example.com/",
        "actions":{
            "GET":true,
            "OPTIONS":true,
            "HEAD":true
        },
        "attributes":{

        },
        "advices":{

        }
    },
    {
        "resource":"http://www.example.com/",
        "actions":{
            "POST":false,
            "PATCH":false,
            "GET":true,
            "DELETE":true,
            "OPTIONS":true,
            "HEAD":true,
            "PUT":true
        },
        "attributes":{
            "myStaticAttr":[
                "myStaticValue"
            ]
        },
        "advices":{

        }
    },
    {
        "resource":"http://www.example.com/?*",
        "actions":{
            "POST":false,
            "PATCH":false,
            "GET":false,
            "DELETE":false,
            "OPTIONS":true,
            "HEAD":false,
            "PUT":false
        },
        "attributes":{

        },
        "advices":{
            "AuthLevelConditionAdvice":[
                "3"
            ]
        }
    }
]

PingOne Advanced Identity Cloud returns decisions not only for the specified resource, but also for matching resource names in the tree whose root is the specified resource.

In the JSON list of decisions returned for each resource, PingOne Advanced Identity Cloud includes these fields:

resource

A resource name whose root is the resource specified in the request.

The decisions returned are not guaranteed to be in the same order as the resources were requested.

actions

A map of action name keys to Boolean values that indicate whether the action is allowed (true) or denied (false) for the specified resource.

In the example, for matching resources with a query string only HTTP OPTIONS is allowed according to the policies configured.

attributes

A map of attribute names to their values if any response attributes are returned according to applicable policies.

In the example, the policy that applies to http://www.example.com:80/* causes a static attribute to be returned.

advices

A map of advice names to their values if any advice is returned according to applicable policies.

The advices field can provide hints regarding what PingOne Advanced Identity Cloud needs to take the authorization decision.

In the example, the policy that applies to resources with a query string requests that the subject authenticates at an authentication level of at least 3.

Notice that with the advices field present, no advices appear in the JSON response.

{
    "advices": {
        "AuthLevelConditionAdvice": [ "3" ]
    }
}

You can use the query string parameters _prettyPrint=true to make the output easier to read, and _fields=field-name[,field-name...] to limit the fields returned in the output.