diff --git a/docs/developers/signing-keys.mdx b/docs/developers/signing-keys.mdx index 150ceb54b47..d3e571dd7b2 100644 --- a/docs/developers/signing-keys.mdx +++ b/docs/developers/signing-keys.mdx @@ -7,7 +7,7 @@ sidebar_position: 5 # Signing keys -Logto [OIDC signing keys](https://auth.wiki/signing-key), as known as "OIDC private keys" and "OIDC cookie keys", are the signing keys used to sign JWTs ([access tokens](https://auth.wiki/access-token) and [ID tokens](https://auth.wiki/id-token)) and browser cookies in Logto [sign-in sessions](/end-user-flows/sign-out#sign-in-session). These signing keys are generated when seeding Logto database ([open-source](/logto-oss)) or creating a new tenant ([Cloud](/logto-cloud)) and can be managed through [CLI](/logto-oss/using-cli) (open-source), Management APIs or Console UI. +Logto [OIDC signing keys](https://auth.wiki/signing-key), as known as "OIDC private keys" and "OIDC cookie keys", are the signing keys used to sign JWTs ([access tokens](https://auth.wiki/access-token) and [ID tokens](https://auth.wiki/id-token)) and browser cookies in Logto [sign-in sessions](/end-user-flows/sign-out#what-is-a-logto-session). These signing keys are generated when seeding Logto database ([open-source](/logto-oss)) or creating a new tenant ([Cloud](/logto-cloud)) and can be managed through [CLI](/logto-oss/using-cli) (open-source), Management APIs or Console UI. By default, Logto uses the elliptic curve (EC) algorithm to generate digital signatures. However, considering that users often need to verify JWT signatures and many older tools do not support the EC algorithm (only supporting RSA), we have implemented the functionality to rotate private keys and allow users to choose the signature algorithm (including both RSA and EC). This ensures compatibility with services that use outdated signature verification tools. diff --git a/docs/end-user-flows/README.mdx b/docs/end-user-flows/README.mdx index b47e1665641..8c705a79eb7 100644 --- a/docs/end-user-flows/README.mdx +++ b/docs/end-user-flows/README.mdx @@ -21,7 +21,7 @@ End-user flows cover all verification processes for user interactions, categoriz | [Magic link (One-time token)](/end-user-flows/one-time-token) | | | Authorize third-party apps | | | Collect user profile | | -| [Sign-out](/end-user-flows/sign-out) | | +| [Sign-out](/end-user-flows/sign-out) | | This section introduces Logto’s pre-built UI for a streamlined sign-in experience, helping you accelerate time-to-market. For more flexibility in customizing your sign-in UI, try the “[Bring Your UI](/customization/bring-your-ui)” feature with Logto Experience APIs. diff --git a/docs/end-user-flows/account-settings/README.mdx b/docs/end-user-flows/account-settings/README.mdx index 6e4604cf2b6..ea9030b3b45 100644 --- a/docs/end-user-flows/account-settings/README.mdx +++ b/docs/end-user-flows/account-settings/README.mdx @@ -41,7 +41,7 @@ Logto's Account APIs are ready-to-use, front-end endpoints that let end users se 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. - **Client-side integration**: Designed for safe, direct use in your front-end. - **Full customization**: Build your own UI while leveraging Logto's secure APIs. - **Permission control**: Toggle which Account APIs are enabled via Management API settings. @@ -88,12 +88,12 @@ Key features: ## Comparison of account settings options \{#comparison-of-account-settings-options} -| Feature | Prebuilt Account Center UI | Account APIs | Management APIs | -| ---------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| **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 | All basic settings + Delete/suspend/restore account, Personal access tokens, user impersonation, connect OAuth apps, etc. | -| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) | -| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) | -| **When to use** | For the fastest way to add account management without building custom pages | When you need custom UI but want to leverage Logto's secure APIs | When Account APIs don't meet your needs. E.g., for complex account deletion logic, high-risk actions, or building back-office tools | +| Feature | Prebuilt Account Center UI | Account APIs | Management APIs | +| ---------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| **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. | +| **UI customization** | Inherits sign-in experience branding | Full customization (build your own UI) | Full customization (build your own UI) | +| **Setup complexity** | None (just link to prebuilt pages) | Low (use APIs with your UI) | Medium to high (requires custom implementation) | +| **When to use** | For the fastest way to add account management without building custom pages | When you need custom UI but want to leverage Logto's secure APIs | When Account APIs don't meet your needs. E.g., for complex account deletion logic, high-risk actions, or building back-office tools | diff --git a/docs/end-user-flows/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx index 5b508c98898..e3ea2ef58e5 100644 --- a/docs/end-user-flows/account-settings/by-account-api.mdx +++ b/docs/end-user-flows/account-settings/by-account-api.mdx @@ -23,6 +23,7 @@ Some frequent use cases are listed below: - Update user password - Update user identities including email, phone, and social connections - Manage MFA factors (verifications) +- Manage user sessions To learn more about the available APIs, please visit [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) and [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). @@ -47,7 +48,11 @@ Once enabled, configure per-field permissions for identifiers, profile data, and 2. **Profile fields**: - Fields include: username, name, avatar, [profile](/user-management/user-data#profile) (other standard profile attributes), and [custom data](/user-management/user-data#custom-data). - End users can edit these without additional verification. -3. **Secret vault**: For OIDC or OAuth social and enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) securely stores third-party access and refresh tokens after authentication. Apps can then call external APIs, such as syncing Google Calendar events, without prompting users to sign in again. Token retrieval becomes available automatically once the Account API is enabled. +3. **Secret vault**: + - For OIDC or OAuth social and enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) securely stores third-party access and refresh tokens after authentication. Apps can then call external APIs, such as syncing Google Calendar events, without prompting users to sign in again. Token retrieval becomes available automatically once the Account API is enabled. +4. **Session management**: + - When enabled, users can view and manage their active sessions, including device information and last sign-in time. Users can also revoke sessions to log out from specific devices. + - Before end users access session management, they must verify their identity via password, email, or SMS to obtain a 10-minute verification record ID. See [Get a verification record id](#get-a-verification-record-id). ## How to access Account API \{#how-to-access-account-api} @@ -69,6 +74,7 @@ const config: LogtoConfig = { UserScope.Address, // To manage address UserScope.Identities, // For identity and MFA related APIs UserScope.Profile, // To manage user profile + UserScope.Sessions, // To manage user sessions ], }; ``` @@ -663,3 +669,47 @@ The response body would be like: - `code`: the backup code. - `usedAt`: the timestamp when the code was used, `null` if not used yet. + +### Manage user sessions \{#manage-user-sessions} + +**List active sessions** + +To list the user's active sessions, you can use the [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) endpoint. + +:::note + +- `UserScope.Sessions` scope is required to access this endpoint. +- `Sessions` field in account center settings must be set to `ReadOnly` or `Edit`. + +::: + +```bash +curl https://[tenant-id].logto.app/api/my-account/sessions \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**Revoke session by session ID** + +To revoke a specific session, use the [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) endpoint. + +:::note + +- `UserScope.Sessions` scope is required to access this endpoint. +- `Sessions` field in account center settings must be set to `Edit`. + ::: + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Optional query parameters: + +- `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. (Recommended for most use cases, as it revokes access for your own app while keeping third-party app grants intact, providing a better user experience.) + - unspecified: Default behavior revokes grants that does not have `offline_access` scope, which typically means revoking non-refresh-token grants for the session. diff --git a/docs/end-user-flows/account-settings/by-management-api.mdx b/docs/end-user-flows/account-settings/by-management-api.mdx index 124f11b4ca0..1759b581139 100644 --- a/docs/end-user-flows/account-settings/by-management-api.mdx +++ b/docs/end-user-flows/account-settings/by-management-api.mdx @@ -194,3 +194,11 @@ Personal access tokens provide a secure way for users to grant [access token](ht | method | path | description | | ------ | -------------------------------------------------------------------------------- | ------------------------- | | DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Delete a user by user ID. | + +### User session management \{#user-session-management} + +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Get user sessions by user ID. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Get a user session by session ID. | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Delete a user session by session ID. | diff --git a/docs/end-user-flows/sign-out.mdx b/docs/end-user-flows/sign-out.mdx index 467ea581e2d..b22142c451d 100644 --- a/docs/end-user-flows/sign-out.mdx +++ b/docs/end-user-flows/sign-out.mdx @@ -4,178 +4,220 @@ sidebar_position: 8 # Sign-out -The sign-out process in Logto (as an OIDC-based identity provider) is a multi-faced concept due to the involvement of both centralized sign-in session managed by Logto and the distributed authentication status managed by the client applications. +Sign-out in Logto (as an OIDC identity provider) involves both: -## Sign-in session \{#sign-in-session} +- A **centralized Logto session** (browser cookie under Logto domain), and +- **Distributed client-side auth state** (tokens and local app session in each app). -To better understand the sign-out process, it's important to first understand how user sign-in sessions and their authentication status are managed in Logto. +To understand sign-out behavior, it helps to separate these two layers and then see how **grants** connect them. + +## Core concepts \{#core-concepts} + +### What is a Logto session? \{#what-is-a-logto-session} + +A Logto session is the centralized sign-in state managed by Logto. It is created after successful authentication and represented by cookies under the Logto domain. + +If the session cookie is valid, the user can be silently authenticated (SSO) across multiple apps that trust the same Logto tenant. + +If no valid session exists, Logto shows the sign-in page. + +### What are grants? \{#what-are-grants} + +A **grant** represents the authorization status for a specific user + client application combination. + +- One Logto session can have grants for multiple client apps. +- A grant is what issued tokens are associated with. +- In this doc set, use **grant** as the cross-app authorization unit. + +### How session, grants, and client auth status relate \{#how-session-grants-and-client-auth-status-relate} + +```mermaid +flowchart LR + subgraph Logto [Logto domain] + S[Logto session] + G1[Grant for App A] + G2[Grant for App B] + end + + subgraph AppA [Client domain A] + A[Local session / tokens] + end + + subgraph AppB [Client domain B] + B[Local session / tokens] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto session** controls centralized SSO experience. +- **Client local session/tokens** control whether each app currently treats user as signed in. +- **Grants** connect these two worlds by representing app-specific authorization state. + +## Sign-in recap (why sign-out is multi-layered) \{#sign-in-recap-why-sign-out-is-multi-layered} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party (RP) + participant Client as Client application + end + + box Logto (IdP) + participant OIDC as OIDC provider + participant SignIn as Sign-in page + end + + User ->> Client: Access application + Client ->> OIDC: Redirect for authentication + OIDC -->> OIDC: Check Logto session + OIDC ->> SignIn: Prompt sign-in if needed + SignIn ->> OIDC: User authenticates + OIDC -->> OIDC: Create session and grant + OIDC ->> Client: Return authorization code + Client ->> OIDC: Exchange code for tokens + OIDC -->> Client: Return tokens +``` + +## Session topology across apps/devices \{#session-topology-across-apps-devices} + +### Shared session cookie (same browser/user agent) \{#shared-session-cookie-same-browser-user-agent} + +If a user signs in to multiple apps from the same browser, those apps can reuse the same Logto session cookie and SSO behavior applies. ```mermaid - sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as Client application - end - - box Logto (IdP) - participant OIDC as OIDC provider - participant SignIn as Sign-in page - end - - User ->> Client: Access web application - Client ->> OIDC: Redirect user to OIDC for authentication - OIDC -->> OIDC: Check user's sign-in session - OIDC ->> SignIn: Prompt user to sign in - SignIn ->> OIDC: Identify user and submit the interaction result - OIDC -->> OIDC: Establish user's sign-in session and authentication grant - OIDC ->> Client: Redirect user back to the web application with authentication code (Authorization Code flow) - Client ->> OIDC: Exchange the code for tokens - OIDC -->> Client: Return tokens +flowchart TD + U[User] + A["Client Application A (Client domain A)"] + B["Client Application B (Client domain B)"] + C{"Logto session exists? (Logto domain)"} + D["Sign-in page (Logto domain)"] + + subgraph UA["User agent A (same browser)"] + U + A + B + C + D + end + + U -->|Sign in| A + A -->|Redirect to Logto| C + U -->|Open app| B + B -->|Redirect to Logto| C + C -->|No| D + D -->|Create session| C ``` -1. The user accesses the web application (RP). -2. The client application redirects the user to Logto (IdP) for [authentication](https://auth.wiki/authentication). -3. The OIDC provider checks the user's sign-in session status. If no session exists or the session has expired, the user is prompted to sign in. -4. The user interacts with the sign-in page to get authenticated. -5. After successful sign-in, Logto creates a new session for the user and redirects back to the client application with an authorization code. -6. The OIDC provider creates a new sign-in session and authentication grant for the user. -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. - -## Components \{#components} - -### Centralized sign-in session managed by Logto \{#centralized-sign-in-session-managed-by-logto} - -In the above flow, the centralized sign-in session is managed by Logto. The session is created when the user successfully signs in and is destroyed when the user signs out. The session is also destroyed when the user's session expires. - -Logto sign-in session is managed using session cookies. The session cookie is set when the user signs in. All the authentication requests are validated against the session cookie. If the session cookie is present and valid the user with be automatically authenticated and directly redirected to the client application with the authorization code. Otherwise, the user will be prompted to sign in. - -1. Shared Logto session cookie - For a user who signs in to multiple client applications from the same user agent (e.g., browser), the user will have a shared session cookie under the Logto domain. This means that the user only needs to sign in once and get automatically authenticated for other client applications. - - ```mermaid - flowchart TD - subgraph User [User agent A] - U[User] - - subgraph Layer1 [Client domain A] - A[Client Application A] - end - - subgraph Layer1 [Client domain B] - B[Client Application B] - end - - subgraph Layer2 [Logto domain] - C{{Logto sign-in session?}} - D[sign-in page] - end - end - - U --> |Sign-in| A - A --> |Redirect to Logto| C - U --> |Sign-in| B - B --> |Redirect to Logto| C - C --> |No| D - D --> |Create session| C - ``` - -2. Isolated Logto session cookie - For a user who signs in to different client applications from different devices or browsers, the user will have isolated session cookies under the Logto domain. This means that the user needs to sign in for each client application separately. - - ```mermaid - flowchart TD - U[User] - - subgraph DeviceA [User agent A] - subgraph Layer1 [Client domain A] - A[Client Application A] - end - - subgraph Layer2 [Logto domain] - C{{Logto sign-in session?}} - D[sign-in page] - end - end - - subgraph DeviceB [User agent B] - subgraph Layer3 [Client domain B] - B[Client Application B] - end - - subgraph Layer4 [Logto domain] - E{{Logto sign-in session?}} - F[sign-in page] - end - end - - U --> |Sign-in| A - A --> |Redirect to Logto| C - U --> |Sign-in| B - B --> |Redirect to Logto| E - C --> |No| D - E --> |No| F - D --> |Create session| C - F --> |Create session| E - ``` - -## Distributed authentication status managed by the client applications \{#distributed-authentication-status-managed-by-the-client-applications} - -Each client application maintains its own authentication status. Whether a Native, SPA, or Web application, all have their own way of managing the user's authentication status. - -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. - -- 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. +### Isolated session cookies (different devices/browsers) \{#isolated-session-cookies-different-devices-browsers} + +Different browsers/devices hold different Logto cookies, so sign-in session state is isolated. + +```mermaid +flowchart TD + U[User] + A["Client Application A (Client domain A)"] + C{"Logto session exists? (Device A, Logto domain)"} + D["Sign-in page (Device A, Logto domain)"] + + subgraph DeviceA["User agent A"] + A + C + D + end + + B["Client Application B (Client domain B)"] + E{"Logto session exists? (Device B, Logto domain)"} + F["Sign-in page (Device B, Logto domain)"] + + subgraph DeviceB["User agent B"] + B + E + F + end + + U -->|Sign in| A + A -->|Redirect to Logto| C + U -->|Sign in| B + B -->|Redirect to Logto| E + C -->|No| D + E -->|No| F + D -->|Create session| C + F -->|Create session| E +``` ## Sign-out mechanisms \{#sign-out-mechanisms} -### Clear tokens and local session at the client side \{#clear-tokens-and-local-session-at-the-client-side} +### 1) Client-side-only sign-out \{#1-client-side-only-sign-out} -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. +Client app clears its own local session and tokens (ID/access/refresh tokens). This signs user out from that app's local state only. -### Clear sign-in session at Logto \{#clear-sign-in-session-at-logto} +- Logto session may still be active. +- Other apps under same Logto session may still SSO. -To explicitly sign out the user and clear the session at Logto, the client application need to redirect the user to the Logto's **end session endpoint**. +### 2) End-session at Logto (global sign-out in current Logto implementation) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -E.g. `https://{your-logto-domain}/oidc/session/end` +To clear centralized Logto session, app redirects user to the end session endpoint, for example: -The **end session endpoint** is a standard OIDC endpoint that allows the client application to notify the authorization server that the user has signed out. The endpoint will clear the centralized sign-in session at Logto. +`https://{your-logto-domain}/oidc/session/end` -Once the session is cleared, any subsequent authorization requests will require the user to sign in again. +In current Logto SDK behavior: -If a **post-logout redirect URI** is provided, the user will be redirected to the specified URI after the session is cleared. Otherwise, the user will be redirected to the default post-logout page hosted by Logto. +1. `signOut()` redirects to `/session/end`. +2. Then it goes to `/session/end/confirm`. +3. Default confirm form auto-posts `logout=true`. -## Federated sign-out: Back-channel logout \{#federated-sign-out-back-channel-logout} +As a result, current SDK sign-out is treated as **global sign-out**. -For more consistent sign-out management, Logto supports [back-channel logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). Back-channel logout is a mechanism that allows Logto to notify all the client applications under the same sign-in session when the user signs out. +### What happens during global sign-out \{#what-happens-during-global-sign-out} -This is particularly useful in scenarios where the user signs out from one client application and expects to be signed out from all other client applications under the same Logto sign-in session. +```mermaid +flowchart TD + A["Client starts sign-out"] --> B["/session/end"] + B --> C["/session/end/confirm (logout=true)"] + C --> D["Revoke centralized Logto session"] + D --> E{"Check per-app grant"} + E -->|"offline_access not granted"| F["Revoke grant"] + E -->|"offline_access granted"| G["Keep grant until grant TTL expires"] +``` -To enable back-channel logout for your client applications, go to the application details page in the Logto dashboard, and register a back-channel logout URI. Logto will send a logout token to all the registered URI when the user initiates a sign-out request from any client application. +During global sign-out: -If your client application requires the sign-in session to be included in the logout token, turn on the `Is session required` settings in the back-channel logout configuration. A `sid` claim will be included in the logout token to identify the user's sign-in session at Logto. +- The centralized Logto session is revoked. +- Related app grants are handled per app authorization state: + - If `offline_access` is **not** granted, related grants are revoked. + - If `offline_access` **is** granted, grants are not revoked by end-session. +- For `offline_access` cases, refresh tokens and grants remain valid until grant expiration. -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. +## Grant lifetime and `offline_access` impact \{#grant-lifetime-and-offline-access-impact} -Sign-out actions for each client application when receiving the logout token: +- Default Logto grant TTL is **180 days**. +- If `offline_access` is granted, end-session does not revoke that app grant by default. +- Refresh token chain associated with that grant can continue until the grant expires (or is explicitly revoked). -- Validate the logout token. -- Clear the local session and remove tokens from local storage or session storage. +## Federated sign-out: back-channel logout \{#federated-sign-out-back-channel-logout} -## Sign-out methods in Logto SDKs \{#sign-out-methods-in-logto-sdks} +For cross-app consistency, Logto supports [back-channel logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). + +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. + +If `Is session required` is enabled in app back-channel settings, the logout token includes `sid` to identify the Logto session. + +Typical flow: -If you are integrating Logto with your client application using Logto's SDKs: +1. User initiates sign-out from one app. +2. Logto processes end-session and sends logout token(s) to registered back-channel logout URI(s). +3. Each app validates logout token and clears its own local session/tokens. -- For SPA and web applications, the `client.signOut()` method will clear the local token storage and redirect the user to the Logto's end session endpoint. You may specify a **post-logout redirect URI** to redirect the user after the session is cleared. -- For native applications (including hybrid apps like **React Native** and **Flutter**), only the local token storage is cleared. This is because in native application, we use the sessionless webview to handle the sign-in process. No session cookies are stored in the native browser, so there is no need to clear the sign-in session at Logto. Each authentication request is a standalone request that does not carry any session cookies. +## Sign-out methods in Logto SDKs \{#sign-out-methods-in-logto-sdks} + +- **SPA and web**: `client.signOut()` clears local token storage and redirects to Logto end-session endpoint. You may provide a post-logout redirect URI. +- **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. @@ -183,19 +225,16 @@ For native applications that does not support sessionless webview or does not re ## Enforce re-authentication on every access \{#enforce-re-authentication-on-every-access} -In high-security scenarios—such as verifying a user's identity before sensitive actions—you may want to require the user to re-authenticate on every access. To enforce this behavior, include `prompt=login` in your authentication 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 ``` -This guarantees the user is re-authenticated and explicitly consents to offline access. - ## FAQs \{#faqs}
@@ -205,8 +244,8 @@ This guarantees the user is re-authenticated and explicitly consents to offline -- Ensure that the back-channel logout URI is correctly registered in the Logto dashboard. -- Ensure that your client application has an valid active sign-in session and is the same session as the one that initiated the sign-out request. +- Ensure back-channel logout URI is correctly registered in Logto dashboard. +- Ensure your app has an active sign-in state for the same user/session context.
diff --git a/docs/quick-starts/fragments/_scope-claim-list.md b/docs/quick-starts/fragments/_scope-claim-list.md index e329a54b7fd..7e17f98c8fb 100644 --- a/docs/quick-starts/fragments/_scope-claim-list.md +++ b/docs/quick-starts/fragments/_scope-claim-list.md @@ -1,6 +1,6 @@ Here's the list of supported scopes and the corresponding claims: -### Standard OIDC scopes +### Standard OIDC scopes {#standard-oidc-scopes} **`openid`** (default) @@ -46,7 +46,7 @@ Please refer to the [OpenID Connect Core 1.0](https://openid.net/specs/openid-co Scopes marked with **(default)** are always requested by the Logto SDK. Claims under standard OIDC scopes are always included in the ID token when the corresponding scope is requested — they cannot be turned off. ::: -### Extended scopes +### Extended scopes {#extended-scopes} The following scopes are extended by Logto and will return claims through the [userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). These claims can also be configured to be included directly in the ID token through Console > Custom JWT. See [Custom ID token](/developers/custom-id-token) for more details. diff --git a/docs/user-management/README.mdx b/docs/user-management/README.mdx index f7cb8fd3438..c29f07b4a40 100644 --- a/docs/user-management/README.mdx +++ b/docs/user-management/README.mdx @@ -12,6 +12,7 @@ User management is a significant area of focus for Logto. You can access your us - Checking user logs. - Assigning roles for access control. - Create and manage personal access tokens. +- Managing user sessions. ## Features for user management \{#features-for-user-management} diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx index 4c83cd9ccba..9701ab98ca9 100644 --- a/docs/user-management/manage-users.mdx +++ b/docs/user-management/manage-users.mdx @@ -55,6 +55,7 @@ To view the details of a user, simply click on the corresponding row in the user - 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. :::warning @@ -88,6 +89,13 @@ After you reset the password, copy and send it to the end-user. Once the "Reset You cannot set a specific password for users in the Logto Console, but you can use the [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` to specify a password. +### Manage user active sessions \{#manage-user-active-sessions} + +On the "User details" page, navigate to the "Session details" page by clicking on the "Manage" button of a specific session. Here you can view detailed information about the session, such as the device, location, and login time. If you want to log out the user from this session, simply click the "Revoke session" button at the right top corner, and the session will be immediately revoked. + +- By default revoking a session on the Console will also revoke all the first-party app grants associated with that session, and the user will need to sign in again to restore access. Any pre-issued opaque access tokens and refresh tokens to first-party apps will also be revoked immediately. +- For third-party apps with `offline_access` scope, revoking a session does not revoke the app grant by default, any pre-issued refresh tokens can still be used until the grant expires. + ## Password compliance check \{#password-compliance-check} After you update the [password policy](/security/password-policy) in Logto, existing users can still sign in with their current passwords. Only newly created accounts will be required to follow the updated password policy.