Skip to main content
Custom Token Exchange (CTE) is currently available in Early Access for all Auth0 B2C Professional, B2B Professional, and Enterprise customers. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. To learn more about Auth0’s product release cycle, read Product Release Stages. To learn more about subscription types, review the Auth0 pricing page.
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. If the Action successfully completes and sets a user for the transaction, post-login Actions and the rest of the Auth0 pipeline are then executed for that logged-in user.
Actions in this flow are blocking (synchronous), which means they execute as part of a trigger’s process and will prevent the rest of the Auth0 pipeline from running until the Action is complete.

​
Custom Token Exchange vs Post Login Actions

The Post Login Actions trigger executes after the Custom Token Exchange Action runs for the user you set for the transaction. For other use cases, such as adding custom claims to access tokens, use the Post Login Action trigger. The Custom Token Exchange uses the token exchange grant type, where the event.transaction.protocol is set to oauth2-token-exchange in the Post Login Action trigger. Both the Custom Token Exchange and Native Social Login use the token exchange grant type. To distinguish between the two, use the value of the subject_token_type, which should correspond to one of your Custom Token Exchange Profiles.
Custom Token Exchange Early Access doesn’t support api.authentication.challengeWith() or api.authentication.enrollWith(). If you use those methods with your Post-Login Actions, the transaction will fail with a non-recoverable error. Make sure you skip those two methods when event.transaction.protocol==oauth2-token-exchange depending on the subject_token_type value.

​
Actor support for delegation

The custom-token-exchange trigger supports delegated authorization scenarios. The Action can call api.authentication.setActor() to include an act claim in issued tokens, identifying the principal acting on behalf of the subject user. setActor() can be called regardless of whether the request includes an actor_token. The actor_token parameter is one way for the calling application to pass actor information to the Action, but the actor identity can also be embedded in the subject_token itself or obtained through other custom means within the Action code. When the request does include actor_token and actor_token_type, these values are available in event.transaction. If actor_token_type is urn:ietf:params:oauth:token-type:id_token and the token is a valid Auth0 ID token from the same tenant, the server automatically validates the token and populates event.transaction.actor_token_user with the actor’s user profile. The act claim set via setActor() is also available in Post-Login Actions via event.transaction.actor.

​
Triggers

​
Custom Token Exchange

The custom-token-exchange trigger is the first step in the Auth0 pipeline. This function is executed after the received Custom Token Exchange request has been validated and successfully mapped to an existing profile.

​
References

  • Event object: Provides contextual information about the a Token Exchange request, including the subject_token, IP address, client, and more.
  • API object: Provides methods to use with your Token Exchange Action that allows you to set the user, set the actor for delegation, reject the transaction, set user metadata and access the Actions cache, and more.

​
Common Use Cases

To learn about common Custom Token Exchange use cases, read Example Use Cases.