How To

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

Last updated Nov 19, 2019

The purpose of this article is to provide information on adding a session property claim to the OIDC Claims Script in AM/OpenAM in order to output SSO session details in the JWT ID token.


Overview

The OIDC id_token is specifically designed for identity use cases and you can easily modify the OIDC claims script to integrate SSO session properties into the id_token JWT.

The processes in this article use the AuthLevel session property, but the same steps apply to all session properties, including custom and protected ones.

This article demonstrates how to add a session property claim to the OIDC Claims script depending on version:

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

Adding a session property claim (AM 5 and later)

The following process describes how to add a session property claim to the OIDC Claims Script in order to return SSO session details:

  1. Navigate to: Realms > [Realm Name] > Services > Session Property Whitelist Service and add the session property to the Whitelisted Session Property Names field.
  2. 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.
  3. 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 session property claim to the claimAttributes section. You can reformat the claims value as required. For example:
      // [ {claim}: {attribute retriever}, ... ]
      claimAttributes = [
              "email": userProfileClaimResolver.curry("mail"),
              ...
              "name": userProfileClaimResolver.curry("cn"),
              "AuthLevel": { claim, identity -> [ (claim.getName()): session.getProperty("AuthLevel") ] }
      ]
      
    3. Add the session property 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", "AuthLevel" ]
      ]
      
    4. Update any other script details as needed.
  4. 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.
  5. Navigate to Realms > [Realm Name] > Services > OAuth2 Provider > OpenID Connect > OIDC Claims Script and select the OIDC claims script you created in step 1.
  6. 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 session property claim (needed if you want to include claims when requesting an access token). For example, AuthLevel|en|Authentication Level will display AuthLevel on the consent page as Authentication Level.
    • 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).
  7. Restart the web application container in which AM runs to complete this configuration.

Adding a session property claim (OpenAM 13.5.x)

The following process describes how to add a session property claim to the OIDC Claims Script in order to return SSO session details:

  1. Navigate to: Realms > [Realm Name] > Services > Session Property Whitelist Service and add the session property to the Whitelisted Session Property Names field.
  2. 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.
  3. 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 session property claim to the claimAttributes section. You can reformat the claims value as required. For example:
      // [ {claim}: {attribute retriever}, ... ]
      claimAttributes = [
              "email": attributeRetriever.curry("mail"),
              ...
              "name": attributeRetriever.curry("cn"),
              "AuthLevel": { claim, identity, requested -> [ (claim.getName()): session.getProperty("AuthLevel") ] }
      ]
      
    3. Add the session property 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", "AuthLevel" ]
      ]
      
    4. Update any other script details as needed.
  4. 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.
  5. Navigate to Realms > [Realm Name] > Services > OAuth2 Provider > OIDC Claims Script and select the OIDC claims script you created in step 1.
  6. 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 session property claim (needed if you want to include claims when requesting an access token). For example, AuthLevel|en|Authentication Level will display AuthLevel on the consent page as Authentication Level.
    • 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).
  7. Restart the web application container in which OpenAM runs to complete this configuration.

See Also

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

How do I automate the creation of scripts in AM/OpenAM (All versions)?

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

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 © 2019 ForgeRock, all rights reserved.

Recommended Books

Loading...