--- title: Policy condition script API description: In addition to the common bindings, a policy condition script has access to the following specific bindings, predefined objects that Advanced Identity Cloud injects into the script execution context. component: pingoneaic page_id: pingoneaic:am-scripting:policy-condition-scripting-api canonical_url: https://docs.pingidentity.com/pingoneaic/am-scripting/policy-condition-scripting-api.html keywords: ["Authorization", "Policy", "Administration", "Scripting", "Evaluation"] section_ids: policy-condition-script-environment: Access environment data policy-condition-script-profile: Access profile data scripting-api-authz-session: Access session data scripting-api-authz-response: Set authorization responses --- # Policy condition script API In addition to the [common bindings](script-bindings.html), a policy condition script has access to the following specific *bindings*, predefined objects that Advanced Identity Cloud injects into the script execution context. Use these objects in a script to get information such as the authorization state of a request, session properties, and user profile data. You can find an example of how to configure and test a policy condition script in [Scripted policy conditions](../am-authorization/scripted-policy-condition.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | The policy condition script is available as a [next-generation script](next-generation-scripts.html), which has access to all the next-generation common bindings. You can find information about converting existing scripts in [Migrate policy condition scripts to next-generation scripts](policy-condition-migrate.html). | | Binding | Description | Further information | | -------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | `advice` | Return the condition advice from the script. | [Set authorization responses](#scripting-api-authz-response) | | `authorized` | Return `true` if the authorization is currently successful, or `false` if authorization has failed. | Server-side scripts must set a value for `authorized` before completing. | | `environment` | A map of environment values passed from the client making the authorization request. | [Access environment data](#policy-condition-script-environment) | | `identity` | Access the data stored in the user's profile. | [Access profile data](#policy-condition-script-profile) | | `resourceURI` | The URI of the requested resource. | [Set authorization responses](#scripting-api-authz-response) | | `responseAttributes` | Add an attribute to the response to the authorization request. | [Set authorization responses](#scripting-api-authz-response) | | `scriptName` | Return the name of the running script. | [Output script name](script-bindings.html#common-scriptName). | | `session` | Access the properties for the current session. | [Access session data](#scripting-api-authz-session) | | `ttl` | The time-to-live value for the response to a successful authorization. | [Set authorization responses](#scripting-api-authz-response) | | `username` | String identifying the user ID of the subject requesting authorization. | - | ## Access environment data The `environment` binding holds data from the client making the authorization request. Depending on the type of script, the data is formatted as a map containing either the `IP` or `clientId` property, for example: * Policy condition script * OAuth 2.0 scopes policy script ```none "environment": { "IP": [ "127.0.0.1" ] } ``` ```none "environment": { "clientId": [ "MyOAuth2Client" ] } ``` | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For information about scripting OAuth 2.0 policy conditions, refer to [Scripted OAuth 2.0 scopes policy conditions](../am-authorization/scripted-policy-condition.html#scripting-api-oauth2-policy). | The following example shows how to access the environment data in a policy condition script: * Next-generation * Legacy ```javascript var ipList = environment.get("IP"); if (ipList == null || ipList.length == 0) { logger.warn("Missing IP"); authorized = false; } else{ logger.info("IP: " + ipList[0]); authorized = true; } ``` ```javascript var ipSet = environment.get("IP"); if (ipSet == null || ipSet.size == 0) { logger.warning("Missing IP"); authorized = false; } else { logger.message("IP: " + ipSet.iterator().next()); authorized = true; } ``` ## Access profile data Server-side authorization scripts can access the profile data of the subject of the authorization request through the methods of the `identity` object. | | | | - | ------------------------------------------------------------------------------------------------- | | | To access a subject's profile data, they must be logged in and their SSO token must be available. | * Get attribute values Return the values of the named attribute for the subject of the authorization request. * Next-generation * Legacy ```javascript // Returns all values as an array, for example: ["test@example.com", "user@example.com"] identity.getAttributeValues("mail"); // Returns the first value, for example: test@example.com identity.getAttributeValues("mail")[0]; ``` ```javascript // Returns all values as a set, for example: [test@example.com, user@example.com] identity.getAttribute("mail").toString(); // Returns the first value, for example: test@example.com identity.getAttribute("mail").iterator().next(); ``` * Set attribute values Set the named attribute to the values specified by the attribute value for the subject of the authorization request. * Next-generation * Legacy ```javascript identity.setAttribute("attrName", ["newValue"]); // Explicitly persist data identity.store(); ``` | | | | - | -------------------------------------------------------------------------- | | | You must explicitly call `store()` to persist changes to attribute values. | ```javascript identity.setAttribute("attrName", ["newValue"]); ``` * Add attribute values Add an attribute value to the list of attribute values associated with the attribute name for the subject of the authorization request. * Next-generation * Legacy ```javascript identity.addAttribute("attrName", ["newValue"]); // Explicitly persist data identity.store(); ``` | | | | - | -------------------------------------------------------------------------- | | | You must explicitly call `store()` to persist changes to attribute values. | ```javascript identity.addAttribute("attrName", ["newValue"]); ``` ## Access session data Server-side authorization scripts can access session data for the subject of the authorization request through the methods of the `session` object. | | | | - | -------------------------------------------------------------------------------------------------------- | | | To access the session data of the subject, they must be logged in and their SSO token must be available. | * `String session.getProperty(String propertyName)` Retrieve properties from the session associated with the subject of the authorization request. Refer to the following table for example properties and their values. > **Collapse: Session properties and example values** > > | Key | Sample value | > | ---------------------------- | ----------------------------------------------- | > | `AMCtxId` | `e370cca2-02d6-41f9-a244-2b107206bd2a-122934` | > | `amlbcookie` | `01` | > | `authInstant` | `2018-04-04T09:19:05Z` | > | `AuthLevel` | `0` | > | `CharSet` | `UTF-8` | > | `clientType` | `genericHTML` | > | `FullLoginURL` | `/am/XUI/?realm=alpha#login/` | > | `Host` | `198.51.100.1` | > | `HostName` | `am.example.com` | > | `Locale` | `en_US` | > | `Organization` | `dc=am,dc=example,dc=com` | > | `Principal` | `uid=amAdmin,ou=People,dc=am,dc=example,dc=com` | > | `Principals` | `amAdmin` | > | `Service` | `ldapService` | > | `successURL` | `/am/console` | > | `sun.am.UniversalIdentifier` | `uid=amAdmin,ou=People,dc=am,dc=example,dc=com` | > | `UserId` | `amAdmin` | > | `UserProfile` | `Required` | > | `UserToken` | `amAdmin` | > | `webhooks` | `myWebHook` | ## Set authorization responses Server-side authorization scripts can return information in the response to an authorization request with the following methods: * `void responseAttributes.put(String attributeName, Array attributeValue)` Add an attribute to the response to the authorization request. * `void advice.put(String adviceKey, Array adviceValues)` Add advice key-value pairs to the response to a failing authorization request. * `void ttl(Integer ttlValue)` Add a time-to-live value, which is a timestamp in milliseconds to the response to a successful authorization. After the time-to-live value the decision is no longer valid. If no value is set, `ttlValue` defaults to `Long.MAX_VALUE` (9223372036854775807), which means the decision has no timeout, and can live for as long as the calling client holds on to it. In the case of policy enforcement points, they hold onto the decision for their configured cache timeout.