OAuth 2.0 token exchange in authentik: when services need to act for a user
A backend service that holds a token from another provider or source often needs authentik access for the same user, but should not pass that original token along. In authentik 2026.8, OAuth 2.0 token exchange lets the service trade a token from a trusted provider or source for an authentik access token that represents the same user. On-behalf-of token exchange covers the related case where a service acts for the user in a downstream call. Both features are disabled by default and must be switched on under the provider's grant types before any application can use them.
Enabling the feature is a deliberate decision, not a toggle to flip during setup. Each provider that accepts exchanges needs a clear list of which upstream issuers and sources it trusts, which client may request the exchange, and what the resulting token is allowed to do. Confirm in the authentik 2026.8 release notes which grant types, source settings and token claims apply to your version, and test the exact exchange request your service will send against a non-production instance before you rely on it.
The same release added dynamic client registration and OpenID key binding for ID tokens. Dynamic client registration changes how clients are created, so your team should decide whether it is allowed at all, and who approves new clients if it is. Key binding ties ID tokens to a key, which affects how relying parties verify them and how you rotate keys. Plan both changes with the exchange feature, because each one alters the trust model that the exchange depends on.
Configuration options and when each fits
This table compares the five token exchange settings introduced in authentik 2026.8, covering when each one fits and what it costs in trust or operational complexity. Read each row as a separate decision, since the grant type setting is the gate for token exchange while the others refine who may exchange tokens and how ID tokens are bound.
| Option | When it fits | Trade-off to weigh |
|---|---|---|
| Grant type for token exchange on the provider | Enable only on providers whose client applications must swap an upstream token for an authentik access token for the same user | Off by default, so enabling it widens what a client can request; review each provider that turns it on |
| Trusted providers and sources as token origins | Restrict exchange to tokens issued by upstream identity providers or sources you already trust and have configured in authentik | Every trusted origin adds a token issuer you must govern, monitor and remove when retired |
| On-behalf-of token exchange | Services acting for a user, such as a backend calling a downstream API, need a token scoped to that user without passing the original token along | Confirm how the downstream audience and scopes are set in your release notes version, since delegation chains are harder to audit than direct logins |
| Dynamic client registration | Platform teams that onboard many short-lived or self-service clients and want them to register without manual steps in the admin interface | Clients can appear without a ticket, so pair it with approval policies and a regular review of registered clients |
| OpenID key binding for ID tokens | Relying parties that need to verify ID tokens against a specific signing key and want that binding enforced | Clients and key rotation procedures must support the binding, so test key rollover before enabling it broadly |
| Default configuration (none of the above) | Existing OAuth2 and OIDC applications that do not exchange tokens and need no change in behavior | Leaves the feature off, which is the safest starting point; confirm no existing client depends on the new options |
How to enable token exchange safely in authentik
This sequence takes a deployment from version check to verified token exchange, with each step limited to the trusted providers and sources that need it. The result is a tested configuration and an audit trail you can show a reviewer.
Confirm the deployment version
Check the running authentik version in the admin interface before changing anything. Token exchange was added in authentik 2026.8, so the deployment must run that release or another version listed as supported in the security policy. Confirm the exact supported versions in the security policy and the current release notes, since the project publishes security releases in advance and the supported list can change. The step is done when the version is recorded in your change ticket and matches a supported line.
Define permitted trusted providers and sources
Before enabling anything, list which upstream trusted providers or sources may present a token that authentik will exchange for its own access token, and which applications will call the exchange. Record the owner of each entry and the reason it needs exchange rather than a fresh sign-in. Use this list as the reference for the rest of the sequence. The step is done when the list is approved by the application owner and the security reviewer, and every entry names a specific source or provider.
Enable the grant type on required providers only
Open each OAuth2/OIDC provider that appears on the approved list and enable the token exchange grant type in its grant type settings. Leave the setting off on all other providers, because it is disabled by default. Do not enable it on a provider for convenience. The step is done when a provider export or the admin view shows the grant type on exactly the providers in your list and off everywhere else.
Configure on-behalf-of and key-bound settings deliberately
Decide whether each permitted flow needs on-behalf-of token exchange, dynamic client registration or key-bound ID tokens, since authentik 2026.8 added each of these. Enable only the features the approved applications use, and record the decision per provider. Confirm the behavior of each setting in the 2026.8 release notes before relying on it. The step is done when each provider's settings match the decisions in the change record.
Test with a real application and a test user
Using a non-production test user, run the calling application through the exchange path end to end. Confirm that the exchange succeeds for the intended user, that the returned access token has the expected scopes and audience, and that a request using a token from an unapproved provider or source is refused. Repeat the refused case for a second test user to rule out a user-specific result. The step is done when the expected success and failure cases both match the written test plan.
Review audit events and close the change
Check the event log for the test exchanges and confirm that each one records the user, the calling provider and the outcome. Compare the logged events with the test plan, and investigate any exchange that appears without a matching test. Store the events, the provider configuration export and the approved list together in the change record. Ask your security team to confirm the logging meets your audit needs. The step is done when the reviewer signs off on the evidence package.
Security risks to review before enabling exchange
Token exchange lets one application trade a token it received for an authentik access token, which widens who can obtain access and how long it lasts. The cards below cover the decisions that control that widening, from which upstream tokens are accepted to how exchanges are logged and how authentik is kept on a supported release.
Trust scope for upstream tokens
Exchange only accepts tokens from a trusted provider or source you have configured, so every trusted entry is a path to a new authentik token. Review each trusted provider and source, confirm who controls its signing keys, and remove entries that no longer have a live integration. Test with a token from an untrusted issuer and confirm authentik rejects it.
Least-privilege scopes on exchanged tokens
An exchanged token should carry only the scopes the receiving service needs, not the full scope set of the user's original session. Map each exchanging client to the scopes it may request, and check the resulting token's claims in a test environment before production. Grant types are off by default, so enable token exchange only on the providers that need it.
Key binding of ID tokens
OpenID key binding for ID tokens ties the token to the key the client holds, so a copied token is harder to replay elsewhere. Confirm that each relying party can validate bound tokens before you enable it, because a client that does not support the binding will fail at sign-in. Record which providers use binding so reviewers can see the setting.
Token lifetime and revocation after offboarding
An exchanged access token remains valid until it expires, so a leaver's access can persist after the account is disabled if lifetimes are long. Set token lifetimes deliberately, and test that deactivating a user and revoking sessions stops new exchanges and invalidates active tokens within your required window. Confirm this behavior with your own tests, not assumptions.
Logging of exchanges
Each exchange should leave an event that shows which client exchanged which upstream token, for which user, and what was issued. Without that record, an incident involving a downstream service cannot be traced back through authentik. Confirm the event fields in your version, forward them to your log platform, and set retention to match your investigation needs.
Staying on supported releases
Security fixes reach only the supported versions, and the project announces security releases at least 24 hours in advance. Plan a process that can apply a security release within that notice window, and keep a tested staging instance on the same version. Check the security policy page for which release lines are supported before scheduling any upgrade.
Questions teams ask before enabling token exchange
What does it cost to enable token exchange in authentik?
No fixed price applies, because cost follows the written scope. The main cost is consulting and engineering time, which depends on how many trusted origins (providers and sources that can submit tokens for exchange) you configure, how many downstream services request exchanged tokens, and how deep the testing goes. Software licensing is a separate line. The authentik pricing page lists an Open Source edition at no charge, and an Enterprise edition at $5 per user per month billed annually plus $0.02 per external user per month. Token exchange is available in the release notes for authentik 2026.8, so confirm with the vendor which edition your environment needs before you request a quote.
What drives the effort of a token exchange project?
Effort rises with the number of moving parts, not with the feature switch itself. The main drivers are the number of trusted origins, the number of downstream services that will receive exchanged tokens, how each service validates tokens, and the depth of testing you require. Each trusted origin needs its trust relationship, claims and audience rules reviewed. Each downstream service needs its own integration test. Ask for a quote that lists origins, services and test cases separately so you can see which item changes the price.
How long does a token exchange implementation take?
Duration depends on the scope you agree, and no general timeline applies. A small setup with one trusted origin and one downstream service differs greatly from a setup with several origins, on-behalf-of flows and staged rollouts. Ask for a schedule tied to the deliverables in the written scope, with named review and test milestones. Your internal change process and approval windows will also affect the calendar.
What must our team provide before the work starts?
Your team needs to provide four things: a current identity architecture description, including how users, groups and existing providers relate; access to the upstream providers and sources that will be trusted; a set of test users with the roles and groups that downstream services check; and a named owner who can approve the trust decisions. Without the upstream access, origins cannot be tested end to end. Without test users covering the real role mix, authorization tests will miss gaps. Confirm these items in the scope before scheduling.
Can our internal team enable token exchange without outside help?
Yes, a team with experience running authentik and with control of its providers can enable the feature alone. The risk lies in the trust decisions: which origin may submit tokens, which audience and scopes an exchanged token receives, and how downstream services validate it. Teams that lack an identity architect or that have not reviewed token lifetimes and key binding often choose to bring in outside review for those decisions. Check your team's experience with OIDC trust and your change controls before deciding.
When does a fixed-scope engagement make sense for token exchange?
A fixed-scope engagement fits when the work has a defined boundary: a known set of trusted origins, a known list of downstream services and an agreed test plan. DeployOpen works on fixed scope, with scope, deliverables and timelines agreed in writing before work starts. It is a weaker fit when the trust model is still undecided, because the scope cannot be fixed until those decisions are made. In that case, a short design phase can settle the trust model first. Ongoing support and upgrades after go-live are available as retainers.
What breaks most often after enabling token exchange?
The most common failures come from mismatched configuration rather than from the protocol itself. Typical problems include a trusted origin whose tokens do not carry the expected audience, a downstream service that accepts tokens without checking the audience or issuer, and grant type settings left on for clients that do not need them. Key-bound ID tokens can also fail when a service has not been updated to check the binding. Test each origin and each downstream service against valid, expired and wrongly scoped tokens, and record the results as evidence for your review.
Running token exchange after go-live
Token exchange needs its own monitoring once it is live, because a failed or unexpected exchange often looks like an ordinary login problem to the calling application. Start by confirming which trusted providers and sources can reach the grant type, and record that list as the baseline. Then make sure the authentik event log is reviewed for exchange attempts, including rejected requests from sources you did not expect. Ask your team to confirm how exchange events are forwarded to your log platform and whether the fields needed to tell a downstream application, a trusted source and the affected user apart are present in the records you keep. Without that, an incident review will struggle to reconstruct who obtained an access token and on whose behalf.
Trusted keys need a rotation procedure before the first rotation is due. Treat each key used to vouch for an external token as a credential with an owner, an expiry date and a named change window. Rotate in an order that keeps the old key valid until every calling application has picked up the new one, and test that sequence in a non-production tenant first. Confirm with your identity team how the key material is stored and who can replace it, since a key that only one administrator can change becomes a single point of failure during an incident.
Upgrades need their own test pass for token exchange, not only a smoke test of sign-in. Because authentik requires upgrades to follow its documented sequential path, plan each step against the release notes for 2026.8 and any later release notes on that path, and check whether grant type settings, trusted source definitions or ID token key binding changed. Repeat an end-to-end exchange test after each step, using the same user, client and grant type as production. When you add a downstream application, rerun the exchange test for that client, confirm its allowed grant types match the least privilege you intended, and check that its ID token handling still works with key-bound tokens.
How DeployOpen scopes and delivers token exchange work
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms in infrastructure you control, including authentik. For OAuth 2.0 token exchange, we start from a written list of which services need to act on a user's behalf, which trusted providers and sources they trust, and how each exchange is tested before it reaches production.
How we scope
- Each engagement starts with a written scope listing the services that will exchange tokens and their trusted providers or sources.
- The scope names the grant type settings, client registrations and on-behalf-of flows to be configured in your authentik version.
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts; a quote follows from that scope.
How we build
- We configure trusted providers and sources, enable token exchange only on the providers that need it, and keep the default disabled state elsewhere.
- We test that exchanged tokens represent the same user, carry the expected scopes, and are refused for untrusted issuers or unlisted clients.
- We set up key-bound ID token settings and verify that dependent applications validate signatures against the published keys.
How we hand over
- You receive a written configuration record covering providers, sources, grant types, client settings and the reasoning behind each choice.
- Test cases and their results are delivered so your team can rerun the token exchange checks after changes or upgrades.
- We walk your engineers through the runbook for adding a new trusted source or service, and what to review before approving it.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover.
- Retainer work can cover reviewing the token exchange configuration when authentik releases a new version and planning the upgrade path.
- Ask any provider to confirm how the release notes and supported versions apply to your environment before you schedule changes.
