Conversation
update sign-out page by adding new session management related topics
add session management flow to account APIs and management APIs
Deploying logto-docs-tutorials with
|
| Latest commit: |
a40f30b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://7dc24dc4.logto-docs-tutorials.pages.dev |
| Branch Preview URL: | https://simeng-session-management-do.logto-docs-tutorials.pages.dev |
There was a problem hiding this comment.
Pull request overview
Adds session-management documentation across user management and end-user flows, and updates sign-out docs to better explain session vs grant vs client auth state.
Changes:
- Document user session viewing/revocation in the Console user details docs.
- Add Account API + Management API session-management endpoints and usage examples.
- Restructure the sign-out doc around sessions/grants and sign-out mechanisms, with new diagrams and explanations.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/user-management/manage-users.mdx | Adds Console guidance for viewing/revoking user sessions. |
| docs/user-management/README.mdx | Mentions session management as a user-management capability. |
| docs/end-user-flows/sign-out.mdx | Major rewrite to explain sign-out across session/grant/client state layers. |
| docs/end-user-flows/account-settings/by-management-api.mdx | Adds Management API session-management endpoints for users. |
| docs/end-user-flows/account-settings/by-account-api.mdx | Adds Account API session-management scope, endpoints, and revoke options. |
| docs/end-user-flows/account-settings/README.mdx | Updates Account APIs overview + comparison table to include sessions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| - `UserScope.Sessions` scope is required to access this endpoint. | ||
| - `Sessions` field in account center settings must be set to `Edit`. | ||
| ::: |
There was a problem hiding this comment.
The closing ::: for this :::note block is indented, which will break the admonition rendering (it will be treated as a code block / list continuation). Please unindent the closing ::: so the note renders correctly.
| ::: | |
| ::: |
| ## Sign-out mechanisms | ||
|
|
||
| Upon successful sign-in, the client application may receive an [ID token](https://auth.wiki/id-token) and [access token](https://auth.wiki/access-token). The client application can use the ID token to determine the user's identity and the access token to access the user's resources. The user's authentication status is represented by the access token's expiration time. | ||
| ### 1) Client-side-only sign-out | ||
|
|
||
| - Native and SPA applications: | ||
| Client application need to securely store and manage these tokens in order to maintain the user's authentication status. E.g., store the tokens in local storage or session storage, and clear the tokens when the user signs out. | ||
| - Web applications: | ||
| Web apps like those built with frameworks like Next.js often manage their own session for logged-in users alongside the tokens issued by Logto. Once the user signs in, and the web app receives the tokens from Logto, it can store the tokens at the client-side just like SPA applications, or it can store the tokens at the server-side and manage the session using cookies or other mechanisms. | ||
| Client app clears its own local session and tokens (ID/access/refresh tokens). This signs user out from that app's local state only. | ||
|
|
||
| ## Sign-out mechanisms \{#sign-out-mechanisms} | ||
| - Logto session may still be active. | ||
| - Other apps under same Logto session may still SSO. | ||
|
|
||
| ### Clear tokens and local session at the client side \{#clear-tokens-and-local-session-at-the-client-side} | ||
| ### 2) End-session at Logto (global sign-out in current Logto implementation) | ||
|
|
||
| On the client side, a simple sign-out involves clearing the local session and removing tokens (ID token, access token, refresh token) from local storage or session storage. This results in a client-side-only sign-out where the centralized session remains intact. Users sign out in this manner may still be able to access other applications under the same authorization server session until the centralized session expires or is actively destroyed. | ||
| To clear centralized Logto session, app redirects user to the end session endpoint, for example: | ||
|
|
||
| ### Clear sign-in session at Logto \{#clear-sign-in-session-at-logto} | ||
| `https://{your-logto-domain}/oidc/session/end` |
There was a problem hiding this comment.
The previous anchors #clear-tokens-and-local-session-at-the-client-side and #clear-sign-in-session-at-logto are still referenced elsewhere (e.g. docs/end-user-flows/README.mdx), but the headings here were renamed so those fragments will 404. Please add explicit {#clear-tokens-and-local-session-at-the-client-side} and {#clear-sign-in-session-at-logto} ids to the corresponding sections (client-side sign-out and end-session) to avoid breaking existing links.
| ## Federated sign-out: back-channel logout | ||
|
|
||
| 1. User initiates a sign-out request from one client application. | ||
| 2. Logto receives the end session request, generates a logout token, and sends the logout token to all registered back-channel logout URIs. | ||
| 3. Each client application receives the logout token and perform sign-out actions. | ||
| For cross-app consistency, Logto supports [back-channel logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). | ||
|
|
||
| Sign-out actions for each client application when receiving the logout token: | ||
| When a user signs out from one app, Logto can notify all apps participating in the same session by sending a logout token to each app's registered back-channel logout URI. |
There was a problem hiding this comment.
Consider adding an explicit {#federated-sign-out-back-channel-logout} id to this heading to preserve existing inbound links (e.g. docs/security/README.mdx and docs/end-user-flows/README.mdx). Relying on auto-generated slugs is brittle if the heading text changes again.
| - `revokeGrantsTarget`: Optionally specify the target of the grants to revoke along with the session. Possible values: | ||
| - `all`: Revoke all grants associated with the session | ||
| - `firstParty`: Revoke only first-party app grants associated with the session | ||
| - unspecified: Default behavior revokes grants that does not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session. |
There was a problem hiding this comment.
Grammar: "revokes grants that does not have" should be plural ("do not have"), since it refers to "grants".
| - unspecified: Default behavior revokes grants that does not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session. | |
| - unspecified: Default behavior revokes grants that do not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session. |
| - You cannot add or remove enterprise SSO identities in the Console. | ||
| - For OIDC-based enterprise connectors with [token storage](/secret-vault/federated-token-set) enabled, you can view and delete tokens in the connection detail page. | ||
| - **User profile data**: name, avatar URL, custom data, and additional OpenID Connect standard claims that are not included. All these profile fields are editable. | ||
| - **Sessions**: View the list of user active sessions, including device information sessionId and GEO location if applicable. View more details of a session and revoke it in the session detail page. |
There was a problem hiding this comment.
Wording/formatting is hard to read here (missing commas and inconsistent terms): "user active sessions", "device information sessionId and GEO location". Consider rephrasing to "user’s active sessions" and formatting the field name consistently (e.g. "session ID" / sessionId) and "geolocation".
| - **Sessions**: View the list of user active sessions, including device information sessionId and GEO location if applicable. View more details of a session and revoke it in the session detail page. | |
| - **Sessions**: View the list of the user's active sessions, including device information, session ID, and geolocation, if applicable. View more details of a session and revoke it in the session detail page. |
| | **Intended user** | End users | End users | Admins / Developers | | ||
| | **Access context** | Redirect to Logto-hosted pages | Client-side / front-end | Server-side / back-end | | ||
| | **Permission model** | Toggle which fields are enabled via Account center settings | Toggle which Account APIs are enabled via Management API | Fully customizable by developers | | ||
| | **Supported features** | Update: email, phone, username, password, MFA (TOTP, passkeys, backup codes) | View, update, and delete: username, email, phone, password, social accounts, MFA, profile, sessions | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, session, etc. | |
There was a problem hiding this comment.
Minor consistency issue: this list says "profile, sessions" elsewhere but here it says "connect OAuth apps, session, etc.". Please use the plural "sessions" for consistency with the rest of the doc and the preceding column.
| | **Supported features** | Update: email, phone, username, password, MFA (TOTP, passkeys, backup codes) | View, update, and delete: username, email, phone, password, social accounts, MFA, profile, sessions | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, session, etc. | | |
| | **Supported features** | Update: email, phone, username, password, MFA (TOTP, passkeys, backup codes) | View, update, and delete: username, email, phone, password, social accounts, MFA, profile, sessions | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, sessions, etc. | |
| Key features: | ||
|
|
||
| - **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, and profile data. | ||
| - **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, profile data and sessions. |
There was a problem hiding this comment.
Grammar: add a comma in "profile data and sessions" ("profile data, and sessions") to avoid reading it as a single combined concept.
| - **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, profile data and sessions. | |
| - **End-user settings**: Users manage their own sign-in identifiers and credentials, social accounts, MFA methods, profile data, and sessions. |
| 7. The OIDC provider redirects the user back to the client with an authentication code ([Authorization Code flow](https://auth.wiki/authorization-code-flow)). | ||
| 8. The client receives the authentication code and exchanges it for tokens to access user information. | ||
| 9. Grant tokens to the client application. | ||
| ### What is a Logto session? |
There was a problem hiding this comment.
This rewrite removed the previous explicit heading anchor #sign-in-session, but other docs still link to /end-user-flows/sign-out#sign-in-session (e.g. signing-keys.mdx). Please preserve backward-compatible anchors by adding an explicit {#sign-in-session} id to the section that defines the Logto session (or reintroduce a matching heading).
| ### What is a Logto session? | |
| ### What is a Logto session? {#sign-in-session} |
| - **Native (including React Native / Flutter)**: usually clears local token storage only. Sessionless webview means no persistent Logto browser cookie to clear. | ||
|
|
||
| :::note | ||
| For native applications that does not support sessionless webview or does not recognize the `emphasized` settings(Android app using **React Native** or **Flutter** SDK), you may force the user prompt to sign in again by passing the `prompt=login` parameter in the authorization request. |
There was a problem hiding this comment.
This note has a few grammar/clarity issues that make it hard to follow (e.g. "applications that does not", missing space before the parenthesis). Please adjust phrasing so it reads cleanly and unambiguously.
| For native applications that does not support sessionless webview or does not recognize the `emphasized` settings(Android app using **React Native** or **Flutter** SDK), you may force the user prompt to sign in again by passing the `prompt=login` parameter in the authorization request. | |
| For native applications that do not support sessionless webviews or do not recognize the `emphasized` setting (for example, Android apps using the **React Native** or **Flutter** SDK), you can force the user to sign in again by passing the `prompt=login` parameter in the authorization request. |
| For high-security actions, include `prompt=login` in auth requests to bypass SSO and force credential entry each time. | ||
|
|
||
| Setting `prompt=login` forces Logto to always display the sign-in page, regardless of whether the user has an active session or recently signed in. This bypasses single sign-on (SSO) behavior and ensures the user is prompted to enter their credentials each time. | ||
| If requesting `offline_access` (to receive refresh tokens), also include `consent`, `prompt=login consent`. | ||
|
|
||
| If your app requests the offline_access scope (to receive a refresh token), the OpenID Connect specification requires you to also include `prompt=consent`. | ||
| In most cases, to both enforce re-authentication and ensure refresh token issuance, set: | ||
| Typical combined setting: | ||
|
|
||
| ``` | ||
| ```txt | ||
| prompt=login consent |
There was a problem hiding this comment.
The offline_access guidance here is ambiguous/incorrectly phrased ("also include consent, prompt=login consent"). In OIDC the parameter is prompt, so this should explicitly say to include prompt=consent (or combine as prompt=login consent) when requesting offline_access, and avoid implying a separate consent parameter.
Summary
Add session management-related content to the docs.