--- 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: 8.1 page_id: pingam:am-authorization:rest-api-authz-policy-decisions canonical_url: https://docs.pingidentity.com/pingam/8.1/am-authorization/rest-api-authz-policy-decisions.html keywords: ["Authorization", "Policy", "REST API", "Evaluation"] page_aliases: ["authorization-guide:rest-api-authz-policy-decisions.adoc"] section_ids: rest-api-authz-policy-decision-concrete: Request policy decisions for a specific resource example_request: Example request rest-api-authz-policy-decision-subtree: Request policy decisions for a tree of resources example_request_2: Example request 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 doesn't 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. Find more information about the AM session token and its use in REST API calls in [Session token after authentication](../am-authentication/rest-using-ssotokens.html). Learn more about requesting decisions for specific resources in [Request policy decisions for a specific resource](#rest-api-authz-policy-decision-concrete). Learn more about requesting decisions for a resource and all resources beneath it in [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. Learn more in [Policy sets over REST](rest-api-authz-applications.html). * `subject` (Optional). Holds an object that represents the subject. If you don't 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, which is returned, for example, on successful authentication as described in [Authenticate over REST](../am-authentication/authn-rest.html). If the client the token's been issued for is authorized to use ID tokens as session tokens, you can use an OIDC token instead. Learn more in [ID tokens as session cookies](../am-oidc1/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 doesn't attempt to validate the JWT signature or the claims in the JWT. It's assumed you've already validated the JWT before calling the authorization endpoint.For AM-issued ID Tokens, you can 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 validates the token. Learn more in [ID tokens as policy subjects](../am-oidc1/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. ### Example request 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://am.example.com:8443/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":[ "bjensen" ] }, "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 aren't 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/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/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/do?action=run` requests the subject to be authenticated at an authentication level of at least 3. ```json { "advices": { "AuthLevelConditionAdvice": [ "3" ] } } ``` Learn more in [Policy decision advice](#rest-api-authz-policy-decision-advice). 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. Learn more in [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](../am-authentication/authn-rest.html). * `jwt` The value is a JWT string. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you pass the subject details as a JWT, AM doesn't attempt to validate the JWT signature or the claims in the JWT. It's assumed you've already validated the JWT before calling the authorization endpoint.For AM-issued ID Tokens, you can 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 validates the token. Learn more in [ID tokens as policy subjects](../am-oidc1/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 don't specify the environment, the default is an empty map. ### Example request 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://am.example.com:8443/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" ] } } ] ``` | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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 aren't 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/*` 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 the subject to 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). The following examples show different types of policy decision advice and the conditions that cause AM to return the advice. * AuthLevel and LEAuthLevel condition failures `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" ] } ``` * AuthenticateToRealm condition failure 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" ] } ``` * AuthenticateToService condition failure An `AuthenticateToService` condition failure can result in an advice showing the name of the required authentication tree. For example, failure against the following condition: ```json { "type": "AuthenticateToService", "authenticateToService": "Login" } ``` Leads to this advice: ```json { "AuthenticateToServiceConditionAdvice": [ "Login" ] } ``` * ResourceEnvIP condition failure 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=Login" ] } ``` Leads to this advice: ```json { "AuthenticateToServiceConditionAdvice": [ "Login" ] } ``` * Session condition failure A `Session` condition failure can result in an advice showing that access was denied because the authenticated 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: ```json { "type": "Session", "maxSessionTime": "10", "terminateSession": true } ``` Leads to this advice: ```json { "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 doesn't 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.