feat: add Session Delegation docs - #1624
Open
dlozlla wants to merge 7 commits into
Open
Conversation
Adds public docs for Session Delegation (Custom Token Exchange Phase 2), which lets an authorized actor establish an audited web session as another user via a Session Transfer Token. - New top-level nav section under Single Sign-On: an overview page, a configure page (security model + client settings), and a dedicated behavior/monitoring page (session behavior, Organizations, side effects, Actions, audit log types). - New use case in cte-example-use-cases.mdx with an Action code sample and an "Important considerations for session delegation" section (audience-based detection, connection-scoped target-app reachability, domain separation, agent logout between sessions). - get-token.mdx: Session Transfer Token request/response shape, the confidential-client requirement for STT requests, and error responses. - openid-connect-scopes.mdx: clarifies scope-based filtering applies to Action-set claims and Access Tokens, not just ID Tokens. - Cross-links from native-to-web docs distinguishing Session Delegation from Native to Web SSO.
dlozlla
added
the
DO NOT MERGE
Contributor
Summary
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…t/behavior pages Splits the initial Session Delegation draft into a clearer four-page structure and tightens content based on team review and developer persona feedback: - New "Implement Session Delegation" page: full security model (config-time confidentiality through runtime IP binding), a concrete CTE request/response example, exact Action responsibilities, the browser-redirect redemption flow with organization handling, and act-claim handling in the callback. - "Configure Session Delegation" trimmed to client settings only, with the real required JSON (token_exchange, session_transfer device binding/refresh-token settings) and matching curl examples. - "Delegated Session Behavior and Monitoring" (renamed): corrected the always-on IP device-binding behavior, merged side effects into the main behavior list, and fixed the sdeleacft/fdeleacft log descriptions. - cte-example-use-cases.mdx: considerations sections are now child sections of their use case; Action sample switched to setUserByConnection with the connection sourced from subject_token. - get-token.mdx Remarks trimmed to link out to concepts instead of re-explaining them inline. - Small additions in token-exchange-flow.mdx and the CTE trigger docs pointing to Session Delegation.
- Add the official flow diagram to the Session Delegation use case, and a Mermaid sequence diagram to the "How it works" overview, covering both the token-issuance and redemption parts of the flow. - Consolidate the "important considerations" content into Implement Session Delegation's troubleshooting checklist (per Madhuri's review), adding connection-reachability and organization-linkage checks she flagged as missing. The use case now links to the full Implement Session Delegation article rather than just the troubleshooting anchor. - Remove the actor_token/actor_token_type remark from get-token.mdx, redundant with the Body Parameters section (Madhuri's nitpick).
- Match N2W's placeholder convention for the session_transfer audience URN (urn:YOUR_AUTH0_TENANT_DOMAIN:session_transfer), per Slack feedback. - Rename initiate_login_url -> initiate_login_uri throughout (the actual Auth0 field name), per Justin's review. - Remove the orphaned cte_session_transfer_token feature-flag mention from get-token.mdx's 400-error table - it's an internal EA gating mechanism with no customer-facing config, and had no explanation after the Remarks section was trimmed in an earlier pass.
dlozlla
added
DO NOT MERGE
lrzhou25
reviewed
Jul 30, 2026
|
|
||
| <ParamField body="audience" type="string"> | ||
| (Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in [Tenant Settings](https://auth0.com/docs/get-started/tenant-settings). | ||
| (Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in [Tenant Settings](https://auth0.com/docs/get-started/tenant-settings). To request a [Session Transfer Token](/docs/authenticate/single-sign-on/session-delegation) for delegated session establishment instead of an access token, use `urn:{yourDomain}:session_transfer`. |
Contributor
There was a problem hiding this comment.
Suggested change
| (Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in [Tenant Settings](https://auth0.com/docs/get-started/tenant-settings). To request a [Session Transfer Token](/docs/authenticate/single-sign-on/session-delegation) for delegated session establishment instead of an access token, use `urn:{yourDomain}:session_transfer`. | |
| (Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in [Tenant Settings](https://auth0.com/docs/get-started/tenant-settings). To request a [Session Transfer Token](/docs/authenticate/single-sign-on/session-delegation) to establish a delegated session instead of an access token, use `urn:{yourDomain}:session_transfer`. |
| By binding Session Transfer Tokens to the specific device through IP address or ASN, session continuity and security is maintained and ensures the authentication context remains secure throughout the transition. | ||
|
|
||
| <Callout icon="file-lines" color="#0EA5E9" iconType="regular"> | ||
| Looking to let a support agent or other authorized actor establish a session **as another user**, rather than moving a user's own session from native to web? Read [Session Delegation](/docs/authenticate/single-sign-on/session-delegation) instead. |
Contributor
There was a problem hiding this comment.
Suggested change
| Looking to let a support agent or other authorized actor establish a session **as another user**, rather than moving a user's own session from native to web? Read [Session Delegation](/docs/authenticate/single-sign-on/session-delegation) instead. | |
| If you want a support agent or other authorized actor to establish a session **as another user** rather than move a user's own session from native to web, read [Session Delegation](/docs/authenticate/single-sign-on/session-delegation) instead. |
| * **Authorization Code flow only.** SAML, WS-Federation, and the Implicit flow are not supported for establishing a delegated session. | ||
| * **No refresh tokens.** The `offline_access` scope is excluded from any token issued during a delegated session. | ||
| * **No interactive prompts.** MFA, consent, and enrollment prompts (for example, passkey or MFA factor enrollment) cannot be satisfied during a delegated session. If one would be triggered, the request fails with `interaction_required` instead of prompting the user. | ||
| * **Existing sessions block delegated access.** If an active Auth0 session already exists for the browser, the delegated session attempt fails with an error page asking the user to log out first. This applies to *any* active session on that domain — the subject user's own session, or a previous delegated session established for a different user — not only a session belonging to the subject user. This is different from standard Native to Web SSO, which revokes the existing session and continues — read [Native to Web SSO and Sessions](/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-and-sessions) for that comparison. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **Existing sessions block delegated access.** If an active Auth0 session already exists for the browser, the delegated session attempt fails with an error page asking the user to log out first. This applies to *any* active session on that domain — the subject user's own session, or a previous delegated session established for a different user — not only a session belonging to the subject user. This is different from standard Native to Web SSO, which revokes the existing session and continues — read [Native to Web SSO and Sessions](/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-and-sessions) for that comparison. | |
| * **Existing sessions block delegated access.** If an active Auth0 session already exists for the browser, the delegated session attempt fails with an error page asking the user to log out first. This applies to *any* active session on that domain — the subject user's own session, or a previous delegated session established for a different user — not only a session belonging to the subject user. This is different from standard Native to Web SSO, which revokes the existing session and continues. To learn more, read [Native to Web SSO and Sessions](/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-and-sessions). |
| * **Existing sessions block delegated access.** If an active Auth0 session already exists for the browser, the delegated session attempt fails with an error page asking the user to log out first. This applies to *any* active session on that domain — the subject user's own session, or a previous delegated session established for a different user — not only a session belonging to the subject user. This is different from standard Native to Web SSO, which revokes the existing session and continues — read [Native to Web SSO and Sessions](/docs/authenticate/single-sign-on/native-to-web/native-to-web-sso-and-sessions) for that comparison. | ||
|
|
||
| <Callout icon="file-lines" color="#0EA5E9" iconType="regular"> | ||
| In practice, this means an actor (for example, a support agent) must log out of a delegated session before a different delegated session can be established for another user on the same domain. |
Contributor
There was a problem hiding this comment.
Suggested change
| In practice, this means an actor (for example, a support agent) must log out of a delegated session before a different delegated session can be established for another user on the same domain. | |
| The actor, for example, a support agent, must log out of a delegated session before a different delegated session can be established for another user on the same domain. |
| <Callout icon="file-lines" color="#0EA5E9" iconType="regular"> | ||
| In practice, this means an actor (for example, a support agent) must log out of a delegated session before a different delegated session can be established for another user on the same domain. | ||
| </Callout> | ||
| * **Ephemeral by default.** The session cookie is set to non-persistent (discarded when the browser closes). |
Contributor
There was a problem hiding this comment.
Suggested change
| * **Ephemeral by default.** The session cookie is set to non-persistent (discarded when the browser closes). | |
| * **Ephemeral by default.** The session cookie is set to non-persistent or discarded when the browser closes. |
| </Callout> | ||
| * **Ephemeral by default.** The session cookie is set to non-persistent (discarded when the browser closes). | ||
| * **Fixed 2-hour session lifetime.** Both the absolute and idle timeouts are hard-coded to 2 hours for delegated sessions and are not currently configurable. The issued access token shares this same 2-hour expiration. | ||
| * **Device binding.** Delegated sessions always enforce IP-based device binding — this cannot be disabled or changed to ASN, unlike the configurable device binding used by standard Native to Web SSO. Delegated sessions honor `is_token_endpoint_ip_header_trusted` and `auth0-forwarded-for` for determining the trusted IP, the same as Native to Web SSO. |
Contributor
There was a problem hiding this comment.
Suggested change
| * **Device binding.** Delegated sessions always enforce IP-based device binding — this cannot be disabled or changed to ASN, unlike the configurable device binding used by standard Native to Web SSO. Delegated sessions honor `is_token_endpoint_ip_header_trusted` and `auth0-forwarded-for` for determining the trusted IP, the same as Native to Web SSO. | |
| * **Device binding.** Delegated sessions always enforce IP-based device binding. This cannot be disabled or changed to ASN, unlike the configurable device binding used by standard Native to Web SSO. Delegated sessions honor `is_token_endpoint_ip_header_trusted` and `auth0-forwarded-for` for determining the trusted IP, the same as Native to Web SSO. |
lrzhou25
reviewed
Jul 30, 2026
lrzhou25
left a comment
lrzhou25
left a comment
Contributor
There was a problem hiding this comment.
First pass, left a few suggestions
Co-authored-by: Lucy Zhou <141781699+lrzhou25@users.noreply.github.com>
Simplify the standard-claims callout to point at the actual claim-setting mechanism (setCustomClaim() in a postLogin Action) instead of setUserById()/setUserByConnection(), which select the transaction's user rather than set claims.
- Fix cliams -> claims typo in openid-connect-scopes.mdx. - Fix MDX parsing error in session-delegation-behavior-and-monitoring.mdx: the nested <Callout> inside a list item needs blank lines and consistent 2-space indentation on every line to stay associated with the list item, matching the convention used elsewhere in the repo (e.g. session-layers.mdx).
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
2 participants
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.
Description
Adds public docs for Session Delegation (Custom Token Exchange Phase 2), which lets an authorized actor establish an audited web session as another user via a Session Transfer Token.