PingOne Advanced Identity Cloud

Policy condition script API

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.

Binding Description Further information

advice

Return the condition advice from the script.

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

The environment values passed from the client making the authorization request.

httpClient

Make outbound HTTP calls.

identity

Access the data stored in the user’s profile.

logger

Write a message to the PingOne Advanced Identity Cloud debug log.

resourceAttributes

Add an attribute to the response to the authorization request.

scriptName

Return the name of the running script.

session

Access the properties for the current session.

ttl

The time-to-live value for the response to a successful authorization.

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 as a Map of <String, Set<String>.

For example, the following shows a simple environment map with a single entry:

  • 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.

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.

Set identity.getAttribute(String attributeName)

Return the values of the named attribute for the subject of the authorization request.

For example:

var attribute = identity.getAttribute("attrName").iterator().next();
void identity.setAttribute(String attributeName, Array attributeValues)

Set the named attribute to the values specified by the attribute value for the subject of the authorization request.

For example:

identity.setAttribute("attrName", ["newValue"]);

// Explicitly persist data
identity.store();
void identity.addAttribute(String attributeName, String attributeValue)

Add an attribute value to the list of attribute values associated with the attribute name for the subject of the authorization request.

For example:

identity.addAttribute("attrName", ["newValue"]);

// Explicitly persist data
identity.store();

You must call identity.store() to persist changes or they will be lost when the script completes.

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

AMCtxId

e370cca2-02d6-41f9-a244-2b107206bd2a-122934

amlbcookie

01

authInstant

2018-04-04T09:19:05Z

AuthLevel

0

CharSet

UTF-8

clientType

genericHTML

FullLoginURL

/openam/XUI/?realm=alpha#login/

Host

198.51.100.1

HostName

openam.example.com

Locale

en_US

Organization

dc=openam,dc=forgerock,dc=org

Principal

uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org

Principals

amAdmin

Service

ldapService

successURL

/openam/console

sun.am.UniversalIdentifier

uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org

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.