How do I modify the OAuth2 Access Token Modification script in AM 6.5.2.x, 6.5.3, 6.5.4, 6.5.5 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 allowlist 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.

Scopes 

Scopes must be defined as an array (for example: scope: ["scope1", "scope2", "scope3"]). If you define them as a list of space-separated scopes, you will see the following error:Cannot cast java.lang.String to java.util.Set

You can modify the Access Token Modification script to reformat the scope claim as a space-separated string if required. See How do I change the format of the scope claim returned in an OAuth 2.0 Access token in Identity Cloud and AM (All versions)? for further information.

There is an RFE to change this: OPENAM-17240 (Access Token JWT - scope should be a space-separated list of scopes instead of an array).

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 /oauth2/access_token for further information.
7. Introspect the token using the /oauth2/introspect endpoint. See /oauth2/introspect for further information. In the response, you should see the following details included: "groups": ["groupA", "groupB"]

See Also

How do I change the format of the scope claim returned in an OAuth 2.0 Access token in Identity Cloud and AM (All versions)?

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

OAuth 2.0 and OIDC in AM

Access token modification plugin

Example access token modification plugin

Interface AccessToken

Scripting

Related Training

N/A

Related Issue Tracker IDs

OPENAM-17240 (Access Token JWT - scope should be a space-separated list of scopes instead of an array)