OpenID Connect 1.0 (OIDC) claims

Use this extension point to modify and override claims in an ID token and in the response to a /userinfo request.

To view the default script, including the available script properties, refer to oidc-claims-extension.js.

To view or modify the default script in the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts and select OIDC Claims Script.

Custom user info claim examples

Refer to the following sections for example use cases:

Add custom claims to the profile scope
Add a custom claim to a custom scope
Add a session property claim to the profile scope
Redirect users to a specific URL after they sign out
Override the audience and issuer claims

These examples require you to have a test end user. You can create one as follows:

In the Advanced Identity Cloud admin UI, select Identities > Manage > Alpha realm - Users > + New Alpha realm - User and complete the required fields.
Record the username and password.

Add custom claims to the profile scope

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

Create the user info claims script
Create an OpenID Connect 1.0 relying party account
Update the end user profile
Try the custom user info claims plugin script

This example replaces the zoneinfo and locale claims with custom claims from end user profile attributes. It uses the /oauth2/userinfo endpoint to inspect the custom claim values.

Create the user info claims script

This task describes how to create a new script to map custom claims.

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts > + New Script, and create a new OIDC Claims script.
Name the script Demo OIDC claims.

Edit the default JavaScript as follows:

In the utils.setScopeClaimsMap function call, replace the zoneinfo and locale claims with references to the custom claims custom_string and custom_multivalue:

utils.setScopeClaimsMap({
    profile: [
        'name',
        'family_name',
        'given_name',
        'custom_string',
        'custom_multivalue'
    ],
    email: ['email'],
    address: ['address'],
    phone: ['phone_number']
});

In the utils.setClaimResolvers function call, replace the zoneinfo and locale definitions with definitions for the custom claims:

utils.setClaimResolvers({
    name: utils.getUserProfileClaimResolver('cn'),
    family_name: utils.getUserProfileClaimResolver('sn'),
    given_name: utils.getUserProfileClaimResolver('givenname'),
    custom_string: utils.getUserProfileClaimResolver('fr-attr-str1'),
    custom_multivalue: utils.getUserProfileClaimResolver('fr-attr-multi1'),
    email: utils.getUserProfileClaimResolver('mail'),
    address: utils.getAddressClaimResolver(
        // ...
        utils.getUserProfileClaimResolver('postaladdress')
    ),
    phone_number: utils.getUserProfileClaimResolver('telephonenumber')});
});

The attributes fr-attr-str1 and fr-attr-multi1 are end user profile attributes. You set their values when creating the end user profile.

Save your changes.

The new user info claims script is now ready to retrieve custom claims for the profile scope.

Create an OpenID Connect 1.0 relying party account

This OIDC relying party (client) profile overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications.

Refer to Register a client application for further information.

Create a confidential OAuth 2.0 client account

In the Advanced Identity Cloud admin UI, go to Applications and click + Custom Application.
Select the sign-in method as OIDC - OpenId Connect and application type as Web.
Create the application, providing the following details:

Name

myClient

Owners

<resource-owner>

Client ID

myClient

Client Secret

mySecret
Switch to the Sign On tab and under General Settings, make the following changes:

Sign-in URLs

https://www.example.com:443/callback

Grant Types

Implicit

Scopes

openid
profile
Click Show advanced settings, select the Access tab and make the following changes:

Response Types

token id_token
Select the Authentication tab and make the following changes:

Token Endpoint Authentication Method

None
Save your changes.

Override OAuth 2.0 provider settings for this client

Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab and update the following settings:

Enable OAuth2 Provider Overrides

Enabled

OIDC Claims Plugin Type

SCRIPTED

OIDC Claims Script

Demo OIDC claims
Save your changes.

Update the end user profile

The end user profile holds the values for the custom attributes referenced in your script.

In the Advanced Identity Cloud admin UI, go to Identities > Manage > Alpha realm - Users, and select your test user.
Update the following settings in your test end user profile and save your work:

Generic Unindexed String 1

Custom string

Generic Unindexed Multivalue 1

custom
value

The script takes custom claim values from the attributes fr-attr-str1 and fr-attr-multi1. As described in User identity attributes and properties reference, the Advanced Identity Cloud admin UI labels these Generic Unindexed String 1 and Generic Unindexed Multivalue 1.
Display the Raw JSON for the end user profile.

Find the following settings in the JSON:
```
{
  "frUnindexedString1": "Custom string",
  "frUnindexedMultivalued1": [
    "custom",
    "value"
  ]
}
```
The attributes fr-attr-str1 and fr-attr-multi1 map to frUnindexedString1 and frUnindexedMultivalued1 in the JSON representation.

Try the custom user info claims plugin script

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

Authenticate as the end user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <end-user-username>' \
--header 'X-OpenAM-Password: <end-user-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "<end-user-tokenId>",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Copy the value of the tokenId returned in the response. You’ll need this value in the next step.

Invoke the authorization server’s /oauth2/authorize endpoint specifying the tokenId 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=<end-user-tokenId>

For example:

$ curl --dump-header - \
--cookie '<session-cookie-name>=<end-user-tokenId>' \
--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=<end-user-tokenId>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize'

...
Location: https://www.example.com:443/callback#access_token=<access-token>&id_token=<id-token>...
...

Copy the value of the access_token appended to the redirection URI in the response. You’ll need this value in the next step.

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 <access-token>' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/userinfo'
{
  "name": "Test User",
  "family_name": "User",
  "given_name": "Test",
  "custom_string": "Custom string",
  "custom_multivalue": ["value", "custom"],
  "sub": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "subname": "014c54bd-6078-4639-8316-8ce0e7746fa4"
}

Verify the response contains the custom claim added by the script (custom_string and custom_multivalue in this example).

Add a custom claim to a custom scope

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

Create the user info claims script
Create an OpenID Connect 1.0 relying party account
Configure the provider to return claims in the ID token
Try the custom user info claims plugin script

This example adds the custom claim to the ID token and uses the /oauth2/idtokeninfo endpoint to inspect the custom claim values.

Create the user info claims script

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

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts > + New Script, and create a new OIDC Claims script.
Name the script Demo OIDC claims.

Edit the default JavaScript as follows:

In the utils.setScopeClaimsMap function call, add the new myCustomAttr claim to a new custom scope:

utils.setScopeClaimsMap({
        ...
        phone: ['phone_number'],
        custom: ['myCustomAttr']

In the utils.setClaimResolvers function call, add the new claim to the script. For example, insert myCustomAttr after the phone_number claim as follows:

utils.setClaimResolvers({
        ...
        phone_number: utils.getUserProfileClaimResolver('telephonenumber'),
        myCustomAttr: utils.getUserProfileClaimResolver('uid')
    });

Save your changes.

The new user info claims script is now ready to retrieve a custom claim for the custom scope.

Create an OpenID Connect 1.0 relying party account

This OIDC relying party (client) profile overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications.

Create a confidential OAuth 2.0 client account

In the Advanced Identity Cloud admin UI, go to Applications and click + Custom Application.
Select the sign-in method as OIDC - OpenId Connect and application type as Web.
Create the application with the following settings:

Client ID

myClient

Client Secret

mySecret
Switch to the Sign On tab and under General Settings, make the following changes:

Sign-in URLs

https://www.example.com:443/callback

Grant Types

Implicit

Scopes

openid
profile
custom
Click Show advanced settings, select the Access tab and make the following changes:

Response Types

token id_token
Select the Authentication tab and make the following changes:

Token Endpoint Authentication Method

None
Save your changes.

Override OAuth 2.0 provider settings for this client

Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab and update the following settings:

Enable OAuth2 Provider Overrides

Enabled

OIDC Claims Plugin Type

SCRIPTED

OIDC Claims Script

Demo OIDC claims
Save your changes.

Configure the provider to return claims in the ID token

Perform this task to configure the OAuth2 provider to always return scope-derived claims in the ID token.

This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in Request claims in ID tokens.

Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect.
Enable Always Return Claims in ID Tokens.
Save your changes.

Try the custom user info claims plugin script

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

Authenticate as the end user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <end-user-username>' \
--header 'X-OpenAM-Password: <end-user-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "<end-user-tokenId>",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Copy the value of the tokenId returned in the response. You’ll need this value in the next step.

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

client_id=myClient
response_type=token id_token
scope=openid profile custom
nonce=your nonce value
redirect_uri=https://www.example.com:443/callback
decision=allow
csrf=<end-user-tokenId>

For example:

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

...
Location: https://www.example.com:443/callback#access_token=<access-token>&id_token=<id-token>...
...

Copy the value of the id_token appended to the redirection URI in the response. You’ll need this value in the next step.

Call the /oauth2/idtokeninfo endpoint to inspect the custom claim values, including the ID token obtained from the previous request.

For example:

$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=<id-token>' \
"https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/idtokeninfo"
{
  "at_hash": "_0Uie6DRQNgxqiSFa4EIDg",
  "sub": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "auditTrackingId": "b187bfdc-c0ff-4942-b4be-34a8c7134c40-3099380",
  "subname": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
  "tokenName": "id_token",
  "given_name": "Test",
  "sid": "f1ChiEDjsYqYc/ML20bm4QZ9kQvmbIJmD+hZwkRdfOo=",
  "myCustomAttr":"test.user",
  "aud": "myClient",
  "c_hash": "j0ry4449CY9GonHxNEgC4A",
  "acr": "0",
  "org.forgerock.openidconnect.ops": "5NkCJhSacAzRsdELBgRJvbpuVMk",
  "s_hash": "bKE9UspwyIPg8LsQHkJaiQ",
  "azp": "myClient",
  "auth_time": 1670316296,
  "name": "Test User",
  "realm": "/alpha",
  "exp": 1670319945,
  "tokenType": "JWTToken",
  "iat": 1670316345,
  "family_name": "User"
}

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

Add a session property claim to the profile scope

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

Create the user info claims script
Allowlist the session property
Create an OpenID Connect 1.0 relying party account
Configure the provider to return claims in the ID token
Try the custom user info claims plugin script

This example adds SSO session details to the ID token and uses the /oauth2/idtokeninfo endpoint to inspect the session property claim values.

These steps add the AuthLevel session property, but the same steps apply to all session properties. For a list of the default session properties, refer to Session properties.

For an example of adding a session property obtained during a login journey, refer to How do I make session properties from a journey available in the OIDC ID token in Identity Cloud?

Create the user info claims script

This task describes how to create a new script to map a session property claim.

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts > + New Script, and create a new OIDC Claims script.
Name the script Demo OIDC claims.

Edit the default JavaScript as follows:

In the utils.setScopeClaimsMap function call, add the new AuthLevel claim to the profile scope:

utils.setScopeClaimsMap({
        profile: [
            'name',
            'family_name',
            'given_name',
            'zoneinfo',
            'locale',
            'AuthLevel'
        ],
        email: ['email'],

In the utils.setClaimResolvers function call, add the new claim to the script. For example, insert AuthLevel after the phone_number claim as follows:

utils.setClaimResolvers({
        ...
        phone_number: utils.getUserProfileClaimResolver('telephonenumber'),
        AuthLevel: function () {
            return session.getProperty('AuthLevel');
        }

    });

Save your changes.

The new user info claims script is now ready to retrieve a session property claim for the profile scope.

Allowlist the session property

Provide access to the session property to allow it to be output in the ID token.

Under Native Consoles > Access Management, select Realms > alpha > Services > Session Property Whitelist Service.
Add AuthLevel to the Allowlisted Session Property Names field.
Save your changes.

Create an OpenID Connect 1.0 relying party account

This OIDC relying party (client) profile overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications.

Refer to Register a client application for further information.

Create a confidential OAuth 2.0 client account

In the Advanced Identity Cloud admin UI, go to Applications and click + Custom Application.
Select the sign-in method as OIDC - OpenId Connect and application type as Web.
Create the application, providing the following details:

Name

myClient

Owners

<resource-owner>

Client ID

myClient

Client Secret

mySecret
Switch to the Sign On tab and under General Settings, make the following changes:

Sign-in URLs

https://www.example.com:443/callback

Grant Types

Implicit

Scopes

openid
profile
Click Show advanced settings, select the Access tab and make the following changes:

Response Types

token id_token
Select the Authentication tab and make the following changes:

Token Endpoint Authentication Method

None
Save your changes.

Override OAuth 2.0 provider settings for this client

Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab and update the following settings:

Enable OAuth2 Provider Overrides

Enabled

OIDC Claims Plugin Type

SCRIPTED

OIDC Claims Script

Demo OIDC claims
Save your changes.

Configure the provider to return claims in the ID token

Perform this task to configure the OAuth2 provider to always return scope-derived claims in the ID token.

This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in Request claims in ID tokens.

Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect.
Enable Always Return Claims in ID Tokens.
Save your changes.

Try the custom user info claims plugin script

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

Authenticate as the end user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <end-user-username>' \
--header 'X-OpenAM-Password: <end-user-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "<end-user-tokenId>",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Copy the value of the tokenId returned in the response. You’ll need this value in the next step.

Invoke the authorization server’s /oauth2/authorize endpoint specifying the tokenId 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=<end-user-tokenId>

For example:

$ curl --dump-header - \
--cookie '<session-cookie-name>=<end-user-tokenId>' \
--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=<end-user-tokenId>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize'

...
Location: https://www.example.com:443/callback#access_token=<access-token>&id_token=<id-token>...
...

Copy the value of the id_token appended to the redirection URI in the response. You’ll need this value in the next step.

Call the /oauth2/idtokeninfo endpoint to inspect the session property claim values, including the ID token obtained from the previous request.

For example:

$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=<id-token>' \
"https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/idtokeninfo"
{
  "at_hash": "_0Uie6DRQNgxqiSFa4EIDg",
  "sub": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "auditTrackingId": "b187bfdc-c0ff-4942-b4be-34a8c7134c40-3099380",
  "subname": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "iss": "https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha",
  "tokenName": "id_token",
  "given_name": "Test",
  "sid": "f1ChiEDjsYqYc/ML20bm4QZ9kQvmbIJmD+hZwkRdfOo=",
  "AuthLevel":"0",
  "aud": "myClient",
  "c_hash": "j0ry4449CY9GonHxNEgC4A",
  "acr": "0",
  "org.forgerock.openidconnect.ops": "5NkCJhSacAzRsdELBgRJvbpuVMk",
  "s_hash": "bKE9UspwyIPg8LsQHkJaiQ",
  "azp": "myClient",
  "auth_time": 1670316296,
  "name": "Test User",
  "realm": "/alpha",
  "exp": 1670319945,
  "tokenType": "JWTToken",
  "iat": 1670316345,
  "family_name": "User"
}

Verify the response contains the session property claim added by the script (AuthLevel in this example).

Redirect users to a specific URL after they sign out

Complete the following steps to implement an example user info claims script that redirects users to a specific URL after they sign out of the Advanced Identity Cloud end-user UI:

Configure the user info claims script
Configure the provider to return claims in the ID token
Test the redirection

This is achieved by adding an optional claim called post_logout_url to the OIDC ID token issued during an OIDC flow.

Configure the user info claims script

This task describes how to modify the default script used by the end-user UI to redirect users to a specific URL after they sign out.

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts and select Alpha endUserUIClient OIDC Claims Script.
Edit the default JavaScript as follows:
- In the utils.setScopeClaimsMap function call, add the post_logout_url claim to the fr:idm:* scope as follows:
  utils.setScopeClaimsMap({ ... phone: ['phone_number'], 'fr:idm:*': ['post_logout_url']
- In the utils.setClaimResolvers function call, add mapping details for the post_logout_url claim, including the URL where you want to redirect users on logout. For example, redirect users to https://pingidentity.com as follows:
  utils.setClaimResolvers({ ... phone_number: utils.getUserProfileClaimResolver('telephonenumber'), post_logout_url: function (requestedClaim) { return 'https://pingidentity.com'; } });
Save your changes.

The post_logout_url claim is added to all clients that use the modified script and request the fr:idm:* scope.

Configure the provider to return claims in the ID token

Perform this task to configure the OAuth2 provider to always return scope-derived claims in the ID token.

This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in Request claims in ID tokens.

Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect.
Enable Always Return Claims in ID Tokens.
Save your changes.

Test the redirection

Test your changes as follows:

In the Advanced Identity Cloud admin UI, go to account_tree Journeys and click on the Login journey.
In the Preview URL field, click copy and paste the URL into an Incognito window.

The Sign In page displays.
Sign in as the test end user.
Sign out.

The End User UI redirects the browser to the URL you configured for the post_logout_url claim, in this case, https://pingidentity.com.

Override the audience and issuer claims

Complete the following steps to implement an example user info claims script that overrides the aud (audience) and iss (issuer) claims:

Create the user info claims script
Create an OpenID Connect 1.0 relying party account
Configure the provider to return claims in the ID token
Try the custom user info claims plugin script

This example overrides the aud and iss claims in the ID token and uses the /oauth2/idtokeninfo endpoint to inspect the overridden claims.

These steps override the aud and iss claims, but the same steps can be used to override any of the core OIDC claims.

For information about the core OIDC claims, refer to the ID Token data structure.

Create the user info claims script

This task describes how to create a new script to override the aud and iss claims.

In the Advanced Identity Cloud admin UI, go to Scripts > Auth Scripts > + New Script, and create a new OIDC Claims script.
Name the script Demo OIDC claims.

Edit the default JavaScript as follows:

Add the claim override details before the return computedClaims; line. You can specify overrides as a string or an array. For example, add an iss override as a string:
```
computedClaims.put("iss", "https://example.com")

return computedClaims;
```

Then add an aud override as an array:

var audClaim = ["myClient","testClient"];
computedClaims.put("aud", audClaim)

The aud override values you specify must correspond to registered clients; otherwise, you’ll see an error when you inspect the claim values.

Replace testClient in the script above with the ID of another registered OAuth2 client, or create a temporary OAuth2 client called testClient for testing purposes.

Save your changes.

The new user info claims script is now ready to override claims.

Create an OpenID Connect 1.0 relying party account

This OIDC relying party (client) profile overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications.

Refer to Register a client application for further information.

Create a confidential OAuth 2.0 client account

In the Advanced Identity Cloud admin UI, go to Applications and click + Custom Application.
Select the sign-in method as OIDC - OpenId Connect and application type as Web.
Create the application, providing the following details:

Name

myClient

Owners

<resource-owner>

Client ID

myClient

Client Secret

mySecret
Switch to the Sign On tab and under General Settings, make the following changes:

Sign-in URLs

https://www.example.com:443/callback

Grant Types

Implicit

Scopes

openid
profile
Click Show advanced settings, select the Access tab and make the following changes:

Response Types

token id_token
Select the Authentication tab and make the following changes:

Token Endpoint Authentication Method

None
Save your changes.

Override OAuth 2.0 provider settings for this client

Under Native Consoles > Access Management, select Realms > alpha > Applications > OAuth 2.0 > Clients > myClient, switch to the OAuth2 Provider Overrides tab and update the following settings:

Enable OAuth2 Provider Overrides

Enabled

OIDC Claims Plugin Type

SCRIPTED

OIDC Claims Script

Demo OIDC claims

Overrideable Id_Token Claims

aud
iss
Save your changes.

Configure the provider to return claims in the ID token

Perform this task to configure the OAuth2 provider to always return scope-derived claims in the ID token.

This option is disabled by default because of the security concerns of returning claims that may contain sensitive user information. Learn more in Request claims in ID tokens.

Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect.
Enable Always Return Claims in ID Tokens.
Save your changes.

Try the custom user info claims plugin script

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

Authenticate as the end user:

$ curl \
--request POST \
--header 'Content-Type: application/json' \
--header 'X-OpenAM-Username: <end-user-username>' \
--header 'X-OpenAM-Password: <end-user-password>' \
--header 'Accept-API-Version: resource=2.0, protocol=1.0' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/authenticate'
{
  "tokenId": "<end-user-tokenId>",
  "successUrl": "/enduser/?realm=/alpha",
  "realm": "/alpha"
}

Copy the value of the tokenId returned in the response. You’ll need this value in the next step.

Invoke the authorization server’s /oauth2/authorize endpoint specifying the tokenId 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=<end-user-tokenId>

For example:

$ curl --dump-header - \
--cookie '<session-cookie-name>=<end-user-tokenId>' \
--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=<end-user-tokenId>' \
--data 'redirect_uri=https://www.example.com:443/callback' \
'https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/authorize'

...
Location: https://www.example.com:443/callback#access_token=<access-token>&id_token=<id-token>...
...

Copy the value of the id_token appended to the redirection URI in the response. You’ll need this value in the next step.

Call the /oauth2/idtokeninfo endpoint to inspect the overridden claims, including the ID token obtained from the previous request.

For example:

$ curl \
--request POST \
--user myClient:mySecret \
--data 'id_token=<id-token>' \
"https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/idtokeninfo"
{
  "at_hash": "_0Uie6DRQNgxqiSFa4EIDg",
  "sub": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "auditTrackingId": "b187bfdc-c0ff-4942-b4be-34a8c7134c40-3099380",
  "subname": "014c54bd-6078-4639-8316-8ce0e7746fa4",
  "iss":"https://example.com",
  "tokenName": "id_token",
  "given_name": "Test",
  "sid": "f1ChiEDjsYqYc/ML20bm4QZ9kQvmbIJmD+hZwkRdfOo=",
  "aud": [
    "myClient",
    "testClient"
  ],
  "c_hash": "j0ry4449CY9GonHxNEgC4A",
  "acr": "0",
  "org.forgerock.openidconnect.ops": "5NkCJhSacAzRsdELBgRJvbpuVMk",
  "s_hash": "bKE9UspwyIPg8LsQHkJaiQ",
  "azp": "myClient",
  "auth_time": 1670316296,
  "name": "Test User",
  "realm": "/alpha",
  "exp": 1670319945,
  "tokenType": "JWTToken",
  "iat": 1670316345,
  "family_name": "User"
}

Verify the response contains the overridden iss and aud values.

Use a validated script

Test your OIDC claims scripts as you did in the examples. After validating your script with OAuth 2.0 provider overrides in your test client, you can update the OAuth 2.0 provider configuration to use the script in one of the following ways:

Under Native Consoles > Access Management, select Realms > Realm Name > Services > OAuth2 Provider, switch to the Plugins tab, edit the OIDC Claims Script, and save your work.
In the Advanced Identity Cloud admin UI, select Scripts > Auth Scripts > Realm Name > OIDC Claims Script, and replace the script content with your validated script.

Available objects

PingOne Advanced Identity Cloud injects the following objects into the execution context of a user info claims script:

Binding Information

claims

An object (map) of the default OIDC claims PingOne Advanced Identity Cloud provides.

The keys are the claim strings. The values are the claim value objects.

claimLocales

An array of string values from the claims_locales parameter.

For details, refer to Claims Languages and Scripts in the OpenID Connect Core 1.0 specification.

claimObjects

The default OIDC claims PingOne Advanced Identity Cloud provides.

An array of claim objects.

clientProperties

A read-only object (map) of the following client properties. This is present if PingOne Advanced Identity Cloud identified the client specified in the request.

allowedGrantTypes

List of the grant types allowed for the client. For details, refer to the Javadoc for GrantType.

allowedResponseTypes

The list of the allowed response types for the client.

allowedScopes

The list of the allowed scopes for the client.

clientId

The client’s URI for the request locale.

customProperties

A map of any custom properties added to the client.

These properties can include lists or maps as sub-maps. For example, the script includes customMap[Key1]=Value1 as customMap > Key1 > Value1 in the object.

To add custom properties to a client, go to Native Consoles > Access Management > OAuth 2.0 > Clients > Client ID > Advanced and update the Custom Properties field.

Scripts access the custom properties in the following way:

var customProperties = clientProperties.get("customProperties");
var property = customProperties.get("myProperty");

httpClient

An HTTP client for making external HTTP requests.

identity

An identity PingOne Advanced Identity Cloud can access.

For details, refer to AMIdentity.

logger

Write a message to the PingOne Advanced Identity Cloud debug log. Always present in all extension scripts.

In Advanced Identity Cloud, this corresponds to the am-core log source.

Logger names use the format scripts.OIDC_CLAIMS.<script UUID>.(<script name>).

For information about debug logs, refer to Get audit and debug logs.

requestedClaims

An object (map) of requested claims. This is empty unless the request includes the claims query string parameter and PingOne Advanced Identity Cloud is configured to support its use.

Under Native Consoles > Access Management, go to Realms > Realm Name > Services > OAuth2 Provider > Advanced OpenID Connect. Enable Enable "claims_parameter_supported" and save your change.

For details about the claims query string parameter, refer to Requesting Claims using the "claims" Request Parameter in the OpenID Connect Core 1.0 specification.

requestedTypedClaims

An array of the requested claims objects. This is empty unless the request includes claims.

A claim with a single value means the script should return only that value.

requestProperties

A read-only object (map) of the following request properties.

requestUri

The URI as a string.

realm

The realm as a string.

requestParams

A map of request parameters and posted data, where each value is an array of parameters.

To mitigate the risk of reflection-type attacks, use OWASP best practices when handling these parameters. Refer to Unsafe use of Reflection.

requestHeaders

The value of the named request header. Returns a map of <String, List<String>> as a native JavaScript object, for example:

var ipAddress = requestProperties.requestHeaders["X-Forwarded-For"][0]

Header names are case-sensitive.

scopes

The set of scope strings in the client request.

scriptName

The display name of the script.

session

The user’s session object.

For details, refer to SSOToken.