Configuring Identity Cloud for Token Exchange

Identity Cloud provides a script of the type OAuth2 May Act to add the may_act claims to tokens. Select the script in the OAuth2 Provider service.

No additional configuration is required to add the act claim to token exchange delegated tokens. Identity Cloud automatically adds the claim as needed when issuing them.

Perform the following steps to create a new script and to configure it in the provider service:

1. Go to Realms > Realm Name > Scripts.

2. Create a new script of the type OAuth2 May Act. Name it, for example, Test May Act Script.

   Note that the new script has a comment with the different variables supported by the script. It also has example code to add a may_act claim containing a client ID and a subject name.

   You scripts can perform additional tasks as required, but must also add the may_act claim to the tokens. For more information about the variables available, see "Token Exchange Scripting API".

   Once configured, Identity Cloud adds the may_act claim to the access tokens, ID tokens, and refresh tokens that meet the the criteria established in the script.

   There is no built-in approach to configure token exchange for particular clients; if you need this functionality, either configure these clients in a specific realm/OAuth2 provider, or customize the script on a per-client basis.

   About the may_act Claim

   The may_act claim must contain the client_id object. In delegation cases, it must also contain the sub object. The objects may be formatted as a single entry, or as a collection. For example:

   "may_act": {
      "client_id": [ "myAppClient", "myOtherAppClient" ],
      "sub": "(usr!demo)"
   }

   About the Subject (sub) Object

   The subject claim is in the format (type!subject), where:

   • subject is the identifier of the user/identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

   • type can be one of the following:

     • age. Specifies that the subject is an OAuth 2.0/OpenID Connect-related user-agent or client. For example, an OAuth 2.0 client, a Remote Consent Service agent, and a Web and Java Agent internal client.

     • usr. Specifies that the subject is a user/identity.

   For example, (usr!demo), or (age!myOAuth2Client).

   The may_act claim acts as a condition for the authorization server to issue exchanged tokens, as follows:

   • The client making an impersonation or delegation token exchange request must be authorized in the may_act claim. Requests from other clients are rejected.

   • In delegation cases, the subject of the actor token must also be authorized in the may_act claim of the subject token. Requests coming from other subject IDs are rejected.

   The following Groovy code demonstrates using the may_act claim for delegation, and possibly impersonation:

   import org.forgerock.json.JsonValue
   
   token.setMayAct(
     JsonValue.json(JsonValue.object(
       JsonValue.field("client_id", "serviceConfidentialClient"),
       JsonValue.field("sub", "(usr!ForgerockDemo2)"))));

   The following sections will use these values in the token exchange example calls.

   To add multiple values to one of the fields, declare the second object of the field as an array. For example, JsonValue.field("sub", JsonValue.array("(usr!demo)", "(usr!demo2)")).

   There is no wildcard-like implementation to allow any client or subject to exchange a token.

   You cannot specify in the script the type of token (access or ID token) that Identity Cloud will add the claim to. You configure that in the OAuth2 Provider service in a later step of this procedure.

3. (Optional) Click on Validate to ensure the script syntax is correct.

4. Save your changes.

5. Go to Realms > Realm Name > Services > OAuth2 Provider > Core.

6. Specify the script as follows:

   1. In the OAuth2 Access Token May Act Script drop-down list, select Test May Act Script.

   2. In the OIDC ID Token May Act Script drop-down list, select Test May Act Script.

   You can use different scripts for OAuth 2.0 and OpenID Connect tokens but, for this example, use the same script. You can also enable token exchange for OAuth 2.0 flows only, or for OpenID Connect flows only.

   To disable token exchange for either OAuth 2.0 or OpenID Connect flows, select --- Select a script --- in the appropriate drop-down list.

   Identity Cloud does not add the may_act claim to tokens when a May Act script is not selected.

7. Save your changes.

1. Go to Realms > Realm Name > Services > OAuth2 Provider > Advanced.

2. In the Grant Types field, add the Token Exchange type if it is not already configured.

3. Review the Token Exchange Plugins and the Token Validator Plugins fields.

   Validator plugins ensure that the subject and/or actor tokens meet the criteria to be exchanged for other tokens. Exchange plugins exchange subject and/or actor tokens into new tokens.

   You may remove any plugins you do not want to allow. For example, you may remove the ID token to ID token exchange plugin. If you need to add plugins back, click on the field and the UI will show you the plugins you can add.

   If you decided to write your own implementations of the plugins, select them here, too.

4. Save your changes, if any.

   The OAuth 2.0 provider is now ready to exchange tokens. For more information and examples, see "Token Exchange Flows".

This procedure shows how to configure clients for token exchange using the AM Admin UI.

Token exchange is also supported for Dynamic Client Registration. Ensure that you provide the configuration explained in this procedure in the JSON representation of the client.

1. Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > Advanced.

2. (Optional) In the Token Exchange Auth Level field, enter the authentication level that Identity Cloud should grant to access tokens generated as a result of token exchange when the subject token had no auth_level claim. For example, when the subject token is an ID token.

3. In the Grant Types field, add the Token Exchange type.

4. Save your changes.

   Now you are ready to test the "Token Exchange Flows".