PingOne Advanced Identity Cloud

Access token modification scripting API

In addition to the common bindings, an access token modification script has access to the following specific bindings.

Use these objects in a script to set or remove values from the access token.

You can find an example of how to configure and test an access token modification script in Access tokens.

The access token modification script is available as a next-generation script, which has access to all the next-generation common bindings.

Find information about converting existing scripts in Migrate access token modification scripts to next-generation scripts.
Binding Information Further information

accessToken

The OAuth 2.0 access token.

Modify the access token

clientProperties

A map of properties configured in the client profile. Only present if the client was correctly identified.

Access client properties

identity

Represents an identity that Advanced Identity Cloud can access.

Access profile data

requestProperties

A map of the properties present in the request.

Access request properties

scopes

An array of the requested scopes. For example:

["read", "transfer", "download"].

session

Access the user’s SSO session object if the request contains a session cookie.

The session isn’t available for resource owner password credentials grants.

You can use the session binding to retrieve properties from the session, for example:

String session.getProperty(String propertyName)

SSOToken

Modify the access token

Use the accessToken binding to manipulate the content and fields of the token with methods such as addExtraJsonData, setField, and setExpiryTime.

You can find all the available methods listed in the AccessToken Javadoc.

Set values

The following example shows how to set different values in the access token:

  • Next-generation

  • Legacy

// add values to the token using available bindings
accessToken.setField('foo', 'bar');
var customProperties = clientProperties.get('customProperties');
accessToken.setField('customClientProperty', customProperties.get('testCustomProp'));
accessToken.setField('oauth2ClientId', clientProperties.get('clientId'));
accessToken.setField('requestUri', requestProperties.get('requestUri'));
// set UMA permissions
accessToken.setPermissions('permissions');
// set a new expiry time in milliseconds
accessToken.setExpiryTime(1755242153837);
// add values to the token using available bindings
accessToken.setField('foo', 'bar');
var customProperties = clientProperties.get('customProperties');
accessToken.setField('customClientProperty', customProperties.get('testCustomProp'));
accessToken.setField('oauth2ClientId', clientProperties.get('clientId'));
accessToken.setField('requestUri', requestProperties.get('requestUri'));
// set UMA permissions
accessToken.setPermissions(JsonValue.json('permissions'));
// set a new expiry time in milliseconds
accessToken.setExpiryTime(1755242153837);

Add JSON to the response

The following example shows how to add extra data to the JSON response:

  • Next-generation

  • Legacy

// add value
accessToken.addExtraData('myKey', 'value');
// add JSON value
accessToken.addExtraJsonData('myJsonKey', 'value');
// add list
accessToken.addExtraJsonData('myListJsonKey', ['listValue']);
// add map
accessToken.addExtraJsonData('myMapJsonKey', {'mapKey': 'mapValue'});
import org.forgerock.json.JsonValue;
// add value
accessToken.addExtraData('myKey', { -> 'value' });
// add JSON value
JsonValue myJsonValue = JsonValue.json('value');
accessToken.addExtraJsonData('myJsonKey', { -> myJsonValue });
// add list
JsonValue myListJsonValue = JsonValue.json(JsonValue.array('listValue'));
accessToken.addExtraJsonData('myListJsonKey', { -> myListJsonValue });
// add map
JsonValue myMapJsonValue = JsonValue.json(JsonValue.object(JsonValue.field('mapKey', 'mapValue')));
accessToken.addExtraJsonData('myMapJsonKey', { -> myMapJsonValue });

Access client properties

The client properties map has the following keys:

allowedGrantTypes

An array of grant types.

allowedResponseTypes

An array of strings listing response types.

allowedScopes

An array of strings listing scopes.

clientId

The client’s URI for the request locale.

customProperties

A map of any custom properties added to the client.

These properties can include lists or maps as sub-maps. For example, the script includes customMap[Key1]=Value1 as customMap > Key1 > Value1 in the object.

Under Native Consoles > Access Management, add custom properties to a client. Go to OAuth 2.0 > Clients > Client ID > Advanced, and update the Custom Properties field.

Add custom properties as shown in these examples:

customproperty=custom-value1
customList[0]=customList-value-0
customMap[key1]=customMap-value-1

Scripts can then access the custom properties in the following way:

var customProperties = clientProperties.get("customProperties");
var property = customProperties.get("myProperty");

The map is null if Advanced Identity Cloud did not successfully identify the client.

Access request properties

The request properties map has the following keys:

requestUri

The URI as a string

realm

The realm as a string

requestParams

A map of request parameters and posted data, where each value is an array of parameters.

To mitigate the risk of reflection-type attacks, use OWASP best practices when handling these parameters. Find more information in Unsafe use of Reflection.
requestHeaders

The value of the named request header. Returns a map of <String, List<String>> as a native JavaScript object, for example:

var ipAddress = requestProperties.requestHeaders["X-Forwarded-For"][0]

Header names are case-sensitive.

Access profile data

These examples use the methods of the identity binding to get and set profile data.

  • 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];
// Create / replace attribute with the specified value
identity.setAttribute("attrName", ["newValue"]);
// Add attribute to the list
identity.addAttribute("attrName", ["newValue"]);
// Explicitly persist data when setting attributes
identity.store();
// 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();
// Create / replace attribute with the specified value
identity.setAttribute("attrName", ["newValue"]);
// Add attribute to the list
identity.addAttribute("attrName", ["newValue"]);

Learn more in AMIdentity.