How To

How do I add a roles claim to the OIDC Claims Script in AM (All versions) and OpenAM 13.x?

Last updated Nov 30, 2018

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


Overview

This article demonstrates how to add a roles claim to the OIDC Claims script; the script changes vary across versions:

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

Adding a roles claim (AM 5 and later)

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_' + group.name }]}  
      ]
      
    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.

Adding a roles claim (OpenAM 13.x)

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.UserInfoClaims
      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": attributeRetriever.curry("mail"),
              ...
              "name": attributeRetriever.curry("cn"),
              "roles": { claim, identity, requested ->  identity.getMemberships(IdType.GROUP).collect { group -> 'ROLE_' + group.name } }
      ]
      
    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. Add the com.sun.identity.idm.IdType class to the Java class whitelist:
    • OpenAM 13.5 console: navigate to: Configure > Global Services > Scripting > Secondary Configuration Instance > [Script Type] > Secondary Configuration Instance > Engine Configuration and add the com.sun.identity.idm.IdType class to the Java class whitelist field.
    • OpenAM 13 console: navigate to: Configuration > Global > Scripting > Secondary Configuration Instance > [Script Type] > Secondary Configuration Instance > Engine Configuration and add the com.sun.identity.idm.IdType class to the Java class whitelist field.
  4. Navigate to Realms > [Realm Name] > Services > OAuth2 Provider > 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:
    • 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.
    • Enable the Always Return Claims in ID Tokens option (needed if you want claims returned in the ID token).
    • Enable the Enable "claims_parameter_supported" option (needed if you want to include claims when requesting an access token).
  6. Restart the web application container in which OpenAM runs to complete this configuration.

See Also

How do I automate the creation of scripts in AM (All versions) and OpenAM 13.x?

How do I add logging to server-side scripts in AM (All versions) and OpenAM 13.x?

How do I understand the JWTs used in OIDC that are generated or accepted by AM/OpenAM (All versions)?

Creating OAuth2 Provider in AM 5.5.x and 6 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 AM/OpenAM

OAuth 2.0 in AM/OpenAM

OpenID Connect 1.0 Guide

Development Guide › Developing with Scripts

Related Training

N/A

Related Issue Tracker IDs

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

OPENAM-10585 (The "claims" Request Parameter from the openid standard isn't functional)

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

OPENAM-8440 (Pluggable OAuth2 Access Token Format)

OPENAM-8270 (Using client_credentials Grant type with openid scope returns User must be authenticated to issue ID tokens.)

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



Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.
Loading...