PingOne Advanced Identity Cloud

Migrate access token modification scripts to next-generation scripts

Different bindings are available to an access token modification script depending on the scripting engine version, legacy or next-generation.

To migrate legacy scripts to next-generation scripts:

  1. Complete the steps to migrate common bindings, such as httpclient and logger, as described in Migrate to next-generation scripts.

    Review common bindings only available to next-generation scripts, such as openidm and policy. Consider using them to simplify and improve your scripts.

  2. Update the access token modification script bindings that have changed by referring to the information in the following table.

    Binding Next-generation change

    accessToken

    The get/setScope methods now accept/return a List instead of a Set.

    The List format makes it easier to retrieve values because you can access values directly without converting the return objects.

    The addExtraData, addExtraJsonData, and setPermissions methods now accept/return an Object that is converted to the relevant type, instead of a JsonValue.

    identity

    Attribute values are now returned as a List so that you can access values directly.

    You must now explicitly call store() to persist changes to attribute values.

    scopes

    Access the scopes as a List instead of a Set.

accessToken

Legacy Next-generation 
import org.forgerock.json.JsonValue;

accessToken.addExtraData('myKey', { → 'value' }) 1
JsonValue myJsonValue = JsonValue.json('value')  2
accessToken.addExtraJsonData('myJsonKey', { → myJsonValue })
JsonValue myListJsonValue = JsonValue.json(JsonValue.array('listValue'))
accessToken.addExtraJsonData('myListJsonKey', { → myListJsonValue })
JsonValue myMapJsonValue = JsonValue.json(JsonValue.object(JsonValue.field('mapKey', 'mapValue')))
accessToken.addExtraJsonData('myMapJsonKey', { → myMapJsonValue })
accessToken.setPermissions(JsonValue.json('permissions'))

accessToken.setField('scope',
                      accessToken.getScope()
                      .collect().join(' '))      3
 
accessToken.addExtraData('myKey', 'value')        1
accessToken.addExtraJsonData('myJsonKey','value') 2
accessToken.addExtraJsonData('myListJsonKey', ['listValue'])
accessToken.addExtraJsonData('myMapJsonKey', {'mapKey': 'mapValue'})
accessToken.setPermissions('permissions')

accessToken.setField('scope',
                      Array.from( accessToken.getScope())
                      .join(' '));                3

1 Add values directly to the addExtraData method.
2 Methods that accept/return JsonValues now use Object. The JavaScript engine converts the objects automatically to the appropriate type.
3 Methods that accept/return Sets now return Lists. You can access values more easily with the [] notation.

Learn more about the accessToken binding in Modify the access token.

identity

Use the identity binding to get data about the subject of the authorization request.

The following actions are available to the identity binding:

  • Get attribute values

  • Set attribute values

  • Add attribute values

Legacy Next-generation 
 // Returns all values as a set,
 // for example: [test@example.com,user@example.com]
identity.getAttribute("mail").toString();   1

 // Returns the first value
 // for example: test@example.com
identity.getAttribute("mail")
    .iterator().next();                     2

 // persists data
identity.setAttribute("mail",
    ["new@example.com"]);                   3

identity.addAttribute("mail", "user@example.com");
 
 // Returns all values as an array,
 // for example: ["test@example.com", "user@example.com"]
identity.getAttributeValues("mail");        1

 // Returns the first value, for example: test@example.com
identity.getAttributeValues("mail")[0];     2

 // Does NOT automatically persist data
identity.setAttribute("mail",
    ["new@example.com"]);                   3

 // Does NOT automatically persist data
identity.addAttribute("mail", "user@example.com");

 // persists data (throws an exception if add/setAttribute failed)
try {
    identity.store();                       4
} catch(e) {
    logger.error("Unable to persist attribute. " + e);
}

1 The identity object is now a ScriptedIdentityScriptWrapper, which returns a List instead of a Set.
2 No need to convert objects by calling toArray()[1] or iterator().next(). Instead, you can access values directly, for example, identity.getAttributeValues("KEY")[0].
3 Adding or setting attributes on the identity object does not persist data.
4 You must explicitly persist changes by calling the store method.

Learn more about the identity binding in Access profile data.