Configuring and using token exchange

Consider this typical token exchange flow:

Many other use-cases exist for token exchange, but the preceding example is the most typical.

For standard token exchange, token-exchange-standard:v2 is enabled by default. However, you also need to enable the Standard token exchange switch for the client that is supposed to send token exchange requests, such as the requester-client from the previous example. Note that requester-client must be a confidential client. Also, as is the case for other grant requests, the token exchange requests must be authenticated by the appropriate client authentication method that is configured for the client.

The parameters are aligned with the Token exchange specification, which are described as follows:

A successful response is returned in the JSON format. It contains similar parameters such as the response from other grants. The following are some token exchange specifics of the more notable parameters:

The scope parameter in the token exchange request has the same meaning as other grants. This parameter is optional. When it is omitted, the effective client scopes used in the request are the Default client scopes of the requester-client. When this parameter is used, the effective client scopes are the default scopes together with the Optional client scopes

By default, the used client scopes will add the audiences to the aud claim of the token based on the used client scopes and client roles as specified in the Audience documentation.

The audience parameter can be used for filtering of audiences, so that the aud claim will contain only the audiences specified by the audience parameter. Similarly the client roles in the token will be filtered and the token will have only the client roles of the clients specified by the audience parameter.

In addition, the audience parameter can be used to potentially filter client scopes as well. It works in a manner that is similar to Client scope permission for users. If the client scope does not contain any client roles (for example, it contains zero roles or it contains only realm roles), no additional filtering occurs for client scopes. However, if the client scope contains any client role mappings, it must include some client roles of the clients requested by the audience parameter. Composite roles are also included for consideration. If the client scope contains no client roles of the clients requested by the audience, the client scope will be filtered.

These additional points clarify the behavior of token exchange.

While the preceding sections fully detail standard and legacy token exchange, the following is an overall summary that compares the two token exchange methods.

The specification describes two ways one party can act for another. Suppose Alice, the subject, wants a calendar app, the actor, to book meetings for her:

Keycloak implements delegation, through the may_act and act claims.

Handing the user’s own access token to the actor, whether that actor is another user or a client application, is impersonation in effect, and it has significant drawbacks:

Delegation addresses all of these. The delegated token is issued with the audience and scopes of the requesting client, the client that performs the exchange, narrowing it to only what that client needs. In client delegation, the requesting client is the actor itself. The act claim provides a clear audit trail, and the user must explicitly consent to the delegation.

Keycloak supports two kinds of actor.

This feature requires the parameterized-scopes feature to be enabled. To enable both features, start Keycloak with:

When the feature is enabled, the delegation client scopes (delegation:user and delegation:client) are automatically created in all realms (new and existing) as Optional client scopes, making them available to all clients by default. No manual client scope assignment is needed.

The client requesting a delegation scope must have Consent required enabled. The delegation scopes are marked as always requiring consent, and Keycloak rejects a request for such a scope from a client that does not require consent. The delegation consent is never stored permanently, so the user approves the delegation on every login session.

Delegation also requires granting a delegation permission through Fine-grained admin permissions version 2 (FGAP V2). Without a matching permission granting the delegate scope, the delegation scope is silently dropped from the request and the may_act claim is not included in the token. The login itself still succeeds.

Unlike impersonation, delegation does not use admin roles. Instead, you configure FGAP V2 permissions to control which actors can be delegated to and for which users.

Admin delegation allows a user (subject) to delegate their token to an administrator (actor). The client requests the delegation:user scope with the administrator’s identifier as a parameter using the parameterized scopes syntax.

Client delegation allows a user (subject) to delegate their token to a client application (actor), such as an AI agent or automated service. The client requests the delegation:client scope with the actor client’s identifier as a parameter using the parameterized scopes syntax (for example, delegation:client:actor-app).

Unlike admin delegation, which is designed for human administrators, client delegation is designed for application-to-application scenarios where a user consents to let a specific client act on their behalf. The actor client does not need any admin roles or access to the Admin REST API.

Once the subject’s token carries a may_act claim, the actor performs the actual exchange at the token endpoint. This step is the same for admin delegation and client delegation. Only the contents of the may_act claim differ.

The actor_token is an ordinary access token belonging to the actor. Keycloak resolves the user behind it and treats the request as client delegation when that user is a service account, and as admin delegation otherwise. For client delegation, the actor client obtains the token for its own service account with the client_credentials grant:

For admin delegation, the actor token is the administrator’s own access token, obtained through whichever flow they normally log in with.

The actor then sends both tokens: the subject’s token as the subject_token and its own token as the actor_token. The actor client is confidential, so it authenticates itself on this request as well. The following example uses client_secret_post, but the other client authentication methods work too.

The delegation flow uses the following parameters:

Keycloak then validates both tokens following the delegation semantics of RFC 8693. Unless stated otherwise, a failed check returns 400 Bad Request with the invalid_request error and a description of what failed.

The delegated token is issued in a transient session, so no refresh token is returned and the token carries no session identifier. It contains the act claim built from the subject token’s may_act claim.

The delegation client scopes enforce the permission check and the user consent before adding a may_act claim. A claim with that name can reach a token by other routes though, such as a Hardcoded claim protocol mapper set directly on a client. That claim never passed either check, yet the exchange endpoint would honor it.

The may-act client policy executor closes this gap. It re-validates any may_act claim it finds in a token response, whatever produced it: the issuer must match the realm, the sub must be an existing enabled user other than the token’s own user, that user must hold the delegate permission, and the matching delegation scope must have been consented. Tokens without a may_act claim are untouched, and tokens that fail are rejected with invalid_request.

Configure it under Realm settings → Client policies by adding the may-act executor to a profile and attaching that profile to a policy. All three options are off by default:

Delegation scopes fail safe. If the actor is not authorized, the scope is dropped during scope resolution and the login still succeeds, only without a may_act claim in the token.

A dropped scope is always logged on the server at the WARN level, with the reason:

Two constraints are easy to miss: delegation:user cannot name a service account, so use delegation:client for those, and neither scope can be requested twice with different values in the same request.

In Keycloak, token exchange is the process of using a set of credentials or token to obtain an entirely different token. A client may want to invoke on a less trusted application so it may want to downgrade the current token it has. A client may want to exchange a Keycloak token for a token stored for a linked social provider account. You may want to trust external tokens minted by other Keycloak realms or foreign IDPs. A client may have a need to impersonate a user. Here’s a short summary of the current capabilities of Keycloak around token exchange.

Token exchange in Keycloak is a very loose implementation of the OAuth Token Exchange specification at the IETF. We have extended it a little, ignored some of it, and loosely interpreted other parts of the specification. It is a simple grant type invocation on a realm’s OpenID Connect token endpoint.

It accepts form parameters (application/x-www-form-urlencoded) as input and the output depends on the type of token you requested an exchange for. Token exchange is a client endpoint so requests must provide authentication information for the calling client. Public clients specify their client identifier as a form parameter. Confidential clients can also use form parameters to pass their client id and secret, Basic Auth, or however your admin has configured the client authentication flow in your realm.

With an internal token to token exchange you have an existing token minted to a specific client and you want to exchange this token for a new one minted for a different target client. Why would you want to do this? This generally happens when a client has a token minted for itself, and needs to make additional requests to other applications that require different claims and permissions within the access token. Other reasons this type of exchange might be required is if you need to perform a "permission downgrade" where your app needs to invoke on a less trusted app and you don’t want to propagate your current access token.

You can exchange a realm token for an external token minted by an external identity provider. This external identity provider must be configured within the Identity Provider section of the Admin Console. Currently only OAuth/OpenID Connect based external identity providers are supported, this includes all social providers. Keycloak does not perform a backchannel exchange to the external provider. So if the account is not linked, you will not be able to get the external token. To be able to obtain an external token one of these conditions must be met:

Finally, the external identity provider must have been configured to store tokens, or one of the above actions must have been performed with the same user session as the internal token you are exchanging.

If the account is not linked, the exchange response will contain a link you can use to establish it. This is discussed more in the Making the Request section.

You can trust and exchange external tokens minted by external identity providers for internal tokens. This can be used to bridge between realms or just to trust tokens from your social provider. It works similarly to an identity provider browser login in that a new user is imported into your realm if it doesn’t exist.

When the exchange is complete, a user session will be created within the realm, and you will receive an access and or refresh token depending on the requested_token_type parameter value. You should note that this new user session will remain active until it times out or until you call the logout endpoint of the realm passing this new access token.

These types of changes required a configured identity provider in the Admin Console.

For internal and external token exchanges, the client can request on behalf of a user to impersonate a different user. For example, you may have an admin application that needs to impersonate a user so that a support engineer can debug a problem.

You can make an internal token exchange request without providing a subject_token. This is called a direct naked impersonation because it places a lot of trust in a client as that client can impersonate any user in the realm. You might need this to bridge for applications where it is impossible to obtain a subject token to exchange. For example, you may be integrating a legacy application that performs login directly with LDAP. In that case, the legacy app is able to authenticate users itself, but not able to obtain a token.

When granting clients permission to exchange, you don’t necessarily manually enable those permissions for each and every client. If the client has a service account associated with it, you can use a role to group permissions together and assign exchange permissions by assigning a role to the client’s service account. For example, you might define a naked-exchange role and any service account that has that role can do a naked exchange.

When you start allowing token exchanges, there are various things you have to both be aware of and careful of.

The first is public clients. Public clients do not have or require a client credential in order to perform an exchange. Anybody that has a valid token will be able to impersonate the public client and perform the exchanges that public client is allowed to perform. If there are any untrustworthy clients that are managed by your realm, public clients may open up vulnerabilities in your permission models. This is why direct naked exchanges do not allow public clients and will abort with an error if the calling client is public.

It is possible to exchange social tokens provided by Facebook, Google, etc. for a realm token. Be careful and vigilante on what the exchange token is allowed to do as it’s not hard to create fake accounts on these social websites. Use default roles, groups, and identity provider mappers to control what attributes and roles are assigned to the external social user.

Direct naked exchanges are quite dangerous. You are putting a lot of trust in the calling client that it will never leak out its client credentials. If those credentials are leaked, then the thief can impersonate anybody in your system. This is in direct contrast to confidential clients that have existing tokens. You have two factors of authentication, the access token and the client credentials, and you’re only dealing with one user. So use direct naked exchanges sparingly.