Policy condition script API
In addition to the common bindings, a policy condition script has access to the following specific bindings, predefined objects that PingOne 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.
|
PingOne Advanced Identity Cloud has introduced a next-generation scripting engine that offers several benefits, including enhanced script bindings. The availability and usage of bindings depend on the script engine version of the script: legacy or next-generation. Both versions are described in this section. You can find information about migrating to the enhanced scripting engine in Migrate to next-generation scripts. |
| Binding | Description | Further information |
|---|---|---|
|
Return the condition advice from the script. |
|
|
Return |
Server-side scripts must set a value for |
|
A map of environment values passed from the client making the authorization request. |
|
|
Access the data stored in the user’s profile. |
|
|
The URI of the requested resource. |
|
|
Add an attribute to the response to the authorization request. |
|
|
Return the name of the running script. |
|
|
Access the properties for the current session. |
|
|
The time-to-live value for the response to a successful authorization. |
|
|
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
"environment": {
"IP": [
"127.0.0.1"
]
}"environment": {
"clientId": [
"MyOAuth2Client"
]
}|
For information about scripting OAuth 2.0 policy conditions, refer to Scripted OAuth 2.0 scopes policy conditions. |
The following example shows how to access the environment data in a policy condition script:
-
Next-generation
-
Legacy
var ipList = environment.get("IP");
if (ipList == null || ipList.length == 0) {
logger.warn("Missing IP");
action.goTo("false");
}
else{
logger.info("IP: " + ipList[0]);
action.goTo("true");
}var fr = JavaImporter(org.forgerock.openam.auth.node.api.Action);
var ipSet = environment.get("IP");
if (ipSet == null || ipSet.size == 0) {
logger.warning("Missing IP");
action = fr.Action.goTo("false").build();
}
else {
logger.message("IP: " + ipSet.iterator().next());
action = fr.Action.goTo("true").build();
}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
// 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];// 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
identity.setAttribute("attrName", ["newValue"]); // Explicitly persist data identity.store();You must explicitly call
store()to persist changes to attribute values.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
identity.addAttribute("attrName", ["newValue"]); // Explicitly persist data identity.store();You must explicitly call
store()to persist changes to attribute values.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.
Session properties and example values
| Key | Sample value |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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,
ttlValuedefaults toLong.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.