PingAM

Migrate OAuth scripts to next-generation scripts

Different bindings are available to an OAuth 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 script bindings that have changed for your OAuth script type by referring to the API and information in the following table.

    Binding Used in API 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.

    requestedClaims

    Access the requested claims as a Map of List instead of Set objects.

    requestedTypedClaims

    No longer available. Use requestedClaims instead.

    scopes

    Access the scopes as a List instead of a Set.

    session

    The legacy session binding is an instance of SSOToken. Methods include getProperty, getTimeLeft, getMaxIdleTime, and getTokenID.

    The next-generation session binding is an instance of ScriptedSession.

    token

    A ExchangeableTokenScriptWrapper object.

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.

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.