Custom Token Exchange - Auth0 Docs

Availability varies by Auth0 plan

This feature is available for B2C Professional, B2B Professional, and Enterprise plans. To learn more, read Pricing.

Custom Token Exchange enables applications to exchange their existing tokens for Auth0 tokens when calling the /oauth/token endpoint, as defined in RFC 8693. Common use cases for the Custom Token Exchange include:

To learn more, read Example Use Cases and Code Samples.

If you don’t have custom token validation requirements and only need to propagate delegation context between your own services, use On-Behalf-Of Token Exchange instead. It doesn’t run a custom Action per request and supports significantly higher throughput. Use Custom Token Exchange when you need to validate subject or actor tokens in a custom format, integrate an external identity provider, or otherwise need full control over the exchange logic.

Each Custom Token Exchange request maps to a Custom Token Exchange Profile that is governed by an Action, where you can:

You can configure multiple Custom Token Exchange Profiles for an application. After the Auth0 Authorization Server validates that the Custom Token Exchange request is valid and maps to an existing Custom Token Exchange Profile, the Custom Token Exchange trigger executes the single Action associated with that profile. The application can then leverage the Custom Token Exchange to authenticate and get Auth0 access, ID, and refresh tokens for the user.

Custom Token Exchange gives you the added flexibility to set the user for the transaction by taking on the additional responsibility of securely validating the corresponding subject token that identifies the user for the transaction. Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type you require, as long as your Action code can interpret them. You must implement strong validation of the tokens you receive and accept. If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else’s user ID or acting on their behalf in an unauthorized manner. To learn about different options for implementing secure validation of your subject tokens, read and apply the recommendations included in Example Use Cases and Code Samples. Make sure you also take into consideration and apply Attack Protection capabilities.

Tenant logs

Each Custom Token Exchange transaction generates a tenant event log:

When an actor is set via setActor(), the actor property (containing sub and any nested actor) is included in secte log entries for audit purposes. Use the tenant logs to help you troubleshoot any issues you encounter with your token exchange.

Limitations

Custom Token Exchange does not support the following: