Identity Cloud

Configure AM for token exchange

To configure AM for token exchange, perform the following tasks:

Task Procedures

Create at least one script of the type OAuth2 May Act, and configure it in the OAuth 2.0 provider service.

This script adds the may_act claim to the issued tokens.

Create a may_act script

Configure the OAuth 2.0 Provider to let clients exchange tokens.

Configure the OAuth 2.0 provider for token exchange

Configure the client profiles for token exchange.

Configure clients for token exchange

Create a may_act script

AM provides a script of the type OAuth2 May Act to add the may_act claim to tokens. Select the script in the OAuth 2.0 provider service.

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

Follow these steps to create a new script and to configure it in the provider service:

  1. In the Identity Cloud admin UI, go to Scripts > Auth Scripts and click + New Script.

  2. Select OAuth2 May Act and click Next.

  3. Name the script, for example, Test May Act Script and add the script body.

    The following JavaScript adds a may_act claim for delegation and, possibly, impersonation. The may_act claim contains a client ID and a subject name:

    (function () {
    var frJava = JavaImporter(
        org.forgerock.json.JsonValue
    );

    var mayAct = frJava.JsonValue.json(frJava.JsonValue.object());
    mayAct.put('client_id', 'serviceConfidentialClient');
    mayAct.put('sub', 'bjensen');

    token.setMayAct(mayAct);
    // No return value is expected. Let it be undefined.
}());

    Your script can perform additional tasks, as required, but it must add the may_act claim to the tokens. For details of the variables available to this script, see Token exchange scripting API.

    AM adds the may_act claim to access tokens, ID tokens, and refresh tokens that meet the criteria established in the script.

    There is no default functionality to configure token exchange for specific clients. If you need to do this, 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 a client_id. In delegation cases, it must also contain a subject (sub). The client_id and sub can have either scalar or array values, for example:

    "may_act": {
   "client_id": [ "myAppClient", "myOtherAppClient" ],
   "sub": "bjensen"
}

    The subject (sub) field specifies the ID of the user or identity, or the name of the OAuth 2.0/OpenID Connect client that is the subject of the token.

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

    • The client that makes 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 from other subject IDs are rejected.

    The following sections will use the values shown in the sample script, in the token exchange example calls.

    To add multiple values to one of the fields, declare the value of the field as an array. For example, mayAct.put('sub', ['bjensen', 'scarter']);

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

    You cannot specify the token type (access or ID) in the script. Instead, configure that in the OAuth2 Provider service (as shown further in this procedure).

  4. Save your changes.

  5. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider and select the Core tab.

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

    • 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.

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

  6. Save your changes.

Configure the OAuth 2.0 provider for token exchange

  1. In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider and select the Advanced tab.

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

  3. Review the Token Exchanger 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. Exchanger plugins exchange subject and/or actor tokens for new tokens.

    You can remove any plugins you don’t want to allow. For example, you might remove the ID token to ID token exchanger plugin. To add the plugins again, click in the field. The UI displays the list of plugins you can add.

  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.

Configure clients for token exchange

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. In the Token Exchange Auth Level field, enter the authentication level that AM should grant to access tokens generated as a result of token exchange, when the subject token has 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.

    You are now ready to test the Token exchange flows.

Copyright © 2010-2022 ForgeRock, all rights reserved.