How To
ForgeRock Identity Cloud

How do I include additional profile attributes in the OAuth 2.0 Access token in Identity Cloud?

Last updated Apr 14, 2022

The purpose of this article is to provide information on including additional profile attribute values in the OAuth 2.0 Access token. This can be achieved by adding profile fields to the Access Token Modification script in ForgeRock Identity Cloud. This article uses the extension attributes provided in Identity Cloud (such as frIndexedString1 or frIndexedMultivalued1) to add the profile fields to the Access token.


Overview

This article demonstrates how you can output additional profile attributes in the Access token by adding profile fields to the Access Token Modification script. This article uses the extension attributes within Identity Cloud but the same principles apply to other identity attributes. 

To include any identity attributes, you must use the equivalent AM attribute name in the Access Token Modification script. For example, for the extension attributes frIndexedString1 and frIndexedMultivalued1, you would use fr-attr-istr1 and fr-attr-imulti1 respectively in your scripts:Display Name                | IDM Property           | AM Attribute ------------------------------------------------------------------------  Generic Indexed String 1      | frIndexedString1       | fr-attr-istr1 Generic Indexed Multivalue 1  | frIndexedMultivalued1  | fr-attr-imulti1

See User Identity Attributes and Properties Reference for mapping details.

Steps involved

  1. Create a custom Access Token Modification script
  2. Update the OAuth 2.0 client
  3. Validate the Access token contains the profile fields

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have an existing OAuth 2.0 client in Identity Cloud for use with the OAuth 2.0 Provider. See Applications for further information.
  • You have populated the additional profile attributes for relevant users. The profile fields will not be included in the Access token unless the corresponding attributes are populated.
Note

Writing scripts for modifying the Access token is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Creating a custom Access Token Modification script

  1. In the Identity Cloud admin UI, go to Scripts > Auth Scripts > OAuth2 Access Token Modification Script.
  2. Click the menu and select Duplicate.
  3. Enter a unique name for your script and optionally a description.
  4. Add the profile fields you want to include in the Access token to the script. You should add these fields near the top of the script and make sure they are not commented out. For example, the following script addition adds profile fields to the Access token, including default ones and custom ones (called customMulti and customProfile) that use the extension attributes: // Adds additional profile fields to the Access token. accessToken.setField('name', identity.getAttribute('cn')); accessToken.setField('given_name', identity.getAttribute('givenName')); accessToken.setField('family_name', identity.getAttribute('sn')); accessToken.setField('mail', identity.getAttribute('mail')); accessToken.setField('phone', identity.getAttribute('telephoneNumber').toArray()[0]); accessToken.setField('customMulti', identity.getAttribute('fr-attr-imulti1')); accessToken.setField('customProfile', identity.getAttribute('fr-attr-istr1'));
  5. Click Save and Close.

Updating the OAuth 2.0 client

  1. In the Identity Cloud admin UI, go to Native Consoles > Access Management > Applications > OAuth 2.0 > Clients and click the name of your OAuth 2.0 client.
  2. Select the OAuth2 Provider Overrides tab and select the custom OAuth2 Access Token Modification script you created above in the OAuth2 Access Token Modification Script field.
  3. Click Save Changes.

Validating the Access token contains the profile fields

  1. Initiate the flow by navigating to a URL such as the following in a browser using Incognito or Browsing mode: https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/authorize?client_id=<client_id>&response_mode=form_post&response_type=code&scope=openid%20profile&redirect_uri=https://httpbin.org/anything
  2. Authenticate as an end user.
  3. Allow access to your personal information when prompted for consent.
  4. Copy the authorization code returned in the browser, for example:"form": {   "client_id": "<client_id>",      "code": "8xjrUVHHR5i5t_Fkpp3UUr6NBJ8.spkaJhs1d63p7qILFOVrHGaAlp8",  ...
  5. Exchange the authorization code for the access_token:$ curl --location --request POST 'https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=authorization_code' \ --data-urlencode 'code=<authorization-code>' \ --data-urlencode 'client_id=<client_id>' \ --data-urlencode 'client_secret=<client_secret>' \ --data-urlencode 'redirect_uri=https://httpbin.org/anything'

See Identity Cloud Postman Collection for further information.

  1. Copy the access_token returned (do not copy the entire response as that also includes the id_token).
  2. Introspect the access_token to verify the profile fields are included. For example (using jq to prettify the response for readability - you can install jq as outlined in Download jq):$ curl --location --request POST 'https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/introspect' \ --data-urlencode 'client_id=<client_id>' \ --data-urlencode 'client_secret=<client_secret>' \ --data-urlencode 'token=<access_token>' | jq .Example response showing the additional profile fields included (including the custom ones called customMulti and customProfile in this example):{  "active": true,   "scope": "openid profile",   "realm": "/alpha",   "client_id": "<client_name>",   "user_id": "bddb135d-f6b7-4933-bb9e-525d436d48bb",   "username": "bddb135d-f6b7-4933-bb9e-525d436d48bb",   "token_type": "Bearer",   "exp": 1649179127,   "sub": "bddb135d-f6b7-4933-bb9e-525d436d48bb",   "subname": "bddb135d-f6b7-4933-bb9e-525d436d48bb",   "iss": "https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha",   "auth_level": 0,   "authGrantId": "lNBvCkjpNNLOilKWpEpYL8U21IY.ANEyNZiZrkDQZImw8hC1juQz9EE",   "auditTrackingId": "070f4e34-eed8-43f9-908c-d68c0da8d717-166028",   "mail": [     "jdoe@example.com"   ],   "phone": "01234567890",   "customMulti": [     "test1",     "test2"   ],   "name": [     "Jane Doe"   ],   "customProfile": [     "test"   ],   "given_name": [     "Jane"   ],   "family_name": [     "Doe"   ] }

See Also

How do I include additional profile attributes in the OIDC ID token in Identity Cloud?

Access token modification plugin


Copyright and Trademarks Copyright © 2022 ForgeRock, all rights reserved.