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 This script adds the |
|
Configure the OAuth 2.0 Provider to let clients exchange tokens. |
|
Configure the client profiles 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:
-
In the Identity Cloud admin UI, go to Scripts > Auth Scripts and click + New Script.
-
Select
OAuth2 May Act
and click Next. -
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. Themay_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 aclient_id
. In delegation cases, it must also contain a subject (sub
). Theclient_id
andsub
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).
-
-
Save your changes.
-
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. -
-
Save your changes.
Configure the OAuth 2.0 provider for token exchange
-
In the AM admin UI, go to Realms > Realm Name > Services > OAuth2 Provider and select the Advanced tab.
-
In the Grant Types field, add the
Token Exchange
type, if it is not already present. -
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. -
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.
-
Go to Realms > Realm Name > Applications > OAuth 2.0 > Clients > Client Name > Advanced.
-
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. -
In the Grant Types field, add the
Token Exchange
type. -
Save your changes.
You are now ready to test the Token exchange flows.