--- title: Configuring AM for token exchange description: To configure AM for token exchange, perform the following tasks: component: pingam version: 7.2 page_id: pingam:oauth2-guide:token-exchange-configuration canonical_url: https://docs.pingidentity.com/pingam/8.1/am-oauth2/token-exchange.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: may_act-script-token-exchange: Configure a new may act script configure-provider-token-exchange: Configure the OAuth 2.0 provider service for token exchange configure-clients-token-exchange: Configure clients for token exchange --- # Configuring 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. | [Configure a new may act script](#may_act-script-token-exchange) | | Configure the OAuth2 Provider to allow clients to exchange tokens. | [Configure the OAuth 2.0 provider service for token exchange](#configure-provider-token-exchange) | | Configure the relevant client profiles for token exchange. | [Configure clients for token exchange](#configure-clients-token-exchange) | ## Configure a new may act script AM provides a script of the type `OAuth2 May Act` to add the `may_act` claims 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 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. Your 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](scripting-api-may_act.html). Once configured, AM adds the `may_act` claim to the access tokens, ID tokens, and refresh tokens that meet 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. > **Collapse: 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: > > ```none > "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: ```groovy 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 AM will add the claim to. You configure that in the OAuth2 Provider service in a later step of this procedure. 3. 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: * 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. 7. Save your changes. ## Configure the OAuth 2.0 provider service for token exchange 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](token-exchange-flows.html). ## 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](../oidc1-guide/oauth2-dynamic-client-registration.html). 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](../authentication-guide/about-authentication-trees.html#authentication-levels-trees) that AM 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](token-exchange-flows.html).