--- title: Request policy decisions over REST description: 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. component: pingam version: 7.2 page_id: pingam:authorization-guide:rest-api-authz-policy-decisions canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authorization/rest-api-authz-policy-decisions.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/pingam/8.1/am-authorization/rest-api-authz-policy-decisions.html section_ids: rest-api-authz-policy-decision-concrete: Request policy decisions for a specific resource rest-api-authz-policy-decision-subtree: Request policy decisions for a tree of resources rest-api-authz-policy-decision-advice: Policy decision advice --- # 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, see [Session token after authentication](../authentication-guide/rest-using-ssotokens.html). To request decisions for specific resources, see [Request policy decisions for a specific resource](#rest-api-authz-policy-decision-concrete). To request decisions for a resource and all resources beneath it, see [Request policy decisions for a tree of resources](#rest-api-authz-policy-decision-subtree). ## 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. ```json { "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. ```json { "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, see [Policy sets over REST](rest-api-authz-applications.html). * `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](../authentication-guide/authn-rest.html). 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 more information, see [Using ID Tokens as Session Tokens](../oidc1-guide/oidc-additional-use-cases.html#idtokens-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, see [ID tokens as subjects in policy evaluation](../oidc1-guide/oidc-additional-use-cases.html#idtokens-in-policy-decision). | * `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. ```bash $ 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. ```json { "advices": { "AuthLevelConditionAdvice": [ "3" ] } } ``` See [Policy decision advice](#rest-api-authz-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. ```json { "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. ```json { "resource": "http://www.example.com/" } ``` * `application` The name of the policy set. Defaults to `"iPlanetAMWebAgentService"` if not specified. For more on policy sets, see [Policy sets over REST](rest-api-authz-applications.html). * `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](../authentication-guide/authn-rest.html). * `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, see [Using ID Tokens as Subjects in Policy Decisions](../oidc1-guide/oidc-additional-use-cases.html#idtokens-in-policy-decision). | * `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. ```bash $ 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. ```json { "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. ```json { "advices": { "type": [ "advice" ] } } ``` The advices returned depend on [policy conditions](rest-api-authz-policies.html). 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: ```json { "type": "AuthLevel", "authLevel": 2 } ``` Leads to this advice: ```json { "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: ```json { "type": "AuthScheme", "authScheme": [ "HOTP" ], "applicationName": "iPlanetAMWebAgentService", "applicationIdleTimeout": 10 } ``` Leads to this advice: ```json { "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: ```json { "type": "AuthenticateToRealm", "authenticateToRealm": "MyRealm" } ``` Leads to this advice: ```json { "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: ```json { "type": "AuthenticateToService", "authenticateToService": "MyAuthnChain" } ``` Leads to this advice: ```json { "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: ```json { "type": "ResourceEnvIP", "resourceEnvIPConditionValue": [ "IF IP=[127.0.0.12] THEN authlevel=4" ] } ``` Leads to this advice: ```json { "AuthLevelConditionAdvice": [ "4" ] } ``` Failure against a different type of `ResourceEnvIP` condition such as the following: ```json { "type": "ResourceEnvIP", "resourceEnvIPConditionValue": [ "IF IP=[127.0.0.11] THEN service=MyAuthnChain" ] } ``` Leads to this advice: ```json { "AuthenticateToServiceConditionAdvice": [ "MyAuthnChain" ] } ``` A `Session` condition failure can result in an advice showing that access has been denied because the user's session has been active longer than allowed by the condition. The advice will also show if the user's session was terminated and reauthentication is required. For example, failure against the following condition: ```json { "type": "Session", "maxSessionTime": "10", "terminateSession": false } ``` Leads to this advice: ```json { "SessionConditionAdvice": [ "deny" ] } ``` 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.