--- title: OIDC claims description: Use this extension point to modify and override claims in an ID token and in the response to a /userinfo request. component: pingoneaic page_id: pingoneaic:am-oauth2:plugins-user-info-claims canonical_url: https://docs.pingidentity.com/pingoneaic/am-oauth2/plugins-user-info-claims.html keywords: ["OAuth 2.0", "OpenID Connect (OIDC)", "Customization", "Plugins", "Authorization", "Scripting"] page_aliases: ["oauth2-guide:plugins-user-info-claims.adoc"] section_ids: prepare-for-examples: Prepare the end user profile custom-oidc-claims-legacy: Examples using legacy scripts example-add-custom-claims-profile-scope: Add custom claims to the profile scope config-oidc-plugin: Create the OIDC claims script create-oidc-client: Create a client application create_a_confidential_oauth_2_0_client: Create a confidential OAuth 2.0 client override_oauth_2_0_provider_settings_for_this_client: Override OAuth 2.0 provider settings for this client try-oidc-plugin: Try the script example-add-custom-claim-custom-scope: Add a custom claim to a custom scope config-oidc-plugin-custom: Create the OIDC claims script create-oidc-client-custom: Create a client application create_a_confidential_oauth_2_0_client_2: Create a confidential OAuth 2.0 client override_oauth_2_0_provider_settings_for_this_client_2: Override OAuth 2.0 provider settings for this client configure-provider-claims-id-token-custom: Configure the provider try-oidc-plugin-custom: Try the script example-add-session-claim-profile-scope: Add a session property claim to the profile scope config-oidc-plugin-session: Create the OIDC claims script allowlist-session-property: Allowlist the session property create-oidc-client-session: Create a client application create_a_confidential_oauth_2_0_client_3: Create a confidential OAuth 2.0 client override_oauth_2_0_provider_settings_for_this_client_3: Override OAuth 2.0 provider settings for this client configure-provider-claims-id-token-session: Configure the provider try-oidc-plugin-session: Try the script example-redirect-users-after-logout: Redirect users to a specific URL after they sign out config-oidc-plugin-logout: Configure the OIDC claims script configure-provider-claims-id-token-logout: Configure the provider try-oidc-plugin-logout: Test the redirection example-override-issuer-audience: Override the audience and issuer claims config-oidc-plugin-override: Create the OIDC claims script create-oidc-client-override: Create a client application create_a_confidential_oauth_2_0_client_4: Create a confidential OAuth 2.0 client override_oauth_2_0_provider_settings_for_this_client_4: Override OAuth 2.0 provider settings for this client configure-provider-claims-id-token-override: Configure the provider try-oidc-plugin-override: Try the script example-oidc-claims-nextgen: Example using a next-generation script config-oidc-plugin-ng: Create the OIDC claims script create-oidc-client-ng: Create a client application create_a_confidential_oauth_2_0_client_5: Create a confidential OAuth 2.0 client override_oauth_2_0_provider_settings_for_this_client_5: Override OAuth 2.0 provider settings for this client try-oidc-plugin-ng: Try the script use_a_validated_script: Use a validated script --- # OIDC claims Use this extension point to modify and override claims in an ID token and in the response to a [`/userinfo`](../am-oidc1/rest-api-oidc-userinfo-endpoint.html) request. * Template script [OIDC Claims Script](../am-scripting/sample-scripts.html#oidc-claims-extension-js) * Script bindings [OIDC claims scripting API](../am-scripting/user-info-claims-api.html) ## Prepare the end user profile The customization examples require you to have a test end user. Some require you to set profile attributes. Complete these prerequisite steps to set up a test user: 1. [Create a user profile](../identities/manage-identities.html#create_a_user_profile) 2. Record the username and password. 3. Set the following values in the user profile: * Generic Unindexed String 1 `Custom string` * Generic Unindexed Multivalue 1 `custom` + `value` This sets the attributes `fr-attr-str1` and `fr-attr-multi1`. 4. Save your changes. ## Examples using legacy scripts The following examples demonstrate how to customize OIDC claims using a legacy script. * [Add custom claims to the profile scope](#example-add-custom-claims-profile-scope) * [Add a custom claim to a custom scope](#example-add-custom-claim-custom-scope) * [Add a session property claim to the profile scope](#example-add-session-claim-profile-scope) * [Redirect users to a specific URL after they sign out](#example-redirect-users-after-logout) * [Override the audience and issuer claims](#example-override-issuer-audience) ### Add custom claims to the profile scope Complete the following steps to implement an example OIDC claims script that adds custom claims to the profile scope: 1. [Create the OIDC claims script](#config-oidc-plugin) 2. [Create a client application](#create-oidc-client) 3. [Try the script](#try-oidc-plugin) This example replaces the `zoneinfo` and `locale` claims with custom claims from end user profile attributes. It uses the [/oauth2/userinfo](../am-oidc1/rest-api-oidc-userinfo-endpoint.html) endpoint to inspect the custom claim values. #### Create the OIDC claims script This task describes how to create a new script to map custom claims. 1. In the Advanced Identity Cloud admin console, [create a new](../developer-docs/scripting-auth.html#create-a-new-auth-script) OIDC Claims script. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | This example uses a legacy script. Find a next-generation example in [Example using a next-generation script](#example-oidc-claims-nextgen). | 2. Name the script `Demo OIDC claims`. 3. 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`: ```javascript 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: ```javascript 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 you [created the end user profile](#prepare-for-examples). 4. Save your changes. The new OIDC claims script is now ready to retrieve custom claims for the `profile` scope. #### Create a client application The client application (the OIDC relying party) overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications. Find more information in [Register a client application](../app-management/register-a-custom-application.html). ##### Create a confidential OAuth 2.0 client 1. In the Advanced Identity Cloud admin console, go to Applications and click + Custom Application. 2. Select the sign-in method as OIDC - OpenId Connect and application type as Web. 3. Create the application, providing the following details: * Name `myClient` * Owners `` * Client ID `myClient` * Client Secret `mySecret` 4. 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` 5. Click Show advanced settings, select the Access tab and make the following changes: * Response Types `token id_token` 6. Select the Authentication tab and make the following changes: * Token Endpoint Authentication Method `None` 7. Save your changes. ##### Override OAuth 2.0 provider settings for this client 1. 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` 2. Save your changes. #### Try the script To try your custom script, use the [Implicit grant](oauth2-implicit-grant.html) flow as demonstrated in the following steps. 1. Authenticate as the end user: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "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. 2. Invoke the authorization server's [/oauth2/authorize](oauth2-authorize-endpoint.html) 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**=`` For example: ```bash $ curl --dump-header - \ --cookie '=' \ --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=' \ --data 'redirect_uri=https://www.example.com:443/callback' \ 'https:///am/oauth2/realms/root/realms/alpha/authorize' ``` ```HTTP ... Location: https://www.example.com:443/callback#access_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. 3. Call the [/oauth2/userinfo](../am-oidc1/rest-api-oidc-userinfo-endpoint.html) endpoint to inspect the custom claim values, including the access token obtained from the previous request. For example: ```bash $ curl \ --request GET \ --header 'Authorization: Bearer ' \ 'https:///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 OIDC claims script that adds a custom claim to a custom scope: 1. [Create the OIDC claims script](#config-oidc-plugin-custom) 2. [Create a client application](#create-oidc-client-custom) 3. [Configure the provider](#configure-provider-claims-id-token-custom) 4. [Try the script](#try-oidc-plugin-custom) This example adds the custom claim to the ID token and uses the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint to inspect the custom claim values. #### Create the OIDC claims script This task describes how to create a new script to map a custom claim. 1. In the Advanced Identity Cloud admin console, [create a new](../developer-docs/scripting-auth.html#create-a-new-auth-script) OIDC Claims script. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | This example uses a legacy script. Find a next-generation example in [Example using a next-generation script](#example-oidc-claims-nextgen). | 2. Name the script `Demo OIDC claims`. 3. Edit the default JavaScript as follows: * In the `utils.setScopeClaimsMap` function call, add the new `myCustomAttr` claim to a new `custom` scope: ```javascript 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: ```javascript utils.setClaimResolvers({ ... phone_number: utils.getUserProfileClaimResolver('telephonenumber'), myCustomAttr: utils.getUserProfileClaimResolver('uid') }); ``` 4. Save your changes. The new OIDC claims script is now ready to retrieve a custom claim for the `custom` scope. #### Create a client application The client application (the OIDC relying party) 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 1. In the Advanced Identity Cloud admin console, go to Applications and click + Custom Application. 2. Select the sign-in method as OIDC - OpenId Connect and application type as Web. 3. Create the application with the following settings: * Client ID `myClient` * Client Secret `mySecret` 4. 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` 5. Click Show advanced settings, select the Access tab and make the following changes: * Response Types `token id_token` 6. Select the Authentication tab and make the following changes: * Token Endpoint Authentication Method `None` 7. Save your changes. ##### Override OAuth 2.0 provider settings for this client 1. 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` 2. Save your changes. #### Configure the provider 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](../am-oidc1/understanding-openid-connect-scopes-and-claims.html#request-claims-tokens). | 1. Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect. 2. Enable Always Return Claims in ID Tokens. 3. Save your changes. #### Try the script To try your custom script, use the [Implicit grant](oauth2-implicit-grant.html) flow as demonstrated in the following steps. 1. Authenticate as the end user: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "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. 2. Invoke the authorization server's [/oauth2/authorize](oauth2-authorize-endpoint.html) 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**=`` For example: ```bash $ curl --dump-header - \ --cookie '=' \ --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=' \ --data 'redirect_uri=https://www.example.com:443/callback' \ 'https:///am/oauth2/realms/root/realms/alpha/authorize' ``` ```HTTP ... Location: https://www.example.com:443/callback#access_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. 3. Call the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint to inspect the custom claim values, including the ID token obtained from the previous request. For example: ```bash $ curl \ --request POST \ --user myClient:mySecret \ --data 'id_token=' \ "https:///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://_/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 OIDC claims script that adds a session property claim to the profile scope: 1. [Create the OIDC claims script](#config-oidc-plugin-session) 2. [Allowlist the session property](#allowlist-session-property) 3. [Create a client application](#create-oidc-client-session) 4. [Configure the provider](#configure-provider-claims-id-token-session) 5. [Try the script](#try-oidc-plugin-session) This example adds SSO session details to the ID token and uses the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint to inspect the session property claim values. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | These steps add the `AuthLevel` session property, but the same steps apply to all session properties. Find a list of the default session properties in [Session properties](../am-authentication/auth-tree-webhooks.html#session-properties).Learn more about adding a session property obtained during a login journey in [Expose journey session properties in the OIDC ID token](../use-cases/use-case-journey-session-properties-oidc.html). | #### Create the OIDC claims script This task describes how to create a new script to map a session property claim. 1. In the Advanced Identity Cloud admin console, [create a new](../developer-docs/scripting-auth.html#create-a-new-auth-script) OIDC Claims script. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | This example uses a legacy script. Find a next-generation example in [Example using a next-generation script](#example-oidc-claims-nextgen). | 2. Name the script `Demo OIDC claims`. 3. Edit the default JavaScript as follows: * In the `utils.setScopeClaimsMap` function call, add the new `AuthLevel` claim to the `profile` scope: ```javascript 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: ```javascript utils.setClaimResolvers({ ... phone_number: utils.getUserProfileClaimResolver('telephonenumber'), AuthLevel: function () { return session.getProperty('AuthLevel'); } }); ``` 4. Save your changes. The new OIDC 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. 1. Under Native Consoles > Access Management, select Realms > alpha > Services > Session Property Whitelist Service. 2. Add `AuthLevel` to the Allowlisted Session Property Names field. 3. Save your changes. #### Create a client application The client application (the OIDC relying party) overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications. Find more information in [Register a client application](../app-management/register-a-custom-application.html). ##### Create a confidential OAuth 2.0 client 1. In the Advanced Identity Cloud admin console, go to Applications and click + Custom Application. 2. Select the sign-in method as OIDC - OpenId Connect and application type as Web. 3. Create the application, providing the following details: * Name `myClient` * Owners `` * Client ID `myClient` * Client Secret `mySecret` 4. 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` 5. Click Show advanced settings, select the Access tab and make the following changes: * Response Types `token id_token` 6. Select the Authentication tab and make the following changes: * Token Endpoint Authentication Method `None` 7. Save your changes. ##### Override OAuth 2.0 provider settings for this client 1. 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` 2. Save your changes. #### Configure the provider 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](../am-oidc1/understanding-openid-connect-scopes-and-claims.html#request-claims-tokens). | 1. Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect. 2. Enable Always Return Claims in ID Tokens. 3. Save your changes. #### Try the script To try your custom script, use the [Implicit grant](oauth2-implicit-grant.html) flow as demonstrated in the following steps. 1. Authenticate as the end user: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "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. 2. Invoke the authorization server's [/oauth2/authorize](oauth2-authorize-endpoint.html) 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**=`` For example: ```bash $ curl --dump-header - \ --cookie '=' \ --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=' \ --data 'redirect_uri=https://www.example.com:443/callback' \ 'https:///am/oauth2/realms/root/realms/alpha/authorize' ``` ```HTTP ... Location: https://www.example.com:443/callback#access_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. 3. Call the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint to inspect the session property claim values, including the ID token obtained from the previous request. For example: ```bash $ curl \ --request POST \ --user myClient:mySecret \ --data 'id_token=' \ "https:///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://_/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 OIDC claims script that redirects users to a specific URL after they sign out of the Advanced Identity Cloud end-user UI: 1. [Configure the OIDC claims script](#config-oidc-plugin-logout) 2. [Configure the provider](#configure-provider-claims-id-token-logout) 3. [Test the redirection](#try-oidc-plugin-logout) This is achieved by adding an optional claim called `post_logout_url` to the OIDC ID token issued during an OIDC flow. #### Configure the OIDC 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. 1. In the Advanced Identity Cloud admin console, go to Scripts > Auth Scripts and select Alpha endUserUIClient OIDC Claims Script. 2. 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: ```javascript 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 as follows: ```javascript utils.setClaimResolvers({ ... phone_number: utils.getUserProfileClaimResolver('telephonenumber'), post_logout_url: function (requestedClaim) { return 'https://pingidentity.com'; } }); ``` 3. 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 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](../am-oidc1/understanding-openid-connect-scopes-and-claims.html#request-claims-tokens). | 1. Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect. 2. Enable Always Return Claims in ID Tokens. 3. Save your changes. #### Test the redirection Test your changes as follows: 1. In the Advanced Identity Cloud admin console, go to [icon: account_tree, set=material, size=inline] Journeys and click on the `Login` journey. 2. In the Preview URL field, click [icon: copy, set=material, size=inline] and paste the URL into an incognito window. The Sign In page displays. 3. Sign in as the test end user. 4. Sign out. The End User UI redirects the browser to the URL you configured for the `post_logout_url` claim, in this case, . ### Override the audience and issuer claims Complete the following steps to implement an example OIDC claims script that overrides the `aud` (audience) and `iss` (issuer) claims: 1. [Create the OIDC claims script](#config-oidc-plugin-override) 2. [Create a client application](#create-oidc-client-override) 3. [Configure the provider](#configure-provider-claims-id-token-override) 4. [Try the script](#try-oidc-plugin-override) This example overrides the `aud` and `iss` claims in the ID token and uses the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) 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](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). | #### Create the OIDC claims script This task describes how to create a new script to override the `aud` and `iss` claims. 1. In the Advanced Identity Cloud admin console, [create a new](../developer-docs/scripting-auth.html#create-a-new-auth-script) OIDC Claims script. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------- | | | This example uses a legacy script. Find a next-generation example in [Example using a next-generation script](#example-oidc-claims-nextgen). | 2. Name the script `Demo OIDC claims`. 3. 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: ```javascript computedClaims.put("iss", "https://example.com") return computedClaims; ``` * Then add an `aud` override as an array: ```javascript 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. | 4. Save your changes. The new OIDC claims script is now ready to override claims. #### Create a client application The client application (the OIDC relying party) overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications. Find more information in [Register a client application](../app-management/register-a-custom-application.html). ##### Create a confidential OAuth 2.0 client 1. In the Advanced Identity Cloud admin console, go to Applications and click + Custom Application. 2. Select the sign-in method as OIDC - OpenId Connect and application type as Web. 3. Create the application, providing the following details: * Name `myClient` * Owners `` * Client ID `myClient` * Client Secret `mySecret` 4. 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` 5. Click Show advanced settings, select the Access tab and make the following changes: * Response Types `token id_token` 6. Select the Authentication tab and make the following changes: * Token Endpoint Authentication Method `None` 7. Save your changes. ##### Override OAuth 2.0 provider settings for this client 1. 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` 2. Save your changes. #### Configure the provider 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](../am-oidc1/understanding-openid-connect-scopes-and-claims.html#request-claims-tokens). | 1. Under Native Consoles > Access Management, select Realms > alpha > Services > OAuth2 Provider > Advanced OpenID Connect. 2. Enable Always Return Claims in ID Tokens. 3. Save your changes. #### Try the script To try your custom script, use the [Implicit grant](oauth2-implicit-grant.html) flow as demonstrated in the following steps. 1. Authenticate as the end user: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "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. 2. Invoke the authorization server's [/oauth2/authorize](oauth2-authorize-endpoint.html) 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**=`` For example: ```bash $ curl --dump-header - \ --cookie '=' \ --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=' \ --data 'redirect_uri=https://www.example.com:443/callback' \ 'https:///am/oauth2/realms/root/realms/alpha/authorize' ``` ```HTTP ... Location: https://www.example.com:443/callback#access_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. 3. Call the [/oauth2/idtokeninfo](../am-oidc1/rest-api-oidc-idtoken-validation.html) endpoint to inspect the overridden claims, including the ID token obtained from the previous request. For example: ```bash $ curl \ --request POST \ --user myClient:mySecret \ --data 'id_token=' \ "https:///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. ## Example using a next-generation script The following example demonstrates how to add custom claims to the profile scope using a next-generation script. 1. [Create the OIDC claims script](#config-oidc-plugin-ng) 2. [Create a client application](#create-oidc-client-ng) 3. [Try the script](#try-oidc-plugin-ng) This example adds custom claims from end user profile attributes. It uses the [/oauth2/userinfo](../am-oidc1/rest-api-oidc-userinfo-endpoint.html) endpoint to inspect the custom claim values. ### Create the OIDC claims script This task describes how to create a new next-generation script to map custom claims. 1. Under Native Consoles > Access Management, go to Scripts > + New Script, and provide the following values: * Name `Demo OIDC claims` * Script Type `OIDC Claims` * Evaluator Version `Next Generation` 2. In the Script field, paste the following JavaScript: ```javascript (function () { var computedClaims = {}; var compositeScopes = {}; function getAttribute(attrName) { var values = identity.getAttributeValues(attrName); return (values && values.size() > 0 ? values[0] : null); } // Use the 'identity' binding to fetch user profile data if (identity) { var cn = getAttribute('cn'); var sn = getAttribute('sn'); var gn = getAttribute('givenName'); var customString = getAttribute('fr-attr-str1'); var customMulti = getAttribute('fr-attr-multi1'); // Map standard OIDC claims if (cn) computedClaims['name'] = cn; if (sn) computedClaims['family_name'] = sn; if (gn) computedClaims['given_name'] = gn; // Add custom claims if (customString) computedClaims['custom_string'] = customString; if (customMulti) computedClaims['custom_multivalue'] = Array.from(customMulti); } // Map claims to requested scopes for each(var scope in scopes) { // Map claims to the 'profile' scope, including our custom ones if (scope === 'profile') { compositeScopes['profile'] = [ 'name', 'family_name', 'given_name', 'custom_string', 'custom_multivalue' ]; } else if (scope === 'email') { compositeScopes['email'] = ['email']; } } // The script must return an object with exactly two properties: // 'values' and 'compositeScopes' var result = { values: computedClaims, compositeScopes: compositeScopes }; return result; }()); ``` The attributes `fr-attr-str1` and `fr-attr-multi1` are end user profile attributes. You set their values when you [created the end user profile](#prepare-for-examples). 3. Save your changes. The new OIDC claims script is now ready to retrieve custom claims for the `profile` scope. #### Create a client application The client application (the OIDC relying party) overrides the OAuth 2.0 provider settings. The override lets you test the script without affecting ID and access tokens issued to other applications. Find more information in [Register a client application](../app-management/register-a-custom-application.html). ##### Create a confidential OAuth 2.0 client 1. In the Advanced Identity Cloud admin console, go to Applications and click + Custom Application. 2. Select the sign-in method as OIDC - OpenId Connect and application type as Web. 3. Create the application, providing the following details: * Name `myClient` * Owners `` * Client ID `myClient` * Client Secret `mySecret` 4. 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` 5. Click Show advanced settings, select the Access tab and make the following changes: * Response Types `token id_token` 6. Select the Authentication tab and make the following changes: * Token Endpoint Authentication Method `None` 7. Save your changes. ##### Override OAuth 2.0 provider settings for this client 1. 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` 2. Save your changes. #### Try the script To try your custom script, use the [Implicit grant](oauth2-implicit-grant.html) flow as demonstrated in the following steps. 1. Authenticate as the end user: ```bash $ curl \ --request POST \ --header 'Content-Type: application/json' \ --header 'X-OpenAM-Username: ' \ --header 'X-OpenAM-Password: ' \ --header 'Accept-API-Version: resource=2.0, protocol=1.0' \ 'https:///am/json/realms/root/realms/alpha/authenticate' { "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. 2. Invoke the authorization server's [/oauth2/authorize](oauth2-authorize-endpoint.html) 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**=`` For example: ```bash $ curl --dump-header - \ --cookie '=' \ --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=' \ --data 'redirect_uri=https://www.example.com:443/callback' \ 'https:///am/oauth2/realms/root/realms/alpha/authorize' ``` ```HTTP ... Location: https://www.example.com:443/callback#access_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. 3. Call the [/oauth2/userinfo](../am-oidc1/rest-api-oidc-userinfo-endpoint.html) endpoint to inspect the custom claim values, including the access token obtained from the previous request. For example: ```bash $ curl \ --request GET \ --header 'Authorization: Bearer ' \ 'https:///am/oauth2/realms/root/realms/alpha/userinfo' { "name": "Test User", "family_name": "User", "given_name": "Test", "custom_string": "Custom string", "custom_multivalue": ["value", "custom"] } ``` Verify the response contains the custom claims, `custom_string` and `custom_multivalue`, added by the script. ## 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 console, select Scripts > Auth Scripts > *Realm Name* > OIDC Claims Script, and replace the script content with your validated script.