feat: Adds Custom Token Exchange support

[kailash-b]

By submitting a PR to this repository, you agree to the terms within the Auth0 Code of Conduct. Please see the contributing guidelines for how to create and submit a high-quality PR for this repo.

Description

This PR adds support for Custom Token Exchange (RFC 8693) to the SDK, letting an application exchange an existing external/custom security token for Auth0 tokens without a browser redirect. The primary use cases are delegation/impersonation and agent-identity scenarios. It requires a configured Custom Token Exchange Profile and a validation Action in the Auth0 tenant.

The feature is exposed through a new HttpContext.CustomTokenExchangeAsync(CustomTokenExchangeRequest) extension method:

• CustomTokenExchangeRequest describes the exchange: SubjectToken and SubjectTokenType (required), plus optional Audience, Scope, ActorToken/ActorTokenType (delegation pair), and Organization.

• CustomTokenExchangeResult returns the exchanged tokens (AccessToken, IdToken, RefreshToken, ExpiresIn, Scope) and the decoded act (actor) claim (Act) for delegation flows.

• CustomTokenExchangeException is thrown on client-side validation failures or token-endpoint rejections, carrying StatusCode, Error, and ErrorDescription for the latter. It never carries token-bearing bytes.

• Stateless by design. CustomTokenExchangeAsync performs the exchange and returns the tokens but has no session side-effects — it does not sign the user in or write any cookie. The caller decides what (if anything) to persist.

• Client-side validation (CustomTokenExchangeRequestValidator) runs before any network call: subject_token must be non-empty and must not include a Bearer prefix; subject_token_type must be a valid URI (URL or URN), 10–100 characters, and the reserved urn:ietf: and urn:auth0: namespaces are rejected; an actor token requires its matching type and vice-versa.

• Delegation / impersonation. When an actor token pair is supplied, the act claim from the returned ID token is decoded and exposed on result.Act (ActClaimReader). The outermost Sub is the current actor; nested Act values are prior actors and are informational only. Auth0 suppresses the refresh token in delegation flows.

The exchange is implemented on TokenClient (ExchangeCustomToken) and integrates with the SDK's existing domain resolution (including Multiple Custom Domain support) and backchannel client.

References

• Custom Token Exchange documentation

Testing

Unit/integration tests were added covering the new functionality:

• This change adds test coverage for new/changed/fixed functionality

Checklist

• I have added documentation for new/changed functionality in this PR or in auth0.com/docs
• All active GitHub checks for tests, formatting, and security are passing
• The correct base branch is being used, if not main