Token Exchange / Impersonation - Beta Feature
The Token Exchange grant implements RFC 8693, OAuth 2.0 Token Exchange and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation.
A typical use case is when customer support uses the token exchange to temporarily access a user’s account, allowing them to troubleshoot issues without needing the user’s password.
The whole documentation including some examples can be found in our Impersonation and delegation using Token Exchange guide.
Testing Period: till 31. March 2025
Testing Objectives:
- Did you encounter problems or bugs?
- Is the current permission model suitable? Do you need more?
- General feedback on feature enhancements
How to test:
- Enable the feature flag: https://zitadel.com/docs/guides/integrate/token-exchange#feature-api
- Follow the simple Token Exchange example: https://zitadel.com/docs/guides/integrate/token-exchange#simple-token-exchange-examples
- Or follow the impersonation example: https://zitadel.com/docs/guides/integrate/token-exchange#impersonation-examples
Known Bugs / Limitations:
At the moment token exchange is only implemented for your own applications, but not for getting access to a Zitadel Manager account.
Token exchange works for Zitadel created Tokens currently, in the future the possibility for external services will be added as well. Track the state in the corresponding issue.
Test the token exchange and add improvement or bug reports directly to the github repository or let us know your general feedback below!
RFC 8693: OAuth 2.0 Token Exchange
This specification defines a protocol for an HTTP- and JSON-based
Security Token Service (STS) by defining how to request and obtain
security tokens from OAuth 2.0 authorization servers,
including security tokens employing impersonation and delegation.
ZITADEL Docs
The Token Exchange grant implements RFC 8693, OAuth 2.0 Token Exchange and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation. This guide will explain how token exchange is implemented inside ZITADEL and gives some usage examples.
12 Replies
Having read the security warnings I’m kinda stuck as to how I’d handle token exchange on a PKCE React app
I’d like to have a superuser grant that can impersonate any user in an org and see the app as they would but don’t really know where to start,
ZITADEL allows any application to use Token Exchange, however we strongly recommend to only configure confidential clients (using either client credentials or JWT assertion) with the Token Exchange grant type. This is because there is some trust placed in the application when it comes to defining scope and that it obtained tokens in a legitimate way. For example, if the app possesses a token of an admin user with impersonation permissions it can obtain tokens for any other user in your instance. It is your responsibility to make sure the application can be trusted with this kind of powers. If you configure a public client with the Token Exchange grant, you risk a leaked token can be used by an attacker who knows the client ID of a granted public client.But then the guide talks about a portal app having token exchange enabled?
@muhlemmer @livio can you help here?
Unknown User•9mo ago
Message Not Public
Sign In & Join Server To View
Interesting - lots of rough edges to consider
Unknown User•9mo ago
Message Not Public
Sign In & Join Server To View
True that, given physical access is nearly as far as a keylogger
I’ll have a think about the risk tolerance here
Unknown User•8mo ago
Message Not Public
Sign In & Join Server To View
any idea when this is out of Beta?
hey @kappapilla I will check with my team, thanks
Hey! Just wanted to share that we’re actively using impersonation by user ID for kiosk authentication with badges in a closed network. It’s been a great fit for our use case, and I think this feature adds a lot of value.
Heya, thanks for the feedback! We're planning to move this out of beta in V5, however since we launched this (months ago), we haven't had a great deal of feedback from the community and therefore haven't made any plans to enhance the functionality. So if you're using it, do give us a shout with your thoughts 🙏
We want to use this for user support. But we need to know that the impersonated user is not a real user. There is the act claim in the token but we need some more information about the impersonator. Ideally we could add this to the token via the actions V2 preaccesstoken function.
Is there any way that to already see the act claim in the preaccesstoken handler? Or somehow pass information to that handler via required scopes or something?