PingAM 7.5.0

Request policy decisions over REST

You can request policy decisions from AM over REST. AM evaluates requests based on the context and the configured policies, and returns decisions that indicate what actions are allowed or denied, as well as any attributes or advices for the specified resources.

This section does not apply to OAuth 2.0 policies.

Request policy evaluation at the /json/realms/root/realms/Realm Name/policies endpoint.

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, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

Before making a REST API call to manage a policy, you must have:

  • Authenticated successfully to AM as a user with sufficient privileges to make the REST API call.

  • Obtained the session token returned after successful authentication.

When making the REST API call, pass the session token in the HTTP header. For more information about the AM session token and its use in REST API calls, refer to Session token after authentication.

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

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

Request policy decisions for a specific resource

To request policy decisions for specific resources, send a POST request to the policies endpoint, with the evaluate action. For example:

/json/realms/root/realms/Realm Name/policies?_action=evaluate.

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, starting at the Top Level Realm. Prefix each realm in the hierarchy with the realms/ keyword. For example, /realms/root/realms/customers/realms/europe.

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": "defaults to iPlanetAMWebAgentService if not specified",
    "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 input fields are as follows:

resources

(Required) Specifies the list of resources for which to return decisions.

For example, when using the default policy set, "iPlanetAMWebAgentService", you can request decisions for resource URLs.

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

The name of the policy set. Defaults to "iPlanetAMWebAgentService", if not specified.

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

subject

(Optional). Holds an object that represents the subject. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.

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 over REST.

You can use an OpenID Connect ID token if the client that the token has been issued for is authorized to use ID tokens as session tokens. For details, refer to Using ID Tokens as Session Tokens.

jwt

The value is a JWT string.

If you pass the subject details as a JWT, AM does not attempt to validate the JWT signature or the claims in the JWT. It is assumed that you have already validated the JWT before calling the authorization endpoint.

For AM-issued ID Tokens, you can, instead, pass the ID Token as the value of the ssoToken field (after adding your client to the Authorized SSO Clients list). In this case, AM will validate the token. For more information, refer to ID tokens as subjects in policy evaluation.
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

(Optional). Holds a map of keys to lists of values.

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

The following example requests policy decisions for two URL resources. The iPlanetDirectoryPro 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 "iPlanetDirectoryPro: AQIC5…​" \
--data '{
    "resources":[
        "http://www.example.com/index.html",
        "http://www.example.com/do?action=run"
    ],
    "application":"iPlanetAMWebAgentService"
}' \
"https://openam.example.com:8443/openam/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, AM includes these fields.

resource

The resource specified in the request.

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

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 about what AM requires to make an 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.

Request policy decisions for a tree of resources

To request policy decisions for a resource, and all other resources in the subtree, send a POST request to the policies endpoint, with the evaluateTree action. For example:

/json/realms/root/realms/Realm Name/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": "defaults to iPlanetAMWebAgentService if not specified",
    "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

(Required) Specifies the root resource for the decisions to return.

For example, when using the default policy set, "iPlanetAMWebAgentService", you can request decisions for resource URLs.

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

The name of the policy set. Defaults to "iPlanetAMWebAgentService" if not specified.

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

subject

(Optional) 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 that correspond to any type in the request.

ssoToken

The SSO token ID string for the subject, returned on successful authentication, as described in Authenticate over REST.

jwt

The value is a JWT string.

If you pass the subject details as a JWT, AM does not attempt to validate the JWT signature or the claims in the JWT. It is assumed that you have already validated the JWT before calling the authorization endpoint.

For AM-issued ID Tokens, you can, instead, pass the ID Token as the value of the ssoToken field (after adding your client to the Authorized SSO Clients list). In this case, AM will validate the token. For more information, refer to Using ID Tokens as Subjects in Policy Decisions.
claims

An object (map) of JWT claims to their values. If you do not specify the subject, AM uses the SSO token ID of the subject making the request.

environment

(Optional) A map of keys to lists of values.

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

The following example requests policy decisions for http://www.example.com/. The iPlanetDirectoryPro header sets the SSO token for a user who has access to perform the operation. The subject takes the SSO token of the user who wants to access a resource.

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iPlanetDirectoryPro: AQIC5…​NDU1*" \
--header "Accept-API-Version: resource=1.0" \
--data '{
    "resource": "http://www.example.com/",
    "subject": { "ssoToken": "AQIC5…​zE4*" }
}' \
"https://openam.example.com:8443/openam/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"
            ]
        }
    }
]

AM 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, AM 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 AM needs, to make the authorization decision.

In the example, the policy that applies to resources with a query string requests that the subject be authenticated 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.

Policy decision advice

When AM 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.

This section shows examples of the different types of policy decision advice and the conditions that cause AM to return the advice.

"AuthLevel" and "LEAuthLevel" condition failures can result in an 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 AuthScheme condition failure can result in an advice showing one or more required authentication modules. For example, failure against the following condition:

{
    "type": "AuthScheme",
    "authScheme": [
        "HOTP"
    ],
    "applicationName": "iPlanetAMWebAgentService",
    "applicationIdleTimeout": 10
}

Leads to this advice:

{
    "AuthSchemeConditionAdvice": [
        "HOTP"
    ]
}

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

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

Leads to this advice:

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

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

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

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A ResourceEnvIP condition failure can result in an 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=MyAuthnChain"
    ]
}

Leads to this advice:

{
    "AuthenticateToServiceConditionAdvice": [
        "MyAuthnChain"
    ]
}

A Session condition failure can result in an advice showing that access was denied because the user’s session was active longer than allowed by the condition.

If terminateSession is true and policy evaluation is requested, AM sends the session advice to the Java, Web, or PingGateway agent when the maxSessionTime elapses.

For example, failure against the following condition:

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

Leads to this advice:

{
    "SessionConditionAdvice": [
        "deny"
    ]
}

When AM receives the terminate advice, the user is redirected to the login page to reauthenticate.

If terminateSession is false and policy evaluation is requested, AM doesn’t send the session advice to the Java, Web, or PingGateway agent when the maxSessionTime elapses. Instead of being redirected to the login page, the user receives a 403 Forbidden response for the protected resource.

When policy evaluation denials occur against the following conditions, AM does not return any advice:

  • IPv4

  • IPv6

  • LDAPFilter

  • OAuth2Scope

  • SessionProperty

  • SimpleTime

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