Skip to content

feat: add Session Transfer Token support for CTE impersonation via session transfer - #153

Merged
kishore7snehil merged 2 commits into
mainfrom
feat/cte-stt-support
Aug 6, 2026
Merged

feat: add Session Transfer Token support for CTE impersonation via session transfer#153
kishore7snehil merged 2 commits into
mainfrom
feat/cte-stt-support

Conversation

@kishore7snehil

Copy link
Copy Markdown
Contributor

📋 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 AuthClient wrappers 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 the act claim. The initiator mints the STT and builds the redirect; the target needs no new SDK code, since the mounted /auth/login route already forwards session_transfer_token to /authorize.

✨ Features

  • AuthClient.request_session_transfer_token delegates to the underlying client to perform the CTE exchange against the urn:{domain}:session_transfer audience and returns a SessionTransferTokenResult
  • AuthClient.build_session_transfer_redirect returns the redirect URL that hands the STT to the target app's login URL, forwarding organization when present
  • The target (redeeming) side needs no new code: the mounted /auth/login route already forwards session_transfer_token (and organization) through to /authorize

🔧 API Changes

  • New method request_session_transfer_token(subject_token, subject_token_type, actor_token=None, actor_token_type=None, scope=None, organization=None, store_options=None) -> SessionTransferTokenResult
  • New method build_session_transfer_redirect(target_login_url, result, organization=None) -> str
  • Bumped the auth0-server-python dependency to >=1.0.0b14, which provides the STT surface, the SessionTransferTokenResult model, and the ACTOR_UNAVAILABLE / SETACTOR_REQUIRED / SESSION_TRANSFER_DISABLED error codes

📖 Documentation

  • Added an "Impersonation via Session Transfer (STT)" section to examples/CustomTokenExchange.md covering 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 detail
  • Linked the new section from the Custom Token Exchange feature list in README.md

🧪 Testing

  • This change adds test coverage
  • This change has been tested on the latest version of the platform/language

Contributor Checklist

…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.
@kishore7snehil
kishore7snehil requested a review from a team as a code owner August 4, 2026 11:07
Comment thread examples/CustomTokenExchange.md Outdated
Comment thread examples/CustomTokenExchange.md Outdated
Comment thread examples/CustomTokenExchange.md Outdated
Comment thread poetry.lock Outdated
Comment thread requirements.txt
Comment thread src/auth0_fastapi/auth/auth_client.py
Comment thread src/auth0_fastapi/auth/auth_client.py
Comment thread src/auth0_fastapi/auth/auth_client.py
Comment thread src/auth0_fastapi/test/test_auth_client.py
- 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.
@kishore7snehil
kishore7snehil merged commit 62d8a77 into main Aug 6, 2026
9 checks passed
@kishore7snehil kishore7snehil mentioned this pull request Aug 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants