Identity Cloud

User info claims plugin

This plugin extension point is invoked when issuing an ID token or during a request to the /userinfo OpenID Connect endpoint. Use this script to retrieve claim values based on an issued access token.

To view a sample script, including the available script properties, see oidc-claims-extension.js.

Example user info claims plugin

Complete the following steps to implement an example user info claims script that adds a custom claim to the profile scope:

Prepare the user info claims script

This task describes how to create a script to map a custom claim.

  1. In the AM admin UI, go to Realms > Realm Name > Scripts, and click New Script.

  2. Enter a unique name for your script, select OIDC Claims from the Script Type drop-down list, and click Create.

  3. If necessary, copy the oidc-claims-extension.js script and paste in the Script field.

  4. In the Script field:

    • As a simple example, insert a new claim, myTestName, in the profile (around line 127):

      utils.setScopeClaimsMap({
              profile: [
                  'name',
                  'myTestName',
                  'family_name',
                  'given_name',
                  'zoneinfo',
                  'locale'
              ],
              email: ['email'],
              address: ['address'],
              phone: ['phone_number']
          });
    • Add a value for myTestName around line 199, as follows:

      utils.setClaimResolvers({
      
         name: utils.getUserProfileClaimResolver('cn'),
         myTestName: utils.getUserProfileClaimResolver('cn'),
         family_name: utils.getUserProfileClaimResolver('sn'),
         ...
      });

    You can also use the script to override the claims included in an ID token. For example, you can add a post_logout_url claim that redirects a user’s browser to the URL specified in the claim, when that user signs out of the hosted end user UI. For details, see Can I configure the hosted end user UI to redirect users to a specific URL after they sign out? in the Knowledge Base.

  5. Save your changes.

The default user info claims script is now amended to retrieve a custom claim for the profile scope.

Configure AM to use the user info claims script

Perform this task to set up an OAuth2 provider to use your custom script.

  1. Log in to the AM admin UI as an administrator.

  2. Configure the provider to ensure the following properties are set:

    • OIDC Claims Plugin Type to SCRIPTED.

    • OIDC Claims Script to the name of the script you created.

  3. Save your changes.

Create an OAuth2 client for authorization

Create a public OAuth 2.0 client to use in the authorization request.

  1. In the AM admin UI, go to Realms > Realm Name > Applications > OAuth 2.0 > Clients, and click Add Client.

  2. Enter the following values:

    • Client ID: myClient

    • Client secret: forgerock

    • Redirection URIs: https://www.example.com:443/callback

    • Scope(s): openid profile

  3. Click Create.

  4. In the Core tab, set Client type to Public.

  5. In the Advanced tab, set the following values:

    • Grant Types: Implicit

    • Token Endpoint Authentication Method: none

    • Response Types: token id_token

AM is now prepared for you to try the sample user info claims script.

Try the custom user info claims plugin script

To try your custom script, use the Implicit grant flow as demonstrated in the following steps.

  1. Log in to AM as the demo user, for example:

    $ curl \
    -i \
    --request POST \
    --header "Content-Type: application/json" \
    --header "X-OpenAM-Username: demo" \
    --header "X-OpenAM-Password: Secret12!" \
    --header "Accept-API-Version: resource=2.0, protocol=1.0" \
    'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
    [/mnt/scratch/workspaces/workspace/docs-idpaas-release_master/target/repositories/openam-docs/target/asciidoc/modules/ROOT/attachments/endpoints/authenticate.bash:#POST-authenticate-demo-expected]

    Note the SSO token value returned as tokenId in the output.

  2. Invoke the authorization server’s /oauth2/authorize endpoint specifying the SSO token value in a cookie, and the following parameters as a minimum:

    • client_id=myClient

    • response_type=token id_token

    • scope=openid profile

    • nonce=your nonce value

    • redirect_uri=https://www.example.com:443/callback

    • decision=allow

    • csrf=SSO-token

      For example:

      $ curl --dump-header - \
      --Cookie "<session-cookie-name>=AQIC5wM…​TU3OQ*" \
      --request POST \
      --data "client_id=myClient" \
      --data "response_type=token id_token" \
      --data "scope=openid profile" \
      --data "state=123abc" \
      --data "nonce=abc123" \
      --data "decision=allow" \
      --data "csrf=AQIC5wM…​TU3OQ*" \
      --data "redirect_uri=https://www.example.com:443/callback" \
      "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize"

      If the authorization server successfully authenticates the user, note the value of the access token appended to the redirection URI in the response.

  3. Call the /oauth2/userinfo endpoint to inspect the custom claim values, including the access token obtained from the previous request.

    For example:

    $ curl --request GET --header "Authorization: Bearer az91IvnIQ-uP3Eqw5QqaXXY_DCo" \
    "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/userinfo"
    {
      "given_name":"Demo First Name",
      "family_name":"Demo Last Name",
      "name":"demo",
      "myTestName":"demo",
      "sub":"(usr!demo)",
      "subname":"demo"
    }

    Verify that the response contains the custom claim added by the script (myTestName in this example).

OAuth 2.0 user info claims scripting API

The following properties are available to user info claims scripts, in addition to the common OAuth 2.0 script properties.

Show script properties
claims

Contains a map of the claims that the server provides by default. For example:

{
  "sub": "248289761001",
  "updated_at": "1450368765"
}
claimsLocales

The values from the 'claims_locales' parameter. For details, see Claims Languages and Scripts in the OpenID Connect Core 1.0 specification..

claimObjects

The default claims provided by the server. Always present.

clientProperties

A map of properties configured in the relevant client profile. Only present if the client was correctly identified.

The keys in the map are as follows:

clientId

The URI of the client.

allowedGrantTypes

The list of the allowed grant types (org.forgerock.oauth2.core.GrantType) for the client.

allowedResponseTypes

The list of the allowed response types for the client.

allowedScopes

The list of the allowed scopes for the client.

customProperties

A map of any custom properties added to the client.

Lists or maps are included as sub-maps. For example, a custom property of customMap[Key1]=Value1 is returned as customMap > Key1 > Value1.

To add custom properties to a client, go to OAuth 2.0 > Clients > Client ID > Advanced, and update the Custom Properties field. The custom properties can be added in the format shown in these examples:

customproperty=custom-value1
customList[0]=customList-value-0
customList[1]=customList-value-1
customMap[key1]=customMap-value-1
customMap[key2]=customMap-value-2

From within the script, you can then access the custom properties in the following way:

var customProperties = clientProperties.get("customProperties");
var property = customProperties.get(<PROPERTY_KEY>);
identity

Contains a representation of the identity of the resource owner.

For more details, see the com.sun.identity.idm.AMIdentity class in the AM Javadoc.

requestedClaims

Contains requested claims if the claims query parameter is used in the request, and if Enable "claims_parameter_supported" is checked in the OAuth 2.0 provider service configuration; otherwise, this property is empty.

For more information see Requesting Claims using the "claims" Request Parameter in the OpenID Connect Core 1.0 specification.

Example:

{
  "given_name": {
    "essential": true,
    "values": [
      "Demo User",
      "D User"
    ]
  },
  "nickname": null,
  "email": {
    "essential": true
  }
}
requestedTypedClaims

Contains a list of requested claims if the claims query parameter is used in the request, and Enable "claims_parameter_supported" is checked in the OAuth 2.0 provider service configuration. Otherwise, this property is empty.

A claim with a single value indicates this is the only value that should be returned.

requestProperties

A map of the properties present in the request. Always present.

The keys in the map are as follows:

requestUri

The URI of the request.

realm

The realm to which the request was made.

requestParams

The request parameters, and/or posted data. Each value in this map is a list of one, or more, properties.

To mitigate the risk of reflection-type attacks, use OWASP best practices when handling these properties. For example, see Unsafe use of Reflection.

scopes

Contains a set of the requested scopes. For example:

[
  "profile",
  "openid"
]
session

Contains a representation of the user’s session object if the request contained a session cookie.

For more details, see the com.iplanet.sso.SSOToken class in the AM Javadoc.

Copyright © 2010-2022 ForgeRock, all rights reserved.