How do I modify the OAuth2 Access Token Modification script in Identity Cloud, AM 6.5.2.x, 6.5.3 and 7.x?

Overview

This article demonstrates how to modify the Access Token Modification script and includes an example for including group membership details.

The high level steps for modifying the script are as follows:

1. Edit the script by navigating to Realms > [Realm Name] > Scripts and selecting the OAuth2 Access Token Modification Script.
2. Declare any required classes in the import section at the top of the script.
3. Update the script to include new fields for the value(s) you want to include.
4. Add any classes you declared in the import section to the Java class whitelist by navigating to: Configure > Global Services > Scripting > Secondary Configurations > OAUTH2_ACCESS_TOKEN_MODIFICATION > Secondary Configurations > EngineConfiguration and adding the Java class(es) to the Java class whitelist field.

The following section shows detailed steps for including group membership details and testing to check it has worked.

Modifying the script to include group membership details

The following process describes how to modify the Access Token Modification script in order to return group membership details:

1. Edit the script by navigating to Realms > [Realm Name] > Scripts and selecting the OAuth2 Access Token Modification Script.
2. Declare the com.sun.identity.idm.IdType class in the import section at the top of the script: import org.forgerock.http.protocol.Request import org.forgerock.http.protocol.Response import com.iplanet.sso.SSOException import groovy.json.JsonSlurper import com.sun.identity.idm.IdType
3. Update the script to include a new field to return group membership details. For example, this adds a groups field: accessToken.setField("groups", (identity.getMemberships(IdType.GROUP).collect { group -> group.name }))
4. Navigate to: Configure > Global Services > Scripting > Secondary Configurations > OAUTH2_ACCESS_TOKEN_MODIFICATION > Secondary Configurations > EngineConfiguration and add the com.sun.identity.idm.IdType class to the Java class whitelist field.
5. Ensure you have a test user set up who is added to one or more groups. For example, the demo user has been added to groupA and groupB for testing purposes.
6. Generate an access token for this user using the /oauth2/access_token endpoint. See OAuth 2.0 Guide › oauth2-access_token-endpoint for further information.
7. Introspect the token using the /oauth2/introspect endpoint. See OAuth 2.0 Guide › varlist-oauth2-introspect-endpoint for further information. In the response, you should see the following details included: "groups": ["groupA", "groupB"]

See Also

How do I create a script in AM (All versions) using Amster?

How do I add logging to server-side scripts in AM (All versions)?

OAuth 2.0 in AM

OAuth 2.0 Guide › Modifying the Content of Access Tokens

OAuth 2.0 Guide › Preparing AM to Modify Access Tokens

API Javadoc › Interface AccessToken

Getting Started with Scripting

Related Training

N/A

Related Issue Tracker IDs

N/A