Use-Case: We have a monolithic COTS ERP web application which may be extended by various add-on services, some of them are connected synchronously, some asynchronously with a (scheduled) callback.
Following Scott Brady's delegation patterns for OAuth 2.0 we rely on token exchange to adjust token type, token audience and as far as supported token scopes. Exchange from access_token to offline_access refresh token is essential to us.

Token-Exchange Variant: UC1, with keycloak being connected to LDAP, AD or Shibboleth

Description:
Our applications and keycloak/RHBK are exclusively run on-premise by customers themselves.
Examples of add-on services are scheduled reporting, data retrieval and maintenance jobs which are delegated by interactive users to the services.

Current implementation up to keycloak 22 works okay for us, but a more complete support of scope adjustments would be fine to enhance security. During next development cycle, we will move to keycloak/RHBK 24 and need to verify if #21578 breaks currently used addition of offline_access during exchange.

We welcome the long awaited focus on enhancing token exchange and promoting it to production level, as using a preview feature worries some customers. This got even more troublesome after token exchange was downgraded to developer preview in RHBK.

Use Case: Migration of refresh tokens during a migration to Keycloak
Token-Exchange Variant: UC3
Description:

Inspired by: https://dev.to/mohammedalics/seamless-migration-to-keycloak-refresh-token-4m4f

During a migration to Keycloak we want to be able to on the fly migrate refresh tokens issued by the previous system to a Keycloak refresh token.

Basic idea is that an API gateway would intercept the grant_type=refresh_token request and in the case of a token being issued by the old system the request is transformed to a grant_type=urn:ietf:params:oauth:grant-type:token-exchange request. This would then return a Keycloak refresh_token, that could be used from there on.

At the moment, to enable the exchange with a refresh_token, I had to implement a custom IDP as the default OIDC Provider currently only allows UC3 token exchange with an access_token. See this issue and my corresponding PR: #29313

Use case: Exchange user's access token for an offline access and refresh token.

UC1: Internal token to internal token

We want to provide offline API keys (not keycloak access or refresh tokens) to our platform users. We manage the keys in a client, and the user requests a token through a web interface integrated with our Keycloak auth. User access token is passed to client, which attempts to exchange it for an offline token for the same user. We store the offline access and refresh tokens and return a unique API key to the user. We then intercept offline requests including API keys and replace the API token with a valid access token.

This appears to have worked in previous versions of Keycloak (as reported by others online, I am new to Keycloak). The scope parameter no longer seems to affect anything when exchanging tokens (https://groups.google.com/g/keycloak-user/c/26cDt4q0kCc).

curl --location 'KEYCLOAK_URL/auth/realms/REALM/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=token-client' \
--data-urlencode 'client_secret=AAAAAAAAAAAAAAAAAAA' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token=eyJ...QNw' \
--data-urlencode 'scope=offline_access'

Response is a regular access and refresh token with "scope": "profile", whereas I would expect it to be an offline_access token.

Use case: Say you have one web client embed another in an iframe. You want to single signon.

Token-Exchange Variant: UC1

Description:
The outer app logs in, gets a token from keycloak. When embedding the child app, you call keycloak, pass it the redirect url back to the embeded app's oidc callback location, and params to token exchange the outer apps token for one to give to the child app. the child app still does code exchange to get its token, so the outer app never has it.

C3 variant:

End users log in via a third party IdP. The users can be company users or members of the public.

The end users use an application provided by the third party. The third party application calls our services and our services do token exchange by calling the token endpoint directly. There is no possibility to redirect the users to login again through our Keycloak.

For identification purposes, the access token from the third party only includes a third party internal id.

Company users already exist in our Keycloak and we need to be able to match the ID from the third party to our internal user. How user is matched from external access token to the internal user should be configurable when the token endpoint is called during the exchange.

Non-company users can be created on the fly during the token exchange.

To further elaborate the situation:

Employee of the company authenticates using the external IdP to an app provided by the 3rd party. The employees account already exists in Keycloak and should be matched to his/her existing account using information from the external access token. During the token exchange existing user information (groups, attributes, etc) can be used to map further roles to the access token.

Use case: Allow technical support team to impersonate end users

Token-Exchange Variant: UC2 + UC3 + UC4 ?

Description: The technical support team should be able to see the app as the end user would see it, so they can guide the user in using the app. This is a planned feature. We have not implemented it, because token exchange and fine grained auth are still preview.

• technical support team members have users in another realm in the same Keycloak instance as end users
• technical support team members may impersonate a subset of end users, based on some custom attribute (custom attribute of support team member must "match"a custom attribute of end user; "match" does not mean equal but common prefix or something like this)

We would like to implement something like

1. end user E calls technical support agent S
2. S logs in to administration SPA
3. S searches for E in a list and clicks a button like "impersonate" or "open support view"
4. S is redirected to end user SPA and is automatically logged in with an impersonated token of E

Use case: Exchange a trusted 3rd party IdP token for an access token for our API.

Token-Exchange Variant: UC3

Description: We need to authorise access to our API resources for services and users of our B2B client. The client does not want their services and users to access our Authorisation service directly, but via their API management service. This rules out OIDC and direct client credentials grants, so we are planning on their services and users authenticating with their own IdP(s) and then passing the tokens to our token exchange server via their API service.

@thomasdarimont, we are still in the design phase of this project and have been hesitant about committing to the Token Exchange flow due to its Preview status, so I am very glad to find this thread. You started the thread almost a year ago - would it be possible to have an update on the current status?
Many thanks!

Use-case

Delegation of Access Rights (f.x Power of Attorney within Healthcare)

Token-Exchange Variant:

UC1 / UC4

Description:

We have 2 scenarios that we are currently investigating both of which depend on RFC8693's definition of delegation semantics.

Parent - Child Relationship

On a high level, the Parent should be able to access their child's data and act on behalf of them. However, we do not want to simply impersonate as we need to know when actions are performed by the parent and when the actions are performed by the child. The delegation semantics outlined in RFC8693 almost perfectly fits this use-case as we can use the act claim for logging purposes.

i.e a Patient exchanges their JWT for another Patient JWT (both of which are generated by the same Keycloak realm, so internal -> internal token exchange)

Doctor - Patient Relationship

Again, on a high level, sometimes a doctor needs to perform a limited set of actions on behalf of a patient (for example, in case of an emergency or in case of non-tech-savvy users). Once again, we can utilize RFC8693 to generate a token that represents the patient with a limited set of scopes (hence simplifying the resource server code) while using the act claim to identify who is performing the action.

i.e a Doctor exchanges their JWT for a Patient JWT (both of which are generated by the same Keycloak realm)

We currently have a proof-of-concept running using the Token Exchange & Authorization Services features, however are a bit hesitant on using them in a production setting due to the preview status of both features.

As a sidenote, the token exchange implementation (at least on KC25.0.1) is different than the one outlined in the RFC, is the intention to keep it as is or would the required form parameters change to be more in line with the RFC?

Use case: Exchange an external token for an internal token, so we can add permissions to the (internal) token

Token-Exchange Variant: UC3

Description: Our keycloak works as a trustbroker for an external IDP which is used by the users of our web applications to login. Our keycloak adds the permissions to the token, so our applications and webservices can authorize the user requests by simply checking the permissions present in the token.

Our users also work with other (third party) web applications which use the same external IDP for their login and these applications want to access our webservice. So, we want to use the token exchange feature to exchange the tokens of the external IDP with our own Keycloak tokens.

The current token exchange feature provides all we need and our setup works as expected (with KC 25.0.6), but we are reluctant to use the token exchange feature in production as long as it is still a preview feature. We fear that the token exchange feature might change or even disappear leaving us with many users not able to use our webservices anymore.
(by the way: would this risk be reduced if we used the TokenExchangeProvider to implement our own token exchange functionality? Or, is the TokenExchangeProvider also considered as "preview"?)

Use case: Exchange a trusted 3rd party IdP token for an access token for our API using JWT only

Token-Exchange Variant: UC3

Description: I have successfully implemented token exchange, accepting the JWT of a trusted external provider to exchange for an internal token (our use case is a customer opt-in where they add our keycloak instance as Identity provider)

Now at the moment, this connection is only possible, when our Identity provider creates a confidential client, which will be used by the customers IdP, as there only exist these authentication methods:

Now I wonder - why is it not possible to configure, to trust the external IdP solely by accepting a JWT Token with configured issuer and loading the remote JSON web key set. This is a common scenario for JWT authentication, and it would ease setting up such a combination, as the parent IdP would not need to know about the other keycloak instance.

So e.g.

https://customer.keycloak.info (CKI) configures https://our.keycloak.info (OKI) as Identity Provider, just by trusting JWT tokens with issuer https://our.keycloak.info/realm/master and loading the verification token from https://our.keycloak.info/realm/master/protocol/openid-connect/certs (other rules like required claim etc, should apply)

Use case:
Exchange a token issued to Backstage as the audience with fresh tokens with the respective services that Backstage needs to call as audiences (audience exchange), ensuring each service call made in Backstage processes happens in the user context.

Token-Exchange Variant: UC1

Description: (c.f. #31553 (comment)) With the legacy token exchange, it was possible to issue tokens with a very narrow audience, e.g. issuing a token to a frontend client and including a backend as an additional audience. In that setup, when the frontend made a request to the backend, the backend could exchange the token to request another service.

Importantly, the downstream service did not need to be present in the initial token’s audience claim. We could rely on fine-grained permissions to control access effectively.

With the standard token exchange, however, it seems we can only "down-audience" a token (restrict it further) but not entirely change the audience. This makes certain use cases difficult to support.

In particular, if a client already possesses a broadly scoped token, there is little incentive for the client to perform a token exchange. On the other hand, if tokens were issued with a narrower audience from the beginning, an IAM system based on Keycloak could enforce token exchange to progressively obtain broader access - resulting in a more secure and manageable ecosystem.

With downscoping only, the initiating requester needs to know all audiences in advance (e.g. when a user logs into Backstage) and downscope the token downstream when Backstage calls these services, creating challenges to implement this in a setup with distributed responsibilities.

Ideally, Keycloak can manage token exchange policies to map the Backstage aud to the respective service auds, allowing for centralized governance.

I'm working on a use case. Currently, I request the organization scope while asking the user to log in, and Keycloak shows a UI after the login for the user to select one specific organization. Once the user selects the organization, the org information is added to the access token. Now, I want to know how to exchange the organization for the user, For example user switch from org A to org B. Does Keycloak provide a API interface where we can send the access token along with the new org code to get the access token for the requested org?

I assume it's not possible, We would need to build a flow somehow inside Keycloak and redirect the user back to Keycloak to change the org. (If we have to redirect the user to keycloak, This will not provide good user experience in the mobile app, Since we have to Open In App Browser)

I have a service which has a web app and a mobile app. Both of these clients are "public", i.e. they don't require a client-secret.

I created two separate clients 'web' and 'mobile' because that seemed like the right thing to do at the time. I suppose the advantage of that is that the session are separated and things like token times and whatnot can be configured independently.

However, I'd like to be able to link from the web into the mobile app, and be magically already authenticated there (perhaps vice versa too).
It's surely a bad idea to pass the refresh token via query parameter in the deep-link in both of those cases.

Is there a way to accomplish that properly?

Is using OAuth 2.0 Device Authorization Grant the answer? Should I have the authenticated client generate a code and pass that throught he deep link and let the other client get authenticated that way?

If so, how can I get the client to be different? This affects the azp field, right? The azp field is going to be wrong for the other client if I don't manage to do exchange at the same time.

I headed down the token exchange path thinking that UC1 (above) was the answer with Standard Token Exchange now implemented. But AFAICT, token exchange isn't even possible with both clients being public. I presume token exchange changes the azp.

So, two questions I guess (hoping for a singular solution) 1) how to safely get authentication across via deep link to/from the mobile or web apps. and 2) how to get the azp field also to change.