How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jun 21, 2021

The purpose of this article is to provide information on modifying the OAuth2 Access Token Modification script in AM. This article also includes an example for including group membership details for the user.


2 readers recommend this article

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.

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

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 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

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


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.