Token-Exchange Use-cases #26502
Replies: 26 comments 23 replies
-
|
Use case: Our token exchange use case is being able to exchange a token from SAML to OAuth/OIDC and then exchange back to SAML. The flow would be to initiate SAML Session with Keycloak, token exchange from internal SAML client to internal OAuth/OIDC client, and token exchange back from internal OAuth/OIDC client to the SAML client. Token-Exchange Variant: I assume UC1 from the description above Description: Then during this SAML session the user wishes to transfer to one of our newer services that only uses OAuth/OIDC, perform some actions logged in as a the same user from the SAML session, and then transfer back to the original SAML application. As it currently stands, when a user is authenticated with SAML but wishes to transition to the other application that needs OAuth they either need to log-in again on that system (creating two sessions) or we need to do a token exchange from SAML to OAuth/OIDC. The issue here is that currently as per the securing apps documentation here the reverse exchange from OAuth to SAML is not yet supported. |
Beta Was this translation helpful? Give feedback.
-
|
Not really following this use-case. Are you saying you have an application that authenticates a user with SAML, and the application needs to invoke a REST API with an access token? Why do you need the reverse exchange from OAuth back to SAML? |
Beta Was this translation helpful? Give feedback.
-
|
Also don't understand this use-case. IMO it makes sense to support token exchange for exchange SAML assertion of client1 to OIDC tokens of client2. This is not supported yet in current Keycloak. Wouldn't it be sufficient for your use-case? If I understand correctly, when client1 exchanges SAML assertion to OIDC tokens of client2, client1 can invoke backend service of client2 with it's tokens. Then once it receives data from client2, client1 would be able to consume this data. Per my understanding, there is no need to exchange also OIDC tokens of client2 back to SAML assertion of client1? |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Our primary use case for token exchange is to empower entities, such as OAuth clients or OAuth resource servers, to replace an access token (which may have been issued for a different client) with a new token specifically tailored or more narrowly scoped for downstream services. In this context, the entity initiating the token exchange, referred to as the client in RFC 8693: Token Exchange, can request a fresh access token with a scope better aligned to the specific requirements of the downstream service. Token-Exchange Variant: UC1 Description: Things we believe that should be changed :
We agree that session for token exchange must be examined. We agree that how a client is allowed to execute token exchange is strange. However, a change in allowing client token exchange must be documented in the migration part (and ideally auto migrated). |
Beta Was this translation helpful? Give feedback.
-
|
Exactly the use-case UC1 is intended for; a resource server needing a different token when invoking downstream services.
Migration - it's a preview feature, so really any migration notes (or auto migration) is best effort and will only be considered if it's a relatively low hanging fruit. That's basically the whole point of preview features that we are able to make breaking changes, etc. |
Beta Was this translation helpful? Give feedback.
-
You could see the issue I have created in the token exchange epic. Proposed dedicated configuration state is logic for me.
Yes. As you can see from Request parameters for Token exchange](https://datatracker.ietf.org/doc/html/rfc8693#name-token-exchange-request-and-), audience request parameter is optional.
|
Beta Was this translation helpful? Give feedback.
-
|
What I read from the spec (https://datatracker.ietf.org/doc/html/rfc8693#section-2.1.1) is that the target audience may be influenced by audience, resource, and scope parameters; with Keycloak not supporting resource, and scope's being global rather than tied to individual clients; I would argue that Keycloak really should just require the audience param to be present, as otherwise there is no way to sensibly infer the target audience for a given token. |
Beta Was this translation helpful? Give feedback.
-
|
Use case: we have mobile App as Client A which authenticates user X and gets the access-token without launching a web browser. Token-Exchange Variant: UC1 Description: |
Beta Was this translation helpful? Give feedback.
-
|
Did you find an alternative solution for this problem? We also wanted to use token exchange for this use case, but have faced the same issues. |
Beta Was this translation helpful? Give feedback.
-
|
Waiting to be fixed in keycloak, mean time extended to custom implementation. |
Beta Was this translation helpful? Give feedback.
-
|
An alternative approach to this use-case is using a refresh request; you can basically do a authz code request with say |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Token-Exchange Variant: UC6 Description: |
Beta Was this translation helpful? Give feedback.
-
|
@dominikschlosser Thanks for this use-case. But I am not understand it very well TBH. You mentioned that "Exchange a refresh token for a short-lived action token" is the use-case, which works for you. However current Keycloak implementation supports just access tokens though as per https://github.com/keycloak/keycloak/blob/26.0.5/services/src/main/java/org/keycloak/protocol/oidc/DefaultTokenExchangeProvider.java#L168 ? Also I am not sure what exactly you mean by "framework support to determine the effective scopes and not just the provided sope param as string" . Can you please specify this use-case in more details possibly with some example (with the example of how you see the request and the final token to look like regarding scopes etc)? |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Token-Exchange Variant: UC3 Description: |
Beta Was this translation helpful? Give feedback.
-
|
Since you are configuring the external IdP as the default IdP provider I would assume your apps are authenticating via Keycloak, and not directly via the external IdP? If so why do you need to exchange the external token for an internal one? |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Internal token to external token exchange with an identity provider We have also other UC1 use cases similar to responses above so I just upvoted them. < 1E0A /td> |
Beta Was this translation helpful? Give feedback.
-
|
For internal token to external token; have you considered using the Identity Brokering APIs (https://www.keycloak.org/docs/latest/server_development/index.html#retrieving-external-idp-tokens). To me that seems a more natural API to obtain the stored tokens than token exchange, as we're really not talking about an exchange, but rather just a way to obtain the stored tokens. |
Beta Was this translation helpful? Give feedback.
-
|
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. Token-Exchange Variant: UC1, with keycloak being connected to LDAP, AD or Shibboleth Description: 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. |
Beta Was this translation helpful? Give feedback.
-
|
Use case: We have a web application with optional peripheral features, think IoT devices. The process of adding the IoT device involves authenticating with the main web application (using a client just for the web) and then needing to obtain an offline refresh token (for a different client) to give to the IoT device so it can function thereafter. Token-Exchange Variant: UC1 (it would seem) Description: Having just discovered this feature being available (see #28945), I've yet to try this out. Will return with results. The previous comment would seem to indicate it should work for us. |
Beta Was this translation helpful? Give feedback.
-
|
Have you also checked if using simple SSO (i.e. if you use a web application and a mobile app on the same device, the user won't have to reauthenticate when the same system browser is used) and/or the device code grant (see https://datatracker.ietf.org/doc/html/rfc8628) apply to your case? |
Beta Was this translation helpful? Give feedback.
-
|
If I understand the use-case correctly you don't need token exchange for that; simply do a authz code flow from the web application with scope=offline and you'll get a refresh_token that is disconnected from the session that can be passed to the IoT device. |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Token-Exchange Variant: UC1 Description: Due to both of the client being public client, the backend for client A, which has its own confidential client, will be involved in exchanging the token. |
Beta Was this translation helpful? Give feedback.
-
|
Why not just do authz code flow with the system browser? That would enable SSO between the apps, and not require the user to re-login? Seems simpler than trying to use token exchange for this purpose. |
Beta Was this translation helpful? Give feedback.
-
|
The app uses offline tokens, so if the browser session has expired for the user (which is quite likely), they would need to sign in again when switching over to the embedded application (client B), even though they have a valid token. Using token exchange allows us to use the users valid token for client A to get a token for client B without ever asking the user to sign in again when they have a valid token. From the users perspective they are just navigating to a different section of the application, but technically it's a different application and code base, so I think it'd lead to a poor user experience if we suddenly ask them to login again when navigating to a different section of the application. |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Private application authorised to act on behalf of a user on a public app. A user ( A specific process manager( Passing along |
Beta Was this translation helpful? Give feedback.
-
|
Allow P to impersonate any user sounds like a terrible idea from a security perspective; reasonable standard use-case to be able to have an async service do some callback within a context onbehalf of a specific user though. I'm thinking along the line of being able to get a disconnected token, with a longer expiration, and a very specific set of claims/scopes that can reduce what P can do with the token. |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Impersonate specific user to do some work in the name of the impersonated user. Using In an existing application, this was done using multiple accounts. The assistant would have multiple account access and will authenticate using the correct "boss" account to do the expected work. With the complete rework of the application, the security was reviewed and instead of using multiple accounts, the assistant will only have one account (its own one) and some permission to impersonate users belonging to a specific list. The UMA approach was discarded because of the complexity: the targeted user would have to managed the rights while it was unecessary when using impersonation. The accepted solution is the following:
The whole process can be described as the following:
|
Beta Was this translation helpful? Give feedback.
-
|
@gdelbos , Is this something that you have implemented currently using Keycloak ? If yes, could you provide some details on how you have implemented it ? Thanks. |
Beta Was this translation helpful? Give feedback.
-
|
Hi @porobd , What do you mean by using Keycloak? The configuration done for the token exchange or the way the user will do the exchange? If it's the way the user will do the exchange: it's not done on Keycloak. We are using Keycloak OIDC features (authentication and token exchange) as well as Keycloak Admin REST API features (list users). The usage of those features is part of a SPA. If it's the configuration done on Keycloak, I'll try doing an export of a sample realm with the complete configuration as well as some request regarding the usage. This will be more clear than a wall of text. |
Beta Was this translation helpful? Give feedback.
-
|
Here are three files. impersonate-realm.json The two first file can be imported either using The realm is configured with the following:
|
Beta Was this translation helpful? Give feedback.
-
|
Use Case: Migration of refresh tokens during a migration to Keycloak 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 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 |
Beta Was this translation helpful? Give feedback.
-
|
Use Case: multiple backend systems by different companies combined in a single app We do not want to reconfigure our backend services to accept tokens from the customers keycloak. Also the format of those tokens is not compatible with the format of the tokens generated by our internal keycloak. But the enduser should also not have to trigger a new log in with our keycloak to get tokens compatible with our backend. That's why we want to do the following:
That would allow us to accept only tokens signed by our keycloak in the backend while still providing a nice user experience with even though the app uses multiple backends built by different companies. For legacy reasons we would also use UC6 to be able to connect with custom non OIDC compliant authentication providers. |
Beta Was this translation helpful? Give feedback.
-
|
we have the same usecase (although the keycloak is not from different companies, just different branches of our company) |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Internal token to internal token |
Beta Was this translation helpful? Give feedback.
-
|
@bradhead I think this issue is because Keycloak is possibly using incorrect client for creating clientSession when using token exchange. For example when you send token-exchange request with the client |
Beta Was this translation helpful? Give feedback.
-
|
yes, I think so, I have to go back and re-run the scenario. But I believe the issue was I was setting the 'aud' to be service1.. i.e. the target resource server is authenticating, passing in a bearer token intended for a different audience, and so client credentials auth and the 'aud' are both the resource server client. However, when service1, the RS, then attempts to introspect the new bearer token, the introspection fails due to lack of session for the new target client. I have not confirmed this on KC 25, or 26. As I belie this was from KC 24.x. |
Beta Was this translation helpful? Give feedback.
-
|
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). Response is a regular access and refresh token with |
Beta Was this translation helpful? Give feedback.
-
|
Use case: Say you have one web client embed another in an iframe. You want to single signon. Token-Exchange Variant: UC1 Description: |
Beta Was this translation helpful? Give feedback.
-
|
Dear Team, I have successfully implemented token exchange using standard OAuth 2 tokens, but I now need to perform a token exchange with a SAML assertion. Unfortunately, I couldn’t find any documentation regarding SAML. Therefore, I’m posting my query in this group. Could you please provide the steps or guidelines for this? |
Beta Was this translation helpful? Give feedback.
-
|
@krishnakumarakurathi Do you mean you want to exchange SAML assertion of |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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.
We would like to implement something like
|
Beta Was this translation helpful? Give feedback.
-
|
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? |
Beta Was this translation helpful? Give feedback.
-
Use-caseDelegation 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 RelationshipOn 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 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 RelationshipAgain, 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 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 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? |
Beta Was this translation helpful? Give feedback.
-
|
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. |
Beta Was this translation helpful? Give feedback.
-
|
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) |
Beta Was this translation helpful? Give feedback.
-
|
Use case: 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. |
Beta Was this translation helpful? Give feedback.
-
|
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) |
Beta Was this translation helpful? Give feedback.
-
|
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). 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. |
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Keycloak has been supporting the OAuth RFC 8693: Token Exchange feature for many years; however, since its inception, it has remained a technology preview feature. Following many requests from the community and customers, the Keycloak team is committed to getting token exchange out of preview.
To do so, we need to align the token exchange implementation in Keycloak with the official RFCs, which might involve user-facing changes. Since the Keycloak implementation deviated from the standard, we need to know which functionality to keep for compatibility.
Note that besides the built-in Token Exchange functionality, Keycloak also allows to customize token exchange mechanics via the
TokenExchangeProviderinfrastructure.Token Exchange Use Cases
Keycloak currently supports the following token exchange use cases:
UC1) Internal token to internal token exchange
A client can exchange an existing Keycloak token created for a specific client for a new token targeted to a different client.
UC2) Internal token to external token exchange
A client can exchange an existing Keycloak token for an external token, i.e., a linked Facebook account.
UC3) External token to internal token exchange
A client can exchange an external token for a Keycloak token.
UC4) Impersonation
A client can impersonate a user if the subject token is available
UC5) Direct Naked Impersonation
A client can impersonate a user without requiring the subject token
UC6) Custom
Custom Token Exchange with the
TokenExchangeProviderSPIDiscussion
Let's focus on practical OAuth Token Exchange usage and implementations with Keycloak. This discussion aims at sharing insights and exploring diverse use cases. We're also eager to learn about the use-cases that required customizations to the TokenExchangeProvider SPI.
Participants are encouraged to contribute with the format:
Use case: [Name your Use case]
Token-Exchange Variant:
Description: [How you use token exchange]
We are looking forward to a rich exchange of ideas and experiences.
Beta Was this translation helpful? Give feedback.
All reactions