feat: add Session Transfer Token support for CTE impersonation via session transfer - #153
Merged
Conversation
…ssion transfer Surfaces CTE Impersonation via Session Transfer through the auth0-fastapi wrapper SDK. Adds thin AuthClient wrappers over the auth0-server-python STT surface: - request_session_transfer_token: mints an STT via custom token exchange and returns a SessionTransferTokenResult. - build_session_transfer_redirect: builds the redirect that hands the STT to the target app's login URL. The target (redeeming) side needs no new code: the mounted /auth/login route already forwards session_transfer_token to /authorize. Bumps auth0-server-python to >=1.0.0b14 for the STT surface, adds an STT section to examples/CustomTokenExchange.md and a README pointer, and adds unit tests for the wrappers.
nandan-bhat
reviewed
Aug 5, 2026
- Fix the impersonation doc example to pass response in store_options and propagate response.headers, so sourcing the actor can refresh an expired session ID token without crashing on a None response. - Reword the redirect security note to say the SDK checks URL shape, not the host, so the trusted-target responsibility stays with the caller. - Re-export InvalidArgumentError from auth0_fastapi.errors, which the redirect helper and the STT mint (blank organization) can raise. - Add /auth/login STT-forwarding route tests and a redirect validation propagation test. - Document that mounted-route STT redemption is incompatible with pushed authorization requests, and add initiator-side audit logging guidance. - Regenerate poetry.lock with Poetry 2.4.1 to restore the dropped 3.14 markers.
nandan-bhat
approved these changes
Aug 6, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📋 Changes
This PR surfaces Custom Token Exchange (CTE) Impersonation via Session Transfer (RFC 8693) through the auth0-fastapi wrapper SDK. The heavy lifting lives in auth0-server-python; this SDK adds thin
AuthClientwrappers so a FastAPI app can exchange a subject token for a short-lived, single-use Session Transfer Token (STT) that redeems into an impersonated web session on a target app - logging an agent in as a customer with the agent recorded in theactclaim. The initiator mints the STT and builds the redirect; the target needs no new SDK code, since the mounted/auth/loginroute already forwardssession_transfer_tokento/authorize.✨ Features
AuthClient.request_session_transfer_tokendelegates to the underlying client to perform the CTE exchange against theurn:{domain}:session_transferaudience and returns aSessionTransferTokenResultAuthClient.build_session_transfer_redirectreturns the redirect URL that hands the STT to the target app's login URL, forwardingorganizationwhen present/auth/loginroute already forwardssession_transfer_token(andorganization) through to/authorize🔧 API Changes
request_session_transfer_token(subject_token, subject_token_type, actor_token=None, actor_token_type=None, scope=None, organization=None, store_options=None) -> SessionTransferTokenResultbuild_session_transfer_redirect(target_login_url, result, organization=None) -> strauth0-server-pythondependency to>=1.0.0b14, which provides the STT surface, theSessionTransferTokenResultmodel, and theACTOR_UNAVAILABLE/SETACTOR_REQUIRED/SESSION_TRANSFER_DISABLEDerror codes📖 Documentation
examples/CustomTokenExchange.mdcovering the FastAPI wrappers, how the flow maps onto the mounted routes, the redirect-URL security note, and the STT error codes, pointing to the auth0-server-python guide for the underlying protocol detailREADME.md🧪 Testing
Contributor Checklist