How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I add a roles claim to the OIDC Claims Script in AM (All versions)?

Last updated Apr 13, 2021

The purpose of this article is to provide information on adding a roles claim to the OIDC Claims Script in AM in order to return group membership details.

1 reader recommends this article


This article demonstrates how to add a roles claim to the OIDC Claims script.

See How do I add custom claims to the OIDC Claims Script in AM (All versions)? for further information on obtaining the JWT ID token with the claims included.

Adding a roles claim

The following process describes how to add a roles claim to the OIDC Claims Script in order to return group membership details:

  1. Create a custom OIDC Claims Script by navigating to Realms > [Realm Name] > Scripts and clicking New Script. Enter a name for your script and select OIDC Claims as the script type.
  2. Specify the script details:
    1. Declare the com.sun.identity.idm.IdType class in the import section at the top of the script: import com.iplanet.sso.SSOException import com.sun.identity.idm.IdRepoException import org.forgerock.oauth2.core.exceptions.InvalidRequestException import org.forgerock.oauth2.core.UserInfoClaims import org.forgerock.openidconnect.Claim import com.sun.identity.idm.IdType
    2. Add mapping details for the roles claim to the claimAttributes section. You can reformat the claims value as required. For example (where the resulting group returned will be prefixed with ROLE_): // [ {claim}: {attribute retriever}, ... ] claimAttributes = [        "email": userProfileClaimResolver.curry("mail"),         ...         "name": userProfileClaimResolver.curry("cn"),         "roles": { claim, identity -> [ "roles" : identity.getMemberships(IdType.GROUP).collect { group -> 'ROLE_' + }]}  ]
    3. Add the roles claim to the profile scope in the scopeClaimsMap section. For example: // {scope}: [ {claim}, ... ] scopeClaimsMap = [        "email": [ "email" ],         "address": [ "address" ],         "phone": [ "phone_number" ],         "profile": [ "given_name", "zoneinfo", "family_name", "locale", "name", "roles" ] ]
    4. Update any other script details as needed.
  3. Navigate to: Configure > Global Services > Scripting > Secondary Configurations > [Script Type] > Secondary Configurations > EngineConfiguration and add the com.sun.identity.idm.IdType class to the Java class whitelist field.
  4. Navigate to Realms > [Realm Name] > Services > OAuth2 Provider > OpenID Connect > OIDC Claims Script and select the OIDC claims script you created in step 1.
  5. Update the OAuth2Provider to process claims per your business requirements by navigating to Realms > [Realm Name] > Services > OAuth2 Provider. Settings you might want to change include:
    • OpenID Connect tab:
      • Update the Supported Claims field to include the roles claim (needed if you want to include claims when requesting an access token). For example, roles|en|Group membership will display the group membership details on the consent page as Group membership.
    • Advanced OpenID Connect tab - enable the following options:
      • Always Return Claims in ID Tokens (needed if you want claims returned in the ID token).
      • Enable "claims_parameter_supported" (needed if you want to include claims when requesting an access token).
  6. Restart the web application container in which AM runs to complete this configuration.

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

What JWTs are generated or accepted in Identity Cloud and AM?

Creating OAuth2 Provider in AM 5.5.x, 6.x and 7.x fails with a Could not initialise script configurations for realm error when using ssoadm

How do I modify the OIDC issuer ID or audience in a multi-server AM (All versions) environment?

FAQ: OAuth 2.0 in Identity Cloud and AM

OAuth 2.0 and OIDC in AM

OpenID Connect 1.0 Guide

Getting Started with Scripting

Related Training


Related Issue Tracker IDs

OPENAM-11445 (Request to Customize OAuth2 Access Token Content)

OPENAM-10584 (Supported claims and scopes in OAuth2|OpenID provider are not hot swappable )

OPENAM-7878 (Add functionality to modify the sub at the module level to override the clientID setting)

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