From 618e115fc9807daf117bb156f778a062b1947aba Mon Sep 17 00:00:00 2001 From: simeng-li Date: Mon, 30 Mar 2026 17:09:03 +0800 Subject: [PATCH 1/4] feat(docs): add session management docs add session management docs --- docs/developers/signing-keys.mdx | 2 +- .../account-settings/by-account-api.mdx | 55 +++++- .../account-settings/by-management-api.mdx | 15 ++ docs/end-user-flows/sign-out.mdx | 156 ++-------------- .../application-data-structure.mdx | 19 ++ docs/sessions/README.mdx | 168 ++++++++++++++++++ docs/sessions/grants-management.mdx | 71 ++++++++ docs/sessions/manage-user-sessions.mdx | 78 ++++++++ docs/sessions/session-configs.mdx | 107 +++++++++++ docs/user-management/manage-users.mdx | 15 ++ src/assets/sessions.svg | 6 + src/sidebar/docs.ts | 8 + src/theme/DocSidebarItem/Category/icons.ts | 2 + 13 files changed, 555 insertions(+), 147 deletions(-) create mode 100644 docs/sessions/README.mdx create mode 100644 docs/sessions/grants-management.mdx create mode 100644 docs/sessions/manage-user-sessions.mdx create mode 100644 docs/sessions/session-configs.mdx create mode 100644 src/assets/sessions.svg diff --git a/docs/developers/signing-keys.mdx b/docs/developers/signing-keys.mdx index 0dcc7732e27..0685bbb417f 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#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. +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](/sessions#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/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx index e3ea2ef58e5..6e15d72e5c8 100644 --- a/docs/end-user-flows/account-settings/by-account-api.mdx +++ b/docs/end-user-flows/account-settings/by-account-api.mdx @@ -24,6 +24,7 @@ Some frequent use cases are listed below: - Update user identities including email, phone, and social connections - Manage MFA factors (verifications) - Manage user sessions +- Manage user authorized apps (grants) 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). @@ -52,6 +53,7 @@ Once enabled, configure per-field permissions for identifiers, profile data, and - 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. + - This same `Sessions` field permission also controls user authorized apps (grants) APIs (view and revoke grants). - 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} @@ -74,7 +76,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 + UserScope.Sessions, // To manage user sessions and app grants ], }; ``` @@ -713,3 +715,54 @@ Optional query parameters: - `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. + +### Manage user authorized apps (grants) \{#manage-user-authorized-apps-grants} + +Use user authorized apps (grants) APIs when users need to review and revoke authorized apps from their account settings page. + +:::note + +- App grant APIs share the same permission model as session APIs. +- `UserScope.Sessions` scope is required. +- `Sessions` field in account center settings must be enabled: + - `ReadOnly` or `Edit` to list grants. + - `Edit` to revoke grants. + +::: + +**List active app grants** + +To list active app grants of the current user, use the [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) endpoint. + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Optional query parameter: + +- `appType=firstParty`: Return first-party app grants only. +- `appType=thirdParty`: Return third-party app grants only. +- Omit `appType`: Return all active grants. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**Revoke app grant by grant ID** + +To revoke a specific app grant, use the [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) endpoint. + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +When a grant is revoked, previously issued opaque access tokens and refresh tokens for that grant are invalidated. 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 1759b581139..bab7515d303 100644 --- a/docs/end-user-flows/account-settings/by-management-api.mdx +++ b/docs/end-user-flows/account-settings/by-management-api.mdx @@ -202,3 +202,18 @@ Personal access tokens provide a secure way for users to grant [access token](ht | 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. | + +### Manage user authorized apps (grants) \{#manage-user-authorized-apps-grants} + +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | List active app grants for the user. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | Revoke a specific app grant by ID. | + +Optional query parameter for grant listing: + +- `appType=firstParty`: Return first-party app grants only. +- `appType=thirdParty`: Return third-party app grants only. +- Omit `appType`: Return all active grants. + +When a grant is revoked, previously issued opaque access tokens and refresh tokens for that grant are invalidated. diff --git a/docs/end-user-flows/sign-out.mdx b/docs/end-user-flows/sign-out.mdx index b22142c451d..277fa5fda1d 100644 --- a/docs/end-user-flows/sign-out.mdx +++ b/docs/end-user-flows/sign-out.mdx @@ -1,155 +1,15 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # Sign-out -Sign-out in Logto (as an OIDC identity provider) involves both: +Sign-out in Logto involves two layers: -- A **centralized Logto session** (browser cookie under Logto domain), and -- **Distributed client-side auth state** (tokens and local app session in each app). +- **Logto session sign-out**: Ends the centralized sign-in session under the Logto domain. +- **App sign-out**: Clears local session state and tokens in your client application. -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 -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 -``` - -### 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 -``` +To better understand how sessions work in Logto, see [Sessions](/sessions). ## Sign-out mechanisms \{#sign-out-mechanisms} @@ -174,6 +34,12 @@ In current Logto SDK behavior: As a result, current SDK sign-out is treated as **global sign-out**. +:::note + +- **Global sign-out**: Revoke the centralized Logto session. + +::: + ### What happens during global sign-out \{#what-happens-during-global-sign-out} ```mermaid diff --git a/docs/integrate-logto/application-data-structure.mdx b/docs/integrate-logto/application-data-structure.mdx index 93c0ba1f805..7e2854bb48e 100644 --- a/docs/integrate-logto/application-data-structure.mdx +++ b/docs/integrate-logto/application-data-structure.mdx @@ -179,6 +179,25 @@ To ensure the refresh token TTL setting takes full effect, make sure to include The OpenID Connect backchannel logout endpoint. See [Federated sign-out: Back-channel logout](#) for more information. +### Max allowed grants (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` is an optional app-level field under `customClientMetadata` that controls the maximum number of concurrent active grants per user for the current app. + +- **Default**: `undefined` (no limit) +- **When configured**: On each successful authorization, Logto checks the total active grants for the user in the current app (across browsers and devices). If the limit is exceeded, Logto revokes the oldest grants. + +This setting is useful when you want to cap concurrent authenticated devices per app. + +:::note + +This field is not supported for: + +- Machine-to-machine apps +- Protected apps +- SAML apps + +::: + ### Custom data \{#custom-data} Additional custom application info not listed in the pre-defined application properties, users can define their own custom data fields according to their specific needs, such as business-specific settings and configurations. diff --git a/docs/sessions/README.mdx b/docs/sessions/README.mdx new file mode 100644 index 00000000000..d009ff93c87 --- /dev/null +++ b/docs/sessions/README.mdx @@ -0,0 +1,168 @@ +# Sessions + +Sessions in Logto define how authentication state is created, shared, refreshed, and revoked across apps, browsers, and devices. + +In practice, users experience "signed in" as one state, but the system state is split into multiple layers. Understanding these layers is the key to designing predictable SSO, token renewal, and sign-out behavior. + +## Session model in Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto domain"] + S["Sign-in session"] + G1["Grant (App A)"] + G2["Grant (App B)"] + end + + subgraph AppA ["App domain A"] + A["Local session / tokens"] + end + + subgraph AppB ["App domain B"] + B["Local session / tokens"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto sign-in session**: Centralized sign-in state stored as Logto-domain cookies. This controls SSO availability in the current browser context. +- **Grant**: App-specific authorization state for `user + client app`. Grants are the bridge between centralized sign-in and app token issuance. +- **App-local session/tokens**: Local authentication state in each app (ID/access/refresh tokens, app session cookie, etc.). + +## Core concepts \{#core-concepts} + +### What is a Logto session? \{#what-is-a-logto-session} + +A Logto session is the centralized authentication state created after successful sign-in. If it is still valid, Logto can authenticate users silently for other apps in the same tenant. If it does not exist, users must sign in again. + +### What are grants? \{#what-are-grants} + +A grant is app-level authorization state tied to a specific user and client app. + +- One Logto session can have grants for multiple apps. +- Tokens for an app are issued under that app's grant. +- Revoking a grant affects that app's ability to continue token-based access. + +### How session, grants, and app auth state relate \{#how-session-grants-and-app-auth-state-relate} + +- **Session** answers: "Can this browser do SSO with Logto right now?" +- **Grant** answers: "Is this user authorized for this client app?" +- **App-local session** answers: "Does this app currently treat user as signed in?" + +## Sign-in and session creation \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as Client application + end + + box Logto + participant OIDC as OIDC provider + participant SignIn as Sign-in page + end + + User ->> Client: Access application + Client ->> OIDC: Authorization request + OIDC -->> OIDC: Check existing Logto session + OIDC ->> SignIn: Prompt sign-in if needed + SignIn ->> OIDC: User authenticates + OIDC -->> OIDC: Create session and app grant + OIDC ->> Client: Return authorization code + Client ->> OIDC: Exchange code for tokens + OIDC -->> Client: Return tokens +``` + +## Session topology across apps and devices \{#session-topology-across-apps-and-devices} + +### Same browser: shared Logto session \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[User] + A["Client App A"] + B["Client App B"] + C{"Logto session exists?"} + D["Logto sign-in page"] + + U --> A + A --> C + U --> B + B --> C + C -->|No| D +``` + +Apps in the same browser can share centralized Logto session state, so SSO can happen without repeated credential input. + +### Different browsers or devices: isolated Logto sessions \{#different-browsers-or-devices-isolated-logto-sessions} + +Each browser/device has separate cookie storage. A valid session on Device A does not imply a valid session on Device B. + +## Session lifecycle \{#session-lifecycle} + +### 1. Create \{#1-create} + +After user authentication, Logto creates a centralized session and an app-specific grant. + +### 2. Reuse (SSO) \{#2-reuse-sso} + +As long as session cookies are valid in the same browser, new authorization requests can often complete silently. + +### 3. Renew tokens \{#3-renew-tokens} + +App access usually continues through token refresh flows (when enabled). This is app-level continuity, separate from whether centralized Logto session still exists. + +### 4. Revoke/expire \{#4-revokeexpire} + +Revocation can happen at different layers: + +- Local app sign-out removes app-local tokens/session. +- End-session removes centralized Logto session. +- Grant revocation removes app-level authorization continuity. + +## Design recommendations \{#design-recommendations} + +- Keep app-local session handling explicit in your app code. +- Treat Logto session, grants, and app-local session as separate layers. +- Choose whether sign-out should be app-local only or global. +- Use [back-channel logout](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) when multi-app consistency is required. +- For sign-out behavior and implementation details, see [Sign-out](/end-user-flows/sign-out). + +## Best practices for revoking access \{#best-practices-for-revoking-access} + +Use different revoke strategies based on your goal: + +- **Revoke access from your first-party apps**: + Revoke the target session with `revokeGrantsTarget=firstParty`. + This signs the user out across first-party apps associated with that session, which creates a consistent logout experience. + At the same time, grants for third-party apps that have `offline_access` granted can remain available for ongoing integrations. + See [Manage user sessions](/sessions/manage-user-sessions) for session revoke details. + +- **Revoke access to third-party apps**: + Choose one of the following: + + - Revoke the session with `revokeGrantsTarget=all` to revoke all grants associated with that session. + - Revoke specific grants directly through grant management APIs to remove third-party app authorizations without forcing full session sign-out. + See [Manage user authorized apps (grants)](/sessions/grants-management) for grant-specific revoke strategies. + +- **When using Logto Console**: + On the user details page, Logto provides both session management and authorized third-party app management out of the box. + - Revoking a session revokes first-party app grants as well, to keep first-party logout behavior consistent. + - Revoking a third-party app authorization revokes grants for that third-party app while keeping the original session status unchanged. + +## Related resources \{#related-resources} + +Manage user sessions +Manage user authorized apps (grants) +Session configuration +Sign-out +Sign-up and sign-in + + Understand authentication flow + diff --git a/docs/sessions/grants-management.mdx b/docs/sessions/grants-management.mdx new file mode 100644 index 00000000000..44e71302653 --- /dev/null +++ b/docs/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# Manage user authorized apps (grants) + +App grants represent user authorization state for specific client applications. + +Use grants management when users or admins need to review authorized apps and revoke app access without revoking the whole Logto session. + +When grants are revoked, previously issued opaque access tokens and refresh tokens for those grants are invalidated. + +## Choose the right path \{#choose-the-right-path} + +| Scenario | Recommended path | +| ----------------------------------------------------------- | ---------------- | +| Let signed-in users manage their own app authorizations | Account API | +| Let admins or support teams manage grants for a target user | Management API | +| Let operators manage third-party app authorizations in UI | Admin Console | + +## Direct grant management APIs \{#direct-grant-management-apis} + +### Account API (self-service) \{#account-api-self-service} + +Use Account API in end-user account settings pages: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- Reference: [Manage user authorized apps (grants)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (admin tools) \{#management-api-admin-tools} + +Use Management API in admin tools and support workflows: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- Reference: [Manage user authorized apps (grants)](/end-user-flows/account-settings/by-management-api#user-app-grant-management) + +### Filter grant list by app type \{#filter-grant-list-by-app-type} + +Grant listing endpoints support optional query parameter `appType`: + +- `appType=firstParty`: List first-party app grants only. +- `appType=thirdParty`: List third-party app grants only. +- Omit `appType`: Return all active grants. + +## Manage third-party app authorizations in Console \{#manage-third-party-app-authorizations-in-console} + +In Logto Console, use the user details page to view and revoke authorized third-party apps. + +- Reference: [Manage user authorized third-party apps](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## Revoke grants when revoking a session \{#revoke-grants-when-revoking-a-session} + +When revoking a session via `DELETE /api/my-account/sessions/{sessionId}`, use optional query parameter `revokeGrantsTarget` to control grant revocation scope: + +- `all`: Revoke grants for all apps associated with the session. +- `firstParty`: Revoke grants for first-party apps only. + +For session-level behavior and endpoint context, see [Manage user sessions](/sessions/manage-user-sessions) and [Sign-out](/end-user-flows/sign-out). + +## Related resources \{#related-resources} + +Sessions +Manage user sessions + + Account settings by Account API: Manage user authorized apps (grants) + + + Account settings by Management API: Manage user authorized apps (grants) + diff --git a/docs/sessions/manage-user-sessions.mdx b/docs/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..3b36f6de42d --- /dev/null +++ b/docs/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# Manage user sessions + +User session management helps users and admins review active sign-in states and revoke sessions when needed. + +In Logto, you can manage sessions through three common paths: + +- **Account API**: For end-user self-service in your product account settings page. +- **Management API**: For admin or support tools to manage sessions for any user. +- **Admin Console**: For operator workflows in Logto Console without building custom tooling. + +## Choose the right API \{#choose-the-right-api} + +| Scenario | Recommended API | +| ------------------------------------------------------- | --------------- | +| Let signed-in users manage their own active sessions | Account API | +| Let admins or support teams manage sessions for a user | Management API | +| Let operators manage sessions directly in Logto Console | Admin Console | + +## View active sessions \{#view-active-sessions} + +### Account API (self-service) \{#account-api-self-service} + +Use the Account API session endpoint to list the current user's active sessions. + +- Reference section: [Manage user sessions](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +Before exposing this capability to end users, make sure session management is enabled in Account center settings and your app requests the required Account API scope. + +### Management API (admin tools) \{#management-api-admin-tools} + +Use Management API when your admin system needs to list sessions for a target user. + +- Reference section: [User session management](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Optional details endpoint: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## Revoke sessions \{#revoke-sessions} + +### Account API (end user revokes own sessions) \{#account-api-end-user-revokes-own-sessions} + +End users can revoke a specific session from their own session list. + +- Reference section: [Manage user sessions](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +For sensitive operations, Account API session management requires user verification before access. See [Get a verification record id](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id). + +### Management API (admin revokes user sessions) \{#management-api-admin-revokes-user-sessions} + +Admins can revoke a target user's session by user ID and session ID. + +- Reference section: [User session management](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +If your team manages users directly in Logto Console, you can review active sessions and revoke specific sessions from the user detail page. + +- Reference section: [Manage user active sessions](/user-management/manage-users#manage-user-active-sessions) + +## Related resources \{#related-resources} + +Sessions +Manage user authorized apps (grants) + + Account settings by Account API: Manage user sessions + + + Account settings by Management API: User session management + + + User management: Manage user active sessions + diff --git a/docs/sessions/session-configs.mdx b/docs/sessions/session-configs.mdx new file mode 100644 index 00000000000..117fb009c21 --- /dev/null +++ b/docs/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# Session configuration + +Session configuration defines tenant-level controls for how long Logto sign-in sessions stay active and how session-related access policies are enforced. + +This page covers: + +- Session TTL configuration +- Max concurrent authenticated devices per app + +## Session TTL configuration \{#session-ttl-configuration} + +Session TTL determines the maximum lifetime of the Logto OIDC sign-in session. +It is a **tenant-level setting**: once configured, it applies to all apps and authentication flows in that tenant. + +### Default behavior \{#default-behavior} + +- By default, session TTL is **14 days**. +- If no custom TTL is configured, Logto continues to use this default value. + +### Configure via Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +You can configure session TTL in Console under: + +Console > Tenant > Settings > OIDC settings + +Use **Session maximum time to live** to update the value. + +:::note + +Console uses **days** for input and display, while the underlying OIDC session config/API uses **seconds**. + +::: + +### Configure via Management API \{#configure-via-management-api} + +Use these endpoints to read and update OIDC session configuration: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +Example (`ttl` in seconds): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` seconds = 14 days. + +:::note + +For OSS deployments, restart the service instance after changing `logto-config` so the server can pick up the latest OIDC settings. + +To apply OIDC config updates automatically without restarting the service, [enable central redis cache](/logto-oss/central-cache). + +::: + +## Max concurrent authenticated devices per app \{#max-concurrent-authenticated-devices-per-app} + +Max concurrent authenticated devices per app is an app-level control that limits how many active grants each user can keep for a specific app. + +This is configured through the `maxAllowedGrants` field in application `customClientMetadata`. +Learn more in [Application data structure](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants). + +### Behavior \{#behavior} + +When `maxAllowedGrants` is set, Logto evaluates the user's active grants for the current app on every successful authorization. +If the number of active grants exceeds the limit, Logto revokes the oldest grants first. + +If `maxAllowedGrants` is not set, there is no concurrency limit. + +### Configure via Logto Console \{#configure-via-logto-console} + +You can configure this in each app's details page under: + + + Console > Applications > Application details > Concurrent device limit + + +Set the maximum number of concurrent active grants (devices) per user for the current app. + +:::note + +This setting is not supported for machine-to-machine apps, protected apps, and SAML apps. + +::: + +## Related resources \{#related-resources} + +Sessions +Manage user sessions +Manage user authorized apps (grants) + + Application data structure: maxAllowedGrants + +Interact with Management API diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx index 3de22915071..5a98f697785 100644 --- a/docs/user-management/manage-users.mdx +++ b/docs/user-management/manage-users.mdx @@ -97,6 +97,21 @@ On the "User details" page, navigate to the "Session details" page by clicking o - 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. +### Manage user authorized third-party apps \{#manage-user-authorized-third-party-apps} + +On the "User details" page, you can use the "Authorized third-party apps" section to review app authorization status for the user. +This section is backed by user authorized apps (grants) management APIs. + +For each authorized app, Console shows: + +- App name +- App ID +- Access creation time + +If you need to remove access, click the revoke action and confirm in the modal. + +Revoking an app authorization removes all active third-party grants associated with that app for the user. It will also revoke any pre-issued opaque access tokens and refresh tokens for that app immediately. + ## 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. diff --git a/src/assets/sessions.svg b/src/assets/sessions.svg new file mode 100644 index 00000000000..839cf889d50 --- /dev/null +++ b/src/assets/sessions.svg @@ -0,0 +1,6 @@ + + + diff --git a/src/sidebar/docs.ts b/src/sidebar/docs.ts index 78066d90437..80243c3bdec 100644 --- a/src/sidebar/docs.ts +++ b/src/sidebar/docs.ts @@ -46,11 +46,19 @@ const docsSidebar: SidebarConfig = [ }, { type: 'category', + key: 'main-authorization', label: 'Authorization', link: { type: 'doc', id: 'authorization/README' }, items: [{ type: 'autogenerated', dirName: 'authorization' }], customProps: { id: 'authorization' }, }, + { + type: 'category', + label: 'Sessions', + link: { type: 'doc', id: 'sessions/README' }, + items: [{ type: 'autogenerated', dirName: 'sessions' }], + customProps: { id: 'sessions' }, + }, { type: 'category', label: 'User management', diff --git a/src/theme/DocSidebarItem/Category/icons.ts b/src/theme/DocSidebarItem/Category/icons.ts index fe7a6c27216..5f6d5d01f8c 100644 --- a/src/theme/DocSidebarItem/Category/icons.ts +++ b/src/theme/DocSidebarItem/Category/icons.ts @@ -12,6 +12,7 @@ import LightBulb from '@site/src/assets/light-bulb.svg'; import OpenSource from '@site/src/assets/open-source.svg'; import Organization from '@site/src/assets/organization.svg'; import Security from '@site/src/assets/security.svg'; +import Sessions from '@site/src/assets/sessions.svg'; import UserFlows from '@site/src/assets/user-flows.svg'; import UserManagement from '@site/src/assets/user-management.svg'; import Vault from '@site/src/assets/vault.svg'; @@ -28,6 +29,7 @@ const icons: IconMap = Object.freeze({ introduction: Introduction, 'integrate-logto': Integrate, 'end-user-flows': UserFlows, + sessions: Sessions, connectors: Connectors, customization: Customization, authorization: Authorization, From c9de1b696a64465f922e485218f1a80a28aa7c30 Mon Sep 17 00:00:00 2001 From: simeng-li Date: Mon, 30 Mar 2026 17:30:49 +0800 Subject: [PATCH 2/4] fix(docs): fix broken links fix broken anchor links --- docs/sessions/grants-management.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sessions/grants-management.mdx b/docs/sessions/grants-management.mdx index 44e71302653..74702de570b 100644 --- a/docs/sessions/grants-management.mdx +++ b/docs/sessions/grants-management.mdx @@ -34,7 +34,7 @@ Use Management API in admin tools and support workflows: - `GET /api/users/{userId}/grants` - `DELETE /api/users/{userId}/grants/{grantId}` -- Reference: [Manage user authorized apps (grants)](/end-user-flows/account-settings/by-management-api#user-app-grant-management) +- Reference: [Manage user authorized apps (grants)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) ### Filter grant list by app type \{#filter-grant-list-by-app-type} From e1107c3ec339f5a08d482e77da5c3f7c7018791d Mon Sep 17 00:00:00 2001 From: simeng-li Date: Tue, 31 Mar 2026 10:09:33 +0800 Subject: [PATCH 3/4] chore(docs): add i18n add i18n # Conflicts: # i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx # Conflicts: # i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/de/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/es/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/fr/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/ja/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/ko/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/th/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx # i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/mfa/configure-mfa.mdx # i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-cloud/private-cloud.mdx --- .../current/developers/signing-keys.mdx | 38 +- .../account-settings/by-account-api.mdx | 359 ++++++++------ .../account-settings/by-management-api.mdx | 186 +++---- .../current/end-user-flows/sign-out.mdx | 232 ++------- .../application-data-structure.mdx | 132 ++--- .../current/sessions/README.mdx | 168 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 103 ++-- .../current/developers/signing-keys.mdx | 38 +- .../account-settings/by-account-api.mdx | 299 +++++++----- .../account-settings/by-management-api.mdx | 169 ++++--- .../current/end-user-flows/sign-out.mdx | 232 ++------- .../application-data-structure.mdx | 126 +++-- .../current/sessions/README.mdx | 170 +++++++ .../current/sessions/grants-management.mdx | 73 +++ .../current/sessions/manage-user-sessions.mdx | 80 +++ .../current/sessions/session-configs.mdx | 109 +++++ .../current/user-management/manage-users.mdx | 79 +-- .../current/developers/signing-keys.mdx | 40 +- .../account-settings/by-account-api.mdx | 389 ++++++++------- .../account-settings/by-management-api.mdx | 227 +++++---- .../current/end-user-flows/sign-out.mdx | 230 ++------- .../application-data-structure.mdx | 143 +++--- .../current/sessions/README.mdx | 170 +++++++ .../current/sessions/grants-management.mdx | 73 +++ .../current/sessions/manage-user-sessions.mdx | 80 +++ .../current/sessions/session-configs.mdx | 109 +++++ .../current/user-management/manage-users.mdx | 101 ++-- .../current/developers/signing-keys.mdx | 52 +- .../account-settings/by-account-api.mdx | 462 ++++++++++-------- .../account-settings/by-management-api.mdx | 201 ++++---- .../current/end-user-flows/sign-out.mdx | 240 ++------- .../application-data-structure.mdx | 161 +++--- .../current/sessions/README.mdx | 168 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 135 ++--- .../current/developers/signing-keys.mdx | 38 +- .../account-settings/by-account-api.mdx | 387 ++++++++------- .../account-settings/by-management-api.mdx | 195 ++++---- .../current/end-user-flows/sign-out.mdx | 228 ++------- .../application-data-structure.mdx | 148 +++--- .../current/sessions/README.mdx | 168 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 123 +++-- .../current/developers/signing-keys.mdx | 28 +- .../account-settings/by-account-api.mdx | 313 +++++++----- .../account-settings/by-management-api.mdx | 191 ++++---- .../current/end-user-flows/sign-out.mdx | 236 ++------- .../application-data-structure.mdx | 147 +++--- .../current/sessions/README.mdx | 170 +++++++ .../current/sessions/grants-management.mdx | 72 +++ .../current/sessions/manage-user-sessions.mdx | 80 +++ .../current/sessions/session-configs.mdx | 109 +++++ .../current/user-management/manage-users.mdx | 97 ++-- .../current/developers/signing-keys.mdx | 50 +- .../account-settings/by-account-api.mdx | 399 ++++++++------- .../account-settings/by-management-api.mdx | 261 +++++----- .../current/end-user-flows/sign-out.mdx | 250 +++------- .../application-data-structure.mdx | 154 +++--- .../current/sessions/README.mdx | 168 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 119 +++-- .../current/developers/signing-keys.mdx | 44 +- .../account-settings/by-account-api.mdx | 415 +++++++++------- .../account-settings/by-management-api.mdx | 215 ++++---- .../current/end-user-flows/sign-out.mdx | 250 +++------- .../application-data-structure.mdx | 155 +++--- .../current/sessions/README.mdx | 165 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 127 ++--- .../current/developers/signing-keys.mdx | 52 +- .../account-settings/by-account-api.mdx | 439 +++++++++-------- .../account-settings/by-management-api.mdx | 257 +++++----- .../current/end-user-flows/sign-out.mdx | 248 +++------- .../application-data-structure.mdx | 168 ++++--- .../current/sessions/README.mdx | 168 +++++++ .../current/sessions/grants-management.mdx | 71 +++ .../current/sessions/manage-user-sessions.mdx | 78 +++ .../current/sessions/session-configs.mdx | 107 ++++ .../current/user-management/manage-users.mdx | 147 +++--- 90 files changed, 8814 insertions(+), 5277 deletions(-) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/README.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 0d3c91f2b4b..26e05074e4d 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,26 +7,26 @@ sidebar_position: 5 # Signaturschlüssel -Logto [OIDC-Signaturschlüssel](https://auth.wiki/signing-key), auch bekannt als „OIDC-Private Keys“ und „OIDC-Cookie-Keys“, sind die Signaturschlüssel, die zum Signieren von JWTs ([Zugangstokens](https://auth.wiki/access-token) und [ID-Tokens](https://auth.wiki/id-token)) sowie Browser-Cookies in Logto [Anmeldesitzungen](/end-user-flows/sign-out#what-is-a-logto-session) verwendet werden. Diese Signaturschlüssel werden beim Initialisieren der Logto-Datenbank ([Open-Source](/logto-oss)) oder beim Erstellen eines neuen Mandanten ([Cloud](/logto-cloud)) generiert und können über [CLI](/logto-oss/using-cli) (Open-Source), Management APIs oder die Console UI verwaltet werden. +Logto [OIDC-Signaturschlüssel](https://auth.wiki/signing-key), auch bekannt als "OIDC-Private Keys" und "OIDC-Cookie-Keys", sind die Signaturschlüssel, die verwendet werden, um JWTs ([Zugangstokens](https://auth.wiki/access-token) und [ID-Tokens](https://auth.wiki/id-token)) und Browser-Cookies in Logto [Anmeldesitzungen](/sessions#what-is-a-logto-session) zu signieren. Diese Signaturschlüssel werden beim Seeding der Logto-Datenbank ([Open-Source](/logto-oss)) oder beim Erstellen eines neuen Mandanten ([Cloud](/logto-cloud)) generiert und können über [CLI](/logto-oss/using-cli) (Open-Source), Management APIs oder die Console UI verwaltet werden. -Standardmäßig verwendet Logto den Elliptische-Kurven-Algorithmus (EC), um digitale Signaturen zu erzeugen. Da Benutzer jedoch häufig JWT-Signaturen überprüfen müssen und viele ältere Tools den EC-Algorithmus nicht unterstützen (sondern nur RSA), haben wir die Möglichkeit implementiert, private Schlüssel zu rotieren und den Signaturalgorithmus auszuwählen (einschließlich sowohl RSA als auch EC). Dies stellt die Kompatibilität mit Diensten sicher, die veraltete Signaturüberprüfungstools verwenden. +Standardmäßig verwendet Logto den Elliptic Curve (EC) Algorithmus, um digitale Signaturen zu erzeugen. Da Benutzer jedoch häufig JWT-Signaturen überprüfen müssen und viele ältere Tools den EC-Algorithmus nicht unterstützen (nur RSA unterstützen), haben wir die Funktionalität implementiert, private Schlüssel zu rotieren und Benutzern die Wahl des Signaturalgorithmus zu ermöglichen (einschließlich sowohl RSA als auch EC). Dies gewährleistet die Kompatibilität mit Diensten, die veraltete Signaturüberprüfungstools verwenden. :::note -Theoretisch sollten Signaturschlüssel nicht kompromittiert werden und haben keine Ablaufzeit, was bedeutet, dass sie nicht rotiert werden müssen. Dennoch kann das regelmäßige Rotieren des Signaturschlüssels nach einem bestimmten Zeitraum die Sicherheit erhöhen. +Theoretisch sollten Signaturschlüssel nicht geleakt werden und haben keine Ablaufzeit, was bedeutet, dass es nicht notwendig ist, sie zu rotieren. Das periodische Rotieren des Signaturschlüssels nach einem bestimmten Zeitraum kann jedoch die Sicherheit erhöhen. ::: -## Wie funktioniert das? \{#how-it-works} +## Wie funktioniert es? \{#how-it-works} -- **OIDC-Private Key** - Beim Initialisieren einer Logto-Instanz wird automatisch ein Schlüsselpaar aus öffentlichem und privatem Schlüssel generiert und im zugrunde liegenden OIDC-Provider registriert. Wenn Logto ein neues JWT (Zugangstoken oder ID-Token) ausstellt, wird das Token mit dem privaten Schlüssel signiert. Gleichzeitig kann jede Client-Anwendung, die ein JWT erhält, den zugehörigen öffentlichen Schlüssel verwenden, um die Signatur des Tokens zu überprüfen und sicherzustellen, dass das Token nicht von Dritten manipuliert wurde. Der private Schlüssel ist auf dem Logto-Server geschützt. Der öffentliche Schlüssel hingegen ist, wie der Name schon sagt, für jeden zugänglich und kann über die `/oidc/jwks`-Schnittstelle des OIDC-Endpunkts abgerufen werden. Ein Signaturschlüssel-Algorithmus kann beim Generieren des privaten Schlüssels angegeben werden, und Logto verwendet standardmäßig den EC (Elliptische Kurve) Algorithmus. Die Administratoren können den Standardalgorithmus durch Rotieren der privaten Schlüssel auf RSA (Rivest-Shamir-Adleman) ändern. -- **OIDC-Cookie-Key** - Wenn ein Benutzer einen Anmelde- oder Registrierungsprozess startet, wird auf dem Server eine „OIDC-Sitzung“ sowie eine Reihe von Browser-Cookies erstellt. Mit diesen Cookies kann der Browser die Logto Experience API nutzen, um im Namen des Benutzers eine Reihe von Interaktionen durchzuführen, wie z. B. Anmeldung, Registrierung und Passwort zurücksetzen. Im Gegensatz zu JWTs werden die Cookies jedoch nur von Logto OIDC-Service selbst signiert und überprüft, asymmetrische Kryptographie ist nicht erforderlich. Daher gibt es keine zugehörigen öffentlichen Schlüssel für Cookie-Signaturschlüssel und keine asymmetrischen Verschlüsselungsalgorithmen. +- **OIDC-Private Key** + Beim Initialisieren einer Logto-Instanz wird automatisch ein Paar aus öffentlichem und privatem Schlüssel generiert und im zugrunde liegenden OIDC-Anbieter registriert. Wenn Logto ein neues JWT (Zugangstoken oder ID-Token) ausstellt, wird das Token mit dem privaten Schlüssel signiert. Gleichzeitig kann jede Client-Anwendung, die ein JWT erhält, den gepaarten öffentlichen Schlüssel verwenden, um die Tokensignatur zu überprüfen, um sicherzustellen, dass das Token nicht von Dritten manipuliert wurde. Der private Schlüssel ist auf dem Logto-Server geschützt. Der öffentliche Schlüssel hingegen ist, wie der Name schon sagt, für jeden zugänglich und kann über die `/oidc/jwks`-Schnittstelle des OIDC-Endpunkts abgerufen werden. Ein Signaturschlüsselalgorithmus kann beim Generieren des privaten Schlüssels angegeben werden, und Logto verwendet standardmäßig den EC (Elliptic Curve) Algorithmus. Die Administratoren können den Standardalgorithmus durch Rotieren der privaten Schlüssel auf RSA (Rivest-Shamir-Adleman) ändern. +- **OIDC-Cookie Key** + Wenn ein Benutzer einen Anmelde- oder Registrierungsfluss initiiert, wird auf dem Server eine "OIDC-Sitzung" erstellt, sowie eine Reihe von Browser-Cookies. Mit diesen Cookies kann der Browser die Logto Experience API anfordern, um eine Reihe von Interaktionen im Namen des Benutzers durchzuführen, wie z. B. Anmeldung, Registrierung und Passwort zurücksetzen. Im Gegensatz zu den JWTs werden die Cookies jedoch nur von Logto OIDC-Dienst selbst signiert und überprüft, asymmetrische Kryptographiemaßnahmen sind nicht erforderlich. Daher haben wir keine gepaarten öffentlichen Schlüssel für Cookie-Signaturschlüssel, noch asymmetrische Verschlüsselungsalgorithmen. -## Signaturschlüssel über die Console UI rotieren \{#rotate-signing-keys-from-console-ui} +## Signaturschlüssel aus der Console UI rotieren \{#rotate-signing-keys-from-console-ui} -Logto führt eine Funktion zur „Rotation von Signaturschlüsseln“ ein, mit der du einen neuen OIDC-Private Key und Cookie Key in deinem Mandanten erstellen kannst. +Logto führt eine Funktion zur "Rotation von Signaturschlüsseln" ein, die es dir ermöglicht, einen neuen OIDC-Private Key und Cookie Key in deinem Mandanten zu erstellen. -1. Navigiere zu Console > Signaturschlüssel. Dort kannst du sowohl OIDC-Private Keys als auch OIDC-Cookie-Keys verwalten. +1. Navigiere zu Console > Mandanteneinstellungen > OIDC-Konfiguration. Dort kannst du sowohl OIDC-Private Keys als auch OIDC-Cookie-Keys verwalten. 2. Um den Signaturschlüssel zu rotieren, klicke auf die Schaltfläche „Private Keys rotieren“ oder „Cookie Keys rotieren“. Beim Rotieren der privaten Schlüssel hast du die Möglichkeit, den Signaturalgorithmus zu ändern. 3. Du findest eine Tabelle, die alle verwendeten Signaturschlüssel auflistet. Hinweis: Du kannst den vorherigen Schlüssel löschen, aber nicht den aktuellen. @@ -35,21 +35,21 @@ Logto führt eine Funktion zur „Rotation von Signaturschlüsseln“ ein, mit d | Aktuell | Dies zeigt an, dass dieser Schlüssel derzeit aktiv in deinen Anwendungen und APIs verwendet wird. | | Vorherig | Bezieht sich auf einen Schlüssel, der zuvor verwendet wurde, aber rotiert wurde. Bestehende Tokens mit diesem Signaturschlüssel bleiben gültig. | -Bitte beachte, dass die Rotation die folgenden drei Aktionen umfasst: +Bitte denke daran, dass die Rotation die folgenden drei Aktionen umfasst: -1. **Erstellen eines neuen Signaturschlüssels**: Dadurch müssen alle deine **Anwendungen** und **APIs** den neuen Signaturschlüssel übernehmen. -2. **Rotation des aktuellen Schlüssels**: Der bestehende Schlüssel wird nach der Rotation als „vorherig“ gekennzeichnet und nicht mehr von neu erstellten Anwendungen und APIs verwendet. Tokens, die mit diesem Schlüssel signiert wurden, bleiben jedoch weiterhin gültig. -3. **Entfernen des vorherigen Schlüssels**: Schlüssel, die als „vorherig“ gekennzeichnet sind, werden widerrufen und aus der Tabelle entfernt. +1. **Erstellen eines neuen Signaturschlüssels**: Dies erfordert, dass alle deine **Anwendungen** und **APIs** den neuen Signaturschlüssel übernehmen. +2. **Rotieren des aktuellen Schlüssels**: Der bestehende Schlüssel wird nach der Rotation als "vorherig" bezeichnet und nicht mehr von neu erstellten Anwendungen und APIs verwendet. Tokens, die mit diesem Schlüssel signiert wurden, bleiben jedoch weiterhin gültig. +3. **Entfernen deines vorherigen Schlüssels**: Schlüssel, die als "vorherig" gekennzeichnet sind, werden widerrufen und aus der Tabelle entfernt. :::warning -Rotiere niemals Signaturschlüssel hintereinander (zwei- oder mehrmals), da dies ALLE ausgestellten Tokens ungültig machen kann. +Drehe niemals Signaturschlüssel aufeinanderfolgend (zwei oder mehr Mal), da dies ALLE ausgegebenen Tokens ungültig machen kann. -- Für OSS-Nutzer ist nach der Rotation des Signaturschlüssels ein Neustart der Logto-Instanz erforderlich, damit der neue Signaturschlüssel wirksam wird. -- Für Cloud-Nutzer wird der neue Signaturschlüssel unmittelbar nach der Rotation wirksam, aber stelle sicher, dass du den Signaturschlüssel nicht mehrfach hintereinander rotierst. +- Für OSS-Benutzer ist nach dem Rotieren des Signaturschlüssels ein Neustart der Logto-Instanz erforderlich, damit der neue Signaturschlüssel wirksam wird. +- Für Cloud-Benutzer wird der neue Signaturschlüssel sofort nach der Rotation wirksam, aber bitte stelle sicher, dass du den Signaturschlüssel nicht mehrmals hintereinander rotierst. ::: ## Verwandte Ressourcen \{#related-resources} - + Einführung in EC- und RSA-Signaturalgorithmen in JWT diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index e7fb82b57db..53965c7a27f 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,97 +1,99 @@ --- -description: Erfahre, wie du die Account API zur Verwaltung von Benutzern verwendest (Learn how to use the Account API to manage user) +description: Erfahre, wie du die Account API zur Verwaltung von Benutzern nutzt sidebar_position: 1 --- -# Kontoeinstellungen über Account API +# Kontoeinstellungen über die Account API ## Was ist die Logto Account API \{#what-is-logto-account-api} -Die Logto Account API ist eine umfassende Sammlung von APIs, die Endbenutzern direkten API-Zugang ermöglicht, ohne die Management API nutzen zu müssen. Hier die wichtigsten Punkte: +Die Logto Account API ist eine umfassende Sammlung von APIs, die Endbenutzern direkten API-Zugriff ermöglicht, ohne die Management API durchlaufen zu müssen. Hier sind die Highlights: -- Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto zuzugreifen und ihr Profil zu verwalten, ohne die Management API zu benötigen. -- Verwaltung von Benutzerprofilen und Identitäten: Benutzer können ihr Profil und ihre Sicherheitseinstellungen vollständig verwalten, einschließlich der Möglichkeit, Identitätsinformationen wie E-Mail, Telefon und Passwort zu aktualisieren sowie soziale Verbindungen zu verwalten. MFA und SSO-Unterstützung folgen in Kürze. -- Globale Zugangskontrolle: Administratoren haben vollständige, globale Kontrolle über die Zugriffseinstellungen und können jedes Feld individuell anpassen. -- Nahtlose Autorisierung (Authorization): Autorisierung (Authorization) ist einfacher denn je! Verwende einfach `client.getAccessToken()`, um ein opakes Zugangstoken (Opaque token) für OP (Logto) zu erhalten, und füge es dem Authorization-Header als `Bearer ` hinzu. +- Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihre eigenen Kontoprofile zuzugreifen und diese zu verwalten, ohne die Weiterleitung der Management API zu benötigen. +- Benutzerprofil- und Identitätsverwaltung: Benutzer können ihre Profile und Sicherheitseinstellungen vollständig verwalten, einschließlich der Möglichkeit, Identitätsinformationen wie E-Mail, Telefon und Passwort zu aktualisieren sowie soziale Verbindungen zu verwalten. MFA und SSO-Unterstützung kommen bald. +- Globale Zugriffskontrolle: Administratoren haben vollständige, globale Kontrolle über die Zugriffseinstellungen und können jedes Feld anpassen. +- Nahtlose Autorisierung: Die Autorisierung ist einfacher denn je! Verwende einfach `client.getAccessToken()`, um ein opakes Zugangstoken für OP (Logto) zu erhalten, und füge es dem Authorization-Header als `Bearer ` hinzu. -Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig in Logto integriert ist. +Mit der Logto Account API kannst du ein benutzerdefiniertes Kontoverwaltungssystem wie eine Profilseite erstellen, die vollständig in Logto integriert ist. Einige häufige Anwendungsfälle sind unten aufgeführt: - Benutzerprofil abrufen - Benutzerprofil aktualisieren - Benutzerpasswort aktualisieren -- Benutzeridentitäten einschließlich E-Mail, Telefon und sozialen Verbindungen aktualisieren +- Benutzeridentitäten einschließlich E-Mail, Telefon und sozialer Verbindungen aktualisieren - MFA-Faktoren (Verifizierungen) verwalten - Benutzersitzungen verwalten +- Benutzerautorisierte Apps (Grants) verwalten Um mehr über die verfügbaren APIs zu erfahren, besuche bitte die [Logto Account API Referenz](https://openapi.logto.io/group/endpoint-my-account) und die [Logto Verification API Referenz](https://openapi.logto.io/group/endpoint-verifications). :::note -SSO-Kontoansicht und Kontolöschungsfunktionen sind derzeit über die Logto Management APIs verfügbar. Siehe [Kontoeinstellungen über Management API](/end-user-flows/account-settings/by-management-api) für Implementierungsdetails. +SSO-Kontoansicht und Kontolöschungsfunktionen sind derzeit über die Logto Management APIs verfügbar. Siehe [Kontoeinstellungen über die Management API](/end-user-flows/account-settings/by-management-api) für Implementierungsdetails. ::: -## Wie aktiviere ich die Account API \{#how-to-enable-account-api} +## Wie man die Account API aktiviert \{#how-to-enable-account-api} -Navigiere zu Konsole > Anmeldung & Konto > Account Center. +Navigiere zu Konsole > Anmeldung & Konto > Konto-Center. -Die Account API ist standardmäßig deaktiviert, daher sind ihre Zugriffskontrollen gesperrt. Aktiviere **Account API aktivieren**, um sie einzuschalten. +Die Account API ist standardmäßig deaktiviert, daher sind ihre Zugriffskontrollen gesperrt. Schalte **Account API aktivieren** um, um sie einzuschalten. -Nach der Aktivierung kannst du die Berechtigungen pro Feld für Identifikatoren, Profildaten und Drittanbieter-Token-Zugriff konfigurieren. Jedes Feld unterstützt `Off`, `ReadOnly` oder `Edit`; der Standardwert ist `Off`. +Sobald sie aktiviert ist, konfiguriere die Berechtigungen pro Feld für Identifikatoren, Profildaten und Drittanbieter-Token-Zugriff. Jedes Feld unterstützt `Off`, `ReadOnly` oder `Edit`; der Standard ist `Off`. 1. **Sicherheitsfelder**: - - Zu den Feldern gehören: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort und MFA. - - Bevor Endbenutzer diese Felder bearbeiten, müssen sie ihre Identität per Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungs-ID zu erhalten. Siehe [Verifizierungs-ID erhalten](#get-a-verification-record-id). - - Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu **WebAuthn Related Origins** hinzu, damit Account Center und Anmeldungserlebnis Passkeys teilen können. Siehe [Neuen WebAuthn-Passkey verknüpfen](#link-a-new-webauthn-passkey). + - Felder umfassen: primäre E-Mail, primäres Telefon, soziale Identitäten, Passwort und MFA. + - Bevor Endbenutzer diese Felder bearbeiten, müssen sie ihre Identität über Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungsdatensatz-ID zu erhalten. Siehe [Erhalte eine Verifizierungsdatensatz-ID](#get-a-verification-record-id). + - Um WebAuthn-Passkeys für MFA zu verwenden, füge die Domains deiner Frontend-App zu **WebAuthn Related Origins** hinzu, damit das Konto-Center und die Anmeldungserfahrung Passkeys teilen können. Siehe [Verknüpfe einen neuen WebAuthn-Passkey](#link-a-new-webauthn-passkey). 2. **Profilfelder**: - - Zu den Feldern gehören: Benutzername, Name, Avatar, [Profil](/user-management/user-data#profile) (weitere Standard-Profilattribute) und [benutzerdefinierte Daten](/user-management/user-data#custom-data). - - Endbenutzer können diese Felder ohne zusätzliche Verifizierung bearbeiten. -3. **Secret Vault**: - - Für OIDC- oder OAuth-Sozial- und Enterprise-Connectors speichert der Logto [Secret Vault](/secret-vault/federated-token-set) Drittanbieter-Zugangs- und Auffrischungstokens sicher nach der Authentifizierung. Apps können dann externe APIs aufrufen, wie z. B. das Synchronisieren von Google-Kalenderereignissen, ohne dass Benutzer sich erneut anmelden müssen. Das Abrufen von Tokens ist automatisch verfügbar, sobald die Account API aktiviert ist. + - Felder umfassen: Benutzername, Name, Avatar, [Profil](/user-management/user-data#profile) (andere Standardprofilattribute) und [benutzerdefinierte Daten](/user-management/user-data#custom-data). + - Endbenutzer können diese ohne zusätzliche Verifizierung bearbeiten. +3. **Geheimnis-Tresor**: + - Für OIDC- oder OAuth-Sozial- und Unternehmens-Connectors speichert Logto [Geheimnis-Tresor](/secret-vault/federated-token-set) sicher Drittanbieter-Zugangs- und Auffrischungstokens nach der Authentifizierung. Apps können dann externe APIs aufrufen, wie das Synchronisieren von Google-Kalenderereignissen, ohne die Benutzer erneut zur Anmeldung aufzufordern. Die Token-Abfrage wird automatisch verfügbar, sobald die Account API aktiviert ist. 4. **Sitzungsverwaltung**: - - Wenn aktiviert, können Benutzer ihre aktiven Sitzungen einschließlich Geräteinformationen und letzter Anmeldung anzeigen und verwalten. Benutzer können auch Sitzungen widerrufen, um sich von bestimmten Geräten abzumelden. - - Bevor Endbenutzer auf die Sitzungsverwaltung zugreifen, müssen sie ihre Identität per Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungs-ID zu erhalten. Siehe [Verifizierungs-ID erhalten](#get-a-verification-record-id). + - Wenn aktiviert, können Benutzer ihre aktiven Sitzungen anzeigen und verwalten, einschließlich Geräteinformationen und letzter Anmeldezeit. Benutzer können auch Sitzungen widerrufen, um sich von bestimmten Geräten abzumelden. + - Diese gleiche `Sessions`-Feldberechtigung steuert auch die APIs für benutzerautorisierte Apps (Grants) (Anzeigen und Widerrufen von Grants). + - Bevor Endbenutzer auf die Sitzungsverwaltung zugreifen, müssen sie ihre Identität über Passwort, E-Mail oder SMS verifizieren, um eine 10-minütige Verifizierungsdatensatz-ID zu erhalten. Siehe [Erhalte eine Verifizierungsdatensatz-ID](#get-a-verification-record-id). -## Wie greife ich auf die Account API zu \{#how-to-access-account-api} +## Wie man auf die Account API zugreift \{#how-to-access-account-api} :::note -Um sicherzustellen, dass das Zugangstoken (Access token) die entsprechenden Berechtigungen hat, stelle sicher, dass du die entsprechenden Berechtigungen (Scopes) in deiner Logto-Konfiguration richtig eingestellt hast. +Um sicherzustellen, dass das Zugangstoken die entsprechenden Berechtigungen hat, stelle sicher, dass du die entsprechenden Berechtigungen in deiner Logto-Konfiguration richtig konfiguriert hast. -Zum Beispiel musst du für die `POST /api/my-account/primary-email` API die `email`-Berechtigung konfigurieren; für die `POST /api/my-account/primary-phone` API die `phone`-Berechtigung. +Zum Beispiel, für die `POST /api/my-account/primary-email` API, musst du die `email` Berechtigung konfigurieren; für die `POST /api/my-account/primary-phone` API, musst du die `phone` Berechtigung konfigurieren. ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...andere Optionen - // Füge die passenden Berechtigungen hinzu, die zu deinem Anwendungsfall passen. + // Füge die passenden Berechtigungen hinzu, die zu deinen Anwendungsfällen passen. scopes: [ UserScope.Email, // Für `{POST,DELETE} /api/my-account/primary-email` APIs UserScope.Phone, // Für `{POST,DELETE} /api/my-account/primary-phone` APIs UserScope.CustomData, // Um benutzerdefinierte Daten zu verwalten - UserScope.Address, // Um Adresse zu verwalten + UserScope.Address, // Um Adressen zu verwalten UserScope.Identities, // Für Identitäts- und MFA-bezogene APIs - UserScope.Profile, // Um Benutzerprofil zu verwalten - UserScope.Sessions, // Um Benutzersitzungen zu verwalten + UserScope.Profile, // Um Benutzerprofile zu verwalten + UserScope.Sessions, // Um Benutzersitzungen und App-Grants zu verwalten ], }; ``` ::: -### Zugangstoken abrufen \{#fetch-an-access-token} +### Ein Zugangstoken abrufen \{#fetch-an-access-token} -Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode `client.getAccessToken()` verwenden, um ein Zugangstoken (Access token) abzurufen. Dieses Token ist ein opaker Token (Opaque token), das für den Zugriff auf die Account API verwendet werden kann. +Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode `client.getAccessToken()` verwenden, um ein Zugangstoken abzurufen. Dieses Token ist ein opakes Token, das verwendet werden kann, um auf die Account API zuzugreifen. -Wenn du das offizielle SDK nicht verwendest, solltest du das `resource`-Feld für die Zugangstoken-Anfrage an `/oidc/token` leer lassen. +Wenn du das offizielle SDK nicht verwendest, solltest du das `resource` für die Zugangstoken-Grant-Anfrage an `/oidc/token` leer lassen. -### Zugriff auf Account API mit Zugangstoken \{#access-account-api-using-access-token} +### Zugriff auf die Account API mit Zugangstoken \{#access-account-api-using-access-token} -Du solltest das Zugangstoken im `Authorization`-Feld der HTTP-Header im Bearer-Format (`Bearer YOUR_TOKEN`) beim Zugriff auf die Account API angeben. +Du solltest das Zugangstoken im `Authorization`-Feld der HTTP-Header im Bearer-Format (`Bearer YOUR_TOKEN`) einfügen, wenn du mit der Account API interagierst. -Hier ein Beispiel, um die Benutzerkontoinformationen abzurufen: +Hier ist ein Beispiel, um die Benutzerkontoinformationen abzurufen: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -109,7 +111,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -120,11 +122,11 @@ Die Antwort sieht zum Beispiel so aus: } ``` -Die Antwortfelder können je nach Account Center-Einstellungen variieren. +Die Antwortfelder können je nach den Einstellungen des Konto-Centers variieren. ### Grundlegende Kontoinformationen aktualisieren \{#update-basic-account-information} -Zu den grundlegenden Kontoinformationen gehören Benutzername, Name, Avatar, benutzerdefinierte Daten und andere Profilinformationen. +Grundlegende Kontoinformationen umfassen den Benutzernamen, den Namen, den Avatar, benutzerdefinierte Daten und andere Profilinformationen. Um **Benutzername, Name, Avatar und customData** zu aktualisieren, kannst du den [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) Endpunkt verwenden. @@ -146,15 +148,15 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Identifikatoren und andere sensible Informationen verwalten \{#manage-identifiers-and-other-sensitive-information} -Aus Sicherheitsgründen erfordert die Account API eine zusätzliche Autorisierungsebene für Vorgänge, die Identifikatoren und andere sensible Informationen betreffen. +Aus Sicherheitsgründen erfordert die Account API eine zusätzliche Autorisierungsebene für Operationen, die Identifikatoren und andere sensible Informationen betreffen. -### Verifizierungs-ID erhalten \{#get-a-verification-record-id} +### Eine Verifizierungsdatensatz-ID erhalten \{#get-a-verification-record-id} -Zuerst musst du eine **Verifizierungs-ID** mit einer Gültigkeit von 10 Minuten (TTL) erhalten. Diese kann verwendet werden, um die Identität des Benutzers zu verifizieren, bevor sensible Informationen aktualisiert werden. Das bedeutet, sobald ein Benutzer seine Identität erfolgreich per Passwort, E-Mail-Verifizierungscode oder SMS-Verifizierungscode bestätigt hat, hat er 10 Minuten Zeit, um seine authentifizierungsbezogenen Daten wie Identifikatoren, Zugangsdaten, Social Account Linking und MFA zu aktualisieren. +Zuerst musst du eine **Verifizierungsdatensatz-ID** mit einer 10-minütigen Ablaufzeit (TTL) erhalten. Diese kann verwendet werden, um die Identität des Benutzers zu verifizieren, bevor sensible Informationen aktualisiert werden. Das bedeutet, dass ein Benutzer, sobald er seine Identität erfolgreich über Passwort, E-Mail-Verifizierungscode oder SMS-Verifizierungscode verifiziert hat, 10 Minuten Zeit hat, um seine authentifizierungsbezogenen Daten zu aktualisieren, einschließlich Identifikatoren, Anmeldeinformationen, sozialer Kontoverknüpfungen und MFA. -Um eine Verifizierungs-ID zu erhalten, kannst du [das Benutzerpasswort verifizieren](#verify-the-users-password) oder [einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du [das Passwort des Benutzers verifizieren](#verify-the-users-password) oder [einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -#### Passwort des Benutzers verifizieren \{#verify-the-users-password} +#### Das Passwort des Benutzers verifizieren \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -172,13 +174,13 @@ Die Antwort sieht zum Beispiel so aus: } ``` -#### Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### Verifizieren durch Senden eines Verifizierungscodes an die E-Mail oder das Telefon des Benutzers \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/) oder den [SMS-Connector konfigurieren](/connectors/sms-connectors/) und sicherstellen, dass die `UserPermissionValidation`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/) oder den [SMS-Connector konfigurieren](/connectors/sms-connectors/), und sicherstellen, dass die `UserPermissionValidation`-Vorlage konfiguriert ist. ::: -Am Beispiel E-Mail: Fordere einen neuen Verifizierungscode an und erhalte die Verifizierungs-ID: +Nehmen wir E-Mail als Beispiel, fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -205,13 +207,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Nach erfolgreicher Verifizierung des Codes kannst du nun die Verifizierungs-ID verwenden, um den Identifikator des Benutzers zu aktualisieren. +Nach der Verifizierung des Codes kannst du nun die Verifizierungsdatensatz-ID verwenden, um den Identifikator des Benutzers zu aktualisieren. -Um mehr über Verifizierungen zu erfahren, siehe [Sicherheitsverifizierung über Account API](/end-user-flows/security-verification). +Um mehr über Verifizierungen zu erfahren, siehe [Sicherheitsverifizierung durch Account API](/end-user-flows/security-verification). -### Anfrage mit Verifizierungs-ID senden \{#send-request-with-verification-record-id} +### Anfrage mit Verifizierungsdatensatz-ID senden \{#send-request-with-verification-record-id} -Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungs-ID im Request-Header mit dem Feld `logto-verification-id` angeben. +Wenn du eine Anfrage sendest, um den Identifikator des Benutzers zu aktualisieren, musst du die Verifizierungsdatensatz-ID im Anfrage-Header mit dem `logto-verification-id`-Feld einfügen. ### Passwort des Benutzers aktualisieren \{#update-users-password} @@ -226,16 +228,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -Wie Passwörter, die während der Registrierung erstellt wurden, müssen auch Passwörter, die über die Account API gesetzt werden, der von dir konfigurierten [Passwortrichtlinie](/security/password-policy) in Konsole > Sicherheit > Passwortrichtlinie entsprechen. Logto gibt detaillierte Validierungsergebnisse und Fehlermeldungen zurück, wenn das Passwort die Richtlinie nicht erfüllt. +Genau wie Passwörter, die während der Anmeldung erstellt wurden, müssen Passwörter, die über die Account API festgelegt werden, den [Passwortrichtlinien](/security/password-policy) entsprechen, die du in Konsole > Sicherheit > Passwortrichtlinien konfiguriert hast. Logto gibt detaillierte Validierungsergebnisse und Fehlermeldungen zurück, wenn das Passwort die Richtlinien nicht erfüllt. ::: ### Neue E-Mail aktualisieren oder verknüpfen \{#update-or-link-new-email} :::note -Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/) und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/), und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. ::: -Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, musst du zuerst den Besitz der E-Mail nachweisen. +Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, solltest du zuerst das Eigentum der E-Mail nachweisen. Rufe den [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) Endpunkt auf, um einen Verifizierungscode anzufordern. @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Du findest eine `verificationId` in der Antwort und erhältst einen Verifizierungscode per E-Mail, den du zur Verifizierung der E-Mail verwendest. +Du wirst eine `verificationId` in der Antwort finden und einen Verifizierungscode in der E-Mail erhalten, verwende ihn, um die E-Mail zu verifizieren. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,32 +257,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Nach erfolgreicher Verifizierung des Codes kannst du nun [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) aufrufen, um die E-Mail des Benutzers zu aktualisieren. Setze die `verificationId` im Request-Body als `newIdentifierVerificationRecordId`. +Nach der Verifizierung des Codes kannst du nun [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) aufrufen, um die E-Mail des Benutzers zu aktualisieren, setze die `verificationId` in den Anfragekörper als `newIdentifierVerificationRecordId`. -:::info[Zwei verschiedene Verifizierungs-IDs] +:::info[Zwei verschiedene Verifizierungsdatensatz-IDs] -Für diese Anfrage werden zwei verschiedene Verifizierungs-IDs benötigt: +Diese Anfrage erfordert zwei separate Verifizierungsdatensatz-IDs: -- **`logto-verification-id` (Header)**: Bestätigt die Identität des Benutzers vor sensiblen Änderungen. Erhalte diese durch [Verifizierung des Benutzerpassworts](#verify-the-users-password) oder [Versand eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (Body)**: Bestätigt den Besitz der neuen E-Mail-Adresse. Dies ist die `verificationRecordId`, die aus dem oben genannten `POST /api/verifications/verification-code`-Aufruf zurückgegeben wird. +- **`logto-verification-id` (Header)**: Beweist die Identität des Benutzers, bevor sensible Änderungen vorgenommen werden. Erhalte dies durch [Verifizierung des Benutzerpassworts](#verify-the-users-password) oder [Senden eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (Body)**: Beweist das Eigentum an der neuen E-Mail-Adresse. Dies ist die `verificationRecordId`, die aus dem `POST /api/verifications/verification-code` Aufruf oben zurückgegeben wird. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # Bestätigt die Benutzeridentität (durch Passwort oder bestehende E-Mail/Telefon-Verifizierung) + # Verifiziert die Benutzeridentität (aus Passwort- oder bestehender E-Mail/Telefon-Verifizierung) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # Die "newIdentifierVerificationRecordId" bestätigt den Besitz der neuen E-Mail (aus dem oben beschriebenen Verifizierungscode-Flow) + # Die "newIdentifierVerificationRecordId" beweist das Eigentum an der neuen E-Mail (aus dem Verifizierungscode-Fluss oben) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -Wie E-Mails, die während der Registrierung gesammelt werden, muss jede E-Mail, die über die Account API verknüpft wird, die von dir konfigurierte [Blocklist](/security/blocklist) in Konsole > Sicherheit > Blocklist bestehen. Logto lehnt die Anfrage ab und gibt eine detaillierte Fehlermeldung zurück, wenn die E-Mail gegen die Richtlinie verstößt. +Genau wie E-Mails, die während der Anmeldung gesammelt wurden, muss jede E-Mail, die über die Account API verknüpft wird, die [Blocklist](/security/blocklist) Verifizierung bestehen, die du in Konsole > Sicherheit > Blocklist konfiguriert hast. Logto wird die Anfrage ablehnen und einen detaillierten Fehler zurückgeben, wenn die E-Mail gegen die Richtlinien verstößt. ::: -### E-Mail des Benutzers entfernen \{#remove-the-users-email} +### Die E-Mail des Benutzers entfernen \{#remove-the-users-email} Um die E-Mail des Benutzers zu entfernen, kannst du den [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) Endpunkt verwenden. @@ -293,12 +295,12 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Telefon verwalten \{#manage-phone} :::note -Um diese Methode zu verwenden, musst du den [SMS-Connector konfigurieren](/connectors/sms-connectors/) und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [SMS-Connector konfigurieren](/connectors/sms-connectors/), und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. ::: -Ähnlich wie beim Aktualisieren der E-Mail kannst du den [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) Endpunkt verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) Endpunkt, um das Telefon des Benutzers zu entfernen. +Ähnlich wie beim Aktualisieren der E-Mail kannst du den [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) Endpunkt verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) Endpunkt verwenden, um das Telefon des Benutzers zu entfernen. -### Neue soziale Verbindung verknüpfen \{#link-a-new-social-connection} +### Eine neue soziale Verbindung verknüpfen \{#link-a-new-social-connection} Um eine neue soziale Verbindung zu verknüpfen, solltest du zuerst eine Autorisierungs-URL mit [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) anfordern. @@ -309,13 +311,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`: Die ID des [Social Connectors](/connectors/social-connectors/). -- `redirectUri`: Die Weiterleitungs-URL nach der Autorisierung durch den Benutzer. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen. -- `state`: Der State, der nach der Autorisierung durch den Benutzer zurückgegeben wird. Es handelt sich um einen zufälligen String, der zur Verhinderung von CSRF-Angriffen verwendet wird. +- `connectorId`: Die ID des [sozialen Connectors](/connectors/social-connectors/). +- `redirectUri`: Die Umleitungs-URI, nachdem der Benutzer die Anwendung autorisiert hat. Du solltest eine Webseite unter dieser URL hosten und den Rückruf erfassen. +- `state`: Der Zustand, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es ist eine zufällige Zeichenfolge, die verwendet wird, um CSRF-Angriffe zu verhindern. -In der Antwort findest du eine `verificationRecordId`, die du für später aufbewahren solltest. +In der Antwort findest du eine `verificationRecordId`, bewahre sie für die spätere Verwendung auf. -Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an die `redirectUri` mit dem `state`-Parameter. Dann kannst du den [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) Endpunkt verwenden, um die soziale Verbindung zu verifizieren. +Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Rückruf an die `redirectUri` mit dem `state`-Parameter. Dann kannst du den [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) Endpunkt verwenden, um die soziale Verbindung zu verifizieren. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,30 +326,30 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -Das `connectorData` ist die von dem Social Connector zurückgegebene Daten nach der Autorisierung durch den Benutzer. Du musst die Query-Parameter aus der `redirectUri` auf deiner Callback-Seite extrahieren und sie als JSON im Feld `connectorData` übergeben. +Die `connectorData` sind die Daten, die vom sozialen Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Abfrageparameter von der `redirectUri` auf deiner Rückrufseite analysieren und sie als JSON als Wert des `connectorData`-Feldes einfügen. Schließlich kannst du den [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) Endpunkt verwenden, um die soziale Verbindung zu verknüpfen. -:::info[Zwei verschiedene Verifizierungs-IDs] +:::info[Zwei verschiedene Verifizierungsdatensatz-IDs] -Für diese Anfrage werden zwei verschiedene Verifizierungs-IDs benötigt: +Diese Anfrage erfordert zwei separate Verifizierungsdatensatz-IDs: -- **`logto-verification-id` (Header)**: Bestätigt die Identität des Benutzers vor sensiblen Änderungen. Erhalte diese durch [Verifizierung des Benutzerpassworts](#verify-the-users-password) oder [Versand eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (Body)**: Identifiziert die zu verknüpfende soziale Identität. Dies ist die `verificationRecordId`, die aus dem oben genannten `POST /api/verifications/social`-Aufruf zurückgegeben wird. +- **`logto-verification-id` (Header)**: Beweist die Identität des Benutzers, bevor sensible Änderungen vorgenommen werden. Erhalte dies durch [Verifizierung des Benutzerpassworts](#verify-the-users-password) oder [Senden eines Verifizierungscodes an die bestehende E-Mail oder das Telefon des Benutzers](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (Body)**: Identifiziert die zu verknüpfende soziale Identität. Dies ist die `verificationRecordId`, die aus dem `POST /api/verifications/social` Aufruf oben zurückgegeben wird. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # Bestätigt die Benutzeridentität (durch Passwort oder bestehende E-Mail/Telefon-Verifizierung) + # Verifiziert die Benutzeridentität (aus Passwort- oder bestehender E-Mail/Telefon-Verifizierung) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # Die "newIdentifierVerificationRecordId" identifiziert die zu verknüpfende soziale Verbindung (aus dem oben beschriebenen Social-Verification-Flow) + # Die "newIdentifierVerificationRecordId" identifiziert die zu verknüpfende soziale Verbindung (aus dem sozialen Verifizierungsfluss oben) --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### Soziale Verbindung entfernen \{#remove-a-social-connection} +### Eine soziale Verbindung entfernen \{#remove-a-social-connection} Um eine soziale Verbindung zu entfernen, kannst du den [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) Endpunkt verwenden. @@ -357,30 +359,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Neuen WebAuthn-Passkey verknüpfen \{#link-a-new-webauthn-passkey} +### Einen neuen WebAuthn-Passkey verknüpfen \{#link-a-new-webauthn-passkey} :::note Denke daran, zuerst [MFA und WebAuthn zu aktivieren](/end-user-flows/mfa). ::: :::note -Um diese Methode zu verwenden, musst du das Feld `mfa` in den [Account Center-Einstellungen](#how-to-enable-account-api) aktivieren. +Um diese Methode zu verwenden, musst du das `mfa`-Feld in den [Konto-Center-Einstellungen](#how-to-enable-account-api) aktivieren. ::: -**Schritt 1: Ursprungs-URL deiner Frontend-App zu den Related Origins hinzufügen** +**Schritt 1: Füge den Ursprung deiner Frontend-App zu den verwandten Ursprüngen hinzu** -WebAuthn-Passkeys sind an einen bestimmten Hostnamen gebunden, der als **Relying Party ID (RP ID)** bezeichnet wird. Nur Anwendungen, die auf dem Origin der RP ID gehostet werden, können mit diesen Passkeys registrieren oder authentifizieren. +WebAuthn-Passkeys sind an einen bestimmten Hostnamen gebunden, der als **Relying Party ID (RP ID)** bezeichnet wird. Nur Anwendungen, die auf dem Ursprung der RP ID gehostet werden, können sich mit diesen Passkeys registrieren oder authentifizieren. -Da deine Frontend-Anwendung die Account API von einer anderen Domain als die Logto-Authentifizierungsseiten aufruft, musst du **Related Origins** konfigurieren, um Cross-Origin-Passkey-Operationen zu ermöglichen. +Da deine Frontend-Anwendung die Account API von einer anderen Domain als Logtos Authentifizierungsseiten aufruft, musst du **Verwandte Ursprünge** konfigurieren, um Cross-Origin-Passkey-Operationen zu ermöglichen. **Wie Logto die RP ID bestimmt:** -- **Standard-Setup**: Wenn du nur die Standarddomain von Logto `https://[tenant-id].logto.app` verwendest, ist die RP ID `[tenant-id].logto.app` -- **Eigene Domain**: Wenn du eine [eigene Domain](/logto-cloud/custom-domain) wie `https://auth.example.com` konfiguriert hast, wird die RP ID zu `auth.example.com` +- **Standard-Setup**: Wenn du nur Logtos Standard-Domain `https://[tenant-id].logto.app` verwendest, ist die RP ID `[tenant-id].logto.app` +- **Benutzerdefinierte Domain**: Wenn du eine [benutzerdefinierte Domain](/logto-cloud/custom-domain) wie `https://auth.example.com` konfiguriert hast, wird die RP ID zu `auth.example.com` -**Related Origins konfigurieren:** +**Verwandte Ursprünge konfigurieren:** -Verwende den [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) Endpunkt, um den Origin deiner Frontend-Anwendung hinzuzufügen. Wenn das Account Center deiner App z. B. unter `https://account.example.com` läuft: +Verwende den [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) Endpunkt, um den Ursprung deiner Frontend-Anwendung hinzuzufügen. Zum Beispiel, wenn das Konto-Center deiner App auf `https://account.example.com` läuft: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn unterstützt bis zu 5 eindeutige eTLD+1-Labels für Related Origins. Das eTLD+1 (effective top-level domain plus one label) ist der registrierbare Domain-Teil. Zum Beispiel: +WebAuthn unterstützt bis zu 5 einzigartige eTLD+1 Labels für verwandte Ursprünge. Das eTLD+1 (effektive Top-Level-Domain plus ein Label) ist der registrierbare Domain-Teil. Zum Beispiel: - `https://example.com`, `https://app.example.com` und `https://auth.example.com` zählen als **ein** Label (`example.com`) -- `https://shopping.com`, `https://shopping.co.uk` und `https://shopping.co.jp` zählen ebenfalls als **ein** Label (`shopping`) +- `https://shopping.com`, `https://shopping.co.uk` und `https://shopping.co.jp` zählen auch als **ein** Label (`shopping`) - `https://example.com` und `https://another.com` zählen als **zwei** Labels -Wenn du mehr als 5 verschiedene Domains als Related Origins unterstützen musst, siehe die [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) Dokumentation für Details. +Wenn du mehr als 5 verschiedene Domains als verwandte Ursprünge unterstützen musst, siehe die [Verwandte Ursprungsanfragen](https://passkeys.dev/docs/advanced/related-origins/) Dokumentation für Details. ::: **Schritt 2: Neue Registrierungsoptionen anfordern** -Verwende den [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) Endpunkt, um eine Registrierung für einen neuen Passkey anzufordern. Logto erlaubt es jedem Benutzerkonto, mehrere Passkeys zu registrieren. +Verwende den [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) Endpunkt, um die Registrierung für einen neuen Passkey anzufordern. Logto erlaubt jedem Benutzerkonto, mehrere Passkeys zu registrieren. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -421,25 +423,25 @@ Du erhältst eine Antwort wie: } ``` -**Schritt 3: Passkey im lokalen Browser registrieren** +**Schritt 3: Registriere den Passkey im lokalen Browser** -Am Beispiel von [`@simplewebauthn/browser`](https://simplewebauthn.dev/) kannst du die Funktion `startRegistration` verwenden, um den Passkey im lokalen Browser zu registrieren. +Nimm [`@simplewebauthn/browser`](https://simplewebauthn.dev/) als Beispiel, du kannst die `startRegistration` Funktion verwenden, um den Passkey im lokalen Browser zu registrieren. ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // Die vom Server in Schritt 1 zurückgegebenen Daten + optionsJSON: registrationOptions, // Die Daten, die vom Server in Schritt 1 zurückgegeben wurden }); // Speichere die Antwort für die spätere Verwendung ``` -**Schritt 4: Passkey-Registrierung verifizieren** +**Schritt 4: Verifiziere die Passkey-Registrierung** Verwende den [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) Endpunkt, um die Passkey-Registrierung zu verifizieren. -In diesem Schritt wird die vom Authenticator generierte kryptografische Signatur überprüft, um sicherzustellen, dass der Passkey legitim erstellt wurde und während der Übertragung nicht manipuliert wurde. +Dieser Schritt verifiziert die kryptografische Signatur, die vom Authenticator generiert wurde, um sicherzustellen, dass der Passkey legitim erstellt wurde und während der Übertragung nicht manipuliert wurde. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -448,10 +450,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`: Die Antwort aus dem lokalen Browser in Schritt 2. -- `verificationRecordId`: Die vom Server in Schritt 1 zurückgegebene Verifizierungs-ID. +- `payload`: Die Antwort vom lokalen Browser in Schritt 2. +- `verificationRecordId`: Die Verifizierungsdatensatz-ID, die vom Server in Schritt 1 zurückgegeben wurde. -**Schritt 5: Passkey verknüpfen** +**Schritt 5: Verknüpfe den Passkey** Schließlich kannst du den Passkey mit dem Benutzerkonto verknüpfen, indem du den [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) Endpunkt verwendest. @@ -463,9 +465,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: Eine gültige Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe [Verifizierungs-ID erhalten](#get-a-verification-record-id) für Details. -- `type`: Der Typ des MFA-Faktors, aktuell wird nur `WebAuthn` unterstützt. -- `newIdentifierVerificationRecordId`: Die vom Server in Schritt 1 zurückgegebene Verifizierungs-ID. +- `verification_record_id`: eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt [Erhalte eine Verifizierungsdatensatz-ID](#get-a-verification-record-id) für weitere Details einsehen. +- `type`: der Typ des MFA-Faktors, derzeit wird nur `WebAuthn` unterstützt. +- `newIdentifierVerificationRecordId`: die Verifizierungsdatensatz-ID, die vom Server in Schritt 1 zurückgegeben wurde. ### Bestehende WebAuthn-Passkeys verwalten \{#manage-existing-webauthn-passkeys} @@ -476,7 +478,7 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json [ @@ -491,12 +493,12 @@ Die Antwort sieht zum Beispiel so aus: ] ``` -- `id`: Die ID der Verifizierung. -- `type`: Der Typ der Verifizierung, `WebAuthn` für WebAuthn-Passkey. -- `name`: Der Name des Passkeys, optionales Feld. -- `agent`: Der User Agent des Passkeys. +- `id`: die ID der Verifizierung. +- `type`: der Typ der Verifizierung, `WebAuthn` für WebAuthn-Passkey. +- `name`: der Name des Passkeys, optionales Feld. +- `agent`: der Benutzeragent des Passkeys. -Den Passkey-Namen kannst du mit [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) aktualisieren: +Aktualisiere den Passkey-Namen mit dem [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) Endpunkt: ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Den Passkey kannst du mit [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) löschen: +Lösche den Passkey mit dem [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) Endpunkt: ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -514,19 +516,19 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'logto-verification-id: ' ``` -### Neues TOTP verknüpfen \{#link-a-new-totp} +### Einen neuen TOTP verknüpfen \{#link-a-new-totp} :::note Denke daran, zuerst [MFA und TOTP zu aktivieren](/end-user-flows/mfa). ::: :::note -Um diese Methode zu verwenden, musst du das Feld `mfa` in den [Account Center-Einstellungen](#how-to-enable-account-api) aktivieren. +Um diese Methode zu verwenden, musst du das `mfa`-Feld in den [Konto-Center-Einstellungen](#how-to-enable-account-api) aktivieren. ::: -**Schritt 1: TOTP-Secret generieren** +**Schritt 1: Ein TOTP-Geheimnis generieren** -Verwende den [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) Endpunkt, um ein TOTP-Secret zu generieren. +Verwende den [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) Endpunkt, um ein TOTP-Geheimnis zu generieren. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -542,9 +544,9 @@ Die Antwort sieht zum Beispiel so aus: } ``` -**Schritt 2: TOTP-Secret dem Benutzer anzeigen** +**Schritt 2: Zeige das TOTP-Geheimnis dem Benutzer an** -Verwende das Secret, um einen QR-Code zu generieren oder zeige es dem Benutzer direkt an. Der Benutzer sollte es zu seiner Authenticator-App (wie Google Authenticator, Microsoft Authenticator oder Authy) hinzufügen. +Verwende das Geheimnis, um einen QR-Code zu generieren oder es direkt dem Benutzer anzuzeigen. Der Benutzer sollte es zu seiner Authenticator-App hinzufügen (wie Google Authenticator, Microsoft Authenticator oder Authy). Das URI-Format für den QR-Code sollte sein: @@ -558,9 +560,9 @@ Beispiel: otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp ``` -**Schritt 3: TOTP-Faktor binden** +**Schritt 3: Binde den TOTP-Faktor** -Nachdem der Benutzer das Secret zu seiner Authenticator-App hinzugefügt hat, muss er es verifizieren und an sein Konto binden. Verwende den [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) Endpunkt, um den TOTP-Faktor zu binden. +Nachdem der Benutzer das Geheimnis zu seiner Authenticator-App hinzugefügt hat, muss er es verifizieren und an sein Konto binden. Verwende den [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) Endpunkt, um den TOTP-Faktor zu binden. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,9 +572,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`: Eine gültige Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe [Verifizierungs-ID erhalten](#get-a-verification-record-id) für Details. -- `type`: Muss `Totp` sein. -- `secret`: Das in Schritt 1 generierte TOTP-Secret. +- `verification_record_id`: eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt [Erhalte eine Verifizierungsdatensatz-ID](#get-a-verification-record-id) für weitere Details einsehen. +- `type`: muss `Totp` sein. +- `secret`: das in Schritt 1 generierte TOTP-Geheimnis. :::note Ein Benutzer kann nur einen TOTP-Faktor gleichzeitig haben. Wenn der Benutzer bereits einen TOTP-Faktor hat, führt der Versuch, einen weiteren hinzuzufügen, zu einem 422-Fehler. @@ -585,7 +587,7 @@ Denke daran, zuerst [MFA und Backup-Codes zu aktivieren](/end-user-flows/mfa). ::: :::note -Um diese Methode zu verwenden, musst du das Feld `mfa` in den [Account Center-Einstellungen](#how-to-enable-account-api) aktivieren. +Um diese Methode zu verwenden, musst du das `mfa`-Feld in den [Konto-Center-Einstellungen](#how-to-enable-account-api) aktivieren. ::: **Schritt 1: Neue Backup-Codes generieren** @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -606,18 +608,18 @@ Die Antwort sieht zum Beispiel so aus: } ``` -**Schritt 2: Backup-Codes dem Benutzer anzeigen** +**Schritt 2: Zeige die Backup-Codes dem Benutzer an** -Bevor die Backup-Codes an das Benutzerkonto gebunden werden, musst du sie dem Benutzer anzeigen und ihn anweisen: +Bevor du die Backup-Codes an das Benutzerkonto bindest, musst du sie dem Benutzer anzeigen und ihn anweisen: -- Lade diese Codes sofort herunter oder schreibe sie auf -- Bewahre sie an einem sicheren Ort auf -- Jeder Code kann nur einmal verwendet werden -- Diese Codes sind die letzte Rettung, falls der Benutzer den Zugang zu seinen primären MFA-Methoden verliert +- Diese Codes sofort herunterzuladen oder aufzuschreiben +- Sie an einem sicheren Ort zu speichern +- Zu verstehen, dass jeder Code nur einmal verwendet werden kann +- Zu wissen, dass diese Codes ihre letzte Rettung sind, wenn sie den Zugriff auf ihre primären MFA-Methoden verlieren -Du solltest die Codes in einem klaren, einfach zu kopierenden Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) anbieten. +Du solltest die Codes in einem klaren, leicht kopierbaren Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) in Betracht ziehen. -**Schritt 3: Backup-Codes an das Benutzerkonto binden** +**Schritt 3: Binde die Backup-Codes an das Benutzerkonto** Verwende den [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) Endpunkt, um die Backup-Codes an das Benutzerkonto zu binden. @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`: Eine gültige Verifizierungs-ID, die durch Verifizierung des bestehenden Faktors des Benutzers erlangt wurde. Siehe [Verifizierungs-ID erhalten](#get-a-verification-record-id) für Details. -- `type`: Muss `BackupCode` sein. -- `codes`: Das Array der im vorherigen Schritt generierten Backup-Codes. +- `verification_record_id`: eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Du kannst den Abschnitt [Erhalte eine Verifizierungsdatensatz-ID](#get-a-verification-record-id) für weitere Details einsehen. +- `type`: muss `BackupCode` sein. +- `codes`: das Array der in den vorherigen Schritten generierten Backup-Codes. :::note -- Ein Benutzer kann nur einen Satz Backup-Codes gleichzeitig haben. Wenn alle Codes verwendet wurden, muss der Benutzer neue Codes generieren und binden. -- Backup-Codes können nicht der einzige MFA-Faktor sein. Der Benutzer muss mindestens einen weiteren MFA-Faktor (wie WebAuthn oder TOTP) aktiviert haben. +- Ein Benutzer kann nur einen Satz von Backup-Codes gleichzeitig haben. Wenn alle Codes verwendet wurden, muss der Benutzer neue Codes generieren und binden. +- Backup-Codes können nicht der einzige MFA-Faktor sein. Der Benutzer muss mindestens einen anderen MFA-Faktor (wie WebAuthn oder TOTP) aktiviert haben. - Jeder Backup-Code kann nur einmal verwendet werden. ::: **Vorhandene Backup-Codes anzeigen** -Um vorhandene Backup-Codes und deren Nutzungsstatus anzuzeigen, verwende den [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) Endpunkt: +Um vorhandene Backup-Codes und ihren Nutzungsstatus anzuzeigen, verwende den [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) Endpunkt: ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -Die Antwort sieht zum Beispiel so aus: +Der Antwortkörper könnte so aussehen: ```json { @@ -667,8 +669,8 @@ Die Antwort sieht zum Beispiel so aus: } ``` -- `code`: Der Backup-Code. -- `usedAt`: Der Zeitstempel, wann der Code verwendet wurde, `null` wenn noch nicht verwendet. +- `code`: der Backup-Code. +- `usedAt`: der Zeitpunkt, zu dem der Code verwendet wurde, `null`, wenn er noch nicht verwendet wurde. ### Benutzersitzungen verwalten \{#manage-user-sessions} @@ -678,8 +680,8 @@ Um die aktiven Sitzungen des Benutzers aufzulisten, kannst du den [`GET /api/my- :::note -- Die Berechtigung `UserScope.Sessions` ist erforderlich, um auf diesen Endpunkt zuzugreifen. -- Das Feld `Sessions` in den Account Center-Einstellungen muss auf `ReadOnly` oder `Edit` gesetzt sein. +- `UserScope.Sessions` Berechtigung ist erforderlich, um auf diesen Endpunkt zuzugreifen. +- `Sessions`-Feld in den Konto-Center-Einstellungen muss auf `ReadOnly` oder `Edit` gesetzt sein. ::: @@ -696,8 +698,8 @@ Um eine bestimmte Sitzung zu widerrufen, verwende den [`DELETE /api/my-account/s :::note -- Die Berechtigung `UserScope.Sessions` ist erforderlich, um auf diesen Endpunkt zuzugreifen. -- Das Feld `Sessions` in den Account Center-Einstellungen muss auf `Edit` gesetzt sein. +- `UserScope.Sessions` Berechtigung ist erforderlich, um auf diesen Endpunkt zuzugreifen. +- `Sessions`-Feld in den Konto-Center-Einstellungen muss auf `Edit` gesetzt sein. ::: ```bash @@ -707,9 +709,60 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} -H 'content-type: application/json' ``` -Optionale Query-Parameter: +Optionale Abfrageparameter: -- `revokeGrantsTarget`: Optional kannst du das Ziel der zu widerrufenden Berechtigungen zusammen mit der Sitzung angeben. Mögliche Werte: - - `all`: Widerruft alle mit der Sitzung verbundenen Berechtigungen. - - `firstParty`: Widerruft nur Berechtigungen von First-Party-Apps, die mit der Sitzung verbunden sind. (Empfohlen für die meisten Anwendungsfälle, da so der Zugriff für deine eigene App widerrufen wird, während Berechtigungen für Drittanbieter-Apps erhalten bleiben und so ein besseres Benutzererlebnis bieten.) - - nicht angegeben: Das Standardverhalten widerruft Berechtigungen, die nicht den `offline_access`-Scope haben, was typischerweise bedeutet, dass Nicht-Refresh-Token-Berechtigungen für die Sitzung widerrufen werden. +- `revokeGrantsTarget`: Optional das Ziel der Grants angeben, die zusammen mit der Sitzung widerrufen werden sollen. Mögliche Werte: + - `all`: Widerrufe alle Grants, die mit der Sitzung verbunden sind. + - `firstParty`: Widerrufe nur First-Party-App-Grants, die mit der Sitzung verbunden sind. (Empfohlen für die meisten Anwendungsfälle, da es den Zugriff für deine eigene App widerruft, während Third-Party-App-Grants intakt bleiben, was eine bessere Benutzererfahrung bietet.) + - nicht angegeben: Standardverhalten widerruft Grants, die nicht den `offline_access`-Bereich haben, was typischerweise bedeutet, dass nicht-Auffrischungstoken-Grants für die Sitzung widerrufen werden. + +### Benutzerautorisierte Apps (Grants) verwalten \{#manage-user-authorized-apps-grants} + +Verwende Benutzerautorisierte Apps (Grants) APIs, wenn Benutzer autorisierte Apps von ihrer Kontoeinstellungsseite aus überprüfen und widerrufen müssen. + +:::note + +- App-Grant-APIs teilen dasselbe Berechtigungsmodell wie Sitzungs-APIs. +- `UserScope.Sessions` Berechtigung ist erforderlich. +- `Sessions`-Feld in den Konto-Center-Einstellungen muss aktiviert sein: + - `ReadOnly` oder `Edit`, um Grants aufzulisten. + - `Edit`, um Grants zu widerrufen. + +::: + +**Aktive App-Grants auflisten** + +Um aktive App-Grants des aktuellen Benutzers aufzulisten, verwende den [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) Endpunkt. + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Optionaler Abfrageparameter: + +- `appType=firstParty`: Gibt nur First-Party-App-Grants zurück. +- `appType=thirdParty`: Gibt nur Third-Party-App-Grants zurück. +- `appType` weglassen: Gibt alle aktiven Grants zurück. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**App-Grant nach Grant-ID widerrufen** + +Um einen bestimmten App-Grant zu widerrufen, verwende den [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) Endpunkt. + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Wenn ein Grant widerrufen wird, werden zuvor ausgegebene opake Zugangstokens und Auffrischungstokens für diesen Grant ungültig. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index dfad5a50859..3ac51707e1b 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -6,21 +6,20 @@ sidebar_position: 2 ## Integrationen \{#integrations} -Logto stellt verschiedene Management API zur Verfügung, um Benutzerkonten zu verwalten. Du kannst diese APIs nutzen, um eine Self-Service-Kontoeinstellungsseite für Endbenutzer zu erstellen. +Logto bietet verschiedene Management API, um Benutzerkonten zu verwalten. Du kannst diese APIs verwenden, um eine Selbstbedienungs-Kontoeinstellungsseite für Endbenutzer zu erstellen. ### Architektur \{#architecture} ```mermaid graph TB - A[Benutzer] - --> B[Client-Anwendung] - B -->|Self-hosted Kontoeinstellungen API-Aufruf|C[Serverseitige Anwendung] + A[Benutzer] --> B[Client-Anwendung] + B -->|Selbstgehosteter Kontoeinstellungen API-Aufruf|C[Serverseitige Anwendung] C -->|Management API-Aufruf| D[Logto] ``` -1. **Benutzer**: Authentifizierter Endbenutzer, der auf seine Kontoeinstellungen zugreifen und diese verwalten möchte. +1. **Benutzer**: Authentifizierter Endbenutzer, der auf seine Kontoeinstellungen zugreifen und diese verwalten muss. 2. **Client-Anwendung**: Deine Client-Anwendung, die dem Benutzer die Kontoeinstellungsseite bereitstellt. -3. **Serverseitige Anwendung**: Serverseitige Anwendung, die die Kontoeinstellungen-API für den Client bereitstellt. Kommuniziert mit der Logto Management API. +3. **Serverseitige Anwendung**: Serverseitige Anwendung, die die Kontoeinstellungen API für den Client bereitstellt. Interagiert mit der Logto Management API. 4. **Logto**: Logto als Authentifizierungs- und Autorisierungsdienst. Stellt die Management API zur Verwaltung von Benutzerkonten bereit. ### Sequenzdiagramm \{#sequence-diagram} @@ -40,7 +39,7 @@ Logto stellt verschiedene Management API zur Verfügung, um Benutzerkonten zu ve Client ->> Logto: POST /oidc/token Logto ->> Client: Zugangstoken A Client ->> Server: GET /account-settings (mit Zugangstoken A) - Server ->> Logto: POST /oidc/token (mit Client-Credentials) + Server ->> Logto: POST /oidc/token (mit Client-Anmeldedaten) Logto ->> Server: Zugangstoken B Server ->> Logto: GET /api/users/{userId} (mit Zugangstoken B) Logto ->> Server: Benutzerdetails @@ -50,19 +49,19 @@ Logto stellt verschiedene Management API zur Verfügung, um Benutzerkonten zu ve 1. Der Benutzer greift auf die Client-Anwendung zu. 2. Die Client-Anwendung sendet die Authentifizierungsanfrage an Logto und leitet den Benutzer zur Logto-Anmeldeseite weiter. 3. Der Benutzer meldet sich bei Logto an. -4. Der authentifizierte Benutzer wird mit dem Autorisierungscode zurück zur Client-Anwendung geleitet. -5. Die Client-Anwendung fordert das Zugangstoken von Logto für den Zugriff auf die Self-hosted Kontoeinstellungen-API an. +4. Der authentifizierte Benutzer wird mit dem Autorisierungscode zurück zur Client-Anwendung weitergeleitet. +5. Die Client-Anwendung fordert das Zugangstoken von Logto für den Zugriff auf die selbstgehostete Kontoeinstellungen API an. 6. Logto gewährt der Client-Anwendung das Zugangstoken. -7. Die Client-Anwendung sendet die Kontoeinstellungen-Anfrage an die serverseitige Anwendung mit dem Benutzer-Zugangstoken. -8. Die serverseitige Anwendung prüft die Identität und Berechtigung des Anfragenden anhand des Benutzer-Zugangstokens. Dann fordert sie ein Management API-Zugangstoken von Logto an. +7. Die Client-Anwendung sendet die Anfrage für die Kontoeinstellungen an die serverseitige Anwendung mit dem Benutzer-Zugangstoken. +8. Die serverseitige Anwendung überprüft die Identität und Berechtigung des Anfragenden aus dem Benutzer-Zugangstoken. Dann fordert sie ein Management API-Zugangstoken von Logto an. 9. Logto gewährt der serverseitigen Anwendung das Management API-Zugangstoken. 10. Die serverseitige Anwendung fordert die Benutzerdaten von Logto mit dem Management API-Zugangstoken an. -11. Logto prüft die Identität des Servers und die Management API-Berechtigung und gibt die Benutzerdaten zurück. -12. Die serverseitige Anwendung verarbeitet die Benutzerdaten basierend auf der Berechtigung des Anfragenden und gibt die Kontodetails an die Client-Anwendung zurück. +11. Logto überprüft die Identität des Servers und die Management API-Berechtigung und gibt die Benutzerdaten zurück. +12. Die serverseitige Anwendung verarbeitet die Benutzerdaten basierend auf der Berechtigung des Anfragenden und gibt die Kontodetails des Benutzers an die Client-Anwendung zurück. ### Management API in serverseitige Anwendung integrieren \{#integrate-management-api-to-server-side-application} -Sieh dir den Abschnitt [Management API](/integrate-logto/interact-with-management-api/) an, um zu erfahren, wie du die Management APIs in serverseitige Anwendungen integrierst. +Sieh dir den Abschnitt [Management API](/integrate-logto/interact-with-management-api/) an, um zu erfahren, wie du die Management APIs in serverseitige Anwendungen integrieren kannst. ## Benutzerverwaltungs-APIs \{#user-management-apis} @@ -70,53 +69,53 @@ Sieh dir den Abschnitt [Management API](/integrate-logto/interact-with-managemen Sieh dir den Abschnitt [Benutzerdaten und benutzerdefinierte Daten](/user-management/user-data/) an, um mehr über das Benutzerschema in Logto zu erfahren. -### Benutzerprofil- und Identifikatoren-Management APIs \{#user-profile-and-identifiers-management-apis} +### Benutzerprofil- und Identifikatoren-Management-APIs \{#user-profile-and-identifiers-management-apis} -Das Profil und die Identifikatoren eines Benutzers sind essenziell für die Benutzerverwaltung. Du kannst die folgenden APIs verwenden, um Benutzerprofile und Identifikatoren zu verwalten. +Das Profil und die Identifikatoren eines Benutzers sind entscheidend für die Benutzerverwaltung. Du kannst die folgenden APIs verwenden, um Benutzerprofile und Identifikatoren zu verwalten. -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Benutzerdetails aktualisieren. | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Benutzerprofilfelder nach Benutzer-ID aktualisieren. | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Benutzerdefinierte Daten nach Benutzer-ID abrufen. | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Benutzerdefinierte Daten nach Benutzer-ID aktualisieren. | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Sperrstatus des Benutzers nach Benutzer-ID aktualisieren. | +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Benutzerdetails aktualisieren. | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Benutzerprofilfelder nach Benutzer-ID aktualisieren. | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Benutzerdefinierte Daten nach Benutzer-ID abrufen. | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Benutzerdefinierte Daten nach Benutzer-ID aktualisieren. | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Benutzer-Suspendierungsstatus nach Benutzer-ID aktualisieren. | -### E-Mail- und Telefonnummer-Verifizierung \{#email-and-phone-number-verification} +### E-Mail- und Telefonnummern-Verifizierung \{#email-and-phone-number-verification} -Im Logto-System können sowohl E-Mail-Adressen als auch Telefonnummern als Benutzeridentifikatoren dienen, weshalb deren Verifizierung unerlässlich ist. Dafür stellen wir eine Reihe von Verifizierungscode-APIs bereit, um die angegebene E-Mail oder Telefonnummer zu verifizieren. +Im Logto-System können sowohl E-Mail-Adressen als auch Telefonnummern als Benutzeridentifikatoren dienen, weshalb ihre Verifizierung unerlässlich ist. Um dies zu unterstützen, bieten wir eine Reihe von Verifizierungscode-APIs an, um die bereitgestellte E-Mail oder Telefonnummer zu verifizieren. :::note Stelle sicher, dass du die E-Mail oder Telefonnummer verifizierst, bevor du das Benutzerprofil mit einer neuen E-Mail oder Telefonnummer aktualisierst. ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Verifizierungscode für E-Mail oder Telefonnummer senden. | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | E-Mail oder Telefonnummer mit Verifizierungscode prüfen. | +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Verifizierungscode für E-Mail oder Telefonnummer senden. | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | E-Mail oder Telefonnummer durch Verifizierungscode verifizieren. | -### Benutzerpasswortverwaltung \{#user-password-management} +### Benutzer-Passwortverwaltung \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Aktuelles Benutzerpasswort nach Benutzer-ID prüfen. | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Benutzerpasswort nach Benutzer-ID aktualisieren. | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Prüfen, ob der Benutzer ein Passwort hat. | +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Aktuelles Benutzerpasswort nach Benutzer-ID verifizieren. | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Benutzerpasswort nach Benutzer-ID aktualisieren. | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Überprüfen, ob der Benutzer ein Passwort hat, nach Benutzer-ID. | :::note -Stelle sicher, dass du das aktuelle Passwort des Benutzers prüfst, bevor du das Passwort aktualisierst. +Stelle sicher, dass du das aktuelle Passwort des Benutzers verifizierst, bevor du das Passwort des Benutzers aktualisierst. ::: -### Verwaltung sozialer Identitäten des Benutzers \{#user-social-identities-management} +### Verwaltung sozialer Identitäten von Benutzern \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. Die sozialen Identitäten findest du im Feld `identities`. | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Eine authentifizierte soziale Identität mit dem Benutzer nach Benutzer-ID verknüpfen. | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Eine soziale Identität vom Benutzer nach Benutzer-ID trennen. | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Eine mit dem Benutzer verknüpfte soziale Identität direkt aktualisieren. | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Die Autorisierungs-URI für einen sozialen Identitätsanbieter abrufen. Nutze diese URI, um eine neue Verbindung zu initiieren. | +| Methode | Pfad | Beschreibung | +| ------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. Die sozialen Identitäten sind im Feld `identities` zu finden. | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Eine authentifizierte soziale Identität mit dem Benutzer nach Benutzer-ID verknüpfen. | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Eine soziale Identität vom Benutzer nach Benutzer-ID trennen. | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Eine mit dem Benutzer verknüpfte soziale Identität direkt nach Benutzer-ID aktualisieren. | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Die Autorisierungs-URI für einen sozialen Identitätsanbieter abrufen. Verwende diese URI, um eine neue soziale Identitätsverbindung zu initiieren. | ```mermaid sequenceDiagram @@ -127,79 +126,94 @@ sequenceDiagram participant Logto as Logto participant IdP as Sozialer Identitätsanbieter - User ->> Client: Zugriff auf Client-App, Anfrage zur Bindung sozialer Identität + User ->> Client: Zugriff auf Client-App-Anfrage zur Bindung sozialer Identität Client ->> App: Anfrage zur Bindung sozialer Identität senden App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: Autorisierungs-URI App ->> Client: Autorisierungs-URI zurückgeben Client ->> IdP: Weiterleitung zur IdP-Autorisierungsseite - User -->> IdP: Anmeldung beim IdP + User -->> IdP: Anmeldung bei IdP IdP ->> Client: Weiterleitung zur Client-App mit Autorisierungscode - Client ->> Server: Anfrage zur Verknüpfung sozialer Identität, Weiterleitung der IdP-Antwort + Client ->> Server: Anfrage zur Verknüpfung sozialer Identität, Weiterleitung der IdP-Autorisierungsantwort Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: Benutzerinfo vom IdP mit Autorisierungscode abrufen - IdP ->> Logto: Benutzerinfo zurückgeben + Logto ->> IdP: Benutzerinformationen von IdP mit Autorisierungscode abrufen + IdP ->> Logto: Benutzerinformationen zurückgeben ``` 1. Der Benutzer greift auf die Client-Anwendung zu und fordert die Bindung einer sozialen Identität an. 2. Die Client-Anwendung sendet eine Anfrage an den Server, um eine soziale Identität zu binden. -3. Der Server sendet eine Anfrage an Logto, um die Autorisierungs-URI für den sozialen Identitätsanbieter zu erhalten. Du musst deinen eigenen `state`-Parameter und `redirect_uri` in der Anfrage angeben. Stelle sicher, dass du die `redirect_uri` beim sozialen Identitätsanbieter registrierst. +3. Der Server sendet eine Anfrage an Logto, um die Autorisierungs-URI für den sozialen Identitätsanbieter zu erhalten. Du musst deinen eigenen `state`-Parameter und `redirect_uri` in der Anfrage bereitstellen. Stelle sicher, dass du die `redirect_uri` beim sozialen Identitätsanbieter registrierst. 4. Logto gibt die Autorisierungs-URI an den Server zurück. 5. Der Server gibt die Autorisierungs-URI an die Client-Anwendung zurück. 6. Die Client-Anwendung leitet den Benutzer zur IdP-Autorisierungs-URI weiter. 7. Der Benutzer meldet sich beim IdP an. -8. Der IdP leitet den Benutzer mit dem Autorisierungscode und der `redirect_uri` zurück zur Client-Anwendung. -9. Die Client-Anwendung validiert den `state` und leitet die IdP-Antwort an den Server weiter. +8. Der IdP leitet den Benutzer mit dem Autorisierungscode zurück zur Client-Anwendung unter Verwendung der `redirect_uri`. +9. Die Client-Anwendung validiert den `state` und leitet die IdP-Autorisierungsantwort an den Server weiter. 10. Der Server sendet eine Anfrage an Logto, um die soziale Identität mit dem Benutzer zu verknüpfen. -11. Logto holt die Benutzerinformationen vom IdP mit dem Autorisierungscode. +11. Logto ruft die Benutzerinformationen vom IdP mit dem Autorisierungscode ab. 12. Der IdP gibt die Benutzerinformationen an Logto zurück und Logto verknüpft die soziale Identität mit dem Benutzer. :::note -Es gibt einige Einschränkungen, die beim Verknüpfen neuer sozialer Identitäten mit einem Benutzer zu beachten sind: +Es gibt einige Einschränkungen, die bei der Verknüpfung neuer sozialer Identitäten mit einem Benutzer zu beachten sind: -- Die Management API hat keinen Sitzungs-Kontext. Jeder Social Connector, der eine aktive Sitzung benötigt, um den sozialen Authentifizierungsstatus sicher zu halten, kann nicht über die Management API verknüpft werden. Nicht unterstützte Connectoren sind apple, Standard-OIDC und Standard-OAuth 2.0 Connector. -- Aus demselben Grund kann Logto den `state`-Parameter in der Autorisierungsantwort nicht prüfen. Stelle sicher, dass du den `state`-Parameter in deiner Client-App speicherst und prüfst, wenn die Autorisierungsantwort empfangen wird. -- Du musst die `redirect_uri` im Voraus beim sozialen Identitätsanbieter registrieren. Andernfalls wird der soziale IdP den Benutzer nicht zurück zu deiner Client-App weiterleiten. Dein sozialer IdP muss mehr als eine Callback-`redirect_uri` akzeptieren, eine für die Benutzeranmeldung, eine für deine eigene Profilbindungsseite. +- Die Management API hat keinen Sitzungs-Kontext. Jeder soziale Connector, der eine aktive Sitzung erfordert, um den sozialen Authentifizierungsstatus sicher aufrechtzuerhalten, kann nicht über die Management API verknüpft werden. Nicht unterstützte Connectoren sind Apple, Standard OIDC und Standard OAuth 2.0 Connector. +- Aus dem gleichen Grund kann Logto den `state`-Parameter in der Autorisierungsantwort nicht verifizieren. Stelle sicher, dass du den `state`-Parameter in deiner Client-App speicherst und validierst, wenn die Autorisierungsantwort empfangen wird. +- Du musst die `redirect_uri` im Voraus beim sozialen Identitätsanbieter registrieren. Andernfalls wird der soziale IdP den Benutzer nicht zurück zu deiner Client-App weiterleiten. Dein sozialer IdP muss mehr als eine Rückruf-`redirect_uri` akzeptieren, eine für die Benutzeranmeldung, eine für deine eigene Profilbindungsseite. ::: -### Verwaltung von Enterprise-Identitäten des Benutzers \{#user-enterprise-identities-management} +### Verwaltung von Unternehmensidentitäten von Benutzern \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. Die Enterprise-Identitäten findest du im Feld `ssoIdentities`. Füge den Query-Parameter `includeSsoIdentities=true` hinzu, um sie einzuschließen. | +| Methode | Pfad | Beschreibung | +| ------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Benutzerdetails nach Benutzer-ID abrufen. Die Unternehmensidentitäten sind im Feld `ssoIdentities` zu finden. Füge den Abfrageparameter `includeSsoIdentities=true` zur Benutzerdetails-API hinzu, um sie einzuschließen. | -Derzeit unterstützt die Management API nicht das Verknüpfen oder Trennen von Enterprise-Identitäten mit einem Benutzer. Du kannst nur die mit einem Benutzer verknüpften Enterprise-Identitäten anzeigen. +Derzeit unterstützt die Management API nicht das Verknüpfen oder Trennen von Unternehmensidentitäten mit einem Benutzer. Du kannst nur die mit einem Benutzer verknüpften Unternehmensidentitäten anzeigen. -### Persönlicher Zugangstoken \{#personal-access-token} +### Persönliches Zugangstoken \{#personal-access-token} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Alle persönlichen Zugangstokens des Benutzers abrufen. | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Einen neuen persönlichen Zugangstoken für den Benutzer hinzufügen. | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Einen Token für den Benutzer nach Name löschen. | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Einen Token für den Benutzer nach Name aktualisieren. | +| Methode | Pfad | Beschreibung | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Alle persönlichen Zugangstokens für den Benutzer abrufen. | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Ein neues persönliches Zugangstoken für den Benutzer hinzufügen. | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Ein Token für den Benutzer nach Name löschen. | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Ein Token für den Benutzer nach Name aktualisieren. | -Persönliche Zugangstokens bieten eine sichere Möglichkeit für Benutzer, [Zugangstoken (Access token)](https://auth.wiki/access-token) zu gewähren, ohne ihre Zugangsdaten und interaktive Anmeldung zu verwenden. Erfahre mehr über [die Verwendung persönlicher Zugangstokens](/user-management/personal-access-token). +Persönliche Zugangstokens bieten eine sichere Möglichkeit für Benutzer, ein [Zugangstoken](https://auth.wiki/access-token) zu gewähren, ohne ihre Anmeldedaten und interaktive Anmeldung zu verwenden. Erfahre mehr über [die Verwendung persönlicher Zugangstokens](/user-management/personal-access-token). -### Verwaltung der MFA-Einstellungen des Benutzers \{#user-mfa-settings-management} +### Verwaltung der Benutzer-MFA-Einstellungen \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | MFA-Einstellungen des Benutzers nach Benutzer-ID abrufen. | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Eine MFA-Verifizierung für den Benutzer einrichten. | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Eine MFA-Verifizierung des Benutzers nach ID löschen. | +| Methode | Pfad | Beschreibung | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Benutzer-MFA-Einstellungen nach Benutzer-ID abrufen. | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Eine Benutzer-MFA-Verifizierung nach Benutzer-ID einrichten. | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Eine Benutzer-MFA-Verifizierung nach ID löschen. | -### Benutzerkonto löschen \{#user-account-deletion} +### Benutzerkontolöschung \{#user-account-deletion} -| method | path | description | -| ------ | -------------------------------------------------------------------------------- | ---------------------------------------- | -| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Einen Benutzer nach Benutzer-ID löschen. | +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------- | ---------------------------------------- | +| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Einen Benutzer nach Benutzer-ID löschen. | ### Verwaltung von Benutzersitzungen \{#user-session-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Benutzersitzungen nach Benutzer-ID abrufen. | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Eine Benutzersitzung nach Sitzungs-ID abrufen. | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Eine Benutzersitzung nach Sitzungs-ID löschen. | +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Benutzersitzungen nach Benutzer-ID abrufen. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Eine Benutzersitzung nach Sitzungs-ID abrufen. | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Eine Benutzersitzung nach Sitzungs-ID löschen. | + +### Verwaltung der autorisierten Apps eines Benutzers (Grants) \{#manage-user-authorized-apps-grants} + +| Methode | Pfad | Beschreibung | +| ------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | Aktive App-Grants für den Benutzer auflisten. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | Einen bestimmten App-Grant nach ID widerrufen. | + +Optionaler Abfrageparameter für die Grant-Auflistung: + +- `appType=firstParty`: Nur First-Party-App-Grants zurückgeben. +- `appType=thirdParty`: Nur Third-Party-App-Grants zurückgeben. +- `appType` weglassen: Alle aktiven Grants zurückgeben. + +Wenn ein Grant widerrufen wird, werden zuvor ausgegebene opake Zugangstokens und Auffrischungstokens für diesen Grant ungültig. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index caa7cebb132..7b865c341b9 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,233 +1,99 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- -# Abmelden +# Abmeldung -Das Abmelden in Logto (als OIDC-Identitätsanbieter) umfasst sowohl: +Die Abmeldung in Logto umfasst zwei Ebenen: -- Eine **zentralisierte Logto-Sitzung** (Browser-Cookie unter der Logto-Domain) als auch -- **Verteilten clientseitigen Auth-Status** (Tokens und lokale App-Sitzung in jeder App). +- **Logto-Sitzungsabmeldung**: Beendet die zentrale Anmeldesitzung unter der Logto-Domain. +- **App-Abmeldung**: Löscht den lokalen Sitzungsstatus und die Tokens in deiner Client-Anwendung. -Um das Abmeldeverhalten zu verstehen, hilft es, diese beiden Ebenen zu trennen und dann zu sehen, wie **Grants** sie verbinden. +Um besser zu verstehen, wie Sitzungen in Logto funktionieren, siehe [Sitzungen](/sessions). -## Zentrale Konzepte \{#core-concepts} +## Abmeldemechanismen \{#sign-out-mechanisms} -### Was ist eine Logto-Sitzung? \{#what-is-a-logto-session} +### 1) Nur clientseitige Abmeldung \{#1-client-side-only-sign-out} -Eine Logto-Sitzung ist der zentralisierte Anmeldestatus, der von Logto verwaltet wird. Sie wird nach erfolgreicher Authentifizierung erstellt und durch Cookies unter der Logto-Domain repräsentiert. - -Wenn das Sitzungs-Cookie gültig ist, kann der Benutzer stillschweigend (SSO) über mehrere Apps hinweg authentifiziert werden, die demselben Logto-Tenant vertrauen. - -Wenn keine gültige Sitzung existiert, zeigt Logto die Anmeldeseite an. - -### Was sind Grants? \{#what-are-grants} - -Ein **Grant** repräsentiert den Autorisierungsstatus für eine bestimmte Kombination aus Benutzer + Client-Anwendung. - -- Eine Logto-Sitzung kann Grants für mehrere Client-Apps haben. -- Ein Grant ist das, womit ausgegebene Tokens verknüpft sind. -- In dieser Dokumentation wird **Grant** als die bereichsübergreifende Autorisierungseinheit verwendet. - -### Wie hängen Sitzung, Grants und Client-Auth-Status zusammen? \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto-Domain] - S[Logto-Sitzung] - G1[Grant für App A] - G2[Grant für App B] - end - - subgraph AppA [Client-Domain A] - A[Lokale Sitzung / Tokens] - end - - subgraph AppB [Client-Domain B] - B[Lokale Sitzung / Tokens] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Logto-Sitzung** steuert die zentralisierte SSO-Erfahrung. -- **Lokale Client-Sitzung / Tokens** steuern, ob jede App den Benutzer aktuell als angemeldet behandelt. -- **Grants** verbinden diese beiden Welten, indem sie den app-spezifischen Autorisierungsstatus repräsentieren. - -## Sign-in Rückblick (warum Sign-out mehrschichtig ist) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as Client-Anwendung - end - - box Logto (IdP) - participant OIDC as OIDC-Anbieter - participant SignIn as Anmeldeseite - end - - User ->> Client: Anwendung aufrufen - Client ->> OIDC: Weiterleitung zur Authentifizierung - OIDC -->> OIDC: Logto-Sitzung prüfen - OIDC ->> SignIn: Anmeldung anfordern, falls nötig - SignIn ->> OIDC: Benutzer authentifiziert sich - OIDC -->> OIDC: Sitzung und Grant erstellen - OIDC ->> Client: Autorisierungscode zurückgeben - Client ->> OIDC: Code gegen Tokens tauschen - OIDC -->> Client: Tokens zurückgeben -``` - -## Sitzungs-Topologie über Apps / Geräte hinweg \{#session-topology-across-apps-devices} - -### Geteiltes Sitzungs-Cookie (gleicher Browser / User Agent) \{#shared-session-cookie-same-browser-user-agent} - -Wenn sich ein Benutzer in mehreren Apps im selben Browser anmeldet, können diese Apps dasselbe Logto-Sitzungs-Cookie wiederverwenden und SSO-Verhalten gilt. - -```mermaid -flowchart TD - U[Benutzer] - A["Client-Anwendung A (Client-Domain A)"] - B["Client-Anwendung B (Client-Domain B)"] - C{"Logto-Sitzung vorhanden? (Logto-Domain)"} - D["Anmeldeseite (Logto-Domain)"] - - subgraph UA["User Agent A (gleicher Browser)"] - U - A - B - C - D - end - - U -->|Anmelden| A - A -->|Weiterleitung zu Logto| C - U -->|App öffnen| B - B -->|Weiterleitung zu Logto| C - C -->|Nein| D - D -->|Sitzung erstellen| C -``` - -### Isolierte Sitzungs-Cookies (verschiedene Geräte / Browser) \{#isolated-session-cookies-different-devices-browsers} - -Verschiedene Browser / Geräte halten unterschiedliche Logto-Cookies, daher ist der Anmeldestatus isoliert. - -```mermaid -flowchart TD - U[Benutzer] - A["Client-Anwendung A (Client-Domain A)"] - C{"Logto-Sitzung vorhanden? (Gerät A, Logto-Domain)"} - D["Anmeldeseite (Gerät A, Logto-Domain)"] - - subgraph DeviceA["User Agent A"] - A - C - D - end - - B["Client-Anwendung B (Client-Domain B)"] - E{"Logto-Sitzung vorhanden? (Gerät B, Logto-Domain)"} - F["Anmeldeseite (Gerät B, Logto-Domain)"] - - subgraph DeviceB["User Agent B"] - B - E - F - end - - U -->|Anmelden| A - A -->|Weiterleitung zu Logto| C - U -->|Anmelden| B - B -->|Weiterleitung zu Logto| E - C -->|Nein| D - E -->|Nein| F - D -->|Sitzung erstellen| C - F -->|Sitzung erstellen| E -``` - -## Abmelde-Mechanismen \{#sign-out-mechanisms} - -### 1) Nur clientseitiges Abmelden \{#1-client-side-only-sign-out} - -Die Client-App löscht ihre eigene lokale Sitzung und Tokens (ID- / Zugangstoken / Auffrischungstoken). Dadurch wird der Benutzer nur aus dem lokalen Zustand dieser App abgemeldet. +Die Client-App löscht ihre eigene lokale Sitzung und Tokens (ID- / Zugangs- / Auffrischungstokens). Dies meldet den Benutzer nur aus dem lokalen Zustand dieser App ab. - Die Logto-Sitzung kann weiterhin aktiv sein. - Andere Apps unter derselben Logto-Sitzung können weiterhin SSO nutzen. -### 2) End-Sitzung bei Logto (globales Abmelden in aktueller Logto-Implementierung) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +### 2) Sitzung bei Logto beenden (globale Abmeldung in der aktuellen Logto-Implementierung) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -Um die zentralisierte Logto-Sitzung zu löschen, leitet die App den Benutzer zum End-Sitzung-Endpunkt weiter, zum Beispiel: +Um die zentrale Logto-Sitzung zu löschen, leitet die App den Benutzer zum End-Sitzungs-Endpunkt weiter, zum Beispiel: `https://{your-logto-domain}/oidc/session/end` -Im aktuellen Logto SDK-Verhalten: +Im aktuellen Verhalten des Logto SDK: 1. `signOut()` leitet zu `/session/end` weiter. 2. Dann geht es zu `/session/end/confirm`. -3. Das Standard-Bestätigungsformular sendet automatisch `logout=true`. +3. Das Standardbestätigungsformular sendet automatisch `logout=true`. + +Als Ergebnis wird die aktuelle SDK-Abmeldung als **globale Abmeldung** behandelt. -Dadurch wird das aktuelle SDK-Abmelden als **globales Abmelden** behandelt. +:::note + +- **Globale Abmeldung**: Widerruft die zentrale Logto-Sitzung. + +::: -### Was passiert beim globalen Abmelden \{#what-happens-during-global-sign-out} +### Was passiert während der globalen Abmeldung \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["Client startet Abmelden"] --> B["/session/end"] + A["Client startet Abmeldung"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["Zentralisierte Logto-Sitzung widerrufen"] - D --> E{"Pro-App-Grant prüfen"} - E -->|"offline_access nicht gewährt"| F["Grant widerrufen"] - E -->|"offline_access gewährt"| G["Grant bleibt bis Grant-TTL abläuft"] + C --> D["Zentrale Logto-Sitzung widerrufen"] + D --> E{"Prüfe pro-App-Gewährung"} + E -->|"offline_access nicht gewährt"| F["Gewährung widerrufen"] + E -->|"offline_access gewährt"| G["Gewährung behalten, bis Gewährung TTL abläuft"] ``` -Beim globalen Abmelden gilt: +Während der globalen Abmeldung: -- Die zentralisierte Logto-Sitzung wird widerrufen. -- Zugehörige App-Grants werden je nach Autorisierungsstatus der App behandelt: - - Wenn `offline_access` **nicht** gewährt ist, werden die zugehörigen Grants widerrufen. - - Wenn `offline_access` **gewährt** ist, werden Grants durch End-Sitzung nicht widerrufen. -- Bei `offline_access`-Fällen bleiben Auffrischungstoken und Grants bis zum Ablauf des Grants gültig. +- Die zentrale Logto-Sitzung wird widerrufen. +- Zugehörige App-Gewährungen werden je nach Autorisierungsstatus der App behandelt: + - Wenn `offline_access` **nicht** gewährt ist, werden zugehörige Gewährungen widerrufen. + - Wenn `offline_access` **gewährt** ist, werden Gewährungen nicht durch End-Sitzung widerrufen. +- Bei `offline_access`-Fällen bleiben Auffrischungstokens und Gewährungen gültig, bis die Gewährung abläuft. -## Grant-Lebensdauer und Auswirkung von `offline_access` \{#grant-lifetime-and-offline-access-impact} +## Gewährungslebensdauer und `offline_access`-Auswirkung \{#grant-lifetime-and-offline-access-impact} -- Die Standard-Grant-TTL in Logto beträgt **180 Tage**. -- Wenn `offline_access` gewährt ist, wird der App-Grant durch End-Sitzung standardmäßig nicht widerrufen. -- Die mit diesem Grant verknüpfte Auffrischungstoken-Kette kann weiterlaufen, bis der Grant abläuft (oder explizit widerrufen wird). +- Die Standard-Logto-Gewährung TTL beträgt **180 Tage**. +- Wenn `offline_access` gewährt ist, widerruft die End-Sitzung diese App-Gewährung standardmäßig nicht. +- Die mit dieser Gewährung verbundene Auffrischungstoken-Kette kann fortgesetzt werden, bis die Gewährung abläuft (oder explizit widerrufen wird). -## Föderiertes Abmelden: Back-Channel-Logout \{#federated-sign-out-back-channel-logout} +## Föderierte Abmeldung: Back-Channel-Logout \{#federated-sign-out-back-channel-logout} -Für bereichsübergreifende Konsistenz unterstützt Logto [Back-Channel-Logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). +Für Konsistenz über Apps hinweg unterstützt Logto [Back-Channel-Logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). -Wenn sich ein Benutzer von einer App abmeldet, kann Logto alle Apps, die an derselben Sitzung teilnehmen, benachrichtigen, indem ein Logout-Token an jede registrierte Back-Channel-Logout-URI gesendet wird. +Wenn sich ein Benutzer von einer App abmeldet, kann Logto alle Apps, die an derselben Sitzung teilnehmen, benachrichtigen, indem es ein Logout-Token an die registrierte Back-Channel-Logout-URI jeder App sendet. Wenn `Is session required` in den Back-Channel-Einstellungen der App aktiviert ist, enthält das Logout-Token `sid`, um die Logto-Sitzung zu identifizieren. Typischer Ablauf: -1. Benutzer startet Abmelden in einer App. -2. Logto verarbeitet End-Sitzung und sendet Logout-Token(s) an registrierte Back-Channel-Logout-URI(s). +1. Benutzer initiiert Abmeldung von einer App. +2. Logto verarbeitet die End-Sitzung und sendet Logout-Token(s) an die registrierte Back-Channel-Logout-URI(s). 3. Jede App validiert das Logout-Token und löscht ihre eigene lokale Sitzung / Tokens. -## Abmelde-Methoden in Logto SDKs \{#sign-out-methods-in-logto-sdks} +## Abmeldemethoden in Logto SDKs \{#sign-out-methods-in-logto-sdks} -- **SPA und Web**: `client.signOut()` löscht den lokalen Token-Speicher und leitet zum Logto-End-Sitzung-Endpunkt weiter. Du kannst eine Post-Logout-Redirect-URI angeben. -- **Native (einschließlich React Native / Flutter)**: löscht in der Regel nur den lokalen Token-Speicher. Sitzungslose Webviews bedeuten, dass kein persistentes Logto-Browser-Cookie gelöscht werden muss. +- **SPA und Web**: `client.signOut()` löscht den lokalen Token-Speicher und leitet zur Logto-End-Sitzungs-Endpoint weiter. Du kannst eine Post-Logout-Redirect-URI angeben. +- **Native (einschließlich React Native / Flutter)**: löscht normalerweise nur den lokalen Token-Speicher. Sitzungslose Webansicht bedeutet, dass kein persistentes Logto-Browser-Cookie gelöscht werden muss. :::note -Für native Anwendungen, die keine sitzungslose Webview unterstützen oder die `emphasized` Einstellungen nicht erkennen (Android-App mit **React Native** oder **Flutter** SDK), kannst du den Benutzer zwingen, sich erneut anzumelden, indem du den Parameter `prompt=login` in der Authentifizierungsanfrage übergibst. +Für native Anwendungen, die keine sitzungslose Webansicht unterstützen oder die `emphasized`-Einstellungen nicht erkennen (Android-App mit **React Native** oder **Flutter** SDK), kannst du den Benutzer dazu zwingen, sich erneut anzumelden, indem du den Parameter `prompt=login` in der Autorisierungsanfrage übergibst. ::: -## Erzwinge Re-Authentifizierung bei jedem Zugriff \{#enforce-re-authentication-on-every-access} +## Erzwinge erneute Authentifizierung bei jedem Zugriff \{#enforce-re-authentication-on-every-access} -Für sicherheitskritische Aktionen füge `prompt=login` in Auth-Anfragen ein, um SSO zu umgehen und jedes Mal die Eingabe der Zugangsdaten zu erzwingen. +Für hochsichere Aktionen füge `prompt=login` in Auth-Anfragen ein, um SSO zu umgehen und die Eingabe von Anmeldedaten jedes Mal zu erzwingen. -Wenn du `offline_access` anforderst (um Auffrischungstoken zu erhalten), füge auch `consent`, `prompt=login consent` hinzu. +Wenn `offline_access` angefordert wird (um Auffrischungstokens zu erhalten), füge auch `consent`, `prompt=login consent` hinzu. Typische kombinierte Einstellung: @@ -252,5 +118,5 @@ prompt=login consent ## Verwandte Ressourcen \{#related-resources} - OIDC Back-Channel-Logout verstehen. + Verständnis des OIDC-Back-Channel-Logouts. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/de/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 1a90c71863c..481c9164636 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: Siehe wichtige Anwendungsparameter für die OIDC-Authentifizierungsintegration, einschließlich Redirect-URIs, Endpunkte, Auffrischungstokens, Backchannel-Logout usw. +description: Beziehen Sie sich auf wichtige Anwendungsparameter für die OIDC-Authentifizierungsintegration, einschließlich Redirect-URIs, Endpunkte, Auffrischungstokens, Backchannel-Logout usw. sidebar_position: 6 --- @@ -7,42 +7,41 @@ sidebar_position: 6 ## Einführung \{#introduction} -In Logto bezeichnet eine _Anwendung_ ein bestimmtes Softwareprogramm oder einen Dienst, der bei der Logto-Plattform registriert ist und die Autorisierung erhalten hat, auf Benutzerinformationen zuzugreifen oder Aktionen im Namen eines Benutzers durchzuführen. Anwendungen werden verwendet, um die Quelle von Anfragen an die Logto API zu identifizieren sowie den Authentifizierungs- und Autorisierungsprozess für Benutzer, die auf diese Anwendungen zugreifen, zu verwalten. +In Logto bezieht sich eine _Anwendung_ auf ein spezifisches Softwareprogramm oder einen Dienst, der bei der Logto-Plattform registriert ist und die Berechtigung erhalten hat, auf Benutzerinformationen zuzugreifen oder Aktionen im Namen eines Benutzers auszuführen. Anwendungen werden verwendet, um die Quelle von Anfragen an die Logto API zu identifizieren und den Authentifizierungs- und Autorisierungsprozess für Benutzer zu verwalten, die auf diese Anwendungen zugreifen. -Die Verwendung von Anwendungen in der Logto-Anmeldeerfahrung ermöglicht es Benutzern, ihre autorisierten Anwendungen einfach von einem zentralen Ort aus zu verwalten und darauf zuzugreifen – mit einem konsistenten und sicheren Authentifizierungsprozess. Dies trägt dazu bei, die Benutzererfahrung zu optimieren und sicherzustellen, dass nur autorisierte Personen auf sensible Informationen zugreifen oder im Namen der Organisation handeln. +Die Verwendung von Anwendungen in Logtos Anmeldeerfahrung ermöglicht es Benutzern, ihre autorisierten Anwendungen von einem einzigen Ort aus einfach zu verwalten und darauf zuzugreifen, mit einem konsistenten und sicheren Authentifizierungsprozess. Dies trägt dazu bei, die Benutzererfahrung zu optimieren und sicherzustellen, dass nur autorisierte Personen auf sensible Informationen zugreifen oder im Namen der Organisation handeln. -Anwendungen werden auch in den Logto-Audit-Logs verwendet, um Benutzeraktivitäten zu verfolgen und potenzielle Sicherheitsbedrohungen oder -verletzungen zu erkennen. Durch die Zuordnung bestimmter Aktionen zu einer bestimmten Anwendung kann Logto detaillierte Einblicke darüber geben, wie Daten abgerufen und verwendet werden, sodass Organisationen ihre Sicherheits- und Compliance-Anforderungen besser verwalten können. -Wenn du deine Anwendung mit Logto integrieren möchtest, siehe [Logto integrieren](/integrate-logto). +Anwendungen werden auch in Logtos Prüfprotokollen verwendet, um Benutzeraktivitäten zu verfolgen und potenzielle Sicherheitsbedrohungen oder -verletzungen zu identifizieren. Durch die Zuordnung spezifischer Aktionen zu einer bestimmten Anwendung kann Logto detaillierte Einblicke in die Art und Weise geben, wie Daten abgerufen und verwendet werden, sodass Organisationen ihre Sicherheits- und Compliance-Anforderungen besser verwalten können. Wenn du deine Anwendung mit Logto integrieren möchtest, siehe [Logto integrieren](/integrate-logto). ## Eigenschaften \{#properties} ### Anwendungs-ID \{#application-id} -_Anwendungs-ID_ ist ein eindeutiger, automatisch generierter Schlüssel zur Identifizierung deiner Anwendung in Logto und wird als [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) in OAuth 2.0 bezeichnet. +_Anwendungs-ID_ ist ein einzigartiger automatisch generierter Schlüssel, um deine Anwendung in Logto zu identifizieren, und wird in OAuth 2.0 als [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) referenziert. ### Anwendungstypen \{#application-types} Eine _Anwendung_ kann einer der folgenden Anwendungstypen sein: -- **Native App** ist eine App, die in einer nativen Umgebung läuft. Z. B. iOS-App, Android-App. - - **Device Flow App** ist ein spezieller Typ einer nativen App für geräte- oder kopflose Anwendungen mit eingeschränkter Eingabe (z. B. Smart-TVs, Spielkonsolen, CLI-Tools, IoT-Geräte). Sie verwendet den [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) anstelle des Standard-Redirect-basierten Flows. Siehe [Device Flow Schnellstart](/quick-starts/device-flow) für Details. -- **Single Page App** ist eine App, die in einem Webbrowser läuft und die Seite mit neuen Daten vom Server aktualisiert, ohne ganze neue Seiten zu laden. Z. B. React DOM App, Vue App. -- **Traditionelle Web-App** ist eine App, die Seiten ausschließlich durch den Webserver rendert und aktualisiert. Z. B. JSP, PHP. -- **Maschine-zu-Maschine (M2M) App** ist eine Anwendung, die in einer Maschinenumgebung für direkte Service-zu-Service-Kommunikation ohne Benutzerinteraktion läuft. +- **Native App** ist eine App, die in einer nativen Umgebung läuft. Z.B. iOS-App, Android-App. + - **Device Flow App** ist ein spezieller Typ von nativer App für gerätebeschränkte oder kopflose Anwendungen (z.B. Smart-TVs, Spielkonsolen, CLI-Tools, IoT-Geräte). Sie verwendet den [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) anstelle des standardmäßigen redirect-basierten Flows. Siehe [Device Flow Schnellstart](/quick-starts/device-flow) für Details. +- **Single Page App** ist eine App, die in einem Webbrowser läuft und die Seite mit neuen Daten vom Server aktualisiert, ohne ganze neue Seiten zu laden. Z.B. React DOM App, Vue App. +- **Traditionelle Web-App** ist eine App, die Seiten ausschließlich vom Webserver rendert und aktualisiert. Z.B. JSP, PHP. +- **Maschine-zu-Maschine (M2M) App** ist eine Anwendung, die in einer Maschinenumgebung für direkte Dienst-zu-Dienst-Kommunikation ohne Benutzerinteraktion läuft. ### Anwendungsschlüssel \{#application-secret} -_Anwendungsschlüssel_ ist ein Schlüssel, der zur Authentifizierung der Anwendung im Authentifizierungssystem verwendet wird, speziell für private Clients (traditionelle Web- und M2M-Apps) als private Sicherheitsbarriere. +_Anwendungsschlüssel_ ist ein Schlüssel, der verwendet wird, um die Anwendung im Authentifizierungssystem zu authentifizieren, speziell für private Clients (Traditionelle Web- und M2M-Apps) als private Sicherheitsbarriere. :::tip -Single Page Apps (SPAs) und Native Apps stellen keinen App-Schlüssel bereit. SPAs und Native Apps sind "öffentliche Clients" und können keine Geheimnisse bewahren (Browser-Code oder App-Bundles sind einsehbar). Anstelle eines App-Schlüssels schützt Logto sie mit PKCE, strikter Redirect-URI/CORS-Validierung, kurzlebigen Zugangstokens und Auffrischungstoken-Rotation. +Single Page Apps (SPAs) und Native Apps bieten keinen App-Schlüssel. SPAs und Native Apps sind "öffentliche Clients" und können keine Geheimnisse bewahren (Browsercode oder App-Bundles sind einsehbar). Anstelle eines App-Schlüssels schützt Logto sie mit PKCE, strikter Redirect-URI/CORS-Validierung, kurzlebigen Zugangstokens und Auffrischungstoken-Rotation. ::: ### Anwendungsname \{#application-name} _Anwendungsname_ ist ein menschenlesbarer Name der Anwendung und wird in der Admin-Konsole angezeigt. -Der _Anwendungsname_ ist ein wichtiger Bestandteil der Verwaltung von Anwendungen in Logto, da er Administratoren ermöglicht, einzelne Anwendungen innerhalb der Plattform einfach zu identifizieren und deren Aktivitäten nachzuverfolgen. +Der _Anwendungsname_ ist ein wichtiger Bestandteil der Verwaltung von Anwendungen in Logto, da er Administratoren ermöglicht, die Aktivität einzelner Anwendungen innerhalb der Plattform leicht zu identifizieren und zu verfolgen. :::note Es ist wichtig zu beachten, dass der _Anwendungsname_ sorgfältig gewählt werden sollte, da er für alle Benutzer sichtbar ist, die Zugriff auf die Admin-Konsole haben. Er sollte den Zweck und die Funktion der Anwendung genau widerspiegeln und gleichzeitig leicht verständlich und erkennbar sein. @@ -50,135 +49,154 @@ Es ist wichtig zu beachten, dass der _Anwendungsname_ sorgfältig gewählt werde ### Beschreibung \{#description} -Eine kurze Beschreibung der Anwendung wird auf der Detailseite der Anwendung in der Admin-Konsole angezeigt. Die Beschreibung soll Administratoren zusätzliche Informationen über die Anwendung geben, wie z. B. deren Zweck, Funktionalität und weitere relevante Details. +Eine kurze Beschreibung der Anwendung wird auf der Detailseite der Admin-Konsole angezeigt. Die Beschreibung soll Administratoren zusätzliche Informationen über die Anwendung bieten, wie ihren Zweck, ihre Funktionalität und alle anderen relevanten Details. ### Redirect-URIs \{#redirect-uris} _Redirect-URIs_ sind eine Liste gültiger Redirect-URIs, die für eine Anwendung vorkonfiguriert wurden. Wenn sich ein Benutzer bei Logto anmeldet und versucht, auf die Anwendung zuzugreifen, wird er zu einer der in den Anwendungseinstellungen angegebenen erlaubten URIs weitergeleitet. -Die Liste der erlaubten URIs wird verwendet, um die Redirect-URI zu validieren, die in der Autorisierungsanfrage von der Anwendung an Logto während des Authentifizierungsprozesses gesendet wird. Wenn die in der Autorisierungsanfrage angegebene Redirect-URI mit einer der erlaubten URIs in den Anwendungseinstellungen übereinstimmt, wird der Benutzer nach erfolgreicher Authentifizierung zu dieser URI weitergeleitet. Wenn die Redirect-URI nicht auf der erlaubten Liste steht, wird der Benutzer nicht weitergeleitet und der Authentifizierungsprozess schlägt fehl. +Die Liste der erlaubten URIs wird verwendet, um die Redirect-URI zu validieren, die in der Autorisierungsanfrage enthalten ist, die von der Anwendung während des Authentifizierungsprozesses an Logto gesendet wird. Wenn die in der Autorisierungsanfrage angegebene Redirect-URI mit einer der erlaubten URIs in den Anwendungseinstellungen übereinstimmt, wird der Benutzer nach erfolgreicher Authentifizierung zu dieser URI weitergeleitet. Wenn die Redirect-URI nicht auf der erlaubten Liste steht, wird der Benutzer nicht weitergeleitet und der Authentifizierungsprozess schlägt fehl. :::note -Es ist wichtig sicherzustellen, dass alle gültigen Redirect-URIs zur erlaubten Liste für eine Anwendung in Logto hinzugefügt werden, damit Benutzer nach der Authentifizierung erfolgreich auf die Anwendung zugreifen können. +Es ist wichtig sicherzustellen, dass alle gültigen Redirect-URIs zur erlaubten Liste für eine Anwendung in Logto hinzugefügt werden, um sicherzustellen, dass Benutzer nach der Authentifizierung erfolgreich auf die Anwendung zugreifen können. ::: -Weitere Informationen findest du beim [Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2). +Du kannst den [Redirection Endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) für weitere Informationen überprüfen. - Redirect-URIs im OIDC mit Authorization Code Flow verstehen + Verständnis von Redirect-URIs in OIDC mit Authorization Code Flow #### Wildcard-Muster \{#wildcard-patterns} _Verfügbarkeit: Single Page App, Traditionelle Web-App_ -Redirect-URIs unterstützen Wildcard-Muster (`*`) für dynamische Umgebungen wie Preview-Deployments. Wildcards können in den Hostnamen- und Pfadkomponenten von HTTP/HTTPS-URIs verwendet werden. +Redirect-URIs unterstützen Wildcard-Muster (`*`) für dynamische Umgebungen wie Vorschau-Bereitstellungen. Wildcards können in den Hostnamen- und Pfadnamen-Komponenten von HTTP/HTTPS-URIs verwendet werden. **Regeln:** - Wildcards sind nur im Hostnamen und Pfadnamen erlaubt -- Wildcards sind nicht im Schema, Port, in Query-Parametern oder Hash-Fragmente erlaubt -- Hostname-Wildcards müssen mindestens einen Punkt enthalten (z. B. `https://*.example.com/callback`) +- Wildcards sind nicht im Schema, Port, in Abfrageparametern oder Hash-Fragmenten erlaubt +- Hostname-Wildcards müssen mindestens einen Punkt enthalten (z.B. `https://*.example.com/callback`) **Beispiele:** -- `https://*.example.com/callback` – passt auf jede Subdomain -- `https://preview-*.example.com/callback` – passt auf Preview-Deployments -- `https://example.com/*/callback` – passt auf jedes Pfadsegment +- `https://*.example.com/callback` - passt zu jedem Subdomain +- `https://preview-*.example.com/callback` - passt zu Vorschau-Bereitstellungen +- `https://example.com/*/callback` - passt zu jedem Pfadsegment :::caution Wildcard-Redirect-URIs sind kein Standard-OIDC und können die Angriffsfläche vergrößern. Verwende sie mit Vorsicht und bevorzuge wann immer möglich exakte Redirect-URIs. ::: -### Post-Sign-out-Redirect-URIs \{#post-sign-out-redirect-uris} +### Post-Sign-out Redirect-URIs \{#post-sign-out-redirect-uris} -_Post-Sign-out-Redirect-URIs_ sind eine Liste gültiger URIs, die für eine Anwendung vorkonfiguriert wurden, um den Benutzer nach dem Abmelden von Logto weiterzuleiten. +_Post-Sign-out Redirect-URIs_ sind eine Liste gültiger URIs, die für eine Anwendung vorkonfiguriert wurden, um den Benutzer nach dem Abmelden von Logto weiterzuleiten. -Die Verwendung von erlaubten _Post-Sign-out-Redirect-URIs_ für Logout ist Teil der RP-Initiated (Relying Party Initiated) Logout-Spezifikation in OIDC. Diese Spezifikation bietet eine standardisierte Methode für Anwendungen, eine Logout-Anfrage für einen Benutzer zu initiieren, einschließlich der Weiterleitung des Benutzers zu einem vorkonfigurierten Endpunkt nach dem Abmelden. +Die Verwendung von erlaubten _Post-Sign-out Redirect-URIs_ für Logout ist Teil der RP-Initiated (Relying Party Initiated) Logout-Spezifikation in OIDC. Diese Spezifikation bietet eine standardisierte Methode für Anwendungen, um eine Abmeldeanforderung für einen Benutzer zu initiieren, die das Weiterleiten des Benutzers zu einem vorkonfigurierten Endpunkt nach dem Abmelden umfasst. -Wenn sich ein Benutzer von Logto abmeldet, wird seine Sitzung beendet und er wird zu einer der in den Anwendungseinstellungen angegebenen erlaubten URIs weitergeleitet. Dies stellt sicher, dass der Benutzer nach dem Abmelden nur zu autorisierten und gültigen Endpunkten weitergeleitet wird, was dazu beiträgt, unbefugten Zugriff und Sicherheitsrisiken im Zusammenhang mit der Weiterleitung zu unbekannten oder nicht verifizierten Endpunkten zu verhindern. +Wenn sich ein Benutzer von Logto abmeldet, wird seine Sitzung beendet und er wird zu einer der in den Anwendungseinstellungen angegebenen erlaubten URIs weitergeleitet. Dies stellt sicher, dass der Benutzer nur zu autorisierten und gültigen Endpunkten weitergeleitet wird, nachdem er sich abgemeldet hat, und hilft, unbefugten Zugriff und Sicherheitsrisiken zu verhindern, die mit der Weiterleitung von Benutzern zu unbekannten oder nicht verifizierten Endpunkten verbunden sind. -Weitere Informationen findest du beim [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout). +Du kannst den [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) für weitere Informationen überprüfen. ### CORS erlaubte Ursprünge \{#cors-allowed-origins} -Die _CORS (Cross-origin resource sharing) erlaubten Ursprünge_ sind eine Liste von erlaubten Ursprüngen, von denen eine Anwendung Anfragen an den Logto-Dienst stellen kann. Jeder Ursprung, der nicht in der erlaubten Liste enthalten ist, kann keine Anfragen an den Logto-Dienst stellen. +Die _CORS (Cross-origin resource sharing) erlaubten Ursprünge_ sind eine Liste von erlaubten Ursprüngen, von denen aus eine Anwendung Anfragen an den Logto-Dienst stellen kann. Jeder Ursprung, der nicht in der erlaubten Liste enthalten ist, kann keine Anfragen an den Logto-Dienst stellen. -Die Liste der erlaubten Ursprünge wird verwendet, um den Zugriff auf den Logto-Dienst von nicht autorisierten Domains einzuschränken und Cross-Site-Request-Forgery (CSRF)-Angriffe zu verhindern. Durch die Angabe der erlaubten Ursprünge für eine Anwendung in Logto kann der Dienst sicherstellen, dass nur autorisierte Domains Anfragen an den Dienst stellen können. +Die Liste der CORS erlaubten Ursprünge wird verwendet, um den Zugriff auf den Logto-Dienst von unbefugten Domains zu beschränken und um Cross-Site-Request-Forgery (CSRF)-Angriffe zu verhindern. Durch die Angabe der erlaubten Ursprünge für eine Anwendung in Logto kann der Dienst sicherstellen, dass nur autorisierte Domains Anfragen an den Dienst stellen können. :::note -Die Liste der erlaubten Ursprünge sollte den Ursprung enthalten, unter dem die Anwendung bereitgestellt wird. Dies stellt sicher, dass Anfragen von der Anwendung erlaubt sind, während Anfragen von nicht autorisierten Ursprüngen blockiert werden. +Die Liste der erlaubten Ursprünge sollte den Ursprung enthalten, von dem aus die Anwendung bereitgestellt wird. Dies stellt sicher, dass Anfragen von der Anwendung erlaubt sind, während Anfragen von unbefugten Ursprüngen blockiert werden. ::: -### OpenID Provider-Konfigurationsendpunkt \{#openid-provider-configuration-endpoint} +### OpenID Provider Konfigurationsendpunkt \{#openid-provider-configuration-endpoint} Der Endpunkt für [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). ### Autorisierungsendpunkt \{#authorization-endpoint} -_Autorisierungsendpunkt_ ist ein OIDC-Begriff und ein erforderlicher Endpunkt, der verwendet wird, um den Authentifizierungsprozess für einen Benutzer zu starten. Wenn ein Benutzer versucht, auf eine geschützte Ressource oder Anwendung zuzugreifen, die bei der Logto-Plattform registriert ist, wird er zum _Autorisierungsendpunkt_ weitergeleitet, um seine Identität zu authentifizieren und die Autorisierung für den Zugriff auf die angeforderte Ressource zu erhalten. +_Autorisierungsendpunkt_ ist ein OIDC-Begriff und ein erforderlicher Endpunkt, der verwendet wird, um den Authentifizierungsprozess für einen Benutzer zu initiieren. Wenn ein Benutzer versucht, auf eine geschützte Ressource oder Anwendung zuzugreifen, die bei der Logto-Plattform registriert ist, wird er zum _Autorisierungsendpunkt_ weitergeleitet, um seine Identität zu authentifizieren und die Berechtigung zu erhalten, auf die angeforderte Ressource zuzugreifen. -Weitere Informationen findest du beim [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint). +Du kannst den [Autorisierungsendpunkt](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) für weitere Informationen überprüfen. ### Token-Endpunkt \{#token-endpoint} -_Token-Endpunkt_ ist ein OIDC-Begriff. Es handelt sich um einen Web-API-Endpunkt, der von einem OIDC-Client verwendet wird, um ein Zugangstoken, ein ID-Token oder ein Auffrischungstoken von einem OIDC-Provider zu erhalten. +_Token-Endpunkt_ ist ein OIDC-Begriff, es ist ein Web-API-Endpunkt, der von einem OIDC-Client verwendet wird, um ein Zugangstoken, ein ID-Token oder ein Auffrischungstoken von einem OIDC-Anbieter zu erhalten. -Wenn ein OIDC-Client ein Zugangstoken oder ID-Token benötigt, sendet er eine Anfrage an den Token-Endpunkt mit einer Autorisierungsgewährung, die typischerweise ein Autorisierungscode oder ein Auffrischungstoken ist. Der Token-Endpunkt validiert dann die Autorisierungsgewährung und stellt dem Client ein Zugangstoken oder ID-Token aus, wenn die Gewährung gültig ist. +Wenn ein OIDC-Client ein Zugangstoken oder ID-Token erhalten muss, sendet er eine Anfrage an den Token-Endpunkt mit einem Autorisierungs-Grant, der typischerweise ein Autorisierungscode oder ein Auffrischungstoken ist. Der Token-Endpunkt validiert dann den Autorisierungs-Grant und stellt dem Client ein Zugangstoken oder ID-Token aus, wenn der Grant gültig ist. -Weitere Informationen findest du beim [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint). +Du kannst den [Token-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) für weitere Informationen überprüfen. ### Userinfo-Endpunkt \{#userinfo-endpoint} -Der OpenID Connect [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). +Der OpenID Connect [UserInfo-Endpunkt](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). ### Immer Auffrischungstoken ausstellen \{#always-issue-refresh-token} -_Verfügbarkeit: Traditionelle Web, SPA_ +_Verfügbarkeit: Traditionelles Web, SPA_ -Wenn aktiviert, stellt Logto immer Auffrischungstokens aus, unabhängig davon, ob `prompt=consent` in der Authentifizierungsanfrage vorhanden ist oder `offline_access` in den Berechtigungen enthalten ist. +Wenn aktiviert, wird Logto immer Auffrischungstokens ausstellen, unabhängig davon, ob `prompt=consent` in der Authentifizierungsanfrage präsentiert wird oder `offline_access` in den Berechtigungen enthalten ist. -Diese Praxis wird jedoch nicht empfohlen, es sei denn, sie ist notwendig (in der Regel nützlich für einige OAuth-Integrationen von Drittanbietern, die ein Auffrischungstoken erfordern), da sie nicht mit OpenID Connect kompatibel ist und potenziell Probleme verursachen kann. +Diese Praxis wird jedoch nicht empfohlen, es sei denn, sie ist notwendig (normalerweise ist sie nützlich für einige Drittanbieter-OAuth-Integrationen, die ein Auffrischungstoken erfordern), da sie nicht mit OpenID Connect kompatibel ist und potenziell Probleme verursachen kann. ### Auffrischungstoken rotieren \{#rotate-refresh-token} _Standard: `true`_ -Wenn aktiviert, stellt Logto ein neues Auffrischungstoken für Token-Anfragen unter den folgenden Bedingungen aus: +Wenn aktiviert, wird Logto ein neues Auffrischungstoken für Token-Anfragen unter den folgenden Bedingungen ausstellen: -- Wenn das Auffrischungstoken rotiert wurde (seine TTL durch die Ausgabe eines neuen Tokens verlängert wurde) für ein Jahr; **ODER** -- Wenn das Auffrischungstoken kurz vor dem Ablauf steht (>=70% seiner ursprünglichen Lebensdauer (TTL) vergangen); **ODER** -- Wenn der Client ein öffentlicher Client ist, z. B. Native Anwendung oder Single Page Application (SPA). +- Wenn das Auffrischungstoken rotiert wurde (seine TTL durch die Ausstellung eines neuen verlängert wurde) für ein Jahr; **ODER** +- Wenn das Auffrischungstoken nahe an seiner Ablaufzeit ist (>=70% seiner ursprünglichen Time to Live (TTL) vergangen); **ODER** +- Wenn der Client ein öffentlicher Client ist, z.B. Native Anwendung oder Single Page Application (SPA). :::note -Für öffentliche Clients wird bei aktivierter Funktion immer ein neues Auffrischungstoken ausgestellt, wenn der Client ein neues Zugangstoken mit dem Auffrischungstoken anfordert. -Obwohl du die Funktion für diese öffentlichen Clients deaktivieren kannst, wird dringend empfohlen, sie aus Sicherheitsgründen aktiviert zu lassen. +Für öffentliche Clients, wenn diese Funktion aktiviert ist, wird immer ein neues Auffrischungstoken ausgestellt, wenn der Client ein neues Zugangstoken mit dem Auffrischungstoken austauscht. +Obwohl du die Funktion für diese öffentlichen Clients immer noch deaktivieren kannst, wird dringend empfohlen, sie aus Sicherheitsgründen aktiviert zu lassen. ::: - Auffrischungstoken-Rotation verstehen + Verständnis der Auffrischungstoken-Rotation -### Auffrischungstoken Lebensdauer (TTL) in Tagen \{#refresh-token-time-to-live-ttl-in-days} +### Auffrischungstoken Time-to-Live (TTL) in Tagen \{#refresh-token-time-to-live-ttl-in-days} _Verfügbarkeit: Nicht SPA; Standard: 14 Tage_ Die Dauer, für die ein Auffrischungstoken verwendet werden kann, um neue Zugangstokens anzufordern, bevor es abläuft und ungültig wird. Token-Anfragen verlängern die TTL des Auffrischungstokens auf diesen Wert. -In der Regel wird ein niedrigerer Wert bevorzugt. +Typischerweise wird ein niedrigerer Wert bevorzugt. -Hinweis: Die Verlängerung der TTL ist in SPA (Single Page App) aus Sicherheitsgründen nicht verfügbar. Das bedeutet, dass Logto die TTL nicht durch Token-Anfragen verlängert. Um die Benutzererfahrung zu verbessern, kannst du die Funktion "Auffrischungstoken rotieren" aktivieren, sodass Logto bei Bedarf ein neues Auffrischungstoken ausstellt. +Hinweis: Die TTL-Auffrischung ist in SPA (Single Page App) aus Sicherheitsgründen nicht verfügbar. Das bedeutet, dass Logto die TTL nicht durch Token-Anfragen verlängert. Um die Benutzererfahrung zu verbessern, kannst du die Funktion "Auffrischungstoken rotieren" aktivieren, sodass Logto bei Bedarf ein neues Auffrischungstoken ausstellt. :::caution Auffrischungstoken und Sitzungsbindung -Wenn ein Auffrischungstoken **ohne** die Berechtigung `offline_access` in der Autorisierungsanfrage ausgestellt wird, wird es an die Benutzersitzung gebunden. Die Sitzung hat eine feste TTL von **14 Tagen**. Nach Ablauf der Sitzung wird das Auffrischungstoken unabhängig von seiner eigenen TTL-Einstellung ungültig. +Wenn ein Auffrischungstoken **ohne** den `offline_access`-Scope in der Autorisierungsanfrage ausgestellt wird, wird es an die Benutzersitzung gebunden. Die Sitzung hat eine feste TTL von **14 Tagen**. Nach Ablauf der Sitzung wird das Auffrischungstoken unabhängig von seiner eigenen TTL-Einstellung ungültig. -Um sicherzustellen, dass die Auffrischungstoken-TTL-Einstellung vollständig wirksam ist, stelle sicher, dass du die Berechtigung `offline_access` in deiner Autorisierungsanfrage einschließt. +Um sicherzustellen, dass die Auffrischungstoken-TTL-Einstellung vollständig wirksam wird, stelle sicher, dass du den `offline_access`-Scope in deiner Autorisierungsanfrage einschließt. ::: ### Backchannel-Logout-URI \{#backchannel-logout-uri} -Der OpenID Connect Backchannel-Logout-Endpunkt. Siehe [Föderiertes Abmelden: Back-Channel-Logout](#) für weitere Informationen. +Der OpenID Connect Backchannel-Logout-Endpunkt. Siehe [Federated sign-out: Back-channel logout](#) für weitere Informationen. + +### Maximal erlaubte Grants (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` ist ein optionales App-Level-Feld unter `customClientMetadata`, das die maximale Anzahl gleichzeitiger aktiver Grants pro Benutzer für die aktuelle App steuert. + +- **Standard**: `undefined` (kein Limit) +- **Wenn konfiguriert**: Bei jeder erfolgreichen Autorisierung überprüft Logto die Gesamtzahl der aktiven Grants für den Benutzer in der aktuellen App (über Browser und Geräte hinweg). Wenn das Limit überschritten wird, widerruft Logto die ältesten Grants. + +Diese Einstellung ist nützlich, wenn du die gleichzeitigen authentifizierten Geräte pro App begrenzen möchtest. + +:::note + +Dieses Feld wird nicht unterstützt für: + +- Maschine-zu-Maschine-Apps +- Geschützte Apps +- SAML-Apps + +::: ### Benutzerdefinierte Daten \{#custom-data} -Zusätzliche benutzerdefinierte Anwendungsinformationen, die nicht in den vordefinierten Anwendungseigenschaften aufgeführt sind. Benutzer können eigene benutzerdefinierte Datenfelder entsprechend ihren spezifischen Anforderungen definieren, z. B. geschäftsspezifische Einstellungen und Konfigurationen. +Zusätzliche benutzerdefinierte Anwendungsinformationen, die nicht in den vordefinierten Anwendungseigenschaften aufgeführt sind. Benutzer können ihre eigenen benutzerdefinierten Datenfelder entsprechend ihren spezifischen Bedürfnissen definieren, wie z.B. geschäftsspezifische Einstellungen und Konfigurationen. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..5eb55f26d97 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,168 @@ +# Sitzungen + +Sitzungen in Logto definieren, wie der Authentifizierungsstatus über Apps, Browser und Geräte erstellt, geteilt, aktualisiert und widerrufen wird. + +In der Praxis erleben Benutzer den Zustand "angemeldet" als einen Zustand, aber der Systemzustand ist in mehrere Schichten aufgeteilt. Das Verständnis dieser Schichten ist der Schlüssel zur Gestaltung eines vorhersehbaren SSO, zur Token-Erneuerung und zum Abmeldeverhalten. + +## Sitzungsmodell in Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto-Domain"] + S["Anmeldesitzung"] + G1["Gewährung (App A)"] + G2["Gewährung (App B)"] + end + + subgraph AppA ["App-Domain A"] + A["Lokale Sitzung / Tokens"] + end + + subgraph AppB ["App-Domain B"] + B["Lokale Sitzung / Tokens"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto-Anmeldesitzung**: Zentralisierter Anmeldestatus, der als Logto-Domain-Cookies gespeichert wird. Dies steuert die Verfügbarkeit von SSO im aktuellen Browserkontext. +- **Gewährung**: App-spezifischer Autorisierungsstatus für `Benutzer + Client-App`. Gewährungen sind die Brücke zwischen zentralisierter Anmeldung und App-Token-Ausgabe. +- **App-lokale Sitzung / Tokens**: Lokaler Authentifizierungsstatus in jeder App (ID / Zugangstoken / Auffrischungstoken, App-Sitzungscookie usw.). + +## Kernkonzepte \{#core-concepts} + +### Was ist eine Logto-Sitzung? \{#what-is-a-logto-session} + +Eine Logto-Sitzung ist der zentralisierte Authentifizierungsstatus, der nach erfolgreicher Anmeldung erstellt wird. Wenn sie noch gültig ist, kann Logto Benutzer für andere Apps im selben Mandanten stillschweigend authentifizieren. Wenn sie nicht existiert, müssen sich Benutzer erneut anmelden. + +### Was sind Gewährungen? \{#what-are-grants} + +Eine Gewährung ist ein App-Ebene-Autorisierungsstatus, der an einen bestimmten Benutzer und eine Client-App gebunden ist. + +- Eine Logto-Sitzung kann Gewährungen für mehrere Apps haben. +- Tokens für eine App werden unter der Gewährung dieser App ausgegeben. +- Der Widerruf einer Gewährung beeinflusst die Fähigkeit dieser App, weiterhin tokenbasierten Zugriff zu haben. + +### Wie sich Sitzung, Gewährungen und App-Auth-Status zueinander verhalten \{#how-session-grants-and-app-auth-state-relate} + +- **Sitzung** beantwortet: "Kann dieser Browser gerade SSO mit Logto durchführen?" +- **Gewährung** beantwortet: "Ist dieser Benutzer für diese Client-App autorisiert?" +- **App-lokale Sitzung** beantwortet: "Behandelt diese App den Benutzer derzeit als angemeldet?" + +## Anmeldung und Sitzungserstellung \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as Client-Anwendung + end + + box Logto + participant OIDC as OIDC-Anbieter + participant SignIn as Anmeldeseite + end + + User ->> Client: Anwendung aufrufen + Client ->> OIDC: Autorisierungsanfrage + OIDC -->> OIDC: Bestehende Logto-Sitzung prüfen + OIDC ->> SignIn: Anmeldung bei Bedarf auffordern + SignIn ->> OIDC: Benutzer authentifiziert sich + OIDC -->> OIDC: Sitzung und App-Gewährung erstellen + OIDC ->> Client: Autorisierungscode zurückgeben + Client ->> OIDC: Code gegen Tokens austauschen + OIDC -->> Client: Tokens zurückgeben +``` + +## Sitzungstopologie über Apps und Geräte \{#session-topology-across-apps-and-devices} + +### Gleicher Browser: geteilte Logto-Sitzung \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[Benutzer] + A["Client-App A"] + B["Client-App B"] + C{"Logto-Sitzung vorhanden?"} + D["Logto-Anmeldeseite"] + + U --> A + A --> C + U --> B + B --> C + C -->|Nein| D +``` + +Apps im gleichen Browser können den zentralisierten Logto-Sitzungsstatus teilen, sodass SSO ohne wiederholte Eingabe von Anmeldeinformationen erfolgen kann. + +### Verschiedene Browser oder Geräte: isolierte Logto-Sitzungen \{#different-browsers-or-devices-isolated-logto-sessions} + +Jeder Browser / jedes Gerät hat einen separaten Cookie-Speicher. Eine gültige Sitzung auf Gerät A impliziert keine gültige Sitzung auf Gerät B. + +## Sitzungslebenszyklus \{#session-lifecycle} + +### 1. Erstellen \{#1-create} + +Nach der Benutzer-Authentifizierung erstellt Logto eine zentralisierte Sitzung und eine app-spezifische Gewährung. + +### 2. Wiederverwenden (SSO) \{#2-reuse-sso} + +Solange Sitzungscookies im gleichen Browser gültig sind, können neue Autorisierungsanfragen oft stillschweigend abgeschlossen werden. + +### 3. Tokens erneuern \{#3-renew-tokens} + +Der App-Zugriff wird normalerweise durch Token-Auffrischungsflüsse fortgesetzt (wenn aktiviert). Dies ist eine App-Ebene-Kontinuität, unabhängig davon, ob die zentralisierte Logto-Sitzung noch existiert. + +### 4. Widerrufen / ablaufen \{#4-revokeexpire} + +Der Widerruf kann auf verschiedenen Ebenen erfolgen: + +- Lokale App-Abmeldung entfernt App-lokale Tokens / Sitzung. +- End-Sitzung entfernt zentralisierte Logto-Sitzung. +- Gewährungswiderruf entfernt App-Ebene-Autorisierungskontinuität. + +## Designempfehlungen \{#design-recommendations} + +- Halte die App-lokale Sitzungsverwaltung in deinem App-Code explizit. +- Behandle Logto-Sitzung, Gewährungen und App-lokale Sitzung als separate Schichten. +- Entscheide, ob die Abmeldung nur App-lokal oder global sein soll. +- Verwende [Back-Channel-Abmeldung](/end-user-flows/sign-out#federated-sign-out-back-channel-logout), wenn Konsistenz über mehrere Apps erforderlich ist. +- Für Abmeldeverhalten und Implementierungsdetails siehe [Abmelden](/end-user-flows/sign-out). + +## Best Practices zum Widerrufen des Zugriffs \{#best-practices-for-revoking-access} + +Verwende unterschiedliche Widerrufsstrategien basierend auf deinem Ziel: + +- **Zugriff von deinen First-Party-Apps widerrufen**: + Widerrufe die Ziel-Sitzung mit `revokeGrantsTarget=firstParty`. + Dies meldet den Benutzer über First-Party-Apps ab, die mit dieser Sitzung verbunden sind, was ein konsistentes Abmeldeerlebnis schafft. + Gleichzeitig können Gewährungen für Drittanbieter-Apps, die `offline_access` gewährt haben, für laufende Integrationen verfügbar bleiben. + Siehe [Benutzersitzungen verwalten](/sessions/manage-user-sessions) für Details zum Sitzungswiderruf. + +- **Zugriff auf Drittanbieter-Apps widerrufen**: + Wähle eine der folgenden Optionen: + + - Widerrufe die Sitzung mit `revokeGrantsTarget=all`, um alle mit dieser Sitzung verbundenen Gewährungen zu widerrufen. + - Widerrufe spezifische Gewährungen direkt über Gewährungsverwaltungs-APIs, um Drittanbieter-App-Autorisierungen zu entfernen, ohne eine vollständige Sitzungsabmeldung zu erzwingen. + Siehe [Benutzerautorisierte Apps (Gewährungen) verwalten](/sessions/grants-management) für gewährungsspezifische Widerrufsstrategien. + +- **Bei Verwendung der Logto-Konsole**: + Auf der Benutzerdetailseite bietet Logto sowohl Sitzungsverwaltung als auch Verwaltung autorisierter Drittanbieter-Apps von Haus aus. + - Der Widerruf einer Sitzung widerruft auch First-Party-App-Gewährungen, um das First-Party-Abmeldeverhalten konsistent zu halten. + - Der Widerruf einer Drittanbieter-App-Autorisierung widerruft Gewährungen für diese Drittanbieter-App, während der ursprüngliche Sitzungsstatus unverändert bleibt. + +## Verwandte Ressourcen \{#related-resources} + +Benutzersitzungen verwalten +Benutzerautorisierte Apps (Gewährungen) verwalten +Sitzungskonfiguration +Abmelden +Registrieren und Anmelden + + Authentifizierungsfluss verstehen + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/de/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..fac237529e8 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# Verwaltung von autorisierten Benutzer-Apps (Grants) + +App-Grants repräsentieren den Autorisierungsstatus eines Benutzers für spezifische Client-Anwendungen. + +Verwende das Grants-Management, wenn Benutzer oder Administratoren autorisierte Apps überprüfen und den App-Zugriff widerrufen müssen, ohne die gesamte Logto-Sitzung zu widerrufen. + +Wenn Grants widerrufen werden, werden zuvor ausgestellte opake Zugangstokens und Auffrischungstokens für diese Grants ungültig. + +## Wähle den richtigen Weg \{#choose-the-right-path} + +| Szenario | Empfohlener Weg | +| --------------------------------------------------------------------------------------------- | --------------- | +| Angemeldeten Benutzern erlauben, ihre eigenen App-Autorisierungen zu verwalten | Account API | +| Administratoren oder Support-Teams erlauben, Grants für einen Zielbenutzer zu verwalten | Management API | +| Operatoren erlauben, Drittanbieter-App-Autorisierungen in der Benutzeroberfläche zu verwalten | Admin Console | + +## Direkte Grant-Management-APIs \{#direct-grant-management-apis} + +### Account API (Selbstbedienung) \{#account-api-self-service} + +Verwende die Account API auf den Einstellungsseiten des Endbenutzerkontos: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- Referenz: [Verwaltung von autorisierten Benutzer-Apps (Grants)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (Admin-Tools) \{#management-api-admin-tools} + +Verwende die Management API in Admin-Tools und Support-Workflows: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- Referenz: [Verwaltung von autorisierten Benutzer-Apps (Grants)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### Grant-Liste nach App-Typ filtern \{#filter-grant-list-by-app-type} + +Die Endpunkte zur Grant-Auflistung unterstützen den optionalen Abfrageparameter `appType`: + +- `appType=firstParty`: Nur Grants für First-Party-Apps auflisten. +- `appType=thirdParty`: Nur Grants für Drittanbieter-Apps auflisten. +- `appType` weglassen: Alle aktiven Grants zurückgeben. + +## Verwaltung von Drittanbieter-App-Autorisierungen in der Konsole \{#manage-third-party-app-authorizations-in-console} + +In der Logto-Konsole kannst du auf der Benutzerdetailseite autorisierte Drittanbieter-Apps anzeigen und widerrufen. + +- Referenz: [Verwaltung von autorisierten Drittanbieter-Apps für Benutzer](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## Grants widerrufen, wenn eine Sitzung widerrufen wird \{#revoke-grants-when-revoking-a-session} + +Beim Widerrufen einer Sitzung über `DELETE /api/my-account/sessions/{sessionId}` verwende den optionalen Abfrageparameter `revokeGrantsTarget`, um den Umfang des Grant-Widerrufs zu steuern: + +- `all`: Grants für alle mit der Sitzung verbundenen Apps widerrufen. +- `firstParty`: Nur Grants für First-Party-Apps widerrufen. + +Für das Verhalten auf Sitzungsebene und den Endpunktkontext siehe [Verwaltung von Benutzersitzungen](/sessions/manage-user-sessions) und [Abmelden](/end-user-flows/sign-out). + +## Verwandte Ressourcen \{#related-resources} + +Sitzungen +Verwaltung von Benutzersitzungen + + Kontoeinstellungen über Account API: Verwaltung von autorisierten Benutzer-Apps (Grants) + + + Kontoeinstellungen über Management API: Verwaltung von autorisierten Benutzer-Apps (Grants) + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/de/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..2f34738d1d3 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# Benutzersitzungen verwalten + +Das Management von Benutzersitzungen hilft Benutzern und Administratoren, aktive Anmeldestände zu überprüfen und Sitzungen bei Bedarf zu widerrufen. + +In Logto kannst du Sitzungen über drei gängige Wege verwalten: + +- **Account API**: Für die Selbstbedienung der Endbenutzer auf der Kontoeinstellungsseite deines Produkts. +- **Management API**: Für Admin- oder Support-Tools, um Sitzungen für jeden Benutzer zu verwalten. +- **Admin Console**: Für Betreiber-Workflows in der Logto Console, ohne benutzerdefinierte Tools zu erstellen. + +## Wähle die richtige API \{#choose-the-right-api} + +| Szenario | Empfohlene API | +| -------------------------------------------------------------------------------------- | -------------- | +| Angemeldeten Benutzern erlauben, ihre eigenen aktiven Sitzungen zu verwalten | Account API | +| Administratoren oder Support-Teams erlauben, Sitzungen für einen Benutzer zu verwalten | Management API | +| Betreibern erlauben, Sitzungen direkt in der Logto Console zu verwalten | Admin Console | + +## Aktive Sitzungen anzeigen \{#view-active-sessions} + +### Account API (Selbstbedienung) \{#account-api-self-service} + +Verwende den Account API-Sitzungsendpunkt, um die aktiven Sitzungen des aktuellen Benutzers aufzulisten. + +- Referenzabschnitt: [Benutzersitzungen verwalten](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpunkt: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +Bevor du diese Funktionalität Endbenutzern zur Verfügung stellst, stelle sicher, dass das Sitzungsmanagement in den Einstellungen des Account Centers aktiviert ist und deine App den erforderlichen Account API-Bereich anfordert. + +### Management API (Admin-Tools) \{#management-api-admin-tools} + +Verwende die Management API, wenn dein Admin-System Sitzungen für einen Zielbenutzer auflisten muss. + +- Referenzabschnitt: [Benutzersitzungsmanagement](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpunkt: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Optionaler Detailendpunkt: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## Sitzungen widerrufen \{#revoke-sessions} + +### Account API (Endbenutzer widerruft eigene Sitzungen) \{#account-api-end-user-revokes-own-sessions} + +Endbenutzer können eine bestimmte Sitzung aus ihrer eigenen Sitzungsübersicht widerrufen. + +- Referenzabschnitt: [Benutzersitzungen verwalten](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpunkt: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +Für sensible Operationen erfordert das Sitzungsmanagement der Account API eine Benutzerverifizierung vor dem Zugriff. Siehe [Eine Verifizierungsdatensatz-ID erhalten](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id). + +### Management API (Admin widerruft Benutzersitzungen) \{#management-api-admin-revokes-user-sessions} + +Administratoren können die Sitzung eines Zielbenutzers anhand der Benutzer-ID und der Sitzungs-ID widerrufen. + +- Referenzabschnitt: [Benutzersitzungsmanagement](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpunkt: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +Wenn dein Team Benutzer direkt in der Logto Console verwaltet, kannst du aktive Sitzungen überprüfen und spezifische Sitzungen von der Benutzerdetailseite aus widerrufen. + +- Referenzabschnitt: [Aktive Benutzersitzungen verwalten](/user-management/manage-users#manage-user-active-sessions) + +## Verwandte Ressourcen \{#related-resources} + +Sitzungen +Benutzerautorisierte Apps verwalten (Grants) + + Kontoeinstellungen durch Account API: Benutzersitzungen verwalten + + + Kontoeinstellungen durch Management API: Benutzersitzungsmanagement + + + Benutzermanagement: Aktive Benutzersitzungen verwalten + diff --git a/i18n/de/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/de/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..c013fac632f --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# Sitzungs-Konfiguration + +Die Sitzungs-Konfiguration definiert die mandantenweiten Kontrollen dafür, wie lange Logto-Anmeldesitzungen aktiv bleiben und wie sitzungsbezogene Zugriffspolicies durchgesetzt werden. + +Diese Seite behandelt: + +- Sitzungs-TTL-Konfiguration +- Maximale gleichzeitige authentifizierte Geräte pro App + +## Sitzungs-TTL-Konfiguration \{#session-ttl-configuration} + +Die Sitzungs-TTL bestimmt die maximale Lebensdauer der Logto OIDC-Anmeldesitzung. +Es ist eine **mandantenweite Einstellung**: Sobald sie konfiguriert ist, gilt sie für alle Apps und Authentifizierungsabläufe in diesem Mandanten. + +### Standardverhalten \{#default-behavior} + +- Standardmäßig beträgt die Sitzungs-TTL **14 Tage**. +- Wenn keine benutzerdefinierte TTL konfiguriert ist, verwendet Logto weiterhin diesen Standardwert. + +### Konfiguration über Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +Du kannst die Sitzungs-TTL in der Console unter konfigurieren: + +Console > Tenant > Settings > OIDC settings + +Verwende **Session maximum time to live**, um den Wert zu aktualisieren. + +:::note + +Die Console verwendet **Tage** für Eingabe und Anzeige, während die zugrunde liegende OIDC-Sitzungskonfiguration / API **Sekunden** verwendet. + +::: + +### Konfiguration über Management API \{#configure-via-management-api} + +Verwende diese Endpunkte, um die OIDC-Sitzungskonfiguration zu lesen und zu aktualisieren: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +Beispiel (`ttl` in Sekunden): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` Sekunden = 14 Tage. + +:::note + +Für OSS-Bereitstellungen starte die Dienstinstanz nach dem Ändern von `logto-config` neu, damit der Server die neuesten OIDC-Einstellungen übernehmen kann. + +Um OIDC-Konfigurationsupdates automatisch anzuwenden, ohne den Dienst neu zu starten, [aktiviere den zentralen Redis-Cache](/logto-oss/central-cache). + +::: + +## Maximale gleichzeitige authentifizierte Geräte pro App \{#max-concurrent-authenticated-devices-per-app} + +Die maximale Anzahl gleichzeitiger authentifizierter Geräte pro App ist eine App-spezifische Kontrolle, die begrenzt, wie viele aktive Berechtigungen jeder Benutzer für eine bestimmte App behalten kann. + +Dies wird über das Feld `maxAllowedGrants` in der `customClientMetadata` der Anwendung konfiguriert. +Erfahre mehr in [Anwendungsdatenstruktur](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants). + +### Verhalten \{#behavior} + +Wenn `maxAllowedGrants` gesetzt ist, bewertet Logto die aktiven Berechtigungen des Benutzers für die aktuelle App bei jeder erfolgreichen Autorisierung. +Wenn die Anzahl der aktiven Berechtigungen das Limit überschreitet, widerruft Logto zuerst die ältesten Berechtigungen. + +Wenn `maxAllowedGrants` nicht gesetzt ist, gibt es kein Gleichzeitigkeit-Limit. + +### Konfiguration über Logto Console \{#configure-via-logto-console} + +Du kannst dies auf der Detailseite jeder App unter konfigurieren: + + + Console > Applications > Application details > Concurrent device limit + + +Setze die maximale Anzahl gleichzeitiger aktiver Berechtigungen (Geräte) pro Benutzer für die aktuelle App. + +:::note + +Diese Einstellung wird nicht für Maschine-zu-Maschine-Apps, geschützte Apps und SAML-Apps unterstützt. + +::: + +## Verwandte Ressourcen \{#related-resources} + +Sitzungen +Benutzersitzungen verwalten +Benutzerautorisierte Apps (Berechtigungen) verwalten + + Anwendungsdatenstruktur: maxAllowedGrants + +Mit Management API interagieren diff --git a/i18n/de/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/de/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index e61a0716bb0..f2b219af38b 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -4,33 +4,33 @@ sidebar_position: 2 # Benutzer verwalten -## Verwaltung über die Logto Console \{#manage-via-logto-console} +## Verwaltung über die Logto-Konsole \{#manage-via-logto-console} ### Benutzer durchsuchen und suchen \{#browse-and-search-users} -Um auf die Benutzerverwaltungsfunktion in der Logto Console zuzugreifen, navigiere zu Konsole > Benutzerverwaltung. Dort siehst du eine Tabellenansicht aller Benutzer. +Um auf die Benutzerverwaltungsfunktionalität in der Logto-Konsole zuzugreifen, navigiere zu Konsole > Benutzerverwaltung. Dort siehst du eine Tabellenansicht aller Benutzer. Die Tabelle besteht aus drei Spalten: -- **Benutzer**: Zeigt Informationen über den Benutzer an, wie z. B. Avatar, vollständiger Name, Benutzername, Telefonnummer und E-Mail-Adresse. -- **Von Anwendung**: Zeigt den Namen der Anwendung an, mit der sich der Benutzer ursprünglich registriert hat. +- **Benutzer**: Zeigt Informationen über den Benutzer an, wie z. B. deren Avatar, vollständigen Namen, Benutzernamen, Telefonnummer und E-Mail +- **Von Anwendung**: Zeigt den Namen der Anwendung an, mit der sich der Benutzer ursprünglich registriert hat - **Letzte Anmeldung**: Zeigt den Zeitstempel der letzten Anmeldung des Benutzers an. -Es wird die Schlüsselwortsuche für [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email) unterstützt. +Es unterstützt die Schlüsselwortzuordnung für [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email). ### Benutzer hinzufügen \{#add-users} -Mit der Console können Entwickler neue Konten für Endbenutzer erstellen. Klicke dazu auf die Schaltfläche „Benutzer hinzufügen“ in der oberen rechten Ecke des Bildschirms. +Über die Konsole können Entwickler neue Konten für Endbenutzer erstellen. Klicke dazu auf die Schaltfläche "Benutzer hinzufügen" in der oberen rechten Ecke des Bildschirms. -Beim Erstellen eines Benutzers in der Logto Console oder über die Management API (nicht vom Endbenutzer selbst über die UI registriert), musst du mindestens einen Identifikator angeben: `primary email`, `primary phone` oder `username`. Das Feld `name` ist optional. +Beim Erstellen eines Benutzers in der Logto-Konsole oder über die Management API (nicht vom Endbenutzer selbst über die Benutzeroberfläche registriert) musst du mindestens einen Identifikator angeben: `primäre E-Mail`, `primäre Telefonnummer` oder `Benutzername`. Das `Name`-Feld ist optional. -Nachdem der Benutzer erstellt wurde, generiert Logto automatisch ein zufälliges Passwort. Das Anfangspasswort wird nur einmal angezeigt, aber du kannst das [Passwort zurücksetzen](./manage-users#reset-user-password) später. Wenn du ein bestimmtes Passwort festlegen möchtest, verwende die Management API `patch /api/users/{userId}/password`, um es nach der Erstellung des Benutzers zu aktualisieren. +Nachdem der Benutzer erstellt wurde, generiert Logto automatisch ein zufälliges Passwort. Das anfängliche Passwort wird nur einmal angezeigt, aber du kannst das Passwort später [zurücksetzen](./manage-users#reset-user-password). Wenn du ein bestimmtes Passwort festlegen möchtest, verwende die Management API `patch /api/users/{userId}/password`, um es nach der Erstellung des Benutzers zu aktualisieren. -Du kannst die **eingegebenen Identifikatoren (E-Mail-Adresse / Telefonnummer / Benutzername)** und das **Anfangspasswort** mit einem Klick kopieren, was es einfach macht, diese Zugangsdaten mit dem neuen Benutzer zu teilen, damit er sich anmelden und loslegen kann. +Du kannst die **eingegebenen Identifikatoren (E-Mail-Adresse / Telefonnummer / Benutzername)** und das **anfängliche Passwort** mit einem Klick kopieren, was es einfach macht, diese Anmeldedaten mit dem neuen Benutzer zu teilen, damit er sich anmelden und loslegen kann. :::tip -Wenn du eine Registrierung nur auf Einladung implementieren möchtest, empfehlen wir, [Benutzer mit einem Magic Link einzuladen](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Dadurch können sich nur auf der Whitelist stehende Benutzer selbst registrieren und ihr eigenes Passwort festlegen. +Wenn du eine Registrierung nur auf Einladung implementieren möchtest, empfehlen wir, [Benutzer mit einem magischen Link einzuladen](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Dadurch können sich nur auf der Whitelist stehende Benutzer selbst registrieren und ihr eigenes Passwort festlegen. ::: @@ -42,82 +42,97 @@ Um die Details eines Benutzers anzuzeigen, klicke einfach auf die entsprechende - **E-Mail-Adresse** ([primary_email](/user-management/user-data#primary_email)): Bearbeitbar - **Telefonnummer** ([primary_phone](/user-management/user-data#primary_phone)): Bearbeitbar - **Benutzername** ([username](/user-management/user-data#username)): Bearbeitbar - - **Passwort** ([has_password](/user-management/user-data#has_password)): Du kannst ein zufälliges Passwort neu generieren. Mehr dazu unter "[Benutzerpasswort zurücksetzen](#reset-user-password)". - - **Multi-Faktor-Authentifizierung (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Zeige alle Authentifizierungsfaktoren an (z. B. Passkeys, Authenticator-Apps, Backup-Codes), die dieser Benutzer eingerichtet hat. Faktoren können in der Console entfernt werden. - - **Passkeys**: Wenn [Passkey-Anmeldung](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) im Mandanten aktiviert ist, kannst du auf der Seite mit den Benutzerdetails auch die Anmelde-Passkeys des Benutzers anzeigen und bei Bedarf entfernen. Diese Passkeys basieren auf demselben WebAuthn-Credential-Modell wie MFA. - - **Personal Access Token**: Erstellen, anzeigen, umbenennen und löschen von [Personal Access Tokens](/user-management/personal-access-token). + - **Passwort** ([has_password](/user-management/user-data#has_password)): Du kannst ein zufälliges Passwort neu generieren. Erfahre mehr über "[Benutzerpasswort zurücksetzen](#reset-user-password)". + - **Multi-Faktor-Authentifizierung (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Zeige alle Authentifizierungsfaktoren an (z. B. Passkeys, Authenticator-Apps, Backup-Codes), die dieser Benutzer eingerichtet hat. Faktoren können in der Konsole entfernt werden. + - **Passkeys**: Wenn [Passkey-Anmeldung](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) im Mandanten aktiviert ist, kannst du auch die Anmelde-Passkeys des Benutzers auf der Seite mit den Benutzerdetails anzeigen und bei Bedarf entfernen. Diese Passkeys werden durch dasselbe WebAuthn-Credential-Modell unterstützt, das von MFA verwendet wird. + - **Persönlicher Zugangstoken**: Erstellen, anzeigen, umbenennen und löschen von [persönlichen Zugangstokens](/user-management/personal-access-token). - **Verbindung**: - **Soziale Verbindungen** ([identities](/user-management/user-data#social-identities)): - - Zeige die verknüpften sozialen Konten des Benutzers an, einschließlich Social-IDs und Profildetails, die von den sozialen Anbietern synchronisiert wurden (z. B. erscheint ein "Facebook"-Eintrag, wenn sich der Benutzer über Facebook angemeldet hat). + - Zeige die verknüpften sozialen Konten des Benutzers an, einschließlich sozialer IDs und Profildetails, die von ihren sozialen Anbietern synchronisiert wurden (z. B. erscheint ein "Facebook"-Eintrag, wenn sich der Benutzer über Facebook angemeldet hat). - Du kannst bestehende soziale Identitäten entfernen, aber keine neuen sozialen Konten im Namen des Benutzers verknüpfen. - - Für Social Connectors mit aktiviertem [Token-Speicher](/secret-vault/federated-token-set) kannst du Zugangstokens und Auffrischungstokens auf der Verbindungsdetailseite anzeigen und verwalten. + - Für soziale Connectors mit aktiviertem [Token-Speicher](/secret-vault/federated-token-set) kannst du Zugangstokens und Auffrischungstokens auf der Verbindungsdetailseite anzeigen und verwalten. - **Enterprise SSO-Verbindungen** ([sso_identities](/user-management/user-data#sso-identities)): - - Zeige die verknüpften Enterprise-Identitäten des Benutzers an, einschließlich Enterprise-IDs und Profildetails, die von den Enterprise-Identitätsanbietern synchronisiert wurden. - - Du kannst Enterprise SSO-Identitäten in der Console nicht hinzufügen oder entfernen. - - Für OIDC-basierte Enterprise Connectors mit aktiviertem [Token-Speicher](/secret-vault/federated-token-set) kannst du Tokens auf der Verbindungsdetailseite anzeigen und löschen. -- **Benutzerprofildaten**: Name, Avatar-URL, benutzerdefinierte Daten und zusätzliche OpenID Connect Standardansprüche, die nicht enthalten sind. Alle diese Profilfelder sind bearbeitbar. + - Zeige die verknüpften Unternehmensidentitäten des Benutzers an, einschließlich Unternehmens-IDs und Profildetails, die von ihren Unternehmensidentitätsanbietern synchronisiert wurden. + - Du kannst keine Enterprise SSO-Identitäten in der Konsole hinzufügen oder entfernen. + - Für OIDC-basierte Enterprise-Connectors mit aktiviertem [Token-Speicher](/secret-vault/federated-token-set) kannst du Tokens auf der Verbindungsdetailseite anzeigen und löschen. +- **Benutzerprofildaten**: Name, Avatar-URL, benutzerdefinierte Daten und zusätzliche OpenID Connect-Standardansprüche, die nicht enthalten sind. Alle diese Profilfelder sind bearbeitbar. - **Sitzungen**: Zeige die Liste der aktiven Benutzersitzungen an, einschließlich Geräteinformationen, sessionId und GEO-Standort, falls zutreffend. Zeige weitere Details einer Sitzung an und widerrufe sie auf der Sitzungsdetailseite. :::warning -Es ist wichtig zu bestätigen, dass der Benutzer eine alternative Anmeldemethode hat, bevor eine soziale Verbindung entfernt wird, z. B. eine andere soziale Verbindung, Telefonnummer, E-Mail oder Benutzername-mit-Passwort. Wenn der Benutzer keine andere Anmeldemethode hat, kann er nach dem Entfernen der sozialen Verbindung nicht mehr auf sein Konto zugreifen. +Es ist wichtig zu bestätigen, dass der Benutzer eine alternative Anmeldemethode hat, bevor eine soziale Verbindung entfernt wird, wie z. B. eine andere soziale Verbindung, Telefonnummer, E-Mail oder Benutzername-mit-Passwort. Wenn der Benutzer keine andere Anmeldemethode hat, kann er nach dem Entfernen der sozialen Verbindung nicht mehr auf sein Konto zugreifen. ::: ### Benutzeraktivitäten anzeigen \{#view-user-activities} -Um die letzten Aktivitäten eines Benutzers anzuzeigen, navigiere zum Untertab „Benutzerprotokolle“ auf der Seite „Benutzerdetails“. Hier findest du eine Tabelle, die die letzten Aktivitäten des Benutzers anzeigt, einschließlich der durchgeführten Aktion, des Ergebnisses der Aktion, der zugehörigen Anwendung und der Zeit, zu der der Benutzer gehandelt hat. +Um die letzten Aktivitäten eines Benutzers anzuzeigen, navigiere zum Untertab "Benutzerprotokolle" auf der Seite "Benutzerdetails". Hier findest du eine Tabelle, die die letzten Aktivitäten des Benutzers anzeigt, einschließlich der durchgeführten Aktion, des Ergebnisses der Aktion, der zugehörigen Anwendung und der Zeit, zu der der Benutzer gehandelt hat. -Klicke auf die Tabellenzeile, um weitere Details im Benutzerprotokoll zu sehen, z. B. IP-Adresse, User Agent, Rohdaten usw. +Klicke auf die Tabellenzeile, um weitere Details im Benutzerprotokoll zu sehen, z. B. IP-Adresse, Benutzeragent, Rohdaten usw. ### Benutzer sperren \{#suspend-user} -Auf der Seite „Benutzerdetails“ klicke auf „Drei Punkte“ -> „Benutzer sperren“-Schaltfläche. +Auf der Seite "Benutzerdetails" klicke auf "Drei Punkte" -> "Benutzer sperren" Schaltfläche. -Sobald ein Benutzer gesperrt ist, kann er sich nicht mehr bei deiner App anmelden und erhält nach Ablauf des aktuellen Zugangstokens kein neues Zugangstoken mehr. Außerdem schlagen alle API-Anfragen dieses Benutzers fehl. +Sobald ein Benutzer gesperrt ist, kann er sich nicht mehr bei deiner App anmelden und kann nach Ablauf des aktuellen Zugangstokens kein neues Zugangstoken mehr erhalten. Darüber hinaus werden alle API-Anfragen, die von diesem Benutzer gestellt werden, fehlschlagen. -Wenn du diesen Benutzer wieder aktivieren möchtest, kannst du dies tun, indem du auf „Drei Punkte“ -> „Benutzer reaktivieren“-Schaltfläche klickst. +Wenn du diesen Benutzer reaktivieren möchtest, kannst du dies tun, indem du auf "Drei Punkte" -> "Benutzer reaktivieren" Schaltfläche klickst. ### Benutzer löschen \{#delete-user} -Auf der Seite „Benutzerdetails“ klicke auf „Drei Punkte“ -> „Löschen“-Schaltfläche. Das Löschen eines Benutzers kann nicht rückgängig gemacht werden. +Auf der Seite "Benutzerdetails" klicke auf "Drei Punkte" -> "Löschen" Schaltfläche. Das Löschen eines Benutzers kann nicht rückgängig gemacht werden. ### Benutzerpasswort zurücksetzen \{#reset-user-password} -Auf der Seite „Benutzerdetails“ klicke auf „Drei Punkte“ -> „Passwort zurücksetzen“-Schaltfläche, und Logto generiert automatisch ein zufälliges Passwort. +Auf der Seite "Benutzerdetails" klicke auf "Drei Punkte" -> "Passwort zurücksetzen" Schaltfläche, und dann wird Logto automatisch ein zufälliges Passwort neu generieren. -Nachdem du das Passwort zurückgesetzt hast, kopiere es und sende es an den Endbenutzer. Sobald das „Passwort zurücksetzen“-Modal geschlossen ist, kannst du das Passwort nicht mehr einsehen. Wenn du es vergessen hast, kannst du es erneut zurücksetzen. +Nachdem du das Passwort zurückgesetzt hast, kopiere es und sende es an den Endbenutzer. Sobald das "Passwort zurücksetzen"-Modal geschlossen ist, kannst du das Passwort nicht mehr anzeigen. Wenn du es vergisst, kannst du es erneut zurücksetzen. -Du kannst in der Logto Console kein bestimmtes Passwort für Benutzer festlegen, aber du kannst die [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` verwenden, um ein Passwort anzugeben. +Du kannst kein spezifisches Passwort für Benutzer in der Logto-Konsole festlegen, aber du kannst die [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` verwenden, um ein Passwort festzulegen. ### Aktive Benutzersitzungen verwalten \{#manage-user-active-sessions} -Auf der Seite „Benutzerdetails“ navigiere zur Seite „Sitzungsdetails“, indem du auf die „Verwalten“-Schaltfläche einer bestimmten Sitzung klickst. Hier kannst du detaillierte Informationen zur Sitzung anzeigen, wie Gerät, Standort und Anmeldezeit. Wenn du den Benutzer aus dieser Sitzung abmelden möchtest, klicke einfach auf die Schaltfläche „Sitzung widerrufen“ in der rechten oberen Ecke, und die Sitzung wird sofort widerrufen. +Auf der Seite "Benutzerdetails" navigiere zur Seite "Sitzungsdetails", indem du auf die Schaltfläche "Verwalten" einer bestimmten Sitzung klickst. Hier kannst du detaillierte Informationen über die Sitzung anzeigen, wie z. B. das Gerät, den Standort und die Anmeldezeit. Wenn du den Benutzer aus dieser Sitzung abmelden möchtest, klicke einfach auf die Schaltfläche "Sitzung widerrufen" in der rechten oberen Ecke, und die Sitzung wird sofort widerrufen. -- Standardmäßig wird beim Widerrufen einer Sitzung in der Console auch alle zugehörigen First-Party-App-Genehmigungen widerrufen, und der Benutzer muss sich erneut anmelden, um den Zugriff wiederherzustellen. Alle zuvor ausgestellten opaken Zugangstokens und Auffrischungstokens für First-Party-Apps werden ebenfalls sofort widerrufen. -- Für Drittanbieter-Apps mit `offline_access`-Berechtigung widerruft das Widerrufen einer Sitzung standardmäßig nicht die App-Genehmigung, alle zuvor ausgestellten Auffrischungstokens können weiterhin verwendet werden, bis die Genehmigung abläuft. +- Standardmäßig wird beim Widerrufen einer Sitzung in der Konsole auch alle mit dieser Sitzung verbundenen First-Party-App-Gewährungen widerrufen, und der Benutzer muss sich erneut anmelden, um den Zugriff wiederherzustellen. Alle zuvor ausgestellten opaken Zugangstokens und Auffrischungstokens für First-Party-Apps werden ebenfalls sofort widerrufen. +- Für Drittanbieter-Apps mit `offline_access`-Berechtigung widerruft das Widerrufen einer Sitzung standardmäßig nicht die App-Gewährung, alle zuvor ausgestellten Auffrischungstokens können weiterhin verwendet werden, bis die Gewährung abläuft. -## Passwort-Compliance-Prüfung \{#password-compliance-check} +### Autorisierte Drittanbieter-Apps des Benutzers verwalten \{#manage-user-authorized-third-party-apps} -Nachdem du die [Passwortrichtlinie](/security/password-policy) in Logto aktualisiert hast, können sich bestehende Benutzer weiterhin mit ihren aktuellen Passwörtern anmelden. Nur neu erstellte Konten müssen die aktualisierte Passwortrichtlinie befolgen. +Auf der Seite "Benutzerdetails" kannst du den Abschnitt "Autorisierte Drittanbieter-Apps" verwenden, um den Autorisierungsstatus der App für den Benutzer zu überprüfen. +Dieser Abschnitt wird durch die Verwaltung der von Benutzern autorisierten Apps (Gewährungen) APIs unterstützt. -Um eine stärkere Sicherheit durchzusetzen, kannst du die `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) verwenden, um zu überprüfen, ob das Passwort eines Benutzers der aktuellen Richtlinie in der Standard-Anmeldeerfahrung entspricht. Falls nicht, kannst du den Benutzer mit einem benutzerdefinierten Ablauf auffordern, sein Passwort mit der [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) zu aktualisieren. +Für jede autorisierte App zeigt die Konsole: + +- App-Name +- App-ID +- Zeitpunkt der Zugriffserstellung + +Wenn du den Zugriff entfernen musst, klicke auf die Widerrufsaktion und bestätige im Modal. + +Das Widerrufen einer App-Autorisierung entfernt alle aktiven Drittanbieter-Gewährungen, die mit dieser App für den Benutzer verbunden sind. Es wird auch alle zuvor ausgestellten opaken Zugangstokens und Auffrischungstokens für diese App sofort widerrufen. + +## Passwort-Compliance-Check \{#password-compliance-check} + +Nachdem du die [Passwortrichtlinie](/security/password-policy) in Logto aktualisiert hast, können sich bestehende Benutzer weiterhin mit ihren aktuellen Passwörtern anmelden. Nur neu erstellte Konten müssen der aktualisierten Passwortrichtlinie folgen. + +Um eine stärkere Sicherheit zu erzwingen, kannst du die `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) verwenden, um zu überprüfen, ob das Passwort eines Benutzers den aktuellen Richtlinien entspricht, die in der Standard-Anmeldeerfahrung definiert sind. Wenn dies nicht der Fall ist, kannst du den Benutzer mit einem benutzerdefinierten Ablauf auffordern, sein Passwort mit der [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) zu aktualisieren. ### Rollen von Benutzern verwalten \{#manage-roles-of-users} -Im Tab „Rollen“ auf der Seite mit den Benutzerdetails kannst du Rollen einfach zuweisen oder entfernen, um das gewünschte Ergebnis zu erzielen. Siehe [Rollenbasierte Zugangskontrolle (RBAC)](/authorization/role-based-access-control) für Details. +Im Tab "Rollen" der Seite mit den Benutzerdetails kannst du einfach Rollen zuweisen oder entfernen, um dein gewünschtes Ergebnis zu erzielen. Siehe [Rollenbasierte Zugangskontrolle](/authorization/role-based-access-control) für Details. -### Organisationen anzeigen, denen der Benutzer angehört \{#view-the-organizations-the-user-belongs-to} +### Die Organisationen anzeigen, zu denen der Benutzer gehört \{#view-the-organizations-the-user-belongs-to} -Logto unterstützt [Organisationen](/organizations/organization-management) und kann deren Mitglieder verwalten. Du kannst Benutzerdetails einfach anzeigen und sehen, zu welcher Organisation sie gehören. +Logto unterstützt [Organisationen](/organizations/organization-management) und kann deren Mitglieder verwalten. Du kannst einfach Benutzerdetails anzeigen und sehen, zu welcher Organisation sie gehören. ## Verwaltung über die Logto Management API \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) ist eine Sammlung von APIs, die Zugriff auf den Logto-Backend-Service bieten. Wie bereits erwähnt, ist die Benutzer-API ein wichtiger Bestandteil dieses Dienstes und kann eine Vielzahl von Szenarien unterstützen. +[Management API](/concepts/core-service/#management-api) ist eine Sammlung von APIs, die Zugriff auf den Logto-Backend-Dienst bieten. Wie bereits erwähnt, ist die Benutzer-API ein kritischer Bestandteil dieses Dienstes und kann eine Vielzahl von Szenarien unterstützen. -Die benutzerbezogenen [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs sind unter `/api/users` verfügbar, mit Ausnahme der Benutzeraktivitäten, d. h. Benutzerprotokolle `/api/logs?userId=:userId`. +Die benutzerbezogenen [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs sind unter `/api/users` montiert, mit Ausnahme der Benutzeraktivitäten, d. h. Benutzerprotokolle `/api/logs?userId=:userId`. -Du kannst Benutzer über die Management API in verschiedenen Anwendungsfällen verwalten, z. B. [erweiterte Benutzersuche](/user-management/advanced-user-search), [Massenkontenerstellung](https://openapi.logto.io/operation/operation-createuser), [Registrierung nur auf Einladung](/end-user-flows/sign-up-and-sign-in/disable-user-registration) usw. +Du kannst Benutzer über die Management API in mehreren Anwendungsfällen verwalten. Zum Beispiel [erweiterte Benutzersuche](/user-management/advanced-user-search), [Massenkontenerstellung](https://openapi.logto.io/operation/operation-createuser), [Registrierung nur auf Einladung](/end-user-flows/sign-up-and-sign-in/disable-user-registration) usw. ## FAQs \{#faqs} @@ -129,8 +144,8 @@ Du kannst Benutzer über die Management API in verschiedenen Anwendungsfällen v -Aufgrund der [Omni-sign-in](https://logto.io/products/omni-sign-in)-Natur von Logto ist es nicht dafür ausgelegt, den Benutzerzugriff auf bestimmte Anwendungen vor der Authentifizierung einzuschränken. +Aufgrund der [Omni-Anmeldung](https://logto.io/products/omni-sign-in) von Logto ist es nicht darauf ausgelegt, den Benutzerzugriff auf bestimmte Anwendungen vor der Authentifizierung einzuschränken. Du kannst jedoch anwendungsspezifische Benutzerrollen und Berechtigungen entwerfen, um deine API-Ressourcen zu schützen, und Berechtigungen beim API-Zugriff nach erfolgreicher Benutzeranmeldung validieren. -Siehe Autorisierung: [Rollenbasierte Zugangskontrolle (RBAC)](/authorization/role-based-access-control) für weitere Informationen. +Siehe Autorisierung: [Rollenbasierte Zugangskontrolle](/authorization/role-based-access-control) für weitere Informationen. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 5c0c490e908..0f30bcd01c5 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,45 +7,45 @@ sidebar_position: 5 # Claves de firma -Las [claves de firma OIDC](https://auth.wiki/signing-key) de Logto, también conocidas como "claves privadas OIDC" y "claves de cookies OIDC", son las claves de firma utilizadas para firmar JWTs ([tokens de acceso](https://auth.wiki/access-token) y [tokens de ID](https://auth.wiki/id-token)) y cookies del navegador en las [sesiones de inicio de sesión](/end-user-flows/sign-out#what-is-a-logto-session) de Logto. Estas claves de firma se generan al inicializar la base de datos de Logto ([código abierto](/logto-oss)) o al crear un nuevo tenant ([Cloud](/logto-cloud)) y pueden gestionarse a través de la [CLI](/logto-oss/using-cli) (código abierto), Management APIs o la interfaz de la Consola. +Las [claves de firma OIDC](https://auth.wiki/signing-key) de Logto, también conocidas como "claves privadas OIDC" y "claves de cookies OIDC", son las claves de firma utilizadas para firmar JWTs ([tokens de acceso](https://auth.wiki/access-token) y [tokens de ID](https://auth.wiki/id-token)) y cookies del navegador en las [sesiones de inicio de sesión](/sessions#what-is-a-logto-session) de Logto. Estas claves de firma se generan al sembrar la base de datos de Logto ([código abierto](/logto-oss)) o al crear un nuevo inquilino ([Cloud](/logto-cloud)) y se pueden gestionar a través de [CLI](/logto-oss/using-cli) (código abierto), Management APIs o la interfaz de usuario de la consola. -Por defecto, Logto utiliza el algoritmo de curva elíptica (EC) para generar firmas digitales. Sin embargo, considerando que los usuarios a menudo necesitan verificar firmas de JWT y muchas herramientas antiguas no admiten el algoritmo EC (solo admiten RSA), hemos implementado la funcionalidad para rotar claves privadas y permitir a los usuarios elegir el algoritmo de firma (incluyendo tanto RSA como EC). Esto garantiza la compatibilidad con servicios que utilizan herramientas de verificación de firmas obsoletas. +Por defecto, Logto utiliza el algoritmo de curva elíptica (EC) para generar firmas digitales. Sin embargo, considerando que los usuarios a menudo necesitan verificar firmas de JWT y muchas herramientas antiguas no admiten el algoritmo EC (solo admiten RSA), hemos implementado la funcionalidad para rotar claves privadas y permitir a los usuarios elegir el algoritmo de firma (incluyendo tanto RSA como EC). Esto asegura la compatibilidad con servicios que utilizan herramientas de verificación de firmas obsoletas. :::note -Teóricamente, las claves de firma no deberían filtrarse y no tienen un tiempo de expiración, lo que significa que no es necesario rotarlas. Sin embargo, rotar periódicamente la clave de firma después de cierto tiempo puede mejorar la seguridad. +Teóricamente, las claves de firma no deberían filtrarse y no tienen un tiempo de expiración, lo que significa que no hay necesidad de rotarlas. Sin embargo, rotar periódicamente la clave de firma después de un cierto período puede mejorar la seguridad. ::: ## ¿Cómo funciona? \{#how-it-works} - **Clave privada OIDC** - Al inicializar una instancia de Logto, se genera automáticamente un par de clave pública y clave privada, que se registran en el proveedor OIDC subyacente. Así, cuando Logto emite un nuevo JWT (token de acceso o token de ID), el token se firma con la clave privada. Mientras tanto, cualquier aplicación cliente que reciba un JWT puede usar la clave pública emparejada para verificar la firma del token, con el fin de asegurar que el token no ha sido manipulado por terceros. La clave privada está protegida en el servidor de Logto. La clave pública, como su nombre indica, es pública para todos y puede accederse a través de la interfaz `/oidc/jwks` del endpoint OIDC. Se puede especificar un algoritmo de clave de firma al generar la clave privada, y Logto utiliza el algoritmo EC (Curva Elíptica) por defecto. Los usuarios administradores pueden cambiar el algoritmo predeterminado a RSA (Rivest-Shamir-Adleman) rotando las claves privadas. + Al inicializar una instancia de Logto, se genera automáticamente un par de clave pública y clave privada y se registran en el proveedor OIDC subyacente. Por lo tanto, cuando Logto emite un nuevo JWT (token de acceso o token de ID), el token se firma con la clave privada. Mientras tanto, cualquier aplicación cliente que reciba un JWT puede usar la clave pública emparejada para verificar la firma del token, con el fin de asegurar que el token no sea manipulado por terceros. La clave privada está protegida en el servidor de Logto. La clave pública, sin embargo, como su nombre indica, es pública para todos y se puede acceder a través de la interfaz `/oidc/jwks` del punto final OIDC. Se puede especificar un algoritmo de clave de firma al generar la clave privada, y Logto utiliza el algoritmo EC (Curva Elíptica) por defecto. Los usuarios administradores pueden cambiar el algoritmo predeterminado a RSA (Rivest-Shamir-Adleman) rotando las claves privadas. - **Clave de cookie OIDC** - Cuando el usuario inicia un flujo de inicio de sesión o registro, se crea una "sesión OIDC" en el servidor, así como un conjunto de cookies en el navegador. Con estas cookies, el navegador puede solicitar a la Experience API de Logto realizar una serie de interacciones en nombre del usuario, como iniciar sesión, registrarse y restablecer la contraseña. Sin embargo, a diferencia de los JWTs, las cookies solo son firmadas y verificadas por el propio servicio OIDC de Logto, no se requieren medidas de criptografía asimétrica. Por lo tanto, no tenemos claves públicas emparejadas para las claves de firma de cookies, ni algoritmos de cifrado asimétrico. + Cuando el usuario inicia un flujo de inicio de sesión o registro, se creará una "sesión OIDC" en el servidor, así como un conjunto de cookies del navegador. Con estas cookies, el navegador puede solicitar a la Experience API de Logto realizar una serie de interacciones en nombre del usuario, como iniciar sesión, registrarse y restablecer la contraseña. Sin embargo, a diferencia de los JWTs, las cookies solo son firmadas y verificadas por el servicio OIDC de Logto, no se requieren medidas de criptografía asimétrica. Por lo tanto, no tenemos claves públicas emparejadas para las claves de firma de cookies, ni algoritmos de cifrado asimétrico. -## Rotar claves de firma desde la Consola \{#rotate-signing-keys-from-console-ui} +## Rotar claves de firma desde la interfaz de usuario de la consola \{#rotate-signing-keys-from-console-ui} -Logto introduce la función de "Rotación de claves de firma", que te permite crear una nueva clave privada OIDC y una clave de cookie en tu tenant. +Logto introduce una función de "Rotación de Claves de Firma", que te permite crear una nueva clave privada OIDC y una clave de cookie en tu inquilino. -1. Navega a Consola > Claves de firma. Desde allí, puedes gestionar tanto las claves privadas OIDC como las claves de cookies OIDC. +1. Navega a Consola > Configuración del tenant > Configuración de OIDC. Desde allí, puedes gestionar tanto las claves privadas OIDC como las claves de cookies OIDC. 2. Para rotar la clave de firma, haz clic en el botón "Rotar claves privadas" o "Rotar claves de cookies". Al rotar las claves privadas, tienes la opción de cambiar el algoritmo de firma. -3. Encontrarás una tabla que enumera todas las claves de firma en uso. Nota: Puedes eliminar la clave anterior, pero no puedes eliminar la actual. +3. Y encontrarás una tabla que lista todas las claves de firma en uso. Nota: Puedes eliminar la clave anterior, pero no puedes eliminar la actual. - | Estado | Descripción | - | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | - | Actual | Indica que esta clave está actualmente en uso activo dentro de tus aplicaciones y APIs. | - | Anterior | Se refiere a una clave que se usó previamente pero que ha sido rotada. Los tokens existentes con esta clave de firma siguen siendo válidos. | + | Estado | Descripción | + | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | + | Actual | Esto indica que esta clave está actualmente en uso activo dentro de tus aplicaciones y APIs. | + | Anterior | Se refiere a una clave que se usó anteriormente pero ha sido rotada. Los tokens existentes con esta clave de firma siguen siendo válidos. | -Recuerda que la rotación implica las siguientes tres acciones: +Por favor, recuerda que la rotación implica las siguientes tres acciones: 1. **Crear una nueva clave de firma**: Esto requerirá que todas tus **aplicaciones** y **APIs** adopten la nueva clave de firma. -2. **Rotar la clave actual**: La clave existente se designará como "anterior" después de la rotación y no será utilizada por las nuevas aplicaciones y APIs. Sin embargo, los tokens firmados con esta clave seguirán siendo válidos. -3. **Eliminar tu clave anterior**: Las claves etiquetadas como "anterior" serán revocadas y eliminadas de la tabla. +2. **Rotar la clave actual**: La clave existente se designará como "anterior" después de la rotación y no será utilizada por aplicaciones y APIs recién creadas. Sin embargo, los tokens firmados con esta clave seguirán siendo válidos. +3. **Eliminar tu clave anterior**: Las claves etiquetadas como "anteriores" serán revocadas y eliminadas de la tabla. :::warning -Nunca rotes las claves de firma consecutivamente (dos o más veces), ya que esto puede invalidar TODOS los tokens emitidos. +Nunca rotar las claves de firma consecutivamente (dos o más veces), ya que esto puede invalidar TODOS los tokens emitidos. -- Para usuarios OSS, después de rotar la clave de firma, se requiere reiniciar la instancia de Logto para que la nueva clave de firma tenga efecto. -- Para usuarios Cloud, la nueva clave de firma entra en vigor inmediatamente después de la rotación, pero asegúrate de no rotar la clave de firma varias veces consecutivas. +- Para los usuarios de OSS, después de rotar la clave de firma, se requiere un reinicio de la instancia de Logto para que la nueva clave de firma surta efecto. +- Para los usuarios de Cloud, la nueva clave de firma surte efecto inmediatamente después de la rotación, pero asegúrate de no rotar la clave de firma varias veces consecutivamente. ::: ## Recursos relacionados \{#related-resources} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 061783ceda9..b9623a7d609 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,60 +1,62 @@ --- -description: Aprende cómo usar la Account API para gestionar usuarios +description: Aprende a usar la Account API para gestionar usuarios sidebar_position: 1 --- # Configuración de cuenta mediante Account API -## ¿Qué es la Account API de Logto? \{#what-is-logto-account-api} +## ¿Qué es Logto Account API? \{#what-is-logto-account-api} -La Account API de Logto es un conjunto completo de APIs que brinda a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí tienes los aspectos más destacados: +La Logto Account API es un conjunto completo de APIs que ofrece a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí están los aspectos destacados: - Acceso directo: La Account API permite a los usuarios finales acceder y gestionar directamente sus propios perfiles de cuenta sin requerir el uso de la Management API. -- Gestión de perfil de usuario e identidades: Los usuarios pueden gestionar completamente sus perfiles y configuraciones de seguridad, incluyendo la capacidad de actualizar información de identidad como correo electrónico, teléfono y contraseña, así como gestionar conexiones sociales. El soporte para MFA y SSO estará disponible próximamente. -- Control de acceso global: Los administradores tienen control total y global sobre la configuración de acceso y pueden personalizar cada campo. -- Autorización sin complicaciones: ¡La autorización es más fácil que nunca! Simplemente usa `client.getAccessToken()` para obtener un token de acceso opaco para OP (Logto), y adjúntalo al encabezado Authorization como `Bearer `. +- Gestión de perfiles de usuario e identidades: Los usuarios pueden gestionar completamente sus perfiles y configuraciones de seguridad, incluyendo la capacidad de actualizar información de identidad como correo electrónico, teléfono y contraseña, así como gestionar conexiones sociales. El soporte para MFA y SSO estará disponible pronto. +- Control de acceso global: Los administradores tienen control total y global sobre las configuraciones de acceso y pueden personalizar cada campo. +- Autorización sin problemas: ¡La autorización es más fácil que nunca! Simplemente usa `client.getAccessToken()` para obtener un token de acceso opaco para OP (Logto) y adjúntalo al encabezado de Autorización como `Bearer `. -Con la Account API de Logto, puedes construir un sistema personalizado de gestión de cuentas como una página de perfil totalmente integrada con Logto. +Con la Logto Account API, puedes construir un sistema de gestión de cuentas personalizado como una página de perfil totalmente integrada con Logto. Algunos casos de uso frecuentes se enumeran a continuación: -- Recuperar el perfil del usuario -- Actualizar el perfil del usuario -- Actualizar la contraseña del usuario -- Actualizar las identidades del usuario, incluyendo correo electrónico, teléfono y conexiones sociales +- Recuperar perfil de usuario +- Actualizar perfil de usuario +- Actualizar contraseña de usuario +- Actualizar identidades de usuario incluyendo correo electrónico, teléfono y conexiones sociales - Gestionar factores de MFA (verificaciones) - Gestionar sesiones de usuario +- Gestionar aplicaciones autorizadas por el usuario (concesiones) -Para obtener más información sobre las APIs disponibles, visita la [Referencia de Logto Account API](https://openapi.logto.io/group/endpoint-my-account) y la [Referencia de Logto Verification API](https://openapi.logto.io/group/endpoint-verifications). +Para obtener más información sobre las APIs disponibles, visita [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) y [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). :::note -Las funciones de visualización de cuentas SSO y eliminación de cuentas están actualmente disponibles a través de las Management APIs de Logto. Consulta [Configuración de cuenta mediante Management API](/end-user-flows/account-settings/by-management-api) para detalles de implementación. +Las funciones de visualización de cuentas SSO y eliminación de cuentas están actualmente disponibles a través de las Logto Management APIs. Consulta [Configuración de cuenta mediante Management API](/end-user-flows/account-settings/by-management-api) para detalles de implementación. ::: -## Cómo habilitar la Account API \{#how-to-enable-account-api} +## Cómo habilitar Account API \{#how-to-enable-account-api} -Navega a Consola > Inicio de sesión y cuenta > Centro de cuentas. +Navega a Console > Sign-in & account > Account center. -La Account API está desactivada por defecto, por lo que sus controles de acceso están bloqueados. Activa **Habilitar Account API** para encenderla. +La Account API está desactivada por defecto, por lo que sus controles de acceso están bloqueados. Activa **Enable Account API** para encenderla. Una vez habilitada, configura los permisos por campo para identificadores, datos de perfil y acceso a tokens de terceros. Cada campo admite `Off`, `ReadOnly` o `Edit`; el valor predeterminado es `Off`. 1. **Campos de seguridad**: - Los campos incluyen: correo electrónico principal, teléfono principal, identidades sociales, contraseña y MFA. - - Antes de que los usuarios finales editen estos campos, deben verificar su identidad mediante contraseña, correo electrónico o SMS para obtener un ID de registro de verificación válido por 10 minutos. Consulta [Obtener un ID de registro de verificación](#get-a-verification-record-id). - - Para usar claves de acceso WebAuthn para MFA, añade los dominios de tu app front-end a **WebAuthn Related Origins** para que el centro de cuentas y la experiencia de inicio de sesión puedan compartir claves de acceso. Consulta [Vincular una nueva clave de acceso WebAuthn](#link-a-new-webauthn-passkey). + - Antes de que los usuarios finales editen estos campos, deben verificar su identidad a través de contraseña, correo electrónico o SMS para obtener un ID de registro de verificación de 10 minutos. Consulta [Obtener un ID de registro de verificación](#get-a-verification-record-id). + - Para usar claves de paso WebAuthn para MFA, agrega los dominios de tus aplicaciones front-end a **WebAuthn Related Origins** para que el centro de cuentas y la experiencia de inicio de sesión puedan compartir claves de paso. Consulta [Vincular una nueva clave de paso WebAuthn](#link-a-new-webauthn-passkey). 2. **Campos de perfil**: - - Los campos incluyen: nombre de usuario, nombre, avatar, [perfil](/user-management/user-data#profile) (otros atributos estándar de perfil) y [datos personalizados](/user-management/user-data#custom-data). - - Los usuarios finales pueden editar estos campos sin verificación adicional. -3. **Secret vault**: - - Para conectores sociales y empresariales OIDC u OAuth, el [secret vault](/secret-vault/federated-token-set) de Logto almacena de forma segura los tokens de acceso y actualización de terceros después de la autenticación. Las aplicaciones pueden entonces llamar a APIs externas, como sincronizar eventos de Google Calendar, sin pedir a los usuarios que inicien sesión de nuevo. La recuperación de tokens estará disponible automáticamente una vez que la Account API esté habilitada. + - Los campos incluyen: nombre de usuario, nombre, avatar, [perfil](/user-management/user-data#profile) (otros atributos de perfil estándar) y [datos personalizados](/user-management/user-data#custom-data). + - Los usuarios finales pueden editar estos sin verificación adicional. +3. **Bóveda secreta**: + - Para conectores sociales y empresariales OIDC o OAuth, Logto [bóveda secreta](/secret-vault/federated-token-set) almacena de forma segura los tokens de acceso y actualización de terceros después de la autenticación. Las aplicaciones pueden entonces llamar a APIs externas, como sincronizar eventos de Google Calendar, sin pedir a los usuarios que inicien sesión nuevamente. La recuperación de tokens se vuelve disponible automáticamente una vez que la Account API está habilitada. 4. **Gestión de sesiones**: - - Cuando está habilitada, los usuarios pueden ver y gestionar sus sesiones activas, incluyendo información del dispositivo y la última hora de inicio de sesión. Los usuarios también pueden revocar sesiones para cerrar sesión en dispositivos específicos. - - Antes de que los usuarios finales accedan a la gestión de sesiones, deben verificar su identidad mediante contraseña, correo electrónico o SMS para obtener un ID de registro de verificación válido por 10 minutos. Consulta [Obtener un ID de registro de verificación](#get-a-verification-record-id). + - Cuando está habilitada, los usuarios pueden ver y gestionar sus sesiones activas, incluyendo información del dispositivo y la última hora de inicio de sesión. Los usuarios también pueden revocar sesiones para cerrar sesión desde dispositivos específicos. + - Este mismo permiso de campo `Sessions` también controla las APIs de aplicaciones autorizadas por el usuario (ver y revocar concesiones). + - Antes de que los usuarios finales accedan a la gestión de sesiones, deben verificar su identidad a través de contraseña, correo electrónico o SMS para obtener un ID de registro de verificación de 10 minutos. Consulta [Obtener un ID de registro de verificación](#get-a-verification-record-id). -## Cómo acceder a la Account API \{#how-to-access-account-api} +## Cómo acceder a Account API \{#how-to-access-account-api} :::note Para asegurar que el token de acceso tenga los permisos apropiados, asegúrate de haber configurado correctamente los alcances correspondientes en tu configuración de Logto. @@ -66,15 +68,15 @@ import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...otras opciones - // Añade los alcances apropiados según tus casos de uso. + // Agrega los alcances adecuados que se ajusten a tus casos de uso. scopes: [ UserScope.Email, // Para las APIs `{POST,DELETE} /api/my-account/primary-email` UserScope.Phone, // Para las APIs `{POST,DELETE} /api/my-account/primary-phone` UserScope.CustomData, // Para gestionar datos personalizados - UserScope.Address, // Para gestionar dirección + UserScope.Address, // Para gestionar la dirección UserScope.Identities, // Para APIs relacionadas con identidad y MFA UserScope.Profile, // Para gestionar el perfil de usuario - UserScope.Sessions, // Para gestionar sesiones de usuario + UserScope.Sessions, // Para gestionar sesiones de usuario y concesiones de aplicaciones ], }; ``` @@ -83,11 +85,11 @@ const config: LogtoConfig = { ### Obtener un token de acceso \{#fetch-an-access-token} -Después de configurar el SDK en tu aplicación, puedes usar el método `client.getAccessToken()` para obtener un token de acceso. Este token es un token opaco (Opaque token) que puede usarse para acceder a la Account API. +Después de configurar el SDK en tu aplicación, puedes usar el método `client.getAccessToken()` para obtener un token de acceso. Este token es un token opaco que se puede usar para acceder a la Account API. -Si no estás usando el SDK oficial, debes establecer el `resource` como vacío para la solicitud de concesión de token de acceso a `/oidc/token`. +Si no estás usando el SDK oficial, debes establecer el `resource` en vacío para la solicitud de concesión de token de acceso a `/oidc/token`. -### Acceder a la Account API usando el token de acceso \{#access-account-api-using-access-token} +### Acceder a Account API usando el token de acceso \{#access-account-api-using-access-token} Debes incluir el token de acceso en el campo `Authorization` de los encabezados HTTP con el formato Bearer (`Bearer YOUR_TOKEN`) al interactuar con la Account API. @@ -102,14 +104,14 @@ curl https://[tenant-id].logto.app/api/my-account \ ### Recuperar información de la cuenta de usuario \{#retrieve-user-account-information} -Para obtener los datos del usuario, puedes usar el endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). +Para obtener datos de usuario, puedes usar el endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -120,13 +122,13 @@ El cuerpo de la respuesta sería así: } ``` -Los campos de la respuesta pueden variar dependiendo de la configuración del centro de cuentas. +Los campos de respuesta pueden variar dependiendo de la configuración del centro de cuentas. ### Actualizar información básica de la cuenta \{#update-basic-account-information} La información básica de la cuenta incluye el nombre de usuario, nombre, avatar, datos personalizados y otra información de perfil. -Para actualizar **username, name, avatar y customData** puedes usar el endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). +Para actualizar **username, name, avatar, y customData** puedes usar el endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -Para actualizar otra información de perfil, incluyendo **familyName, givenName, middleName, nickname, profile (URL de la página de perfil), website, gender, birthdate, zoneinfo, locale y address**, puedes usar el endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). +Para actualizar otra información de perfil, incluyendo **familyName, givenName, middleName, nickname, profile (URL de la página de perfil), website, gender, birthdate, zoneinfo, locale, y address**, puedes usar el endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -146,11 +148,11 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Gestionar identificadores y otra información sensible \{#manage-identifiers-and-other-sensitive-information} -Por razones de seguridad, la Account API requiere una capa adicional de autorización para operaciones que involucren identificadores y otra información sensible. +Por razones de seguridad, la Account API requiere una capa adicional de autorización para operaciones que involucran identificadores y otra información sensible. ### Obtener un ID de registro de verificación \{#get-a-verification-record-id} -Primero, necesitas obtener un **ID de registro de verificación** con una expiración de 10 minutos (TTL). Esto puede usarse para verificar la identidad del usuario antes de actualizar información sensible. Esto significa que una vez que un usuario verifica exitosamente su identidad mediante contraseña, código de verificación por correo electrónico o código de verificación por SMS, tiene 10 minutos para actualizar sus datos relacionados con autenticación, incluyendo identificadores, credenciales, vinculación de cuentas sociales y MFA. +Primero, necesitas obtener un **ID de registro de verificación** con una expiración de 10 minutos (TTL). Esto se puede usar para verificar la identidad del usuario antes de actualizar información sensible. Esto significa que una vez que un usuario verifica exitosamente su identidad a través de contraseña, código de verificación por correo electrónico o código de verificación por SMS, tiene 10 minutos para actualizar sus datos relacionados con la autenticación, incluyendo identificadores, credenciales, vinculación de cuentas sociales y MFA. Para obtener un ID de registro de verificación, puedes [verificar la contraseña del usuario](#verify-the-users-password) o [enviar un código de verificación al correo electrónico o teléfono del usuario](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -178,7 +180,7 @@ El cuerpo de la respuesta sería así: Para usar este método, necesitas [configurar el conector de correo electrónico](/connectors/email-connectors/) o [conector de SMS](/connectors/sms-connectors/), y asegurarte de que la plantilla `UserPermissionValidation` esté configurada. ::: -Tomando el correo electrónico como ejemplo, solicita un nuevo código de verificación y obtén el ID de registro de verificación: +Toma el correo electrónico como ejemplo, solicita un nuevo código de verificación y obtén el ID de registro de verificación: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -196,7 +198,7 @@ El cuerpo de la respuesta sería así: } ``` -Al recibir el código de verificación, puedes usarlo para actualizar el estado de verificación del registro. +Al recibir el código de verificación, puedes usarlo para actualizar el estado de verificación del registro de verificación. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -207,11 +209,11 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v Después de verificar el código, ahora puedes usar el ID de registro de verificación para actualizar el identificador del usuario. -Para obtener más información sobre verificaciones, consulta [Verificación de seguridad mediante Account API](/end-user-flows/security-verification). +Para obtener más información sobre las verificaciones, consulta [Verificación de seguridad mediante Account API](/end-user-flows/security-verification). ### Enviar solicitud con ID de registro de verificación \{#send-request-with-verification-record-id} -Al enviar una solicitud para actualizar el identificador del usuario, debes incluir el ID de registro de verificación en el encabezado de la solicitud con el campo `logto-verification-id`. +Al enviar una solicitud para actualizar el identificador del usuario, necesitas incluir el ID de registro de verificación en el encabezado de la solicitud con el campo `logto-verification-id`. ### Actualizar la contraseña del usuario \{#update-users-password} @@ -226,16 +228,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -Al igual que las contraseñas creadas durante el registro, las contraseñas establecidas a través de la Account API deben cumplir con la [política de contraseñas](/security/password-policy) que configuraste en Consola > Seguridad > Política de contraseñas. Logto devuelve resultados de validación detallados y mensajes de error si la contraseña no cumple la política. +Al igual que las contraseñas creadas durante el registro, las contraseñas establecidas a través de la Account API deben cumplir con la [política de contraseñas](/security/password-policy) que configuraste en Console > Security > Password policy. Logto devuelve resultados de validación detallados y mensajes de error si la contraseña no cumple con la política. ::: ### Actualizar o vincular un nuevo correo electrónico \{#update-or-link-new-email} :::note -Para usar este método, necesitas [configurar el conector de correo electrónico](/connectors/email-connectors/) y asegurarte de que la plantilla `BindNewIdentifier` esté configurada. +Para usar este método, necesitas [configurar el conector de correo electrónico](/connectors/email-connectors/), y asegurarte de que la plantilla `BindNewIdentifier` esté configurada. ::: -Para actualizar o vincular un nuevo correo electrónico, primero debes demostrar la propiedad del correo. +Para actualizar o vincular un nuevo correo electrónico, primero debes demostrar la propiedad del correo electrónico. Llama al endpoint [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) para solicitar un código de verificación. @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Encontrarás un `verificationId` en la respuesta y recibirás un código de verificación en el correo electrónico; úsalo para verificar el correo. +Encontrarás un `verificationId` en la respuesta y recibirás un código de verificación en el correo electrónico, úsalo para verificar el correo electrónico. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,29 +257,29 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Después de verificar el código, ahora puedes llamar a [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) para actualizar el correo electrónico del usuario, estableciendo el `verificationId` en el cuerpo de la solicitud como `newIdentifierVerificationRecordId`. +Después de verificar el código, ahora puedes llamar a [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) para actualizar el correo electrónico del usuario, establece el `verificationId` en el cuerpo de la solicitud como `newIdentifierVerificationRecordId`. -:::info[Dos IDs de registro de verificación diferentes] +:::info[Dos diferentes IDs de registro de verificación] Esta solicitud requiere dos IDs de registro de verificación separados: -- **`logto-verification-id` (header)**: Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto [verificando la contraseña del usuario](#verify-the-users-password) o [enviando un código de verificación al correo electrónico o teléfono existente del usuario](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (body)**: Demuestra la propiedad del nuevo correo electrónico. Este es el `verificationRecordId` devuelto por la llamada `POST /api/verifications/verification-code` anterior. +- **`logto-verification-id` (encabezado)**: Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto [verificando la contraseña del usuario](#verify-the-users-password) o [enviando un código de verificación al correo electrónico o teléfono existente del usuario](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (cuerpo)**: Demuestra la propiedad de la nueva dirección de correo electrónico. Este es el `verificationRecordId` devuelto por la llamada `POST /api/verifications/verification-code` anterior. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # Verifica la identidad del usuario (por contraseña o verificación de correo/teléfono existente) + # Verifica la identidad del usuario (de la contraseña o verificación de correo electrónico/teléfono existente) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # El "newIdentifierVerificationRecordId" demuestra la propiedad del nuevo correo (del flujo de verificación anterior) + # El "newIdentifierVerificationRecordId" demuestra la propiedad del nuevo correo electrónico (del flujo de código de verificación anterior) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -Al igual que los correos electrónicos recogidos durante el registro, cualquier correo vinculado a través de la Account API debe pasar la verificación de la [lista de bloqueo](/security/blocklist) que configuraste en Consola > Seguridad > Lista de bloqueo. Logto rechazará la solicitud y devolverá un error detallado si el correo viola la política. +Al igual que los correos electrónicos recopilados durante el registro, cualquier correo electrónico vinculado a través de la Account API debe pasar la verificación de [lista de bloqueo](/security/blocklist) que configuraste en Console > Security > Blocklist. Logto rechazará la solicitud y devolverá un error detallado si el correo electrónico viola la política. ::: ### Eliminar el correo electrónico del usuario \{#remove-the-users-email} @@ -293,10 +295,10 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Gestionar teléfono \{#manage-phone} :::note -Para usar este método, necesitas [configurar el conector de SMS](/connectors/sms-connectors/) y asegurarte de que la plantilla `BindNewIdentifier` esté configurada. +Para usar este método, necesitas [configurar el conector de SMS](/connectors/sms-connectors/), y asegurarte de que la plantilla `BindNewIdentifier` esté configurada. ::: -De manera similar a la actualización de correo electrónico, puedes usar el endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) para actualizar o vincular un nuevo teléfono. Y usa el endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) para eliminar el teléfono del usuario. +Similar a la actualización de correo electrónico, puedes usar el endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) para actualizar o vincular un nuevo teléfono. Y usa el endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) para eliminar el teléfono del usuario. ### Vincular una nueva conexión social \{#link-a-new-social-connection} @@ -310,12 +312,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`: El ID del [conector social](/connectors/social-connectors/). -- `redirectUri`: La URI de redirección después de que el usuario autorice la aplicación; debes alojar una página web en esta URL y capturar el callback. -- `state`: El estado que se devolverá después de que el usuario autorice la aplicación; es una cadena aleatoria que se utiliza para prevenir ataques CSRF. +- `redirectUri`: La URI de redirección después de que el usuario autorice la aplicación, debes alojar una página web en esta URL y capturar la devolución de llamada. +- `state`: El estado que se devolverá después de que el usuario autorice la aplicación, es una cadena aleatoria que se usa para prevenir ataques CSRF. -En la respuesta, encontrarás un `verificationRecordId`, guárdalo para su uso posterior. +En la respuesta, encontrarás un `verificationRecordId`, guárdalo para uso posterior. -Después de que el usuario autorice la aplicación, recibirás un callback en el `redirectUri` con el parámetro `state`. Luego puedes usar el endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) para verificar la conexión social. +Después de que el usuario autorice la aplicación, recibirás una devolución de llamada en el `redirectUri` con el parámetro `state`. Luego puedes usar el endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) para verificar la conexión social. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,23 +326,23 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -El `connectorData` es la información devuelta por el conector social después de que el usuario autoriza la aplicación; necesitas analizar y obtener los parámetros de consulta del `redirectUri` en tu página de callback y envolverlos como un JSON como valor del campo `connectorData`. +El `connectorData` es el dato devuelto por el conector social después de que el usuario autorice la aplicación, necesitas analizar y obtener los parámetros de consulta del `redirectUri` en tu página de devolución de llamada, y envolverlos como un JSON como el valor del campo `connectorData`. Finalmente, puedes usar el endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) para vincular la conexión social. -:::info[Dos IDs de registro de verificación diferentes] +:::info[Dos diferentes IDs de registro de verificación] Esta solicitud requiere dos IDs de registro de verificación separados: -- **`logto-verification-id` (header)**: Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto [verificando la contraseña del usuario](#verify-the-users-password) o [enviando un código de verificación al correo electrónico o teléfono existente del usuario](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (body)**: Identifica la identidad social que se está vinculando. Este es el `verificationRecordId` devuelto por la llamada `POST /api/verifications/social` anterior. +- **`logto-verification-id` (encabezado)**: Demuestra la identidad del usuario antes de realizar cambios sensibles. Obtén esto [verificando la contraseña del usuario](#verify-the-users-password) o [enviando un código de verificación al correo electrónico o teléfono existente del usuario](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (cuerpo)**: Identifica la identidad social que se está vinculando. Este es el `verificationRecordId` devuelto por la llamada `POST /api/verifications/social` anterior. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # Verifica la identidad del usuario (por contraseña o verificación de correo/teléfono existente) + # Verifica la identidad del usuario (de la contraseña o verificación de correo electrónico/teléfono existente) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ # El "newIdentifierVerificationRecordId" identifica la conexión social a vincular (del flujo de verificación social anterior) @@ -357,7 +359,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Vincular una nueva clave de acceso WebAuthn \{#link-a-new-webauthn-passkey} +### Vincular una nueva clave de paso WebAuthn \{#link-a-new-webauthn-passkey} :::note Recuerda [habilitar MFA y WebAuthn](/end-user-flows/mfa) primero. @@ -367,20 +369,20 @@ Recuerda [habilitar MFA y WebAuthn](/end-user-flows/mfa) primero. Para usar este método, necesitas habilitar el campo `mfa` en la [configuración del centro de cuentas](#how-to-enable-account-api). ::: -**Paso 1: Añade el origen de tu app front-end a los orígenes relacionados** +**Paso 1: Agrega el origen de tu aplicación front-end a los orígenes relacionados** -Las claves de acceso WebAuthn están vinculadas a un hostname específico llamado **Relying Party ID (RP ID)**. Solo las aplicaciones alojadas en el origen del RP ID pueden registrar o autenticar con esas claves. +Las claves de paso WebAuthn están vinculadas a un nombre de host específico llamado **Relying Party ID (RP ID)**. Solo las aplicaciones alojadas en el origen del RP ID pueden registrar o autenticar con esas claves de paso. -Dado que tu aplicación front-end llama a la Account API desde un dominio diferente al de las páginas de autenticación de Logto, necesitas configurar **Related Origins** para permitir operaciones de claves de acceso entre dominios. +Dado que tu aplicación front-end llama a la Account API desde un dominio diferente al de las páginas de autenticación de Logto, necesitas configurar **Related Origins** para permitir operaciones de claves de paso entre dominios. **Cómo determina Logto el RP ID:** - **Configuración predeterminada**: Si solo usas el dominio predeterminado de Logto `https://[tenant-id].logto.app`, el RP ID es `[tenant-id].logto.app` -- **Dominio personalizado**: Si has configurado un [dominio personalizado](/logto-cloud/custom-domain) como `https://auth.example.com`, el RP ID será `auth.example.com` +- **Dominio personalizado**: Si has configurado un [dominio personalizado](/logto-cloud/custom-domain) como `https://auth.example.com`, el RP ID se convierte en `auth.example.com` -**Configura Related Origins:** +**Configurar Orígenes Relacionados:** -Usa el endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) para añadir el origen de tu aplicación front-end. Por ejemplo, si el centro de cuentas de tu app se ejecuta en `https://account.example.com`: +Usa el endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) para agregar el origen de la aplicación front-end. Por ejemplo, si el centro de cuentas de tu aplicación se ejecuta en `https://account.example.com`: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn admite hasta 5 etiquetas únicas eTLD+1 para Related Origins. El eTLD+1 (dominio de nivel superior efectivo más una etiqueta) es la parte registrable del dominio. Por ejemplo: +WebAuthn admite hasta 5 etiquetas eTLD+1 únicas para Orígenes Relacionados. El eTLD+1 (dominio de nivel superior efectivo más una etiqueta) es la parte del dominio registrable. Por ejemplo: -- `https://example.com`, `https://app.example.com` y `https://auth.example.com` cuentan como **una** etiqueta (`example.com`) -- `https://shopping.com`, `https://shopping.co.uk` y `https://shopping.co.jp` también cuentan como **una** etiqueta (`shopping`) +- `https://example.com`, `https://app.example.com`, y `https://auth.example.com` cuentan como **una** etiqueta (`example.com`) +- `https://shopping.com`, `https://shopping.co.uk`, y `https://shopping.co.jp` también cuentan como **una** etiqueta (`shopping`) - `https://example.com` y `https://another.com` cuentan como **dos** etiquetas -Si necesitas admitir más de 5 dominios diferentes como Related Origins, consulta la documentación de [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) para más detalles. +Si necesitas admitir más de 5 dominios diferentes como Orígenes Relacionados, consulta la documentación de [Solicitudes de Orígenes Relacionados](https://passkeys.dev/docs/advanced/related-origins/) para obtener detalles. ::: -**Paso 2: Solicita nuevas opciones de registro** +**Paso 2: Solicitar nuevas opciones de registro** -Usa el endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) para solicitar el registro de una nueva clave de acceso. Logto permite que cada cuenta de usuario registre múltiples claves. +Usa el endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) para solicitar el registro de una nueva clave de paso. Logto permite que cada cuenta de usuario registre múltiples claves de paso. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -421,9 +423,9 @@ Recibirás una respuesta como: } ``` -**Paso 3: Registra la clave de acceso en el navegador local** +**Paso 3: Registrar la clave de paso en el navegador local** -Tomando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como ejemplo, puedes usar la función `startRegistration` para registrar la clave en el navegador local. +Toma [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como ejemplo, puedes usar la función `startRegistration` para registrar la clave de paso en el navegador local. ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -432,14 +434,14 @@ import { startRegistration } from '@simplewebauthn/browser'; const response = await startRegistration({ optionsJSON: registrationOptions, // Los datos devueltos por el servidor en el paso 1 }); -// Guarda la respuesta para usarla después +// Guarda la respuesta para uso posterior ``` -**Paso 4: Verifica el registro de la clave de acceso** +**Paso 4: Verificar el registro de la clave de paso** -Usa el endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) para verificar el registro de la clave. +Usa el endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) para verificar el registro de la clave de paso. -Este paso verifica la firma criptográfica generada por el autenticador para asegurar que la clave fue creada legítimamente y no ha sido manipulada durante la transmisión. +Este paso verifica la firma criptográfica generada por el autenticador para asegurar que la clave de paso fue creada legítimamente y no ha sido alterada durante la transmisión. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -451,9 +453,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat - `payload`: La respuesta del navegador local en el paso 2. - `verificationRecordId`: El ID de registro de verificación devuelto por el servidor en el paso 1. -**Paso 5: Vincula la clave de acceso** +**Paso 5: Vincular la clave de paso** -Finalmente, puedes vincular la clave de acceso a la cuenta del usuario usando el endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). +Finalmente, puedes vincular la clave de paso a la cuenta del usuario usando el endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: un ID de registro de verificación válido, obtenido al verificar el factor existente del usuario; puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. +- `verification_record_id`: un ID de registro de verificación válido, otorgado al verificar el factor existente del usuario, puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. - `type`: el tipo de factor MFA, actualmente solo se admite `WebAuthn`. - `newIdentifierVerificationRecordId`: el ID de registro de verificación devuelto por el servidor en el paso 1. -### Gestionar claves de acceso WebAuthn existentes \{#manage-existing-webauthn-passkeys} +### Gestionar claves de paso WebAuthn existentes \{#manage-existing-webauthn-passkeys} -Para gestionar claves de acceso WebAuthn existentes, puedes usar el endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) para obtener las claves actuales y otros factores de verificación MFA. +Para gestionar claves de paso WebAuthn existentes, puedes usar el endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) para obtener las claves de paso actuales y otros factores de verificación MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json [ @@ -492,11 +494,11 @@ El cuerpo de la respuesta sería así: ``` - `id`: el ID de la verificación. -- `type`: el tipo de verificación, `WebAuthn` para clave de acceso WebAuthn. -- `name`: el nombre de la clave, campo opcional. -- `agent`: el user agent de la clave. +- `type`: el tipo de la verificación, `WebAuthn` para clave de paso WebAuthn. +- `name`: el nombre de la clave de paso, campo opcional. +- `agent`: el agente de usuario de la clave de paso. -Actualiza el nombre de la clave usando el endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname): +Actualiza el nombre de la clave de paso usando el endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname): ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Elimina la clave usando el endpoint [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification): +Elimina la clave de paso usando el endpoint [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification): ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -542,9 +544,9 @@ El cuerpo de la respuesta sería así: } ``` -**Paso 2: Muestra el secreto TOTP al usuario** +**Paso 2: Mostrar el secreto TOTP al usuario** -Usa el secreto para generar un código QR o muéstralo directamente al usuario. El usuario debe añadirlo a su app autenticadora (como Google Authenticator, Microsoft Authenticator o Authy). +Usa el secreto para generar un código QR o muéstralo directamente al usuario. El usuario debe agregarlo a su aplicación de autenticación (como Google Authenticator, Microsoft Authenticator o Authy). El formato URI para el código QR debe ser: @@ -555,12 +557,12 @@ otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] Ejemplo: ``` -otpauth://totp/TuApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=TuApp +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp ``` -**Paso 3: Vincula el factor TOTP** +**Paso 3: Vincular el factor TOTP** -Después de que el usuario haya añadido el secreto a su app autenticadora, debe verificarlo y vincularlo a su cuenta. Usa el endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) para vincular el factor TOTP. +Después de que el usuario haya agregado el secreto a su aplicación de autenticación, necesita verificarlo y vincularlo a su cuenta. Usa el endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) para vincular el factor TOTP. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,12 +572,12 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`: un ID de registro de verificación válido, obtenido al verificar el factor existente del usuario. Puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. +- `verification_record_id`: un ID de registro de verificación válido, otorgado al verificar el factor existente del usuario. Puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. - `type`: debe ser `Totp`. - `secret`: el secreto TOTP generado en el paso 1. :::note -Un usuario solo puede tener un factor TOTP a la vez. Si el usuario ya tiene un factor TOTP, intentar añadir otro resultará en un error 422. +Un usuario solo puede tener un factor TOTP a la vez. Si el usuario ya tiene un factor TOTP, intentar agregar otro resultará en un error 422. ::: ### Gestionar códigos de respaldo \{#manage-backup-codes} @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -606,18 +608,18 @@ El cuerpo de la respuesta sería así: } ``` -**Paso 2: Muestra los códigos de respaldo al usuario** +**Paso 2: Mostrar códigos de respaldo al usuario** -Antes de vincular los códigos de respaldo a la cuenta del usuario, debes mostrárselos e indicarle que: +Antes de vincular los códigos de respaldo a la cuenta del usuario, debes mostrarlos al usuario e instruirlo para que: - Descargue o anote estos códigos inmediatamente -- Los guarde en un lugar seguro -- Entienda que cada código solo puede usarse una vez +- Los almacene en un lugar seguro +- Entienda que cada código solo se puede usar una vez - Sepa que estos códigos son su último recurso si pierde acceso a sus métodos MFA principales -Debes mostrar los códigos en un formato claro y fácil de copiar y considerar ofrecer una opción de descarga (por ejemplo, como archivo de texto o PDF). +Debes mostrar los códigos en un formato claro y fácil de copiar y considerar proporcionar una opción de descarga (por ejemplo, como un archivo de texto o PDF). -**Paso 3: Vincula los códigos de respaldo a la cuenta del usuario** +**Paso 3: Vincular códigos de respaldo a la cuenta del usuario** Usa el endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) para vincular los códigos de respaldo a la cuenta del usuario. @@ -629,15 +631,15 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`: un ID de registro de verificación válido, obtenido al verificar el factor existente del usuario. Puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. +- `verification_record_id`: un ID de registro de verificación válido, otorgado al verificar el factor existente del usuario. Puedes consultar la sección [Obtener un ID de registro de verificación](#get-a-verification-record-id) para más detalles. - `type`: debe ser `BackupCode`. - `codes`: el array de códigos de respaldo generados en el paso anterior. :::note -- Un usuario solo puede tener un conjunto de códigos de respaldo a la vez. Si se han usado todos los códigos, el usuario debe generar y vincular nuevos códigos. +- Un usuario solo puede tener un conjunto de códigos de respaldo a la vez. Si se han utilizado todos los códigos, el usuario necesita generar y vincular nuevos códigos. - Los códigos de respaldo no pueden ser el único factor MFA. El usuario debe tener al menos otro factor MFA (como WebAuthn o TOTP) habilitado. -- Cada código de respaldo solo puede usarse una vez. +- Cada código de respaldo solo se puede usar una vez. ::: @@ -650,7 +652,7 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes -H 'authorization: Bearer ' ``` -El cuerpo de la respuesta sería así: +El cuerpo de la respuesta sería como: ```json { @@ -678,8 +680,8 @@ Para listar las sesiones activas del usuario, puedes usar el endpoint [`GET /api :::note -- El alcance `UserScope.Sessions` es necesario para acceder a este endpoint. -- El campo `Sessions` en la configuración del centro de cuentas debe estar en `ReadOnly` o `Edit`. +- Se requiere el alcance `UserScope.Sessions` para acceder a este endpoint. +- El campo `Sessions` en la configuración del centro de cuentas debe estar configurado en `ReadOnly` o `Edit`. ::: @@ -696,8 +698,8 @@ Para revocar una sesión específica, usa el endpoint [`DELETE /api/my-account/s :::note -- El alcance `UserScope.Sessions` es necesario para acceder a este endpoint. -- El campo `Sessions` en la configuración del centro de cuentas debe estar en `Edit`. +- Se requiere el alcance `UserScope.Sessions` para acceder a este endpoint. +- El campo `Sessions` en la configuración del centro de cuentas debe estar configurado en `Edit`. ::: ```bash @@ -709,7 +711,58 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} Parámetros de consulta opcionales: -- `revokeGrantsTarget`: Opcionalmente especifica el objetivo de los permisos a revocar junto con la sesión. Valores posibles: - - `all`: Revoca todos los permisos asociados con la sesión. - - `firstParty`: Revoca solo los permisos de aplicaciones de primera parte asociados con la sesión. (Recomendado para la mayoría de los casos de uso, ya que revoca el acceso para tu propia app mientras mantiene los permisos de apps de terceros intactos, proporcionando una mejor experiencia de usuario.) - - sin especificar: El comportamiento predeterminado revoca los permisos que no tienen el alcance `offline_access`, lo que normalmente significa revocar permisos que no son de refresh-token para la sesión. +- `revokeGrantsTarget`: Opcionalmente especifica el objetivo de las concesiones a revocar junto con la sesión. Valores posibles: + - `all`: Revoca todas las concesiones asociadas con la sesión. + - `firstParty`: Revoca solo las concesiones de aplicaciones de primera parte asociadas con la sesión. (Recomendado para la mayoría de los casos de uso, ya que revoca el acceso para tu propia aplicación mientras mantiene intactas las concesiones de aplicaciones de terceros, proporcionando una mejor experiencia de usuario). + - no especificado: El comportamiento predeterminado revoca las concesiones que no tienen el alcance `offline_access`, lo que generalmente significa revocar concesiones que no son de token de actualización para la sesión. + +### Gestionar aplicaciones autorizadas por el usuario (concesiones) \{#manage-user-authorized-apps-grants} + +Usa las APIs de aplicaciones autorizadas por el usuario (concesiones) cuando los usuarios necesiten revisar y revocar aplicaciones autorizadas desde su página de configuración de cuenta. + +:::note + +- Las APIs de concesiones de aplicaciones comparten el mismo modelo de permisos que las APIs de sesiones. +- Se requiere el alcance `UserScope.Sessions`. +- El campo `Sessions` en la configuración del centro de cuentas debe estar habilitado: + - `ReadOnly` o `Edit` para listar concesiones. + - `Edit` para revocar concesiones. + +::: + +**Listar concesiones de aplicaciones activas** + +Para listar las concesiones de aplicaciones activas del usuario actual, usa el endpoint [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants). + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Parámetro de consulta opcional: + +- `appType=firstParty`: Devuelve solo concesiones de aplicaciones de primera parte. +- `appType=thirdParty`: Devuelve solo concesiones de aplicaciones de terceros. +- Omitir `appType`: Devuelve todas las concesiones activas. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**Revocar concesión de aplicación por ID de concesión** + +Para revocar una concesión de aplicación específica, usa el endpoint [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid). + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Cuando se revoca una concesión, los tokens de acceso opacos y los tokens de actualización emitidos previamente para esa concesión se invalidan. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index ef2c87fa6fb..678e882a91b 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -6,7 +6,7 @@ sidebar_position: 2 ## Integraciones \{#integrations} -Logto proporciona varias Management API para gestionar cuentas de usuario. Puedes utilizar estas APIs para construir una página de configuración de cuenta de autoservicio para los usuarios finales. +Logto proporciona varias Management API para gestionar cuentas de usuario. Puedes usar estas API para construir una página de configuración de cuenta de autoservicio para los usuarios finales. ### Arquitectura \{#architecture} @@ -18,9 +18,9 @@ Logto proporciona varias Management API para gestionar cuentas de usuario. Puede ``` 1. **Usuario**: Usuario final autenticado que necesita acceder y gestionar la configuración de su cuenta. -2. **Aplicación cliente**: Tu aplicación cliente que muestra la página de configuración de cuenta al usuario. +2. **Aplicación cliente**: Tu aplicación cliente que sirve la página de configuración de cuenta al usuario. 3. **Aplicación del lado del servidor**: Aplicación del lado del servidor que proporciona la API de configuración de cuenta al cliente. Interactúa con la Management API de Logto. -4. **Logto**: Logto como servicio de autenticación y autorización. Proporciona la Management API para gestionar cuentas de usuario. +4. **Logto**: Logto como el servicio de autenticación y autorización. Proporciona la Management API para gestionar cuentas de usuario. ### Diagrama de secuencia \{#sequence-diagram} @@ -39,7 +39,7 @@ Logto proporciona varias Management API para gestionar cuentas de usuario. Puede Client ->> Logto: POST /oidc/token Logto ->> Client: Token de acceso A Client ->> Server: GET /account-settings (con token de acceso A) - Server ->> Logto: POST /oidc/token (con credenciales de cliente) + Server ->> Logto: POST /oidc/token (con credenciales del cliente) Logto ->> Server: Token de acceso B Server ->> Logto: GET /api/users/{userId} (con token de acceso B) Logto ->> Server: Detalles del usuario @@ -50,90 +50,90 @@ Logto proporciona varias Management API para gestionar cuentas de usuario. Puede 2. La aplicación cliente envía la solicitud de autenticación a Logto y redirige al usuario a la página de inicio de sesión de Logto. 3. El usuario inicia sesión en Logto. 4. El usuario autenticado es redirigido de vuelta a la aplicación cliente con el código de autorización. -5. La aplicación cliente solicita el token de acceso a Logto para acceder a la API de configuración de cuenta autohospedada. +5. La aplicación cliente solicita el token de acceso a Logto para el acceso a la API de configuración de cuenta autohospedada. 6. Logto concede el token de acceso a la aplicación cliente. 7. La aplicación cliente envía la solicitud de configuración de cuenta a la aplicación del lado del servidor con el token de acceso del usuario. -8. La aplicación del lado del servidor verifica la identidad y permisos del solicitante a partir del token de acceso del usuario. Luego solicita un token de acceso a la Management API de Logto. -9. Logto concede el token de acceso a la Management API a la aplicación del lado del servidor. -10. La aplicación del lado del servidor solicita los datos del usuario a Logto usando el token de acceso de la Management API. -11. Logto verifica la identidad del servidor y el permiso de la Management API y devuelve los datos del usuario. -12. La aplicación del lado del servidor procesa los datos del usuario según los permisos del solicitante y devuelve los detalles de la cuenta de usuario a la aplicación cliente. +8. La aplicación del lado del servidor verifica la identidad y el permiso del solicitante a partir del token de acceso del usuario. Luego solicita un token de acceso a Management API de Logto. +9. Logto concede el token de acceso a Management API a la aplicación del lado del servidor. +10. La aplicación del lado del servidor solicita los datos del usuario a Logto usando el token de acceso a Management API. +11. Logto verifica la identidad del servidor y el permiso de Management API y devuelve los datos del usuario. +12. La aplicación del lado del servidor procesa los datos del usuario basándose en el permiso del solicitante y devuelve los detalles de la cuenta del usuario a la aplicación cliente. -### Integrar Management API en la aplicación del lado del servidor \{#integrate-management-api-to-server-side-application} +### Integrar Management API a la aplicación del lado del servidor \{#integrate-management-api-to-server-side-application} -Consulta la sección de [Management API](/integrate-logto/interact-with-management-api/) para aprender cómo integrar las Management APIs con aplicaciones del lado del servidor. +Consulta la sección de [Management API](/integrate-logto/interact-with-management-api/) para aprender cómo integrar las Management API con aplicaciones del lado del servidor. ## APIs de gestión de usuarios \{#user-management-apis} -### Esquema de datos de usuario \{#user-data-schema} +### Esquema de datos del usuario \{#user-data-schema} Consulta la sección de [datos de usuario y datos personalizados](/user-management/user-data/) para aprender más sobre el esquema de usuario en Logto. ### APIs de gestión de perfil e identificadores de usuario \{#user-profile-and-identifiers-management-apis} -El perfil y los identificadores de un usuario son esenciales para la gestión de usuarios. Puedes utilizar las siguientes APIs para gestionar perfiles e identificadores de usuario. +El perfil y los identificadores de un usuario son esenciales para la gestión de usuarios. Puedes usar las siguientes APIs para gestionar perfiles e identificadores de usuario. -| método | path | descripción | -| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Actualizar detalles del usuario. | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Actualizar campos del perfil por ID de usuario. | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obtener datos personalizados por ID de usuario. | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Actualizar datos personalizados por ID de usuario. | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Actualizar el estado de suspensión por ID de usuario. | +| método | ruta | descripción | +| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Actualizar detalles del usuario. | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Actualizar campos del perfil del usuario por ID. | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obtener datos personalizados del usuario por ID. | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Actualizar datos personalizados del usuario por ID. | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Actualizar estado de suspensión del usuario por ID. | ### Verificación de correo electrónico y número de teléfono \{#email-and-phone-number-verification} -En el sistema Logto, tanto las direcciones de correo electrónico como los números de teléfono pueden servir como identificadores de usuario, por lo que su verificación es esencial. Para ello, proporcionamos un conjunto de APIs de código de verificación para ayudar a verificar el correo electrónico o número de teléfono proporcionado. +En el sistema Logto, tanto las direcciones de correo electrónico como los números de teléfono pueden servir como identificadores de usuario, por lo que su verificación es esencial. Para apoyar esto, proporcionamos un conjunto de APIs de código de verificación para ayudar a verificar el correo electrónico o número de teléfono proporcionado. :::note Asegúrate de verificar el correo electrónico o número de teléfono antes de actualizar el perfil del usuario con un nuevo correo electrónico o número de teléfono. ::: -| método | path | descripción | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Enviar código de verificación por correo o teléfono. | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Verificar correo electrónico o teléfono por código. | +| método | ruta | descripción | +| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Enviar código de verificación de correo electrónico o número de teléfono. | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Verificar correo electrónico o número de teléfono mediante código de verificación. | ### Gestión de contraseñas de usuario \{#user-password-management} -| método | path | descripción | -| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Verificar la contraseña actual por ID de usuario. | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Actualizar la contraseña por ID de usuario. | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Comprobar si el usuario tiene contraseña. | +| método | ruta | descripción | +| ------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Verificar la contraseña actual del usuario por ID. | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Actualizar la contraseña del usuario por ID. | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Comprobar si el usuario tiene una contraseña por ID. | :::note -Asegúrate de verificar la contraseña actual del usuario antes de actualizar la contraseña. +Asegúrate de verificar la contraseña actual del usuario antes de actualizar la contraseña del usuario. ::: ### Gestión de identidades sociales de usuario \{#user-social-identities-management} -| método | path | descripción | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. Las identidades sociales se encuentran en el campo `identities`. | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Vincular una identidad social autenticada al usuario por ID. | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Desvincular una identidad social del usuario por ID. | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Actualizar directamente una identidad social vinculada al usuario por ID. | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obtener la URI de autorización para un proveedor de identidad social. Usa esta URI para iniciar una nueva conexión. | +| método | ruta | descripción | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. Las identidades sociales se pueden encontrar en el campo `identities`. | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Vincular una identidad social autenticada al usuario por ID. | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Desvincular una identidad social del usuario por ID. | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Actualizar directamente una identidad social vinculada al usuario por ID. | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obtener el URI de autorización para un proveedor de identidad social. Usa este URI para iniciar una nueva conexión de identidad social. | ```mermaid sequenceDiagram autoNumber participant User as Usuario participant Client as Aplicación cliente - participant App as aplicación servidor + participant App as Aplicación del servidor participant Logto as Logto participant IdP as Proveedor de identidad social - User ->> Client: Solicita vincular identidad social + User ->> Client: Accede a la aplicación cliente y solicita vincular identidad social Client ->> App: Envía solicitud para vincular identidad social App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: URI de autorización App ->> Client: Devuelve URI de autorización Client ->> IdP: Redirige a la página de autorización de IdP User -->> IdP: Inicia sesión en IdP - IdP ->> Client: Redirige a la aplicación cliente con código de autorización + IdP ->> Client: Redirige a la aplicación cliente con el código de autorización Client ->> Server: Solicitud de vinculación de identidad social, reenvía respuesta de autorización de IdP Server ->> Logto: POST /api/users/{userId}/identities Logto ->> IdP: Obtiene información del usuario de IdP usando el código de autorización @@ -142,63 +142,78 @@ sequenceDiagram 1. El usuario accede a la aplicación cliente y solicita vincular una identidad social. 2. La aplicación cliente envía una solicitud al servidor para vincular una identidad social. -3. El servidor envía una solicitud a Logto para obtener la URI de autorización del proveedor de identidad social. Debes proporcionar tu propio parámetro `state` y `redirect_uri` en la solicitud. Asegúrate de registrar el `redirect_uri` en el proveedor de identidad social. -4. Logto devuelve la URI de autorización al servidor. -5. El servidor devuelve la URI de autorización a la aplicación cliente. -6. La aplicación cliente redirige al usuario a la URI de autorización del IdP. -7. El usuario inicia sesión en el IdP. -8. El IdP redirige al usuario de vuelta a la aplicación cliente usando el `redirect_uri` con el código de autorización. -9. La aplicación cliente valida el `state` y reenvía la respuesta de autorización del IdP al servidor. +3. El servidor envía una solicitud a Logto para obtener el URI de autorización para el proveedor de identidad social. Necesitas proporcionar tu propio parámetro `state` y `redirect_uri` en la solicitud. Asegúrate de registrar el `redirect_uri` en el proveedor de identidad social. +4. Logto devuelve el URI de autorización al servidor. +5. El servidor devuelve el URI de autorización a la aplicación cliente. +6. La aplicación cliente redirige al usuario al URI de autorización de IdP. +7. El usuario inicia sesión en IdP. +8. IdP redirige al usuario de vuelta a la aplicación cliente usando el `redirect_uri` con el código de autorización. +9. La aplicación cliente valida el `state` y reenvía la respuesta de autorización de IdP al servidor. 10. El servidor envía una solicitud a Logto para vincular la identidad social al usuario. -11. Logto obtiene la información del usuario del IdP usando el código de autorización. -12. El IdP devuelve la información del usuario a Logto y Logto vincula la identidad social al usuario. +11. Logto obtiene la información del usuario de IdP usando el código de autorización. +12. IdP devuelve la información del usuario a Logto y Logto vincula la identidad social al usuario. :::note Hay algunas limitaciones a considerar al vincular nuevas identidades sociales a un usuario: -- La Management API no tiene contexto de sesión, por lo que cualquier conector social que requiera una sesión activa para mantener de forma segura el estado de autenticación social no puede ser vinculado mediante la Management API. Los conectores no soportados incluyen apple, OIDC estándar y conector OAuth 2.0 estándar. +- Management API no tiene ningún contexto de sesión, cualquier conector social que requiera una sesión activa para mantener de manera segura el estado de autenticación social no puede ser vinculado a través de Management API. Los conectores no soportados incluyen apple, OIDC estándar y conector OAuth 2.0 estándar. - Por la misma razón, Logto no puede verificar el parámetro `state` en la respuesta de autorización. Asegúrate de almacenar el parámetro `state` en tu aplicación cliente y validarlo cuando se reciba la respuesta de autorización. -- Debes registrar el `redirect_uri` en el proveedor de identidad social con antelación. De lo contrario, el IdP social no redirigirá al usuario de vuelta a tu aplicación cliente. Tu IdP social debe aceptar más de un `redirect_uri` de retorno, uno para el inicio de sesión de usuario y otro para tu propia página de vinculación de perfil. +- Necesitas registrar el `redirect_uri` en el proveedor de identidad social con anticipación. De lo contrario, el IdP social no redirigirá al usuario de vuelta a tu aplicación cliente. Tu IdP social debe aceptar más de un `redirect_uri` de callback, uno para el inicio de sesión del usuario, otro para tu propia página de vinculación de perfil. ::: ### Gestión de identidades empresariales de usuario \{#user-enterprise-identities-management} -| método | path | descripción | -| ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. Las identidades empresariales se encuentran en el campo `ssoIdentities`. Añade el parámetro de consulta `includeSsoIdentities=true` para incluirlas. | +| método | ruta | descripción | +| ------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obtener detalles del usuario por ID. Las identidades empresariales se pueden encontrar en el campo `ssoIdentities`. Añade el parámetro de consulta `includeSsoIdentities=true` a la API de detalles del usuario para incluirlas. | -Actualmente, la Management API no admite vincular o desvincular identidades empresariales a un usuario. Solo puedes mostrar las identidades empresariales vinculadas a un usuario. +Actualmente, Management API no admite vincular o desvincular identidades empresariales a un usuario. Solo puedes mostrar las identidades empresariales vinculadas a un usuario. ### Token de acceso personal \{#personal-access-token} -| método | path | descripción | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obtener todos los tokens de acceso personal del usuario. | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Añadir un nuevo token de acceso personal para el usuario. | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Eliminar un token del usuario por nombre. | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Actualizar un token del usuario por nombre. | +| método | ruta | descripción | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obtener todos los tokens de acceso personal para el usuario. | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Añadir un nuevo token de acceso personal para el usuario. | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Eliminar un token para el usuario por nombre. | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Actualizar un token para el usuario por nombre. | -Los tokens de acceso personal proporcionan una forma segura para que los usuarios otorguen [token de acceso (Access token)](https://auth.wiki/access-token) sin usar sus credenciales ni inicio de sesión interactivo. Aprende más sobre [cómo usar tokens de acceso personal](/user-management/personal-access-token). +Los tokens de acceso personal proporcionan una forma segura para que los usuarios otorguen [token de acceso (Access token)](https://auth.wiki/access-token) sin usar sus credenciales e inicio de sesión interactivo. Aprende más sobre [usar tokens de acceso personal](/user-management/personal-access-token). -### Gestión de configuración MFA de usuario \{#user-mfa-settings-management} +### Gestión de configuraciones de MFA de usuario \{#user-mfa-settings-management} -| método | path | descripción | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obtener configuración MFA del usuario por ID. | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurar una verificación MFA por ID. | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Eliminar una verificación MFA por ID. | +| método | ruta | descripción | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obtener configuraciones de MFA del usuario por ID. | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurar una verificación de MFA para el usuario por ID. | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Eliminar una verificación de MFA del usuario por ID. | ### Eliminación de cuenta de usuario \{#user-account-deletion} -| método | path | descripción | +| método | ruta | descripción | | ------ | -------------------------------------------------------------------------------- | --------------------------- | | DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Eliminar un usuario por ID. | ### Gestión de sesiones de usuario \{#user-session-management} -| método | path | descripción | -| ------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obtener sesiones de usuario por ID. | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obtener una sesión de usuario por ID. | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Eliminar una sesión de usuario por ID. | +| método | ruta | descripción | +| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obtener sesiones de usuario por ID. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obtener una sesión de usuario por ID de sesión. | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Eliminar una sesión de usuario por ID de sesión. | + +### Gestionar aplicaciones autorizadas por el usuario (concesiones) \{#manage-user-authorized-apps-grants} + +| método | ruta | descripción | +| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | Listar concesiones de aplicaciones activas para el usuario. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | Revocar una concesión de aplicación específica por ID. | + +Parámetro de consulta opcional para la lista de concesiones: + +- `appType=firstParty`: Devuelve solo concesiones de aplicaciones de primera parte. +- `appType=thirdParty`: Devuelve solo concesiones de aplicaciones de terceros. +- Omitir `appType`: Devuelve todas las concesiones activas. + +Cuando se revoca una concesión, los tokens de acceso opacos y los tokens de actualización previamente emitidos para esa concesión se invalidan. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index 7157a4f67ce..a62cff14f41 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,168 +1,28 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # Cierre de sesión -El cierre de sesión en Logto (como proveedor de identidad OIDC) implica tanto: +El cierre de sesión en Logto involucra dos capas: -- Una **sesión centralizada de Logto** (cookie del navegador bajo el dominio de Logto), y -- **Estado de autenticación distribuido en el lado del cliente** (tokens y sesión local de la app en cada aplicación). +- **Cierre de sesión de la sesión de Logto**: Termina la sesión de inicio de sesión centralizada bajo el dominio de Logto. +- **Cierre de sesión de la aplicación**: Borra el estado de la sesión local y los tokens en tu aplicación cliente. -Para entender el comportamiento del cierre de sesión, ayuda separar estas dos capas y luego ver cómo los **grants** las conectan. - -## Conceptos clave \{#core-concepts} - -### ¿Qué es una sesión de Logto? \{#what-is-a-logto-session} - -Una sesión de Logto es el estado centralizado de inicio de sesión gestionado por Logto. Se crea tras una autenticación exitosa y está representada por cookies bajo el dominio de Logto. - -Si la cookie de sesión es válida, el usuario puede ser autenticado silenciosamente (SSO) en varias aplicaciones que confían en el mismo tenant de Logto. - -Si no existe una sesión válida, Logto muestra la página de inicio de sesión. - -### ¿Qué son los grants? \{#what-are-grants} - -Un **grant** representa el estado de autorización para una combinación específica de usuario + aplicación cliente. - -- Una sesión de Logto puede tener grants para varias aplicaciones cliente. -- Un grant es con lo que se asocian los tokens emitidos. -- En este conjunto de documentación, se usa **grant** como la unidad de autorización entre aplicaciones. - -### Cómo se relacionan la sesión, los grants y el estado de autenticación del cliente \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Dominio Logto] - S[Sesión de Logto] - G1[Grant para App A] - G2[Grant para App B] - end - - subgraph AppA [Dominio cliente A] - A[Sessión local / tokens] - end - - subgraph AppB [Dominio cliente B] - B[Sessión local / tokens] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Sesión de Logto** controla la experiencia centralizada de SSO. -- **Sesión local / tokens del cliente** controlan si cada app considera actualmente al usuario como autenticado. -- **Grants** conectan estos dos mundos representando el estado de autorización específico de la app. - -## Resumen del inicio de sesión (por qué el cierre de sesión es multinivel) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as Aplicación cliente - end - - box Logto (IdP) - participant OIDC as Proveedor OIDC - participant SignIn as Página de inicio de sesión - end - - User ->> Client: Accede a la aplicación - Client ->> OIDC: Redirige para autenticación - OIDC -->> OIDC: Verifica sesión de Logto - OIDC ->> SignIn: Solicita inicio de sesión si es necesario - SignIn ->> OIDC: El usuario se autentica - OIDC -->> OIDC: Crea sesión y grant - OIDC ->> Client: Devuelve código de autorización - Client ->> OIDC: Intercambia código por tokens - OIDC -->> Client: Devuelve tokens -``` - -## Topología de sesión entre apps / dispositivos \{#session-topology-across-apps-devices} - -### Cookie de sesión compartida (mismo navegador / agente de usuario) \{#shared-session-cookie-same-browser-user-agent} - -Si un usuario inicia sesión en varias apps desde el mismo navegador, esas apps pueden reutilizar la misma cookie de sesión de Logto y se aplica el comportamiento SSO. - -```mermaid -flowchart TD - U[Usuario] - A["Aplicación cliente A (Dominio cliente A)"] - B["Aplicación cliente B (Dominio cliente B)"] - C{"¿Existe sesión de Logto? (Dominio Logto)"} - D["Página de inicio de sesión (Dominio Logto)"] - - subgraph UA["Agente de usuario A (mismo navegador)"] - U - A - B - C - D - end - - U -->|Iniciar sesión| A - A -->|Redirige a Logto| C - U -->|Abrir app| B - B -->|Redirige a Logto| C - C -->|No| D - D -->|Crear sesión| C -``` - -### Cookies de sesión aisladas (diferentes dispositivos / navegadores) \{#isolated-session-cookies-different-devices-browsers} - -Diferentes navegadores / dispositivos mantienen diferentes cookies de Logto, por lo que el estado de la sesión de inicio de sesión está aislado. - -```mermaid -flowchart TD - U[Usuario] - A["Aplicación cliente A (Dominio cliente A)"] - C{"¿Existe sesión de Logto? (Dispositivo A, Dominio Logto)"} - D["Página de inicio de sesión (Dispositivo A, Dominio Logto)"] - - subgraph DeviceA["Agente de usuario A"] - A - C - D - end - - B["Aplicación cliente B (Dominio cliente B)"] - E{"¿Existe sesión de Logto? (Dispositivo B, Dominio Logto)"} - F["Página de inicio de sesión (Dispositivo B, Dominio Logto)"] - - subgraph DeviceB["Agente de usuario B"] - B - E - F - end - - U -->|Iniciar sesión| A - A -->|Redirige a Logto| C - U -->|Iniciar sesión| B - B -->|Redirige a Logto| E - C -->|No| D - E -->|No| F - D -->|Crear sesión| C - F -->|Crear sesión| E -``` +Para comprender mejor cómo funcionan las sesiones en Logto, consulta [Sesiones](/sessions). ## Mecanismos de cierre de sesión \{#sign-out-mechanisms} -### 1) Cierre de sesión solo en el lado del cliente \{#1-client-side-only-sign-out} +### 1) Cierre de sesión solo del lado del cliente \{#1-client-side-only-sign-out} -La aplicación cliente borra su propia sesión local y tokens (tokens de ID / acceso / actualización). Esto cierra la sesión del usuario solo en el estado local de esa app. +La aplicación cliente borra su propia sesión local y tokens (Tokens de ID / Tokens de acceso / Tokens de actualización). Esto cierra la sesión del usuario solo del estado local de esa aplicación. - La sesión de Logto puede seguir activa. -- Otras apps bajo la misma sesión de Logto pueden seguir usando SSO. +- Otras aplicaciones bajo la misma sesión de Logto pueden seguir usando SSO. -### 2) Fin de sesión en Logto (cierre de sesión global en la implementación actual de Logto) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +### 2) Terminar sesión en Logto (cierre de sesión global en la implementación actual de Logto) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -Para borrar la sesión centralizada de Logto, la app redirige al usuario al endpoint de fin de sesión, por ejemplo: +Para borrar la sesión centralizada de Logto, la aplicación redirige al usuario al endpoint de fin de sesión, por ejemplo: `https://{your-logto-domain}/oidc/session/end` @@ -170,64 +30,70 @@ En el comportamiento actual del SDK de Logto: 1. `signOut()` redirige a `/session/end`. 2. Luego va a `/session/end/confirm`. -3. El formulario de confirmación por defecto envía automáticamente `logout=true`. +3. El formulario de confirmación predeterminado auto-envía `logout=true`. + +Como resultado, el cierre de sesión actual del SDK se trata como un **cierre de sesión global**. -Como resultado, el cierre de sesión del SDK actual se trata como **cierre de sesión global**. +:::note + +- **Cierre de sesión global**: Revoca la sesión centralizada de Logto. + +::: ### Qué sucede durante el cierre de sesión global \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["La app inicia cierre de sesión"] --> B["/session/end"] + A["El cliente inicia el cierre de sesión"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["Revoca sesión centralizada de Logto"] - D --> E{"Verifica grant por app"} - E -->|"offline_access no concedido"| F["Revoca grant"] - E -->|"offline_access concedido"| G["Mantiene grant hasta que expire TTL"] + C --> D["Revocar sesión centralizada de Logto"] + D --> E{"Verificar concesión por aplicación"} + E -->|"offline_access no concedido"| F["Revocar concesión"] + E -->|"offline_access concedido"| G["Mantener concesión hasta que expire el TTL de la concesión"] ``` Durante el cierre de sesión global: -- Se revoca la sesión centralizada de Logto. -- Los grants relacionados se gestionan según el estado de autorización de cada app: - - Si `offline_access` **no** está concedido, los grants relacionados se revocan. - - Si `offline_access` **está** concedido, los grants no se revocan por el fin de sesión. -- Para los casos de `offline_access`, los tokens de actualización y grants siguen siendo válidos hasta que expire el grant. +- La sesión centralizada de Logto es revocada. +- Las concesiones de aplicaciones relacionadas se manejan según el estado de autorización de cada aplicación: + - Si `offline_access` **no** está concedido, las concesiones relacionadas son revocadas. + - Si `offline_access` **está** concedido, las concesiones no son revocadas por el fin de sesión. +- Para los casos de `offline_access`, los tokens de actualización y las concesiones permanecen válidos hasta la expiración de la concesión. -## Duración del grant e impacto de `offline_access` \{#grant-lifetime-and-offline-access-impact} +## Duración de la concesión e impacto de `offline_access` \{#grant-lifetime-and-offline-access-impact} -- El TTL por defecto de un grant de Logto es **180 días**. -- Si se concede `offline_access`, el fin de sesión no revoca ese grant de la app por defecto. -- La cadena de tokens de actualización asociada a ese grant puede continuar hasta que el grant expire (o se revoque explícitamente). +- El TTL de concesión predeterminado de Logto es de **180 días**. +- Si `offline_access` está concedido, el fin de sesión no revoca esa concesión de aplicación por defecto. +- La cadena de tokens de actualización asociada con esa concesión puede continuar hasta que la concesión expire (o sea revocada explícitamente). -## Cierre de sesión federado: cierre de sesión back-channel \{#federated-sign-out-back-channel-logout} +## Cierre de sesión federado: cierre de sesión por canal secundario \{#federated-sign-out-back-channel-logout} -Para la coherencia entre apps, Logto admite el [cierre de sesión back-channel](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). +Para la consistencia entre aplicaciones, Logto admite [cierre de sesión por canal secundario](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). -Cuando un usuario cierra sesión en una app, Logto puede notificar a todas las apps que participan en la misma sesión enviando un token de cierre de sesión al URI de cierre de sesión back-channel registrado de cada app. +Cuando un usuario cierra sesión desde una aplicación, Logto puede notificar a todas las aplicaciones que participan en la misma sesión enviando un token de cierre de sesión a la URI de cierre de sesión por canal secundario registrada de cada aplicación. -Si `Is session required` está habilitado en la configuración back-channel de la app, el token de cierre de sesión incluye `sid` para identificar la sesión de Logto. +Si `Is session required` está habilitado en la configuración de canal secundario de la aplicación, el token de cierre de sesión incluye `sid` para identificar la sesión de Logto. Flujo típico: -1. El usuario inicia el cierre de sesión desde una app. -2. Logto procesa el fin de sesión y envía el/los token(s) de cierre de sesión a los URI(s) de cierre de sesión back-channel registrados. -3. Cada app valida el token de cierre de sesión y borra su propia sesión local / tokens. +1. El usuario inicia el cierre de sesión desde una aplicación. +2. Logto procesa el fin de sesión y envía token(es) de cierre de sesión a la(s) URI(s) de cierre de sesión por canal secundario registrada(s). +3. Cada aplicación valida el token de cierre de sesión y borra su propia sesión local / tokens. ## Métodos de cierre de sesión en los SDKs de Logto \{#sign-out-methods-in-logto-sdks} -- **SPA y web**: `client.signOut()` borra el almacenamiento local de tokens y redirige al endpoint de fin de sesión de Logto. Puedes proporcionar un URI de redirección post-logout. -- **Nativo (incluyendo React Native / Flutter)**: normalmente solo borra el almacenamiento local de tokens. El webview sin sesión significa que no hay cookie persistente de Logto en el navegador que borrar. +- **SPA y web**: `client.signOut()` borra el almacenamiento local de tokens y redirige al endpoint de fin de sesión de Logto. Puedes proporcionar una URI de redirección posterior al cierre de sesión. +- **Nativo (incluyendo React Native / Flutter)**: generalmente borra solo el almacenamiento local de tokens. La vista web sin sesión significa que no hay cookie persistente del navegador de Logto para borrar. :::note -Para aplicaciones nativas que no admiten webview sin sesión o no reconocen la configuración `emphasized` (app de Android usando el SDK de **React Native** o **Flutter**), puedes forzar que se solicite al usuario iniciar sesión de nuevo pasando el parámetro `prompt=login` en la solicitud de autorización. +Para aplicaciones nativas que no admiten vista web sin sesión o no reconocen la configuración `emphasized` (aplicación Android usando el SDK de **React Native** o **Flutter**), puedes forzar al usuario a iniciar sesión nuevamente pasando el parámetro `prompt=login` en la solicitud de autorización. ::: -## Forzar la re-autenticación en cada acceso \{#enforce-re-authentication-on-every-access} +## Forzar re-autenticación en cada acceso \{#enforce-re-authentication-on-every-access} -Para acciones de alta seguridad, incluye `prompt=login` en las solicitudes de autenticación para omitir el SSO y forzar la introducción de credenciales cada vez. +Para acciones de alta seguridad, incluye `prompt=login` en las solicitudes de autenticación para omitir SSO y forzar la entrada de credenciales cada vez. -Si solicitas `offline_access` (para recibir tokens de actualización), incluye también `consent`, `prompt=login consent`. +Si solicitas `offline_access` (para recibir tokens de actualización), también incluye `consent`, `prompt=login consent`. Configuración combinada típica: @@ -240,17 +106,17 @@ prompt=login consent
-### No recibo las notificaciones de cierre de sesión back-channel. \{#im-not-receiving-the-back-channel-logout-notifications} +### No estoy recibiendo las notificaciones de cierre de sesión por canal secundario. \{#im-not-receiving-the-back-channel-logout-notifications} -- Asegúrate de que el URI de cierre de sesión back-channel esté correctamente registrado en el panel de Logto. -- Asegúrate de que tu app tenga un estado de inicio de sesión activo para el mismo usuario / contexto de sesión. +- Asegúrate de que la URI de cierre de sesión por canal secundario esté correctamente registrada en el panel de Logto. +- Asegúrate de que tu aplicación tenga un estado de inicio de sesión activo para el mismo contexto de usuario / sesión.
## Recursos relacionados \{#related-resources} - Entendiendo el cierre de sesión back-channel de OIDC. + Comprendiendo el cierre de sesión por canal secundario de OIDC. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/es/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 422454a1163..6c6b0b818f0 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: Consulta los parámetros clave de la aplicación para la integración de autenticación OIDC, incluyendo URIs de redirección, endpoints, tokens de actualización, cierre de sesión por canal secundario, etc. +description: Consulta los parámetros clave de la aplicación para la integración de autenticación OIDC, incluidos los URIs de redirección, endpoints, tokens de actualización, cierre de sesión por canal secundario, etc. sidebar_position: 6 --- @@ -7,42 +7,42 @@ sidebar_position: 6 ## Introducción \{#introduction} -En Logto, una _aplicación_ se refiere a un programa o servicio de software específico que está registrado en la plataforma Logto y ha recibido autorización para acceder a la información del usuario o realizar acciones en nombre de un usuario. Las aplicaciones se utilizan para identificar la fuente de las solicitudes realizadas a la API de Logto, así como para gestionar el proceso de autenticación y autorización para los usuarios que acceden a esas aplicaciones. +En Logto, una _aplicación_ se refiere a un programa de software o servicio específico que está registrado en la plataforma Logto y ha sido autorizado para acceder a información del usuario o realizar acciones en nombre de un usuario. Las aplicaciones se utilizan para identificar la fuente de las solicitudes realizadas a la API de Logto, así como para gestionar el proceso de autenticación y Autorización (Authorization) para los usuarios que acceden a esas aplicaciones. -El uso de aplicaciones en la experiencia de inicio de sesión de Logto permite a los usuarios acceder y gestionar fácilmente sus aplicaciones autorizadas desde una sola ubicación, con un proceso de autenticación coherente y seguro. Esto ayuda a simplificar la experiencia del usuario y garantiza que solo las personas autorizadas accedan a información sensible o realicen acciones en nombre de la organización. +El uso de aplicaciones en la experiencia de inicio de sesión de Logto permite a los usuarios acceder y gestionar fácilmente sus aplicaciones autorizadas desde un único lugar, con un proceso de autenticación coherente y seguro. Esto ayuda a simplificar la experiencia del usuario y garantiza que solo las personas autorizadas accedan a información sensible o realicen acciones en nombre de la organización. -Las aplicaciones también se utilizan en los registros de auditoría de Logto para rastrear la actividad del usuario e identificar posibles amenazas o brechas de seguridad. Al asociar acciones específicas con una aplicación en particular, Logto puede proporcionar información detallada sobre cómo se accede y utiliza la información, permitiendo a las organizaciones gestionar mejor sus requisitos de seguridad y cumplimiento. +Las aplicaciones también se utilizan en los registros de auditoría de Logto para rastrear la actividad del usuario e identificar cualquier posible amenaza o violación de seguridad. Al asociar acciones específicas con una aplicación en particular, Logto puede proporcionar información detallada sobre cómo se está accediendo y utilizando los datos, lo que permite a las organizaciones gestionar mejor sus requisitos de seguridad y cumplimiento. Si deseas integrar tu aplicación con Logto, consulta [Integrar Logto](/integrate-logto). ## Propiedades \{#properties} ### ID de la aplicación \{#application-id} -_Application ID_ es una clave única autogenerada para identificar tu aplicación en Logto, y se referencia como [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) en OAuth 2.0. +El _ID de la aplicación_ es una clave única generada automáticamente para identificar tu aplicación en Logto, y se referencia como [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) en OAuth 2.0. ### Tipos de aplicación \{#application-types} -Una _aplicación_ puede ser uno de los siguientes tipos de aplicación: +Una _Aplicación_ puede ser uno de los siguientes tipos de aplicación: -- **Aplicación nativa** es una aplicación que se ejecuta en un entorno nativo. Ejemplo: aplicación iOS, aplicación Android. - - **Aplicación de flujo de dispositivo** es un tipo especial de aplicación nativa para dispositivos con entrada limitada o aplicaciones sin interfaz gráfica (por ejemplo, televisores inteligentes, consolas de juegos, herramientas CLI, dispositivos IoT). Utiliza el [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) en lugar del flujo estándar basado en redirección. Consulta [Inicio rápido de flujo de dispositivo](/quick-starts/device-flow) para más detalles. -- **Aplicación de una sola página (SPA)** es una aplicación que se ejecuta en un navegador web, que actualiza la página con nuevos datos del servidor sin cargar páginas completas nuevas. Ejemplo: aplicación React DOM, aplicación Vue. -- **Aplicación web tradicional** es una aplicación que renderiza y actualiza páginas únicamente por el servidor web. Ejemplo: JSP, PHP. -- **Aplicación máquina a máquina (M2M)** es una aplicación que se ejecuta en un entorno de máquina para la comunicación directa entre servicios sin interacción del usuario. +- **Aplicación nativa** es una aplicación que se ejecuta en un entorno nativo. Por ejemplo, aplicación iOS, aplicación Android. + - **Aplicación de flujo de dispositivo** es un tipo especial de aplicación nativa para dispositivos con entrada limitada o aplicaciones sin interfaz (por ejemplo, televisores inteligentes, consolas de juegos, herramientas CLI, dispositivos IoT). Utiliza el [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) en lugar del flujo estándar basado en redirección. Consulta [Inicio rápido del flujo de dispositivo](/quick-starts/device-flow) para más detalles. +- **Aplicación de una sola página** es una aplicación que se ejecuta en un navegador web, que actualiza la página con los nuevos datos del servidor sin cargar páginas completas nuevas. Por ejemplo, aplicación React DOM, aplicación Vue. +- **Aplicación web tradicional** es una aplicación que renderiza y actualiza páginas solo por el servidor web. Por ejemplo, JSP, PHP. +- **Aplicación máquina a máquina (M2M)** es una aplicación que se ejecuta en un entorno de máquina para comunicación directa de servicio a servicio sin interacción del usuario. ### Secreto de la aplicación \{#application-secret} -_Application secret_ es una clave utilizada para autenticar la aplicación en el sistema de autenticación, específicamente para clientes privados (aplicaciones web tradicionales y M2M) como una barrera de seguridad privada. +El _secreto de la aplicación_ es una clave utilizada para autenticar la aplicación en el sistema de autenticación, específicamente para clientes privados (aplicaciones web tradicionales y M2M) como una barrera de seguridad privada. :::tip -Las aplicaciones de una sola página (SPA) y las aplicaciones nativas no proporcionan secreto de aplicación. Las SPA y las aplicaciones nativas son "clientes públicos" y no pueden mantener secretos (el código del navegador o los paquetes de la aplicación son inspeccionables). En lugar de un secreto de aplicación, Logto las protege con PKCE, validación estricta de URI de redirección / CORS, tokens de acceso de corta duración y rotación de tokens de actualización. +Las aplicaciones de una sola página (SPAs) y las aplicaciones nativas no proporcionan un secreto de aplicación. Las SPAs y las aplicaciones nativas son "clientes públicos" y no pueden mantener secretos (el código del navegador o los paquetes de aplicaciones son inspeccionables). En lugar de un secreto de aplicación, Logto las protege con PKCE, validación estricta de URI de redirección / CORS, tokens de acceso de corta duración y rotación de tokens de actualización. ::: ### Nombre de la aplicación \{#application-name} -_Application name_ es el nombre legible por humanos de la aplicación y se mostrará en la consola de administración. +El _nombre de la aplicación_ es un nombre legible por humanos de la aplicación y se mostrará en la consola de administración. -El _nombre de la aplicación_ es un componente importante para la gestión de aplicaciones en Logto, ya que permite a los administradores identificar y rastrear fácilmente la actividad de aplicaciones individuales dentro de la plataforma. +El _nombre de la aplicación_ es un componente importante para gestionar aplicaciones en Logto, ya que permite a los administradores identificar y rastrear fácilmente la actividad de aplicaciones individuales dentro de la plataforma. :::note Es importante tener en cuenta que el _nombre de la aplicación_ debe elegirse cuidadosamente, ya que será visible para todos los usuarios que tengan acceso a la consola de administración. Debe reflejar con precisión el propósito y la función de la aplicación, además de ser fácil de entender y reconocer. @@ -54,91 +54,92 @@ Una breve descripción de la aplicación se mostrará en la página de detalles ### URIs de redirección \{#redirect-uris} -_Redirect URIs_ son una lista de URIs de redirección válidas que se han preconfigurado para una aplicación. Cuando un usuario inicia sesión en Logto e intenta acceder a la aplicación, se le redirige a uno de los URIs permitidos especificados en la configuración de la aplicación. +Los _URIs de redirección_ son una lista de URIs de redirección válidos que han sido preconfigurados para una aplicación. Cuando un usuario inicia sesión en Logto e intenta acceder a la aplicación, se le redirige a uno de los URIs permitidos especificados en la configuración de la aplicación. -La lista de URIs permitidas se utiliza para validar el URI de redirección que se incluye en la solicitud de autorización enviada por la aplicación a Logto durante el proceso de autenticación. Si el URI de redirección especificado en la solicitud de autorización coincide con uno de los URIs permitidos en la configuración de la aplicación, el usuario será redirigido a ese URI después de una autenticación exitosa. Si el URI de redirección no está en la lista permitida, el usuario no será redirigido y el proceso de autenticación fallará. +La lista de URIs permitidos se utiliza para validar el URI de redirección que se incluye en la solicitud de Autorización (Authorization) enviada por la aplicación a Logto durante el proceso de autenticación. Si el URI de redirección especificado en la solicitud de Autorización (Authorization) coincide con uno de los URIs permitidos en la configuración de la aplicación, el usuario es redirigido a ese URI después de una autenticación exitosa. Si el URI de redirección no está en la lista permitida, el usuario no será redirigido y el proceso de autenticación fallará. :::note -Es importante asegurarse de que todos los URIs de redirección válidos se agreguen a la lista permitida para una aplicación en Logto, para garantizar que los usuarios puedan acceder correctamente a la aplicación después de la autenticación. +Es importante asegurarse de que todos los URIs de redirección válidos se agreguen a la lista permitida para una aplicación en Logto, para garantizar que los usuarios puedan acceder exitosamente a la aplicación después de la autenticación. ::: -Puedes consultar el [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) para más información. +Puedes consultar el [Endpoint de redirección](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) para más información. - Entendiendo los URIs de redirección en OIDC con Authorization Code Flow + Comprendiendo los URIs de redirección en OIDC con el flujo de código de Autorización + (Authorization) -#### Patrones comodín \{#wildcard-patterns} +#### Patrones de comodín \{#wildcard-patterns} -_Disponibilidad: Aplicación de una sola página, aplicación web tradicional_ +_Disponibilidad: Aplicación de una sola página, Aplicación web tradicional_ -Los URIs de redirección admiten patrones comodín (`*`) para entornos dinámicos como despliegues de vista previa. Los comodines pueden usarse en los componentes de nombre de host y ruta de los URIs HTTP/HTTPS. +Los URIs de redirección admiten patrones de comodín (`*`) para entornos dinámicos como implementaciones de vista previa. Los comodines se pueden usar en los componentes de nombre de host y ruta de los URIs HTTP/HTTPS. **Reglas:** - Los comodines solo están permitidos en el nombre de host y la ruta -- Los comodines no están permitidos en el esquema, puerto, parámetros de consulta o fragmentos hash +- Los comodines no están permitidos en el esquema, puerto, parámetros de consulta o fragmentos de hash - Los comodines en el nombre de host deben incluir al menos un punto (por ejemplo, `https://*.example.com/callback`) **Ejemplos:** - `https://*.example.com/callback` - coincide con cualquier subdominio -- `https://preview-*.example.com/callback` - coincide con despliegues de vista previa +- `https://preview-*.example.com/callback` - coincide con implementaciones de vista previa - `https://example.com/*/callback` - coincide con cualquier segmento de ruta :::caution -Los URIs de redirección comodín no son estándar OIDC y pueden aumentar la superficie de ataque. Úsalos con precaución y prefiere URIs de redirección exactos siempre que sea posible. +Los URIs de redirección con comodines no son estándar en OIDC y pueden aumentar la superficie de ataque. Úsalos con cuidado y prefiere URIs de redirección exactos siempre que sea posible. ::: -### URIs de redirección post cierre de sesión \{#post-sign-out-redirect-uris} +### URIs de redirección después del cierre de sesión \{#post-sign-out-redirect-uris} -_Post sign-out redirect URIs_ son una lista de URIs válidas que se han preconfigurado para una aplicación para redirigir al usuario después de que haya cerrado sesión en Logto. +Los _URIs de redirección después del cierre de sesión_ son una lista de URIs válidos que han sido preconfigurados para una aplicación para redirigir al usuario después de que haya cerrado sesión en Logto. -El uso de _Post Sign-out Redirect URIs_ permitidos para el cierre de sesión forma parte de la especificación de Logout iniciado por la parte confiable (RP-Initiated Logout) en OIDC. Esta especificación proporciona un método estandarizado para que las aplicaciones inicien una solicitud de cierre de sesión para un usuario, lo que incluye redirigir al usuario a un endpoint preconfigurado después de que haya cerrado sesión. +El uso de _URIs de redirección permitidos después del cierre de sesión_ para el cierre de sesión es parte de la especificación de cierre de sesión iniciado por RP (Relying Party) en OIDC. Esta especificación proporciona un método estandarizado para que las aplicaciones inicien una solicitud de cierre de sesión para un usuario, que incluye redirigir al usuario a un endpoint preconfigurado después de que haya cerrado sesión. -Cuando un usuario cierra sesión en Logto, su sesión se termina y se le redirige a uno de los URIs permitidos especificados en la configuración de la aplicación. Esto garantiza que el usuario solo sea dirigido a endpoints autorizados y válidos después de cerrar sesión, ayudando a prevenir accesos no autorizados y riesgos de seguridad asociados con redirigir usuarios a endpoints desconocidos o no verificados. +Cuando un usuario cierra sesión en Logto, su sesión se termina y se le redirige a uno de los URIs permitidos especificados en la configuración de la aplicación. Esto asegura que el usuario sea dirigido solo a endpoints autorizados y válidos después de haber cerrado sesión, ayudando a prevenir el acceso no autorizado y los riesgos de seguridad asociados con redirigir a los usuarios a endpoints desconocidos o no verificados. -Puedes consultar el [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) para más información. +Puedes consultar el [cierre de sesión iniciado por RP](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) para más información. -### Orígenes permitidos CORS \{#cors-allowed-origins} +### Orígenes permitidos por CORS \{#cors-allowed-origins} -_Los orígenes permitidos de CORS (Cross-origin resource sharing)_ son una lista de orígenes permitidos desde los cuales una aplicación puede realizar solicitudes al servicio Logto. Cualquier origen que no esté incluido en la lista permitida no podrá realizar solicitudes al servicio Logto. +Los _orígenes permitidos por CORS (Cross-origin resource sharing)_ son una lista de orígenes permitidos desde los cuales una aplicación puede realizar solicitudes al servicio Logto. Cualquier origen que no esté incluido en la lista permitida no podrá realizar solicitudes al servicio Logto. -La lista de orígenes permitidos de CORS se utiliza para restringir el acceso al servicio Logto desde dominios no autorizados y para ayudar a prevenir ataques de falsificación de solicitudes entre sitios (CSRF). Al especificar los orígenes permitidos para una aplicación en Logto, el servicio puede garantizar que solo los dominios autorizados puedan realizar solicitudes al servicio. +La lista de orígenes permitidos por CORS se utiliza para restringir el acceso al servicio Logto desde dominios no autorizados y para ayudar a prevenir ataques de falsificación de solicitudes entre sitios (CSRF). Al especificar los orígenes permitidos para una aplicación en Logto, el servicio puede garantizar que solo los dominios autorizados puedan realizar solicitudes al servicio. :::note -La lista de orígenes permitidos debe contener el origen donde se servirá la aplicación. Esto garantiza que las solicitudes de la aplicación estén permitidas, mientras que las solicitudes de orígenes no autorizados serán bloqueadas. +La lista de orígenes permitidos debe contener el origen donde se servirá la aplicación. Esto asegura que las solicitudes de la aplicación sean permitidas, mientras que las solicitudes de orígenes no autorizados sean bloqueadas. ::: ### Endpoint de configuración del proveedor OpenID \{#openid-provider-configuration-endpoint} El endpoint para [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). -### Endpoint de autorización \{#authorization-endpoint} +### Endpoint de Autorización (Authorization) \{#authorization-endpoint} -_Authorization Endpoint_ es un término de OIDC, y es un endpoint requerido que se utiliza para iniciar el proceso de autenticación de un usuario. Cuando un usuario intenta acceder a un recurso protegido o una aplicación que ha sido registrada en la plataforma Logto, será redirigido al _Authorization Endpoint_ para autenticar su identidad y obtener autorización para acceder al recurso solicitado. +El _Endpoint de Autorización (Authorization)_ es un término de OIDC, y es un endpoint requerido que se utiliza para iniciar el proceso de autenticación para un usuario. Cuando un usuario intenta acceder a un recurso o aplicación protegida que ha sido registrada en la plataforma Logto, será redirigido al _Endpoint de Autorización (Authorization)_ para autenticar su identidad y obtener Autorización (Authorization) para acceder al recurso solicitado. -Puedes consultar el [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) para más información. +Puedes consultar el [Endpoint de Autorización (Authorization)](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) para más información. ### Endpoint de token \{#token-endpoint} -_Token Endpoint_ es un término de OIDC, es un endpoint de API web que es utilizado por un cliente OIDC para obtener un token de acceso, un token de ID o un token de actualización de un proveedor OIDC. +El _Endpoint de token_ es un término de OIDC, es un endpoint de API web que se utiliza por un cliente OIDC para obtener un token de acceso, un Token de ID (ID token) o un token de actualización de un proveedor OIDC. -Cuando un cliente OIDC necesita obtener un token de acceso o un token de ID, envía una solicitud al Token Endpoint con una concesión de autorización, que normalmente es un código de autorización o un token de actualización. El Token Endpoint valida la concesión de autorización y emite un token de acceso o un token de ID al cliente si la concesión es válida. +Cuando un cliente OIDC necesita obtener un token de acceso o un Token de ID (ID token), envía una solicitud al Endpoint de token con un permiso de Autorización (Authorization), que generalmente es un código de Autorización (Authorization) o un token de actualización. El Endpoint de token luego valida el permiso de Autorización (Authorization) y emite un token de acceso o un Token de ID (ID token) al cliente si el permiso es válido. -Puedes consultar el [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) para más información. +Puedes consultar el [Endpoint de token](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) para más información. -### Endpoint de Userinfo \{#userinfo-endpoint} +### Endpoint de información del usuario \{#userinfo-endpoint} -El endpoint [UserInfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) de OpenID Connect. +El [Endpoint de información del usuario](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) de OpenID Connect. ### Emitir siempre token de actualización \{#always-issue-refresh-token} _Disponibilidad: Web tradicional, SPA_ -Cuando está habilitado, Logto siempre emitirá tokens de actualización, independientemente de si `prompt=consent` está presente en la solicitud de autenticación, o si `offline_access` está presente en los alcances. +Cuando está habilitado, Logto siempre emitirá tokens de actualización, independientemente de si `prompt=consent` se presenta en la solicitud de autenticación, ni `offline_access` se presenta en los Alcances (Scopes). -Sin embargo, esta práctica no se recomienda a menos que sea necesario (normalmente es útil para algunas integraciones OAuth de terceros que requieren token de actualización), ya que no es compatible con OpenID Connect y puede causar problemas potenciales. +Sin embargo, esta práctica no se recomienda a menos que sea necesario (generalmente es útil para algunas integraciones de OAuth de terceros que requieren token de actualización), ya que no es compatible con OpenID Connect y puede causar problemas potencialmente. ### Rotar token de actualización \{#rotate-refresh-token} @@ -147,16 +148,16 @@ _Predeterminado: `true`_ Cuando está habilitado, Logto emitirá un nuevo token de actualización para solicitudes de token bajo las siguientes condiciones: - Si el token de actualización ha sido rotado (se ha prolongado su TTL emitiendo uno nuevo) durante un año; **O** -- Si el token de actualización está cerca de su tiempo de expiración (>=70% de su Tiempo de Vida (TTL) original transcurrido); **O** +- Si el token de actualización está cerca de su tiempo de expiración (>=70% de su Tiempo de Vida (TTL) original ha pasado); **O** - Si el cliente es un cliente público, por ejemplo, aplicación nativa o aplicación de una sola página (SPA). :::note -Para clientes públicos, cuando esta función está habilitada, siempre se emitirá un nuevo token de actualización cuando el cliente intercambie por un nuevo token de acceso usando el token de actualización. +Para clientes públicos, cuando esta función está habilitada, siempre se emitirá un nuevo token de actualización cuando el cliente esté intercambiando por un nuevo token de acceso usando el token de actualización. Aunque aún puedes desactivar la función para esos clientes públicos, se recomienda encarecidamente mantenerla habilitada por razones de seguridad. ::: - Entendiendo la rotación de tokens de actualización + Comprendiendo la rotación de tokens de actualización ### Tiempo de vida (TTL) del token de actualización en días \{#refresh-token-time-to-live-ttl-in-days} @@ -165,20 +166,39 @@ _Disponibilidad: No SPA; Predeterminado: 14 días_ La duración durante la cual un token de actualización puede usarse para solicitar nuevos tokens de acceso antes de que expire y se vuelva inválido. Las solicitudes de token extenderán el TTL del token de actualización a este valor. -Normalmente, se prefiere un valor más bajo. +Típicamente, se prefiere un valor más bajo. Nota: La actualización del TTL no está disponible en SPA (aplicación de una sola página) por razones de seguridad. Esto significa que Logto no extenderá el TTL a través de solicitudes de token. Para mejorar la experiencia del usuario, puedes habilitar la función "Rotar token de actualización", permitiendo que Logto emita un nuevo token de actualización cuando sea necesario. :::caution Token de actualización y vinculación de sesión -Cuando se emite un token de actualización **sin** el alcance `offline_access` en la solicitud de autorización, estará vinculado a la sesión del usuario. La sesión tiene un TTL fijo de **14 días**. Después de que la sesión expire, el token de actualización se vuelve inválido independientemente de su propia configuración de TTL. +Cuando se emite un token de actualización **sin** el Alcance (Scope) `offline_access` en la solicitud de Autorización (Authorization), estará vinculado a la sesión del usuario. La sesión tiene un TTL fijo de **14 días**. Después de que la sesión expire, el token de actualización se vuelve inválido independientemente de su propia configuración de TTL. -Para asegurarte de que la configuración de TTL del token de actualización tenga efecto completo, asegúrate de incluir el alcance `offline_access` en tu solicitud de autorización. +Para asegurar que la configuración de TTL del token de actualización tenga pleno efecto, asegúrate de incluir el Alcance (Scope) `offline_access` en tu solicitud de Autorización (Authorization). ::: ### URI de cierre de sesión por canal secundario \{#backchannel-logout-uri} -El endpoint de cierre de sesión por canal secundario de OpenID Connect. Consulta [Cierre de sesión federado: cierre de sesión por canal secundario](#) para más información. +El endpoint de cierre de sesión por canal secundario de OpenID Connect. Consulta [Cierre de sesión federado: Cierre de sesión por canal secundario](#) para más información. + +### Concesiones máximas permitidas (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` es un campo opcional a nivel de aplicación bajo `customClientMetadata` que controla el número máximo de concesiones activas concurrentes por usuario para la aplicación actual. + +- **Predeterminado**: `undefined` (sin límite) +- **Cuando está configurado**: En cada Autorización (Authorization) exitosa, Logto verifica las concesiones activas totales para el usuario en la aplicación actual (a través de navegadores y dispositivos). Si se excede el límite, Logto revoca las concesiones más antiguas. + +Esta configuración es útil cuando deseas limitar los dispositivos autenticados concurrentes por aplicación. + +:::note + +Este campo no es compatible con: + +- Aplicaciones máquina a máquina +- Aplicaciones protegidas +- Aplicaciones SAML + +::: ### Datos personalizados \{#custom-data} -Información adicional personalizada de la aplicación que no está incluida en las propiedades predefinidas de la aplicación; los usuarios pueden definir sus propios campos de datos personalizados según sus necesidades específicas, como configuraciones y ajustes específicos del negocio. +Información adicional personalizada de la aplicación no listada en las propiedades predefinidas de la aplicación, los usuarios pueden definir sus propios campos de datos personalizados según sus necesidades específicas, como configuraciones y ajustes específicos del negocio. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..ba157705047 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,170 @@ +# Sesiones + +Las sesiones en Logto definen cómo se crea, comparte, actualiza y revoca el estado de autenticación a través de aplicaciones, navegadores y dispositivos. + +En la práctica, los usuarios experimentan "inicio de sesión" como un estado, pero el estado del sistema se divide en múltiples capas. Comprender estas capas es clave para diseñar un comportamiento predecible de SSO, renovación de tokens y cierre de sesión. + +## Modelo de sesión en Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Dominio de Logto"] + S["Sesión de inicio de sesión"] + G1["Concesión (App A)"] + G2["Concesión (App B)"] + end + + subgraph AppA ["Dominio de la aplicación A"] + A["Sesión local / tokens"] + end + + subgraph AppB ["Dominio de la aplicación B"] + B["Sesión local / tokens"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Sesión de inicio de sesión de Logto**: Estado de inicio de sesión centralizado almacenado como cookies del dominio Logto. Esto controla la disponibilidad de SSO en el contexto del navegador actual. +- **Concesión (Grant)**: Estado de autorización específico de la aplicación para `usuario + aplicación cliente`. Las concesiones son el puente entre el inicio de sesión centralizado y la emisión de tokens de la aplicación. +- **Sesión/tokens locales de la aplicación**: Estado de autenticación local en cada aplicación (tokens de ID/acceso/actualización, cookie de sesión de la aplicación, etc.). + +## Conceptos clave \{#core-concepts} + +### ¿Qué es una sesión de Logto? \{#what-is-a-logto-session} + +Una sesión de Logto es el estado de autenticación centralizado creado después de un inicio de sesión exitoso. Si aún es válida, Logto puede autenticar a los usuarios de manera silenciosa para otras aplicaciones en el mismo inquilino. Si no existe, los usuarios deben iniciar sesión nuevamente. + +### ¿Qué son las concesiones? \{#what-are-grants} + +Una concesión es un estado de autorización a nivel de aplicación vinculado a un usuario específico y una aplicación cliente. + +- Una sesión de Logto puede tener concesiones para múltiples aplicaciones. +- Los tokens para una aplicación se emiten bajo la concesión de esa aplicación. +- Revocar una concesión afecta la capacidad de esa aplicación para continuar con el acceso basado en tokens. + +### Cómo se relacionan la sesión, las concesiones y el estado de autenticación de la aplicación \{#how-session-grants-and-app-auth-state-relate} + +- **Sesión** responde: "¿Puede este navegador hacer SSO con Logto ahora mismo?" +- **Concesión** responde: "¿Está este usuario autorizado para esta aplicación cliente?" +- **Sesión local de la aplicación** responde: "¿Trata actualmente esta aplicación al usuario como si estuviera conectado?" + +## Creación de sesión e inicio de sesión \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as Aplicación cliente + end + + box Logto + participant OIDC as Proveedor OIDC + participant SignIn as Página de inicio de sesión + end + + User ->> Client: Acceder a la aplicación + Client ->> OIDC: Solicitud de autorización + OIDC -->> OIDC: Verificar sesión existente de Logto + OIDC ->> SignIn: Solicitar inicio de sesión si es necesario + SignIn ->> OIDC: Usuario se autentica + OIDC -->> OIDC: Crear sesión y concesión de la aplicación + OIDC ->> Client: Devolver código de autorización + Client ->> OIDC: Intercambiar código por tokens + OIDC -->> Client: Devolver tokens +``` + +## Topología de sesión a través de aplicaciones y dispositivos \{#session-topology-across-apps-and-devices} + +### Mismo navegador: sesión compartida de Logto \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[Usuario] + A["Aplicación cliente A"] + B["Aplicación cliente B"] + C{"¿Existe sesión de Logto?"} + D["Página de inicio de sesión de Logto"] + + U --> A + A --> C + U --> B + B --> C + C -->|No| D +``` + +Las aplicaciones en el mismo navegador pueden compartir el estado de sesión centralizado de Logto, por lo que el SSO puede ocurrir sin la entrada repetida de credenciales. + +### Diferentes navegadores o dispositivos: sesiones de Logto aisladas \{#different-browsers-or-devices-isolated-logto-sessions} + +Cada navegador/dispositivo tiene un almacenamiento de cookies separado. Una sesión válida en el Dispositivo A no implica una sesión válida en el Dispositivo B. + +## Ciclo de vida de la sesión \{#session-lifecycle} + +### 1. Crear \{#1-create} + +Después de la autenticación del usuario, Logto crea una sesión centralizada y una concesión específica de la aplicación. + +### 2. Reutilizar (SSO) \{#2-reuse-sso} + +Mientras las cookies de sesión sean válidas en el mismo navegador, las nuevas solicitudes de autorización pueden completarse a menudo de manera silenciosa. + +### 3. Renovar tokens \{#3-renew-tokens} + +El acceso a la aplicación generalmente continúa a través de flujos de actualización de tokens (cuando están habilitados). Esta es una continuidad a nivel de aplicación, separada de si la sesión centralizada de Logto aún existe. + +### 4. Revocar/expirar \{#4-revokeexpire} + +La revocación puede ocurrir en diferentes capas: + +- El cierre de sesión local de la aplicación elimina los tokens/sesión local de la aplicación. +- El fin de la sesión elimina la sesión centralizada de Logto. +- La revocación de la concesión elimina la continuidad de la autorización a nivel de aplicación. + +## Recomendaciones de diseño \{#design-recommendations} + +- Mantén el manejo de la sesión local de la aplicación explícito en el código de tu aplicación. +- Trata la sesión de Logto, las concesiones y la sesión local de la aplicación como capas separadas. +- Elige si el cierre de sesión debe ser solo local de la aplicación o global. +- Usa [cierre de sesión por canal secundario](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) cuando se requiera consistencia entre múltiples aplicaciones. +- Para detalles sobre el comportamiento e implementación del cierre de sesión, consulta [Cierre de sesión](/end-user-flows/sign-out). + +## Mejores prácticas para revocar el acceso \{#best-practices-for-revoking-access} + +Usa diferentes estrategias de revocación según tu objetivo: + +- **Revocar acceso desde tus aplicaciones de primera parte**: + Revoca la sesión objetivo con `revokeGrantsTarget=firstParty`. + Esto cierra la sesión del usuario en las aplicaciones de primera parte asociadas con esa sesión, lo que crea una experiencia de cierre de sesión consistente. + Al mismo tiempo, las concesiones para aplicaciones de terceros que tienen `offline_access` concedido pueden permanecer disponibles para integraciones continuas. + Consulta [Gestionar sesiones de usuario](/sessions/manage-user-sessions) para obtener detalles sobre la revocación de sesiones. + +- **Revocar acceso a aplicaciones de terceros**: + Elige una de las siguientes opciones: + + - Revoca la sesión con `revokeGrantsTarget=all` para revocar todas las concesiones asociadas con esa sesión. + - Revoca concesiones específicas directamente a través de las APIs de gestión de concesiones para eliminar autorizaciones de aplicaciones de terceros sin forzar el cierre completo de la sesión. + Consulta [Gestionar aplicaciones autorizadas por el usuario (concesiones)](/sessions/grants-management) para estrategias de revocación específicas de concesiones. + +- **Al usar Logto Console**: + En la página de detalles del usuario, Logto proporciona tanto la gestión de sesiones como la gestión de aplicaciones de terceros autorizadas de manera predeterminada. + - Revocar una sesión también revoca las concesiones de aplicaciones de primera parte, para mantener el comportamiento de cierre de sesión de primera parte consistente. + - Revocar una autorización de aplicación de terceros revoca las concesiones para esa aplicación de terceros mientras mantiene el estado original de la sesión sin cambios. + +## Recursos relacionados \{#related-resources} + +Gestionar sesiones de usuario + + Gestionar aplicaciones autorizadas por el usuario (concesiones) + +Configuración de sesiones +Cierre de sesión +Registro e inicio de sesión + + Comprender el flujo de autenticación + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/es/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..775ce73b05e --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 2 +--- + +# Gestionar aplicaciones autorizadas por el usuario (concesiones) + +Las concesiones de aplicaciones representan el estado de autorización del usuario para aplicaciones cliente específicas. + +Utiliza la gestión de concesiones cuando los usuarios o administradores necesiten revisar las aplicaciones autorizadas y revocar el acceso a las aplicaciones sin revocar toda la sesión de Logto. + +Cuando se revocan las concesiones, los tokens de acceso opacos y los tokens de actualización emitidos previamente para esas concesiones se invalidan. + +## Elige el camino correcto \{#choose-the-right-path} + +| Escenario | Camino recomendado | +| -------------------------------------------------------------------------------------------------------------- | ------------------ | +| Permitir que los usuarios conectados gestionen sus propias autorizaciones de aplicaciones | Account API | +| Permitir que los administradores o equipos de soporte gestionen las concesiones para un usuario objetivo | Management API | +| Permitir que los operadores gestionen las autorizaciones de aplicaciones de terceros en la interfaz de usuario | Admin Console | + +## APIs de gestión directa de concesiones \{#direct-grant-management-apis} + +### Account API (autoservicio) \{#account-api-self-service} + +Utiliza Account API en las páginas de configuración de cuentas de usuario final: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- Referencia: [Gestionar aplicaciones autorizadas por el usuario (concesiones)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (herramientas de administración) \{#management-api-admin-tools} + +Utiliza Management API en herramientas de administración y flujos de trabajo de soporte: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- Referencia: [Gestionar aplicaciones autorizadas por el usuario (concesiones)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### Filtrar lista de concesiones por tipo de aplicación \{#filter-grant-list-by-app-type} + +Los puntos finales de listado de concesiones admiten el parámetro de consulta opcional `appType`: + +- `appType=firstParty`: Lista solo las concesiones de aplicaciones de primera parte. +- `appType=thirdParty`: Lista solo las concesiones de aplicaciones de terceros. +- Omitir `appType`: Devuelve todas las concesiones activas. + +## Gestionar autorizaciones de aplicaciones de terceros en la Consola \{#manage-third-party-app-authorizations-in-console} + +En Logto Console, utiliza la página de detalles del usuario para ver y revocar aplicaciones de terceros autorizadas. + +- Referencia: [Gestionar aplicaciones de terceros autorizadas por el usuario](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## Revocar concesiones al revocar una sesión \{#revoke-grants-when-revoking-a-session} + +Al revocar una sesión a través de `DELETE /api/my-account/sessions/{sessionId}`, utiliza el parámetro de consulta opcional `revokeGrantsTarget` para controlar el alcance de la revocación de concesiones: + +- `all`: Revoca concesiones para todas las aplicaciones asociadas con la sesión. +- `firstParty`: Revoca concesiones solo para aplicaciones de primera parte. + +Para el comportamiento a nivel de sesión y el contexto del punto final, consulta [Gestionar sesiones de usuario](/sessions/manage-user-sessions) y [Cerrar sesión](/end-user-flows/sign-out). + +## Recursos relacionados \{#related-resources} + +Sesiones +Gestionar sesiones de usuario + + Configuración de cuenta por Account API: Gestionar aplicaciones autorizadas por el usuario + (concesiones) + + + Configuración de cuenta por Management API: Gestionar aplicaciones autorizadas por el usuario + (concesiones) + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/es/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..ba635d3ff21 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +--- + +# Gestionar sesiones de usuario + +La gestión de sesiones de usuario ayuda a los usuarios y administradores a revisar los estados de inicio de sesión activos y revocar sesiones cuando sea necesario. + +En Logto, puedes gestionar sesiones a través de tres caminos comunes: + +- **Account API**: Para autoservicio del usuario final en la página de configuración de la cuenta de tu producto. +- **Management API**: Para herramientas de administración o soporte para gestionar sesiones de cualquier usuario. +- **Admin Console**: Para flujos de trabajo de operadores en Logto Console sin necesidad de crear herramientas personalizadas. + +## Elige la API correcta \{#choose-the-right-api} + +| Escenario | API recomendada | +| ---------------------------------------------------------------------------------------- | --------------- | +| Permitir que los usuarios conectados gestionen sus propias sesiones activas | Account API | +| Permitir que los administradores o equipos de soporte gestionen sesiones para un usuario | Management API | +| Permitir que los operadores gestionen sesiones directamente en Logto Console | Admin Console | + +## Ver sesiones activas \{#view-active-sessions} + +### Account API (autoservicio) \{#account-api-self-service} + +Usa el endpoint de sesión de Account API para listar las sesiones activas del usuario actual. + +- Sección de referencia: [Gestionar sesiones de usuario](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +Antes de exponer esta capacidad a los usuarios finales, asegúrate de que la gestión de sesiones esté habilitada en la configuración del centro de cuentas y que tu aplicación solicite el alcance requerido de Account API. + +### Management API (herramientas de administración) \{#management-api-admin-tools} + +Usa Management API cuando tu sistema de administración necesite listar sesiones para un usuario objetivo. + +- Sección de referencia: [Gestión de sesiones de usuario](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Endpoint de detalles opcionales: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## Revocar sesiones \{#revoke-sessions} + +### Account API (el usuario final revoca sus propias sesiones) \{#account-api-end-user-revokes-own-sessions} + +Los usuarios finales pueden revocar una sesión específica de su propia lista de sesiones. + +- Sección de referencia: [Gestionar sesiones de usuario](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +Para operaciones sensibles, la gestión de sesiones de Account API requiere verificación del usuario antes del acceso. Consulta [Obtener un id de registro de verificación](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id). + +### Management API (el administrador revoca sesiones de usuario) \{#management-api-admin-revokes-user-sessions} + +Los administradores pueden revocar la sesión de un usuario objetivo por ID de usuario e ID de sesión. + +- Sección de referencia: [Gestión de sesiones de usuario](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +Si tu equipo gestiona usuarios directamente en Logto Console, puedes revisar sesiones activas y revocar sesiones específicas desde la página de detalles del usuario. + +- Sección de referencia: [Gestionar sesiones activas de usuario](/user-management/manage-users#manage-user-active-sessions) + +## Recursos relacionados \{#related-resources} + +Sesiones + + Gestionar aplicaciones autorizadas por el usuario (concesiones) + + + Configuración de cuenta por Account API: Gestionar sesiones de usuario + + + Configuración de cuenta por Management API: Gestión de sesiones de usuario + + + Gestión de usuarios: Gestionar sesiones activas de usuario + diff --git a/i18n/es/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/es/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..e67229e212a --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 3 +--- + +# Configuración de sesión + +La configuración de sesión define controles a nivel de inquilino para determinar cuánto tiempo permanecen activas las sesiones de inicio de sesión de Logto y cómo se aplican las políticas de acceso relacionadas con la sesión. + +Esta página cubre: + +- Configuración de TTL de sesión +- Máximo de dispositivos autenticados concurrentes por aplicación + +## Configuración de TTL de sesión \{#session-ttl-configuration} + +El TTL de sesión determina la vida útil máxima de la sesión de inicio de sesión OIDC de Logto. +Es una **configuración a nivel de inquilino**: una vez configurada, se aplica a todas las aplicaciones y flujos de autenticación en ese inquilino. + +### Comportamiento predeterminado \{#default-behavior} + +- Por defecto, el TTL de sesión es de **14 días**. +- Si no se configura un TTL personalizado, Logto continúa utilizando este valor predeterminado. + +### Configurar a través de Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +Puedes configurar el TTL de sesión en la Consola bajo: + +Console > Tenant > Settings > OIDC settings + +Usa **Tiempo máximo de vida de la sesión** para actualizar el valor. + +:::note + +La Consola utiliza **días** para la entrada y visualización, mientras que la configuración/API de sesión OIDC subyacente utiliza **segundos**. + +::: + +### Configurar a través de Management API \{#configure-via-management-api} + +Usa estos endpoints para leer y actualizar la configuración de sesión OIDC: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +Ejemplo (`ttl` en segundos): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` segundos = 14 días. + +:::note + +Para implementaciones OSS, reinicia la instancia del servicio después de cambiar `logto-config` para que el servidor pueda recoger la última configuración OIDC. + +Para aplicar actualizaciones de configuración OIDC automáticamente sin reiniciar el servicio, [habilita la caché central de redis](/logto-oss/central-cache). + +::: + +## Máximo de dispositivos autenticados concurrentes por aplicación \{#max-concurrent-authenticated-devices-per-app} + +El máximo de dispositivos autenticados concurrentes por aplicación es un control a nivel de aplicación que limita cuántas concesiones activas puede mantener cada usuario para una aplicación específica. + +Esto se configura a través del campo `maxAllowedGrants` en `customClientMetadata` de la aplicación. +Aprende más en [Estructura de datos de la aplicación](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants). + +### Comportamiento \{#behavior} + +Cuando se establece `maxAllowedGrants`, Logto evalúa las concesiones activas del usuario para la aplicación actual en cada autorización exitosa. +Si el número de concesiones activas supera el límite, Logto revoca las concesiones más antiguas primero. + +Si `maxAllowedGrants` no está establecido, no hay límite de concurrencia. + +### Configurar a través de Logto Console \{#configure-via-logto-console} + +Puedes configurar esto en la página de detalles de cada aplicación bajo: + + + Console > Applications > Application details > Concurrent device limit + + +Establece el número máximo de concesiones activas concurrentes (dispositivos) por usuario para la aplicación actual. + +:::note + +Esta configuración no es compatible con aplicaciones máquina a máquina, aplicaciones protegidas y aplicaciones SAML. + +::: + +## Recursos relacionados \{#related-resources} + +Sesiones +Gestionar sesiones de usuario + + Gestionar aplicaciones autorizadas por el usuario (concesiones) + + + Estructura de datos de la aplicación: maxAllowedGrants + +Interactuar con Management API diff --git a/i18n/es/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/es/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index 8b568125011..0835a29032f 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -8,7 +8,7 @@ sidebar_position: 2 ### Navegar y buscar usuarios \{#browse-and-search-users} -Para acceder a la funcionalidad de gestión de usuarios en Logto Console, navega a Consola > Gestión de usuarios. Una vez allí, verás una vista en tabla de todos los usuarios. +Para acceder a la funcionalidad de gestión de usuarios en Logto Console, navega a Console > Gestión de usuarios. Una vez allí, verás una vista de tabla de todos los usuarios. La tabla consta de tres columnas: @@ -20,43 +20,43 @@ Admite mapeo de palabras clave para [`name`](/user-management/user-data#name), [ ### Añadir usuarios \{#add-users} -Usando la Consola, los desarrolladores pueden crear nuevas cuentas para los usuarios finales. Para hacerlo, haz clic en el botón "Añadir usuario" en la esquina superior derecha de la pantalla. +Usando el Console, los desarrolladores pueden crear nuevas cuentas para los usuarios finales. Para hacerlo, haz clic en el botón "Añadir usuario" en la esquina superior derecha de la pantalla. -Al crear un usuario en Logto Console o mediante la Management API (no usuarios auto-registrados a través de la interfaz), debes proporcionar al menos un identificador: `correo electrónico principal`, `teléfono principal` o `nombre de usuario`. El campo `name` es opcional. +Al crear un usuario en Logto Console o a través del Management API (no registrado por el usuario final a través de la interfaz), debes proporcionar al menos un identificador: `correo electrónico principal`, `teléfono principal` o `nombre de usuario`. El campo `name` es opcional. -Después de crear el usuario, Logto generará automáticamente una contraseña aleatoria. La contraseña inicial solo aparecerá una vez, pero puedes [restablecer la contraseña](./manage-users#reset-user-password) más adelante. Si deseas establecer una contraseña específica, utiliza la Management API `patch /api/users/{userId}/password` para actualizarla después de crear el usuario. +Después de que el usuario sea creado, Logto generará automáticamente una contraseña aleatoria. La contraseña inicial solo aparecerá una vez, pero puedes [restablecer la contraseña](./manage-users#reset-user-password) más tarde. Si deseas establecer una contraseña específica, utiliza el Management API `patch /api/users/{userId}/password` para actualizarla después de que el usuario haya sido creado. -Puedes copiar los **identificadores introducidos (dirección de correo electrónico / número de teléfono / nombre de usuario)** y la **contraseña inicial** con un solo clic, lo que facilita compartir estas credenciales con el nuevo usuario para que pueda iniciar sesión y comenzar. +Puedes copiar los **identificadores ingresados (dirección de correo electrónico / número de teléfono / nombre de usuario)** y la **contraseña inicial** con un solo clic, lo que facilita compartir estas credenciales con el nuevo usuario para que pueda iniciar sesión y comenzar. :::tip -Si deseas implementar un registro solo por invitación, te recomendamos [invitar usuarios con un enlace mágico](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Esto permite que solo los usuarios en la lista blanca se auto-registren y establezcan su propia contraseña. +Si deseas implementar un registro solo por invitación, te recomendamos [invitar a los usuarios con un enlace mágico](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Esto permite que solo los usuarios en lista blanca se registren por sí mismos y establezcan su propia contraseña. ::: ### Ver y actualizar el perfil del usuario \{#view-and-update-the-user-profile} -Para ver los detalles de un usuario, simplemente haz clic en la fila correspondiente en la tabla de usuarios. Esto te llevará a la página de "**Detalles del usuario**", donde puedes encontrar la información del perfil del usuario, incluyendo: +Para ver los detalles de un usuario, simplemente haz clic en la fila correspondiente en la tabla de usuarios. Esto te llevará a la página de "**Detalles del usuario**" donde puedes encontrar la información del perfil del usuario, incluyendo: - **Datos relacionados con la autenticación**: - **Dirección de correo electrónico** ([primary_email](/user-management/user-data#primary_email)): Editable - **Número de teléfono** ([primary_phone](/user-management/user-data#primary_phone)): Editable - **Nombre de usuario** ([username](/user-management/user-data#username)): Editable - **Contraseña** ([has_password](/user-management/user-data#has_password)): Puedes regenerar una contraseña aleatoria. Aprende más sobre "[Restablecer la contraseña del usuario](#reset-user-password)". - - **Autenticación multifactor (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Visualiza todos los factores de autenticación (por ejemplo, passkeys, aplicaciones autenticadoras, códigos de respaldo) que este usuario ha configurado. Los factores pueden eliminarse en la Consola. - - **Passkeys**: Cuando el [inicio de sesión con passkey](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) está habilitado en el tenant, también puedes ver las passkeys de inicio de sesión del usuario en la página de detalles y eliminarlas si es necesario. Estas passkeys están respaldadas por el mismo modelo de credenciales WebAuthn utilizado por MFA. + - **Autenticación multifactor (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Ver todos los factores de autenticación (por ejemplo, claves de acceso, aplicaciones de autenticación, códigos de respaldo) que este usuario ha configurado. Los factores se pueden eliminar en el Console. + - **Claves de acceso**: Cuando el [inicio de sesión con clave de acceso](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) está habilitado en el inquilino, también puedes ver las claves de acceso de inicio de sesión del usuario en la página de detalles del usuario y eliminarlas si es necesario. Estas claves de acceso están respaldadas por el mismo modelo de credenciales WebAuthn utilizado por MFA. - **Token de acceso personal**: Crear, ver, renombrar y eliminar [tokens de acceso personal](/user-management/personal-access-token). - **Conexión**: - **Conexiones sociales** ([identities](/user-management/user-data#social-identities)): - - Visualiza las cuentas sociales vinculadas del usuario, incluidos los IDs sociales y los detalles del perfil sincronizados desde sus proveedores sociales (por ejemplo, aparecerá una entrada "Facebook" si el usuario inició sesión a través de Facebook). + - Ver las cuentas sociales vinculadas del usuario, incluidos los ID sociales y los detalles del perfil sincronizados desde sus proveedores sociales (por ejemplo, aparecerá una entrada "Facebook" si el usuario inició sesión a través de Facebook). - Puedes eliminar identidades sociales existentes, pero no puedes vincular nuevas cuentas sociales en nombre del usuario. - Para conectores sociales con [almacenamiento de tokens](/secret-vault/federated-token-set) habilitado, puedes ver y gestionar tokens de acceso y tokens de actualización en la página de detalles de la conexión. - **Conexiones SSO empresariales** ([sso_identities](/user-management/user-data#sso-identities)): - - Visualiza las identidades empresariales vinculadas del usuario, incluidos los IDs empresariales y los detalles del perfil sincronizados desde sus proveedores de identidad empresariales. - - No puedes añadir ni eliminar identidades SSO empresariales en la Consola. + - Ver las identidades empresariales vinculadas del usuario, incluidos los ID empresariales y los detalles del perfil sincronizados desde sus proveedores de identidad empresarial. + - No puedes añadir o eliminar identidades SSO empresariales en el Console. - Para conectores empresariales basados en OIDC con [almacenamiento de tokens](/secret-vault/federated-token-set) habilitado, puedes ver y eliminar tokens en la página de detalles de la conexión. -- **Datos del perfil del usuario**: nombre, URL del avatar, datos personalizados y reclamos estándar adicionales de OpenID Connect que no están incluidos. Todos estos campos de perfil son editables. -- **Sesiones**: Visualiza la lista de sesiones activas del usuario, incluyendo información del dispositivo, sessionId y ubicación GEO si corresponde. Visualiza más detalles de una sesión y revócala en la página de detalles de la sesión. +- **Datos del perfil del usuario**: nombre, URL del avatar, datos personalizados y reclamos estándar adicionales de OpenID Connect que no están incluidos. Todos estos campos del perfil son editables. +- **Sesiones**: Ver la lista de sesiones activas del usuario, incluida la información del dispositivo, sessionId y ubicación GEO si corresponde. Ver más detalles de una sesión y revocarla en la página de detalles de la sesión. :::warning @@ -66,58 +66,73 @@ Es importante confirmar que el usuario tiene un método alternativo de inicio de ### Ver actividades del usuario \{#view-user-activities} -Para ver las actividades recientes de un usuario, navega a la subpestaña "Registros de usuario" en la página de detalles del usuario. Aquí encontrarás una tabla que muestra las actividades recientes del usuario, incluyendo la acción realizada, el resultado de la acción, la aplicación relacionada y la hora en que el usuario actuó. +Para ver las actividades recientes de un usuario, navega a la subpestaña "Registros de usuario" en la página de "Detalles del usuario". Aquí, puedes encontrar una tabla que muestra las actividades recientes del usuario, incluyendo la acción realizada, el resultado de la acción, la aplicación relacionada y el momento en que el usuario actuó. Haz clic en la fila de la tabla para ver más detalles en el registro del usuario, por ejemplo, dirección IP, agente de usuario, datos sin procesar, etc. ### Suspender usuario \{#suspend-user} -En la página de detalles del usuario, haz clic en "Tres puntos" -> botón "Suspender usuario". +En la página de "Detalles del usuario", haz clic en "Tres puntos" -> botón "Suspender usuario". -Una vez que un usuario está suspendido, no podrá iniciar sesión en tu aplicación ni obtener un nuevo token de acceso después de que el actual expire. Además, cualquier solicitud de API realizada por este usuario fallará. +Una vez que un usuario está suspendido, no podrá iniciar sesión en tu aplicación y no podrá obtener un nuevo token de acceso después de que expire el actual. Además, cualquier solicitud de API realizada por este usuario fallará. Si deseas reactivar a este usuario, puedes hacerlo haciendo clic en "Tres puntos" -> botón "Reactivar usuario". ### Eliminar usuario \{#delete-user} -En la página de detalles del usuario, haz clic en "Tres puntos" -> botón "Eliminar". Eliminar un usuario no se puede deshacer. +En la página de "Detalles del usuario", haz clic en "Tres puntos" -> botón "Eliminar". Eliminar usuario no se puede deshacer. ### Restablecer la contraseña del usuario \{#reset-user-password} -En la página de detalles del usuario, haz clic en "Tres puntos" -> botón "Restablecer contraseña", y luego Logto generará automáticamente una contraseña aleatoria. +En la página de "Detalles del usuario", haz clic en "Tres puntos" -> botón "Restablecer contraseña", y luego Logto regenerará automáticamente una contraseña aleatoria. Después de restablecer la contraseña, cópiala y envíala al usuario final. Una vez que se cierre el modal de "Restablecer contraseña", ya no podrás ver la contraseña. Si olvidas guardarla, puedes restablecerla nuevamente. -No puedes establecer una contraseña específica para los usuarios en Logto Console, pero puedes usar la [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` para especificar una contraseña. +No puedes establecer una contraseña específica para los usuarios en Logto Console, pero puedes usar el [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` para especificar una contraseña. ### Gestionar sesiones activas del usuario \{#manage-user-active-sessions} -En la página de detalles del usuario, navega a la página de "Detalles de la sesión" haciendo clic en el botón "Gestionar" de una sesión específica. Aquí puedes ver información detallada sobre la sesión, como el dispositivo, la ubicación y la hora de inicio de sesión. Si deseas cerrar la sesión del usuario, simplemente haz clic en el botón "Revocar sesión" en la esquina superior derecha, y la sesión se revocará inmediatamente. +En la página de "Detalles del usuario", navega a la página de "Detalles de la sesión" haciendo clic en el botón "Gestionar" de una sesión específica. Aquí puedes ver información detallada sobre la sesión, como el dispositivo, la ubicación y la hora de inicio de sesión. Si deseas cerrar la sesión del usuario, simplemente haz clic en el botón "Revocar sesión" en la esquina superior derecha, y la sesión se revocará inmediatamente. -- Por defecto, revocar una sesión en la Consola también revocará todos los permisos de aplicaciones de primera parte asociados con esa sesión, y el usuario deberá iniciar sesión nuevamente para restaurar el acceso. Cualquier token opaco de acceso y token de actualización emitidos previamente para aplicaciones de primera parte también se revocarán inmediatamente. -- Para aplicaciones de terceros con alcance `offline_access`, revocar una sesión no revoca el permiso de la aplicación por defecto, cualquier token de actualización emitido previamente aún puede usarse hasta que el permiso expire. +- Por defecto, revocar una sesión en el Console también revocará todos los permisos de la aplicación de primera parte asociados con esa sesión, y el usuario deberá iniciar sesión nuevamente para restaurar el acceso. Cualquier token de acceso opaco preemitido y tokens de actualización para aplicaciones de primera parte también se revocarán inmediatamente. +- Para aplicaciones de terceros con alcance `offline_access`, revocar una sesión no revoca el permiso de la aplicación por defecto, cualquier token de actualización preemitido aún puede usarse hasta que el permiso expire. + +### Gestionar aplicaciones de terceros autorizadas por el usuario \{#manage-user-authorized-third-party-apps} + +En la página de "Detalles del usuario", puedes usar la sección "Aplicaciones de terceros autorizadas" para revisar el estado de autorización de la aplicación para el usuario. +Esta sección está respaldada por las APIs de gestión de aplicaciones autorizadas por el usuario (permisos). + +Para cada aplicación autorizada, Console muestra: + +- Nombre de la aplicación +- ID de la aplicación +- Hora de creación del acceso + +Si necesitas eliminar el acceso, haz clic en la acción de revocación y confirma en el modal. + +Revocar una autorización de aplicación elimina todos los permisos activos de terceros asociados con esa aplicación para el usuario. También revocará cualquier token de acceso opaco preemitido y tokens de actualización para esa aplicación inmediatamente. ## Verificación de cumplimiento de contraseñas \{#password-compliance-check} Después de actualizar la [política de contraseñas](/security/password-policy) en Logto, los usuarios existentes aún pueden iniciar sesión con sus contraseñas actuales. Solo las cuentas recién creadas deberán seguir la política de contraseñas actualizada. -Para aplicar una seguridad más fuerte, puedes usar el `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) para comprobar si la contraseña de un usuario cumple con la política actual definida en la experiencia de inicio de sesión predeterminada. Si no la cumple, puedes solicitar al usuario que actualice su contraseña con un flujo personalizado usando la [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). +Para imponer una seguridad más fuerte, puedes usar el `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) para verificar si la contraseña de un usuario cumple con la política actual definida en la experiencia de inicio de sesión predeterminada. Si no lo hace, puedes solicitar al usuario que actualice su contraseña con un flujo personalizado usando [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). -### Gestionar roles de los usuarios \{#manage-roles-of-users} +### Gestionar roles de usuarios \{#manage-roles-of-users} -En la pestaña "Roles" de la página de detalles del usuario, puedes asignar o eliminar roles fácilmente para lograr el resultado deseado. Consulta [Control de acceso basado en roles (RBAC)](/authorization/role-based-access-control) para más detalles. +En la pestaña "Roles" de la página de detalles del usuario, puedes asignar o eliminar roles fácilmente para lograr el resultado deseado. Consulta [Control de acceso basado en roles](/authorization/role-based-access-control) para más detalles. ### Ver las organizaciones a las que pertenece el usuario \{#view-the-organizations-the-user-belongs-to} -Logto admite [organizaciones](/organizations/organization-management) y puede gestionar a sus miembros. Puedes ver fácilmente los detalles del usuario y a qué organización pertenece. +Logto admite [organizaciones](/organizations/organization-management) y puede gestionar a sus miembros. Puedes ver fácilmente los detalles del usuario y ver a qué organización pertenece. ## Gestionar a través de Logto Management API \{#manage-via-logto-management-api} -La [Management API](/concepts/core-service/#management-api) es un conjunto de APIs que proporcionan acceso al servicio backend de Logto. Como se mencionó anteriormente, la API de usuario es un componente crítico de este servicio y puede soportar una amplia gama de escenarios. +[Management API](/concepts/core-service/#management-api) es una colección de APIs que proporcionan acceso al servicio backend de Logto. Como se mencionó anteriormente, el API de usuario es un componente crítico de este servicio y puede admitir una amplia gama de escenarios. -Las [APIs RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) relacionadas con usuarios están montadas en `/api/users` excepto para las actividades del usuario, es decir, los registros de usuario `/api/logs?userId=:userId`. +Las APIs [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) relacionadas con el usuario están montadas en `/api/users` excepto para las actividades del usuario, es decir, registros de usuario `/api/logs?userId=:userId`. -Puedes gestionar usuarios a través de la Management API en varios casos de uso. Como [búsqueda avanzada de usuarios](/user-management/advanced-user-search), [creación masiva de cuentas](https://openapi.logto.io/operation/operation-createuser), [registro solo por invitación](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. +Puedes gestionar usuarios a través del Management API en varios casos de uso. Como [búsqueda avanzada de usuarios](/user-management/advanced-user-search), [creación masiva de cuentas](https://openapi.logto.io/operation/operation-createuser), [registro solo por invitación](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. ## Preguntas frecuentes \{#faqs} @@ -130,7 +145,7 @@ Puedes gestionar usuarios a través de la Management API en varios casos de uso. Debido a la naturaleza de [Omni-sign-in](https://logto.io/products/omni-sign-in) de Logto, no está diseñado para restringir el acceso de usuarios a ciertas aplicaciones antes de la autenticación. -Sin embargo, aún puedes diseñar roles de usuario y permisos específicos de la aplicación para proteger tus recursos de API, y validar los permisos en el acceso a la API tras un inicio de sesión exitoso del usuario. -Consulta Autorización: [Control de acceso basado en roles (RBAC)](/authorization/role-based-access-control) para más información. +Sin embargo, aún puedes diseñar roles de usuario y permisos específicos de la aplicación para proteger tus recursos de API, y validar permisos en el acceso a la API tras el inicio de sesión exitoso del usuario. +Consulta Autorización: [Control de acceso basado en roles](/authorization/role-based-access-control) para más información. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index a0bcd4d4121..b1d32d13d85 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,49 +7,49 @@ sidebar_position: 5 # Clés de signature -Les [clés de signature OIDC](https://auth.wiki/signing-key) de Logto, également appelées "clés privées OIDC" et "clés de cookie OIDC", sont les clés utilisées pour signer les JWTs ([jetons d’accès (Access tokens)](https://auth.wiki/access-token) et [jetons d’identifiant (ID tokens)](https://auth.wiki/id-token)) ainsi que les cookies de navigateur dans les [sessions de connexion](/end-user-flows/sign-out#what-is-a-logto-session) Logto. Ces clés de signature sont générées lors de l'initialisation de la base de données Logto ([open-source](/logto-oss)) ou lors de la création d'un nouveau tenant ([Cloud](/logto-cloud)) et peuvent être gérées via le [CLI](/logto-oss/using-cli) (open-source), les Management APIs ou l'interface Console UI. +Les [clés de signature OIDC](https://auth.wiki/signing-key) de Logto, également connues sous le nom de "clés privées OIDC" et "clés de cookie OIDC", sont les clés de signature utilisées pour signer les JWTs ([jetons d’accès](https://auth.wiki/access-token) et [jetons d’identifiant](https://auth.wiki/id-token)) et les cookies de navigateur dans les [sessions de connexion](/sessions#what-is-a-logto-session) Logto. Ces clés de signature sont générées lors de l'initialisation de la base de données Logto ([open-source](/logto-oss)) ou lors de la création d'un nouveau locataire ([Cloud](/logto-cloud)) et peuvent être gérées via le [CLI](/logto-oss/using-cli) (open-source), les Management APIs ou l'interface utilisateur de la Console. -Par défaut, Logto utilise l'algorithme à courbe elliptique (EC) pour générer les signatures numériques. Cependant, sachant que les utilisateurs doivent souvent vérifier les signatures JWT et que de nombreux outils anciens ne prennent pas en charge l'algorithme EC (ne supportant que RSA), nous avons implémenté la fonctionnalité de rotation des clés privées et permis aux utilisateurs de choisir l'algorithme de signature (y compris RSA et EC). Cela garantit la compatibilité avec les services utilisant des outils de vérification de signature obsolètes. +Par défaut, Logto utilise l'algorithme de courbe elliptique (EC) pour générer des signatures numériques. Cependant, étant donné que les utilisateurs doivent souvent vérifier les signatures JWT et que de nombreux anciens outils ne prennent pas en charge l'algorithme EC (ne prenant en charge que RSA), nous avons implémenté la fonctionnalité de rotation des clés privées et permettons aux utilisateurs de choisir l'algorithme de signature (y compris RSA et EC). Cela garantit la compatibilité avec les services utilisant des outils de vérification de signature obsolètes. :::note -Théoriquement, les clés de signature ne devraient pas être divulguées et n'ont pas de date d'expiration, ce qui signifie qu'il n'est pas nécessaire de les faire tourner. Cependant, effectuer une rotation périodique de la clé de signature après une certaine période peut renforcer la sécurité. +Théoriquement, les clés de signature ne devraient pas être divulguées et n'ont pas de date d'expiration, ce qui signifie qu'il n'est pas nécessaire de les faire tourner. Cependant, faire tourner périodiquement la clé de signature après une certaine période peut renforcer la sécurité. ::: ## Comment ça fonctionne ? \{#how-it-works} - **Clé privée OIDC** - Lors de l'initialisation d'une instance Logto, une paire de clé publique et clé privée est automatiquement générée et enregistrée dans le fournisseur OIDC sous-jacent. Ainsi, lorsque Logto émet un nouveau JWT (jeton d’accès ou jeton d’identifiant), le jeton est signé avec la clé privée. Pendant ce temps, toute application cliente qui reçoit un JWT peut utiliser la clé publique associée pour vérifier la signature du jeton, afin de s'assurer que le jeton n'a pas été altéré par un tiers. La clé privée est protégée sur le serveur Logto. La clé publique, comme son nom l'indique, est publique et accessible via l'interface `/oidc/jwks` du point de terminaison OIDC. Un algorithme de clé de signature peut être spécifié lors de la génération de la clé privée, et Logto utilise par défaut l'algorithme EC (Elliptic Curve). Les administrateurs peuvent changer l'algorithme par défaut en RSA (Rivest-Shamir-Adleman) en effectuant une rotation des clés privées. + Lors de l'initialisation d'une instance Logto, une paire de clé publique et clé privée est automatiquement générée et enregistrée dans le fournisseur OIDC sous-jacent. Ainsi, lorsque Logto émet un nouveau JWT (jeton d’accès ou jeton d’identifiant), le jeton est signé avec la clé privée. En même temps, toute application cliente qui reçoit un JWT peut utiliser la clé publique associée pour vérifier la signature du jeton, afin de s'assurer que le jeton n'est pas altéré par un tiers. La clé privée est protégée sur le serveur Logto. La clé publique, cependant, comme son nom l'indique, est publique pour tout le monde et peut être accédée via l'interface `/oidc/jwks` du point de terminaison OIDC. Un algorithme de clé de signature peut être spécifié lors de la génération de la clé privée, et Logto utilise par défaut l'algorithme EC (Elliptic Curve). Les utilisateurs administrateurs peuvent changer l'algorithme par défaut en RSA (Rivest-Shamir-Adleman) en faisant tourner les clés privées. - **Clé de cookie OIDC** - Lorsqu'un utilisateur initie un flux de connexion ou d'inscription, une "session OIDC" est créée sur le serveur, ainsi qu'un ensemble de cookies de navigateur. Avec ces cookies, le navigateur peut demander à l’Experience API Logto d’effectuer une série d’interactions au nom de l’utilisateur, telles que la connexion, l’inscription et la réinitialisation du mot de passe. Cependant, contrairement aux JWTs, les cookies sont uniquement signés et vérifiés par le service OIDC Logto lui-même, des mesures de cryptographie asymétrique ne sont pas requises. Ainsi, nous n'avons pas de clés publiques associées pour les clés de signature des cookies, ni d'algorithmes de chiffrement asymétrique. + Lorsqu'un utilisateur initie un flux de connexion ou d'inscription, une "session OIDC" sera créée sur le serveur, ainsi qu'un ensemble de cookies de navigateur. Avec ces cookies, le navigateur peut demander à l'Experience API de Logto d'effectuer une série d'interactions au nom de l'utilisateur, telles que la connexion, l'inscription et la réinitialisation du mot de passe. Cependant, contrairement aux JWTs, les cookies sont uniquement signés et vérifiés par le service OIDC de Logto lui-même, des mesures de cryptographie asymétrique ne sont pas requises. Ainsi, nous n'avons pas de clés publiques associées pour les clés de signature de cookies, ni d'algorithmes de cryptage asymétrique. -## Faire tourner les clés de signature depuis la Console UI \{#rotate-signing-keys-from-console-ui} +## Faire tourner les clés de signature depuis l'interface utilisateur de la Console \{#rotate-signing-keys-from-console-ui} -Logto introduit une fonctionnalité de "Rotation des clés de signature", qui vous permet de créer une nouvelle clé privée OIDC et une clé de cookie dans votre tenant. +Logto introduit une fonctionnalité de "Rotation des clés de signature", qui vous permet de créer une nouvelle clé privée OIDC et une clé de cookie dans votre locataire. -1. Accédez à Console > Clés de signature. À partir de là, vous pouvez gérer à la fois les clés privées OIDC et les clés de cookie OIDC. +1. Accédez à Console > Paramètres du locataire > Configuration OIDC. À partir de là, vous pouvez gérer à la fois les clés privées OIDC et les clés de cookie OIDC. 2. Pour faire tourner la clé de signature, cliquez sur le bouton "Faire tourner les clés privées" ou "Faire tourner les clés de cookie". Lors de la rotation des clés privées, vous avez la possibilité de changer l'algorithme de signature. -3. Vous trouverez un tableau qui liste toutes les clés de signature en cours d'utilisation. Remarque : Vous pouvez supprimer la clé précédente, mais vous ne pouvez pas supprimer la clé actuelle. +3. Et vous trouverez un tableau qui répertorie toutes les clés de signature en cours d'utilisation. Remarque : Vous pouvez supprimer la clé précédente, mais vous ne pouvez pas supprimer la clé actuelle. - | Statut | Description | - | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | - | Actuelle | Indique que cette clé est actuellement utilisée activement dans vos applications et APIs. | - | Précédente | Fait référence à une clé précédemment utilisée mais qui a été remplacée. Les jetons existants signés avec cette clé restent valides. | + | Statut | Description | + | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | + | Actuelle | Cela indique que cette clé est actuellement utilisée activement dans vos applications et APIs. | + | Précédente | Elle fait référence à une clé qui était précédemment utilisée mais qui a été remplacée. Les jetons existants avec cette clé de signature restent valides. | -Veuillez noter que la rotation implique les trois actions suivantes : +Veuillez vous rappeler que la rotation implique les trois actions suivantes : -1. **Création d'une nouvelle clé de signature** : Cela obligera toutes vos **applications** et **APIs** à adopter la nouvelle clé de signature. -2. **Rotation de la clé actuelle** : La clé existante sera désignée comme "précédente" après la rotation et ne sera plus utilisée par les nouvelles applications et APIs. Cependant, les jetons signés avec cette clé resteront valides. -3. **Suppression de votre clé précédente** : Les clés marquées comme "précédente" seront révoquées et supprimées du tableau. +1. **Créer une nouvelle clé de signature** : Cela nécessitera que toutes vos **applications** et **APIs** adoptent la nouvelle clé de signature. +2. **Faire tourner la clé actuelle** : La clé existante sera désignée comme "précédente" après la rotation et ne sera pas utilisée par les nouvelles applications et APIs créées. Cependant, les jetons signés avec cette clé resteront valides. +3. **Supprimer votre clé précédente** : Les clés étiquetées comme "précédentes" seront révoquées et supprimées du tableau. :::warning Ne faites jamais tourner les clés de signature consécutivement (deux fois ou plus), car cela pourrait invalider TOUS les jetons émis. -- Pour les utilisateurs OSS, après la rotation de la clé de signature, un redémarrage de l'instance Logto est nécessaire pour que la nouvelle clé prenne effet. -- Pour les utilisateurs Cloud, la nouvelle clé de signature prend effet immédiatement après la rotation, mais veillez à ne pas faire tourner la clé de signature plusieurs fois de suite. +- Pour les utilisateurs OSS, après avoir fait tourner la clé de signature, un redémarrage de l'instance Logto est nécessaire pour que la nouvelle clé de signature prenne effet. +- Pour les utilisateurs Cloud, la nouvelle clé de signature prend effet immédiatement après la rotation, mais assurez-vous de ne pas faire tourner la clé de signature plusieurs fois consécutivement. ::: ## Ressources associées \{#related-resources} - Introduction aux algorithmes de signature EC et RSA dans les JWT + Introduction aux algorithmes de signature EC et RSA dans JWT diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 0c701ece5da..8f607d04a7d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,80 +1,82 @@ --- -description: Découvrez comment utiliser l’Account API pour gérer l’utilisateur (Learn how to use the Account API to manage user) +description: Découvrez comment utiliser l'Account API pour gérer les utilisateurs sidebar_position: 1 --- -# Paramètres du compte via l’Account API +# Paramètres de compte par Account API -## Qu’est-ce que l’Account API de Logto \{#what-is-logto-account-api} +## Qu'est-ce que Logto Account API \{#what-is-logto-account-api} -L’Account API de Logto est un ensemble complet d’API qui donne aux utilisateurs finaux un accès direct à l’API sans avoir besoin de passer par la Management API. Voici les points clés : +Le Logto Account API est un ensemble complet d'API qui donne aux utilisateurs finaux un accès direct à l'API sans avoir besoin de passer par le Management API. Voici les points forts : -- Accès direct : L’Account API permet aux utilisateurs finaux d’accéder et de gérer directement leur propre profil de compte sans passer par la Management API. -- Gestion du profil utilisateur et des identités : Les utilisateurs peuvent gérer entièrement leur profil et leurs paramètres de sécurité, y compris la possibilité de mettre à jour les informations d’identité telles que l’e-mail, le téléphone et le mot de passe, ainsi que de gérer les connexions sociales. Le support de MFA et SSO arrive bientôt. -- Contrôle d’accès global : Les administrateurs disposent d’un contrôle global complet sur les paramètres d’accès et peuvent personnaliser chaque champ. -- Autorisation transparente : L’autorisation est plus simple que jamais ! Utilisez simplement `client.getAccessToken()` pour obtenir un jeton opaque d’accès pour OP (Logto), et attachez-le à l’en-tête Authorization sous la forme `Bearer `. +- Accès direct : L'Account API permet aux utilisateurs finaux d'accéder directement et de gérer leurs propres profils de compte sans nécessiter le relais du Management API. +- Gestion des profils et identités des utilisateurs : Les utilisateurs peuvent gérer entièrement leurs profils et paramètres de sécurité, y compris la possibilité de mettre à jour les informations d'identité telles que l'e-mail, le téléphone et le mot de passe, ainsi que de gérer les connexions sociales. Le support de MFA et SSO arrive bientôt. +- Contrôle d'accès global : Les administrateurs ont un contrôle total et global sur les paramètres d'accès et peuvent personnaliser chaque champ. +- Autorisation transparente : L'autorisation est plus facile que jamais ! Utilisez simplement `client.getAccessToken()` pour obtenir un jeton d’accès (Access token) opaque pour OP (Logto), et attachez-le à l'en-tête Authorization comme `Bearer `. -Avec l’Account API de Logto, vous pouvez construire un système de gestion de compte personnalisé comme une page de profil entièrement intégrée à Logto. +Avec le Logto Account API, vous pouvez construire un système de gestion de compte personnalisé comme une page de profil entièrement intégrée à Logto. -Voici quelques cas d’utilisation fréquents : +Voici quelques cas d'utilisation fréquents : - Récupérer le profil utilisateur - Mettre à jour le profil utilisateur - Mettre à jour le mot de passe utilisateur -- Mettre à jour les identités utilisateur, y compris l’e-mail, le téléphone et les connexions sociales +- Mettre à jour les identités utilisateur, y compris l'e-mail, le téléphone et les connexions sociales - Gérer les facteurs MFA (vérifications) - Gérer les sessions utilisateur +- Gérer les applications autorisées par l'utilisateur (grants) -Pour en savoir plus sur les API disponibles, veuillez consulter la [référence de l’Account API de Logto](https://openapi.logto.io/group/endpoint-my-account) et la [référence de la Verification API de Logto](https://openapi.logto.io/group/endpoint-verifications). +Pour en savoir plus sur les API disponibles, veuillez visiter [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) et [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). :::note -Les fonctionnalités de visualisation de compte SSO et de suppression de compte sont actuellement disponibles via les Management APIs de Logto. Voir [Paramètres du compte via la Management API](/end-user-flows/account-settings/by-management-api) pour les détails d’implémentation. +Les fonctionnalités de visualisation de compte SSO et de suppression de compte sont actuellement disponibles via les Logto Management APIs. Voir [Paramètres de compte par Management API](/end-user-flows/account-settings/by-management-api) pour les détails de l'implémentation. ::: -## Comment activer l’Account API \{#how-to-enable-account-api} +## Comment activer l'Account API \{#how-to-enable-account-api} -Allez dans Console > Connexion & compte > Centre de compte. +Accédez à Console > Connexion & compte > Centre de compte. -L’Account API est désactivée par défaut, donc ses contrôles d’accès sont verrouillés. Activez **Enable Account API** pour l’activer. +L'Account API est désactivé par défaut, donc ses contrôles d'accès sont verrouillés. Basculez **Activer l'Account API** pour l'activer. -Une fois activée, configurez les permissions par champ pour les identifiants, les données de profil et l’accès aux jetons tiers. Chaque champ prend en charge `Off`, `ReadOnly` ou `Edit` ; la valeur par défaut est `Off`. +Une fois activé, configurez les permissions par champ pour les identifiants, les données de profil et l'accès aux jetons tiers. Chaque champ prend en charge `Off`, `ReadOnly` ou `Edit`; la valeur par défaut est `Off`. 1. **Champs de sécurité** : - Les champs incluent : e-mail principal, téléphone principal, identités sociales, mot de passe et MFA. - - Avant que les utilisateurs finaux n’éditent ces champs, ils doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d’enregistrement de vérification valable 10 minutes. Voir [Obtenir un ID d’enregistrement de vérification](#get-a-verification-record-id). - - Pour utiliser les passkeys WebAuthn pour MFA, ajoutez les domaines de votre application front-end à **WebAuthn Related Origins** afin que le centre de compte et l’expérience de connexion puissent partager les passkeys. Voir [Lier une nouvelle passkey WebAuthn](#link-a-new-webauthn-passkey). + - Avant que les utilisateurs finaux puissent modifier ces champs, ils doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d'enregistrement de vérification de 10 minutes. Voir [Obtenir un ID d'enregistrement de vérification](#get-a-verification-record-id). + - Pour utiliser les clés de passe WebAuthn pour MFA, ajoutez les domaines de votre application frontale à **WebAuthn Related Origins** afin que le centre de compte et l'expérience de connexion puissent partager les clés de passe. Voir [Lier une nouvelle clé de passe WebAuthn](#link-a-new-webauthn-passkey). 2. **Champs de profil** : - - Les champs incluent : nom d’utilisateur, nom, avatar, [profil](/user-management/user-data#profile) (autres attributs standard du profil), et [données personnalisées](/user-management/user-data#custom-data). - - Les utilisateurs finaux peuvent éditer ces champs sans vérification supplémentaire. -3. **Secret vault** : - - Pour les connecteurs sociaux et d’entreprise OIDC ou OAuth, le [secret vault](/secret-vault/federated-token-set) de Logto stocke en toute sécurité les jetons d’accès et de rafraîchissement tiers après authentification. Les applications peuvent alors appeler des API externes, comme la synchronisation des événements Google Calendar, sans demander à l’utilisateur de se reconnecter. La récupération des jetons devient disponible automatiquement une fois l’Account API activée. + - Les champs incluent : nom d'utilisateur, nom, avatar, [profil](/user-management/user-data#profile) (autres attributs de profil standard), et [données personnalisées](/user-management/user-data#custom-data). + - Les utilisateurs finaux peuvent modifier ceux-ci sans vérification supplémentaire. +3. **Coffre-fort secret** : + - Pour les connecteurs sociaux et d'entreprise OIDC ou OAuth, Logto [coffre-fort secret](/secret-vault/federated-token-set) stocke en toute sécurité les jetons d’accès (Access tokens) et de rafraîchissement (Refresh tokens) tiers après l'authentification. Les applications peuvent ensuite appeler des API externes, telles que la synchronisation des événements Google Calendar, sans demander aux utilisateurs de se reconnecter. La récupération des jetons devient automatiquement disponible une fois l'Account API activé. 4. **Gestion des sessions** : - - Lorsqu’elle est activée, les utilisateurs peuvent voir et gérer leurs sessions actives, y compris les informations sur l’appareil et la dernière connexion. Ils peuvent aussi révoquer des sessions pour se déconnecter de certains appareils. - - Avant d’accéder à la gestion des sessions, les utilisateurs doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d’enregistrement de vérification valable 10 minutes. Voir [Obtenir un ID d’enregistrement de vérification](#get-a-verification-record-id). + - Lorsqu'elle est activée, les utilisateurs peuvent voir et gérer leurs sessions actives, y compris les informations sur l'appareil et la dernière heure de connexion. Les utilisateurs peuvent également révoquer des sessions pour se déconnecter de certains appareils. + - Ce même champ de permission `Sessions` contrôle également les APIs des applications autorisées par l'utilisateur (grants) (voir et révoquer les grants). + - Avant que les utilisateurs finaux puissent accéder à la gestion des sessions, ils doivent vérifier leur identité via mot de passe, e-mail ou SMS pour obtenir un ID d'enregistrement de vérification de 10 minutes. Voir [Obtenir un ID d'enregistrement de vérification](#get-a-verification-record-id). -## Comment accéder à l’Account API \{#how-to-access-account-api} +## Comment accéder à l'Account API \{#how-to-access-account-api} :::note -Pour garantir que le jeton d’accès dispose des permissions appropriées, assurez-vous d’avoir correctement configuré les portées correspondantes dans votre configuration Logto. +Pour garantir que le jeton d’accès (Access token) dispose des permissions appropriées, assurez-vous d'avoir correctement configuré les portées correspondantes dans votre configuration Logto. -Par exemple, pour l’API `POST /api/my-account/primary-email`, vous devez configurer la portée `email` ; pour l’API `POST /api/my-account/primary-phone`, vous devez configurer la portée `phone`. +Par exemple, pour l'API `POST /api/my-account/primary-email`, vous devez configurer la portée `email`; pour l'API `POST /api/my-account/primary-phone`, vous devez configurer la portée `phone`. ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...autres options - // Ajoutez les portées adaptées à vos cas d’usage. + // Ajoutez les portées appropriées qui correspondent à vos cas d'utilisation. scopes: [ UserScope.Email, // Pour les APIs `{POST,DELETE} /api/my-account/primary-email` UserScope.Phone, // Pour les APIs `{POST,DELETE} /api/my-account/primary-phone` UserScope.CustomData, // Pour gérer les données personnalisées - UserScope.Address, // Pour gérer l’adresse - UserScope.Identities, // Pour les APIs liées à l’identité et au MFA + UserScope.Address, // Pour gérer l'adresse + UserScope.Identities, // Pour les APIs liées à l'identité et MFA UserScope.Profile, // Pour gérer le profil utilisateur - UserScope.Sessions, // Pour gérer les sessions utilisateur + UserScope.Sessions, // Pour gérer les sessions utilisateur et les grants d'application ], }; ``` @@ -83,33 +85,33 @@ const config: LogtoConfig = { ### Récupérer un jeton d’accès \{#fetch-an-access-token} -Après avoir configuré le SDK dans votre application, vous pouvez utiliser la méthode `client.getAccessToken()` pour récupérer un jeton d’accès. Ce jeton est un jeton opaque qui peut être utilisé pour accéder à l’Account API. +Après avoir configuré le SDK dans votre application, vous pouvez utiliser la méthode `client.getAccessToken()` pour récupérer un jeton d’accès. Ce jeton est un jeton d’accès (Access token) opaque qui peut être utilisé pour accéder à l'Account API. -Si vous n’utilisez pas le SDK officiel, vous devez définir le champ `resource` comme vide lors de la demande de jeton d’accès à `/oidc/token`. +Si vous n'utilisez pas le SDK officiel, vous devez définir le `resource` à vide pour la requête de jeton d’accès à `/oidc/token`. -### Accéder à l’Account API avec le jeton d’accès \{#access-account-api-using-access-token} +### Accéder à l'Account API en utilisant le jeton d’accès \{#access-account-api-using-access-token} -Vous devez inclure le jeton d’accès dans le champ `Authorization` des en-têtes HTTP au format Bearer (`Bearer YOUR_TOKEN`) lors de l’interaction avec l’Account API. +Vous devez inclure le jeton d’accès dans le champ `Authorization` des en-têtes HTTP avec le format Bearer (`Bearer YOUR_TOKEN`) lors de l'interaction avec l'Account API. -Voici un exemple pour obtenir les informations du compte utilisateur : +Voici un exemple pour obtenir les informations de compte utilisateur : ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## Gérer les informations de base du compte \{#manage-basic-account-information} +## Gérer les informations de compte de base \{#manage-basic-account-information} -### Récupérer les informations du compte utilisateur \{#retrieve-user-account-information} +### Récupérer les informations de compte utilisateur \{#retrieve-user-account-information} -Pour obtenir les données utilisateur, vous pouvez utiliser l’endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). +Pour obtenir les données utilisateur, vous pouvez utiliser le point de terminaison [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -120,13 +122,13 @@ Le corps de la réponse sera similaire à : } ``` -Les champs de la réponse peuvent varier selon les paramètres du centre de compte. +Les champs de réponse peuvent varier en fonction des paramètres du centre de compte. -### Mettre à jour les informations de base du compte \{#update-basic-account-information} +### Mettre à jour les informations de compte de base \{#update-basic-account-information} -Les informations de base du compte incluent le nom d’utilisateur, le nom, l’avatar, les données personnalisées et d’autres informations de profil. +Les informations de compte de base incluent le nom d'utilisateur, le nom, l'avatar, les données personnalisées et d'autres informations de profil. -Pour mettre à jour **username, name, avatar, et customData**, vous pouvez utiliser l’endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). +Pour mettre à jour **username, name, avatar, et customData**, vous pouvez utiliser le point de terminaison [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -Pour mettre à jour d’autres informations de profil, y compris **familyName, givenName, middleName, nickname, profile (URL de la page de profil), website, gender, birthdate, zoneinfo, locale, et address**, vous pouvez utiliser l’endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). +Pour mettre à jour d'autres informations de profil, y compris **familyName, givenName, middleName, nickname, profile (URL de la page de profil), website, gender, birthdate, zoneinfo, locale, et address**, vous pouvez utiliser le point de terminaison [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -146,15 +148,15 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Gérer les identifiants et autres informations sensibles \{#manage-identifiers-and-other-sensitive-information} -Pour des raisons de sécurité, l’Account API nécessite une couche supplémentaire d’autorisation pour les opérations impliquant des identifiants et d’autres informations sensibles. +Pour des raisons de sécurité, l'Account API nécessite une couche supplémentaire d'autorisation pour les opérations impliquant des identifiants et d'autres informations sensibles. -### Obtenir un ID d’enregistrement de vérification \{#get-a-verification-record-id} +### Obtenir un ID d'enregistrement de vérification \{#get-a-verification-record-id} -Vous devez d’abord obtenir un **ID d’enregistrement de vérification** avec une expiration de 10 minutes (TTL). Cela permet de vérifier l’identité de l’utilisateur avant de mettre à jour des informations sensibles. Cela signifie qu’une fois qu’un utilisateur a vérifié son identité via mot de passe, code de vérification par e-mail ou code de vérification par SMS, il dispose de 10 minutes pour mettre à jour ses données liées à l’authentification, y compris les identifiants, les identifiants de connexion, la liaison de compte social et le MFA. +Tout d'abord, vous devez obtenir un **ID d'enregistrement de vérification** avec une expiration de 10 minutes (TTL). Cela peut être utilisé pour vérifier l'identité de l'utilisateur avant de mettre à jour des informations sensibles. Cela signifie qu'une fois qu'un utilisateur a vérifié avec succès son identité via mot de passe, code de vérification par e-mail ou code de vérification par SMS, il dispose de 10 minutes pour mettre à jour ses données liées à l'authentification, y compris les identifiants, les informations d'identification, le lien de compte social et MFA. -Pour obtenir un ID d’enregistrement de vérification, vous pouvez [vérifier le mot de passe de l’utilisateur](#verify-the-users-password) ou [envoyer un code de vérification à l’e-mail ou au téléphone de l’utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +Pour obtenir un ID d'enregistrement de vérification, vous pouvez [vérifier le mot de passe de l'utilisateur](#verify-the-users-password) ou [envoyer un code de vérification à l'e-mail ou au téléphone de l'utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -#### Vérifier le mot de passe de l’utilisateur \{#verify-the-users-password} +#### Vérifier le mot de passe de l'utilisateur \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -172,13 +174,13 @@ Le corps de la réponse sera similaire à : } ``` -#### Vérifier en envoyant un code de vérification à l’e-mail ou au téléphone de l’utilisateur \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### Vérifier en envoyant un code de vérification à l'e-mail ou au téléphone de l'utilisateur \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -Pour utiliser cette méthode, vous devez [configurer le connecteur e-mail](/connectors/email-connectors/) ou [le connecteur SMS](/connectors/sms-connectors/), et vous assurer que le template `UserPermissionValidation` est configuré. +Pour utiliser cette méthode, vous devez [configurer le connecteur e-mail](/connectors/email-connectors/) ou [connecteur SMS](/connectors/sms-connectors/), et vous assurer que le modèle `UserPermissionValidation` est configuré. ::: -Prenons l’e-mail comme exemple, demandez un nouveau code de vérification et obtenez l’ID d’enregistrement de vérification : +Prenons l'e-mail comme exemple, demandez un nouveau code de vérification et obtenez l'ID d'enregistrement de vérification : ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -196,7 +198,7 @@ Le corps de la réponse sera similaire à : } ``` -Après avoir reçu le code de vérification, vous pouvez l’utiliser pour mettre à jour le statut de vérification de l’enregistrement. +Après avoir reçu le code de vérification, vous pouvez l'utiliser pour mettre à jour le statut de vérification de l'enregistrement de vérification. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -205,17 +207,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Après avoir vérifié le code, vous pouvez maintenant utiliser l’ID d’enregistrement de vérification pour mettre à jour l’identifiant de l’utilisateur. +Après avoir vérifié le code, vous pouvez maintenant utiliser l'ID d'enregistrement de vérification pour mettre à jour l'identifiant de l'utilisateur. -Pour en savoir plus sur les vérifications, veuillez consulter [Vérification de sécurité via l’Account API](/end-user-flows/security-verification). +Pour en savoir plus sur les vérifications, veuillez vous référer à [Vérification de sécurité par Account API](/end-user-flows/security-verification). -### Envoyer une requête avec l’ID d’enregistrement de vérification \{#send-request-with-verification-record-id} +### Envoyer une requête avec l'ID d'enregistrement de vérification \{#send-request-with-verification-record-id} -Lors de l’envoi d’une requête pour mettre à jour l’identifiant de l’utilisateur, vous devez inclure l’ID d’enregistrement de vérification dans l’en-tête de la requête avec le champ `logto-verification-id`. +Lors de l'envoi d'une requête pour mettre à jour l'identifiant de l'utilisateur, vous devez inclure l'ID d'enregistrement de vérification dans l'en-tête de la requête avec le champ `logto-verification-id`. -### Mettre à jour le mot de passe de l’utilisateur \{#update-users-password} +### Mettre à jour le mot de passe de l'utilisateur \{#update-users-password} -Pour mettre à jour le mot de passe de l’utilisateur, vous pouvez utiliser l’endpoint [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword). +Pour mettre à jour le mot de passe de l'utilisateur, vous pouvez utiliser le point de terminaison [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword). ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -226,18 +228,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -Comme les mots de passe créés lors de l’inscription, les mots de passe définis via l’Account API doivent respecter la [politique de mot de passe](/security/password-policy) que vous avez configurée dans Console > Sécurité > Politique de mot de passe. Logto retourne des résultats de validation détaillés et des messages d’erreur si le mot de passe ne respecte pas la politique. +Tout comme les mots de passe créés lors de l'inscription, les mots de passe définis via l'Account API doivent respecter la [politique de mot de passe](/security/password-policy) que vous avez configurée dans Console > Sécurité > Politique de mot de passe. Logto renvoie des résultats de validation détaillés et des messages d'erreur si le mot de passe ne respecte pas la politique. ::: ### Mettre à jour ou lier un nouvel e-mail \{#update-or-link-new-email} :::note -Pour utiliser cette méthode, vous devez [configurer le connecteur e-mail](/connectors/email-connectors/) et vous assurer que le template `BindNewIdentifier` est configuré. +Pour utiliser cette méthode, vous devez [configurer le connecteur e-mail](/connectors/email-connectors/), et vous assurer que le modèle `BindNewIdentifier` est configuré. ::: -Pour mettre à jour ou lier un nouvel e-mail, vous devez d’abord prouver la propriété de l’e-mail. +Pour mettre à jour ou lier un nouvel e-mail, vous devez d'abord prouver la propriété de l'e-mail. -Appelez l’endpoint [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) pour demander un code de vérification. +Appelez le point de terminaison [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) pour demander un code de vérification. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Vous trouverez un `verificationId` dans la réponse, et recevrez un code de vérification par e-mail, utilisez-le pour vérifier l’e-mail. +Vous trouverez un `verificationId` dans la réponse, et recevrez un code de vérification dans l'e-mail, utilisez-le pour vérifier l'e-mail. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,34 +257,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Après avoir vérifié le code, vous pouvez maintenant appeler [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) pour mettre à jour l’e-mail de l’utilisateur, en mettant le `verificationId` dans le corps de la requête sous `newIdentifierVerificationRecordId`. +Après avoir vérifié le code, vous pouvez maintenant appeler [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) pour mettre à jour l'e-mail de l'utilisateur, définissez le `verificationId` dans le corps de la requête comme `newIdentifierVerificationRecordId`. -:::info[Deux IDs d’enregistrement de vérification différents] +:::info[Deux ID d'enregistrement de vérification différents] -Cette requête nécessite deux IDs d’enregistrement de vérification distincts : +Cette requête nécessite deux ID d'enregistrement de vérification distincts : -- **`logto-verification-id` (en-tête)** : Prouve l’identité de l’utilisateur avant d’effectuer des modifications sensibles. Obtenez-le en [vérifiant le mot de passe de l’utilisateur](#verify-the-users-password) ou en [envoyant un code de vérification à l’e-mail ou au téléphone existant de l’utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (corps)** : Prouve la propriété de la nouvelle adresse e-mail. Il s’agit du `verificationRecordId` retourné par l’appel `POST /api/verifications/verification-code` ci-dessus. +- **`logto-verification-id` (en-tête)** : Prouve l'identité de l'utilisateur avant d'apporter des modifications sensibles. Obtenez-le en [vérifiant le mot de passe de l'utilisateur](#verify-the-users-password) ou en [envoyant un code de vérification à l'e-mail ou au téléphone existant de l'utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (corps)** : Prouve la propriété de la nouvelle adresse e-mail. C'est le `verificationRecordId` retourné par l'appel `POST /api/verifications/verification-code` ci-dessus. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # Vérifie l’identité utilisateur (depuis le mot de passe ou la vérification e-mail/téléphone existant) + # Vérifie l'identité de l'utilisateur (à partir du mot de passe ou de la vérification de l'e-mail/téléphone existant) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # Le "newIdentifierVerificationRecordId" prouve la propriété du nouvel e-mail (issu du flux de code de vérification ci-dessus) + # Le "newIdentifierVerificationRecordId" prouve la propriété du nouvel e-mail (à partir du flux de code de vérification ci-dessus) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -Comme les e-mails collectés lors de l’inscription, tout e-mail lié via l’Account API doit passer la vérification de la [blocklist](/security/blocklist) que vous avez configurée dans Console > Sécurité > Blocklist. Logto rejettera la requête et retournera une erreur détaillée si l’e-mail viole la politique. +Tout comme les e-mails collectés lors de l'inscription, tout e-mail lié via l'Account API doit passer la vérification de la [liste de blocage](/security/blocklist) que vous avez configurée dans Console > Sécurité > Liste de blocage. Logto rejettera la requête et renverra une erreur détaillée si l'e-mail viole la politique. ::: -### Supprimer l’e-mail de l’utilisateur \{#remove-the-users-email} +### Supprimer l'e-mail de l'utilisateur \{#remove-the-users-email} -Pour supprimer l’e-mail de l’utilisateur, vous pouvez utiliser l’endpoint [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail). +Pour supprimer l'e-mail de l'utilisateur, vous pouvez utiliser le point de terminaison [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail). ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -293,14 +295,14 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Gérer le téléphone \{#manage-phone} :::note -Pour utiliser cette méthode, vous devez [configurer le connecteur SMS](/connectors/sms-connectors/) et vous assurer que le template `BindNewIdentifier` est configuré. +Pour utiliser cette méthode, vous devez [configurer le connecteur SMS](/connectors/sms-connectors/), et vous assurer que le modèle `BindNewIdentifier` est configuré. ::: -De façon similaire à la mise à jour de l’e-mail, vous pouvez utiliser l’endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) pour mettre à jour ou lier un nouveau téléphone. Et utiliser l’endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) pour supprimer le téléphone de l’utilisateur. +Similaire à la mise à jour de l'e-mail, vous pouvez utiliser le point de terminaison [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) pour mettre à jour ou lier un nouveau téléphone. Et utilisez le point de terminaison [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) pour supprimer le téléphone de l'utilisateur. ### Lier une nouvelle connexion sociale \{#link-a-new-social-connection} -Pour lier une nouvelle connexion sociale, vous devez d’abord demander une URL d’autorisation avec [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial). +Pour lier une nouvelle connexion sociale, vous devez d'abord demander une URL d'autorisation avec [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial). ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -309,13 +311,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId` : L’ID du [connecteur social](/connectors/social-connectors/). -- `redirectUri` : L’URI de redirection après que l’utilisateur a autorisé l’application, vous devez héberger une page web à cette URL et capturer le callback. -- `state` : L’état à retourner après que l’utilisateur a autorisé l’application, c’est une chaîne aléatoire utilisée pour prévenir les attaques CSRF. +- `connectorId` : L'ID du [connecteur social](/connectors/social-connectors/). +- `redirectUri` : L'URI de redirection après que l'utilisateur a autorisé l'application, vous devez héberger une page web à cette URL et capturer le rappel. +- `state` : L'état à retourner après que l'utilisateur a autorisé l'application, c'est une chaîne aléatoire utilisée pour prévenir les attaques CSRF. Dans la réponse, vous trouverez un `verificationRecordId`, conservez-le pour une utilisation ultérieure. -Après que l’utilisateur a autorisé l’application, vous recevrez un callback à l’`redirectUri` avec le paramètre `state`. Vous pouvez alors utiliser l’endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) pour vérifier la connexion sociale. +Après que l'utilisateur a autorisé l'application, vous recevrez un rappel à l'`redirectUri` avec le paramètre `state`. Ensuite, vous pouvez utiliser le point de terminaison [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) pour vérifier la connexion sociale. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,32 +326,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -Le `connectorData` est la donnée retournée par le connecteur social après que l’utilisateur a autorisé l’application, vous devez analyser et récupérer les paramètres de requête depuis le `redirectUri` dans votre page de callback, et les encapsuler en JSON comme valeur du champ `connectorData`. +Le `connectorData` est les données retournées par le connecteur social après que l'utilisateur a autorisé l'application, vous devez analyser et obtenir les paramètres de requête de l'`redirectUri` dans votre page de rappel, et les envelopper sous forme de JSON comme valeur du champ `connectorData`. -Enfin, vous pouvez utiliser l’endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) pour lier la connexion sociale. +Enfin, vous pouvez utiliser le point de terminaison [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) pour lier la connexion sociale. -:::info[Deux IDs d’enregistrement de vérification différents] +:::info[Deux ID d'enregistrement de vérification différents] -Cette requête nécessite deux IDs d’enregistrement de vérification distincts : +Cette requête nécessite deux ID d'enregistrement de vérification distincts : -- **`logto-verification-id` (en-tête)** : Prouve l’identité de l’utilisateur avant d’effectuer des modifications sensibles. Obtenez-le en [vérifiant le mot de passe de l’utilisateur](#verify-the-users-password) ou en [envoyant un code de vérification à l’e-mail ou au téléphone existant de l’utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (corps)** : Identifie l’identité sociale à lier. Il s’agit du `verificationRecordId` retourné par l’appel `POST /api/verifications/social` ci-dessus. +- **`logto-verification-id` (en-tête)** : Prouve l'identité de l'utilisateur avant d'apporter des modifications sensibles. Obtenez-le en [vérifiant le mot de passe de l'utilisateur](#verify-the-users-password) ou en [envoyant un code de vérification à l'e-mail ou au téléphone existant de l'utilisateur](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (corps)** : Identifie l'identité sociale à lier. C'est le `verificationRecordId` retourné par l'appel `POST /api/verifications/social` ci-dessus. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # Vérifie l’identité utilisateur (depuis le mot de passe ou la vérification e-mail/téléphone existant) + # Vérifie l'identité de l'utilisateur (à partir du mot de passe ou de la vérification de l'e-mail/téléphone existant) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # Le "newIdentifierVerificationRecordId" identifie la connexion sociale à lier (issu du flux de vérification sociale ci-dessus) + # Le "newIdentifierVerificationRecordId" identifie la connexion sociale à lier (à partir du flux de vérification sociale ci-dessus) --data-raw '{"newIdentifierVerificationRecordId":""}' ``` ### Supprimer une connexion sociale \{#remove-a-social-connection} -Pour supprimer une connexion sociale, vous pouvez utiliser l’endpoint [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity). +Pour supprimer une connexion sociale, vous pouvez utiliser le point de terminaison [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity). ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -357,30 +359,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Lier une nouvelle passkey WebAuthn \{#link-a-new-webauthn-passkey} +### Lier une nouvelle clé de passe WebAuthn \{#link-a-new-webauthn-passkey} :::note -N’oubliez pas d’[activer MFA et WebAuthn](/end-user-flows/mfa) d’abord. +N'oubliez pas d'[activer MFA et WebAuthn](/end-user-flows/mfa) d'abord. ::: :::note Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les [paramètres du centre de compte](#how-to-enable-account-api). ::: -**Étape 1 : Ajoutez l’origine de votre application front-end aux origines associées** +**Étape 1 : Ajouter l'origine de votre application frontale aux origines associées** -Les passkeys WebAuthn sont liées à un nom d’hôte spécifique appelé **Relying Party ID (RP ID)**. Seules les applications hébergées sur l’origine du RP ID peuvent enregistrer ou s’authentifier avec ces passkeys. +Les clés de passe WebAuthn sont liées à un nom d'hôte spécifique appelé **Relying Party ID (RP ID)**. Seules les applications hébergées sur l'origine du RP ID peuvent enregistrer ou s'authentifier avec ces clés de passe. -Puisque votre application front-end appelle l’Account API depuis un domaine différent de celui des pages d’authentification de Logto, vous devez configurer les **Related Origins** pour permettre les opérations de passkey cross-origin. +Étant donné que votre application frontale appelle l'Account API depuis un domaine différent de celui des pages d'authentification de Logto, vous devez configurer les **Origines associées** pour autoriser les opérations de clé de passe inter-origines. **Comment Logto détermine le RP ID :** - **Configuration par défaut** : Si vous utilisez uniquement le domaine par défaut de Logto `https://[tenant-id].logto.app`, le RP ID est `[tenant-id].logto.app` - **Domaine personnalisé** : Si vous avez configuré un [domaine personnalisé](/logto-cloud/custom-domain) comme `https://auth.example.com`, le RP ID devient `auth.example.com` -**Configurer les Related Origins :** +**Configurer les Origines associées :** -Utilisez l’endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) pour ajouter l’origine de votre application front-end. Par exemple, si le centre de compte de votre application fonctionne sur `https://account.example.com` : +Utilisez le point de terminaison [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) pour ajouter l'origine de votre application frontale. Par exemple, si le centre de compte de votre application fonctionne sur `https://account.example.com` : ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn prend en charge jusqu’à 5 labels eTLD+1 uniques pour les Related Origins. L’eTLD+1 (effective top-level domain plus un label) est la partie du domaine enregistrable. Par exemple : +WebAuthn prend en charge jusqu'à 5 étiquettes eTLD+1 uniques pour les Origines associées. Le eTLD+1 (domaine de premier niveau effectif plus une étiquette) est la partie du domaine enregistrable. Par exemple : -- `https://example.com`, `https://app.example.com` et `https://auth.example.com` comptent pour **un** label (`example.com`) -- `https://shopping.com`, `https://shopping.co.uk` et `https://shopping.co.jp` comptent aussi pour **un** label (`shopping`) -- `https://example.com` et `https://another.com` comptent pour **deux** labels +- `https://example.com`, `https://app.example.com`, et `https://auth.example.com` comptent comme **une** étiquette (`example.com`) +- `https://shopping.com`, `https://shopping.co.uk`, et `https://shopping.co.jp` comptent également comme **une** étiquette (`shopping`) +- `https://example.com` et `https://another.com` comptent comme **deux** étiquettes -Si vous devez prendre en charge plus de 5 domaines différents comme Related Origins, consultez la documentation [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) pour plus de détails. +Si vous devez prendre en charge plus de 5 domaines différents en tant qu'Origines associées, consultez la documentation [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) pour plus de détails. ::: -**Étape 2 : Demander de nouvelles options d’enregistrement** +**Étape 2 : Demander de nouvelles options d'enregistrement** -Utilisez l’endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) pour demander l’enregistrement d’une nouvelle passkey. Logto permet à chaque compte utilisateur d’enregistrer plusieurs passkeys. +Utilisez le point de terminaison [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) pour demander l'enregistrement d'une nouvelle clé de passe. Logto permet à chaque compte utilisateur d'enregistrer plusieurs clés de passe. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -421,25 +423,25 @@ Vous obtiendrez une réponse comme : } ``` -**Étape 3 : Enregistrer la passkey dans le navigateur local** +**Étape 3 : Enregistrer la clé de passe dans le navigateur local** -Prenons [`@simplewebauthn/browser`](https://simplewebauthn.dev/) comme exemple, vous pouvez utiliser la fonction `startRegistration` pour enregistrer la passkey dans le navigateur local. +Prenons [`@simplewebauthn/browser`](https://simplewebauthn.dev/) comme exemple, vous pouvez utiliser la fonction `startRegistration` pour enregistrer la clé de passe dans le navigateur local. ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // Les données retournées par le serveur à l’étape 1 + optionsJSON: registrationOptions, // Les données retournées par le serveur à l'étape 1 }); -// Sauvegardez la réponse pour une utilisation ultérieure +// Enregistrez la réponse pour une utilisation ultérieure ``` -**Étape 4 : Vérifier l’enregistrement de la passkey** +**Étape 4 : Vérifier l'enregistrement de la clé de passe** -Utilisez l’endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) pour vérifier l’enregistrement de la passkey. +Utilisez le point de terminaison [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) pour vérifier l'enregistrement de la clé de passe. -Cette étape vérifie la signature cryptographique générée par l’authentificateur pour s’assurer que la passkey a bien été créée et n’a pas été altérée pendant la transmission. +Cette étape vérifie la signature cryptographique générée par l'authentificateur pour s'assurer que la clé de passe a été légitimement créée et n'a pas été altérée pendant la transmission. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -448,12 +450,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload` : La réponse du navigateur local à l’étape 2. -- `verificationRecordId` : L’ID d’enregistrement de vérification retourné par le serveur à l’étape 1. +- `payload` : La réponse du navigateur local à l'étape 2. +- `verificationRecordId` : L'ID d'enregistrement de vérification retourné par le serveur à l'étape 1. -**Étape 5 : Lier la passkey** +**Étape 5 : Lier la clé de passe** -Enfin, vous pouvez lier la passkey au compte utilisateur en utilisant l’endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). +Enfin, vous pouvez lier la clé de passe au compte de l'utilisateur en utilisant le point de terminaison [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id` : un ID d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur, voir la section [Obtenir un ID d’enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. -- `type` : le type du facteur MFA, actuellement seul `WebAuthn` est supporté. -- `newIdentifierVerificationRecordId` : l’ID d’enregistrement de vérification retourné par le serveur à l’étape 1. +- `verification_record_id` : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur, vous pouvez vous référer à la section [Obtenir un ID d'enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. +- `type` : le type du facteur MFA, actuellement seul `WebAuthn` est pris en charge. +- `newIdentifierVerificationRecordId` : l'ID d'enregistrement de vérification retourné par le serveur à l'étape 1. -### Gérer les passkeys WebAuthn existantes \{#manage-existing-webauthn-passkeys} +### Gérer les clés de passe WebAuthn existantes \{#manage-existing-webauthn-passkeys} -Pour gérer les passkeys WebAuthn existantes, vous pouvez utiliser l’endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) pour obtenir les passkeys actuelles et autres facteurs de vérification MFA. +Pour gérer les clés de passe WebAuthn existantes, vous pouvez utiliser le point de terminaison [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) pour obtenir les clés de passe actuelles et d'autres facteurs de vérification MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json [ @@ -491,12 +493,12 @@ Le corps de la réponse sera similaire à : ] ``` -- `id` : l’ID de la vérification. -- `type` : le type de la vérification, `WebAuthn` pour une passkey WebAuthn. -- `name` : le nom de la passkey, champ optionnel. -- `agent` : l’agent utilisateur de la passkey. +- `id` : l'ID de la vérification. +- `type` : le type de la vérification, `WebAuthn` pour la clé de passe WebAuthn. +- `name` : le nom de la clé de passe, champ optionnel. +- `agent` : l'agent utilisateur de la clé de passe. -Mettez à jour le nom de la passkey avec l’endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) : +Mettre à jour le nom de la clé de passe en utilisant le point de terminaison [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) : ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Supprimez la passkey avec l’endpoint [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) : +Supprimer la clé de passe en utilisant le point de terminaison [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) : ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -517,7 +519,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v ### Lier un nouveau TOTP \{#link-a-new-totp} :::note -N’oubliez pas d’[activer MFA et TOTP](/end-user-flows/mfa) d’abord. +N'oubliez pas d'[activer MFA et TOTP](/end-user-flows/mfa) d'abord. ::: :::note @@ -526,7 +528,7 @@ Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les [param **Étape 1 : Générer un secret TOTP** -Utilisez l’endpoint [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) pour générer un secret TOTP. +Utilisez le point de terminaison [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) pour générer un secret TOTP. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -542,11 +544,11 @@ Le corps de la réponse sera similaire à : } ``` -**Étape 2 : Afficher le secret TOTP à l’utilisateur** +**Étape 2 : Afficher le secret TOTP à l'utilisateur** -Utilisez le secret pour générer un QR code ou l’afficher directement à l’utilisateur. L’utilisateur doit l’ajouter à son application d’authentification (comme Google Authenticator, Microsoft Authenticator ou Authy). +Utilisez le secret pour générer un code QR ou l'afficher directement à l'utilisateur. L'utilisateur doit l'ajouter à son application d'authentification (telle que Google Authenticator, Microsoft Authenticator ou Authy). -Le format URI pour le QR code doit être : +Le format URI pour le code QR doit être : ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -560,7 +562,7 @@ otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp **Étape 3 : Lier le facteur TOTP** -Après que l’utilisateur a ajouté le secret à son application d’authentification, il doit le vérifier et le lier à son compte. Utilisez l’endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) pour lier le facteur TOTP. +Après que l'utilisateur a ajouté le secret à son application d'authentification, il doit le vérifier et le lier à son compte. Utilisez le point de terminaison [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) pour lier le facteur TOTP. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,18 +572,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id` : un ID d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur. Voir la section [Obtenir un ID d’enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. +- `verification_record_id` : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur. Vous pouvez vous référer à la section [Obtenir un ID d'enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. - `type` : doit être `Totp`. -- `secret` : le secret TOTP généré à l’étape 1. +- `secret` : le secret TOTP généré à l'étape 1. :::note -Un utilisateur ne peut avoir qu’un seul facteur TOTP à la fois. Si l’utilisateur a déjà un facteur TOTP, toute tentative d’en ajouter un autre entraînera une erreur 422. +Un utilisateur ne peut avoir qu'un seul facteur TOTP à la fois. Si l'utilisateur a déjà un facteur TOTP, tenter d'en ajouter un autre entraînera une erreur 422. ::: ### Gérer les codes de secours \{#manage-backup-codes} :::note -N’oubliez pas d’[activer MFA et les codes de secours](/end-user-flows/mfa) d’abord. +N'oubliez pas d'[activer MFA et les codes de secours](/end-user-flows/mfa) d'abord. ::: :::note @@ -590,7 +592,7 @@ Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les [param **Étape 1 : Générer de nouveaux codes de secours** -Utilisez l’endpoint [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) pour générer un nouvel ensemble de 10 codes de secours. +Utilisez le point de terminaison [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) pour générer un nouvel ensemble de 10 codes de secours. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -606,20 +608,20 @@ Le corps de la réponse sera similaire à : } ``` -**Étape 2 : Afficher les codes de secours à l’utilisateur** +**Étape 2 : Afficher les codes de secours à l'utilisateur** -Avant de lier les codes de secours au compte utilisateur, vous devez les afficher à l’utilisateur et lui demander de : +Avant de lier les codes de secours au compte de l'utilisateur, vous devez les afficher à l'utilisateur et lui indiquer de : - Télécharger ou noter ces codes immédiatement - Les stocker dans un endroit sécurisé -- Comprendre que chaque code ne peut être utilisé qu’une seule fois -- Savoir que ces codes sont leur dernier recours s’ils perdent l’accès à leurs méthodes MFA principales +- Comprendre que chaque code ne peut être utilisé qu'une seule fois +- Savoir que ces codes sont leur dernier recours s'ils perdent l'accès à leurs méthodes MFA principales -Vous devez afficher les codes dans un format clair, facile à copier, et envisager de proposer une option de téléchargement (par exemple, en fichier texte ou PDF). +Vous devez afficher les codes dans un format clair et facile à copier et envisager de fournir une option de téléchargement (par exemple, sous forme de fichier texte ou PDF). **Étape 3 : Lier les codes de secours au compte utilisateur** -Utilisez l’endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) pour lier les codes de secours au compte utilisateur. +Utilisez le point de terminaison [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) pour lier les codes de secours au compte de l'utilisateur. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id` : un ID d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur. Voir la section [Obtenir un ID d’enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. +- `verification_record_id` : un ID d'enregistrement de vérification valide, accordé en vérifiant le facteur existant de l'utilisateur. Vous pouvez vous référer à la section [Obtenir un ID d'enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. - `type` : doit être `BackupCode`. -- `codes` : le tableau des codes de secours générés à l’étape précédente. +- `codes` : le tableau des codes de secours générés à l'étape précédente. :::note -- Un utilisateur ne peut avoir qu’un seul ensemble de codes de secours à la fois. Si tous les codes ont été utilisés, l’utilisateur doit générer et lier de nouveaux codes. -- Les codes de secours ne peuvent pas être le seul facteur MFA. L’utilisateur doit avoir au moins un autre facteur MFA (comme WebAuthn ou TOTP) activé. -- Chaque code de secours ne peut être utilisé qu’une seule fois. +- Un utilisateur ne peut avoir qu'un seul ensemble de codes de secours à la fois. Si tous les codes ont été utilisés, l'utilisateur doit générer et lier de nouveaux codes. +- Les codes de secours ne peuvent pas être le seul facteur MFA. L'utilisateur doit avoir au moins un autre facteur MFA (tel que WebAuthn ou TOTP) activé. +- Chaque code de secours ne peut être utilisé qu'une seule fois. ::: **Voir les codes de secours existants** -Pour voir les codes de secours existants et leur statut d’utilisation, utilisez l’endpoint [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) : +Pour voir les codes de secours existants et leur statut d'utilisation, utilisez le point de terminaison [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) : ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -Le corps de la réponse sera similaire à : +Le corps de la réponse serait comme : ```json { @@ -668,18 +670,18 @@ Le corps de la réponse sera similaire à : ``` - `code` : le code de secours. -- `usedAt` : l’horodatage d’utilisation du code, `null` s’il n’a pas encore été utilisé. +- `usedAt` : l'horodatage lorsque le code a été utilisé, `null` s'il n'a pas encore été utilisé. ### Gérer les sessions utilisateur \{#manage-user-sessions} **Lister les sessions actives** -Pour lister les sessions actives de l’utilisateur, vous pouvez utiliser l’endpoint [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions). +Pour lister les sessions actives de l'utilisateur, vous pouvez utiliser le point de terminaison [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions). :::note -- La portée `UserScope.Sessions` est requise pour accéder à cet endpoint. -- Le champ `Sessions` dans les paramètres du centre de compte doit être réglé sur `ReadOnly` ou `Edit`. +- La portée `UserScope.Sessions` est requise pour accéder à ce point de terminaison. +- Le champ `Sessions` dans les paramètres du centre de compte doit être défini sur `ReadOnly` ou `Edit`. ::: @@ -692,12 +694,12 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ **Révoquer une session par ID de session** -Pour révoquer une session spécifique, utilisez l’endpoint [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid). +Pour révoquer une session spécifique, utilisez le point de terminaison [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid). :::note -- La portée `UserScope.Sessions` est requise pour accéder à cet endpoint. -- Le champ `Sessions` dans les paramètres du centre de compte doit être réglé sur `Edit`. +- La portée `UserScope.Sessions` est requise pour accéder à ce point de terminaison. +- Le champ `Sessions` dans les paramètres du centre de compte doit être défini sur `Edit`. ::: ```bash @@ -709,7 +711,58 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} Paramètres de requête optionnels : -- `revokeGrantsTarget` : Spécifiez éventuellement la cible des autorisations à révoquer avec la session. Valeurs possibles : - - `all` : Révoque toutes les autorisations associées à la session. - - `firstParty` : Révoque uniquement les autorisations des applications first-party associées à la session. (Recommandé dans la plupart des cas, car cela révoque l’accès pour votre propre application tout en conservant les autorisations des applications tierces, offrant une meilleure expérience utilisateur.) - - non spécifié : Le comportement par défaut révoque les autorisations qui n’ont pas la portée `offline_access`, ce qui signifie généralement la révocation des autorisations sans jeton de rafraîchissement pour la session. +- `revokeGrantsTarget` : Spécifiez éventuellement la cible des grants à révoquer avec la session. Valeurs possibles : + - `all` : Révoquer tous les grants associés à la session. + - `firstParty` : Révoquer uniquement les grants d'application de première partie associés à la session. (Recommandé pour la plupart des cas d'utilisation, car cela révoque l'accès pour votre propre application tout en conservant les grants d'application tierce intacts, offrant une meilleure expérience utilisateur.) + - non spécifié : Le comportement par défaut révoque les grants qui n'ont pas de portée `offline_access`, ce qui signifie généralement révoquer les grants non liés aux jetons de rafraîchissement pour la session. + +### Gérer les applications autorisées par l'utilisateur (grants) \{#manage-user-authorized-apps-grants} + +Utilisez les APIs des applications autorisées par l'utilisateur (grants) lorsque les utilisateurs ont besoin de revoir et de révoquer les applications autorisées depuis leur page de paramètres de compte. + +:::note + +- Les APIs de grant d'application partagent le même modèle de permission que les APIs de session. +- La portée `UserScope.Sessions` est requise. +- Le champ `Sessions` dans les paramètres du centre de compte doit être activé : + - `ReadOnly` ou `Edit` pour lister les grants. + - `Edit` pour révoquer les grants. + +::: + +**Lister les grants d'application actifs** + +Pour lister les grants d'application actifs de l'utilisateur actuel, utilisez le point de terminaison [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants). + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Paramètre de requête optionnel : + +- `appType=firstParty` : Retourner uniquement les grants d'application de première partie. +- `appType=thirdParty` : Retourner uniquement les grants d'application tierce. +- Omettre `appType` : Retourner tous les grants actifs. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**Révoquer un grant d'application par ID de grant** + +Pour révoquer un grant d'application spécifique, utilisez le point de terminaison [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid). + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Lorsqu'un grant est révoqué, les jetons d’accès (Access tokens) opaques et les jetons de rafraîchissement (Refresh tokens) précédemment émis pour ce grant sont invalidés. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index d4712958099..471d92a82ab 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -2,24 +2,24 @@ sidebar_position: 2 --- -# Paramètres du compte via Management API +# Paramètres de compte via Management API ## Intégrations \{#integrations} -Logto fournit diverses Management API pour gérer les comptes utilisateurs. Vous pouvez utiliser ces API pour construire une page de paramètres de compte en libre-service pour les utilisateurs finaux. +Logto fournit diverses Management API pour gérer les comptes utilisateurs. Vous pouvez utiliser ces API pour créer une page de paramètres de compte en libre-service pour les utilisateurs finaux. ### Architecture \{#architecture} ```mermaid graph TB A[Utilisateur] --> B[Application cliente] - B -->|Appel API paramètres de compte auto-hébergée|C[Application côté serveur] + B -->|Appel API de paramètres de compte auto-hébergée|C[Application côté serveur] C -->|Appel Management API| D[Logto] ``` -1. **Utilisateur** : Utilisateur final authentifié qui doit accéder et gérer les paramètres de son compte. -2. **Application cliente** : Votre application cliente qui sert la page des paramètres de compte à l'utilisateur. -3. **Application côté serveur** : Application côté serveur qui fournit l'API des paramètres de compte au client. Interagit avec la Management API de Logto. +1. **Utilisateur** : Utilisateur final authentifié qui doit accéder et gérer ses paramètres de compte. +2. **Application cliente** : Votre application cliente qui sert la page de paramètres de compte à l'utilisateur. +3. **Application côté serveur** : Application côté serveur qui fournit l'API de paramètres de compte au client. Interagit avec la Management API de Logto. 4. **Logto** : Logto en tant que service d'authentification et d'autorisation. Fournit la Management API pour gérer les comptes utilisateurs. ### Diagramme de séquence \{#sequence-diagram} @@ -32,90 +32,90 @@ Logto fournit diverses Management API pour gérer les comptes utilisateurs. Vous participant Server as Application côté serveur participant Logto as Logto - User ->> Client: Accède à l'application cliente + User ->> Client: Accéder à l'application cliente Client ->> Logto: POST /oidc/auth - User -->> Logto: se connecte - Logto -->> Client: Redirige vers l'application cliente + User -->> Logto: se connecter + Logto -->> Client: Rediriger vers l'application cliente Client ->> Logto: POST /oidc/token Logto ->> Client: Jeton d’accès (Access token) A - Client ->> Server: GET /account-settings (avec jeton d’accès A) - Server ->> Logto: POST /oidc/token (avec identifiants client) + Client ->> Server: GET /account-settings (avec le jeton d’accès A) + Server ->> Logto: POST /oidc/token (avec les identifiants client) Logto ->> Server: Jeton d’accès (Access token) B - Server ->> Logto: GET /api/users/{userId} (avec jeton d’accès B) - Logto ->> Server: Détails utilisateur - Server ->> Client: Détails utilisateur + Server ->> Logto: GET /api/users/{userId} (avec le jeton d’accès B) + Logto ->> Server: Détails de l'utilisateur + Server ->> Client: Détails de l'utilisateur ``` 1. L'utilisateur accède à l'application cliente. -2. L'application cliente envoie la requête d’authentification à Logto et redirige l'utilisateur vers la page de connexion Logto. +2. L'application cliente envoie la requête d'authentification à Logto et redirige l'utilisateur vers la page de connexion de Logto. 3. L'utilisateur se connecte à Logto. -4. L'utilisateur authentifié est redirigé vers l'application cliente avec le code d’autorisation. -5. L'application cliente demande le jeton d’accès à Logto pour accéder à l’API des paramètres de compte auto-hébergée. +4. L'utilisateur authentifié est redirigé vers l'application cliente avec le code d'autorisation. +5. L'application cliente demande le jeton d’accès à Logto pour l'accès à l'API de paramètres de compte auto-hébergée. 6. Logto accorde le jeton d’accès à l'application cliente. 7. L'application cliente envoie la requête de paramètres de compte à l'application côté serveur avec le jeton d’accès utilisateur. 8. L'application côté serveur vérifie l'identité et la permission du demandeur à partir du jeton d’accès utilisateur. Puis demande un jeton d’accès Management API à Logto. 9. Logto accorde le jeton d’accès Management API à l'application côté serveur. 10. L'application côté serveur demande les données utilisateur à Logto en utilisant le jeton d’accès Management API. -11. Logto vérifie l'identité du serveur et la permission Management API et retourne les données utilisateur. -12. L'application côté serveur traite les données utilisateur selon la permission du demandeur et retourne les détails du compte utilisateur à l'application cliente. +11. Logto vérifie l'identité du serveur et la permission Management API et renvoie les données utilisateur. +12. L'application côté serveur traite les données utilisateur en fonction de la permission du demandeur et renvoie les détails du compte utilisateur à l'application cliente. -### Intégrer Management API à l’application côté serveur \{#integrate-management-api-to-server-side-application} +### Intégrer Management API à l'application côté serveur \{#integrate-management-api-to-server-side-application} -Consultez la section [Management API](/integrate-logto/interact-with-management-api/) pour apprendre comment intégrer les Management API avec les applications côté serveur. +Consultez la section [Management API](/integrate-logto/interact-with-management-api/) pour apprendre comment intégrer les Management APIs avec les applications côté serveur. -## APIs de gestion des utilisateurs \{#user-management-apis} +## User Management APIs \{#user-management-apis} ### Schéma des données utilisateur \{#user-data-schema} Consultez la section [données utilisateur et données personnalisées](/user-management/user-data/) pour en savoir plus sur le schéma utilisateur dans Logto. -### APIs de gestion du profil utilisateur et des identifiants \{#user-profile-and-identifiers-management-apis} +### User profile and identifiers Management APIs \{#user-profile-and-identifiers-management-apis} -Le profil et les identifiants d’un utilisateur sont essentiels pour la gestion des utilisateurs. Vous pouvez utiliser les APIs suivantes pour gérer les profils et identifiants utilisateurs. +Le profil et les identifiants d'un utilisateur sont essentiels pour la gestion des utilisateurs. Vous pouvez utiliser les API suivantes pour gérer les profils et les identifiants des utilisateurs. -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails utilisateur par ID. | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Mettre à jour les détails utilisateur. | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Mettre à jour les champs du profil utilisateur par ID. | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obtenir les données personnalisées utilisateur par ID. | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Mettre à jour les données personnalisées utilisateur par ID. | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Mettre à jour le statut de suspension utilisateur par ID. | +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails de l'utilisateur par ID. | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Mettre à jour les détails de l'utilisateur. | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Mettre à jour les champs du profil utilisateur par ID. | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obtenir les données personnalisées de l'utilisateur par ID. | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Mettre à jour les données personnalisées de l'utilisateur par ID. | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Mettre à jour le statut de suspension de l'utilisateur par ID. | -### Vérification de l’e-mail et du numéro de téléphone \{#email-and-phone-number-verification} +### Vérification de l'email et du numéro de téléphone \{#email-and-phone-number-verification} -Dans le système Logto, les adresses e-mail et les numéros de téléphone peuvent servir d’identifiants utilisateur, rendant leur vérification essentielle. Pour cela, nous fournissons un ensemble d’APIs de code de vérification pour aider à vérifier l’e-mail ou le numéro de téléphone fourni. +Dans le système Logto, les adresses e-mail et les numéros de téléphone peuvent servir d'identifiants utilisateur, rendant leur vérification essentielle. Pour cela, nous fournissons un ensemble d'APIs de code de vérification pour aider à vérifier l'e-mail ou le numéro de téléphone fourni. :::note -Assurez-vous de vérifier l’e-mail ou le numéro de téléphone avant de mettre à jour le profil utilisateur avec un nouvel e-mail ou numéro de téléphone. +Assurez-vous de vérifier l'e-mail ou le numéro de téléphone avant de mettre à jour le profil de l'utilisateur avec un nouvel e-mail ou numéro de téléphone. ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Envoyer un code de vérification par e-mail ou téléphone. | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Vérifier l’e-mail ou le numéro de téléphone par code. | +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Envoyer un code de vérification par e-mail ou numéro de téléphone. | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Vérifier l'e-mail ou le numéro de téléphone par code de vérification. | -### Gestion du mot de passe utilisateur \{#user-password-management} +### Gestion des mots de passe utilisateur \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Vérifier le mot de passe actuel par ID utilisateur. | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Mettre à jour le mot de passe utilisateur par ID. | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Vérifier si l’utilisateur a un mot de passe par ID. | +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Vérifier le mot de passe actuel de l'utilisateur par ID. | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Mettre à jour le mot de passe de l'utilisateur par ID. | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Vérifier si l'utilisateur a un mot de passe par ID. | :::note -Assurez-vous de vérifier le mot de passe actuel de l’utilisateur avant de le mettre à jour. +Assurez-vous de vérifier le mot de passe actuel de l'utilisateur avant de mettre à jour le mot de passe de l'utilisateur. ::: ### Gestion des identités sociales utilisateur \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails utilisateur par ID. Les identités sociales se trouvent dans le champ `identities`. | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Lier une identité sociale authentifiée à l’utilisateur par ID. | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Délier une identité sociale de l’utilisateur par ID. | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Mettre à jour directement une identité sociale liée à l’utilisateur par ID. | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obtenir l’URI d’autorisation pour un fournisseur d’identité sociale. Utilisez cet URI pour initier une nouvelle connexion sociale. | +| méthode | chemin | description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails de l'utilisateur par ID. Les identités sociales peuvent être trouvées dans le champ `identities`. | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Lier une identité sociale authentifiée à l'utilisateur par ID. | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Dissocier une identité sociale de l'utilisateur par ID. | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Mettre à jour directement une identité sociale liée à l'utilisateur par ID. | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obtenir l'URI d'autorisation pour un fournisseur d'identité sociale. Utilisez cet URI pour initier une nouvelle connexion d'identité sociale. | ```mermaid sequenceDiagram @@ -124,81 +124,96 @@ sequenceDiagram participant Client as Application cliente participant App as Application serveur participant Logto as Logto - participant IdP as Fournisseur d’identité sociale + participant IdP as Fournisseur d'identité sociale - User ->> Client: Accède à l’application cliente, demande de lier une identité sociale - Client ->> App: Envoie la demande de liaison d’identité sociale + User ->> Client: Accéder à l'application cliente pour lier une identité sociale + Client ->> App: Envoyer une requête pour lier une identité sociale App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri - Logto ->> App: URI d’autorisation - App ->> Client: Retourne l’URI d’autorisation - Client ->> IdP: Redirige vers la page d’autorisation IdP - User -->> IdP: Se connecte à IdP - IdP ->> Client: Redirige vers l’application cliente avec le code d’autorisation - Client ->> Server: Demande de liaison d’identité sociale, transmet la réponse d’autorisation IdP + Logto ->> App: URI d'autorisation + App ->> Client: Retourner l'URI d'autorisation + Client ->> IdP: Rediriger vers la page d'autorisation IdP + User -->> IdP: Se connecter à IdP + IdP ->> Client: Rediriger vers l'application cliente avec le code d'autorisation + Client ->> Server: Requête de liaison d'identité sociale, transférer la réponse d'autorisation IdP Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: Récupère les infos utilisateur depuis IdP avec le code d’autorisation - IdP ->> Logto: Retourne les infos utilisateur + Logto ->> IdP: Obtenir les informations utilisateur d'IdP en utilisant le code d'autorisation + IdP ->> Logto: Retourner les informations utilisateur ``` -1. L’utilisateur accède à l’application cliente et demande à lier une identité sociale. -2. L’application cliente envoie une demande au serveur pour lier une identité sociale. -3. Le serveur envoie une demande à Logto pour obtenir l’URI d’autorisation du fournisseur d’identité sociale. Vous devez fournir votre propre paramètre `state` et `redirect_uri` dans la requête. Assurez-vous d’enregistrer le `redirect_uri` auprès du fournisseur d’identité sociale. -4. Logto retourne l’URI d’autorisation au serveur. -5. Le serveur retourne l’URI d’autorisation à l’application cliente. -6. L’application cliente redirige l’utilisateur vers l’URI d’autorisation IdP. -7. L’utilisateur se connecte à l’IdP. -8. L’IdP redirige l’utilisateur vers l’application cliente via le `redirect_uri` avec le code d’autorisation. -9. L’application cliente valide le `state` et transmet la réponse d’autorisation IdP au serveur. -10. Le serveur envoie une demande à Logto pour lier l’identité sociale à l’utilisateur. -11. Logto récupère les informations utilisateur auprès de l’IdP avec le code d’autorisation. -12. L’IdP retourne les informations utilisateur à Logto et Logto lie l’identité sociale à l’utilisateur. +1. L'utilisateur accède à l'application cliente et demande à lier une identité sociale. +2. L'application cliente envoie une requête au serveur pour lier une identité sociale. +3. Le serveur envoie une requête à Logto pour obtenir l'URI d'autorisation pour le fournisseur d'identité sociale. Vous devez fournir votre propre paramètre `state` et `redirect_uri` dans la requête. Assurez-vous d'enregistrer le `redirect_uri` dans le fournisseur d'identité sociale. +4. Logto retourne l'URI d'autorisation au serveur. +5. Le serveur retourne l'URI d'autorisation à l'application cliente. +6. L'application cliente redirige l'utilisateur vers l'URI d'autorisation IdP. +7. L'utilisateur se connecte à l'IdP. +8. L'IdP redirige l'utilisateur vers l'application cliente en utilisant le `redirect_uri` avec le code d'autorisation. +9. L'application cliente valide le `state` et transfère la réponse d'autorisation IdP au serveur. +10. Le serveur envoie une requête à Logto pour lier l'identité sociale à l'utilisateur. +11. Logto obtient les informations utilisateur de l'IdP en utilisant le code d'autorisation. +12. L'IdP retourne les informations utilisateur à Logto et Logto lie l'identité sociale à l'utilisateur. :::note Il y a quelques limitations à prendre en compte lors de la liaison de nouvelles identités sociales à un utilisateur : -- La Management API n’a pas de contexte de session, tout connecteur social nécessitant une session active pour maintenir de manière sécurisée l’état d’authentification sociale ne peut pas être lié via la Management API. Les connecteurs non pris en charge incluent apple, OIDC standard et connecteur OAuth 2.0 standard. -- Pour la même raison, Logto ne peut pas vérifier le paramètre `state` dans la réponse d’autorisation. Assurez-vous de stocker le paramètre `state` dans votre application cliente et de le valider à la réception de la réponse d’autorisation. -- Vous devez enregistrer le `redirect_uri` auprès du fournisseur d’identité sociale à l’avance. Sinon, l’IdP social ne redirigera pas l’utilisateur vers votre application cliente. Votre IdP social doit accepter plus d’un `redirect_uri` de rappel, un pour la connexion utilisateur, un pour votre propre page de liaison de profil. +- Management API n'a pas de contexte de session, tout connecteur social nécessitant une session active pour maintenir en toute sécurité l'état d'authentification sociale ne peut pas être lié via Management API. Les connecteurs non pris en charge incluent apple, OIDC standard et connecteur OAuth 2.0 standard. +- Pour la même raison, Logto ne peut pas vérifier le paramètre `state` dans la réponse d'autorisation. Assurez-vous de stocker le paramètre `state` dans votre application cliente et de le valider lorsque la réponse d'autorisation est reçue. +- Vous devez enregistrer le `redirect_uri` auprès du fournisseur d'identité sociale à l'avance. Sinon, l'IdP social ne redirigera pas l'utilisateur vers votre application cliente. Votre IdP social doit accepter plus d'un `redirect_uri` de rappel, un pour la connexion utilisateur, un pour votre propre page de liaison de profil. ::: -### Gestion des identités d’entreprise utilisateur \{#user-enterprise-identities-management} +### Gestion des identités d'entreprise utilisateur \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails utilisateur par ID. Les identités d’entreprise se trouvent dans le champ `ssoIdentities`. Ajoutez le paramètre de requête `includeSsoIdentities=true` à l’API de détails utilisateur pour les inclure. | +| méthode | chemin | description | +| ------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obtenir les détails de l'utilisateur par ID. Les identités d'entreprise peuvent être trouvées dans le champ `ssoIdentities`. Ajoutez le paramètre de requête `includeSsoIdentities=true` à l'API de détails utilisateur pour les inclure. | -Actuellement, la Management API ne prend pas en charge la liaison ou la suppression des identités d’entreprise à un utilisateur. Vous pouvez seulement afficher les identités d’entreprise liées à un utilisateur. +Actuellement, Management API ne prend pas en charge la liaison ou la dissociation des identités d'entreprise à un utilisateur. Vous pouvez uniquement afficher les identités d'entreprise liées à un utilisateur. -### Jeton d’accès personnel \{#personal-access-token} +### Jeton d'accès personnel \{#personal-access-token} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obtenir tous les jetons d’accès personnels pour l’utilisateur. | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Ajouter un nouveau jeton d’accès personnel pour l’utilisateur. | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Supprimer un jeton pour l’utilisateur par nom. | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Mettre à jour un jeton pour l’utilisateur par nom. | +| méthode | chemin | description | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obtenir tous les jetons d'accès personnels pour l'utilisateur. | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Ajouter un nouveau jeton d'accès personnel pour l'utilisateur. | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Supprimer un jeton pour l'utilisateur par nom. | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Mettre à jour un jeton pour l'utilisateur par nom. | -Les jetons d’accès personnels offrent un moyen sécurisé pour les utilisateurs d’accorder un [jeton d’accès (Access token)](https://auth.wiki/access-token) sans utiliser leurs identifiants et sans connexion interactive. En savoir plus sur [l’utilisation des jetons d’accès personnels](/user-management/personal-access-token). +Les jetons d'accès personnels fournissent un moyen sécurisé pour les utilisateurs d'accorder un [jeton d’accès (Access token)](https://auth.wiki/access-token) sans utiliser leurs identifiants et connexion interactive. En savoir plus sur [l'utilisation des jetons d'accès personnels](/user-management/personal-access-token). ### Gestion des paramètres MFA utilisateur \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obtenir les paramètres MFA utilisateur par ID. | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurer une vérification MFA utilisateur par ID. | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Supprimer une vérification MFA utilisateur par ID. | +| méthode | chemin | description | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obtenir les paramètres MFA utilisateur par ID. | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurer une vérification MFA utilisateur par ID. | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Supprimer une vérification MFA utilisateur par ID. | -### Suppression du compte utilisateur \{#user-account-deletion} +### Suppression de compte utilisateur \{#user-account-deletion} -| method | path | description | -| ------ | -------------------------------------------------------------------------------- | -------------------------------- | -| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Supprimer un utilisateur par ID. | +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------- | -------------------------------- | +| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Supprimer un utilisateur par ID. | ### Gestion des sessions utilisateur \{#user-session-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obtenir les sessions utilisateur par ID. | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obtenir une session utilisateur par ID. | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Supprimer une session utilisateur par ID. | +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obtenir les sessions utilisateur par ID. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obtenir une session utilisateur par ID de session. | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Supprimer une session utilisateur par ID de session. | + +### Gérer les applications autorisées par l'utilisateur (grants) \{#manage-user-authorized-apps-grants} + +| méthode | chemin | description | +| ------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | Lister les autorisations d'application actives pour l'utilisateur. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | Révoquer une autorisation d'application spécifique par ID. | + +Paramètre de requête optionnel pour la liste des autorisations : + +- `appType=firstParty` : Retourner uniquement les autorisations d'application de première partie. +- `appType=thirdParty` : Retourner uniquement les autorisations d'application de tierce partie. +- Omettre `appType` : Retourner toutes les autorisations actives. + +Lorsqu'une autorisation est révoquée, les jetons d’accès opaques et les jetons de rafraîchissement précédemment émis pour cette autorisation sont invalidés. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index bf9616ed0dc..64df4f308c6 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,155 +1,15 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # Déconnexion -La déconnexion dans Logto (en tant que fournisseur d'identité OIDC) implique à la fois : +La déconnexion dans Logto implique deux couches : -- Une **session Logto centralisée** (cookie de navigateur sous le domaine Logto), et -- **Un état d'authentification côté client distribué** (jetons et session locale de l'application dans chaque application). +- **Déconnexion de session Logto** : Termine la session de connexion centralisée sous le domaine Logto. +- **Déconnexion de l'application** : Efface l'état de session local et les jetons dans votre application cliente. -Pour comprendre le comportement de la déconnexion, il est utile de séparer ces deux couches puis de voir comment les **grants** les relient. - -## Concepts de base \{#core-concepts} - -### Qu'est-ce qu'une session Logto ? \{#what-is-a-logto-session} - -Une session Logto est l'état de connexion centralisé géré par Logto. Elle est créée après une authentification réussie et représentée par des cookies sous le domaine Logto. - -Si le cookie de session est valide, l'utilisateur peut être authentifié silencieusement (SSO) sur plusieurs applications qui font confiance au même tenant Logto. - -Si aucune session valide n'existe, Logto affiche la page de connexion. - -### Qu'est-ce qu'un grant ? \{#what-are-grants} - -Un **grant** représente l'état d'autorisation pour une combinaison utilisateur + application cliente spécifique. - -- Une session Logto peut avoir des grants pour plusieurs applications clientes. -- Un grant est ce à quoi les jetons émis sont associés. -- Dans cette documentation, utilisez **grant** comme unité d'autorisation inter-applications. - -### Comment la session, les grants et l'état d'authentification du client sont liés \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Domaine Logto] - S[Session Logto] - G1[Grant pour App A] - G2[Grant pour App B] - end - - subgraph AppA [Domaine client A] - A[Session locale / jetons] - end - - subgraph AppB [Domaine client B] - B[Session locale / jetons] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Session Logto** contrôle l'expérience SSO centralisée. -- **Session locale / jetons du client** contrôlent si chaque application considère actuellement l'utilisateur comme connecté. -- **Grants** relient ces deux mondes en représentant l'état d'autorisation spécifique à l'application. - -## Récapitulatif de la connexion (pourquoi la déconnexion est multi-couches) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as Application cliente - end - - box Logto (IdP) - participant OIDC as Fournisseur OIDC - participant SignIn as Page de connexion - end - - User ->> Client: Accéder à l'application - Client ->> OIDC: Rediriger pour authentification - OIDC -->> OIDC: Vérifier la session Logto - OIDC ->> SignIn: Demander la connexion si nécessaire - SignIn ->> OIDC: L'utilisateur s'authentifie - OIDC -->> OIDC: Créer session et grant - OIDC ->> Client: Retourner le code d'autorisation - Client ->> OIDC: Échanger le code contre des jetons - OIDC -->> Client: Retourner les jetons -``` - -## Topologie des sessions entre applications / appareils \{#session-topology-across-apps-devices} - -### Cookie de session partagé (même navigateur / agent utilisateur) \{#shared-session-cookie-same-browser-user-agent} - -Si un utilisateur se connecte à plusieurs applications depuis le même navigateur, ces applications peuvent réutiliser le même cookie de session Logto et le comportement SSO s'applique. - -```mermaid -flowchart TD - U[Utilisateur] - A["Application cliente A (Domaine client A)"] - B["Application cliente B (Domaine client B)"] - C{"Session Logto existante ? (Domaine Logto)"} - D["Page de connexion (Domaine Logto)"] - - subgraph UA["Agent utilisateur A (même navigateur)"] - U - A - B - C - D - end - - U -->|Connexion| A - A -->|Redirection vers Logto| C - U -->|Ouvrir l'application| B - B -->|Redirection vers Logto| C - C -->|Non| D - D -->|Créer session| C -``` - -### Cookies de session isolés (appareils / navigateurs différents) \{#isolated-session-cookies-different-devices-browsers} - -Des navigateurs / appareils différents détiennent des cookies Logto différents, donc l'état de session de connexion est isolé. - -```mermaid -flowchart TD - U[Utilisateur] - A["Application cliente A (Domaine client A)"] - C{"Session Logto existante ? (Appareil A, Domaine Logto)"} - D["Page de connexion (Appareil A, Domaine Logto)"] - - subgraph DeviceA["Agent utilisateur A"] - A - C - D - end - - B["Application cliente B (Domaine client B)"] - E{"Session Logto existante ? (Appareil B, Domaine Logto)"} - F["Page de connexion (Appareil B, Domaine Logto)"] - - subgraph DeviceB["Agent utilisateur B"] - B - E - F - end - - U -->|Connexion| A - A -->|Redirection vers Logto| C - U -->|Connexion| B - B -->|Redirection vers Logto| E - C -->|Non| D - E -->|Non| F - D -->|Créer session| C - F -->|Créer session| E -``` +Pour mieux comprendre comment fonctionnent les sessions dans Logto, voir [Sessions](/sessions). ## Mécanismes de déconnexion \{#sign-out-mechanisms} @@ -158,74 +18,80 @@ flowchart TD L'application cliente efface sa propre session locale et ses jetons (jetons d’identifiant / d’accès / de rafraîchissement). Cela déconnecte l'utilisateur uniquement de l'état local de cette application. - La session Logto peut toujours être active. -- D'autres applications sous la même session Logto peuvent toujours utiliser le SSO. +- D'autres applications sous la même session Logto peuvent toujours utiliser l'authentification unique (SSO). -### 2) Fin de session sur Logto (déconnexion globale dans l'implémentation Logto actuelle) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +### 2) Fin de session chez Logto (déconnexion globale dans l'implémentation actuelle de Logto) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -Pour effacer la session Logto centralisée, l'application redirige l'utilisateur vers l'endpoint de fin de session, par exemple : +Pour effacer la session centralisée Logto, l'application redirige l'utilisateur vers le point de terminaison de fin de session, par exemple : `https://{your-logto-domain}/oidc/session/end` Dans le comportement actuel du SDK Logto : 1. `signOut()` redirige vers `/session/end`. -2. Puis cela va vers `/session/end/confirm`. +2. Puis il va à `/session/end/confirm`. 3. Le formulaire de confirmation par défaut envoie automatiquement `logout=true`. -En conséquence, la déconnexion via le SDK est traitée comme une **déconnexion globale**. +En conséquence, la déconnexion actuelle du SDK est traitée comme une **déconnexion globale**. + +:::note + +- **Déconnexion globale** : Révoque la session centralisée Logto. + +::: -### Que se passe-t-il lors d'une déconnexion globale \{#what-happens-during-global-sign-out} +### Que se passe-t-il lors de la déconnexion globale \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["Le client lance la déconnexion"] --> B["/session/end"] + A["Le client commence la déconnexion"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["Révoquer la session Logto centralisée"] - D --> E{"Vérifier le grant par application"} - E -->|"offline_access non accordé"| F["Révoquer le grant"] - E -->|"offline_access accordé"| G["Conserver le grant jusqu'à expiration du TTL du grant"] + C --> D["Révoquer la session centralisée Logto"] + D --> E{"Vérifier la subvention par application"} + E -->|"offline_access non accordé"| F["Révoquer la subvention"] + E -->|"offline_access accordé"| G["Conserver la subvention jusqu'à expiration du TTL de la subvention"] ``` -Lors d'une déconnexion globale : +Lors de la déconnexion globale : -- La session Logto centralisée est révoquée. -- Les grants associés aux applications sont traités selon l'état d'autorisation de chaque application : - - Si `offline_access` **n'est pas** accordé, les grants associés sont révoqués. - - Si `offline_access` **est** accordé, les grants ne sont pas révoqués par la fin de session. -- Pour les cas `offline_access`, les jetons de rafraîchissement et les grants restent valides jusqu'à expiration du grant. +- La session centralisée Logto est révoquée. +- Les subventions d'application associées sont gérées selon l'état d'autorisation de chaque application : + - Si `offline_access` n'est **pas** accordé, les subventions associées sont révoquées. + - Si `offline_access` est accordé, les subventions ne sont pas révoquées par la fin de session. +- Pour les cas `offline_access`, les jetons de rafraîchissement et les subventions restent valides jusqu'à l'expiration de la subvention. -## Durée de vie du grant et impact de `offline_access` \{#grant-lifetime-and-offline-access-impact} +## Durée de vie de la subvention et impact de `offline_access` \{#grant-lifetime-and-offline-access-impact} -- Le TTL par défaut d'un grant Logto est de **180 jours**. -- Si `offline_access` est accordé, la fin de session ne révoque pas ce grant d'application par défaut. -- La chaîne de jetons de rafraîchissement associée à ce grant peut continuer jusqu'à expiration du grant (ou révocation explicite). +- Le TTL de subvention par défaut de Logto est de **180 jours**. +- Si `offline_access` est accordé, la fin de session ne révoque pas cette subvention d'application par défaut. +- La chaîne de jetons de rafraîchissement associée à cette subvention peut continuer jusqu'à l'expiration de la subvention (ou jusqu'à ce qu'elle soit explicitement révoquée). -## Déconnexion fédérée : back-channel logout \{#federated-sign-out-back-channel-logout} +## Déconnexion fédérée : déconnexion par canal arrière \{#federated-sign-out-back-channel-logout} -Pour la cohérence inter-applications, Logto prend en charge le [back-channel logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). +Pour une cohérence inter-applications, Logto prend en charge la [déconnexion par canal arrière](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). -Lorsqu'un utilisateur se déconnecte d'une application, Logto peut notifier toutes les applications participant à la même session en envoyant un jeton de déconnexion à chaque URI de back-channel logout enregistré. +Lorsqu'un utilisateur se déconnecte d'une application, Logto peut notifier toutes les applications participant à la même session en envoyant un jeton de déconnexion à l'URI de déconnexion par canal arrière enregistrée de chaque application. -Si `Is session required` est activé dans les paramètres de back-channel de l'application, le jeton de déconnexion inclut `sid` pour identifier la session Logto. +Si `Is session required` est activé dans les paramètres de canal arrière de l'application, le jeton de déconnexion inclut `sid` pour identifier la session Logto. Flux typique : -1. L'utilisateur initie la déconnexion depuis une application. -2. Logto traite la fin de session et envoie le(s) jeton(s) de déconnexion à l'(aux) URI(s) de back-channel logout enregistrée(s). +1. L'utilisateur initie la déconnexion d'une application. +2. Logto traite la fin de session et envoie le(s) jeton(s) de déconnexion à l'URI de déconnexion par canal arrière enregistrée. 3. Chaque application valide le jeton de déconnexion et efface sa propre session locale / ses jetons. ## Méthodes de déconnexion dans les SDK Logto \{#sign-out-methods-in-logto-sdks} -- **SPA et web** : `client.signOut()` efface le stockage local des jetons et redirige vers l'endpoint de fin de session Logto. Vous pouvez fournir une URI de redirection post-déconnexion. -- **Natif (y compris React Native / Flutter)** : efface généralement uniquement le stockage local des jetons. Le webview sans session signifie qu'il n'y a pas de cookie Logto persistant à effacer. +- **SPA et web** : `client.signOut()` efface le stockage local des jetons et redirige vers le point de terminaison de fin de session Logto. Vous pouvez fournir une URI de redirection post-déconnexion. +- **Natif (y compris React Native / Flutter)** : efface généralement uniquement le stockage local des jetons. Webview sans session signifie qu'il n'y a pas de cookie de navigateur Logto persistant à effacer. :::note -Pour les applications natives qui ne prennent pas en charge le webview sans session ou ne reconnaissent pas les paramètres `emphasized` (application Android utilisant le SDK **React Native** ou **Flutter**), vous pouvez forcer l'utilisateur à saisir à nouveau ses identifiants en passant le paramètre `prompt=login` dans la requête d'autorisation. +Pour les applications natives qui ne prennent pas en charge le webview sans session ou ne reconnaissent pas les paramètres `emphasized` (application Android utilisant le SDK **React Native** ou **Flutter**), vous pouvez forcer l'utilisateur à se reconnecter en passant le paramètre `prompt=login` dans la requête d'autorisation. ::: -## Imposer la ré-authentification à chaque accès \{#enforce-re-authentication-on-every-access} +## Imposer une ré-authentification à chaque accès \{#enforce-re-authentication-on-every-access} -Pour les actions à haute sécurité, incluez `prompt=login` dans les requêtes d'authentification pour contourner le SSO et forcer la saisie des identifiants à chaque fois. +Pour les actions à haute sécurité, incluez `prompt=login` dans les requêtes d'authentification pour contourner le SSO et forcer l'entrée des identifiants à chaque fois. Si vous demandez `offline_access` (pour recevoir des jetons de rafraîchissement), incluez également `consent`, `prompt=login consent`. @@ -235,22 +101,22 @@ Paramètre combiné typique : prompt=login consent ``` -## FAQ \{#faqs} +## FAQs \{#faqs}
-### Je ne reçois pas les notifications de back-channel logout. \{#im-not-receiving-the-back-channel-logout-notifications} +### Je ne reçois pas les notifications de déconnexion par canal arrière. \{#im-not-receiving-the-back-channel-logout-notifications} -- Vérifiez que l'URI de back-channel logout est correctement enregistrée dans le tableau de bord Logto. -- Vérifiez que votre application a un état de connexion actif pour le même utilisateur / contexte de session. +- Assurez-vous que l'URI de déconnexion par canal arrière est correctement enregistrée dans le tableau de bord Logto. +- Assurez-vous que votre application a un état de connexion actif pour le même utilisateur / contexte de session.
## Ressources associées \{#related-resources} - Comprendre le back-channel logout OIDC. + Comprendre la déconnexion par canal arrière OIDC. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index dd2eb1ea420..209bf2ad53d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,184 +1,203 @@ --- -description: Consultez les principaux paramètres d’application pour l’intégration de l’authentification OIDC, y compris les URI de redirection, les points de terminaison, les jetons de rafraîchissement, la déconnexion backchannel, etc. +description: Consultez les principaux paramètres d'application pour l'intégration de l'authentification OIDC, y compris les URI de redirection, les points de terminaison, les jetons de rafraîchissement, la déconnexion backchannel, etc. sidebar_position: 6 --- -# Structure des données d’application +# Structure des données de l'application ## Introduction \{#introduction} -Dans Logto, une _application_ désigne un programme ou service logiciel spécifique qui est enregistré sur la plateforme Logto et qui a reçu l’autorisation d’accéder aux informations utilisateur ou d’effectuer des actions au nom d’un utilisateur. Les applications servent à identifier la source des requêtes faites à l’API Logto, ainsi qu’à gérer le processus d’authentification et d’autorisation pour les utilisateurs accédant à ces applications. +Dans Logto, une _application_ fait référence à un programme ou service logiciel spécifique qui est enregistré sur la plateforme Logto et a reçu l'autorisation d'accéder aux informations des utilisateurs ou d'effectuer des actions au nom d'un utilisateur. Les applications sont utilisées pour identifier la source des requêtes faites à l'API Logto, ainsi que pour gérer le processus d'authentification et d'autorisation pour les utilisateurs accédant à ces applications. -L’utilisation des applications dans l’expérience de connexion de Logto permet aux utilisateurs d’accéder facilement à leurs applications autorisées et de les gérer depuis un seul endroit, avec un processus d’authentification cohérent et sécurisé. Cela permet de simplifier l’expérience utilisateur et de garantir que seules les personnes autorisées accèdent à des informations sensibles ou effectuent des actions au nom de l’organisation. +L'utilisation des applications dans l'expérience de connexion de Logto permet aux utilisateurs d'accéder facilement et de gérer leurs applications autorisées à partir d'un emplacement unique, avec un processus d'authentification cohérent et sécurisé. Cela aide à rationaliser l'expérience utilisateur et à garantir que seules les personnes autorisées accèdent aux informations sensibles ou effectuent des actions au nom de l'organisation. -Les applications sont également utilisées dans les journaux d’audit de Logto pour suivre l’activité des utilisateurs et identifier toute menace ou violation potentielle de sécurité. En associant des actions spécifiques à une application particulière, Logto peut fournir des informations détaillées sur la façon dont les données sont consultées et utilisées, permettant ainsi aux organisations de mieux gérer leurs exigences en matière de sécurité et de conformité. +Les applications sont également utilisées dans les journaux d'audit de Logto pour suivre l'activité des utilisateurs et identifier toute menace ou violation potentielle de sécurité. En associant des actions spécifiques à une application particulière, Logto peut fournir des informations détaillées sur la façon dont les données sont accédées et utilisées, permettant aux organisations de mieux gérer leurs exigences de sécurité et de conformité. Si vous souhaitez intégrer votre application avec Logto, consultez [Intégrer Logto](/integrate-logto). ## Propriétés \{#properties} -### ID d’application \{#application-id} +### ID de l'application \{#application-id} -_L’ID d’application_ est une clé unique générée automatiquement pour identifier votre application dans Logto, et est référencée comme [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) dans OAuth 2.0. +_L'ID de l'application_ est une clé unique générée automatiquement pour identifier votre application dans Logto, et est référencée comme [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) dans OAuth 2.0. -### Types d’application \{#application-types} +### Types d'application \{#application-types} -Une _application_ peut être l’un des types suivants : +Une _Application_ peut être l'un des types d'application suivants : -- **Application native** : une application qui s’exécute dans un environnement natif. Par exemple, application iOS, application Android. - - **Application device flow** : un type spécial d’application native pour les appareils à saisie limitée ou les applications sans interface (par exemple, téléviseurs intelligents, consoles de jeux, outils CLI, appareils IoT). Elle utilise le [Device Authorization Grant OAuth 2.0](https://auth.wiki/device-flow) au lieu du flux standard basé sur la redirection. Voir [Démarrage rapide device flow](/quick-starts/device-flow) pour plus de détails. -- **Application monopage (SPA)** : une application qui s’exécute dans un navigateur web, qui met à jour la page avec de nouvelles données du serveur sans recharger entièrement la page. Par exemple, application React DOM, application Vue. -- **Application web traditionnelle** : une application qui rend et met à jour les pages uniquement via le serveur web. Par exemple, JSP, PHP. -- **Application machine à machine (M2M)** : une application qui s’exécute dans un environnement machine pour une communication directe service à service sans interaction utilisateur. +- **Application native** est une application qui s'exécute dans un environnement natif. Par exemple, application iOS, application Android. + - **Application de flux de périphérique** est un type spécial d'application native pour les appareils à saisie limitée ou les applications sans interface (par exemple, téléviseurs intelligents, consoles de jeux, outils CLI, appareils IoT). Elle utilise le [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) au lieu du flux standard basé sur la redirection. Voir [Démarrage rapide du flux de périphérique](/quick-starts/device-flow) pour plus de détails. +- **Application monopage** est une application qui s'exécute dans un navigateur web, qui met à jour la page avec les nouvelles données du serveur sans charger de nouvelles pages entières. Par exemple, application React DOM, application Vue. +- **Application web traditionnelle** est une application qui rend et met à jour les pages uniquement par le serveur web. Par exemple, JSP, PHP. +- **Application machine à machine (M2M)** est une application qui s'exécute dans un environnement machine pour une communication directe de service à service sans interaction utilisateur. -### Secret d’application \{#application-secret} +### Secret de l'application \{#application-secret} -_Le secret d’application_ est une clé utilisée pour authentifier l’application dans le système d’authentification, spécifiquement pour les clients privés (applications web traditionnelles et M2M) en tant que barrière de sécurité privée. +_Le secret de l'application_ est une clé utilisée pour authentifier l'application dans le système d'authentification, spécifiquement pour les clients privés (applications Web traditionnelles et M2M) en tant que barrière de sécurité privée. :::tip -Les applications monopage (SPA) et les applications natives ne fournissent pas de secret d’application. Les SPA et les applications natives sont des "clients publics" et ne peuvent pas garder de secrets (le code du navigateur ou les bundles d’application sont inspectables). Au lieu d’un secret d’application, Logto les protège avec PKCE, une validation stricte des URI de redirection / CORS, des jetons d’accès à durée de vie courte et la rotation des jetons de rafraîchissement. +Les applications monopage (SPAs) et les applications natives ne fournissent pas de secret d'application. Les SPAs et les applications natives sont des "clients publics" et ne peuvent pas garder de secrets (le code du navigateur ou les paquets d'application sont inspectables). Au lieu d'un secret d'application, Logto les protège avec PKCE, une validation stricte des URI de redirection / CORS, des jetons d'accès de courte durée et une rotation des jetons de rafraîchissement. ::: -### Nom de l’application \{#application-name} +### Nom de l'application \{#application-name} -_Le nom de l’application_ est un nom lisible par l’homme de l’application et sera affiché dans la console d’administration. +_Le nom de l'application_ est un nom lisible par l'homme de l'application et sera affiché dans la console d'administration. -Le _nom de l’application_ est un élément important de la gestion des applications dans Logto, car il permet aux administrateurs d’identifier facilement et de suivre l’activité des applications individuelles au sein de la plateforme. +Le _Nom de l'application_ est un composant important de la gestion des applications dans Logto, car il permet aux administrateurs d'identifier et de suivre facilement l'activité des applications individuelles au sein de la plateforme. :::note -Il est important de noter que le _nom de l’application_ doit être choisi avec soin, car il sera visible par tous les utilisateurs ayant accès à la console d’administration. Il doit refléter fidèlement le but et la fonction de l’application, tout en étant facile à comprendre et à reconnaître. +Il est important de noter que le _Nom de l'application_ doit être choisi avec soin, car il sera visible par tous les utilisateurs ayant accès à la console d'administration. Il doit refléter avec précision le but et la fonction de l'application, tout en étant facile à comprendre et à reconnaître. ::: ### Description \{#description} -Une brève description de l’application sera affichée sur la page de détails de l’application dans la console d’administration. La description vise à fournir aux administrateurs des informations supplémentaires sur l’application, telles que son objectif, ses fonctionnalités et tout autre détail pertinent. +Une brève description de l'application sera affichée sur la page des détails de l'application dans la console d'administration. La description est destinée à fournir aux administrateurs des informations supplémentaires sur l'application, telles que son objectif, ses fonctionnalités et tout autre détail pertinent. ### URI de redirection \{#redirect-uris} -_Les URI de redirection_ sont une liste d’URI de redirection valides qui ont été préconfigurées pour une application. Lorsqu’un utilisateur se connecte à Logto et tente d’accéder à l’application, il est redirigé vers l’un des URI autorisés spécifiés dans les paramètres de l’application. +_Les URI de redirection_ sont une liste d'URI de redirection valides qui ont été préconfigurées pour une application. Lorsqu'un utilisateur se connecte à Logto et tente d'accéder à l'application, il est redirigé vers l'une des URI autorisées spécifiées dans les paramètres de l'application. -La liste des URI autorisés est utilisée pour valider l’URI de redirection inclus dans la requête d’autorisation envoyée par l’application à Logto lors du processus d’authentification. Si l’URI de redirection spécifié dans la requête d’autorisation correspond à l’un des URI autorisés dans les paramètres de l’application, l’utilisateur est redirigé vers cet URI après une authentification réussie. Si l’URI de redirection ne figure pas dans la liste autorisée, l’utilisateur ne sera pas redirigé et le processus d’authentification échouera. +La liste des URI autorisées est utilisée pour valider l'URI de redirection qui est inclus dans la requête d'autorisation envoyée par l'application à Logto pendant le processus d'authentification. Si l'URI de redirection spécifié dans la requête d'autorisation correspond à l'une des URI autorisées dans les paramètres de l'application, l'utilisateur est redirigé vers cet URI après une authentification réussie. Si l'URI de redirection n'est pas sur la liste autorisée, l'utilisateur ne sera pas redirigé et le processus d'authentification échouera. :::note -Il est important de s’assurer que tous les URI de redirection valides sont ajoutés à la liste autorisée pour une application dans Logto, afin de garantir que les utilisateurs puissent accéder à l’application après authentification. +Il est important de s'assurer que toutes les URI de redirection valides sont ajoutées à la liste autorisée pour une application dans Logto, afin de garantir que les utilisateurs peuvent accéder avec succès à l'application après l'authentification. ::: -Vous pouvez consulter le [point de terminaison de redirection](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) pour plus d’informations. +Vous pouvez consulter le [Point de terminaison de redirection](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) pour plus d'informations. - Comprendre les URI de redirection dans OIDC avec le flux de code d’autorisation + Comprendre les URI de redirection dans OIDC avec le flux de code d'autorisation -#### Modèles génériques (wildcard) \{#wildcard-patterns} +#### Modèles de caractères génériques \{#wildcard-patterns} _Disponibilité : Application monopage, Application web traditionnelle_ -Les URI de redirection prennent en charge les modèles génériques (`*`) pour les environnements dynamiques tels que les déploiements de prévisualisation. Les caractères génériques peuvent être utilisés dans les composants hostname et pathname des URI HTTP / HTTPS. +Les URI de redirection prennent en charge les modèles de caractères génériques (`*`) pour les environnements dynamiques tels que les déploiements de prévisualisation. Les caractères génériques peuvent être utilisés dans les composants de nom d'hôte et de chemin des URI HTTP / HTTPS. **Règles :** -- Les caractères génériques ne sont autorisés que dans le hostname et le pathname +- Les caractères génériques ne sont autorisés que dans le nom d'hôte et le chemin - Les caractères génériques ne sont pas autorisés dans le schéma, le port, les paramètres de requête ou les fragments de hachage -- Les caractères génériques dans le hostname doivent inclure au moins un point (par exemple, `https://*.example.com/callback`) +- Les caractères génériques de nom d'hôte doivent inclure au moins un point (par exemple, `https://*.example.com/callback`) **Exemples :** -- `https://*.example.com/callback` - correspond à n’importe quel sous-domaine +- `https://*.example.com/callback` - correspond à n'importe quel sous-domaine - `https://preview-*.example.com/callback` - correspond aux déploiements de prévisualisation -- `https://example.com/*/callback` - correspond à n’importe quel segment de chemin +- `https://example.com/*/callback` - correspond à n'importe quel segment de chemin :::caution -Les URI de redirection génériques ne sont pas standard OIDC et peuvent augmenter la surface d’attaque. À utiliser avec précaution et privilégier les URI de redirection exacts autant que possible. +Les URI de redirection avec caractères génériques ne sont pas standard OIDC et peuvent augmenter la surface d'attaque. Utilisez-les avec précaution et préférez des URI de redirection exacts chaque fois que possible. ::: ### URI de redirection après déconnexion \{#post-sign-out-redirect-uris} -_Les URI de redirection après déconnexion_ sont une liste d’URI valides qui ont été préconfigurées pour une application afin de rediriger l’utilisateur après sa déconnexion de Logto. +_Les URI de redirection après déconnexion_ sont une liste d'URI valides qui ont été préconfigurées pour une application pour rediriger l'utilisateur après qu'il se soit déconnecté de Logto. -L’utilisation des _URI de redirection après déconnexion_ autorisées pour la déconnexion fait partie de la spécification RP-Initiated (Relying Party Initiated) Logout dans OIDC. Cette spécification fournit une méthode standardisée permettant aux applications d’initier une demande de déconnexion pour un utilisateur, ce qui inclut la redirection de l’utilisateur vers un point de terminaison préconfiguré après sa déconnexion. +L'utilisation des _URI de redirection après déconnexion_ autorisées pour la déconnexion fait partie de la spécification de déconnexion initiée par le RP (Relying Party) dans OIDC. Cette spécification fournit une méthode standardisée pour que les applications initient une demande de déconnexion pour un utilisateur, ce qui inclut la redirection de l'utilisateur vers un point de terminaison préconfiguré après qu'il se soit déconnecté. -Lorsqu’un utilisateur se déconnecte de Logto, sa session est terminée et il est redirigé vers l’un des URI autorisés spécifiés dans les paramètres de l’application. Cela garantit que l’utilisateur est dirigé uniquement vers des points de terminaison autorisés et valides après sa déconnexion, ce qui aide à prévenir les accès non autorisés et les risques de sécurité associés à la redirection des utilisateurs vers des points de terminaison inconnus ou non vérifiés. +Lorsqu'un utilisateur se déconnecte de Logto, sa session est terminée et il est redirigé vers l'une des URI autorisées spécifiées dans les paramètres de l'application. Cela garantit que l'utilisateur est dirigé uniquement vers des points de terminaison autorisés et valides après qu'il se soit déconnecté, aidant à prévenir l'accès non autorisé et les risques de sécurité associés à la redirection des utilisateurs vers des points de terminaison inconnus ou non vérifiés. -Vous pouvez consulter la [déconnexion initiée par le RP](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) pour plus d’informations. +Vous pouvez consulter la [Déconnexion initiée par le RP](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) pour plus d'informations. ### Origines autorisées CORS \{#cors-allowed-origins} -_Les origines autorisées CORS (Cross-origin resource sharing)_ sont une liste d’origines autorisées à partir desquelles une application peut effectuer des requêtes vers le service Logto. Toute origine qui ne figure pas dans la liste autorisée ne pourra pas effectuer de requêtes vers le service Logto. +Les _origines autorisées CORS (partage de ressources cross-origin)_ sont une liste d'origines autorisées à partir desquelles une application peut faire des requêtes au service Logto. Toute origine qui n'est pas incluse dans la liste autorisée ne pourra pas faire de requêtes au service Logto. -La liste des origines autorisées CORS est utilisée pour restreindre l’accès au service Logto depuis des domaines non autorisés, et pour aider à prévenir les attaques de type cross-site request forgery (CSRF). En spécifiant les origines autorisées pour une application dans Logto, le service peut s’assurer que seuls les domaines autorisés peuvent effectuer des requêtes vers le service. +La liste des origines autorisées CORS est utilisée pour restreindre l'accès au service Logto à partir de domaines non autorisés et pour aider à prévenir les attaques de falsification de requêtes intersites (CSRF). En spécifiant les origines autorisées pour une application dans Logto, le service peut s'assurer que seuls les domaines autorisés peuvent faire des requêtes au service. :::note -La liste des origines autorisées doit contenir l’origine où l’application sera servie. Cela garantit que les requêtes provenant de l’application sont autorisées, tandis que celles provenant d’origines non autorisées sont bloquées. +La liste des origines autorisées doit contenir l'origine où l'application sera servie. Cela garantit que les requêtes de l'application sont autorisées, tandis que les requêtes provenant d'origines non autorisées sont bloquées. ::: ### Point de terminaison de configuration du fournisseur OpenID \{#openid-provider-configuration-endpoint} Le point de terminaison pour la [découverte OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). -### Point de terminaison d’autorisation \{#authorization-endpoint} +### Point de terminaison d'autorisation \{#authorization-endpoint} -_Le point de terminaison d’autorisation_ est un terme OIDC, et c’est un point de terminaison requis utilisé pour initier le processus d’authentification pour un utilisateur. Lorsqu’un utilisateur tente d’accéder à une ressource ou application protégée enregistrée sur la plateforme Logto, il sera redirigé vers le _point de terminaison d’autorisation_ pour authentifier son identité et obtenir l’autorisation d’accéder à la ressource demandée. +_Le point de terminaison d'autorisation_ est un terme OIDC, et c'est un point de terminaison requis qui est utilisé pour initier le processus d'authentification pour un utilisateur. Lorsqu'un utilisateur tente d'accéder à une ressource ou application protégée qui a été enregistrée sur la plateforme Logto, il sera redirigé vers le _point de terminaison d'autorisation_ pour authentifier son identité et obtenir l'autorisation d'accéder à la ressource demandée. -Vous pouvez consulter le [point de terminaison d’autorisation](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) pour plus d’informations. +Vous pouvez consulter le [Point de terminaison d'autorisation](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) pour plus d'informations. ### Point de terminaison de jeton \{#token-endpoint} -_Le point de terminaison de jeton_ est un terme OIDC, c’est un point de terminaison d’API web utilisé par un client OIDC pour obtenir un jeton d’accès, un jeton d’identifiant ou un jeton de rafraîchissement auprès d’un fournisseur OIDC. +_Le point de terminaison de jeton_ est un terme OIDC, c'est un point de terminaison d'API web utilisé par un client OIDC pour obtenir un jeton d’accès, un jeton d’identifiant ou un jeton de rafraîchissement d'un fournisseur OIDC. -Lorsqu’un client OIDC a besoin d’obtenir un jeton d’accès ou un jeton d’identifiant, il envoie une requête au point de terminaison de jeton avec une autorisation, qui est généralement un code d’autorisation ou un jeton de rafraîchissement. Le point de terminaison de jeton valide alors l’autorisation et délivre un jeton d’accès ou un jeton d’identifiant au client si l’autorisation est valide. +Lorsqu'un client OIDC a besoin d'obtenir un jeton d’accès ou un jeton d’identifiant, il envoie une requête au point de terminaison de jeton avec une autorisation de subvention, qui est généralement un code d'autorisation ou un jeton de rafraîchissement. Le point de terminaison de jeton valide ensuite l'autorisation de subvention et émet un jeton d’accès ou un jeton d’identifiant au client si la subvention est valide. -Vous pouvez consulter le [point de terminaison de jeton](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) pour plus d’informations. +Vous pouvez consulter le [Point de terminaison de jeton](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) pour plus d'informations. ### Point de terminaison Userinfo \{#userinfo-endpoint} -Le point de terminaison [UserInfo OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). +Le point de terminaison [UserInfo](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) d'OpenID Connect. ### Toujours émettre un jeton de rafraîchissement \{#always-issue-refresh-token} _Disponibilité : Web traditionnel, SPA_ -Lorsqu’il est activé, Logto émettra toujours des jetons de rafraîchissement, que `prompt=consent` soit présenté ou non dans la requête d’authentification, ou que `offline_access` soit présenté ou non dans les portées. +Lorsqu'il est activé, Logto émettra toujours des jetons de rafraîchissement, que `prompt=consent` soit présenté dans la requête d'authentification ou non, ni `offline_access` soit présenté dans les portées. -Cependant, cette pratique est déconseillée sauf nécessité (elle est généralement utile pour certaines intégrations OAuth tierces qui nécessitent un jeton de rafraîchissement), car elle n’est pas compatible avec OpenID Connect et peut potentiellement causer des problèmes. +Cependant, cette pratique est déconseillée sauf si nécessaire (généralement, elle est utile pour certaines intégrations OAuth tierces qui nécessitent un jeton de rafraîchissement), car elle n'est pas compatible avec OpenID Connect et peut potentiellement causer des problèmes. ### Rotation du jeton de rafraîchissement \{#rotate-refresh-token} _Défaut : `true`_ -Lorsqu’elle est activée, Logto émettra un nouveau jeton de rafraîchissement pour les requêtes de jeton dans les conditions suivantes : +Lorsqu'il est activé, Logto émettra un nouveau jeton de rafraîchissement pour les requêtes de jeton dans les conditions suivantes : -- Si le jeton de rafraîchissement a été renouvelé (sa durée de vie prolongée par l’émission d’un nouveau) pendant un an ; **OU** -- Si le jeton de rafraîchissement approche de sa date d’expiration (>=70 % de sa durée de vie initiale écoulée) ; **OU** +- Si le jeton de rafraîchissement a été tourné (a prolongé sa durée de vie en émettant un nouveau) pendant un an ; **OU** +- Si le jeton de rafraîchissement est proche de son expiration (>=70 % de son temps de vie initial (TTL) écoulé) ; **OU** - Si le client est un client public, par exemple une application native ou une application monopage (SPA). :::note -Pour les clients publics, lorsque cette fonctionnalité est activée, un nouveau jeton de rafraîchissement sera toujours émis lorsque le client échange un nouveau jeton d’accès à l’aide du jeton de rafraîchissement. -Bien que vous puissiez désactiver cette fonctionnalité pour ces clients publics, il est fortement recommandé de la laisser activée pour des raisons de sécurité. +Pour les clients publics, lorsque cette fonctionnalité est activée, un nouveau jeton de rafraîchissement sera toujours émis lorsque le client échange pour un nouveau jeton d’accès en utilisant le jeton de rafraîchissement. +Bien que vous puissiez toujours désactiver la fonctionnalité pour ces clients publics, il est fortement recommandé de la garder activée pour des raisons de sécurité. ::: - Comprendre la rotation du jeton de rafraîchissement + Comprendre la rotation des jetons de rafraîchissement ### Durée de vie (TTL) du jeton de rafraîchissement en jours \{#refresh-token-time-to-live-ttl-in-days} _Disponibilité : Pas SPA ; Défaut : 14 jours_ -La durée pendant laquelle un jeton de rafraîchissement peut être utilisé pour demander de nouveaux jetons d’accès avant d’expirer et de devenir invalide. Les requêtes de jeton prolongeront la durée de vie du jeton de rafraîchissement à cette valeur. +La durée pendant laquelle un jeton de rafraîchissement peut être utilisé pour demander de nouveaux jetons d’accès avant qu'il n'expire et devienne invalide. Les requêtes de jeton prolongeront le TTL du jeton de rafraîchissement à cette valeur. En général, une valeur plus basse est préférable. -Remarque : Le renouvellement du TTL n’est pas disponible dans les SPA (application monopage) pour des raisons de sécurité. Cela signifie que Logto ne prolongera pas la durée de vie via les requêtes de jeton. Pour améliorer l’expérience utilisateur, vous pouvez activer la fonctionnalité "Rotation du jeton de rafraîchissement", permettant à Logto d’émettre un nouveau jeton de rafraîchissement si nécessaire. +Note : Le rafraîchissement du TTL n'est pas disponible dans SPA (application monopage) pour des raisons de sécurité. Cela signifie que Logto n'étendra pas le TTL via des requêtes de jeton. Pour améliorer l'expérience utilisateur, vous pouvez activer la fonctionnalité "Rotation du jeton de rafraîchissement", permettant à Logto d'émettre un nouveau jeton de rafraîchissement lorsque nécessaire. :::caution Jeton de rafraîchissement et liaison de session -Lorsqu’un jeton de rafraîchissement est émis **sans** la portée `offline_access` dans la requête d’autorisation, il sera lié à la session utilisateur. La session a une durée de vie fixe de **14 jours**. Après l’expiration de la session, le jeton de rafraîchissement devient invalide, quelle que soit la configuration de sa propre durée de vie. +Lorsqu'un jeton de rafraîchissement est émis **sans** la portée `offline_access` dans la requête d'autorisation, il sera lié à la session utilisateur. La session a un TTL fixe de **14 jours**. Après l'expiration de la session, le jeton de rafraîchissement devient invalide, quelle que soit sa propre configuration de TTL. -Pour garantir que la configuration de la durée de vie du jeton de rafraîchissement prenne pleinement effet, assurez-vous d’inclure la portée `offline_access` dans votre requête d’autorisation. +Pour garantir que la configuration de TTL du jeton de rafraîchissement prenne pleinement effet, assurez-vous d'inclure la portée `offline_access` dans votre requête d'autorisation. ::: ### URI de déconnexion backchannel \{#backchannel-logout-uri} -Le point de terminaison de déconnexion backchannel OpenID Connect. Voir [Déconnexion fédérée : déconnexion back-channel](#) pour plus d’informations. +Le point de terminaison de déconnexion backchannel d'OpenID Connect. Voir [Déconnexion fédérée : Déconnexion back-channel](#) pour plus d'informations. + +### Subventions maximales autorisées (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` est un champ optionnel au niveau de l'application sous `customClientMetadata` qui contrôle le nombre maximal de subventions actives simultanées par utilisateur pour l'application actuelle. + +- **Défaut** : `undefined` (pas de limite) +- **Lorsqu'il est configuré** : À chaque autorisation réussie, Logto vérifie le total des subventions actives pour l'utilisateur dans l'application actuelle (à travers les navigateurs et les appareils). Si la limite est dépassée, Logto révoque les subventions les plus anciennes. + +Ce paramètre est utile lorsque vous souhaitez limiter les appareils authentifiés simultanés par application. + +:::note + +Ce champ n'est pas pris en charge pour : + +- Applications machine à machine +- Applications protégées +- Applications SAML + +::: ### Données personnalisées \{#custom-data} -Informations personnalisées supplémentaires sur l’application non listées dans les propriétés prédéfinies de l’application ; les utilisateurs peuvent définir leurs propres champs de données personnalisées selon leurs besoins spécifiques, tels que des paramètres et configurations métier. +Informations supplémentaires personnalisées sur l'application non répertoriées dans les propriétés d'application prédéfinies, les utilisateurs peuvent définir leurs propres champs de données personnalisées en fonction de leurs besoins spécifiques, tels que les paramètres et configurations spécifiques à l'entreprise. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..5e6469e74e0 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,170 @@ +# Sessions + +Les sessions dans Logto définissent comment l'état d'authentification est créé, partagé, rafraîchi et révoqué à travers les applications, navigateurs et appareils. + +En pratique, les utilisateurs vivent l'expérience d'être "connectés" comme un état unique, mais l'état du système est divisé en plusieurs couches. Comprendre ces couches est la clé pour concevoir un SSO prévisible, un renouvellement de jeton et un comportement de déconnexion. + +## Modèle de session dans Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Domaine Logto"] + S["Session de connexion"] + G1["Autorisation (App A)"] + G2["Autorisation (App B)"] + end + + subgraph AppA ["Domaine App A"] + A["Session locale / jetons"] + end + + subgraph AppB ["Domaine App B"] + B["Session locale / jetons"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Session de connexion Logto** : État de connexion centralisé stocké sous forme de cookies de domaine Logto. Cela contrôle la disponibilité du SSO dans le contexte du navigateur actuel. +- **Autorisation** : État d'autorisation spécifique à l'application pour `utilisateur + application cliente`. Les autorisations sont le pont entre la connexion centralisée et l'émission de jetons d'application. +- **Session/jetons locaux de l'application** : État d'authentification local dans chaque application (jetons d’identifiant/d’accès/de rafraîchissement, cookie de session de l'application, etc.). + +## Concepts de base \{#core-concepts} + +### Qu'est-ce qu'une session Logto ? \{#what-is-a-logto-session} + +Une session Logto est l'état d'authentification centralisé créé après une connexion réussie. Si elle est toujours valide, Logto peut authentifier les utilisateurs silencieusement pour d'autres applications dans le même locataire. Si elle n'existe pas, les utilisateurs doivent se reconnecter. + +### Qu'est-ce que les autorisations ? \{#what-are-grants} + +Une autorisation est un état d'autorisation au niveau de l'application lié à un utilisateur spécifique et à une application cliente. + +- Une session Logto peut avoir des autorisations pour plusieurs applications. +- Les jetons pour une application sont émis sous l'autorisation de cette application. +- La révocation d'une autorisation affecte la capacité de cette application à continuer l'accès basé sur les jetons. + +### Comment la session, les autorisations et l'état d'authentification de l'application sont liés \{#how-session-grants-and-app-auth-state-relate} + +- **Session** répond : "Ce navigateur peut-il faire du SSO avec Logto en ce moment ?" +- **Autorisation** répond : "Cet utilisateur est-il autorisé pour cette application cliente ?" +- **Session locale de l'application** répond : "Cette application considère-t-elle actuellement l'utilisateur comme connecté ?" + +## Connexion et création de session \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as Application cliente + end + + box Logto + participant OIDC as Fournisseur OIDC + participant SignIn as Page de connexion + end + + User ->> Client: Accéder à l'application + Client ->> OIDC: Requête d’autorisation + OIDC -->> OIDC: Vérifier la session Logto existante + OIDC ->> SignIn: Demander la connexion si nécessaire + SignIn ->> OIDC: L'utilisateur s'authentifie + OIDC -->> OIDC: Créer une session et une autorisation d'application + OIDC ->> Client: Retourner le code d’autorisation + Client ->> OIDC: Échanger le code contre des jetons + OIDC -->> Client: Retourner les jetons +``` + +## Topologie de session à travers les applications et appareils \{#session-topology-across-apps-and-devices} + +### Même navigateur : session Logto partagée \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[Utilisateur] + A["Application cliente A"] + B["Application cliente B"] + C{"Session Logto existe-t-elle ?"} + D["Page de connexion Logto"] + + U --> A + A --> C + U --> B + B --> C + C -->|Non| D +``` + +Les applications dans le même navigateur peuvent partager l'état de session Logto centralisé, de sorte que le SSO peut se produire sans saisie répétée des identifiants. + +### Navigateurs ou appareils différents : sessions Logto isolées \{#different-browsers-or-devices-isolated-logto-sessions} + +Chaque navigateur/appareil a un stockage de cookies séparé. Une session valide sur l'Appareil A n'implique pas une session valide sur l'Appareil B. + +## Cycle de vie de la session \{#session-lifecycle} + +### 1. Créer \{#1-create} + +Après l'authentification de l'utilisateur, Logto crée une session centralisée et une autorisation spécifique à l'application. + +### 2. Réutiliser (SSO) \{#2-reuse-sso} + +Tant que les cookies de session sont valides dans le même navigateur, les nouvelles requêtes d’autorisation peuvent souvent se terminer silencieusement. + +### 3. Renouveler les jetons \{#3-renew-tokens} + +L'accès à l'application se poursuit généralement par des flux de rafraîchissement de jetons (lorsqu'ils sont activés). C'est une continuité au niveau de l'application, distincte de l'existence de la session Logto centralisée. + +### 4. Révoquer/expirer \{#4-revokeexpire} + +La révocation peut se produire à différents niveaux : + +- La déconnexion locale de l'application supprime les jetons/session locaux de l'application. +- La fin de session supprime la session Logto centralisée. +- La révocation d'autorisation supprime la continuité de l'autorisation au niveau de l'application. + +## Recommandations de conception \{#design-recommendations} + +- Gardez la gestion des sessions locales de l'application explicite dans le code de votre application. +- Traitez la session Logto, les autorisations et la session locale de l'application comme des couches séparées. +- Choisissez si la déconnexion doit être uniquement locale à l'application ou globale. +- Utilisez [la déconnexion par canal secondaire](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) lorsque la cohérence multi-applications est requise. +- Pour le comportement de déconnexion et les détails de mise en œuvre, voir [Déconnexion](/end-user-flows/sign-out). + +## Bonnes pratiques pour révoquer l'accès \{#best-practices-for-revoking-access} + +Utilisez différentes stratégies de révocation en fonction de votre objectif : + +- **Révoquer l'accès de vos applications de première partie** : + Révoquez la session cible avec `revokeGrantsTarget=firstParty`. + Cela déconnecte l'utilisateur des applications de première partie associées à cette session, ce qui crée une expérience de déconnexion cohérente. + En même temps, les autorisations pour les applications tierces qui ont `offline_access` accordé peuvent rester disponibles pour les intégrations en cours. + Voir [Gérer les sessions utilisateur](/sessions/manage-user-sessions) pour les détails de révocation de session. + +- **Révoquer l'accès aux applications tierces** : + Choisissez l'une des options suivantes : + + - Révoquez la session avec `revokeGrantsTarget=all` pour révoquer toutes les autorisations associées à cette session. + - Révoquez directement des autorisations spécifiques via les API de gestion des autorisations pour supprimer les autorisations des applications tierces sans forcer une déconnexion complète de la session. + Voir [Gérer les applications autorisées par l'utilisateur (autorisations)](/sessions/grants-management) pour les stratégies de révocation spécifiques aux autorisations. + +- **Lors de l'utilisation de Logto Console** : + Sur la page des détails de l'utilisateur, Logto fournit à la fois la gestion des sessions et la gestion des applications tierces autorisées prêtes à l'emploi. + - Révoquer une session révoque également les autorisations des applications de première partie, pour maintenir un comportement de déconnexion de première partie cohérent. + - Révoquer une autorisation d'application tierce révoque les autorisations pour cette application tierce tout en gardant le statut de session original inchangé. + +## Ressources associées \{#related-resources} + +Gérer les sessions utilisateur + + Gérer les applications autorisées par l'utilisateur (autorisations) + +Configuration de session +Déconnexion +Inscription et connexion + + Comprendre le flux d'authentification + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..94d13e7ff5e --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,73 @@ +--- +sidebar_position: 2 +--- + +# Gérer les applications autorisées par l'utilisateur (autorisations) + +Les autorisations d'application représentent l'état d'autorisation de l'utilisateur pour des applications clientes spécifiques. + +Utilisez la gestion des autorisations lorsque les utilisateurs ou les administrateurs doivent examiner les applications autorisées et révoquer l'accès à une application sans révoquer toute la session Logto. + +Lorsque les autorisations sont révoquées, les jetons d'accès opaques et les jetons de rafraîchissement précédemment émis pour ces autorisations sont invalidés. + +## Choisissez le bon chemin \{#choose-the-right-path} + +| Scénario | Chemin recommandé | +| ------------------------------------------------------------------------------------------------------------ | ----------------- | +| Permettre aux utilisateurs connectés de gérer leurs propres autorisations d'application | Account API | +| Permettre aux administrateurs ou aux équipes de support de gérer les autorisations pour un utilisateur cible | Management API | +| Permettre aux opérateurs de gérer les autorisations d'applications tierces dans l'interface utilisateur | Admin Console | + +## APIs de gestion directe des autorisations \{#direct-grant-management-apis} + +### Account API (self-service) \{#account-api-self-service} + +Utilisez Account API dans les pages de paramètres de compte des utilisateurs finaux : + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- Référence : [Gérer les applications autorisées par l'utilisateur (autorisations)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (outils d'administration) \{#management-api-admin-tools} + +Utilisez Management API dans les outils d'administration et les flux de travail de support : + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- Référence : [Gérer les applications autorisées par l'utilisateur (autorisations)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### Filtrer la liste des autorisations par type d'application \{#filter-grant-list-by-app-type} + +Les points de terminaison de liste des autorisations prennent en charge le paramètre de requête optionnel `appType` : + +- `appType=firstParty` : Lister uniquement les autorisations d'applications de première partie. +- `appType=thirdParty` : Lister uniquement les autorisations d'applications tierces. +- Omettre `appType` : Retourner toutes les autorisations actives. + +## Gérer les autorisations d'applications tierces dans la Console \{#manage-third-party-app-authorizations-in-console} + +Dans Logto Console, utilisez la page de détails de l'utilisateur pour afficher et révoquer les applications tierces autorisées. + +- Référence : [Gérer les applications tierces autorisées par l'utilisateur](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## Révoquer les autorisations lors de la révocation d'une session \{#revoke-grants-when-revoking-a-session} + +Lors de la révocation d'une session via `DELETE /api/my-account/sessions/{sessionId}`, utilisez le paramètre de requête optionnel `revokeGrantsTarget` pour contrôler la portée de la révocation des autorisations : + +- `all` : Révoquer les autorisations pour toutes les applications associées à la session. +- `firstParty` : Révoquer les autorisations pour les applications de première partie uniquement. + +Pour le comportement au niveau de la session et le contexte du point de terminaison, voir [Gérer les sessions utilisateur](/sessions/manage-user-sessions) et [Déconnexion](/end-user-flows/sign-out). + +## Ressources associées \{#related-resources} + +Sessions +Gérer les sessions utilisateur + + Paramètres de compte par Account API : Gérer les applications autorisées par l'utilisateur + (autorisations) + + + Paramètres de compte par Management API : Gérer les applications autorisées par l'utilisateur + (autorisations) + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..428216a1882 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +--- + +# Gérer les sessions utilisateur + +La gestion des sessions utilisateur aide les utilisateurs et les administrateurs à examiner les états de connexion actifs et à révoquer les sessions si nécessaire. + +Dans Logto, vous pouvez gérer les sessions via trois chemins courants : + +- **Account API** : Pour l'auto-service des utilisateurs finaux dans la page des paramètres de compte de votre produit. +- **Management API** : Pour les outils d'administration ou de support afin de gérer les sessions pour tout utilisateur. +- **Admin Console** : Pour les flux de travail des opérateurs dans Logto Console sans créer d'outils personnalisés. + +## Choisissez la bonne API \{#choose-the-right-api} + +| Scénario | API recommandée | +| ------------------------------------------------------------------------------------------------- | --------------- | +| Permettre aux utilisateurs connectés de gérer leurs propres sessions actives | Account API | +| Permettre aux administrateurs ou aux équipes de support de gérer les sessions pour un utilisateur | Management API | +| Permettre aux opérateurs de gérer les sessions directement dans Logto Console | Admin Console | + +## Voir les sessions actives \{#view-active-sessions} + +### Account API (auto-service) \{#account-api-self-service} + +Utilisez le point de terminaison de session de l'Account API pour lister les sessions actives de l'utilisateur actuel. + +- Section de référence : [Gérer les sessions utilisateur](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Point de terminaison : [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +Avant d'exposer cette capacité aux utilisateurs finaux, assurez-vous que la gestion des sessions est activée dans les paramètres du centre de comptes et que votre application demande la portée Account API requise. + +### Management API (outils d'administration) \{#management-api-admin-tools} + +Utilisez Management API lorsque votre système d'administration doit lister les sessions pour un utilisateur cible. + +- Section de référence : [Gestion des sessions utilisateur](/end-user-flows/account-settings/by-management-api#user-session-management) +- Point de terminaison : [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Point de terminaison des détails optionnels : [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## Révoquer les sessions \{#revoke-sessions} + +### Account API (l'utilisateur final révoque ses propres sessions) \{#account-api-end-user-revokes-own-sessions} + +Les utilisateurs finaux peuvent révoquer une session spécifique de leur propre liste de sessions. + +- Section de référence : [Gérer les sessions utilisateur](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Point de terminaison : [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +Pour les opérations sensibles, la gestion des sessions de l'Account API nécessite une vérification de l'utilisateur avant l'accès. Voir [Obtenir un identifiant d'enregistrement de vérification](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id). + +### Management API (l'administrateur révoque les sessions utilisateur) \{#management-api-admin-revokes-user-sessions} + +Les administrateurs peuvent révoquer la session d'un utilisateur cible par ID utilisateur et ID de session. + +- Section de référence : [Gestion des sessions utilisateur](/end-user-flows/account-settings/by-management-api#user-session-management) +- Point de terminaison : [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +Si votre équipe gère les utilisateurs directement dans Logto Console, vous pouvez examiner les sessions actives et révoquer des sessions spécifiques depuis la page de détails de l'utilisateur. + +- Section de référence : [Gérer les sessions actives des utilisateurs](/user-management/manage-users#manage-user-active-sessions) + +## Ressources associées \{#related-resources} + +Sessions + + Gérer les applications autorisées par l'utilisateur (autorisations) + + + Paramètres de compte par Account API : Gérer les sessions utilisateur + + + Paramètres de compte par Management API : Gestion des sessions utilisateur + + + Gestion des utilisateurs : Gérer les sessions actives des utilisateurs + diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..55c50954f01 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 3 +--- + +# Configuration de session + +La configuration de session définit les contrôles au niveau du locataire pour la durée pendant laquelle les sessions de connexion Logto restent actives et comment les politiques d'accès liées aux sessions sont appliquées. + +Cette page couvre : + +- Configuration du TTL de session +- Nombre maximal d'appareils authentifiés simultanément par application + +## Configuration du TTL de session \{#session-ttl-configuration} + +Le TTL de session détermine la durée de vie maximale de la session de connexion OIDC de Logto. +C'est un **paramètre au niveau du locataire** : une fois configuré, il s'applique à toutes les applications et à tous les flux d'authentification de ce locataire. + +### Comportement par défaut \{#default-behavior} + +- Par défaut, le TTL de session est de **14 jours**. +- Si aucun TTL personnalisé n'est configuré, Logto continue d'utiliser cette valeur par défaut. + +### Configurer via Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +Vous pouvez configurer le TTL de session dans la Console sous : + +Console > Tenant > Settings > OIDC settings + +Utilisez **Durée maximale de vie de la session** pour mettre à jour la valeur. + +:::note + +La Console utilise **jours** pour l'entrée et l'affichage, tandis que la configuration / API de session OIDC sous-jacente utilise **secondes**. + +::: + +### Configurer via Management API \{#configure-via-management-api} + +Utilisez ces points de terminaison pour lire et mettre à jour la configuration de session OIDC : + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +Exemple (`ttl` en secondes) : + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` secondes = 14 jours. + +:::note + +Pour les déploiements OSS, redémarrez l'instance de service après avoir modifié `logto-config` afin que le serveur puisse prendre en compte les derniers paramètres OIDC. + +Pour appliquer automatiquement les mises à jour de configuration OIDC sans redémarrer le service, [activez le cache central redis](/logto-oss/central-cache). + +::: + +## Nombre maximal d'appareils authentifiés simultanément par application \{#max-concurrent-authenticated-devices-per-app} + +Le nombre maximal d'appareils authentifiés simultanément par application est un contrôle au niveau de l'application qui limite le nombre de concessions actives que chaque utilisateur peut conserver pour une application spécifique. + +Cela est configuré via le champ `maxAllowedGrants` dans `customClientMetadata` de l'application. +En savoir plus dans [Structure des données de l'application](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants). + +### Comportement \{#behavior} + +Lorsque `maxAllowedGrants` est défini, Logto évalue les concessions actives de l'utilisateur pour l'application actuelle à chaque autorisation réussie. +Si le nombre de concessions actives dépasse la limite, Logto révoque d'abord les plus anciennes. + +Si `maxAllowedGrants` n'est pas défini, il n'y a pas de limite de concurrence. + +### Configurer via Logto Console \{#configure-via-logto-console} + +Vous pouvez configurer cela dans la page de détails de chaque application sous : + + + Console > Applications > Détails de l'application > Limite d'appareils simultanés + + +Définissez le nombre maximal de concessions actives simultanées (appareils) par utilisateur pour l'application actuelle. + +:::note + +Ce paramètre n'est pas pris en charge pour les applications machine à machine, les applications protégées et les applications SAML. + +::: + +## Ressources associées \{#related-resources} + +Sessions +Gérer les sessions utilisateur + + Gérer les applications autorisées par l'utilisateur (concessions) + + + Structure des données de l'application : maxAllowedGrants + +Interagir avec Management API diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index acea3eb8560..675b91c79df 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -4,122 +4,137 @@ sidebar_position: 2 # Gérer les utilisateurs -## Gérer via la Console Logto \{#manage-via-logto-console} +## Gérer via Logto Console \{#manage-via-logto-console} ### Parcourir et rechercher des utilisateurs \{#browse-and-search-users} -Pour accéder à la fonctionnalité de gestion des utilisateurs dans la Console Logto, accédez à Console > Gestion des utilisateurs. Une fois sur place, vous verrez une vue en tableau de tous les utilisateurs. +Pour accéder à la fonctionnalité de gestion des utilisateurs dans le Logto Console, accédez à Console > Gestion des utilisateurs. Une fois là, vous verrez une vue en tableau de tous les utilisateurs. Le tableau se compose de trois colonnes : -- **Utilisateur** : Affiche les informations sur l'utilisateur, telles que son avatar, nom complet, nom d'utilisateur, numéro de téléphone et e-mail. -- **Depuis l'application** : Affiche le nom de l'application avec laquelle l'utilisateur s'est initialement inscrit. -- **Dernière connexion** : Affiche l'horodatage de la dernière connexion de l'utilisateur. +- **Utilisateur** : Il affiche des informations sur l'utilisateur, telles que son avatar, son nom complet, son nom d'utilisateur, son numéro de téléphone et son e-mail. +- **Depuis l'application** : Il affiche le nom de l'application avec laquelle l'utilisateur s'est initialement inscrit. +- **Dernière connexion** : Il affiche l'horodatage de la dernière connexion de l'utilisateur. -La recherche prend en charge la correspondance par mot-clé pour [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email). +Il prend en charge la correspondance de mots-clés pour [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email). ### Ajouter des utilisateurs \{#add-users} -En utilisant la Console, les développeurs peuvent créer de nouveaux comptes pour les utilisateurs finaux. Pour ce faire, cliquez sur le bouton "Ajouter un utilisateur" dans le coin supérieur droit de l'écran. +En utilisant le Console, les développeurs peuvent créer de nouveaux comptes pour les utilisateurs finaux. Pour ce faire, cliquez sur le bouton "Ajouter un utilisateur" dans le coin supérieur droit de l'écran. -Lors de la création d'un utilisateur dans la Console Logto ou via le Management API (et non par auto-inscription de l'utilisateur via l'interface), vous devez fournir au moins un identifiant : `primary email`, `primary phone` ou `username`. Le champ `name` est facultatif. +Lors de la création d'un utilisateur dans le Logto Console ou via le Management API (non auto-enregistré par l'utilisateur final via l'interface utilisateur), vous devez fournir au moins un identifiant : `primary email`, `primary phone`, ou `username`. Le champ `name` est facultatif. -Après la création de l'utilisateur, Logto générera automatiquement un mot de passe aléatoire. Le mot de passe initial n'apparaîtra qu'une seule fois, mais vous pouvez [réinitialiser le mot de passe](./manage-users#reset-user-password) ultérieurement. Si vous souhaitez définir un mot de passe spécifique, utilisez le Management API `patch /api/users/{userId}/password` pour le mettre à jour après la création de l'utilisateur. +Après la création de l'utilisateur, Logto générera automatiquement un mot de passe aléatoire. Le mot de passe initial n'apparaîtra qu'une seule fois, mais vous pouvez [réinitialiser le mot de passe](./manage-users#reset-user-password) plus tard. Si vous souhaitez définir un mot de passe spécifique, utilisez le Management API `patch /api/users/{userId}/password` pour le mettre à jour après la création de l'utilisateur. Vous pouvez copier les **identifiants saisis (adresse e-mail / numéro de téléphone / nom d'utilisateur)** et le **mot de passe initial** en un clic, ce qui facilite le partage de ces informations d'identification avec le nouvel utilisateur afin qu'il puisse se connecter et commencer. :::tip -Si vous souhaitez mettre en place une inscription sur invitation uniquement, nous recommandons [d'inviter les utilisateurs avec un lien magique](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Cela permet uniquement aux utilisateurs sur liste blanche de s'auto-inscrire et de définir leur propre mot de passe. +Si vous souhaitez mettre en œuvre une inscription sur invitation uniquement, nous vous recommandons [d'inviter des utilisateurs avec un lien magique](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Cela permet uniquement aux utilisateurs sur liste blanche de s'auto-enregistrer et de définir leur propre mot de passe. ::: ### Voir et mettre à jour le profil utilisateur \{#view-and-update-the-user-profile} -Pour afficher les détails d'un utilisateur, cliquez simplement sur la ligne correspondante dans le tableau des utilisateurs. Cela vous amènera à la page "**Détails de l'utilisateur**" où vous trouverez les informations du profil de l'utilisateur, notamment : +Pour voir les détails d'un utilisateur, cliquez simplement sur la ligne correspondante dans le tableau des utilisateurs. Cela vous mènera à la page "**Détails de l'utilisateur**" où vous pouvez trouver les informations de profil de l'utilisateur, y compris : - **Données liées à l'authentification** : - **Adresse e-mail** ([primary_email](/user-management/user-data#primary_email)) : Modifiable - **Numéro de téléphone** ([primary_phone](/user-management/user-data#primary_phone)) : Modifiable - **Nom d'utilisateur** ([username](/user-management/user-data#username)) : Modifiable - **Mot de passe** ([has_password](/user-management/user-data#has_password)) : Vous pouvez régénérer un mot de passe aléatoire. En savoir plus sur "[Réinitialiser le mot de passe utilisateur](#reset-user-password)". - - **Authentification multi-facteurs (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)) : Affichez tous les facteurs d'authentification (par exemple, passkeys, applications d'authentification, codes de secours) que cet utilisateur a configurés. Les facteurs peuvent être supprimés dans la Console. - - **Passkeys** : Lorsque la [connexion par passkey](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) est activée dans le tenant, vous pouvez également voir les passkeys de connexion de l'utilisateur sur la page des détails utilisateur et les supprimer si nécessaire. Ces passkeys sont basées sur le même modèle d'identifiants WebAuthn utilisé par la MFA. - - **Jeton d’accès personnel** : Créez, affichez, renommez et supprimez les [jetons d’accès personnels](/user-management/personal-access-token). + - **Authentification multi-facteurs (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)) : Voir tous les facteurs d'authentification (par exemple, clés de passe, applications d'authentification, codes de secours) que cet utilisateur a configurés. Les facteurs peuvent être supprimés dans le Console. + - **Clés de passe** : Lorsque [la connexion par clé de passe](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) est activée dans le locataire, vous pouvez également voir les clés de passe de connexion de l'utilisateur sur la page des détails de l'utilisateur et les supprimer si nécessaire. Ces clés de passe sont soutenues par le même modèle d'identification WebAuthn utilisé par MFA. + - **Jeton d'accès personnel** : Créer, voir, renommer et supprimer des [jetons d'accès personnels](/user-management/personal-access-token). - **Connexion** : - **Connexions sociales** ([identities](/user-management/user-data#social-identities)) : - - Affichez les comptes sociaux liés de l'utilisateur, y compris les identifiants sociaux et les détails du profil synchronisés depuis leurs fournisseurs sociaux (par exemple, une entrée "Facebook" apparaîtra si l'utilisateur s'est connecté via Facebook). + - Voir les comptes sociaux liés de l'utilisateur, y compris les identifiants sociaux et les détails de profil synchronisés depuis leurs fournisseurs sociaux (par exemple, une entrée "Facebook" apparaîtra si l'utilisateur s'est connecté via Facebook). - Vous pouvez supprimer les identités sociales existantes, mais vous ne pouvez pas lier de nouveaux comptes sociaux au nom de l'utilisateur. - - Pour les connecteurs sociaux avec [stockage de jetons](/secret-vault/federated-token-set) activé, vous pouvez afficher et gérer les jetons d’accès et les jetons de rafraîchissement sur la page de détail de la connexion. + - Pour les connecteurs sociaux avec [stockage de jetons](/secret-vault/federated-token-set) activé, vous pouvez voir et gérer les jetons d'accès et les jetons de rafraîchissement sur la page de détails de la connexion. - **Connexions SSO d’entreprise** ([sso_identities](/user-management/user-data#sso-identities)) : - - Affichez les identités d’entreprise liées de l'utilisateur, y compris les identifiants d’entreprise et les détails du profil synchronisés depuis leurs fournisseurs d'identité d’entreprise. - - Vous ne pouvez pas ajouter ou supprimer des identités SSO d’entreprise dans la Console. - - Pour les connecteurs d’entreprise basés sur OIDC avec [stockage de jetons](/secret-vault/federated-token-set) activé, vous pouvez afficher et supprimer les jetons sur la page de détail de la connexion. -- **Données du profil utilisateur** : nom, URL de l'avatar, données personnalisées et revendications standard OpenID Connect supplémentaires qui ne sont pas incluses. Tous ces champs de profil sont modifiables. -- **Sessions** : Affichez la liste des sessions actives de l'utilisateur, y compris les informations sur l'appareil, l'identifiant de session et la localisation GEO si applicable. Affichez plus de détails sur une session et révoquez-la sur la page de détail de la session. + - Voir les identités d'entreprise liées de l'utilisateur, y compris les identifiants d'entreprise et les détails de profil synchronisés depuis leurs fournisseurs d'identité d'entreprise. + - Vous ne pouvez pas ajouter ou supprimer des identités SSO d’entreprise dans le Console. + - Pour les connecteurs d'entreprise basés sur OIDC avec [stockage de jetons](/secret-vault/federated-token-set) activé, vous pouvez voir et supprimer les jetons sur la page de détails de la connexion. +- **Données de profil utilisateur** : nom, URL de l'avatar, données personnalisées et revendications standard OpenID Connect supplémentaires qui ne sont pas incluses. Tous ces champs de profil sont modifiables. +- **Sessions** : Voir la liste des sessions actives de l'utilisateur, y compris les informations sur l'appareil, l'ID de session et la localisation GEO si applicable. Voir plus de détails sur une session et la révoquer sur la page de détails de la session. :::warning -Il est important de vérifier que l'utilisateur dispose d'une méthode de connexion alternative avant de supprimer une connexion sociale, comme une autre connexion sociale, un numéro de téléphone, une adresse e-mail ou un nom d'utilisateur avec mot de passe. Si l'utilisateur ne dispose d'aucune autre méthode de connexion, il ne pourra plus accéder à son compte une fois la connexion sociale supprimée. +Il est important de confirmer que l'utilisateur dispose d'une méthode de connexion alternative avant de supprimer une connexion sociale, telle qu'une autre connexion sociale, un numéro de téléphone, un e-mail ou un nom d'utilisateur avec mot de passe. Si l'utilisateur n'a pas d'autre méthode de connexion, il ne pourra plus accéder à son compte une fois la connexion sociale supprimée. ::: ### Voir les activités de l'utilisateur \{#view-user-activities} -Pour consulter les activités récentes d'un utilisateur, accédez à l'onglet "Journaux utilisateur" sur la page des détails utilisateur. Vous y trouverez un tableau affichant les activités récentes de l'utilisateur, y compris l'action effectuée, le résultat de l'action, l'application concernée et l'heure à laquelle l'utilisateur a agi. +Pour voir les activités récentes d'un utilisateur, accédez à l'onglet "Journaux de l'utilisateur" sur la page des "Détails de l'utilisateur". Ici, vous pouvez trouver un tableau qui affiche les activités récentes de l'utilisateur, y compris l'action effectuée, le résultat de l'action, l'application concernée et le moment où l'utilisateur a agi. -Cliquez sur la ligne du tableau pour voir plus de détails dans le journal utilisateur, par exemple l'adresse IP, l'agent utilisateur, les données brutes, etc. +Cliquez sur la ligne du tableau pour voir plus de détails dans le journal de l'utilisateur, par exemple, l'adresse IP, l'agent utilisateur, les données brutes, etc. ### Suspendre un utilisateur \{#suspend-user} Sur la page "Détails de l'utilisateur", cliquez sur "Trois points" -> bouton "Suspendre l'utilisateur". -Une fois qu'un utilisateur est suspendu, il ne pourra plus se connecter à votre application et ne pourra plus obtenir de nouveau jeton d’accès après l'expiration de l'actuel. De plus, toute requête API effectuée par cet utilisateur échouera. +Une fois qu'un utilisateur est suspendu, il ne pourra plus se connecter à votre application et ne pourra pas obtenir un nouveau jeton d’accès après l'expiration de l'actuel. De plus, toute requête API effectuée par cet utilisateur échouera. Si vous souhaitez réactiver cet utilisateur, vous pouvez le faire en cliquant sur "Trois points" -> bouton "Réactiver l'utilisateur". ### Supprimer un utilisateur \{#delete-user} -Sur la page "Détails de l'utilisateur", cliquez sur "Trois points" -> bouton "Supprimer". La suppression d'un utilisateur est irréversible. +Sur la page "Détails de l'utilisateur", cliquez sur "Trois points" -> bouton "Supprimer". La suppression d'un utilisateur ne peut pas être annulée. -### Réinitialiser le mot de passe utilisateur \{#reset-user-password} +### Réinitialiser le mot de passe de l'utilisateur \{#reset-user-password} Sur la page "Détails de l'utilisateur", cliquez sur "Trois points" -> bouton "Réinitialiser le mot de passe", puis Logto régénérera automatiquement un mot de passe aléatoire. Après avoir réinitialisé le mot de passe, copiez-le et envoyez-le à l'utilisateur final. Une fois la fenêtre modale "Réinitialiser le mot de passe" fermée, vous ne pourrez plus voir le mot de passe. Si vous oubliez de le conserver, vous pouvez le réinitialiser à nouveau. -Vous ne pouvez pas définir un mot de passe spécifique pour les utilisateurs dans la Console Logto, mais vous pouvez utiliser le [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` pour spécifier un mot de passe. +Vous ne pouvez pas définir un mot de passe spécifique pour les utilisateurs dans le Logto Console, mais vous pouvez utiliser le [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` pour spécifier un mot de passe. ### Gérer les sessions actives de l'utilisateur \{#manage-user-active-sessions} -Sur la page "Détails de l'utilisateur", accédez à la page "Détails de la session" en cliquant sur le bouton "Gérer" d'une session spécifique. Ici, vous pouvez voir des informations détaillées sur la session, telles que l'appareil, la localisation et l'heure de connexion. Si vous souhaitez déconnecter l'utilisateur de cette session, cliquez simplement sur le bouton "Révoquer la session" en haut à droite, et la session sera immédiatement révoquée. +Sur la page "Détails de l'utilisateur", accédez à la page "Détails de la session" en cliquant sur le bouton "Gérer" d'une session spécifique. Ici, vous pouvez voir des informations détaillées sur la session, telles que l'appareil, la localisation et l'heure de connexion. Si vous souhaitez déconnecter l'utilisateur de cette session, cliquez simplement sur le bouton "Révoquer la session" dans le coin supérieur droit, et la session sera immédiatement révoquée. -- Par défaut, la révocation d'une session dans la Console révoquera également toutes les autorisations d'applications propriétaires associées à cette session, et l'utilisateur devra se reconnecter pour restaurer l'accès. Tous les jetons d’accès opaques et jetons de rafraîchissement préalablement émis pour les applications propriétaires seront également révoqués immédiatement. -- Pour les applications tierces avec la portée `offline_access`, la révocation d'une session ne révoque pas l'autorisation de l'application par défaut, les jetons de rafraîchissement préalablement émis peuvent toujours être utilisés jusqu'à l'expiration de l'autorisation. +- Par défaut, la révocation d'une session sur le Console révoquera également toutes les autorisations d'application de première partie associées à cette session, et l'utilisateur devra se reconnecter pour restaurer l'accès. Tous les jetons d’accès opaques et les jetons de rafraîchissement pré-émis pour les applications de première partie seront également révoqués immédiatement. +- Pour les applications tierces avec la portée `offline_access`, la révocation d'une session ne révoque pas l'autorisation de l'application par défaut, les jetons de rafraîchissement pré-émis peuvent toujours être utilisés jusqu'à l'expiration de l'autorisation. -## Vérification de conformité des mots de passe \{#password-compliance-check} +### Gérer les applications tierces autorisées par l'utilisateur \{#manage-user-authorized-third-party-apps} -Après avoir mis à jour la [politique de mot de passe](/security/password-policy) dans Logto, les utilisateurs existants peuvent toujours se connecter avec leurs mots de passe actuels. Seuls les nouveaux comptes créés devront respecter la politique de mot de passe mise à jour. +Sur la page "Détails de l'utilisateur", vous pouvez utiliser la section "Applications tierces autorisées" pour examiner le statut d'autorisation des applications pour l'utilisateur. +Cette section est soutenue par les APIs de gestion des applications autorisées par l'utilisateur (autorisations). -Pour appliquer une sécurité renforcée, vous pouvez utiliser l’API `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) pour vérifier si le mot de passe d'un utilisateur respecte la politique actuelle définie dans l'expérience de connexion par défaut. Si ce n'est pas le cas, vous pouvez inviter l'utilisateur à mettre à jour son mot de passe avec un flux personnalisé utilisant [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). +Pour chaque application autorisée, le Console affiche : + +- Nom de l'application +- ID de l'application +- Heure de création de l'accès + +Si vous devez supprimer l'accès, cliquez sur l'action de révocation et confirmez dans la fenêtre modale. + +La révocation d'une autorisation d'application supprime toutes les autorisations tierces actives associées à cette application pour l'utilisateur. Elle révoquera également immédiatement tous les jetons d’accès opaques et les jetons de rafraîchissement pré-émis pour cette application. + +## Vérification de la conformité des mots de passe \{#password-compliance-check} + +Après avoir mis à jour la [politique de mot de passe](/security/password-policy) dans Logto, les utilisateurs existants peuvent toujours se connecter avec leurs mots de passe actuels. Seuls les nouveaux comptes créés devront suivre la politique de mot de passe mise à jour. + +Pour renforcer la sécurité, vous pouvez utiliser l'API `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) pour vérifier si le mot de passe d'un utilisateur respecte la politique actuelle définie dans l'expérience de connexion par défaut. Si ce n'est pas le cas, vous pouvez inviter l'utilisateur à mettre à jour son mot de passe avec un flux personnalisé en utilisant [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). ### Gérer les rôles des utilisateurs \{#manage-roles-of-users} -Dans l'onglet "Rôles" de la page des détails utilisateur, vous pouvez facilement attribuer ou retirer des rôles selon vos besoins. Consultez [Contrôle d’accès basé sur les rôles (RBAC)](/authorization/role-based-access-control) pour plus de détails. +Dans l'onglet "Rôles" de la page des détails de l'utilisateur, vous pouvez facilement attribuer ou supprimer des rôles pour atteindre votre objectif souhaité. Consultez [Contrôle d’accès basé sur les rôles](/authorization/role-based-access-control) pour plus de détails. ### Voir les organisations auxquelles l'utilisateur appartient \{#view-the-organizations-the-user-belongs-to} -Logto prend en charge les [organisations](/organizations/organization-management) et peut gérer leurs membres. Vous pouvez facilement afficher les détails de l'utilisateur et voir à quelle organisation il appartient. +Logto prend en charge les [organisations](/organizations/organization-management) et peut gérer leurs membres. Vous pouvez facilement voir les détails de l'utilisateur et voir à quelle organisation il appartient. ## Gérer via Logto Management API \{#manage-via-logto-management-api} -Le [Management API](/concepts/core-service/#management-api) est un ensemble d'API qui donnent accès au service backend Logto. Comme mentionné précédemment, l'API utilisateur est un composant essentiel de ce service et peut prendre en charge un large éventail de scénarios. +[Management API](/concepts/core-service/#management-api) est un ensemble d'APIs qui fournissent un accès au service backend de Logto. Comme mentionné précédemment, l'API utilisateur est un composant critique de ce service et peut prendre en charge un large éventail de scénarios. -Les [API RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) liées aux utilisateurs sont montées sur `/api/users` à l'exception des activités utilisateur, c'est-à-dire les journaux utilisateur `/api/logs?userId=:userId`. +Les APIs [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) liées aux utilisateurs sont montées sur `/api/users` à l'exception des activités des utilisateurs, c'est-à-dire les journaux des utilisateurs `/api/logs?userId=:userId`. -Vous pouvez gérer les utilisateurs via le Management API dans plusieurs cas d'utilisation, tels que [recherche avancée d'utilisateurs](/user-management/advanced-user-search), [création de comptes en masse](https://openapi.logto.io/operation/operation-createuser), [inscription sur invitation uniquement](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. +Vous pouvez gérer les utilisateurs via le Management API dans plusieurs cas d'utilisation. Tels que [recherche avancée d'utilisateurs](/user-management/advanced-user-search), [création de comptes en masse](https://openapi.logto.io/operation/operation-createuser), [inscription sur invitation uniquement](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. -## FAQ \{#faqs} +## FAQs \{#faqs}
@@ -129,8 +144,8 @@ Vous pouvez gérer les utilisateurs via le Management API dans plusieurs cas d'u -En raison de la nature [Omni-sign-in](https://logto.io/products/omni-sign-in) de Logto, il n'est pas conçu pour restreindre l'accès des utilisateurs à certaines applications avant l'authentification. -Cependant, vous pouvez toujours concevoir des rôles et des permissions utilisateur spécifiques à l'application pour protéger vos ressources API, et valider les permissions lors de l'accès à l'API après la connexion réussie de l'utilisateur. -Consultez Autorisation : [Contrôle d’accès basé sur les rôles (RBAC)](/authorization/role-based-access-control) pour plus d'informations. +En raison de la nature de [l'Omni-sign-in](https://logto.io/products/omni-sign-in) de Logto, il n'est pas conçu pour restreindre l'accès des utilisateurs à certaines applications avant l'authentification. +Cependant, vous pouvez toujours concevoir des rôles et des permissions spécifiques à l'application pour protéger vos ressources API, et valider les permissions lors de l'accès à l'API après une connexion réussie de l'utilisateur. +Consultez Autorisation : [Contrôle d’accès basé sur les rôles](/authorization/role-based-access-control) pour plus d'informations.
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 428d579c0fa..de01dd4e058 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -1,56 +1,56 @@ --- id: signing-keys -title: 署名鍵 -sidebar_label: 署名鍵 +title: 署名キー +sidebar_label: 署名キー sidebar_position: 5 --- -# 署名鍵 +# 署名キー -Logto の [OIDC 署名鍵](https://auth.wiki/signing-key)（「OIDC プライベート鍵」や「OIDC クッキー鍵」とも呼ばれます）は、Logto の [サインインセッション](/end-user-flows/sign-out#what-is-a-logto-session) で JWT（[アクセス トークン](https://auth.wiki/access-token) や [ID トークン](https://auth.wiki/id-token)）およびブラウザクッキーに署名するために使用される鍵です。これらの署名鍵は、Logto データベースの初期化時（[オープンソース](/logto-oss)）や新しいテナント作成時（[Cloud](/logto-cloud)）に生成され、[CLI](/logto-oss/using-cli)（オープンソース）、Management API、またはコンソール UI から管理できます。 +Logto の [OIDC 署名キー](https://auth.wiki/signing-key) は、「OIDC プライベートキー」や「OIDC クッキーキー」としても知られ、Logto の [サインインセッション](/sessions#what-is-a-logto-session) で JWT（[アクセス トークン](https://auth.wiki/access-token) と [ID トークン](https://auth.wiki/id-token)）やブラウザクッキーを署名するために使用されます。これらの署名キーは、Logto データベースをシードする際（[オープンソース](/logto-oss)）や新しいテナントを作成する際（[Cloud](/logto-cloud)）に生成され、[CLI](/logto-oss/using-cli)（オープンソース）、Management API、または Console UI を通じて管理できます。 -デフォルトでは、Logto は楕円曲線（EC）アルゴリズムを使用してデジタル署名を生成します。しかし、ユーザーが JWT 署名を検証する必要がある場合や、多くの古いツールが EC アルゴリズムをサポートしておらず（RSA のみサポート）、このためプライベート鍵のローテーション機能と署名アルゴリズム（RSA および EC の両方を含む）の選択機能を実装しています。これにより、古い署名検証ツールを使用するサービスとの互換性が確保されます。 +デフォルトでは、Logto は楕円曲線 (EC) アルゴリズムを使用してデジタル署名を生成します。しかし、ユーザーが JWT 署名を検証する必要があることが多く、古いツールの多くが EC アルゴリズムをサポートしていない（RSA のみをサポートしている）ことを考慮して、プライベートキーをローテーションし、署名アルゴリズム（RSA と EC の両方を含む）を選択できる機能を実装しました。これにより、古い署名検証ツールを使用するサービスとの互換性が確保されます。 :::note -理論的には、署名鍵は漏洩してはならず、有効期限もありません。つまり、ローテーションする必要はありません。しかし、一定期間ごとに署名鍵をローテーションすることでセキュリティを強化できます。 +理論的には、署名キーは漏洩せず、期限がないため、ローテーションする必要はありません。しかし、一定期間後に署名キーを定期的にローテーションすることでセキュリティを強化できます。 ::: -## 仕組み \{#how-it-works} +## どのように機能するのか？ \{#how-it-works} -- **OIDC プライベート鍵** - Logto インスタンスの初期化時に、公開鍵とプライベート鍵のペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークンや ID トークン）を発行する際、そのトークンはプライベート鍵で署名されます。同時に、JWT を受け取ったクライアントアプリケーションは、ペアとなる公開鍵を使ってトークン署名を検証し、トークンが第三者によって改ざんされていないことを確認できます。プライベート鍵は Logto サーバー上で保護されます。一方、公開鍵はその名の通り誰でもアクセス可能であり、OIDC エンドポイントの `/oidc/jwks` インターフェースから取得できます。プライベート鍵生成時に署名鍵アルゴリズムを指定でき、Logto はデフォルトで EC（楕円曲線）アルゴリズムを使用します。管理者ユーザーは、プライベート鍵のローテーションによってデフォルトのアルゴリズムを RSA（Rivest-Shamir-Adleman）に変更できます。 -- **OIDC クッキー鍵** - ユーザーがサインインまたはサインアップフローを開始すると、サーバー上で「OIDC セッション」が作成され、同時に一連のブラウザクッキーも作成されます。これらのクッキーにより、ブラウザは Logto Experience API にリクエストを送り、サインイン、サインアップ、パスワードリセットなどの一連の操作をユーザーの代わりに実行できます。しかし、JWT とは異なり、クッキーは Logto OIDC サービス自身のみが署名・検証を行い、非対称暗号化は必要ありません。そのため、クッキー署名鍵にはペアとなる公開鍵や非対称暗号化アルゴリズムはありません。 +- **OIDC プライベートキー** + Logto インスタンスを初期化する際に、公開鍵とプライベートキーのペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークンまたは ID トークン）を発行する際に、トークンはプライベートキーで署名されます。同時に、JWT を受け取ったクライアントアプリケーションは、ペアになった公開鍵を使用してトークン署名を検証し、トークンが第三者によって改ざんされていないことを確認できます。プライベートキーは Logto サーバーで保護されていますが、公開鍵はその名の通り、誰でもアクセス可能であり、OIDC エンドポイントの `/oidc/jwks` インターフェースを通じてアクセスできます。署名キーアルゴリズムはプライベートキーを生成する際に指定でき、Logto はデフォルトで EC（楕円曲線）アルゴリズムを使用します。管理者ユーザーは、プライベートキーをローテーションすることでデフォルトのアルゴリズムを RSA（Rivest-Shamir-Adleman）に変更できます。 +- **OIDC クッキーキー** + ユーザーがサインインまたはサインアップフローを開始すると、サーバー上に「OIDC セッション」が作成され、ブラウザクッキーのセットも作成されます。これらのクッキーを使用して、ブラウザは Logto Experience API にリクエストを送信し、サインイン、サインアップ、パスワードリセットなどの一連の操作をユーザーの代わりに実行できます。ただし、JWT とは異なり、クッキーは Logto OIDC サービス自体によってのみ署名および検証され、非対称暗号化手段は必要ありません。したがって、クッキー署名キーにはペアになった公開鍵はなく、非対称暗号化アルゴリズムもありません。 -## コンソール UI から署名鍵をローテーションする \{#rotate-signing-keys-from-console-ui} +## Console UI から署名キーをローテーションする \{#rotate-signing-keys-from-console-ui} -Logto には「署名鍵ローテーション」機能があり、テナント内で新しい OIDC プライベート鍵およびクッキー鍵を作成できます。 +Logto は「署名キーのローテーション」機能を導入しており、テナント内で新しい OIDC プライベートキーとクッキーキーを作成できます。 -1. コンソール > 署名鍵 +1. コンソール > テナント設定 > OIDC 設定 に移動します。ここで OIDC プライベート鍵と OIDC クッキー鍵の両方を管理できます。 2. 署名鍵をローテーションするには、「プライベート鍵をローテーション」または「クッキー鍵をローテーション」ボタンをクリックします。プライベート鍵をローテーションする際、署名アルゴリズムを変更することも可能です。 3. 使用中のすべての署名鍵が一覧表示されたテーブルが表示されます。注意：前の鍵は削除できますが、現在の鍵は削除できません。 - | ステータス | 説明 | - | ---------- | -------------------------------------------------------------------------------------------------------------- | - | 現在 | この鍵が現在アプリケーションや API でアクティブに使用されていることを示します。 | - | 前回 | 以前使用されていたがローテーションされた鍵を指します。この署名鍵で発行された既存のトークンは引き続き有効です。 | + | ステータス | 説明 | + | ---------- | ------------------------------------------------------------------------------------------------------ | + | 現在 | このキーが現在、アプリケーションや API 内でアクティブに使用されていることを示します。 | + | 以前 | 以前使用されていたが、ローテーションされたキーを指します。この署名キーを持つ既存のトークンは有効です。 | -ローテーションは以下の 3 つのアクションを含むことを忘れないでください： +ローテーションには次の 3 つのアクションが含まれることを忘れないでください： -1. **新しい署名鍵の作成**：これにより、すべての **アプリケーション** および **API** で新しい署名鍵の採用が必要となります。 -2. **現在の鍵のローテーション**：既存の鍵はローテーション後「前回」として指定され、新規作成されたアプリケーションや API では使用されません。ただし、この鍵で署名されたトークンは引き続き有効です。 -3. **前回の鍵の削除**： 「前回」とラベル付けされた鍵は失効し、テーブルから削除されます。 +1. **新しい署名キーの作成**：これにより、すべての **アプリケーション** と **API** が新しい署名キーを採用する必要があります。 +2. **現在のキーのローテーション**：既存のキーはローテーション後に「以前」として指定され、新しく作成されたアプリケーションや API では使用されません。ただし、このキーで署名されたトークンは依然として有効です。 +3. **以前のキーの削除**：ラベルが「以前」とされているキーは取り消され、テーブルから削除されます。 :::warning -署名鍵を連続して（2 回以上）ローテーションしないでください。すべての発行済みトークンが無効になる可能性があります。 +署名キーを連続して（2 回以上）ローテーションしないでください。これにより、発行されたすべてのトークンが無効になる可能性があります。 -- OSS ユーザーの場合、署名鍵をローテーションした後、新しい署名鍵を有効にするには Logto インスタンスの再起動が必要です。 -- Cloud ユーザーの場合、ローテーション後すぐに新しい署名鍵が有効になりますが、署名鍵を連続して複数回ローテーションしないようご注意ください。 +- OSS ユーザーの場合、署名キーをローテーションした後、新しい署名キーを有効にするために Logto インスタンスの再起動が必要です。 +- Cloud ユーザーの場合、新しい署名キーはローテーション後すぐに有効になりますが、署名キーを連続して複数回ローテーションしないようにしてください。 ::: ## 関連リソース \{#related-resources} - + JWT における EC および RSA 署名アルゴリズムの紹介 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index deb1b7e1f95..057e563e26b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,118 +1,121 @@ --- -description: アカウント API を使用してユーザーを管理する方法を学ぶ +description: Account API を使用してユーザーを管理する方法を学ぶ sidebar_position: 1 --- -# アカウント設定（Account API 経由） +# Account API によるアカウント設定 ## Logto Account API とは \{#what-is-logto-account-api} -Logto Account API は、エンドユーザーが Management API を経由せずに直接 API アクセスできる包括的な API セットです。主な特徴は以下の通りです： +Logto Account API は、エンドユーザーが Management API を経由せずに直接 API にアクセスできる包括的な API セットです。以下はそのハイライトです： -- 直接アクセス：Account API により、エンドユーザーは自分のアカウントプロファイルへ直接アクセスし管理できます。Management API の中継は不要です。 -- ユーザープロファイルとアイデンティティ管理：ユーザーは自分のプロファイルやセキュリティ設定を完全に管理できます。メール、電話、パスワードなどのアイデンティティ情報の更新や、ソーシャル連携の管理が可能です。多要素認証 (MFA) やシングルサインオン (SSO) のサポートも近日追加予定です。 -- グローバルアクセス制御：管理者はアクセス設定をグローバルに完全管理でき、各フィールドごとにカスタマイズ可能です。 -- シームレスな認可 (Authorization)：認可 (Authorization) がこれまで以上に簡単に！`client.getAccessToken()` を使って OP (Logto) 用の不透明トークン (Opaque token) を取得し、`Authorization` ヘッダーに `Bearer ` として付与するだけです。 +- 直接アクセス: Account API は、エンドユーザーが自分のアカウントプロファイルに直接アクセスし管理することを可能にし、Management API の中継を必要としません。 +- ユーザープロファイルとアイデンティティ管理: ユーザーは、メール、電話、パスワードなどのアイデンティティ情報の更新やソーシャル接続の管理を含む、プロファイルとセキュリティ設定を完全に管理できます。MFA と SSO のサポートは近日中に提供予定です。 +- グローバルアクセス制御: 管理者はアクセス設定を完全にグローバルに制御でき、各フィールドをカスタマイズできます。 +- シームレスな認可 (Authorization): 認可 (Authorization) はこれまでになく簡単です！`client.getAccessToken()` を使用して OP (Logto) の不透明トークンを取得し、`Bearer ` として Authorization ヘッダーに添付します。 -Logto Account API を使えば、Logto と完全連携したプロフィールページのようなカスタムアカウント管理システムを構築できます。 +Logto Account API を使用すると、Logto と完全に統合されたプロファイルページのようなカスタムアカウント管理システムを構築できます。 -よくあるユースケース例： +以下は一般的な使用例です： - ユーザープロファイルの取得 - ユーザープロファイルの更新 - ユーザーパスワードの更新 -- メール・電話・ソーシャル連携などのユーザーアイデンティティの更新 -- MFA 要素（認証要素）の管理 +- メール、電話、ソーシャル接続を含むユーザーアイデンティティの更新 +- MFA 要素（検証）の管理 - ユーザーセッションの管理 +- ユーザー承認アプリ（グラント）の管理 -利用可能な API について詳しくは [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) および [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) をご覧ください。 +利用可能な API について詳しく知るには、 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) と [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) をご覧ください。 :::note -SSO アカウントの閲覧やアカウント削除機能は現在 Logto Management API 経由で提供されています。実装詳細は [Management API によるアカウント設定](/end-user-flows/account-settings/by-management-api) をご参照ください。 +SSO アカウントの表示とアカウント削除機能は現在、Logto Management API を通じて利用可能です。実装の詳細については、 [Management API によるアカウント設定](/end-user-flows/account-settings/by-management-api) を参照してください。 ::: -## Account API の有効化方法 \{#how-to-enable-account-api} +## Account API を有効にする方法 \{#how-to-enable-account-api} - コンソール > サインイン & アカウント > アカウントセンター + {' '} + Console > Sign-in & account > Account center{' '} に移動します。 -Account API はデフォルトで無効化されており、アクセス制御もロックされています。**Account API を有効化** を切り替えてオンにしてください。 +Account API はデフォルトでオフになっているため、そのアクセス制御はロックされています。**Enable Account API** を切り替えてオンにします。 -有効化後は、識別子・プロファイルデータ・サードパーティトークンアクセスごとにフィールド単位で権限を設定できます。各フィールドは `Off`、`ReadOnly`、`Edit` のいずれかをサポートし、デフォルトは `Off` です。 +有効にすると、識別子、プロファイルデータ、およびサードパーティトークンアクセスのフィールドごとの権限を設定できます。各フィールドは `Off`、`ReadOnly`、または `Edit` をサポートし、デフォルトは `Off` です。 -1. **セキュリティフィールド**: - - 対象フィールド：プライマリメール、プライマリ電話、ソーシャルアイデンティティ、パスワード、MFA。 - - エンドユーザーがこれらのフィールドを編集する前に、パスワード・メール・SMS いずれかで本人確認を行い、10 分間有効な認証記録 ID を取得する必要があります。詳細は [認証記録 ID の取得](#get-a-verification-record-id) を参照してください。 - - MFA 用 WebAuthn パスキーを利用する場合は、**WebAuthn 関連オリジン** にフロントエンドアプリのドメインを追加し、アカウントセンターとサインイン体験でパスキーを共有できるようにします。詳細は [新しい WebAuthn パスキーの連携](#link-a-new-webauthn-passkey) を参照してください。 -2. **プロファイルフィールド**: - - 対象フィールド：ユーザー名、氏名、アバター、[プロファイル](/user-management/user-data#profile)（その他標準プロファイル属性）、[カスタムデータ](/user-management/user-data#custom-data)。 - - これらは追加の認証なしでエンドユーザーが編集可能です。 -3. **シークレットボールト**: - - OIDC / OAuth ソーシャル・エンタープライズコネクター用に、Logto の [シークレットボールト](/secret-vault/federated-token-set) が認証後のサードパーティアクセストークン・リフレッシュトークンを安全に保存します。アプリは、たとえば Google カレンダーイベントの同期など、再度サインインを求めることなく外部 API を呼び出せます。Account API 有効化後、自動的にトークン取得が可能になります。 -4. **セッション管理**: - - 有効化すると、ユーザーは自身のアクティブセッション（デバイス情報や最終サインイン時刻を含む）を閲覧・管理できます。特定デバイスからのログアウト（セッションの取り消し）も可能です。 - - セッション管理にアクセスする前に、パスワード・メール・SMS いずれかで本人確認を行い、10 分間有効な認証記録 ID を取得する必要があります。詳細は [認証記録 ID の取得](#get-a-verification-record-id) を参照してください。 +1. **セキュリティフィールド**： + - フィールドには、プライマリメール、プライマリ電話、ソーシャルアイデンティティ、パスワード、MFA が含まれます。 + - エンドユーザーがこれらのフィールドを編集する前に、パスワード、メール、または SMS を介して自分のアイデンティティを確認し、10 分間の検証レコード ID を取得する必要があります。 [Get a verification record id](#get-a-verification-record-id) を参照してください。 + - MFA に WebAuthn パスキーを使用するには、フロントエンドアプリのドメインを **WebAuthn Related Origins** に追加し、アカウントセンターとサインイン体験でパスキーを共有できるようにします。 [Link a new WebAuthn passkey](#link-a-new-webauthn-passkey) を参照してください。 +2. **プロファイルフィールド**： + - フィールドには、ユーザー名、名前、アバター、[プロファイル](/user-management/user-data#profile)（他の標準プロファイル属性）、および [カスタムデータ](/user-management/user-data#custom-data) が含まれます。 + - エンドユーザーは追加の検証なしでこれらを編集できます。 +3. **シークレットボールト**： + - OIDC または OAuth ソーシャルおよびエンタープライズコネクターの場合、Logto [シークレットボールト](/secret-vault/federated-token-set) は、認証後にサードパーティのアクセスおよびリフレッシュトークンを安全に保存します。これにより、アプリはユーザーに再度サインインを促すことなく、Google カレンダーイベントの同期などの外部 API を呼び出すことができます。Account API が有効になると、トークンの取得が自動的に利用可能になります。 +4. **セッション管理**： + - 有効にすると、ユーザーはアクティブなセッションを表示および管理でき、デバイス情報や最後のサインイン時間を含みます。ユーザーは特定のデバイスからログアウトするためにセッションを取り消すこともできます。 + - この同じ `Sessions` フィールドの権限は、ユーザー承認アプリ（グラント）API（表示およびグラントの取り消し）も制御します。 + - エンドユーザーがセッション管理にアクセスする前に、パスワード、メール、または SMS を介して自分のアイデンティティを確認し、10 分間の検証レコード ID を取得する必要があります。 [Get a verification record id](#get-a-verification-record-id) を参照してください。 -## Account API へのアクセス方法 \{#how-to-access-account-api} +## Account API にアクセスする方法 \{#how-to-access-account-api} :::note -アクセストークンに適切な権限が付与されていることを確認するため、Logto 設定で対応するスコープを正しく設定してください。 +アクセス トークンに適切な権限があることを確認するために、Logto 設定で対応するスコープを適切に構成してください。 -たとえば、`POST /api/my-account/primary-email` API には `email` スコープ、`POST /api/my-account/primary-phone` API には `phone` スコープが必要です。 +例えば、`POST /api/my-account/primary-email` API には `email` スコープを、`POST /api/my-account/primary-phone` API には `phone` スコープを構成する必要があります。 ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { - // ...その他のオプション - // ユースケースに合った適切なスコープを追加 + // ...other options + // 使用例に適したスコープを追加します。 scopes: [ - UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` 用 - UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` 用 - UserScope.CustomData, // カスタムデータ管理用 - UserScope.Address, // 住所管理用 - UserScope.Identities, // アイデンティティ・MFA 関連 API 用 - UserScope.Profile, // ユーザープロファイル管理用 - UserScope.Sessions, // ユーザーセッション管理用 + UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` API 用 + UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` API 用 + UserScope.CustomData, // カスタムデータを管理するため + UserScope.Address, // 住所を管理するため + UserScope.Identities, // アイデンティティおよび MFA 関連の API 用 + UserScope.Profile, // ユーザープロファイルを管理するため + UserScope.Sessions, // ユーザーセッションとアプリグラントを管理するため ], }; ``` ::: -### アクセストークンの取得 \{#fetch-an-access-token} +### アクセス トークンを取得する \{#fetch-an-access-token} -SDK をアプリケーションにセットアップした後、`client.getAccessToken()` メソッドでアクセストークンを取得できます。このトークンは Account API へのアクセスに使用できる不透明トークン (Opaque token) です。 +アプリケーションに SDK を設定した後、`client.getAccessToken()` メソッドを使用してアクセス トークンを取得できます。このトークンは、不透明トークンであり、Account API にアクセスするために使用できます。 -公式 SDK を使用しない場合は、アクセストークングラントリクエスト `/oidc/token` の `resource` を空に設定してください。 +公式 SDK を使用していない場合は、アクセス トークンの付与リクエストに対して `resource` を空に設定する必要があります。 -### アクセストークンを使った Account API へのアクセス \{#access-account-api-using-access-token} +### アクセス トークンを使用して Account API にアクセスする \{#access-account-api-using-access-token} -Account API へリクエストする際は、HTTP ヘッダーの `Authorization` フィールドに Bearer 形式（`Bearer YOUR_TOKEN`）でアクセストークンを含めてください。 +Account API とやり取りする際には、HTTP ヘッダーの `Authorization` フィールドにアクセス トークンを Bearer 形式 (`Bearer YOUR_TOKEN`) で含める必要があります。 -ユーザーアカウント情報を取得する例： +ユーザーアカウント情報を取得する例を示します： ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## 基本的なアカウント情報の管理 \{#manage-basic-account-information} +## 基本的なアカウント情報を管理する \{#manage-basic-account-information} -### ユーザーアカウント情報の取得 \{#retrieve-user-account-information} +### ユーザーアカウント情報を取得する \{#retrieve-user-account-information} -ユーザーデータを取得するには、[`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) エンドポイントを利用します。 +ユーザーデータを取得するには、[`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) エンドポイントを使用できます。 ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -123,13 +126,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -レスポンスフィールドはアカウントセンターの設定によって異なる場合があります。 +レスポンスフィールドは、アカウントセンターの設定に応じて異なる場合があります。 -### 基本的なアカウント情報の更新 \{#update-basic-account-information} +### 基本的なアカウント情報を更新する \{#update-basic-account-information} -基本的なアカウント情報には、ユーザー名・氏名・アバター・カスタムデータ・その他プロファイル情報が含まれます。 +基本的なアカウント情報には、ユーザー名、名前、アバター、カスタムデータ、およびその他のプロファイル情報が含まれます。 -**ユーザー名・氏名・アバター・カスタムデータ** の更新には、[`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) エンドポイントを利用します。 +**ユーザー名、名前、アバター、およびカスタムデータ** を更新するには、[`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) エンドポイントを使用できます。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -138,7 +141,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -**familyName, givenName, middleName, nickname, profile（プロフィールページ URL）, website, gender, birthdate, zoneinfo, locale, address** などの他のプロファイル情報を更新するには、[`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) エンドポイントを利用します。 +**familyName, givenName, middleName, nickname, profile (プロファイルページ URL), website, gender, birthdate, zoneinfo, locale, および address** を含むその他のプロファイル情報を更新するには、[`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) エンドポイントを使用できます。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -147,17 +150,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 識別子やその他の機微情報の管理 \{#manage-identifiers-and-other-sensitive-information} +## 識別子およびその他の機密情報を管理する \{#manage-identifiers-and-other-sensitive-information} -セキュリティ上の理由から、Account API で識別子や機微情報を扱う操作には追加の認可 (Authorization) 層が必要です。 +セキュリティ上の理由から、Account API は識別子およびその他の機密情報を含む操作に対して追加の認可 (Authorization) レイヤーを必要とします。 -### 認証記録 ID の取得 \{#get-a-verification-record-id} +### 検証レコード ID を取得する \{#get-a-verification-record-id} -まず、10 分間有効な **認証記録 ID** を取得する必要があります。これは機微情報の更新前にユーザーの本人確認を行うために使用します。つまり、ユーザーがパスワード・メール認証コード・SMS 認証コードで本人確認に成功すると、10 分間は識別子・認証情報・ソーシャル連携・MFA などの認証関連データを更新できます。 +まず、10 分間の有効期限 (TTL) を持つ **検証レコード ID** を取得する必要があります。これは、機密情報を更新する前にユーザーのアイデンティティを確認するために使用できます。つまり、ユーザーがパスワード、メール検証コード、または SMS 検証コードを介して自分のアイデンティティを正常に確認すると、識別子、資格情報、ソーシャルアカウントのリンク、および MFA を含む認証関連データを更新するために 10 分間の時間が与えられます。 -認証記録 ID を取得するには、[ユーザーパスワードで認証](#verify-the-users-password) または [メールや電話に認証コードを送信して認証](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) を行います。 +検証レコード ID を取得するには、[ユーザーのパスワードを確認する](#verify-the-users-password) か、[ユーザーのメールまたは電話に検証コードを送信する](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) ことができます。 -#### ユーザーパスワードで認証 \{#verify-the-users-password} +#### ユーザーのパスワードを確認する \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -166,7 +169,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -175,13 +178,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### メールや電話に認証コードを送信して認証 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### ユーザーのメールまたは電話に検証コードを送信して確認する \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -この方法を利用するには、[メールコネクターの設定](/connectors/email-connectors/) または [SMS コネクターの設定](/connectors/sms-connectors/) を行い、`UserPermissionValidation` テンプレートが設定されていることを確認してください。 +この方法を使用するには、[メールコネクターを設定する](/connectors/email-connectors/) か [SMS コネクターを設定する](/connectors/sms-connectors/) 必要があり、`UserPermissionValidation` テンプレートが設定されていることを確認してください。 ::: -メールを例に、新しい認証コードをリクエストし認証記録 ID を取得します： +メールを例にとると、新しい検証コードをリクエストして検証レコード ID を取得します： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -190,7 +193,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -199,7 +202,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -認証コードを受け取ったら、それを使って認証記録の検証ステータスを更新できます。 +検証コードを受け取ったら、それを使用して検証レコードの検証ステータスを更新できます。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -208,17 +211,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -コードの検証後、認証記録 ID を使ってユーザーの識別子を更新できます。 +コードを確認した後、検証レコード ID を使用してユーザーの識別子を更新できます。 -認証について詳しくは [Account API によるセキュリティ認証](/end-user-flows/security-verification) をご参照ください。 +検証について詳しく知るには、 [Account API によるセキュリティ検証](/end-user-flows/security-verification) を参照してください。 -### 認証記録 ID を使ったリクエスト送信 \{#send-request-with-verification-record-id} +### 検証レコード ID を使用してリクエストを送信する \{#send-request-with-verification-record-id} -ユーザーの識別子を更新するリクエストを送信する際は、リクエストヘッダーの `logto-verification-id` フィールドに認証記録 ID を含めてください。 +ユーザーの識別子を更新するリクエストを送信する際には、リクエストヘッダーに `logto-verification-id` フィールドとして検証レコード ID を含める必要があります。 -### ユーザーパスワードの更新 \{#update-users-password} +### ユーザーのパスワードを更新する \{#update-users-password} -ユーザーパスワードの更新には、[`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) エンドポイントを利用します。 +ユーザーのパスワードを更新するには、[`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) エンドポイントを使用できます。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -229,18 +232,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -サインアップ時と同様、Account API で設定するパスワードも コンソール > セキュリティ > パスワードポリシー で設定した [パスワードポリシー](/security/password-policy) に準拠する必要があります。ポリシー違反時は詳細なバリデーション結果とエラーメッセージが返されます。 +サインアップ時に作成されたパスワードと同様に、Account API を通じて設定されたパスワードは、Console > Security > Password policy で設定した [パスワードポリシー](/security/password-policy) に準拠している必要があります。Logto は、ポリシーに違反した場合、詳細な検証結果とエラーメッセージを返します。 ::: -### 新しいメールの更新・連携 \{#update-or-link-new-email} +### 新しいメールを更新またはリンクする \{#update-or-link-new-email} :::note -この方法を利用するには、[メールコネクターの設定](/connectors/email-connectors/) を行い、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を使用するには、[メールコネクターを設定する](/connectors/email-connectors/) 必要があり、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -新しいメールを更新・連携するには、まずそのメールの所有権を証明する必要があります。 +新しいメールを更新またはリンクするには、まずメールの所有権を証明する必要があります。 -[`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) エンドポイントで認証コードをリクエストします。 +[`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) エンドポイントを呼び出して、検証コードをリクエストします。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -249,7 +252,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -レスポンスで `verificationId` が返され、メールで認証コードが届きます。それを使ってメールを検証します。 +レスポンスには `verificationId` が含まれており、メールで検証コードを受け取ります。それを使用してメールを確認します。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -258,34 +261,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -コードの検証後、[`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) を呼び出してユーザーのメールを更新します。リクエストボディの `newIdentifierVerificationRecordId` に `verificationId` を指定します。 +コードを確認した後、[`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) を呼び出してユーザーのメールを更新し、`verificationId` をリクエストボディに `newIdentifierVerificationRecordId` として設定します。 -:::info[2 種類の認証記録 ID] +:::info[2 つの異なる検証レコード ID] -このリクエストには 2 つの異なる認証記録 ID が必要です： +このリクエストには、2 つの異なる検証レコード ID が必要です： -- **`logto-verification-id`（ヘッダー）**：機微な変更前の本人確認用。これは [ユーザーパスワードで認証](#verify-the-users-password) または [既存メール・電話への認証コード送信](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) で取得します。 -- **`newIdentifierVerificationRecordId`（ボディ）**：新しいメールアドレスの所有権証明用。上記 `POST /api/verifications/verification-code` のレスポンスで返される `verificationRecordId` です。 +- **`logto-verification-id` (header)**: 機密変更を行う前にユーザーのアイデンティティを証明します。これを取得するには、[ユーザーのパスワードを確認する](#verify-the-users-password) か、[ユーザーの既存のメールまたは電話に検証コードを送信する](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 必要があります。 +- **`newIdentifierVerificationRecordId` (body)**: 新しいメールアドレスの所有権を証明します。これは、上記の `POST /api/verifications/verification-code` 呼び出しから返された `verificationRecordId` です。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # 本人確認（パスワードまたは既存メール/電話認証による） + # ユーザーのアイデンティティを確認します（パスワードまたは既存のメール/電話の検証から） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" は新しいメール所有権証明（上記認証コードフローより） + # "newIdentifierVerificationRecordId" は新しいメールの所有権を証明します（上記の検証コードフローから） --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -サインアップ時と同様、Account API で連携するメールも コンソール > セキュリティ > ブロックリスト で設定した [ブロックリスト](/security/blocklist) 検証に合格する必要があります。違反時はリクエストが拒否され、詳細なエラーが返されます。 +サインアップ時に収集されたメールと同様に、Account API を通じてリンクされたメールは、Console > Security > Blocklist で設定した [ブロックリスト](/security/blocklist) 検証に合格する必要があります。Logto は、ポリシーに違反した場合、リクエストを拒否し、詳細なエラーを返します。 ::: -### ユーザーのメール削除 \{#remove-the-users-email} +### ユーザーのメールを削除する \{#remove-the-users-email} -ユーザーのメール削除には、[`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) エンドポイントを利用します。 +ユーザーのメールを削除するには、[`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) エンドポイントを使用できます。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -293,17 +296,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 電話番号の管理 \{#manage-phone} +### 電話を管理する \{#manage-phone} :::note -この方法を利用するには、[SMS コネクターの設定](/connectors/sms-connectors/) を行い、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を使用するには、[SMS コネクターを設定する](/connectors/sms-connectors/) 必要があり、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -メール更新と同様に、[`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) エンドポイントで新しい電話番号の更新・連携、[`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) エンドポイントで電話番号の削除が可能です。 +メールの更新と同様に、[`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) エンドポイントを使用して新しい電話を更新またはリンクできます。また、[`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) エンドポイントを使用してユーザーの電話を削除できます。 -### 新しいソーシャル連携の追加 \{#link-a-new-social-connection} +### 新しいソーシャル接続をリンクする \{#link-a-new-social-connection} -新しいソーシャル連携を追加するには、まず [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) で認可 URL をリクエストします。 +新しいソーシャル接続をリンクするには、まず [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) を使用して認可 URL をリクエストする必要があります。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -312,13 +315,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`：[ソーシャルコネクター](/connectors/social-connectors/) の ID -- `redirectUri`：ユーザーがアプリを認可した後のリダイレクト先。ここでコールバックを受け取るページをホストしてください。 -- `state`：認可後に返されるランダムな文字列。CSRF 攻撃防止用。 +- `connectorId`: [ソーシャルコネクター](/connectors/social-connectors/) の ID。 +- `redirectUri`: ユーザーがアプリケーションを認可した後のリダイレクト URI。この URL にウェブページをホストし、コールバックをキャプチャする必要があります。 +- `state`: ユーザーがアプリケーションを認可した後に返される状態。CSRF 攻撃を防ぐためのランダムな文字列です。 -レスポンスで `verificationRecordId` が返されるので、後で使用するために保持します。 +レスポンスには `verificationRecordId` が含まれており、後で使用するために保持します。 -ユーザーがアプリを認可すると、`redirectUri` で `state` パラメータ付きのコールバックを受け取ります。その後、[`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) でソーシャル連携を検証します。 +ユーザーがアプリケーションを認可した後、`redirectUri` に `state` パラメータを含むコールバックを受け取ります。その後、[`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) エンドポイントを使用してソーシャル接続を確認できます。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -327,32 +330,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` は、ユーザーがアプリを認可した後にソーシャルコネクターから返されるデータです。コールバックページで `redirectUri` のクエリパラメータをパースし、JSON 形式で `connectorData` フィールドに渡してください。 +`connectorData` は、ユーザーがアプリケーションを認可した後にソーシャルコネクターから返されるデータであり、コールバックページで `redirectUri` からクエリパラメータを解析して取得し、`connectorData` フィールドの値として JSON 形式でラップする必要があります。 -最後に、[`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) エンドポイントでソーシャル連携を追加します。 +最後に、[`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) エンドポイントを使用してソーシャル接続をリンクできます。 -:::info[2 種類の認証記録 ID] +:::info[2 つの異なる検証レコード ID] -このリクエストには 2 つの異なる認証記録 ID が必要です： +このリクエストには、2 つの異なる検証レコード ID が必要です： -- **`logto-verification-id`（ヘッダー）**：機微な変更前の本人確認用。これは [ユーザーパスワードで認証](#verify-the-users-password) または [既存メール・電話への認証コード送信](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) で取得します。 -- **`newIdentifierVerificationRecordId`（ボディ）**：連携するソーシャルアイデンティティの識別用。上記 `POST /api/verifications/social` のレスポンスで返される `verificationRecordId` です。 +- **`logto-verification-id` (header)**: 機密変更を行う前にユーザーのアイデンティティを証明します。これを取得するには、[ユーザーのパスワードを確認する](#verify-the-users-password) か、[ユーザーの既存のメールまたは電話に検証コードを送信する](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 必要があります。 +- **`newIdentifierVerificationRecordId` (body)**: リンクされるソーシャルアイデンティティを識別します。これは、上記の `POST /api/verifications/social` 呼び出しから返された `verificationRecordId` です。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # 本人確認（パスワードまたは既存メール/電話認証による） + # ユーザーのアイデンティティを確認します（パスワードまたは既存のメール/電話の検証から） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" は連携するソーシャル連携の識別（上記ソーシャル認証フローより） + # "newIdentifierVerificationRecordId" はリンクするソーシャル接続を識別します（上記のソーシャル検証フローから） --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### ソーシャル連携の削除 \{#remove-a-social-connection} +### ソーシャル接続を削除する \{#remove-a-social-connection} -ソーシャル連携の削除には、[`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) エンドポイントを利用します。 +ソーシャル接続を削除するには、[`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) エンドポイントを使用できます。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -360,30 +363,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### 新しい WebAuthn パスキーの連携 \{#link-a-new-webauthn-passkey} +### 新しい WebAuthn パスキーをリンクする \{#link-a-new-webauthn-passkey} :::note -まず [MFA および WebAuthn の有効化](/end-user-flows/mfa) を行ってください。 +まず [MFA と WebAuthn を有効にする](/end-user-flows/mfa) ことを忘れないでください。 ::: :::note -この方法を利用するには、[アカウントセンター設定](#how-to-enable-account-api) で `mfa` フィールドを有効化する必要があります。 +この方法を使用するには、[アカウントセンターの設定](#how-to-enable-account-api) で `mfa` フィールドを有効にする必要があります。 ::: -**ステップ 1：フロントエンドアプリのオリジンを関連オリジンに追加** +**ステップ 1: フロントエンドアプリのオリジンを関連オリジンに追加する** -WebAuthn パスキーは **Relying Party ID (RP ID)** と呼ばれる特定のホスト名に紐づきます。RP ID のオリジンでホストされているアプリケーションのみが、そのパスキーで登録・認証できます。 +WebAuthn パスキーは、**Relying Party ID (RP ID)** と呼ばれる特定のホスト名にバインドされています。RP ID のオリジンにホストされているアプリケーションのみが、これらのパスキーを登録または認証できます。 -フロントエンドアプリが Logto の認証ページとは異なるドメインから Account API を呼び出す場合、**関連オリジン** を設定してクロスオリジンのパスキー操作を許可する必要があります。 +フロントエンドアプリケーションが Logto の認証ページとは異なるドメインから Account API を呼び出すため、クロスオリジンのパスキー操作を許可するために **Related Origins** を設定する必要があります。 **Logto が RP ID を決定する方法：** -- **デフォルト設定**：Logto のデフォルトドメイン `https://[tenant-id].logto.app` の場合、RP ID は `[tenant-id].logto.app` -- **カスタムドメイン**：[カスタムドメイン](/logto-cloud/custom-domain) を `https://auth.example.com` などで設定した場合、RP ID は `auth.example.com` +- **デフォルト設定**: Logto のデフォルトドメイン `https://[tenant-id].logto.app` のみを使用する場合、RP ID は `[tenant-id].logto.app` です。 +- **カスタムドメイン**: `https://auth.example.com` のような [カスタムドメイン](/logto-cloud/custom-domain) を設定している場合、RP ID は `auth.example.com` になります。 -**関連オリジンの設定方法：** +**関連オリジンを設定する：** -[`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) エンドポイントでフロントエンドアプリのオリジンを追加します。たとえばアカウントセンターが `https://account.example.com` で動作している場合： +[`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) エンドポイントを使用して、フロントエンドアプリケーションのオリジンを追加します。例えば、アプリのアカウントセンターが `https://account.example.com` で実行されている場合： ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -394,19 +397,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn では関連オリジンとして最大 5 つのユニークな eTLD+1 ラベルがサポートされます。eTLD+1（有効なトップレベルドメイン＋1 ラベル）は登録可能なドメイン部分です。例： +WebAuthn は、関連オリジンに対して最大 5 つのユニークな eTLD+1 ラベルをサポートしています。eTLD+1（有効なトップレベルドメインプラス 1 ラベル）は、登録可能なドメイン部分です。例えば： -- `https://example.com`、`https://app.example.com`、`https://auth.example.com` は **1** ラベル（`example.com`） -- `https://shopping.com`、`https://shopping.co.uk`、`https://shopping.co.jp` も **1** ラベル（`shopping`） -- `https://example.com` と `https://another.com` は **2** ラベル +- `https://example.com`、`https://app.example.com`、および `https://auth.example.com` は **1** つのラベル（`example.com`）としてカウントされます。 +- `https://shopping.com`、`https://shopping.co.uk`、および `https://shopping.co.jp` も **1** つのラベル（`shopping`）としてカウントされます。 +- `https://example.com` と `https://another.com` は **2** つのラベルとしてカウントされます。 -5 ドメインを超える関連オリジンが必要な場合は、[Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) ドキュメントを参照してください。 +関連オリジンとして 5 つ以上の異なるドメインをサポートする必要がある場合は、 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) ドキュメントを参照してください。 ::: -**ステップ 2：新規登録オプションのリクエスト** +**ステップ 2: 新しい登録オプションをリクエストする** -[`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) エンドポイントで新しいパスキー登録をリクエストします。Logto では 1 アカウントにつき複数のパスキー登録が可能です。 +[`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) エンドポイントを使用して、新しいパスキーの登録をリクエストします。Logto は、各ユーザーアカウントに複数のパスキーを登録することを許可しています。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -414,7 +417,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -レスポンス例： +レスポンスは次のようになります： ```json { @@ -424,9 +427,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat } ``` -**ステップ 3：ローカルブラウザでパスキーを登録** +**ステップ 3: ローカルブラウザでパスキーを登録する** -[`@simplewebauthn/browser`](https://simplewebauthn.dev/) を例に、`startRegistration` 関数でローカルブラウザにパスキーを登録します。 +[`@simplewebauthn/browser`](https://simplewebauthn.dev/) を例にとると、`startRegistration` 関数を使用してローカルブラウザでパスキーを登録できます。 ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -435,14 +438,14 @@ import { startRegistration } from '@simplewebauthn/browser'; const response = await startRegistration({ optionsJSON: registrationOptions, // ステップ 1 でサーバーから返されたデータ }); -// 後で使用するために response を保存 +// 後で使用するためにレスポンスを保存します ``` -**ステップ 4：パスキー登録の検証** +**ステップ 4: パスキー登録を確認する** -[`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) エンドポイントでパスキー登録を検証します。 +[`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) エンドポイントを使用して、パスキー登録を確認します。 -このステップでは、認証器が生成した暗号署名を検証し、パスキーが正当に作成され転送中に改ざんされていないことを確認します。 +このステップでは、パスキーが正当に作成され、送信中に改ざんされていないことを確認するために、認証器によって生成された暗号署名を検証します。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -451,12 +454,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`：ステップ 2 のローカルブラウザからのレスポンス -- `verificationRecordId`：ステップ 1 でサーバーから返された認証記録 ID +- `payload`: ステップ 2 でローカルブラウザからのレスポンス。 +- `verificationRecordId`: ステップ 1 でサーバーから返された検証レコード ID。 -**ステップ 5：パスキーの連携** +**ステップ 5: パスキーをリンクする** -最後に、[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントでパスキーをユーザーアカウントに連携します。 +最後に、[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントを使用して、パスキーをユーザーのアカウントにリンクできます。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -466,20 +469,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`：既存要素の認証で付与された有効な認証記録 ID。詳細は [認証記録 ID の取得](#get-a-verification-record-id) を参照。 -- `type`：MFA 要素のタイプ。現在は `WebAuthn` のみサポート。 -- `newIdentifierVerificationRecordId`：ステップ 1 でサーバーから返された認証記録 ID。 +- `verification_record_id`: ユーザーの既存の要素を確認することによって付与された有効な検証レコード ID。詳細については、 [Get a verification record ID](#get-a-verification-record-id) セクションを参照してください。 +- `type`: MFA 要素のタイプ、現在は `WebAuthn` のみがサポートされています。 +- `newIdentifierVerificationRecordId`: ステップ 1 でサーバーから返された検証レコード ID。 -### 既存 WebAuthn パスキーの管理 \{#manage-existing-webauthn-passkeys} +### 既存の WebAuthn パスキーを管理する \{#manage-existing-webauthn-passkeys} -既存の WebAuthn パスキー管理には、[`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) エンドポイントで現在のパスキーや他の MFA 要素を取得できます。 +既存の WebAuthn パスキーを管理するには、[`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) エンドポイントを使用して、現在のパスキーおよびその他の MFA 検証要素を取得できます。 ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json [ @@ -494,12 +497,12 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`：認証要素の ID -- `type`：認証要素のタイプ。WebAuthn パスキーの場合は `WebAuthn` -- `name`：パスキー名（任意） -- `agent`：パスキーのユーザーエージェント +- `id`: 検証の ID。 +- `type`: 検証のタイプ、WebAuthn パスキーの場合は `WebAuthn`。 +- `name`: パスキーの名前、オプションフィールド。 +- `agent`: パスキーのユーザーエージェント。 -パスキー名の更新は [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) エンドポイントで行います： +[`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) エンドポイントを使用してパスキー名を更新します： ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -509,7 +512,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -パスキーの削除は [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) エンドポイントで行います： +[`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) エンドポイントを使用してパスキーを削除します： ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -517,19 +520,19 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'logto-verification-id: ' ``` -### 新しい TOTP の連携 \{#link-a-new-totp} +### 新しい TOTP をリンクする \{#link-a-new-totp} :::note -まず [MFA および TOTP の有効化](/end-user-flows/mfa) を行ってください。 +まず [MFA と TOTP を有効にする](/end-user-flows/mfa) ことを忘れないでください。 ::: :::note -この方法を利用するには、[アカウントセンター設定](#how-to-enable-account-api) で `mfa` フィールドを有効化する必要があります。 +この方法を使用するには、[アカウントセンターの設定](#how-to-enable-account-api) で `mfa` フィールドを有効にする必要があります。 ::: -**ステップ 1：TOTP シークレットの生成** +**ステップ 1: TOTP シークレットを生成する** -[`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) エンドポイントで TOTP シークレットを生成します。 +[`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) エンドポイントを使用して、TOTP シークレットを生成します。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -537,7 +540,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -545,11 +548,11 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp } ``` -**ステップ 2：TOTP シークレットをユーザーに表示** +**ステップ 2: ユーザーに TOTP シークレットを表示する** -シークレットを使って QR コードを生成するか、直接ユーザーに表示します。ユーザーはこれを Google Authenticator、Microsoft Authenticator、Authy などの認証アプリに追加します。 +シークレットを使用して QR コードを生成するか、ユーザーに直接表示します。ユーザーはこれを認証アプリ（Google Authenticator、Microsoft Authenticator、Authy など）に追加する必要があります。 -QR コードの URI 形式： +QR コードの URI 形式は次のようにする必要があります： ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -561,9 +564,9 @@ otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp ``` -**ステップ 3：TOTP 要素のバインド** +**ステップ 3: TOTP 要素をバインドする** -ユーザーが認証アプリにシークレットを追加したら、それを検証してアカウントにバインドします。[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントを利用します。 +ユーザーがシークレットを認証アプリに追加した後、それを確認し、アカウントにバインドする必要があります。[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントを使用して TOTP 要素をバインドします。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -573,27 +576,27 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`：既存要素の認証で付与された有効な認証記録 ID。詳細は [認証記録 ID の取得](#get-a-verification-record-id) を参照。 -- `type`：`Totp` を指定 -- `secret`：ステップ 1 で生成した TOTP シークレット +- `verification_record_id`: ユーザーの既存の要素を確認することによって付与された有効な検証レコード ID。詳細については、 [Get a verification record ID](#get-a-verification-record-id) セクションを参照してください。 +- `type`: `Totp` である必要があります。 +- `secret`: ステップ 1 で生成された TOTP シークレット。 :::note -ユーザーは TOTP 要素を 1 つしか持てません。既に TOTP 要素がある場合、追加しようとすると 422 エラーになります。 +ユーザーは一度に 1 つの TOTP 要素しか持つことができません。ユーザーがすでに TOTP 要素を持っている場合、別の要素を追加しようとすると 422 エラーが発生します。 ::: -### バックアップコードの管理 \{#manage-backup-codes} +### バックアップコードを管理する \{#manage-backup-codes} :::note -まず [MFA およびバックアップコードの有効化](/end-user-flows/mfa) を行ってください。 +まず [MFA とバックアップコードを有効にする](/end-user-flows/mfa) ことを忘れないでください。 ::: :::note -この方法を利用するには、[アカウントセンター設定](#how-to-enable-account-api) で `mfa` フィールドを有効化する必要があります。 +この方法を使用するには、[アカウントセンターの設定](#how-to-enable-account-api) で `mfa` フィールドを有効にする必要があります。 ::: -**ステップ 1：新しいバックアップコードの生成** +**ステップ 1: 新しいバックアップコードを生成する** -[`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) エンドポイントで新しい 10 個のバックアップコードを生成します。 +[`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) エンドポイントを使用して、新しい 10 個のバックアップコードセットを生成します。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -601,7 +604,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -609,20 +612,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back } ``` -**ステップ 2：バックアップコードをユーザーに表示** +**ステップ 2: ユーザーにバックアップコードを表示する** -バックアップコードをユーザーアカウントにバインドする前に、必ずユーザーに表示し、以下を案内してください： +バックアップコードをユーザーのアカウントにバインドする前に、ユーザーに表示し、次のことを指示します： -- すぐにダウンロードまたは書き留めること -- 安全な場所に保管すること -- 各コードは 1 回しか使えないこと -- これらのコードは主要な MFA 手段を失った場合の最後の手段であること +- これらのコードをすぐにダウンロードまたは書き留める +- 安全な場所に保管する +- 各コードは一度しか使用できないことを理解する +- これらのコードがプライマリ MFA 方法にアクセスできなくなった場合の最後の手段であることを知る -コピーしやすい形式で表示し、ダウンロード（テキストファイルや PDF など）も提供するとよいでしょう。 +コードを明確でコピーしやすい形式で表示し、ダウンロードオプション（例：テキストファイルまたは PDF として）を提供することを検討してください。 -**ステップ 3：バックアップコードをユーザーアカウントにバインド** +**ステップ 3: バックアップコードをユーザーアカウントにバインドする** -[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントでバックアップコードをバインドします。 +[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) エンドポイントを使用して、バックアップコードをユーザーのアカウントにバインドします。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -632,28 +635,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`：既存要素の認証で付与された有効な認証記録 ID。詳細は [認証記録 ID の取得](#get-a-verification-record-id) を参照。 -- `type`：`BackupCode` を指定 -- `codes`：前ステップで生成したバックアップコード配列 +- `verification_record_id`: ユーザーの既存の要素を確認することによって付与された有効な検証レコード ID。詳細については、 [Get a verification record ID](#get-a-verification-record-id) セクションを参照してください。 +- `type`: `BackupCode` である必要があります。 +- `codes`: 前のステップで生成されたバックアップコードの配列。 :::note -- ユーザーは 1 セットのバックアップコードしか持てません。すべて使い切った場合は新たに生成・バインドが必要です。 -- バックアップコードのみを MFA 要素とすることはできません。必ず他の MFA 要素（WebAuthn や TOTP など）が有効である必要があります。 -- 各バックアップコードは 1 回しか使えません。 +- ユーザーは一度に 1 セットのバックアップコードしか持つことができません。すべてのコードが使用された場合、ユーザーは新しいコードを生成してバインドする必要があります。 +- バックアップコードは唯一の MFA 要素にはなり得ません。ユーザーは少なくとも 1 つの他の MFA 要素（WebAuthn や TOTP など）を有効にしている必要があります。 +- 各バックアップコードは一度しか使用できません。 ::: -**既存バックアップコードの閲覧** +**既存のバックアップコードを表示する** -既存のバックアップコードと使用状況は、[`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) エンドポイントで確認できます： +既存のバックアップコードとその使用状況を表示するには、[`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) エンドポイントを使用します： ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -レスポンス例： +レスポンスボディは次のようになります： ```json { @@ -670,19 +673,19 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes } ``` -- `code`：バックアップコード -- `usedAt`：使用時刻。未使用の場合は `null` +- `code`: バックアップコード。 +- `usedAt`: コードが使用されたタイムスタンプ、まだ使用されていない場合は `null`。 -### ユーザーセッションの管理 \{#manage-user-sessions} +### ユーザーセッションを管理する \{#manage-user-sessions} -**アクティブセッションの一覧取得** +**アクティブなセッションを一覧表示する** -ユーザーのアクティブセッション一覧は、[`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) エンドポイントで取得できます。 +ユーザーのアクティブなセッションを一覧表示するには、[`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) エンドポイントを使用できます。 :::note -- このエンドポイントには `UserScope.Sessions` スコープが必要です。 -- アカウントセンター設定の `Sessions` フィールドが `ReadOnly` または `Edit` である必要があります。 +- このエンドポイントにアクセスするには `UserScope.Sessions` スコープが必要です。 +- アカウントセンターの設定で `Sessions` フィールドを `ReadOnly` または `Edit` に設定する必要があります。 ::: @@ -693,14 +696,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**セッション ID 指定でのセッション取り消し** +**セッション ID でセッションを取り消す** -特定のセッションを取り消すには、[`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) エンドポイントを利用します。 +特定のセッションを取り消すには、[`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) エンドポイントを使用します。 :::note -- このエンドポイントには `UserScope.Sessions` スコープが必要です。 -- アカウントセンター設定の `Sessions` フィールドが `Edit` である必要があります。 +- このエンドポイントにアクセスするには `UserScope.Sessions` スコープが必要です。 +- アカウントセンターの設定で `Sessions` フィールドを `Edit` に設定する必要があります。 ::: ```bash @@ -712,7 +715,58 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} オプションのクエリパラメータ： -- `revokeGrantsTarget`：セッションとともに取り消すグラントの対象を指定可能。値の例： - - `all`：セッションに関連付けられたすべてのグラントを取り消し - - `firstParty`：ファーストパーティアプリのグラントのみ取り消し（多くのケースで推奨。自社アプリのアクセスのみ取り消し、サードパーティアプリのグラントは維持し、より良いユーザー体験を提供） - - 未指定：デフォルト動作は `offline_access` スコープを持たないグラントを取り消し（通常はリフレッシュトークン以外のグラントを取り消し） +- `revokeGrantsTarget`: セッションと共に取り消すグラントのターゲットをオプションで指定します。可能な値： + - `all`: セッションに関連付けられたすべてのグラントを取り消します。 + - `firstParty`: セッションに関連付けられたファーストパーティアプリのグラントのみを取り消します。（ほとんどの使用例に推奨されます。これにより、サードパーティアプリのグラントを保持しながら、自分のアプリのアクセスを取り消し、より良いユーザーエクスペリエンスを提供します。） + - 指定なし: デフォルトの動作は、通常、セッションのリフレッシュトークン以外のグラントを取り消すことを意味します。 + +### ユーザー承認アプリ（グラント）を管理する \{#manage-user-authorized-apps-grants} + +ユーザーがアカウント設定ページから承認されたアプリを確認および取り消す必要がある場合に、ユーザー承認アプリ（グラント）API を使用します。 + +:::note + +- アプリグラント API は、セッション API と同じ権限モデルを共有します。 +- `UserScope.Sessions` スコープが必要です。 +- アカウントセンターの設定で `Sessions` フィールドを有効にする必要があります： + - グラントを一覧表示するには `ReadOnly` または `Edit`。 + - グラントを取り消すには `Edit`。 + +::: + +**アクティブなアプリグラントを一覧表示する** + +現在のユーザーのアクティブなアプリグラントを一覧表示するには、[`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) エンドポイントを使用します。 + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +オプションのクエリパラメータ： + +- `appType=firstParty`: ファーストパーティアプリのグラントのみを返します。 +- `appType=thirdParty`: サードパーティアプリのグラントのみを返します。 +- `appType` を省略: すべてのアクティブなグラントを返します。 + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**グラント ID でアプリグラントを取り消す** + +特定のアプリグラントを取り消すには、[`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) エンドポイントを使用します。 + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +グラントが取り消されると、そのグラントに対して以前に発行された不透明トークンとリフレッシュトークンは無効になります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index e2b93b47752..75df3170c32 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -4,23 +4,23 @@ sidebar_position: 2 # Management API によるアカウント設定 -## インテグレーション \{#integrations} +## 統合 \{#integrations} -Logto は、ユーザーアカウントを管理するためのさまざまな Management API を提供しています。これらの API を利用して、エンドユーザー向けのセルフサービス型アカウント設定ページを構築できます。 +Logto は、ユーザーアカウントを管理するためのさまざまな Management API を提供しています。これらの API を使用して、エンドユーザー向けのセルフサービスアカウント設定ページを構築できます。 ### アーキテクチャ \{#architecture} ```mermaid graph TB A[ユーザー] --> B[クライアントアプリケーション] - B -->|セルフホスト型アカウント設定 API コール|C[サーバーサイドアプリケーション] - C -->|Management API コール| D[Logto] + B -->|セルフホスト型アカウント設定 API 呼び出し|C[サーバーサイドアプリケーション] + C -->|Management API 呼び出し| D[Logto] ``` -1. **ユーザー**：アカウント設定へアクセス・管理するために認証 (Authentication) 済みのエンドユーザー。 -2. **クライアントアプリケーション**：ユーザーにアカウント設定ページを提供するクライアントアプリケーション。 -3. **サーバーサイドアプリケーション**：クライアントにアカウント設定 API を提供するサーバーサイドアプリケーション。Logto Management API と連携します。 -4. **Logto**：認証 (Authentication)・認可 (Authorization) サービスとしての Logto。ユーザーアカウント管理用の Management API を提供します。 +1. **ユーザー**: アカウント設定にアクセスし管理する必要がある認証済みエンドユーザー。 +2. **クライアントアプリケーション**: ユーザーにアカウント設定ページを提供するクライアントアプリケーション。 +3. **サーバーサイドアプリケーション**: クライアントにアカウント設定 API を提供するサーバーサイドアプリケーション。Logto Management API と連携します。 +4. **Logto**: 認証 (Authentication) と認可 (Authorization) サービスとしての Logto。ユーザーアカウントを管理するための Management API を提供します。 ### シーケンス図 \{#sequence-diagram} @@ -32,90 +32,90 @@ Logto は、ユーザーアカウントを管理するためのさまざまな M participant Server as サーバーサイドアプリケーション participant Logto as Logto - User ->> Client: クライアントアプリへアクセス + User ->> Client: クライアントアプリにアクセス Client ->> Logto: POST /oidc/auth User -->> Logto: サインイン - Logto -->> Client: クライアントアプリへリダイレクト + Logto -->> Client: クライアントアプリにリダイレクト Client ->> Logto: POST /oidc/token - Logto ->> Client: アクセストークン A - Client ->> Server: GET /account-settings (アクセストークン A 付き) - Server ->> Logto: POST /oidc/token (クライアントクレデンシャル付き) - Logto ->> Server: アクセストークン B - Server ->> Logto: GET /api/users/{userId} (アクセストークン B 付き) + Logto ->> Client: アクセス トークン A + Client ->> Server: GET /account-settings (アクセス トークン A を使用) + Server ->> Logto: POST /oidc/token (クライアント資格情報を使用) + Logto ->> Server: アクセス トークン B + Server ->> Logto: GET /api/users/{userId} (アクセス トークン B を使用) Logto ->> Server: ユーザー詳細 Server ->> Client: ユーザー詳細 ``` -1. ユーザーがクライアントアプリケーションへアクセスします。 -2. クライアントアプリケーションが Logto へ認証リクエストを送り、ユーザーを Logto のサインインページへリダイレクトします。 -3. ユーザーが Logto へサインインします。 -4. 認証 (Authentication) 済みユーザーが認可コード付きでクライアントアプリケーションへリダイレクトされます。 -5. クライアントアプリケーションがセルフホスト型アカウント設定 API へのアクセス用アクセストークンを Logto からリクエストします。 -6. Logto がクライアントアプリケーションへアクセストークンを発行します。 -7. クライアントアプリケーションがユーザーアクセストークン付きでサーバーサイドアプリケーションへアカウント設定リクエストを送信します。 -8. サーバーサイドアプリケーションがユーザーアクセストークンからリクエスターのアイデンティティと権限を検証し、Logto から Management API アクセストークンをリクエストします。 -9. Logto がサーバーサイドアプリケーションへ Management API アクセストークンを発行します。 -10. サーバーサイドアプリケーションが Management API アクセストークンを使って Logto からユーザーデータを取得します。 -11. Logto がサーバーのアイデンティティと Management API 権限を検証し、ユーザーデータを返します。 -12. サーバーサイドアプリケーションがリクエスターの権限に基づきユーザーデータを処理し、クライアントアプリケーションへユーザーアカウント詳細を返します。 +1. ユーザーがクライアントアプリケーションにアクセスします。 +2. クライアントアプリケーションが Logto に認証リクエストを送り、ユーザーを Logto のサインインページにリダイレクトします。 +3. ユーザーが Logto にサインインします。 +4. 認証されたユーザーがクライアントアプリケーションに認可コードと共にリダイレクトされます。 +5. クライアントアプリケーションが Logto からセルフホスト型アカウント設定 API アクセスのためのアクセス トークンを要求します。 +6. Logto がクライアントアプリケーションにアクセス トークンを付与します。 +7. クライアントアプリケーションがユーザーアクセス トークンを使用してサーバーサイドアプリケーションにアカウント設定リクエストを送信します。 +8. サーバーサイドアプリケーションがユーザーアクセス トークンからリクエスト者のアイデンティティと権限を確認し、Logto から Management API アクセス トークンを要求します。 +9. Logto がサーバーサイドアプリケーションに Management API アクセス トークンを付与します。 +10. サーバーサイドアプリケーションが Management API アクセス トークンを使用して Logto からユーザーデータを要求します。 +11. Logto がサーバーのアイデンティティと Management API 権限を確認し、ユーザーデータを返します。 +12. サーバーサイドアプリケーションがリクエスト者の権限に基づいてユーザーデータを処理し、クライアントアプリケーションにユーザーアカウントの詳細を返します。 -### Management API をサーバーサイドアプリケーションへ統合する \{#integrate-management-api-to-server-side-application} +### Management API をサーバーサイドアプリケーションに統合する \{#integrate-management-api-to-server-side-application} -サーバーサイドアプリケーションへの Management API 統合方法については、[Management API](/integrate-logto/interact-with-management-api/) セクションを参照してください。 +サーバーサイドアプリケーションと Management API を統合する方法については、[Management API](/integrate-logto/interact-with-management-api/) セクションを確認してください。 ## ユーザー管理 API \{#user-management-apis} ### ユーザーデータスキーマ \{#user-data-schema} -Logto のユーザースキーマについては、[ユーザーデータとカスタムデータ](/user-management/user-data/) セクションを参照してください。 +Logto のユーザースキーマについて詳しく知るには、[ユーザーデータとカスタムデータ](/user-management/user-data/) セクションを確認してください。 -### ユーザープロファイルおよび識別子管理 API \{#user-profile-and-identifiers-management-apis} +### ユーザープロファイルと識別子管理 API \{#user-profile-and-identifiers-management-apis} -ユーザーのプロファイルと識別子はユーザー管理に不可欠です。以下の API を利用してユーザープロファイルや識別子を管理できます。 +ユーザープロファイルと識別子は、ユーザー管理において重要です。以下の API を使用して、ユーザープロファイルと識別子を管理できます。 -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。 | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | ユーザー詳細を更新します。 | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | ユーザー ID でユーザープロファイル項目を更新します。 | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | ユーザー ID でカスタムデータを取得します。 | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | ユーザー ID でカスタムデータを更新します。 | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | ユーザー ID でユーザーの停止状態を更新します。 | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。 | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | ユーザー詳細を更新します。 | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | ユーザー ID でユーザープロファイルフィールドを更新します。 | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | ユーザー ID でユーザーのカスタムデータを取得します。 | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | ユーザー ID でユーザーのカスタムデータを更新します。 | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | ユーザー ID でユーザーの停止状態を更新します。 | -### メールアドレスと電話番号の認証 (Verification) \{#email-and-phone-number-verification} +### メールと電話番号の確認 \{#email-and-phone-number-verification} -Logto システムでは、メールアドレスと電話番号の両方がユーザー識別子として利用できるため、その認証 (Verification) は不可欠です。これをサポートするため、指定したメールアドレスや電話番号の認証 (Verification) を支援する認証コード API を提供しています。 +Logto システムでは、メールアドレスと電話番号の両方がユーザー識別子として機能するため、その確認が重要です。これをサポートするために、提供されたメールまたは電話番号を確認するための一連の確認コード API を提供しています。 :::note -新しいメールアドレスや電話番号でユーザープロファイルを更新する前に、必ずメールアドレスまたは電話番号の認証 (Verification) を行ってください。 +新しいメールまたは電話番号でユーザープロファイルを更新する前に、メールまたは電話番号を確認してください。 ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | メールアドレスまたは電話番号の認証コードを送信します。 | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 認証コードでメールアドレスまたは電話番号を認証 (Verification) します。 | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | メールまたは電話番号の確認コードを送信します。 | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 確認コードでメールまたは電話番号を確認します。 | ### ユーザーパスワード管理 \{#user-password-management} | method | path | description | | ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | ユーザー ID で現在のパスワードを認証 (Verification) します。 | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | ユーザー ID でパスワードを更新します。 | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | ユーザー ID でパスワードの有無を確認します。 | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | ユーザー ID で現在のユーザーパスワードを確認します。 | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | ユーザー ID でユーザーパスワードを更新します。 | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | ユーザー ID でユーザーがパスワードを持っているか確認します。 | :::note -ユーザーパスワードを更新する前に、必ず現在のパスワードを認証 (Verification) してください。 +ユーザーのパスワードを更新する前に、現在のパスワードを確認してください。 ::: ### ユーザーソーシャルアイデンティティ管理 \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。ソーシャルアイデンティティは `identities` フィールドに含まれます。 | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 認証 (Authentication) 済みソーシャルアイデンティティをユーザー ID でリンクします。 | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | ユーザー ID でソーシャルアイデンティティのリンクを解除します。 | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | ユーザー ID でリンクされたソーシャルアイデンティティを直接更新します。 | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | ソーシャルアイデンティティプロバイダーの認可 URI を取得します。この URI を使って新しいソーシャルアイデンティティ接続を開始します。 | +| method | path | description | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。ソーシャルアイデンティティは `identities` フィールドにあります。 | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 認証済みのソーシャルアイデンティティをユーザー ID でリンクします。 | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | ソーシャルアイデンティティをユーザー ID からリンク解除します。 | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | ユーザー ID にリンクされたソーシャルアイデンティティを直接更新します。 | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | ソーシャルアイデンティティプロバイダーの認可 URI を取得します。この URI を使用して新しいソーシャルアイデンティティ接続を開始します。 | ```mermaid sequenceDiagram @@ -126,49 +126,49 @@ sequenceDiagram participant Logto as Logto participant IdP as ソーシャルアイデンティティプロバイダー - User ->> Client: クライアントアプリでソーシャルアイデンティティ連携リクエスト - Client ->> App: ソーシャルアイデンティティ連携リクエスト送信 + User ->> Client: クライアントアプリにアクセスしてソーシャルアイデンティティをバインドするリクエスト + Client ->> App: ソーシャルアイデンティティをバインドするリクエストを送信 App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: 認可 URI - App ->> Client: 認可 URI を返却 - Client ->> IdP: IdP 認可ページへリダイレクト - User -->> IdP: IdP へサインイン - IdP ->> Client: 認可コード付きでクライアントアプリへリダイレクト - Client ->> Server: ソーシャルアイデンティティ連携リクエスト、IdP 認可レスポンスを転送 + App ->> Client: 認可 URI を返す + Client ->> IdP: IdP 認可ページにリダイレクト + User -->> IdP: IdP にサインイン + IdP ->> Client: 認可コードと共にクライアントアプリにリダイレクト + Client ->> Server: ソーシャルアイデンティティリンクリクエスト、IdP 認可レスポンスを転送 Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: 認可コードで IdP からユーザー情報取得 - IdP ->> Logto: ユーザー情報返却 + Logto ->> IdP: 認可コードを使用して IdP からユーザー情報を取得 + IdP ->> Logto: ユーザー情報を返す ``` -1. ユーザーがクライアントアプリケーションへアクセスし、ソーシャルアイデンティティ連携をリクエストします。 -2. クライアントアプリケーションがサーバーへソーシャルアイデンティティ連携リクエストを送信します。 -3. サーバーが Logto へソーシャルアイデンティティプロバイダーの認可 URI を取得するリクエストを送信します。このリクエストには独自の `state` パラメーターと `redirect_uri` を指定する必要があります。`redirect_uri` はソーシャルアイデンティティプロバイダーに事前登録してください。 -4. Logto がサーバーへ認可 URI を返却します。 -5. サーバーがクライアントアプリケーションへ認可 URI を返却します。 -6. クライアントアプリケーションがユーザーを IdP 認可 URI へリダイレクトします。 -7. ユーザーが IdP へサインインします。 -8. IdP が認可コード付きでユーザーをクライアントアプリケーションへ `redirect_uri` でリダイレクトします。 -9. クライアントアプリケーションが `state` を検証し、IdP 認可レスポンスをサーバーへ転送します。 -10. サーバーが Logto へソーシャルアイデンティティをユーザーへリンクするリクエストを送信します。 -11. Logto が認可コードを使って IdP からユーザー情報を取得します。 -12. IdP がユーザー情報を Logto へ返却し、Logto がソーシャルアイデンティティをユーザーへリンクします。 +1. ユーザーがクライアントアプリケーションにアクセスし、ソーシャルアイデンティティをバインドするリクエストを行います。 +2. クライアントアプリケーションがサーバーにソーシャルアイデンティティをバインドするリクエストを送信します。 +3. サーバーが Logto にソーシャルアイデンティティプロバイダーの認可 URI を取得するリクエストを送信します。リクエストには独自の `state` パラメータと `redirect_uri` を提供する必要があります。ソーシャルアイデンティティプロバイダーに `redirect_uri` を登録してください。 +4. Logto がサーバーに認可 URI を返します。 +5. サーバーがクライアントアプリケーションに認可 URI を返します。 +6. クライアントアプリケーションがユーザーを IdP 認可 URI にリダイレクトします。 +7. ユーザーが IdP にサインインします。 +8. IdP が `redirect_uri` を使用してユーザーをクライアントアプリケーションに認可コードと共にリダイレクトします。 +9. クライアントアプリケーションが `state` を検証し、IdP 認可レスポンスをサーバーに転送します。 +10. サーバーが Logto にソーシャルアイデンティティをユーザーにリンクするリクエストを送信します。 +11. Logto が認可コードを使用して IdP からユーザー情報を取得します。 +12. IdP がユーザー情報を Logto に返し、Logto がソーシャルアイデンティティをユーザーにリンクします。 :::note -ユーザーへ新しいソーシャルアイデンティティをリンクする際には、いくつかの制限事項があります： +ユーザーに新しいソーシャルアイデンティティをリンクする際に考慮すべき制限があります： -- Management API にはセッションコンテキストがありません。セッションを維持してソーシャル認証状態を安全に管理する必要があるソーシャルコネクターは Management API でリンクできません。サポートされていないコネクターには apple、標準 OIDC、標準 OAuth 2.0 コネクターが含まれます。 -- 同じ理由で、Logto は認可レスポンスの `state` パラメーターを検証できません。クライアントアプリで `state` パラメーターを保存し、認可レスポンス受信時に必ず検証してください。 -- `redirect_uri` を事前にソーシャルアイデンティティプロバイダーへ登録する必要があります。登録しない場合、ソーシャル IdP はユーザーをクライアントアプリへリダイレクトしません。ソーシャル IdP には複数のコールバック `redirect_uri`（ユーザーサインイン用とプロフィール連携用）を登録できる必要があります。 +- Management API にはセッションコンテキストがないため、ソーシャル認証状態を安全に維持するためにアクティブなセッションを必要とするソーシャルコネクターは Management API を介してリンクできません。サポートされていないコネクターには、apple、標準 OIDC、および標準 OAuth 2.0 コネクターが含まれます。 +- 同じ理由で、Logto は認可レスポンスの `state` パラメータを検証できません。クライアントアプリに `state` パラメータを保存し、認可レスポンスを受信したときにそれを検証してください。 +- ソーシャルアイデンティティプロバイダーに `redirect_uri` を事前に登録する必要があります。そうしないと、ソーシャル IdP はユーザーをクライアントアプリにリダイレクトしません。ソーシャル IdP は、ユーザーサインイン用と独自のプロファイルバインディングページ用の複数のコールバック `redirect_uri` を受け入れる必要があります。 ::: ### ユーザーエンタープライズアイデンティティ管理 \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。エンタープライズアイデンティティは `ssoIdentities` フィールドに含まれます。ユーザー詳細 API に `includeSsoIdentities=true` クエリパラメーターを追加してください。 | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | ユーザー ID でユーザー詳細を取得します。エンタープライズアイデンティティは `ssoIdentities` フィールドにあります。ユーザー詳細 API に `includeSsoIdentities=true` クエリパラメータを追加してそれらを含めます。 | -現在、Management API ではユーザーへのエンタープライズアイデンティティのリンク・解除はサポートしていません。ユーザーにリンクされたエンタープライズアイデンティティの表示のみ可能です。 +現在、Management API はユーザーにエンタープライズアイデンティティをリンクまたはリンク解除することをサポートしていません。ユーザーにリンクされたエンタープライズアイデンティティを表示することのみが可能です。 ### パーソナルアクセストークン \{#personal-access-token} @@ -179,15 +179,15 @@ sequenceDiagram | DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 名前でユーザーのトークンを削除します。 | | PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 名前でユーザーのトークンを更新します。 | -パーソナルアクセストークンは、ユーザーが認証情報やインタラクティブなサインインを使わずに [アクセス トークン (Access token)](https://auth.wiki/access-token) を安全に発行できる方法です。[パーソナルアクセストークンの利用方法](/user-management/personal-access-token) もご覧ください。 +パーソナルアクセストークンは、ユーザーが資格情報やインタラクティブなサインインを使用せずに [アクセス トークン](https://auth.wiki/access-token) を付与するための安全な方法を提供します。パーソナルアクセストークンの使用について詳しくは、[パーソナルアクセストークンの使用](/user-management/personal-access-token) を参照してください。 ### ユーザー MFA 設定管理 \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | ユーザー ID でユーザーの MFA 設定を取得します。 | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | ユーザー ID でユーザーの MFA 認証 (Verification) を設定します。 | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | ID でユーザーの MFA 認証 (Verification) を削除します。 | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | ユーザー ID でユーザーの MFA 設定を取得します。 | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | ユーザー ID でユーザーの MFA 確認を設定します。 | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | ID でユーザーの MFA 確認を削除します。 | ### ユーザーアカウント削除 \{#user-account-deletion} @@ -202,3 +202,18 @@ sequenceDiagram | GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | ユーザー ID でユーザーセッションを取得します。 | | GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | セッション ID でユーザーセッションを取得します。 | | DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | セッション ID でユーザーセッションを削除します。 | + +### ユーザー認可アプリ (グラント) の管理 \{#manage-user-authorized-apps-grants} + +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | ユーザーのアクティブなアプリグラントを一覧表示します。 | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | ID で特定のアプリグラントを取り消します。 | + +グラント一覧表示のためのオプションのクエリパラメータ： + +- `appType=firstParty`: ファーストパーティアプリグラントのみを返します。 +- `appType=thirdParty`: サードパーティアプリグラントのみを返します。 +- `appType` を省略: すべてのアクティブなグラントを返します。 + +グラントが取り消されると、そのグラントに対して以前に発行された不透明トークンとリフレッシュ トークンは無効になります。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index c4bc6447106..72fe493e5de 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,233 +1,99 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # サインアウト -Logto（OIDC アイデンティティプロバイダー (IdP) として）のサインアウトは、次の両方を含みます： +Logto でのサインアウトは、2 つのレイヤーに分かれています： -- **集中管理された Logto セッション**（Logto ドメイン配下のブラウザ Cookie） -- **分散されたクライアント側の認証状態**（各アプリのトークンやローカルアプリセッション） +- **Logto セッションのサインアウト**：Logto ドメイン下での集中サインインセッションを終了します。 +- **アプリのサインアウト**：クライアントアプリケーション内のローカルセッション状態とトークンをクリアします。 -サインアウトの挙動を理解するには、この 2 層を分けて考え、**グラント (grant)** がどのようにそれらをつなぐかを見ると分かりやすいです。 +Logto でのセッションの動作をよりよく理解するには、[セッション](/sessions) を参照してください。 -## コア概念 \{#core-concepts} +## サインアウトメカニズム \{#sign-out-mechanisms} -### Logto セッションとは？ \{#what-is-a-logto-session} +### 1) クライアントサイドのみのサインアウト \{#1-client-side-only-sign-out} -Logto セッションは、Logto によって管理される集中管理されたサインイン状態です。認証 (Authentication) に成功した後に作成され、Logto ドメイン配下の Cookie で表現されます。 +クライアントアプリは、自身のローカルセッションとトークン（ID トークン / アクセス トークン / リフレッシュ トークン）をクリアします。これにより、ユーザーはそのアプリのローカル状態からのみサインアウトされます。 -セッション Cookie が有効な場合、同じ Logto テナントを信頼する複数のアプリ間でサイレント認証（シングルサインオン (SSO)）が可能です。 +- Logto セッションはまだアクティブかもしれません。 +- 同じ Logto セッション下の他のアプリはまだ SSO 可能です。 -有効なセッションが存在しない場合、Logto はサインインページを表示します。 +### 2) Logto でのセッション終了（現在の Logto 実装でのグローバルサインアウト） \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -### グラント (grant) とは？ \{#what-are-grants} +集中 Logto セッションをクリアするには、アプリがユーザーをセッション終了エンドポイントにリダイレクトします。例えば： -**グラント (grant)** とは、特定のユーザーとクライアントアプリケーションの組み合わせに対する認可 (Authorization) 状態を表します。 - -- 1 つの Logto セッションは、複数のクライアントアプリのグラント (grant) を持つことができます。 -- グラント (grant) は発行されたトークンと関連付けられます。 -- このドキュメントセットでは、**グラント (grant)** をアプリ横断の認可 (Authorization) 単位として扱います。 - -### セッション、グラント (grant)、クライアント認証状態の関係 \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto ドメイン] - S[Logto セッション] - G1[App A のグラント] - G2[App B のグラント] - end - - subgraph AppA [クライアントドメイン A] - A[ローカルセッション / トークン] - end - - subgraph AppB [クライアントドメイン B] - B[ローカルセッション / トークン] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Logto セッション** は集中管理された SSO 体験を制御します。 -- **クライアントのローカルセッション / トークン** は、各アプリが現在ユーザーをサインイン済みとして扱うかどうかを制御します。 -- **グラント (grant)** は、アプリ固有の認可 (Authorization) 状態を表現することで、この 2 つの世界をつなぎます。 - -## サインインの振り返り（なぜサインアウトが多層的なのか） \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as クライアントアプリケーション - end - - box Logto (IdP) - participant OIDC as OIDC プロバイダー - participant SignIn as サインインページ - end - - User ->> Client: アプリケーションへアクセス - Client ->> OIDC: 認証 (Authentication) のためリダイレクト - OIDC -->> OIDC: Logto セッションを確認 - OIDC ->> SignIn: 必要に応じてサインインを促す - SignIn ->> OIDC: ユーザーが認証 (Authentication) - OIDC -->> OIDC: セッションとグラント (grant) を作成 - OIDC ->> Client: 認可コードを返す - Client ->> OIDC: コードをトークンに交換 - OIDC -->> Client: トークンを返す -``` - -## アプリ / デバイス間のセッショントポロジー \{#session-topology-across-apps-devices} - -### 共有セッション Cookie（同じブラウザ / ユーザーエージェント） \{#shared-session-cookie-same-browser-user-agent} - -ユーザーが同じブラウザから複数のアプリにサインインした場合、それらのアプリは同じ Logto セッション Cookie を再利用でき、SSO が適用されます。 - -```mermaid -flowchart TD - U[ユーザー] - A["クライアントアプリケーション A（クライアントドメイン A）"] - B["クライアントアプリケーション B（クライアントドメイン B）"] - C{"Logto セッションは存在しますか？（Logto ドメイン）"} - D["サインインページ（Logto ドメイン）"] - - subgraph UA["ユーザーエージェント A（同じブラウザ）"] - U - A - B - C - D - end - - U -->|サインイン| A - A -->|Logto へリダイレクト| C - U -->|アプリを開く| B - B -->|Logto へリダイレクト| C - C -->|いいえ| D - D -->|セッション作成| C -``` - -### 分離されたセッション Cookie（異なるデバイス / ブラウザ） \{#isolated-session-cookies-different-devices-browsers} - -異なるブラウザ / デバイスは異なる Logto Cookie を保持するため、サインインセッション状態は分離されます。 - -```mermaid -flowchart TD - U[ユーザー] - A["クライアントアプリケーション A（クライアントドメイン A）"] - C{"Logto セッションは存在しますか？（デバイス A、Logto ドメイン）"} - D["サインインページ（デバイス A、Logto ドメイン）"] - - subgraph DeviceA["ユーザーエージェント A"] - A - C - D - end - - B["クライアントアプリケーション B（クライアントドメイン B）"] - E{"Logto セッションは存在しますか？（デバイス B、Logto ドメイン）"} - F["サインインページ（デバイス B、Logto ドメイン）"] - - subgraph DeviceB["ユーザーエージェント B"] - B - E - F - end - - U -->|サインイン| A - A -->|Logto へリダイレクト| C - U -->|サインイン| B - B -->|Logto へリダイレクト| E - C -->|いいえ| D - E -->|いいえ| F - D -->|セッション作成| C - F -->|セッション作成| E -``` - -## サインアウトの仕組み \{#sign-out-mechanisms} - -### 1) クライアント側のみのサインアウト \{#1-client-side-only-sign-out} - -クライアントアプリが自身のローカルセッションやトークン（ID / アクセス / リフレッシュトークン）をクリアします。これにより、そのアプリのローカル状態のみでユーザーがサインアウトされます。 +`https://{your-logto-domain}/oidc/session/end` -- Logto セッションは引き続き有効な場合があります。 -- 同じ Logto セッション配下の他のアプリでは SSO が継続される場合があります。 +現在の Logto SDK の動作では： -### 2) Logto でのセッション終了（現行 Logto 実装でのグローバルサインアウト） \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +1. `signOut()` は `/session/end` にリダイレクトします。 +2. 次に `/session/end/confirm` に進みます。 +3. デフォルトの確認フォームは `logout=true` を自動投稿します。 -集中管理された Logto セッションをクリアするには、アプリがユーザーをエンドセッションエンドポイントへリダイレクトします。例： +その結果、現在の SDK のサインアウトは **グローバルサインアウト** として扱われます。 -`https://{your-logto-domain}/oidc/session/end` - -現行の Logto SDK の挙動： +:::note -1. `signOut()` は `/session/end` へリダイレクトします。 -2. その後 `/session/end/confirm` へ遷移します。 -3. デフォルトの確認フォームが自動で `logout=true` をポストします。 +- **グローバルサインアウト**：集中 Logto セッションを取り消します。 -このため、現行 SDK のサインアウトは **グローバルサインアウト** として扱われます。 +::: -### グローバルサインアウト時に何が起こるか \{#what-happens-during-global-sign-out} +### グローバルサインアウト中に何が起こるか \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["クライアントがサインアウト開始"] --> B["/session/end"] + A["クライアントがサインアウトを開始"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["集中管理された Logto セッションを取り消し"] - D --> E{"アプリごとのグラント (grant) を確認"} - E -->|"offline_access が付与されていない"| F["グラント (grant) を取り消し"] - E -->|"offline_access が付与されている"| G["グラント (grant) TTL まで保持"] + C --> D["集中 Logto セッションを取り消す"] + D --> E{"アプリごとの許可を確認"} + E -->|"offline_access が付与されていない"| F["許可を取り消す"] + E -->|"offline_access が付与されている"| G["許可を許可 TTL が切れるまで保持"] ``` グローバルサインアウト中： -- 集中管理された Logto セッションが取り消されます。 -- 関連するアプリのグラント (grant) はアプリごとの認可 (Authorization) 状態に応じて処理されます： - - `offline_access` が **付与されていない** 場合、関連グラント (grant) は取り消されます。 - - `offline_access` が **付与されている** 場合、エンドセッションではグラント (grant) は取り消されません。 -- `offline_access` の場合、リフレッシュトークンやグラント (grant) はグラント (grant) の有効期限まで有効です。 +- 集中 Logto セッションが取り消されます。 +- 関連するアプリの許可は、アプリの認可状態に応じて処理されます： + - `offline_access` が付与されていない場合、関連する許可は取り消されます。 + - `offline_access` が付与されている場合、セッション終了によって許可は取り消されません。 +- `offline_access` の場合、リフレッシュ トークンと許可は、許可の有効期限が切れるまで有効です。 -## グラント (grant) の有効期間と `offline_access` の影響 \{#grant-lifetime-and-offline-access-impact} +## 許可の有効期間と `offline_access` の影響 \{#grant-lifetime-and-offline-access-impact} -- デフォルトの Logto グラント (grant) TTL は **180 日** です。 -- `offline_access` が付与されている場合、エンドセッションではそのアプリのグラント (grant) はデフォルトで取り消されません。 -- そのグラント (grant) に紐づくリフレッシュトークンチェーンは、グラント (grant) の有効期限まで（または明示的に取り消されるまで）継続できます。 +- デフォルトの Logto 許可 TTL は **180 日**です。 +- `offline_access` が付与されている場合、セッション終了はそのアプリの許可をデフォルトで取り消しません。 +- その許可に関連付けられたリフレッシュ トークンチェーンは、許可が期限切れになるまで（または明示的に取り消されるまで）続行できます。 ## フェデレーテッドサインアウト：バックチャネルログアウト \{#federated-sign-out-back-channel-logout} -アプリ間の一貫性のため、Logto は [バックチャネルログアウト](https://openid.net/specs/openid-connect-backchannel-1_0-final.html) をサポートしています。 +クロスアプリの一貫性のために、Logto は [バックチャネルログアウト](https://openid.net/specs/openid-connect-backchannel-1_0-final.html) をサポートしています。 -ユーザーが 1 つのアプリからサインアウトすると、Logto は同じセッションに参加しているすべてのアプリに対し、登録済みのバックチャネルログアウト URI へログアウトトークンを送信して通知できます。 +ユーザーがあるアプリからサインアウトすると、Logto は同じセッションに参加しているすべてのアプリにログアウトトークンを送信して通知できます。 -アプリのバックチャネル設定で `Is session required` が有効な場合、ログアウトトークンには Logto セッションを識別する `sid` が含まれます。 +アプリのバックチャネル設定で `Is session required` が有効になっている場合、ログアウトトークンには Logto セッションを識別するための `sid` が含まれます。 一般的なフロー： -1. ユーザーが 1 つのアプリからサインアウトを開始 -2. Logto がエンドセッションを処理し、登録済みのバックチャネルログアウト URI へログアウトトークンを送信 -3. 各アプリがログアウトトークンを検証し、自身のローカルセッション / トークンをクリア +1. ユーザーがあるアプリからサインアウトを開始します。 +2. Logto はセッション終了を処理し、登録されたバックチャネルログアウト URI にログアウトトークンを送信します。 +3. 各アプリはログアウトトークンを検証し、自身のローカルセッション / トークンをクリアします。 -## Logto SDK におけるサインアウト方法 \{#sign-out-methods-in-logto-sdks} +## Logto SDK でのサインアウト方法 \{#sign-out-methods-in-logto-sdks} -- **SPA および Web**：`client.signOut()` はローカルトークンストレージをクリアし、Logto のエンドセッションエンドポイントへリダイレクトします。ポストログアウトリダイレクト URI を指定することも可能です。 -- **ネイティブ（React Native / Flutter を含む）**：通常はローカルトークンストレージのみをクリアします。セッションレス WebView のため、Logto のブラウザ Cookie をクリアすることはありません。 +- **SPA とウェブ**：`client.signOut()` はローカルトークンストレージをクリアし、Logto セッション終了エンドポイントにリダイレクトします。ログアウト後のリダイレクト URI を指定することができます。 +- **ネイティブ（React Native / Flutter を含む）**：通常はローカルトークンストレージのみをクリアします。セッションレスの WebView では、Logto ブラウザクッキーをクリアすることはありません。 :::note -セッションレス WebView をサポートしないネイティブアプリや、`emphasized` 設定を認識しない場合（**React Native** や **Flutter** SDK を利用した Android アプリなど）、認証リクエスト時に `prompt=login` パラメータを渡すことで、毎回サインイン画面を強制表示できます。 +セッションレス WebView をサポートしていないネイティブアプリケーションや、`emphasized` 設定を認識しないアプリケーション（**React Native** または **Flutter** SDK を使用する Android アプリ）では、認証リクエストに `prompt=login` パラメータを渡すことで、ユーザーに再度サインインを促すことができます。 ::: -## 毎回再認証を強制する \{#enforce-re-authentication-on-every-access} +## アクセスごとに再認証を強制する \{#enforce-re-authentication-on-every-access} -高セキュリティな操作には、認証リクエストに `prompt=login` を含めて SSO をバイパスし、毎回資格情報の入力を強制できます。 +高セキュリティのアクションには、認証リクエストに `prompt=login` を含めて SSO をバイパスし、毎回資格情報の入力を強制します。 -リフレッシュトークン（`offline_access`）を要求する場合は、`consent` も含めて `prompt=login consent` とします。 +リフレッシュ トークンを受け取るために `offline_access` を要求する場合は、`consent` も含めてください。`prompt=login consent`。 一般的な組み合わせ設定： @@ -235,17 +101,17 @@ flowchart TD prompt=login consent ``` -## よくある質問 (FAQs) \{#faqs} +## よくある質問 \{#faqs}
-### バックチャネルログアウト通知が届きません \{#im-not-receiving-the-back-channel-logout-notifications} +### バックチャネルログアウト通知を受け取っていません。 \{#im-not-receiving-the-back-channel-logout-notifications} -- Logto ダッシュボードでバックチャネルログアウト URI が正しく登録されているか確認してください。 -- アプリが同じユーザー / セッションコンテキストでアクティブなサインイン状態であることを確認してください。 +- Logto ダッシュボードでバックチャネルログアウト URI が正しく登録されていることを確認してください。 +- アプリが同じユーザー / セッションコンテキストでアクティブなサインイン状態を持っていることを確認してください。
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 518e3ed7f54..8eb391dfd1d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: OIDC 認証 (Authentication) 統合のための主要なアプリケーションパラメーター（リダイレクト URI、エンドポイント、リフレッシュ トークン、バックチャネルログアウトなど）を参照できます。 +description: リダイレクト URI、エンドポイント、リフレッシュ トークン、バックチャネル ログアウトなど、OIDC 認証 (Authentication) 統合のための主要なアプリケーション パラメーターを参照してください。 sidebar_position: 6 --- @@ -7,178 +7,197 @@ sidebar_position: 6 ## はじめに \{#introduction} -Logto における _アプリケーション_ とは、Logto プラットフォームに登録され、ユーザー情報へのアクセスやユーザーの代理でアクションを実行する権限が付与された特定のソフトウェアプログラムまたはサービスを指します。アプリケーションは、Logto API へのリクエスト元を識別し、ユーザーがそれらのアプリケーションにアクセスする際の認証 (Authentication) および認可 (Authorization) プロセスを管理するために使用されます。 +Logto における _アプリケーション_ とは、Logto プラットフォームに登録され、ユーザー情報へのアクセスやユーザーの代わりにアクションを実行する権限を与えられた特定のソフトウェアプログラムまたはサービスを指します。アプリケーションは、Logto API に対するリクエストの発信元を識別し、これらのアプリケーションにアクセスするユーザーの認証 (Authentication) および認可 (Authorization) プロセスを管理するために使用されます。 -Logto のサインイン体験におけるアプリケーションの利用により、ユーザーは一元的な場所から認可 (Authorization) されたアプリケーションへ簡単にアクセス・管理でき、統一された安全な認証 (Authentication) プロセスが実現されます。これによりユーザー体験が効率化され、認可 (Authorization) された人物のみが機密情報へアクセスしたり、組織の代理でアクションを実行できるようになります。 +Logto のサインイン体験におけるアプリケーションの使用により、ユーザーは一元的な場所から認可されたアプリケーションに簡単にアクセスし、管理することができ、一貫性のある安全な認証 (Authentication) プロセスを提供します。これにより、ユーザー体験が簡素化され、組織の代わりに機密情報にアクセスしたりアクションを実行したりするのは認可された個人のみであることが保証されます。 -また、アプリケーションは Logto の監査ログにも利用され、ユーザーのアクティビティを追跡し、潜在的なセキュリティ脅威や侵害を特定するのに役立ちます。特定のアクションを特定のアプリケーションと関連付けることで、Logto はデータがどのようにアクセス・利用されているかの詳細なインサイトを提供し、組織がセキュリティやコンプライアンス要件をより適切に管理できるようにします。 -アプリケーションを Logto と統合したい場合は、 [Logto との統合](/integrate-logto) をご覧ください。 +アプリケーションは、Logto の監査ログでも使用され、ユーザーの活動を追跡し、潜在的なセキュリティ脅威や侵害を特定します。特定のアクションを特定のアプリケーションに関連付けることにより、Logto はデータがどのようにアクセスされ、使用されているかについての詳細な洞察を提供し、組織がセキュリティおよびコンプライアンス要件をより適切に管理できるようにします。 +アプリケーションを Logto と統合したい場合は、[Logto の統合](/integrate-logto)を参照してください。 ## プロパティ \{#properties} ### アプリケーション ID \{#application-id} -_アプリケーション ID_ は、Logto 内でアプリケーションを識別するための一意な自動生成キーであり、OAuth 2.0 では [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) として参照されます。 +_アプリケーション ID_ は、Logto 内でアプリケーションを識別するための一意の自動生成キーであり、OAuth 2.0 では [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) として参照されます。 ### アプリケーションタイプ \{#application-types} -_アプリケーション_ は、次のいずれかのタイプとなります： +_アプリケーション_ は、次のいずれかのアプリケーションタイプにすることができます： -- **ネイティブアプリ**：ネイティブ環境で動作するアプリ。例：iOS アプリ、Android アプリ。 - - **デバイスフローアプリ**：入力制限デバイスやヘッドレスアプリケーション（例：スマート TV、ゲーム機、CLI ツール、IoT デバイス）向けの特別なネイティブアプリタイプです。標準のリダイレクトベースフローの代わりに [OAuth 2.0 デバイス認可 (Authorization) グラント](https://auth.wiki/device-flow) を使用します。詳細は [デバイスフロー クイックスタート](/quick-starts/device-flow) を参照してください。 -- **シングルページアプリ**：Web ブラウザ上で動作し、サーバーからの新しいデータでページ全体を再読み込みせずに更新するアプリ。例：React DOM アプリ、Vue アプリ。 -- **従来型 Web アプリ**：Web サーバーのみでページをレンダリング・更新するアプリ。例：JSP、PHP。 -- **マシン間通信 (M2M) アプリ**：ユーザー操作なしでサービス間通信を直接行うマシン環境で動作するアプリケーション。 +- **ネイティブアプリ** は、ネイティブ環境で実行されるアプリです。例：iOS アプリ、Android アプリ。 + - **デバイスフローアプリ** は、入力が制限されたデバイスやヘッドレスアプリケーション（例：スマートテレビ、ゲームコンソール、CLI ツール、IoT デバイス）向けの特別なタイプのネイティブアプリです。標準のリダイレクトベースのフローの代わりに [OAuth 2.0 デバイス認可グラント](https://auth.wiki/device-flow) を使用します。詳細は [デバイスフローのクイックスタート](/quick-starts/device-flow) を参照してください。 +- **シングルページアプリ** は、Web ブラウザで実行され、サーバーからの新しいデータでページを更新し、完全に新しいページを読み込むことなく動作するアプリです。例：React DOM アプリ、Vue アプリ。 +- **従来の Web アプリ** は、Web サーバーによってページをレンダリングおよび更新するアプリです。例：JSP、PHP。 +- **マシン間通信 (M2M) アプリ** は、ユーザーの操作なしにサービス間通信を直接行うためのマシン環境で実行されるアプリケーションです。 ### アプリケーションシークレット \{#application-secret} -_アプリケーションシークレット_ は、認証 (Authentication) システム内でアプリケーションを認証 (Authentication) するためのキーであり、特にプライベートクライアント（従来型 Web および M2M アプリ）においてプライベートなセキュリティバリアとして機能します。 +_アプリケーションシークレット_ は、認証 (Authentication) システム内でアプリケーションを認証するために使用されるキーであり、特にプライベートクライアント（従来の Web アプリおよび M2M アプリ）に対するプライベートなセキュリティバリアとして機能します。 :::tip -シングルページアプリ (SPA) およびネイティブアプリにはアプリシークレットは提供されません。SPA およびネイティブアプリは「パブリッククライアント」であり、シークレットを保持できません（ブラウザコードやアプリバンドルは検査可能なため）。アプリシークレットの代わりに、Logto は PKCE、厳格なリダイレクト URI / CORS 検証、短命なアクセス トークン、リフレッシュ トークンのローテーションで保護します。 +シングルページアプリ (SPA) およびネイティブアプリは、アプリシークレットを提供しません。SPA およびネイティブアプリは「パブリッククライアント」であり、シークレットを保持できません（ブラウザコードやアプリバンドルは検査可能です）。アプリシークレットの代わりに、Logto は PKCE、厳格なリダイレクト URI / CORS 検証、短命のアクセス トークン、およびリフレッシュ トークンのローテーションでそれらを保護します。 ::: ### アプリケーション名 \{#application-name} -_アプリケーション名_ は、人間が読めるアプリケーションの名称であり、管理コンソールに表示されます。 +_アプリケーション名_ は、人間が読みやすいアプリケーションの名前であり、管理コンソールに表示されます。 -_アプリケーション名_ は Logto でアプリケーションを管理する上で重要な要素であり、管理者がプラットフォーム内の個々のアプリケーションのアクティビティを簡単に識別・追跡できるようにします。 +_アプリケーション名_ は、Logto でアプリケーションを管理する上で重要なコンポーネントであり、管理者がプラットフォーム内の個々のアプリケーションの活動を簡単に識別および追跡できるようにします。 :::note -_アプリケーション名_ は管理コンソールにアクセスできるすべてのユーザーに表示されるため、慎重に選択することが重要です。アプリケーションの目的や機能を正確に反映し、分かりやすく認識しやすい名称にしてください。 +_アプリケーション名_ は、管理コンソールにアクセスできるすべてのユーザーに表示されるため、慎重に選択する必要があります。アプリケーションの目的と機能を正確に反映し、理解しやすく認識しやすいものであるべきです。 ::: ### 説明 \{#description} -アプリケーションの簡単な説明が管理コンソールのアプリケーション詳細ページに表示されます。説明は、アプリケーションの目的や機能、その他関連情報など、管理者に追加情報を提供することを意図しています。 +アプリケーションの簡単な説明が管理コンソールのアプリケーション詳細ページに表示されます。説明は、アプリケーションの目的、機能、およびその他の関連する詳細情報を管理者に提供することを目的としています。 ### リダイレクト URI \{#redirect-uris} -_リダイレクト URI_ は、アプリケーションに事前設定された有効なリダイレクト URI のリストです。ユーザーが Logto にサインインしアプリケーションへアクセスしようとすると、アプリケーション設定で指定された許可された URI のいずれかにリダイレクトされます。 +_リダイレクト URI_ は、アプリケーションのために事前に構成された有効なリダイレクト URI のリストです。ユーザーが Logto にサインインし、アプリケーションにアクセスしようとすると、アプリケーション設定で指定された許可された URI のいずれかにリダイレクトされます。 -許可された URI リストは、認証 (Authentication) プロセス中にアプリケーションから Logto へ送信される認可 (Authorization) リクエストに含まれるリダイレクト URI を検証するために使用されます。認可 (Authorization) リクエストで指定されたリダイレクト URI がアプリケーション設定の許可リストのいずれかと一致する場合、認証 (Authentication) 成功後にその URI へリダイレクトされます。一致しない場合、リダイレクトされず認証 (Authentication) プロセスは失敗します。 +許可された URI リストは、認証 (Authentication) プロセス中にアプリケーションから Logto に送信される認可 (Authorization) リクエストに含まれるリダイレクト URI を検証するために使用されます。認可 (Authorization) リクエストで指定されたリダイレクト URI がアプリケーション設定の許可された URI のいずれかと一致する場合、ユーザーは認証 (Authentication) に成功した後、その URI にリダイレクトされます。リダイレクト URI が許可リストにない場合、ユーザーはリダイレクトされず、認証 (Authentication) プロセスは失敗します。 :::note -すべての有効なリダイレクト URI を Logto のアプリケーションの許可リストに追加しておくことが重要です。これにより、認証 (Authentication) 後にユーザーが正常にアプリケーションへアクセスできるようになります。 +すべての有効なリダイレクト URI が Logto のアプリケーションの許可リストに追加されていることを確認することが重要です。これにより、ユーザーが認証 (Authentication) 後にアプリケーションに正常にアクセスできるようになります。 ::: -詳細は [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) をご覧ください。 +[リダイレクションエンドポイント](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) を参照して、詳細情報を確認できます。 - OIDC の認可コードフローにおけるリダイレクト URI の理解 + OIDC における認可コードフローでのリダイレクト URI の理解 #### ワイルドカードパターン \{#wildcard-patterns} -_対象: シングルページアプリ、従来型 Web アプリ_ +_利用可能性: シングルページアプリ、従来の Web アプリ_ -リダイレクト URI は、プレビュー環境などの動的環境向けにワイルドカードパターン（`*`）をサポートしています。ワイルドカードは HTTP / HTTPS URI のホスト名およびパス名部分で使用できます。 +リダイレクト URI は、プレビュー展開などの動的環境のためにワイルドカードパターン (`*`) をサポートしています。ワイルドカードは、HTTP / HTTPS URI のホスト名およびパス名コンポーネントで使用できます。 -**ルール：** +**ルール:** -- ワイルドカードはホスト名およびパス名のみ許可 -- スキーム、ポート、クエリパラメータ、ハッシュフラグメントでは使用不可 -- ホスト名のワイルドカードは少なくとも 1 つのドットを含む必要があります（例：`https://*.example.com/callback`） +- ワイルドカードはホスト名およびパス名でのみ許可されます +- ワイルドカードはスキーム、ポート、クエリパラメータ、またはハッシュフラグメントでは許可されません +- ホスト名のワイルドカードには少なくとも 1 つのドットを含める必要があります（例：`https://*.example.com/callback`） -**例：** +**例:** -- `https://*.example.com/callback` - 任意のサブドメインにマッチ -- `https://preview-*.example.com/callback` - プレビュー環境にマッチ -- `https://example.com/*/callback` - 任意のパスセグメントにマッチ +- `https://*.example.com/callback` - 任意のサブドメインに一致 +- `https://preview-*.example.com/callback` - プレビュー展開に一致 +- `https://example.com/*/callback` - 任意のパスセグメントに一致 :::caution -ワイルドカードリダイレクト URI は標準 OIDC ではなく、攻撃対象領域が広がる可能性があります。可能な限り正確なリダイレクト URI を優先して使用してください。 +ワイルドカードリダイレクト URI は標準の OIDC ではなく、攻撃の表面を増やす可能性があります。可能な限り正確なリダイレクト URI を使用することをお勧めします。 ::: -### サインアウト後リダイレクト URI \{#post-sign-out-redirect-uris} +### サインアウト後のリダイレクト URI \{#post-sign-out-redirect-uris} -_サインアウト後リダイレクト URI_ は、ユーザーが Logto からサインアウトした後にリダイレクトされるよう、アプリケーションに事前設定された有効な URI のリストです。 +_サインアウト後のリダイレクト URI_ は、Logto からサインアウトした後にユーザーをリダイレクトするためにアプリケーションに事前に構成された有効な URI のリストです。 -許可された _サインアウト後リダイレクト URI_ の利用は、OIDC の RP-Initiated（Relying Party Initiated）ログアウト仕様の一部です。この仕様は、アプリケーションがユーザーのログアウトリクエストを開始し、サインアウト後に事前設定されたエンドポイントへリダイレクトする標準化された方法を提供します。 +ログアウトのための許可された _サインアウト後のリダイレクト URI_ の使用は、OIDC の RP-Initiated (Relying Party Initiated) Logout 仕様の一部です。この仕様は、ユーザーのログアウトリクエストをアプリケーションが開始するための標準化された方法を提供し、ユーザーがサインアウトした後に事前に構成されたエンドポイントにリダイレクトすることを含みます。 -ユーザーが Logto からサインアウトすると、セッションが終了し、アプリケーション設定で指定された許可 URI のいずれかにリダイレクトされます。これにより、サインアウト後にユーザーが認可 (Authorization) された有効なエンドポイントのみに誘導され、未知または未検証のエンドポイントへのリダイレクトによる不正アクセスやセキュリティリスクを防ぎます。 +ユーザーが Logto からサインアウトすると、そのセッションは終了し、アプリケーション設定で指定された許可された URI のいずれかにリダイレクトされます。これにより、ユーザーがサインアウトした後に認可された有効なエンドポイントにのみリダイレクトされることが保証され、ユーザーを未知または未確認のエンドポイントにリダイレクトすることによる不正アクセスやセキュリティリスクを防ぐことができます。 -詳細は [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) をご覧ください。 +[RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) を参照して、詳細情報を確認できます。 -### CORS 許可オリジン \{#cors-allowed-origins} +### CORS 許可されたオリジン \{#cors-allowed-origins} -_CORS（クロスオリジンリソースシェアリング）許可オリジン_ は、アプリケーションが Logto サービスへリクエストを送信できる許可済みオリジンのリストです。許可リストに含まれていないオリジンからは Logto サービスへのリクエストはできません。 +_CORS (クロスオリジンリソース共有) 許可されたオリジン_ は、アプリケーションが Logto サービスにリクエストを行うことができる許可されたオリジンのリストです。許可リストに含まれていないオリジンは、Logto サービスにリクエストを行うことができません。 -CORS 許可オリジンリストは、未認可ドメインからの Logto サービスへのアクセスを制限し、クロスサイトリクエストフォージェリ（CSRF）攻撃を防ぐのに役立ちます。Logto でアプリケーションごとに許可オリジンを指定することで、認可 (Authorization) されたドメインのみがサービスへリクエストできるようにします。 +CORS 許可されたオリジンリストは、未承認のドメインからの Logto サービスへのアクセスを制限し、クロスサイトリクエストフォージェリ (CSRF) 攻撃を防ぐのに役立ちます。Logto でアプリケーションの許可されたオリジンを指定することにより、サービスは許可されたドメインのみがサービスにリクエストを行うことができるようにします。 :::note -許可オリジンリストには、アプリケーションが提供されるオリジンを含めてください。これにより、アプリケーションからのリクエストは許可され、未認可オリジンからのリクエストはブロックされます。 +許可されたオリジンリストには、アプリケーションが提供されるオリジンを含める必要があります。これにより、アプリケーションからのリクエストが許可され、未承認のオリジンからのリクエストがブロックされます。 ::: ### OpenID プロバイダー構成エンドポイント \{#openid-provider-configuration-endpoint} -[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) のためのエンドポイントです。 +[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) のエンドポイント。 ### 認可 (Authorization) エンドポイント \{#authorization-endpoint} -_認可 (Authorization) エンドポイント_ は OIDC 用語であり、ユーザーの認証 (Authentication) プロセスを開始するために使用される必須エンドポイントです。Logto プラットフォームに登録された保護リソースやアプリケーションへユーザーがアクセスしようとすると、_認可 (Authorization) エンドポイント_ へリダイレクトされ、アイデンティティの認証 (Authentication) およびリクエストされたリソースへの認可 (Authorization) を取得します。 +_認可 (Authorization) エンドポイント_ は OIDC 用語であり、ユーザーの認証 (Authentication) プロセスを開始するために使用される必須のエンドポイントです。Logto プラットフォームに登録された保護されたリソースまたはアプリケーションにユーザーがアクセスしようとすると、_認可 (Authorization) エンドポイント_ にリダイレクトされ、アイデンティティを認証 (Authentication) し、要求されたリソースへのアクセスを取得します。 -詳細は [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) をご覧ください。 +[認可 (Authorization) エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) を参照して、詳細情報を確認できます。 ### トークンエンドポイント \{#token-endpoint} -_トークンエンドポイント_ は OIDC 用語であり、OIDC クライアントが OIDC プロバイダーからアクセス トークン、ID トークン、リフレッシュ トークンを取得するための Web API エンドポイントです。 +_トークンエンドポイント_ は OIDC 用語であり、OIDC クライアントが OIDC プロバイダーからアクセス トークン、ID トークン、またはリフレッシュ トークンを取得するために使用される Web API エンドポイントです。 -OIDC クライアントがアクセス トークンや ID トークンを取得する必要がある場合、認可 (Authorization) グラント（通常は認可コードまたはリフレッシュ トークン）を付与してトークンエンドポイントへリクエストを送信します。トークンエンドポイントは認可 (Authorization) グラントを検証し、有効であればクライアントにアクセス トークンや ID トークンを発行します。 +OIDC クライアントがアクセス トークンまたは ID トークンを取得する必要がある場合、トークンエンドポイントに認可 (Authorization) グラント（通常は認可コードまたはリフレッシュ トークン）を含むリクエストを送信します。トークンエンドポイントは認可 (Authorization) グラントを検証し、グラントが有効であればクライアントにアクセス トークンまたは ID トークンを発行します。 -詳細は [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) をご覧ください。 +[トークンエンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) を参照して、詳細情報を確認できます。 -### Userinfo エンドポイント \{#userinfo-endpoint} +### ユーザー情報エンドポイント \{#userinfo-endpoint} -OpenID Connect の [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 +OpenID Connect [ユーザー情報エンドポイント](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 -### 常にリフレッシュ トークンを発行 \{#always-issue-refresh-token} +### 常にリフレッシュ トークンを発行する \{#always-issue-refresh-token} -_対象: 従来型 Web、SPA_ +_利用可能性: 従来の Web、SPA_ -有効にすると、認証 (Authentication) リクエストで `prompt=consent` やスコープに `offline_access` が指定されていなくても、Logto は常にリフレッシュ トークンを発行します。 +有効にすると、Logto は `prompt=consent` が認証 (Authentication) リクエストに提示されているかどうか、または `offline_access` がスコープに提示されているかどうかに関係なく、常にリフレッシュ トークンを発行します。 -ただし、この運用は必要な場合（通常はリフレッシュ トークンを必要とする一部のサードパーティ OAuth 連携）を除き推奨されません。OpenID Connect との互換性がなく、問題が発生する可能性があります。 +ただし、これは OpenID Connect と互換性がなく、問題を引き起こす可能性があるため、必要な場合を除いて（通常、リフレッシュ トークンを必要とする一部のサードパーティ OAuth 統合に役立ちます）、この方法は推奨されません。 ### リフレッシュ トークンのローテーション \{#rotate-refresh-token} _デフォルト: `true`_ -有効にすると、Logto は次の条件下でトークンリクエスト時に新しいリフレッシュ トークンを発行します： +有効にすると、Logto は次の条件下でトークンリクエストに対して新しいリフレッシュ トークンを発行します： -- リフレッシュ トークンが 1 年間ローテーション（新しいものが発行され有効期限が延長）された場合；**または** -- リフレッシュ トークンの有効期限が近い場合（元の TTL の 70% 以上経過）；**または** -- クライアントがパブリッククライアント（例：ネイティブアプリやシングルページアプリ）である場合。 +- リフレッシュ トークンが 1 年間ローテーションされた場合（新しいものを発行して TTL が延長された場合）；**または** +- リフレッシュ トークンが有効期限に近づいている場合（元の Time to Live (TTL) の >=70% が経過した場合）；**または** +- クライアントがパブリッククライアントである場合、例：ネイティブアプリケーションまたはシングルページアプリケーション (SPA)。 :::note -パブリッククライアントの場合、この機能が有効だと、リフレッシュ トークンを使って新しいアクセス トークンを取得するたびに新しいリフレッシュ トークンが発行されます。 -これらのパブリッククライアントでも機能をオフにできますが、セキュリティ上有効のままにすることを強く推奨します。 +パブリッククライアントの場合、この機能が有効になっていると、クライアントがリフレッシュ トークンを使用して新しいアクセス トークンを交換する際に常に新しいリフレッシュ トークンが発行されます。 +これらのパブリッククライアントに対しても機能をオフにすることはできますが、セキュリティ上の理由から有効にしておくことを強くお勧めします。 ::: リフレッシュ トークンのローテーションの理解 -### リフレッシュ トークンの有効期間 (TTL) 日数 \{#refresh-token-time-to-live-ttl-in-days} +### リフレッシュ トークンの有効期間 (TTL) （日数）\{#refresh-token-time-to-live-ttl-in-days} -_対象: SPA 以外；デフォルト: 14 日_ +_利用可能性: SPA ではない；デフォルト: 14 日_ -リフレッシュ トークンが新しいアクセス トークンをリクエストできる有効期間です。有効期間が過ぎると無効になります。トークンリクエストによりリフレッシュ トークンの TTL はこの値まで延長されます。 +リフレッシュ トークンが新しいアクセス トークンを要求するために使用できる期間であり、有効期限が切れて無効になるまでの期間です。トークンリクエストは、リフレッシュ トークンの TTL をこの値に延長します。 -一般的には、より短い値が推奨されます。 +通常、より低い値が推奨されます。 -注意：SPA（シングルページアプリ）ではセキュリティ上、TTL の延長はできません。つまり、Logto はトークンリクエストによる TTL 延長を行いません。ユーザー体験を向上させるには「リフレッシュ トークンのローテーション」機能を有効にし、必要に応じて新しいリフレッシュ トークンを発行できるようにしてください。 +注意: セキュリティ上の理由から、SPA（シングルページアプリ）では TTL の更新は利用できません。つまり、Logto はトークンリクエストを通じて TTL を延長しません。ユーザー体験を向上させるために、「リフレッシュ トークンのローテーション」機能を有効にして、必要に応じて Logto が新しいリフレッシュ トークンを発行できるようにすることができます。 -:::caution リフレッシュ トークンとセッションバインディング -認可 (Authorization) リクエストで `offline_access` スコープ **なし** でリフレッシュ トークンが発行された場合、そのトークンはユーザーセッションにバインドされます。セッションの TTL は **14 日間** で固定です。セッションが期限切れになると、リフレッシュ トークンは自身の TTL 設定に関わらず無効となります。 +:::caution リフレッシュ トークンとセッションのバインディング +認可 (Authorization) リクエストで `offline_access` スコープなしでリフレッシュ トークンが発行された場合、それはユーザーセッションにバインドされます。セッションの TTL は **14 日** に固定されています。セッションが期限切れになると、リフレッシュ トークンはその独自の TTL 設定に関係なく無効になります。 -リフレッシュ トークンの TTL 設定を最大限に活用するには、認可 (Authorization) リクエストに `offline_access` スコープを必ず含めてください。 +リフレッシュ トークンの TTL 設定が完全に効果を発揮するようにするには、認可 (Authorization) リクエストに `offline_access` スコープを含めることを確認してください。 ::: ### バックチャネルログアウト URI \{#backchannel-logout-uri} -OpenID Connect のバックチャネルログアウトエンドポイントです。詳細は [フェデレーテッドサインアウト：バックチャネルログアウト](#) をご覧ください。 +OpenID Connect のバックチャネルログアウトエンドポイント。詳細は [フェデレーテッドサインアウト: バックチャネルログアウト](#) を参照してください。 + +### 最大許可グラント数 (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` は、現在のアプリに対するユーザーごとの同時アクティブグラントの最大数を制御する `customClientMetadata` の下のオプションのアプリレベルフィールドです。 + +- **デフォルト**: `undefined`（制限なし） +- **設定時**: 各認可 (Authorization) 成功時に、Logto は現在のアプリでのユーザーの総アクティブグラントを確認します（ブラウザおよびデバイス全体で）。制限を超えた場合、Logto は最も古いグラントを取り消します。 + +この設定は、アプリごとに同時認証されたデバイスを制限したい場合に便利です。 + +:::note + +このフィールドは次のものにはサポートされていません： + +- マシン間通信アプリ +- 保護されたアプリ +- SAML アプリ + +::: ### カスタムデータ \{#custom-data} -事前定義されたアプリケーションプロパティに含まれない追加のカスタムアプリケーション情報です。ユーザーは、ビジネス固有の設定や構成など、特定のニーズに応じて独自のカスタムデータフィールドを定義できます。 +事前定義されたアプリケーションプロパティにリストされていない追加のカスタムアプリケーション情報であり、ユーザーはビジネス固有の設定や構成など、特定のニーズに応じて独自のカスタムデータフィールドを定義できます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..b7d9e73b5a6 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,168 @@ +# セッション + +Logto のセッションは、アプリ、ブラウザ、デバイス間で認証 (Authentication) 状態がどのように作成、共有、更新、取り消されるかを定義します。 + +実際には、ユーザーは「サインイン済み」という状態を体験しますが、システム状態は複数のレイヤーに分かれています。これらのレイヤーを理解することが、予測可能なシングルサインオン (SSO)、トークン更新、サインアウトの動作を設計する鍵です。 + +## Logto のセッションモデル \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto ドメイン"] + S["サインインセッション"] + G1["グラント (App A)"] + G2["グラント (App B)"] + end + + subgraph AppA ["アプリドメイン A"] + A["ローカルセッション / トークン"] + end + + subgraph AppB ["アプリドメイン B"] + B["ローカルセッション / トークン"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto サインインセッション**：Logto ドメインのクッキーとして保存される集中管理されたサインイン状態。現在のブラウザコンテキストでの SSO の可用性を制御します。 +- **グラント**：`ユーザー + クライアントアプリ` のためのアプリ固有の認可 (Authorization) 状態。グラントは、集中管理されたサインインとアプリトークン発行の間の橋渡しです。 +- **アプリローカルセッション / トークン**：各アプリ内のローカル認証 (Authentication) 状態（ID / アクセス / リフレッシュトークン、アプリセッションクッキーなど）。 + +## コアコンセプト \{#core-concepts} + +### Logto セッションとは？ \{#what-is-a-logto-session} + +Logto セッションは、サインインが成功した後に作成される集中管理された認証 (Authentication) 状態です。まだ有効であれば、Logto は同じテナント内の他のアプリに対してユーザーを静かに認証 (Authentication) できます。存在しない場合、ユーザーは再度サインインする必要があります。 + +### グラントとは？ \{#what-are-grants} + +グラントは、特定のユーザーとクライアントアプリに結び付けられたアプリレベルの認可 (Authorization) 状態です。 + +- 1 つの Logto セッションには、複数のアプリのグラントが含まれることがあります。 +- アプリのトークンは、そのアプリのグラントの下で発行されます。 +- グラントを取り消すと、そのアプリのトークンベースのアクセスを継続する能力に影響を与えます。 + +### セッション、グラント、アプリ認証 (Authentication) 状態の関係 \{#how-session-grants-and-app-auth-state-relate} + +- **セッション**は次の質問に答えます：「このブラウザは今 Logto で SSO を行うことができますか？」 +- **グラント**は次の質問に答えます：「このユーザーはこのクライアントアプリに対して認可 (Authorization) されていますか？」 +- **アプリローカルセッション**は次の質問に答えます：「このアプリは現在ユーザーをサインイン済みとして扱っていますか？」 + +## サインインとセッションの作成 \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as クライアントアプリケーション + end + + box Logto + participant OIDC as OIDC プロバイダー + participant SignIn as サインインページ + end + + User ->> Client: アプリケーションにアクセス + Client ->> OIDC: 認可 (Authorization) リクエスト + OIDC -->> OIDC: 既存の Logto セッションを確認 + OIDC ->> SignIn: 必要に応じてサインインを促す + SignIn ->> OIDC: ユーザーが認証 (Authentication) + OIDC -->> OIDC: セッションとアプリグラントを作成 + OIDC ->> Client: 認可 (Authorization) コードを返す + Client ->> OIDC: コードをトークンに交換 + OIDC -->> Client: トークンを返す +``` + +## アプリとデバイス間のセッショントポロジー \{#session-topology-across-apps-and-devices} + +### 同じブラウザ：共有された Logto セッション \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[ユーザー] + A["クライアントアプリ A"] + B["クライアントアプリ B"] + C{"Logto セッションが存在しますか？"} + D["Logto サインインページ"] + + U --> A + A --> C + U --> B + B --> C + C -->|No| D +``` + +同じブラウザ内のアプリは、集中管理された Logto セッション状態を共有できるため、繰り返しの資格情報入力なしで SSO が可能です。 + +### 異なるブラウザまたはデバイス：分離された Logto セッション \{#different-browsers-or-devices-isolated-logto-sessions} + +各ブラウザ / デバイスには別々のクッキー保存があります。デバイス A で有効なセッションがあるからといって、デバイス B でも有効なセッションがあるとは限りません。 + +## セッションライフサイクル \{#session-lifecycle} + +### 1. 作成 \{#1-create} + +ユーザー認証 (Authentication) 後、Logto は集中管理されたセッションとアプリ固有のグラントを作成します。 + +### 2. 再利用 (SSO) \{#2-reuse-sso} + +同じブラウザでセッションクッキーが有効である限り、新しい認可 (Authorization) リクエストはしばしば静かに完了できます。 + +### 3. トークンの更新 \{#3-renew-tokens} + +アプリアクセスは通常、トークンリフレッシュフロー（有効な場合）を通じて継続します。これはアプリレベルの継続性であり、集中管理された Logto セッションがまだ存在するかどうかとは別です。 + +### 4. 取り消し / 期限切れ \{#4-revokeexpire} + +取り消しは異なるレイヤーで発生することがあります： + +- ローカルアプリのサインアウトは、アプリローカルトークン / セッションを削除します。 +- セッションの終了は、集中管理された Logto セッションを削除します。 +- グラントの取り消しは、アプリレベルの認可 (Authorization) 継続性を削除します。 + +## 設計の推奨事項 \{#design-recommendations} + +- アプリコード内でアプリローカルセッションの処理を明示的に行う。 +- Logto セッション、グラント、アプリローカルセッションを別々のレイヤーとして扱う。 +- サインアウトをアプリローカルのみにするか、グローバルにするかを選択する。 +- 複数のアプリの一貫性が必要な場合は、[バックチャネルログアウト](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) を使用する。 +- サインアウトの動作と実装の詳細については、[サインアウト](/end-user-flows/sign-out) を参照してください。 + +## アクセス取り消しのベストプラクティス \{#best-practices-for-revoking-access} + +目標に基づいて異なる取り消し戦略を使用する： + +- **ファーストパーティアプリからのアクセスを取り消す**： + `revokeGrantsTarget=firstParty` を使用してターゲットセッションを取り消します。 + これにより、そのセッションに関連付けられたファーストパーティアプリ全体でユーザーがサインアウトされ、一貫したログアウト体験が作成されます。 + 同時に、`offline_access` が付与されたサードパーティアプリのグラントは、継続的な統合のために利用可能なままです。 + セッション取り消しの詳細については、[ユーザーセッションの管理](/sessions/manage-user-sessions) を参照してください。 + +- **サードパーティアプリへのアクセスを取り消す**： + 次のいずれかを選択します： + + - `revokeGrantsTarget=all` を使用してセッションを取り消し、そのセッションに関連付けられたすべてのグラントを取り消します。 + - グラント管理 API を通じて特定のグラントを直接取り消し、完全なセッションサインアウトを強制せずにサードパーティアプリの認可 (Authorization) を削除します。 + グラント固有の取り消し戦略については、[ユーザー認可 (Authorization) アプリ (グラント) の管理](/sessions/grants-management) を参照してください。 + +- **Logto コンソールを使用する場合**： + ユーザー詳細ページでは、Logto はセッション管理と認可 (Authorization) されたサードパーティアプリ管理の両方を提供します。 + - セッションを取り消すと、ファーストパーティアプリのグラントも取り消され、ファーストパーティのログアウト動作が一貫します。 + - サードパーティアプリの認可 (Authorization) を取り消すと、そのサードパーティアプリのグラントが取り消され、元のセッション状態は変更されません。 + +## 関連リソース \{#related-resources} + +ユーザーセッションの管理 +ユーザー認可 (Authorization) アプリ (グラント) の管理 +セッション設定 +サインアウト +サインアップとサインイン + + 認証 (Authentication) フローの理解 + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..84ea98454c3 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# ユーザーの認可されたアプリ (グラント) を管理する + +アプリのグラントは、特定のクライアントアプリケーションに対するユーザーの認可状態を表します。 + +ユーザーや管理者が認可されたアプリを確認し、全体の Logto セッションを取り消すことなくアプリのアクセスを取り消す必要がある場合に、グラント管理を使用します。 + +グラントが取り消されると、それらのグラントに対して以前に発行された不透明トークン (Opaque token) とリフレッシュ トークン (Refresh token) は無効になります。 + +## 適切なパスを選択する \{#choose-the-right-path} + +| シナリオ | 推奨パス | +| -------------------------------------------------------------- | -------------- | +| サインインしたユーザーが自分のアプリの認可を管理する | Account API | +| 管理者やサポートチームがターゲットユーザーのグラントを管理する | Management API | +| オペレーターが UI でサードパーティアプリの認可を管理する | Admin Console | + +## 直接グラント管理 API \{#direct-grant-management-apis} + +### Account API (セルフサービス) \{#account-api-self-service} + +エンドユーザーのアカウント設定ページで Account API を使用します： + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- 参照: [ユーザーの認可されたアプリ (グラント) を管理する](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (管理ツール) \{#management-api-admin-tools} + +管理ツールやサポートワークフローで Management API を使用します： + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- 参照: [ユーザーの認可されたアプリ (グラント) を管理する](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### アプリタイプでグラントリストをフィルタリングする \{#filter-grant-list-by-app-type} + +グラントリストのエンドポイントは、オプションのクエリパラメーター `appType` をサポートしています： + +- `appType=firstParty`: ファーストパーティアプリのグラントのみをリストします。 +- `appType=thirdParty`: サードパーティアプリのグラントのみをリストします。 +- `appType` を省略: すべてのアクティブなグラントを返します。 + +## コンソールでサードパーティアプリの認可を管理する \{#manage-third-party-app-authorizations-in-console} + +Logto コンソールでは、ユーザー詳細ページを使用して認可されたサードパーティアプリを表示および取り消すことができます。 + +- 参照: [ユーザーの認可されたサードパーティアプリを管理する](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## セッションを取り消す際にグラントを取り消す \{#revoke-grants-when-revoking-a-session} + +`DELETE /api/my-account/sessions/{sessionId}` を使用してセッションを取り消す際に、オプションのクエリパラメーター `revokeGrantsTarget` を使用してグラントの取り消し範囲を制御します： + +- `all`: セッションに関連付けられたすべてのアプリのグラントを取り消します。 +- `firstParty`: ファーストパーティアプリのグラントのみを取り消します。 + +セッションレベルの動作とエンドポイントのコンテキストについては、[ユーザーセッションを管理する](/sessions/manage-user-sessions) と [サインアウト](/end-user-flows/sign-out) を参照してください。 + +## 関連リソース \{#related-resources} + +セッション +ユーザーセッションを管理する + + Account API によるアカウント設定: ユーザーの認可されたアプリ (グラント) を管理する + + + Management API によるアカウント設定: ユーザーの認可されたアプリ (グラント) を管理する + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..48a089e6e65 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# ユーザーセッションの管理 + +ユーザーセッション管理は、ユーザーと管理者がアクティブなサインイン状態を確認し、必要に応じてセッションを取り消すのに役立ちます。 + +Logto では、次の 3 つの一般的な方法でセッションを管理できます： + +- **Account API**: 製品のアカウント設定ページでエンドユーザーがセルフサービスを行うため。 +- **Management API**: 管理者またはサポートツールが任意のユーザーのセッションを管理するため。 +- **Admin Console**: Logto Console でカスタムツールを構築せずにオペレーターのワークフローを実行するため。 + +## 適切な API を選択する \{#choose-the-right-api} + +| シナリオ | 推奨 API | +| -------------------------------------------------------------- | -------------- | +| サインインしたユーザーが自分のアクティブなセッションを管理する | Account API | +| 管理者またはサポートチームがユーザーのセッションを管理する | Management API | +| オペレーターが Logto Console で直接セッションを管理する | Admin Console | + +## アクティブなセッションを表示する \{#view-active-sessions} + +### Account API (セルフサービス) \{#account-api-self-service} + +Account API のセッションエンドポイントを使用して、現在のユーザーのアクティブなセッションを一覧表示します。 + +- 参照セクション: [ユーザーセッションの管理](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- エンドポイント: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +この機能をエンドユーザーに公開する前に、Account center 設定でセッション管理が有効になっていることと、アプリが必要な Account API スコープを要求していることを確認してください。 + +### Management API (管理ツール) \{#management-api-admin-tools} + +管理システムがターゲットユーザーのセッションを一覧表示する必要がある場合は、Management API を使用します。 + +- 参照セクション: [ユーザーセッション管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- エンドポイント: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- オプションの詳細エンドポイント: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## セッションを取り消す \{#revoke-sessions} + +### Account API (エンドユーザーが自分のセッションを取り消す) \{#account-api-end-user-revokes-own-sessions} + +エンドユーザーは、自分のセッションリストから特定のセッションを取り消すことができます。 + +- 参照セクション: [ユーザーセッションの管理](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- エンドポイント: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +機密性の高い操作の場合、Account API セッション管理はアクセス前にユーザーの確認を必要とします。詳細は [確認レコード ID を取得する](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id) を参照してください。 + +### Management API (管理者がユーザーセッションを取り消す) \{#management-api-admin-revokes-user-sessions} + +管理者は、ユーザー ID とセッション ID を使用してターゲットユーザーのセッションを取り消すことができます。 + +- 参照セクション: [ユーザーセッション管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- エンドポイント: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +チームが Logto Console で直接ユーザーを管理する場合、アクティブなセッションを確認し、ユーザー詳細ページから特定のセッションを取り消すことができます。 + +- 参照セクション: [ユーザーのアクティブセッションを管理する](/user-management/manage-users#manage-user-active-sessions) + +## 関連リソース \{#related-resources} + +セッション +ユーザー承認アプリ (グラント) の管理 + + Account API によるアカウント設定: ユーザーセッションの管理 + + + Management API によるアカウント設定: ユーザーセッション管理 + + + ユーザー管理: ユーザーのアクティブセッションを管理する + diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..f338288f601 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# セッション設定 + +セッション設定は、Logto のサインインセッションがどのくらいの期間アクティブであるか、またセッション関連のアクセスポリシーがどのように適用されるかをテナントレベルで制御します。 + +このページでは以下をカバーします： + +- セッション TTL 設定 +- アプリごとの最大同時認証デバイス数 + +## セッション TTL 設定 \{#session-ttl-configuration} + +セッション TTL は、Logto OIDC サインインセッションの最大存続期間を決定します。 +これは **テナントレベルの設定** であり、一度設定すると、そのテナント内のすべてのアプリと認証フローに適用されます。 + +### デフォルトの動作 \{#default-behavior} + +- デフォルトでは、セッション TTL は **14 日間** です。 +- カスタム TTL が設定されていない場合、Logto はこのデフォルト値を使用し続けます。 + +### Logto コンソールを介して設定 \{#configure-concurrent-device-limit-via-logto-console} + +コンソールでセッション TTL を設定するには、以下の場所で行います： + +Console > Tenant > Settings > OIDC settings + +**Session maximum time to live** を使用して値を更新します。 + +:::note + +コンソールでは入力と表示に **日** を使用しますが、基礎となる OIDC セッション設定 / API では **秒** を使用します。 + +::: + +### Management API を介して設定 \{#configure-via-management-api} + +OIDC セッション設定を読み取りおよび更新するには、次のエンドポイントを使用します： + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +例（`ttl` は秒単位）： + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` 秒 = 14 日間。 + +:::note + +OSS デプロイメントの場合、`logto-config` を変更した後にサービスインスタンスを再起動して、サーバーが最新の OIDC 設定を取得できるようにします。 + +サービスを再起動せずに OIDC 設定の更新を自動的に適用するには、[中央 Redis キャッシュを有効にする](/logto-oss/central-cache) を参照してください。 + +::: + +## アプリごとの最大同時認証デバイス数 \{#max-concurrent-authenticated-devices-per-app} + +アプリごとの最大同時認証デバイス数は、特定のアプリに対して各ユーザーが保持できるアクティブなグラントの数を制限するアプリレベルの制御です。 + +これは、アプリケーションの `customClientMetadata` の `maxAllowedGrants` フィールドを通じて設定されます。 +詳細は [アプリケーションデータ構造](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants) を参照してください。 + +### 動作 \{#behavior} + +`maxAllowedGrants` が設定されている場合、Logto は各成功した認可 (Authorization) の際に現在のアプリに対するユーザーのアクティブなグラントを評価します。 +アクティブなグラントの数が制限を超えると、Logto は最も古いグラントを最初に取り消します。 + +`maxAllowedGrants` が設定されていない場合、同時実行制限はありません。 + +### Logto コンソールを介して設定 \{#configure-via-logto-console} + +各アプリの詳細ページで以下の場所で設定できます： + + + Console > Applications > Application details > Concurrent device limit + + +現在のアプリに対して、ユーザーごとの同時アクティブグラント（デバイス）の最大数を設定します。 + +:::note + +この設定は、マシン間通信アプリ、保護されたアプリ、および SAML アプリには対応していません。 + +::: + +## 関連リソース \{#related-resources} + +セッション +ユーザーセッションの管理 +ユーザー認可アプリ (グラント) の管理 + + アプリケーションデータ構造: maxAllowedGrants + +Management API との対話 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index 828dc818970..f193302ac53 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -4,120 +4,135 @@ sidebar_position: 2 # ユーザー管理 -## Logto Console で管理する \{#manage-via-logto-console} +## Logto コンソールを介して管理 \{#manage-via-logto-console} ### ユーザーの閲覧と検索 \{#browse-and-search-users} -Logto Console でユーザー管理機能にアクセスするには、Console > ユーザー管理 に移動します。そこでは、すべてのユーザーのテーブルビューが表示されます。 +Logto コンソールでユーザー管理機能にアクセスするには、コンソール > ユーザー管理 に移動します。そこでは、すべてのユーザーのテーブルビューが表示されます。 -テーブルは 3 列で構成されています： +テーブルは次の 3 つの列で構成されています： -- **ユーザー**：ユーザーのアバター、氏名、ユーザー名、電話番号、メールアドレスなどの情報を表示します -- **アプリケーションから**：ユーザーが最初に登録したアプリケーション名を表示します -- **最新のサインイン**：ユーザーの最新サインインのタイムスタンプを表示します。 +- **ユーザー**：ユーザーのアバター、フルネーム、ユーザー名、電話番号、メールアドレスなどの情報を表示します。 +- **アプリケーションから**：ユーザーが最初に登録したアプリケーションの名前を表示します。 +- **最新のサインイン**：ユーザーの最新のサインインのタイムスタンプを表示します。 -[`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) のキーワードマッピングに対応しています。 +[`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) のキーワードマッピングをサポートしています。 ### ユーザーの追加 \{#add-users} -Console を使用して、開発者はエンドユーザーの新しいアカウントを作成できます。画面右上の「ユーザー追加」ボタンをクリックしてください。 +コンソールを使用して、開発者はエンドユーザーのために新しいアカウントを作成できます。画面の右上隅にある「ユーザーを追加」ボタンをクリックします。 -Logto Console または Management API でユーザーを作成する場合（UI からのエンドユーザー自己登録ではない）、少なくとも 1 つの識別子（`primary email`、`primary phone`、または `username`）を指定する必要があります。`name` フィールドは任意です。 +Logto コンソールまたは Management API を介してユーザーを作成する場合（UI を介してエンドユーザーが自己登録するのではなく）、少なくとも 1 つの識別子を提供する必要があります：`primary email`、`primary phone`、または `username`。`name` フィールドはオプションです。 -ユーザー作成後、Logto は自動的にランダムなパスワードを生成します。初期パスワードは一度だけ表示されますが、後で [パスワードをリセット](./manage-users#reset-user-password) できます。特定のパスワードを設定したい場合は、Management API の `patch /api/users/{userId}/password` を使ってユーザー作成後に更新してください。 +ユーザーが作成されると、Logto は自動的にランダムなパスワードを生成します。初期パスワードは一度だけ表示されますが、後で [パスワードをリセット](./manage-users#reset-user-password) できます。特定のパスワードを設定したい場合は、ユーザーが作成された後に Management API `patch /api/users/{userId}/password` を使用して更新します。 -**入力した識別子（メールアドレス / 電話番号 / ユーザー名）** と **初期パスワード** をワンクリックでコピーできるため、これらの認証情報を新しいユーザーと簡単に共有し、サインインして利用を開始できます。 +**入力された識別子（メールアドレス / 電話番号 / ユーザー名）** と **初期パスワード** をワンクリックでコピーでき、新しいユーザーにこれらの資格情報を簡単に共有してサインインしてもらうことができます。 :::tip -招待制登録を実装したい場合は、[マジックリンクでユーザーを招待](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended) する方法を推奨します。これにより、ホワイトリストに登録されたユーザーのみが自己登録し、自分でパスワードを設定できます。 +招待制の登録を実装したい場合は、[マジックリンクでユーザーを招待する](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended) ことをお勧めします。これにより、ホワイトリストに登録されたユーザーのみが自己登録し、自分のパスワードを設定できます。 ::: -### ユーザープロフィールの閲覧と更新 \{#view-and-update-the-user-profile} +### ユーザープロフィールの表示と更新 \{#view-and-update-the-user-profile} -ユーザーの詳細を表示するには、ユーザーテーブルの該当行をクリックしてください。「**ユーザー詳細**」ページに移動し、ユーザープロフィール情報を確認できます。内容は以下の通りです： +ユーザーの詳細を表示するには、ユーザーテーブルの対応する行をクリックするだけです。これにより、ユーザーのプロフィール情報を含む「**ユーザー詳細**」ページに移動します： - **認証 (Authentication) 関連データ**： - - **メールアドレス**（[primary_email](/user-management/user-data#primary_email)）：編集可能 - - **電話番号**（[primary_phone](/user-management/user-data#primary_phone)）：編集可能 - - **ユーザー名**（[username](/user-management/user-data#username)）：編集可能 - - **パスワード**（[has_password](/user-management/user-data#has_password)）：ランダムパスワードを再生成できます。「[ユーザーパスワードのリセット](#reset-user-password)」を参照してください。 - - **多要素認証 (MFA)**（[mfa_verification_factor](/user-management/user-data#mfa_verification_factors)）：このユーザーが設定したすべての認証要素（パスキー、認証アプリ、バックアップコードなど）を表示できます。要素は Console で削除可能です。 - - **パスキー**：テナントで [パスキーサインイン](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) が有効な場合、ユーザー詳細ページでサインイン用パスキーを表示・削除できます。これらのパスキーは MFA と同じ WebAuthn 資格情報モデルで管理されます。 - - **パーソナルアクセストークン**：[パーソナルアクセストークン](/user-management/personal-access-token) の作成、表示、名前変更、削除ができます。 + - **メールアドレス** ([primary_email](/user-management/user-data#primary_email))：編集可能 + - **電話番号** ([primary_phone](/user-management/user-data#primary_phone))：編集可能 + - **ユーザー名** ([username](/user-management/user-data#username))：編集可能 + - **パスワード** ([has_password](/user-management/user-data#has_password))：ランダムなパスワードを再生成できます。「[ユーザーパスワードのリセット](#reset-user-password)」について詳しく学びます。 + - **多要素認証 (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors))：このユーザーが設定したすべての認証要素（例：パスキー、認証アプリ、バックアップコード）を表示します。要素はコンソールで削除できます。 + - **パスキー**：テナントで [パスキーサインイン](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) が有効になっている場合、ユーザーのサインインパスキーをユーザー詳細ページで表示し、必要に応じて削除できます。これらのパスキーは、MFA で使用されるのと同じ WebAuthn 資格情報モデルによってサポートされています。 + - **個人用アクセストークン**：[個人用アクセストークン](/user-management/personal-access-token) を作成、表示、名前変更、削除します。 - **接続**： - - **ソーシャル接続**（[identities](/user-management/user-data#social-identities)）： - - ユーザーが連携したソーシャルアカウント（ソーシャル ID やプロバイダから同期されたプロフィール情報）を表示できます（例：Facebook でサインインした場合は「Facebook」エントリが表示されます）。 - - 既存のソーシャル ID は削除できますが、ユーザーの代わりに新しいソーシャルアカウントを連携することはできません。 - - [トークン保存](/secret-vault/federated-token-set) が有効なソーシャルコネクターの場合、接続詳細ページでアクセス トークン (Access token) やリフレッシュ トークン (Refresh token) を表示・管理できます。 - - **エンタープライズ SSO 接続**（[sso_identities](/user-management/user-data#sso-identities)）： - - ユーザーが連携したエンタープライズ ID やプロバイダから同期されたプロフィール情報を表示できます。 - - Console でエンタープライズ SSO ID の追加・削除はできません。 - - OIDC ベースのエンタープライズコネクターで [トークン保存](/secret-vault/federated-token-set) が有効な場合、接続詳細ページでトークンの表示・削除ができます。 -- **ユーザープロフィールデータ**：名前、アバター URL、カスタムデータ、その他 OpenID Connect 標準クレーム（未含分）。これらのプロフィール項目はすべて編集可能です。 -- **セッション**：ユーザーのアクティブセッション一覧を表示します。デバイス情報、sessionId、GEO ロケーション（該当する場合）も確認できます。セッションの詳細を表示したり、セッション詳細ページでセッションを取り消すことも可能です。 + - **ソーシャル接続** ([identities](/user-management/user-data#social-identities))： + - ユーザーのリンクされたソーシャルアカウントを表示し、ソーシャルプロバイダーから同期されたソーシャル ID とプロフィール詳細を表示します（例：ユーザーが Facebook 経由でサインインした場合、「Facebook」エントリが表示されます）。 + - 既存のソーシャルアイデンティティを削除できますが、ユーザーの代わりに新しいソーシャルアカウントをリンクすることはできません。 + - [トークンストレージ](/secret-vault/federated-token-set) が有効になっているソーシャルコネクターの場合、接続詳細ページでアクセストークンとリフレッシュトークンを表示および管理できます。 + - **エンタープライズ SSO 接続** ([sso_identities](/user-management/user-data#sso-identities))： + - ユーザーのリンクされたエンタープライズアイデンティティを表示し、エンタープライズ ID とエンタープライズアイデンティティプロバイダーから同期されたプロフィール詳細を表示します。 + - コンソールでエンタープライズ SSO アイデンティティを追加または削除することはできません。 + - [トークンストレージ](/secret-vault/federated-token-set) が有効になっている OIDC ベースのエンタープライズコネクターの場合、接続詳細ページでトークンを表示および削除できます。 +- **ユーザープロフィールデータ**：名前、アバター URL、カスタムデータ、および含まれていない追加の OpenID Connect 標準クレーム。これらのプロフィールフィールドはすべて編集可能です。 +- **セッション**：デバイス情報、sessionId、および GEO ロケーション（該当する場合）を含むユーザーのアクティブセッションのリストを表示します。セッションの詳細ページでセッションの詳細を表示し、取り消すことができます。 :::warning -ソーシャル接続を削除する前に、他のサインイン方法（別のソーシャル接続、電話番号、メールアドレス、ユーザー名＋パスワードなど）があることを必ず確認してください。他のサインイン方法がない場合、ソーシャル接続を削除するとアカウントに再度アクセスできなくなります。 +ソーシャル接続を削除する前に、ユーザーが別のソーシャル接続、電話番号、メール、またはユーザー名とパスワードなどの代替サインイン方法を持っていることを確認することが重要です。ユーザーが他のサインイン方法を持っていない場合、ソーシャル接続が削除されるとアカウントに再度アクセスできなくなります。 ::: -### ユーザーアクティビティの閲覧 \{#view-user-activities} +### ユーザーアクティビティの表示 \{#view-user-activities} -ユーザーの最近のアクティビティを確認するには、「ユーザー詳細」ページの「ユーザーログ」サブタブに移動します。ここでは、ユーザーが行った操作、結果、関連アプリケーション、操作時刻などがテーブルで表示されます。 +ユーザーの最近のアクティビティを表示するには、「ユーザー詳細」ページの「ユーザーログ」サブタブに移動します。ここでは、ユーザーの最近のアクティビティを表示するテーブルがあり、実行されたアクション、アクションの結果、関連するアプリケーション、およびユーザーが行動した時間が含まれています。 -テーブル行をクリックすると、ユーザーログの詳細（IP アドレス、ユーザーエージェント、生データなど）を確認できます。 +テーブル行をクリックして、ユーザーログの詳細を確認します。例：IP アドレス、ユーザーエージェント、生データなど。 ### ユーザーの一時停止 \{#suspend-user} -「ユーザー詳細」ページで「三点リーダー」→「ユーザーを一時停止」ボタンをクリックします。 +「ユーザー詳細」ページで、「三点リーダー」->「ユーザーの一時停止」ボタンをクリックします。 -ユーザーが一時停止されると、アプリにサインインできなくなり、現在のアクセス トークン (Access token) の有効期限が切れた後は新しいトークンを取得できません。また、このユーザーによる API リクエストも失敗します。 +ユーザーが一時停止されると、そのユーザーはアプリにサインインできなくなり、現在のアクセス トークンが期限切れになった後に新しいアクセス トークンを取得することもできなくなります。さらに、このユーザーによって行われた API リクエストはすべて失敗します。 -このユーザーを再度有効化したい場合は、「三点リーダー」→「ユーザーを再有効化」ボタンをクリックしてください。 +このユーザーを再アクティブ化したい場合は、「三点リーダー」->「ユーザーの再アクティブ化」ボタンをクリックすることで可能です。 ### ユーザーの削除 \{#delete-user} -「ユーザー詳細」ページで「三点リーダー」→「削除」ボタンをクリックします。ユーザーの削除は元に戻せません。 +「ユーザー詳細」ページで、「三点リーダー」->「削除」ボタンをクリックします。ユーザーの削除は元に戻せません。 ### ユーザーパスワードのリセット \{#reset-user-password} -「ユーザー詳細」ページで「三点リーダー」→「パスワードをリセット」ボタンをクリックすると、Logto が自動的にランダムなパスワードを再生成します。 +「ユーザー詳細」ページで、「三点リーダー」->「パスワードのリセット」ボタンをクリックすると、Logto が自動的にランダムなパスワードを再生成します。 -パスワードをリセットした後、エンドユーザーにコピーして送信してください。「パスワードリセット」モーダルを閉じるとパスワードは再表示できません。控え忘れた場合は再度リセットできます。 +パスワードをリセットした後、コピーしてエンドユーザーに送信します。「パスワードのリセット」モーダルが閉じられると、パスワードを表示することはできなくなります。保持するのを忘れた場合は、再度リセットできます。 -Logto Console でユーザーの特定パスワードを設定することはできませんが、[Management API](/integrate-logto/interact-with-management-api) の `PATCH /api/users/{userId}/password` を使って指定できます。 +Logto コンソールでユーザーに特定のパスワードを設定することはできませんが、[Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` を使用してパスワードを指定できます。 -### ユーザーのアクティブセッション管理 \{#manage-user-active-sessions} +### ユーザーのアクティブセッションの管理 \{#manage-user-active-sessions} -「ユーザー詳細」ページで、特定セッションの「管理」ボタンをクリックして「セッション詳細」ページに移動します。ここでは、デバイス、場所、ログイン時刻などセッションの詳細情報を確認できます。このセッションからユーザーをログアウトさせたい場合は、右上の「セッションを取り消す」ボタンをクリックすると、即座にセッションが取り消されます。 +「ユーザー詳細」ページで、特定のセッションの「管理」ボタンをクリックして「セッション詳細」ページに移動します。ここでは、デバイス、場所、ログイン時間など、セッションの詳細情報を表示できます。このセッションからユーザーをログアウトさせたい場合は、右上隅の「セッションの取り消し」ボタンをクリックするだけで、セッションが即座に取り消されます。 -- デフォルトでは、Console でセッションを取り消すと、そのセッションに関連するすべてのファーストパーティアプリのグラントも取り消され、ユーザーは再度サインインが必要になります。事前発行された不透明トークン (Opaque token) やリフレッシュ トークン (Refresh token) も即時取り消されます。 -- `offline_access` スコープを持つサードパーティアプリの場合、セッションの取り消しはデフォルトでアプリグラントを取り消しません。事前発行されたリフレッシュ トークン (Refresh token) はグラントの有効期限まで利用可能です。 +- デフォルトでは、コンソールでセッションを取り消すと、そのセッションに関連付けられたすべてのファーストパーティアプリの許可も取り消され、ユーザーはアクセスを復元するために再度サインインする必要があります。ファーストパーティアプリに事前に発行された不透明トークンとリフレッシュトークンも即座に取り消されます。 +- `offline_access` スコープを持つサードパーティアプリの場合、セッションを取り消してもデフォルトではアプリの許可は取り消されず、事前に発行されたリフレッシュトークンは許可が期限切れになるまで使用できます。 + +### ユーザーが認可したサードパーティアプリの管理 \{#manage-user-authorized-third-party-apps} + +「ユーザー詳細」ページで、「認可されたサードパーティアプリ」セクションを使用して、ユーザーのアプリ認可ステータスを確認できます。 +このセクションは、ユーザーが認可したアプリ（許可）の管理 API によってサポートされています。 + +各認可されたアプリについて、コンソールは次の情報を表示します： + +- アプリ名 +- アプリ ID +- アクセス作成時間 + +アクセスを削除する必要がある場合は、取り消しアクションをクリックし、モーダルで確認します。 + +アプリの認可を取り消すと、そのアプリに関連付けられたすべてのアクティブなサードパーティの許可がユーザーに対して削除されます。また、そのアプリに対して事前に発行された不透明トークンとリフレッシュトークンも即座に取り消されます。 ## パスワードコンプライアンスチェック \{#password-compliance-check} -Logto で [パスワードポリシー](/security/password-policy) を更新した後も、既存ユーザーは現在のパスワードでサインインできます。新規作成アカウントのみが更新後のパスワードポリシーに従う必要があります。 +Logto で [パスワードポリシー](/security/password-policy) を更新した後、既存のユーザーは現在のパスワードでサインインを続けることができます。新しく作成されたアカウントのみが更新されたパスワードポリシーに従う必要があります。 -より強力なセキュリティを強制するには、`POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) を使って、ユーザーのパスワードがデフォルトサインイン体験で定義された現在のポリシーに準拠しているか確認できます。準拠していない場合は、[Account API](/end-user-flows/account-settings/by-management-api#user-password-management) を使ったカスタムフローでパスワード更新を促すことができます。 +より強力なセキュリティを強制するために、`POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) を使用して、ユーザーのパスワードがデフォルトのサインイン体験で定義された現在のポリシーを満たしているかどうかを確認できます。満たしていない場合は、[Account API](/end-user-flows/account-settings/by-management-api#user-password-management) を使用してカスタムフローでユーザーにパスワードの更新を促すことができます。 -### ユーザーのロール管理 \{#manage-roles-of-users} +### ユーザーのロールの管理 \{#manage-roles-of-users} -ユーザー詳細ページの「ロール」タブで、ロールの割り当てや削除が簡単にできます。詳細は [ロールベースのアクセス制御 (RBAC)](/authorization/role-based-access-control) を参照してください。 +ユーザー詳細ページの「ロール」タブで、目的に応じてロールを簡単に割り当てたり削除したりできます。詳細については、[ロールベースのアクセス制御](/authorization/role-based-access-control) を確認してください。 -### ユーザーが所属する組織の確認 \{#view-the-organizations-the-user-belongs-to} +### ユーザーが所属する組織の表示 \{#view-the-organizations-the-user-belongs-to} -Logto は [組織](/organizations/organization-management) をサポートしており、そのメンバー管理が可能です。ユーザー詳細を簡単に確認し、どの組織に所属しているかを把握できます。 +Logto は [組織](/organizations/organization-management) をサポートしており、そのメンバーを管理できます。ユーザーの詳細を簡単に表示し、どの組織に属しているかを確認できます。 -## Logto Management API で管理する \{#manage-via-logto-management-api} +## Logto Management API を介して管理 \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) は、Logto バックエンドサービスへのアクセスを提供する API 群です。前述の通り、ユーザー API はこのサービスの重要なコンポーネントであり、幅広いシナリオに対応できます。 +[Management API](/concepts/core-service/#management-api) は、Logto バックエンドサービスへのアクセスを提供する API のコレクションです。前述のように、ユーザー API はこのサービスの重要なコンポーネントであり、さまざまなシナリオをサポートできます。 -ユーザー関連の [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API は `/api/users` にマウントされています（ユーザーアクティビティ、すなわちユーザーログ `/api/logs?userId=:userId` を除く）。 +ユーザー関連の [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API は、ユーザーアクティビティ、つまりユーザーログ `/api/logs?userId=:userId` を除いて、`/api/users` にマウントされています。 -Management API を通じて、[高度なユーザー検索](/user-management/advanced-user-search)、[一括アカウント作成](https://openapi.logto.io/operation/operation-createuser)、[招待制サインアップ](/end-user-flows/sign-up-and-sign-in/disable-user-registration) など、さまざまな用途でユーザー管理が可能です。 +Management API を通じて、いくつかのユースケースでユーザーを管理できます。例えば、[高度なユーザー検索](/user-management/advanced-user-search)、[一括アカウント作成](https://openapi.logto.io/operation/operation-createuser)、[招待制サインアップ](/end-user-flows/sign-up-and-sign-in/disable-user-registration) などです。 ## よくある質問 \{#faqs} @@ -125,12 +140,12 @@ Management API を通じて、[高度なユーザー検索](/user-management/adv -### 特定ユーザーの特定アプリケーションへのアクセスを制限するには？ \{#how-to-restrict-access-to-certain-application-for-specific-users} +### 特定のユーザーに対して特定のアプリケーションへのアクセスを制限する方法は？ \{#how-to-restrict-access-to-certain-application-for-specific-users} -Logto の [Omni-sign-in](https://logto.io/products/omni-sign-in) の特性上、認証 (Authentication) 前に特定アプリケーションへのユーザーアクセスを制限する設計にはなっていません。 -ただし、アプリケーション固有のユーザーロールや権限を設計し、API リソースを保護することは可能です。ユーザーのサインイン成功後に API アクセス時に権限を検証してください。 -詳細は認可 (Authorization)：[ロールベースのアクセス制御 (RBAC)](/authorization/role-based-access-control) を参照してください。 +Logto の [Omni-sign-in](https://logto.io/products/omni-sign-in) の性質上、認証前に特定のアプリケーションへのユーザーアクセスを制限するようには設計されていません。 +ただし、アプリケーション固有のユーザーロールと権限を設計して API リソースを保護し、ユーザーのサインインが成功した後に API アクセス時に権限を検証することは可能です。 +詳細については、認可 (Authorization)：[ロールベースのアクセス制御](/authorization/role-based-access-control) を参照してください。 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index b4f6c1157e1..3d624e1dc15 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,50 +7,50 @@ sidebar_position: 5 # 서명 키 -Logto [OIDC 서명 키](https://auth.wiki/signing-key)는 "OIDC 개인 키" 및 "OIDC 쿠키 키"라고도 하며, Logto의 [로그인 세션](/end-user-flows/sign-out#what-is-a-logto-session)에서 JWT([액세스 토큰](https://auth.wiki/access-token) 및 [ID 토큰](https://auth.wiki/id-token))과 브라우저 쿠키를 서명하는 데 사용되는 서명 키입니다. 이러한 서명 키는 Logto 데이터베이스를 시드할 때([오픈 소스](/logto-oss)) 또는 새 테넌트를 생성할 때([Cloud](/logto-cloud)) 생성되며, [CLI](/logto-oss/using-cli) (오픈 소스), Management API 또는 Console UI를 통해 관리할 수 있습니다. +Logto [OIDC 서명 키](https://auth.wiki/signing-key), "OIDC 개인 키" 및 "OIDC 쿠키 키"로도 알려진 이 키들은 Logto [로그인 세션](/sessions#what-is-a-logto-session)에서 JWT ([액세스 토큰](https://auth.wiki/access-token) 및 [ID 토큰](https://auth.wiki/id-token))과 브라우저 쿠키를 서명하는 데 사용됩니다. 이러한 서명 키는 Logto 데이터베이스를 시딩할 때 ([오픈 소스](/logto-oss)) 또는 새 테넌트를 생성할 때 ([Cloud](/logto-cloud)) 생성되며, [CLI](/logto-oss/using-cli) (오픈 소스), Management API 또는 Console UI를 통해 관리할 수 있습니다. -기본적으로 Logto는 타원 곡선(EC) 알고리즘을 사용하여 디지털 서명을 생성합니다. 하지만 사용자가 JWT 서명을 검증해야 하는 경우가 많고, 많은 구형 도구들이 EC 알고리즘을 지원하지 않고 RSA만 지원하기 때문에, 개인 키를 교체(로테이션)하고 서명 알고리즘(RSA와 EC 모두 포함)을 선택할 수 있는 기능을 구현했습니다. 이를 통해 구식 서명 검증 도구를 사용하는 서비스와의 호환성을 보장합니다. +기본적으로 Logto는 타원 곡선 (EC) 알고리즘을 사용하여 디지털 서명을 생성합니다. 그러나 사용자가 종종 JWT 서명을 검증해야 하고 많은 오래된 도구가 EC 알고리즘을 지원하지 않기 때문에 (RSA만 지원), 개인 키를 회전하고 사용자가 서명 알고리즘 (RSA 및 EC 모두 포함)을 선택할 수 있는 기능을 구현했습니다. 이는 구식 서명 검증 도구를 사용하는 서비스와의 호환성을 보장합니다. :::note -이론적으로 서명 키는 유출되어서는 안 되며 만료 시간이 없으므로 교체할 필요가 없습니다. 그러나 일정 기간 후에 주기적으로 서명 키를 교체하면 보안을 강화할 수 있습니다. +이론적으로 서명 키는 유출되지 않아야 하며 만료 시간이 없으므로 회전할 필요가 없습니다. 그러나 일정 기간 후에 서명 키를 주기적으로 회전하면 보안을 강화할 수 있습니다. ::: -## 동작 방식은? \{#how-it-works} +## 어떻게 작동하나요? \{#how-it-works} - **OIDC 개인 키** - Logto 인스턴스를 초기화할 때, 공개 키와 개인 키 쌍이 자동으로 생성되어 기본 OIDC 제공자에 등록됩니다. 따라서 Logto가 새로운 JWT(액세스 토큰 또는 ID 토큰)를 발급할 때, 해당 토큰은 개인 키로 서명됩니다. 동시에 JWT를 수신하는 모든 클라이언트 애플리케이션은 쌍으로 제공되는 공개 키를 사용하여 토큰 서명을 검증할 수 있으므로, 토큰이 제3자에 의해 변조되지 않았음을 보장할 수 있습니다. 개인 키는 Logto 서버에서 안전하게 보호됩니다. 반면, 공개 키는 이름 그대로 모두에게 공개되어 있으며, OIDC 엔드포인트의 `/oidc/jwks` 인터페이스를 통해 접근할 수 있습니다. 개인 키를 생성할 때 서명 키 알고리즘을 지정할 수 있으며, Logto는 기본적으로 EC(타원 곡선) 알고리즘을 사용합니다. 관리자는 개인 키를 교체(로테이션)하여 기본 알고리즘을 RSA(Rivest-Shamir-Adleman)로 변경할 수 있습니다. + Logto 인스턴스를 초기화할 때, 공개 키와 개인 키 쌍이 자동으로 생성되고 기본 OIDC 제공자에 등록됩니다. 따라서 Logto가 새로운 JWT (액세스 토큰 또는 ID 토큰)를 발급할 때, 토큰은 개인 키로 서명됩니다. 동시에 JWT를 수신하는 모든 클라이언트 애플리케이션은 쌍으로 된 공개 키를 사용하여 토큰 서명을 검증할 수 있으며, 이를 통해 제3자가 토큰을 변조하지 않았음을 보장할 수 있습니다. 개인 키는 Logto 서버에서 보호됩니다. 그러나 공개 키는 이름에서 알 수 있듯이 모든 사람에게 공개되며, OIDC 엔드포인트의 `/oidc/jwks` 인터페이스를 통해 접근할 수 있습니다. 서명 키 알고리즘은 개인 키를 생성할 때 지정할 수 있으며, Logto는 기본적으로 EC (타원 곡선) 알고리즘을 사용합니다. 관리자 사용자는 개인 키를 회전하여 기본 알고리즘을 RSA (Rivest-Shamir-Adleman)로 변경할 수 있습니다. - **OIDC 쿠키 키** - 사용자가 로그인 또는 회원가입 플로우를 시작하면, 서버에서 "OIDC 세션"이 생성되고 브라우저 쿠키 세트도 함께 생성됩니다. 이 쿠키를 통해 브라우저는 Logto Experience API에 요청하여 로그인, 회원가입, 비밀번호 재설정 등 일련의 상호작용을 사용자를 대신하여 수행할 수 있습니다. 하지만 JWT와 달리, 쿠키는 Logto OIDC 서비스 자체에서만 서명 및 검증되며, 비대칭 암호화가 필요하지 않습니다. 따라서 쿠키 서명 키에는 쌍으로 된 공개 키가 없으며, 비대칭 암호화 알고리즘도 사용하지 않습니다. + 사용자가 로그인 또는 회원가입 흐름을 시작할 때, 서버에 "OIDC 세션"이 생성되며, 브라우저 쿠키 세트도 생성됩니다. 이러한 쿠키를 통해 브라우저는 Logto Experience API에 요청하여 사용자를 대신하여 로그인, 회원가입, 비밀번호 재설정 등의 일련의 상호작용을 수행할 수 있습니다. 그러나 JWT와 달리 쿠키는 Logto OIDC 서비스 자체에 의해 서명되고 검증되며, 비대칭 암호화 조치가 필요하지 않습니다. 따라서 쿠키 서명 키에 대한 쌍으로 된 공개 키가 없으며, 비대칭 암호화 알고리즘도 필요하지 않습니다. -## Console UI에서 서명 키 교체하기 \{#rotate-signing-keys-from-console-ui} +## Console UI에서 서명 키 회전하기 \{#rotate-signing-keys-from-console-ui} -Logto는 "서명 키 교체" 기능을 도입하여, 테넌트 내에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있습니다. +Logto는 "서명 키 회전" 기능을 도입하여 테넌트에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있습니다. -1. Console > 서명 키로 이동하세요. 여기서 +1. Console > 테넌트 설정 > OIDC 구성로 이동하세요. 여기서 OIDC 개인 키와 OIDC 쿠키 키를 모두 관리할 수 있습니다. 2. 서명 키를 교체하려면 "개인 키 교체" 또는 "쿠키 키 교체" 버튼을 클릭하세요. 개인 키를 교체할 때는 서명 알고리즘을 변경할 수도 있습니다. 3. 사용 중인 모든 서명 키가 나열된 테이블을 확인할 수 있습니다. 참고: 이전 키는 삭제할 수 있지만, 현재 사용 중인 키는 삭제할 수 없습니다. | 상태 | 설명 | | ---- | ---------------------------------------------------------------------------------------------- | - | 현재 | 이 키가 현재 애플리케이션 및 API에서 사용 중임을 나타냅니다. | - | 이전 | 이전에 사용되었으나 교체된 키를 의미합니다. 이 서명 키로 서명된 기존 토큰은 여전히 유효합니다. | + | 현재 | 이 키가 현재 애플리케이션 및 API에서 활성 사용 중임을 나타냅니다. | + | 이전 | 이전에 사용되었지만 회전된 키를 나타냅니다. 이 서명 키로 발급된 기존 토큰은 여전히 유효합니다. | -교체(로테이션)는 다음 세 가지 작업을 포함함을 기억하세요: +회전은 다음 세 가지 작업을 포함한다는 점을 기억하세요: -1. **새 서명 키 생성**: 모든 **애플리케이션** 및 **API**가 새 서명 키를 사용해야 합니다. -2. **현재 키 교체**: 기존 키는 교체 후 "이전"으로 지정되며, 새로 생성되는 애플리케이션 및 API에서는 사용되지 않습니다. 그러나 이 키로 서명된 토큰은 여전히 유효합니다. -3. **이전 키 제거**: "이전"으로 표시된 키는 폐기되어 테이블에서 제거됩니다. +1. **새로운 서명 키 생성**: 이는 모든 **애플리케이션**과 **API**가 새로운 서명 키를 채택해야 함을 요구합니다. +2. **현재 키 회전**: 기존 키는 회전 후 "이전"으로 지정되며, 새로 생성된 애플리케이션 및 API에서는 사용되지 않습니다. 그러나 이 키로 서명된 토큰은 여전히 유효합니다. +3. **이전 키 제거**: "이전"으로 표시된 키는 취소되고 테이블에서 제거됩니다. :::warning -서명 키를 연속적으로(두 번 이상) 교체하지 마세요. 이는 발급된 모든 토큰을 무효화할 수 있습니다. +서명 키를 연속적으로 (두 번 이상) 회전하지 마세요. 이는 발급된 모든 토큰을 무효화할 수 있습니다. -- OSS 사용자는 서명 키 교체 후, 새로운 서명 키가 적용되도록 Logto 인스턴스를 재시작해야 합니다. -- Cloud 사용자는 교체 즉시 새로운 서명 키가 적용되지만, 서명 키를 연속적으로 여러 번 교체하지 않도록 주의하세요. +- OSS 사용자의 경우, 서명 키를 회전한 후 Logto 인스턴스를 재시작해야 새로운 서명 키가 적용됩니다. +- Cloud 사용자의 경우, 회전 후 새로운 서명 키가 즉시 적용되지만, 서명 키를 연속적으로 여러 번 회전하지 않도록 주의하세요. ::: ## 관련 리소스 \{#related-resources} - + JWT에서 EC 및 RSA 서명 알고리즘 소개 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 1389dc998ee..618b08d4333 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,81 +1,83 @@ --- -description: Account API를 사용하여 사용자를 관리하는 방법을 알아보세요 +description: 사용자 관리를 위한 Account API 사용 방법을 알아보세요 sidebar_position: 1 --- -# Account API로 계정 설정하기 +# Account API에 의한 계정 설정 -## Logto Account API란? \{#what-is-logto-account-api} +## Logto Account API란 무엇인가요 \{#what-is-logto-account-api} -Logto Account API는 최종 사용자가 Management API를 거치지 않고 직접 API에 접근할 수 있도록 하는 포괄적인 API 세트입니다. 주요 특징은 다음과 같습니다: +Logto Account API는 최종 사용자가 Management API를 거치지 않고 직접 API에 접근할 수 있는 포괄적인 API 세트입니다. 주요 특징은 다음과 같습니다: -- 직접 접근: Account API는 최종 사용자가 Management API를 거치지 않고 자신의 계정 프로필에 직접 접근하고 관리할 수 있도록 합니다. -- 사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호와 같은 아이덴티티 정보 업데이트 및 소셜 연결 관리 등 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원은 곧 제공될 예정입니다. -- 글로벌 접근 제어: 관리자는 접근 설정을 전역적으로 완전히 제어할 수 있으며, 각 필드를 맞춤 설정할 수 있습니다. -- 원활한 인가 (Authorization): 인가 (Authorization)가 그 어느 때보다 쉬워졌습니다! `client.getAccessToken()`을 사용하여 OP (Logto)용 불투명 토큰 (Opaque token)을 얻고, 이를 Authorization 헤더에 `Bearer ` 형식으로 첨부하세요. +- 직접 접근: Account API는 최종 사용자가 자신의 계정 프로필을 직접 접근하고 관리할 수 있도록 하며, Management API의 중계를 필요로 하지 않습니다. +- 사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호와 같은 아이덴티티 정보를 업데이트하고 소셜 연결을 관리할 수 있는 기능을 포함하여 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원은 곧 제공될 예정입니다. +- 글로벌 접근 제어: 관리자는 접근 설정을 완전히 제어할 수 있으며 각 필드를 사용자 정의할 수 있습니다. +- 원활한 인가: 인가가 그 어느 때보다 쉬워졌습니다! `client.getAccessToken()`을 사용하여 OP (Logto)에 대한 불투명 액세스 토큰을 얻고, 이를 `Bearer ` 형식으로 Authorization 헤더에 첨부하세요. Logto Account API를 사용하면 Logto와 완전히 통합된 프로필 페이지와 같은 맞춤형 계정 관리 시스템을 구축할 수 있습니다. -자주 사용되는 사례는 다음과 같습니다: +다음은 자주 사용되는 사례입니다: - 사용자 프로필 조회 - 사용자 프로필 업데이트 - 사용자 비밀번호 업데이트 -- 이메일, 전화번호, 소셜 연결 등 사용자 아이덴티티 업데이트 -- MFA 요소(인증) 관리 +- 이메일, 전화번호 및 소셜 연결을 포함한 사용자 아이덴티티 업데이트 +- MFA 요소 (인증) 관리 - 사용자 세션 관리 +- 사용자 승인 앱 (권한) 관리 -사용 가능한 API에 대해 더 알아보려면 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 및 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) 를 방문하세요. +사용 가능한 API에 대해 더 알고 싶다면 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 및 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications)를 방문하세요. :::note -SSO 계정 조회 및 계정 삭제 기능은 현재 Logto Management API를 통해 제공됩니다. 구현 세부 사항은 [Management API로 계정 설정하기](/end-user-flows/account-settings/by-management-api)를 참고하세요. +SSO 계정 보기 및 계정 삭제 기능은 현재 Logto Management API를 통해 제공됩니다. 구현 세부 사항은 [Management API에 의한 계정 설정](/end-user-flows/account-settings/by-management-api)을 참조하세요. ::: ## Account API 활성화 방법 \{#how-to-enable-account-api} -콘솔 > 로그인 & 계정 > 계정 센터로 +콘솔 > 로그인 및 계정 > 계정 센터로 이동하세요. -Account API는 기본적으로 비활성화되어 있으므로 접근 제어가 잠겨 있습니다. **Account API 활성화**를 토글하여 켜세요. +Account API는 기본적으로 꺼져 있으며, 접근 제어가 잠겨 있습니다. **Account API 활성화**를 토글하여 켜세요. -활성화 후, 식별자, 프로필 데이터, 서드파티 토큰 접근에 대해 필드별 권한을 설정할 수 있습니다. 각 필드는 `Off`, `ReadOnly`, `Edit` 중 하나를 지원하며, 기본값은 `Off`입니다. +활성화되면 식별자, 프로필 데이터 및 타사 토큰 접근에 대한 필드별 권한을 구성하세요. 각 필드는 `Off`, `ReadOnly`, 또는 `Edit`을 지원하며, 기본값은 `Off`입니다. 1. **보안 필드**: - - 필드: 기본 이메일, 기본 전화번호, 소셜 아이덴티티, 비밀번호, MFA. - - 최종 사용자가 이 필드를 수정하기 전에, 비밀번호, 이메일 또는 SMS를 통해 본인 인증을 거쳐 10분 유효의 인증 기록 ID를 받아야 합니다. [인증 기록 ID 받기](#get-a-verification-record-id)를 참고하세요. - - MFA용 WebAuthn 패스키를 사용하려면, 프론트엔드 앱 도메인을 **WebAuthn 관련 Origin**에 추가하여 계정 센터와 로그인 경험이 패스키를 공유할 수 있도록 하세요. [새 WebAuthn 패스키 연결](#link-a-new-webauthn-passkey)을 참고하세요. + - 필드에는 기본 이메일, 기본 전화번호, 소셜 아이덴티티, 비밀번호 및 MFA가 포함됩니다. + - 최종 사용자가 이러한 필드를 편집하기 전에, 비밀번호, 이메일 또는 SMS를 통해 자신의 아이덴티티를 확인하여 10분 동안 유효한 인증 기록 ID를 얻어야 합니다. [인증 기록 ID 얻기](#get-a-verification-record-id)를 참조하세요. + - MFA를 위한 WebAuthn 패스키를 사용하려면, 계정 센터와 로그인 경험이 패스키를 공유할 수 있도록 **WebAuthn 관련 출처**에 프론트엔드 앱 도메인을 추가하세요. [새 WebAuthn 패스키 연결](#link-a-new-webauthn-passkey)을 참조하세요. 2. **프로필 필드**: - - 필드: 사용자명, 이름, 아바타, [프로필](/user-management/user-data#profile) (기타 표준 프로필 속성), [커스텀 데이터](/user-management/user-data#custom-data). - - 최종 사용자는 추가 인증 없이 이 필드를 수정할 수 있습니다. -3. **시크릿 볼트**: - - OIDC 또는 OAuth 소셜 및 엔터프라이즈 커넥터의 경우, Logto [시크릿 볼트](/secret-vault/federated-token-set)는 인증 후 서드파티 액세스 및 리프레시 토큰을 안전하게 저장합니다. 앱은 사용자가 다시 로그인하지 않아도 외부 API(예: Google Calendar 동기화 등)를 호출할 수 있습니다. Account API가 활성화되면 토큰 조회가 자동으로 가능해집니다. + - 필드에는 사용자 이름, 이름, 아바타, [프로필](/user-management/user-data#profile) (기타 표준 프로필 속성) 및 [사용자 정의 데이터](/user-management/user-data#custom-data)가 포함됩니다. + - 최종 사용자는 추가 인증 없이 이를 편집할 수 있습니다. +3. **비밀 금고**: + - OIDC 또는 OAuth 소셜 및 엔터프라이즈 커넥터의 경우, Logto [비밀 금고](/secret-vault/federated-token-set)는 인증 후 타사 액세스 및 리프레시 토큰을 안전하게 저장합니다. 앱은 사용자가 다시 로그인하지 않고도 Google 캘린더 이벤트 동기화와 같은 외부 API를 호출할 수 있습니다. Account API가 활성화되면 토큰 검색이 자동으로 가능합니다. 4. **세션 관리**: - - 활성화 시, 사용자는 자신의 활성 세션(디바이스 정보, 마지막 로그인 시간 포함)을 조회 및 관리할 수 있습니다. 특정 디바이스에서 로그아웃하려면 세션을 해제할 수도 있습니다. - - 최종 사용자가 세션 관리에 접근하기 전에, 비밀번호, 이메일 또는 SMS를 통해 본인 인증을 거쳐 10분 유효의 인증 기록 ID를 받아야 합니다. [인증 기록 ID 받기](#get-a-verification-record-id)를 참고하세요. + - 활성화되면 사용자는 장치 정보 및 마지막 로그인 시간을 포함하여 자신의 활성 세션을 보고 관리할 수 있습니다. 사용자는 특정 장치에서 로그아웃하기 위해 세션을 취소할 수도 있습니다. + - 이 동일한 `Sessions` 필드 권한은 사용자 승인 앱 (권한) API (보기 및 권한 취소)를 제어합니다. + - 최종 사용자가 세션 관리에 접근하기 전에, 비밀번호, 이메일 또는 SMS를 통해 자신의 아이덴티티를 확인하여 10분 동안 유효한 인증 기록 ID를 얻어야 합니다. [인증 기록 ID 얻기](#get-a-verification-record-id)를 참조하세요. ## Account API 접근 방법 \{#how-to-access-account-api} :::note -액세스 토큰이 적절한 권한을 갖도록 Logto 설정에서 해당 스코프를 올바르게 구성해야 합니다. +액세스 토큰에 적절한 권한이 있는지 확인하려면 Logto 구성에서 해당 스코프를 올바르게 구성했는지 확인하세요. -예를 들어, `POST /api/my-account/primary-email` API를 사용하려면 `email` 스코프를, `POST /api/my-account/primary-phone` API를 사용하려면 `phone` 스코프를 구성해야 합니다. +예를 들어, `POST /api/my-account/primary-email` API의 경우 `email` 스코프를 구성해야 하며, `POST /api/my-account/primary-phone` API의 경우 `phone` 스코프를 구성해야 합니다. ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { - // ...기타 옵션 + // ...other options // 사용 사례에 맞는 적절한 스코프를 추가하세요. scopes: [ UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` API용 UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` API용 - UserScope.CustomData, // 커스텀 데이터 관리용 + UserScope.CustomData, // 사용자 정의 데이터 관리용 UserScope.Address, // 주소 관리용 UserScope.Identities, // 아이덴티티 및 MFA 관련 API용 UserScope.Profile, // 사용자 프로필 관리용 - UserScope.Sessions, // 사용자 세션 관리용 + UserScope.Sessions, // 사용자 세션 및 앱 권한 관리용 ], }; ``` @@ -84,15 +86,15 @@ const config: LogtoConfig = { ### 액세스 토큰 가져오기 \{#fetch-an-access-token} -SDK를 애플리케이션에 설정한 후, `client.getAccessToken()` 메서드를 사용하여 액세스 토큰을 가져올 수 있습니다. 이 토큰은 Account API에 접근할 수 있는 불투명 토큰 (Opaque token)입니다. +애플리케이션에서 SDK를 설정한 후, `client.getAccessToken()` 메서드를 사용하여 액세스 토큰을 가져올 수 있습니다. 이 토큰은 Account API에 접근하는 데 사용할 수 있는 불투명 토큰입니다. -공식 SDK를 사용하지 않는 경우, 액세스 토큰 발급 요청 시 `resource`를 비워서 `/oidc/token`에 요청해야 합니다. +공식 SDK를 사용하지 않는 경우, 액세스 토큰 발급 요청을 `/oidc/token`으로 할 때 `resource`를 비워야 합니다. -### 액세스 토큰으로 Account API 접근하기 \{#access-account-api-using-access-token} +### 액세스 토큰을 사용하여 Account API 접근 \{#access-account-api-using-access-token} -Account API와 상호작용할 때, HTTP 헤더의 `Authorization` 필드에 Bearer 형식(`Bearer YOUR_TOKEN`)으로 액세스 토큰을 포함해야 합니다. +Account API와 상호작용할 때 HTTP 헤더의 `Authorization` 필드에 Bearer 형식 (`Bearer YOUR_TOKEN`)으로 액세스 토큰을 포함해야 합니다. -사용자 계정 정보를 가져오는 예시는 다음과 같습니다: +다음은 사용자 계정 정보를 얻는 예입니다: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -103,14 +105,14 @@ curl https://[tenant-id].logto.app/api/my-account \ ### 사용자 계정 정보 조회 \{#retrieve-user-account-information} -사용자 데이터를 가져오려면 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 엔드포인트를 사용할 수 있습니다. +사용자 데이터를 얻으려면 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 엔드포인트를 사용할 수 있습니다. ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -응답 본문 예시는 다음과 같습니다: +응답 본문은 다음과 같습니다: ```json { @@ -121,13 +123,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -응답 필드는 계정 센터 설정에 따라 달라질 수 있습니다. +응답 필드는 계정 센터 설정에 따라 다를 수 있습니다. ### 기본 계정 정보 업데이트 \{#update-basic-account-information} -기본 계정 정보에는 사용자명, 이름, 아바타, 커스텀 데이터 및 기타 프로필 정보가 포함됩니다. +기본 계정 정보에는 사용자 이름, 이름, 아바타, 사용자 정의 데이터 및 기타 프로필 정보가 포함됩니다. -**username, name, avatar, customData**를 업데이트하려면 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 엔드포인트를 사용할 수 있습니다. +**사용자 이름, 이름, 아바타 및 사용자 정의 데이터**를 업데이트하려면 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 엔드포인트를 사용할 수 있습니다. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -136,7 +138,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -**familyName, givenName, middleName, nickname, profile (프로필 페이지 URL), website, gender, birthdate, zoneinfo, locale, address** 등 기타 프로필 정보를 업데이트하려면 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 엔드포인트를 사용할 수 있습니다. +**familyName, givenName, middleName, nickname, profile (프로필 페이지 URL), website, gender, birthdate, zoneinfo, locale, address**를 포함한 기타 프로필 정보를 업데이트하려면 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 엔드포인트를 사용할 수 있습니다. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -145,17 +147,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 식별자 및 기타 민감 정보 관리 \{#manage-identifiers-and-other-sensitive-information} +## 식별자 및 기타 민감한 정보 관리 \{#manage-identifiers-and-other-sensitive-information} -보안상의 이유로, Account API는 식별자 및 기타 민감 정보와 관련된 작업에 대해 추가 인가 (Authorization) 계층을 요구합니다. +보안상의 이유로, Account API는 식별자 및 기타 민감한 정보를 포함하는 작업에 대해 추가적인 인가 계층을 요구합니다. -### 인증 기록 ID 받기 \{#get-a-verification-record-id} +### 인증 기록 ID 얻기 \{#get-a-verification-record-id} -먼저, 10분 유효기간(TTL)의 **인증 기록 ID**를 받아야 합니다. 이는 민감 정보 업데이트 전 사용자의 신원을 검증하는 데 사용됩니다. 즉, 사용자가 비밀번호, 이메일 인증 코드, SMS 인증 코드로 본인 인증에 성공하면, 10분 동안 인증 관련 데이터(식별자, 자격 증명, 소셜 계정 연결, MFA 등)를 업데이트할 수 있습니다. +먼저, 10분 만료 (TTL)와 함께 **인증 기록 ID**를 얻어야 합니다. 이는 민감한 정보를 업데이트하기 전에 사용자의 아이덴티티를 확인하는 데 사용할 수 있습니다. 이는 사용자가 비밀번호, 이메일 인증 코드 또는 SMS 인증 코드를 통해 자신의 아이덴티티를 성공적으로 확인하면, 인증 관련 데이터 (식별자, 자격 증명, 소셜 계정 연결 및 MFA)를 업데이트할 수 있는 10분의 시간이 주어진다는 것을 의미합니다. -인증 기록 ID를 받으려면 [사용자 비밀번호 인증](#verify-the-users-password) 또는 [이메일/전화번호로 인증 코드 전송](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)을 사용할 수 있습니다. +인증 기록 ID를 얻으려면 [사용자의 비밀번호를 확인](#verify-the-users-password)하거나 [사용자의 이메일 또는 전화로 인증 코드를 보내야](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 합니다. -#### 사용자 비밀번호 인증 \{#verify-the-users-password} +#### 사용자의 비밀번호 확인 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -164,7 +166,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -응답 본문 예시는 다음과 같습니다: +응답 본문은 다음과 같습니다: ```json { @@ -173,13 +175,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 이메일 또는 전화번호로 인증 코드 전송 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 사용자의 이메일 또는 전화로 인증 코드 보내기 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/) 또는 [SMS 커넥터](/connectors/sms-connectors/)를 구성하고, `UserPermissionValidation` 템플릿이 설정되어 있어야 합니다. +이 방법을 사용하려면 [이메일 커넥터를 구성](/connectors/email-connectors/)하거나 [SMS 커넥터를 구성](/connectors/sms-connectors/)하고, `UserPermissionValidation` 템플릿이 구성되어 있는지 확인해야 합니다. ::: -이메일을 예로 들어, 새 인증 코드를 요청하고 인증 기록 ID를 받으세요: +이메일을 예로 들어, 새 인증 코드를 요청하고 인증 기록 ID를 얻으세요: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -188,7 +190,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -응답 본문 예시는 다음과 같습니다: +응답 본문은 다음과 같습니다: ```json { @@ -206,17 +208,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -코드 인증이 완료되면, 인증 기록 ID를 사용하여 사용자의 식별자를 업데이트할 수 있습니다. +코드를 확인한 후, 이제 인증 기록 ID를 사용하여 사용자의 식별자를 업데이트할 수 있습니다. -인증에 대해 더 알아보려면 [Account API로 보안 인증](/end-user-flows/security-verification)을 참고하세요. +인증에 대해 더 알고 싶다면 [Account API에 의한 보안 인증](/end-user-flows/security-verification)을 참조하세요. -### 인증 기록 ID와 함께 요청 보내기 \{#send-request-with-verification-record-id} +### 인증 기록 ID를 포함하여 요청 보내기 \{#send-request-with-verification-record-id} -사용자 식별자를 업데이트하는 요청을 보낼 때, 요청 헤더의 `logto-verification-id` 필드에 인증 기록 ID를 포함해야 합니다. +사용자의 식별자를 업데이트하기 위한 요청을 보낼 때, 요청 헤더의 `logto-verification-id` 필드에 인증 기록 ID를 포함해야 합니다. -### 사용자 비밀번호 업데이트 \{#update-users-password} +### 사용자의 비밀번호 업데이트 \{#update-users-password} -사용자 비밀번호를 업데이트하려면 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 엔드포인트를 사용할 수 있습니다. +사용자의 비밀번호를 업데이트하려면 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 엔드포인트를 사용할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -227,16 +229,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -회원가입 시 생성된 비밀번호와 마찬가지로, Account API를 통해 설정된 비밀번호도 콘솔 > 보안 > 비밀번호 정책에서 구성한 [비밀번호 정책](/security/password-policy)을 준수해야 합니다. 정책에 위배될 경우 Logto는 상세한 검증 결과와 오류 메시지를 반환합니다. +가입 시 생성된 비밀번호와 마찬가지로, Account API를 통해 설정된 비밀번호는 콘솔 > 보안 > 비밀번호 정책에서 구성한 [비밀번호 정책](/security/password-policy)을 준수해야 합니다. Logto는 비밀번호가 정책을 통과하지 못하면 상세한 검증 결과와 오류 메시지를 반환합니다. ::: ### 새 이메일 업데이트 또는 연결 \{#update-or-link-new-email} :::note -이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 설정되어 있어야 합니다. +이 방법을 사용하려면 [이메일 커넥터를 구성](/connectors/email-connectors/)하고, `BindNewIdentifier` 템플릿이 구성되어 있는지 확인해야 합니다. ::: -새 이메일을 업데이트하거나 연결하려면, 먼저 해당 이메일의 소유권을 증명해야 합니다. +새 이메일을 업데이트하거나 연결하려면, 먼저 이메일 소유권을 증명해야 합니다. [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) 엔드포인트를 호출하여 인증 코드를 요청하세요. @@ -247,7 +249,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -응답에서 `verificationId`를 확인하고, 이메일로 받은 인증 코드를 사용하여 이메일을 인증하세요. +응답에서 `verificationId`를 찾을 수 있으며, 이메일로 인증 코드를 받게 됩니다. 이를 사용하여 이메일을 인증하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -256,34 +258,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -코드 인증이 완료되면, [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail)로 사용자의 이메일을 업데이트할 수 있습니다. 요청 본문에 `verificationId`를 `newIdentifierVerificationRecordId`로 설정하세요. +코드를 확인한 후, 이제 [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail)를 호출하여 사용자의 이메일을 업데이트할 수 있으며, `verificationId`를 요청 본문에 `newIdentifierVerificationRecordId`로 설정하세요. -:::info[서로 다른 두 개의 인증 기록 ID] +:::info[두 개의 다른 인증 기록 ID] 이 요청에는 두 개의 별도 인증 기록 ID가 필요합니다: -- **`logto-verification-id` (헤더)**: 민감한 변경 전 사용자의 신원을 증명합니다. [사용자 비밀번호 인증](#verify-the-users-password) 또는 [기존 이메일/전화번호로 인증 코드 전송](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)으로 획득합니다. -- **`newIdentifierVerificationRecordId` (본문)**: 새 이메일 주소의 소유권을 증명합니다. 위의 `POST /api/verifications/verification-code` 호출에서 반환된 `verificationRecordId`입니다. +- **`logto-verification-id` (헤더)**: 민감한 변경을 하기 전에 사용자의 아이덴티티를 증명합니다. [사용자의 비밀번호를 확인](#verify-the-users-password)하거나 [사용자의 기존 이메일 또는 전화로 인증 코드를 보내](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 얻을 수 있습니다. +- **`newIdentifierVerificationRecordId` (본문)**: 새 이메일 주소의 소유권을 증명합니다. 이는 위의 `POST /api/verifications/verification-code` 호출에서 반환된 `verificationRecordId`입니다. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # 사용자 신원 인증(비밀번호 또는 기존 이메일/전화번호 인증) + # 사용자 아이덴티티 확인 (비밀번호 또는 기존 이메일/전화 인증에서) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId"는 새 이메일 소유권을 증명(위 인증 코드 플로우에서 획득) + # "newIdentifierVerificationRecordId"는 새 이메일의 소유권을 증명합니다 (위의 인증 코드 흐름에서) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -회원가입 시 수집된 이메일과 마찬가지로, Account API를 통해 연결된 모든 이메일은 콘솔 > 보안 > 블록리스트에서 구성한 [블록리스트](/security/blocklist) 검증을 통과해야 합니다. 정책 위반 시 Logto는 요청을 거부하고 상세 오류를 반환합니다. +가입 시 수집된 이메일과 마찬가지로, Account API를 통해 연결된 모든 이메일은 콘솔 > 보안 > 차단 목록에서 구성한 [차단 목록](/security/blocklist) 검증을 통과해야 합니다. 이메일이 정책을 위반하면 Logto는 요청을 거부하고 상세한 오류를 반환합니다. ::: -### 사용자 이메일 삭제 \{#remove-the-users-email} +### 사용자의 이메일 제거 \{#remove-the-users-email} -사용자 이메일을 삭제하려면 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 엔드포인트를 사용할 수 있습니다. +사용자의 이메일을 제거하려면 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 엔드포인트를 사용할 수 있습니다. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -291,17 +293,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 전화번호 관리 \{#manage-phone} +### 전화 관리 \{#manage-phone} :::note -이 방법을 사용하려면 [SMS 커넥터](/connectors/sms-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 설정되어 있어야 합니다. +이 방법을 사용하려면 [SMS 커넥터를 구성](/connectors/sms-connectors/)하고, `BindNewIdentifier` 템플릿이 구성되어 있는지 확인해야 합니다. ::: -이메일 업데이트와 유사하게, [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 엔드포인트로 새 전화번호를 업데이트/연결할 수 있습니다. [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 엔드포인트로 사용자의 전화번호를 삭제할 수 있습니다. +이메일 업데이트와 유사하게, [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 엔드포인트를 사용하여 새 전화를 업데이트하거나 연결할 수 있습니다. 그리고 [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 엔드포인트를 사용하여 사용자의 전화를 제거할 수 있습니다. ### 새 소셜 연결 추가 \{#link-a-new-social-connection} -새 소셜 연결을 추가하려면, 먼저 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial)로 인증 URL을 요청해야 합니다. +새 소셜 연결을 추가하려면, 먼저 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) 엔드포인트를 사용하여 인가 URL을 요청해야 합니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -311,12 +313,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`: [소셜 커넥터](/connectors/social-connectors/)의 ID. -- `redirectUri`: 사용자가 애플리케이션을 인증한 후 리디렉션될 URI. 이 URL에 웹 페이지를 호스팅하고 콜백을 수신해야 합니다. -- `state`: 인증 후 반환될 상태값. CSRF 공격 방지를 위한 임의 문자열입니다. +- `redirectUri`: 사용자가 애플리케이션을 인가한 후 리디렉션되는 URI로, 이 URL에 웹 페이지를 호스팅하고 콜백을 캡처해야 합니다. +- `state`: 사용자가 애플리케이션을 인가한 후 반환되는 상태로, CSRF 공격을 방지하기 위해 사용되는 임의의 문자열입니다. -응답에서 `verificationRecordId`를 확인하고, 이후 단계에서 사용하세요. +응답에서 `verificationRecordId`를 찾을 수 있으며, 나중에 사용할 수 있도록 보관하세요. -사용자가 애플리케이션을 인증하면, `redirectUri`로 `state` 파라미터와 함께 콜백을 받게 됩니다. 이후 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 엔드포인트로 소셜 연결을 인증할 수 있습니다. +사용자가 애플리케이션을 인가한 후, `redirectUri`에서 `state` 매개변수와 함께 콜백을 받게 됩니다. 그런 다음 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 엔드포인트를 사용하여 소셜 연결을 확인할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -325,32 +327,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData`는 사용자가 애플리케이션을 인증한 후 소셜 커넥터에서 반환된 데이터입니다. 콜백 페이지에서 `redirectUri`의 쿼리 파라미터를 파싱하여 JSON으로 감싸 `connectorData` 필드 값으로 전달해야 합니다. +`connectorData`는 사용자가 애플리케이션을 인가한 후 소셜 커넥터에서 반환된 데이터로, 콜백 페이지에서 `redirectUri`의 쿼리 매개변수를 구문 분석하여 `connectorData` 필드의 값으로 JSON으로 래핑해야 합니다. -마지막으로, [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 엔드포인트로 소셜 연결을 추가할 수 있습니다. +마지막으로, [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 엔드포인트를 사용하여 소셜 연결을 추가할 수 있습니다. -:::info[서로 다른 두 개의 인증 기록 ID] +:::info[두 개의 다른 인증 기록 ID] 이 요청에는 두 개의 별도 인증 기록 ID가 필요합니다: -- **`logto-verification-id` (헤더)**: 민감한 변경 전 사용자의 신원을 증명합니다. [사용자 비밀번호 인증](#verify-the-users-password) 또는 [기존 이메일/전화번호로 인증 코드 전송](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)으로 획득합니다. -- **`newIdentifierVerificationRecordId` (본문)**: 연결할 소셜 아이덴티티를 식별합니다. 위의 `POST /api/verifications/social` 호출에서 반환된 `verificationRecordId`입니다. +- **`logto-verification-id` (헤더)**: 민감한 변경을 하기 전에 사용자의 아이덴티티를 증명합니다. [사용자의 비밀번호를 확인](#verify-the-users-password)하거나 [사용자의 기존 이메일 또는 전화로 인증 코드를 보내](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 얻을 수 있습니다. +- **`newIdentifierVerificationRecordId` (본문)**: 연결 중인 소셜 아이덴티티를 식별합니다. 이는 위의 `POST /api/verifications/social` 호출에서 반환된 `verificationRecordId`입니다. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # 사용자 신원 인증(비밀번호 또는 기존 이메일/전화번호 인증) + # 사용자 아이덴티티 확인 (비밀번호 또는 기존 이메일/전화 인증에서) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId"는 연결할 소셜 아이덴티티를 식별(위 소셜 인증 플로우에서 획득) + # "newIdentifierVerificationRecordId"는 연결할 소셜 연결을 식별합니다 (위의 소셜 인증 흐름에서) --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### 소셜 연결 삭제 \{#remove-a-social-connection} +### 소셜 연결 제거 \{#remove-a-social-connection} -소셜 연결을 삭제하려면 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 엔드포인트를 사용할 수 있습니다. +소셜 연결을 제거하려면 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 엔드포인트를 사용할 수 있습니다. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -361,27 +363,27 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto ### 새 WebAuthn 패스키 연결 \{#link-a-new-webauthn-passkey} :::note -먼저 [MFA 및 WebAuthn 활성화](/end-user-flows/mfa)를 잊지 마세요. +먼저 [MFA 및 WebAuthn을 활성화](/end-user-flows/mfa)하세요. ::: :::note 이 방법을 사용하려면 [계정 센터 설정](#how-to-enable-account-api)에서 `mfa` 필드를 활성화해야 합니다. ::: -**1단계: 프론트엔드 앱 Origin을 관련 Origin에 추가** +**1단계: 프론트엔드 앱 출처를 관련 출처에 추가** -WebAuthn 패스키는 **Relying Party ID (RP ID)**라 불리는 특정 호스트네임에 바인딩됩니다. 해당 Origin에서 호스팅되는 애플리케이션만 해당 패스키로 등록/인증할 수 있습니다. +WebAuthn 패스키는 **Relying Party ID (RP ID)**라는 특정 호스트 이름에 바인딩됩니다. RP ID의 출처에 호스팅된 애플리케이션만 해당 패스키로 등록하거나 인증할 수 있습니다. -프론트엔드 애플리케이션이 Logto 인증 페이지와 다른 도메인에서 Account API를 호출하는 경우, **Related Origins**를 구성하여 교차 Origin 패스키 작업을 허용해야 합니다. +프론트엔드 애플리케이션이 Logto의 인증 페이지와 다른 도메인에서 Account API를 호출하므로, 교차 출처 패스키 작업을 허용하려면 **관련 출처**를 구성해야 합니다. **Logto가 RP ID를 결정하는 방법:** - **기본 설정**: Logto의 기본 도메인 `https://[tenant-id].logto.app`만 사용하는 경우, RP ID는 `[tenant-id].logto.app`입니다. -- **커스텀 도메인**: [커스텀 도메인](/logto-cloud/custom-domain) 예시 `https://auth.example.com`을 구성한 경우, RP ID는 `auth.example.com`이 됩니다. +- **사용자 정의 도메인**: [사용자 정의 도메인](/logto-cloud/custom-domain)을 `https://auth.example.com`과 같이 구성한 경우, RP ID는 `auth.example.com`이 됩니다. -**Related Origins 구성:** +**관련 출처 구성:** -[`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 엔드포인트를 사용하여 프론트엔드 앱의 Origin을 추가하세요. 예를 들어, 계정 센터가 `https://account.example.com`에서 동작한다면: +[`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 엔드포인트를 사용하여 프론트엔드 애플리케이션의 출처를 추가하세요. 예를 들어, 앱의 계정 센터가 `https://account.example.com`에서 실행되는 경우: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -392,19 +394,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn은 Related Origins로 최대 5개의 고유 eTLD+1 레이블을 지원합니다. eTLD+1(유효 최상위 도메인 + 1 레이블)은 등록 가능한 도메인 부분입니다. 예시: +WebAuthn은 관련 출처에 대해 최대 5개의 고유한 eTLD+1 레이블을 지원합니다. eTLD+1 (효과적인 최상위 도메인 플러스 한 레이블)은 등록 가능한 도메인 부분입니다. 예를 들어: -- `https://example.com`, `https://app.example.com`, `https://auth.example.com`은 **하나**의 레이블(`example.com`)로 간주 -- `https://shopping.com`, `https://shopping.co.uk`, `https://shopping.co.jp`도 **하나**의 레이블(`shopping`)로 간주 -- `https://example.com`과 `https://another.com`은 **두 개**의 레이블로 간주 +- `https://example.com`, `https://app.example.com`, `https://auth.example.com`은 **하나**의 레이블 (`example.com`)로 간주됩니다. +- `https://shopping.com`, `https://shopping.co.uk`, `https://shopping.co.jp`도 **하나**의 레이블 (`shopping`)로 간주됩니다. +- `https://example.com`과 `https://another.com`은 **두 개**의 레이블로 간주됩니다. -Related Origins로 5개 이상의 도메인을 지원해야 하는 경우, [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 문서를 참고하세요. +관련 출처로 5개 이상의 다른 도메인을 지원해야 하는 경우, [관련 출처 요청](https://passkeys.dev/docs/advanced/related-origins/) 문서를 참조하세요. ::: -**2단계: 신규 등록 옵션 요청** +**2단계: 새 등록 옵션 요청** -[`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 엔드포인트로 새 패스키 등록을 요청하세요. Logto는 각 사용자 계정에 여러 개의 패스키 등록을 허용합니다. +[`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 엔드포인트를 사용하여 새 패스키 등록을 요청하세요. Logto는 각 사용자 계정이 여러 패스키를 등록할 수 있도록 허용합니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -412,7 +414,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -응답 예시: +응답은 다음과 같습니다: ```json { @@ -424,23 +426,23 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat **3단계: 로컬 브라우저에서 패스키 등록** -[`@simplewebauthn/browser`](https://simplewebauthn.dev/)를 예로 들면, `startRegistration` 함수를 사용하여 로컬 브라우저에서 패스키를 등록할 수 있습니다. +[`@simplewebauthn/browser`](https://simplewebauthn.dev/)를 예로 들어, `startRegistration` 함수를 사용하여 로컬 브라우저에서 패스키를 등록할 수 있습니다. ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // 1단계에서 서버가 반환한 데이터 + optionsJSON: registrationOptions, // 1단계에서 서버에서 반환된 데이터 }); -// 이후 사용을 위해 response를 저장 +// 나중에 사용할 수 있도록 응답을 저장하세요 ``` -**4단계: 패스키 등록 인증** +**4단계: 패스키 등록 확인** -[`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 엔드포인트로 패스키 등록을 인증하세요. +[`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 엔드포인트를 사용하여 패스키 등록을 확인하세요. -이 단계는 인증자가 생성한 암호화 서명을 검증하여 패스키가 합법적으로 생성되었고 전송 중 변조되지 않았음을 확인합니다. +이 단계는 인증자가 생성한 암호화 서명을 확인하여 패스키가 합법적으로 생성되었으며 전송 중에 변조되지 않았음을 보장합니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -449,12 +451,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`: 2단계에서 로컬 브라우저가 반환한 응답 -- `verificationRecordId`: 1단계에서 서버가 반환한 인증 기록 ID +- `payload`: 2단계에서 로컬 브라우저의 응답. +- `verificationRecordId`: 1단계에서 서버에서 반환된 인증 기록 ID. **5단계: 패스키 연결** -마지막으로, [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트로 패스키를 사용자 계정에 연결할 수 있습니다. +마지막으로, [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트를 사용하여 패스키를 사용자의 계정에 연결할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -464,20 +466,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: 기존 요소 인증을 통해 획득한 유효한 인증 기록 ID. 자세한 내용은 [인증 기록 ID 받기](#get-a-verification-record-id) 섹션 참고. -- `type`: MFA 요소 타입, 현재는 `WebAuthn`만 지원. -- `newIdentifierVerificationRecordId`: 1단계에서 서버가 반환한 인증 기록 ID. +- `verification_record_id`: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 [인증 기록 ID 얻기](#get-a-verification-record-id) 섹션을 참조하세요. +- `type`: MFA 요소의 유형으로, 현재는 `WebAuthn`만 지원됩니다. +- `newIdentifierVerificationRecordId`: 1단계에서 서버에서 반환된 인증 기록 ID. ### 기존 WebAuthn 패스키 관리 \{#manage-existing-webauthn-passkeys} -기존 WebAuthn 패스키를 관리하려면 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 엔드포인트로 현재 패스키 및 기타 MFA 인증 요소를 조회할 수 있습니다. +기존 WebAuthn 패스키를 관리하려면 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 엔드포인트를 사용하여 현재 패스키 및 기타 MFA 인증 요소를 가져올 수 있습니다. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -응답 예시: +응답 본문은 다음과 같습니다: ```json [ @@ -492,12 +494,12 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`: 인증 요소의 ID -- `type`: 인증 요소 타입, WebAuthn 패스키의 경우 `WebAuthn` -- `name`: 패스키 이름(선택) -- `agent`: 패스키의 사용자 에이전트 +- `id`: 인증의 ID. +- `type`: 인증의 유형, WebAuthn 패스키의 경우 `WebAuthn`. +- `name`: 패스키의 이름, 선택적 필드. +- `agent`: 패스키의 사용자 에이전트. -패스키 이름을 업데이트하려면 [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 엔드포인트를 사용하세요: +[`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 엔드포인트를 사용하여 패스키 이름을 업데이트하세요: ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -507,7 +509,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -패스키를 삭제하려면 [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 엔드포인트를 사용하세요: +[`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 엔드포인트를 사용하여 패스키를 삭제하세요: ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -518,16 +520,16 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v ### 새 TOTP 연결 \{#link-a-new-totp} :::note -먼저 [MFA 및 TOTP 활성화](/end-user-flows/mfa)를 잊지 마세요. +먼저 [MFA 및 TOTP를 활성화](/end-user-flows/mfa)하세요. ::: :::note 이 방법을 사용하려면 [계정 센터 설정](#how-to-enable-account-api)에서 `mfa` 필드를 활성화해야 합니다. ::: -**1단계: TOTP 시크릿 생성** +**1단계: TOTP 비밀 생성** -[`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 엔드포인트로 TOTP 시크릿을 생성하세요. +[`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 엔드포인트를 사용하여 TOTP 비밀을 생성하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -535,7 +537,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -응답 예시: +응답 본문은 다음과 같습니다: ```json { @@ -543,11 +545,11 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp } ``` -**2단계: 사용자에게 TOTP 시크릿 표시** +**2단계: 사용자에게 TOTP 비밀 표시** -시크릿을 사용해 QR 코드를 생성하거나 직접 사용자에게 표시하세요. 사용자는 이를 Google Authenticator, Microsoft Authenticator, Authy 등 인증 앱에 추가해야 합니다. +비밀을 사용하여 QR 코드를 생성하거나 사용자에게 직접 표시하세요. 사용자는 이를 인증 앱 (예: Google Authenticator, Microsoft Authenticator, Authy)에 추가해야 합니다. -QR 코드용 URI 형식은 다음과 같습니다: +QR 코드의 URI 형식은 다음과 같아야 합니다: ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -561,7 +563,7 @@ otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp **3단계: TOTP 요소 바인딩** -사용자가 인증 앱에 시크릿을 추가한 후, 이를 검증하고 계정에 바인딩해야 합니다. [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트를 사용하세요. +사용자가 비밀을 인증 앱에 추가한 후, 이를 확인하고 계정에 바인딩해야 합니다. [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트를 사용하여 TOTP 요소를 바인딩하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -571,18 +573,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`: 기존 요소 인증을 통해 획득한 유효한 인증 기록 ID. 자세한 내용은 [인증 기록 ID 받기](#get-a-verification-record-id) 섹션 참고. -- `type`: 반드시 `Totp`여야 합니다. -- `secret`: 1단계에서 생성한 TOTP 시크릿 +- `verification_record_id`: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 [인증 기록 ID 얻기](#get-a-verification-record-id) 섹션을 참조하세요. +- `type`: `Totp`여야 합니다. +- `secret`: 1단계에서 생성된 TOTP 비밀. :::note -사용자는 한 번에 하나의 TOTP 요소만 가질 수 있습니다. 이미 TOTP 요소가 있다면 추가 시 422 오류가 발생합니다. +사용자는 한 번에 하나의 TOTP 요소만 가질 수 있습니다. 사용자가 이미 TOTP 요소를 가지고 있는 경우, 다른 요소를 추가하려고 하면 422 오류가 발생합니다. ::: ### 백업 코드 관리 \{#manage-backup-codes} :::note -먼저 [MFA 및 백업 코드 활성화](/end-user-flows/mfa)를 잊지 마세요. +먼저 [MFA 및 백업 코드](/end-user-flows/mfa)를 활성화하세요. ::: :::note @@ -591,7 +593,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ **1단계: 새 백업 코드 생성** -[`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 엔드포인트로 10개의 새 백업 코드를 생성하세요. +[`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 엔드포인트를 사용하여 10개의 새 백업 코드를 생성하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -599,7 +601,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -응답 예시: +응답 본문은 다음과 같습니다: ```json { @@ -609,18 +611,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back **2단계: 사용자에게 백업 코드 표시** -백업 코드를 사용자 계정에 바인딩하기 전에, 사용자에게 코드를 표시하고 다음을 안내해야 합니다: +백업 코드를 사용자의 계정에 바인딩하기 전에, 사용자에게 이를 표시하고 다음을 지시해야 합니다: -- 즉시 다운로드하거나 기록해 둘 것 -- 안전한 장소에 보관할 것 -- 각 코드는 한 번만 사용할 수 있음 -- 주 MFA 수단을 잃었을 때 최후의 수단임을 인지할 것 +- 즉시 이 코드를 다운로드하거나 기록하세요 +- 안전한 장소에 보관하세요 +- 각 코드는 한 번만 사용할 수 있음을 이해하세요 +- 이러한 코드는 기본 MFA 방법에 접근할 수 없을 때 최후의 수단임을 알아두세요 -코드를 명확하고 복사하기 쉬운 형식으로 표시하고, 다운로드 옵션(예: 텍스트 파일, PDF 등)도 제공하는 것이 좋습니다. +코드를 명확하고 쉽게 복사할 수 있는 형식으로 표시하고 다운로드 옵션 (예: 텍스트 파일 또는 PDF로)을 제공하는 것을 고려하세요. -**3단계: 백업 코드를 사용자 계정에 바인딩** +**3단계: 사용자 계정에 백업 코드 바인딩** -[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트로 백업 코드를 계정에 바인딩하세요. +[`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 엔드포인트를 사용하여 백업 코드를 사용자 계정에 바인딩하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -630,28 +632,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`: 기존 요소 인증을 통해 획득한 유효한 인증 기록 ID. 자세한 내용은 [인증 기록 ID 받기](#get-a-verification-record-id) 섹션 참고. -- `type`: 반드시 `BackupCode`여야 합니다. -- `codes`: 이전 단계에서 생성한 백업 코드 배열 +- `verification_record_id`: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 [인증 기록 ID 얻기](#get-a-verification-record-id) 섹션을 참조하세요. +- `type`: `BackupCode`여야 합니다. +- `codes`: 이전 단계에서 생성된 백업 코드 배열. :::note -- 사용자는 한 번에 한 세트의 백업 코드만 가질 수 있습니다. 모든 코드를 사용한 경우 새 코드를 생성 및 바인딩해야 합니다. -- 백업 코드는 유일한 MFA 요소가 될 수 없습니다. 사용자는 최소 한 개 이상의 다른 MFA 요소(WebAuthn 또는 TOTP 등)를 활성화해야 합니다. +- 사용자는 한 번에 하나의 백업 코드 세트만 가질 수 있습니다. 모든 코드가 사용된 경우, 사용자는 새 코드를 생성하고 바인딩해야 합니다. +- 백업 코드는 유일한 MFA 요소가 될 수 없습니다. 사용자는 최소한 하나 이상의 다른 MFA 요소 (예: WebAuthn 또는 TOTP)를 활성화해야 합니다. - 각 백업 코드는 한 번만 사용할 수 있습니다. ::: -**기존 백업 코드 조회** +**기존 백업 코드 보기** -기존 백업 코드 및 사용 상태를 조회하려면 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 엔드포인트를 사용하세요: +기존 백업 코드와 사용 상태를 보려면 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 엔드포인트를 사용하세요: ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -응답 예시: +응답 본문은 다음과 같습니다: ```json { @@ -668,19 +670,19 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes } ``` -- `code`: 백업 코드 -- `usedAt`: 코드 사용 시각, 미사용 시 `null` +- `code`: 백업 코드. +- `usedAt`: 코드가 사용된 타임스탬프, 아직 사용되지 않은 경우 `null`. ### 사용자 세션 관리 \{#manage-user-sessions} -**활성 세션 목록 조회** +**활성 세션 목록** -사용자의 활성 세션을 조회하려면 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 엔드포인트를 사용할 수 있습니다. +사용자의 활성 세션을 나열하려면 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 엔드포인트를 사용할 수 있습니다. :::note - 이 엔드포인트에 접근하려면 `UserScope.Sessions` 스코프가 필요합니다. -- 계정 센터 설정에서 `Sessions` 필드는 `ReadOnly` 또는 `Edit`이어야 합니다. +- 계정 센터 설정에서 `Sessions` 필드는 `ReadOnly` 또는 `Edit`으로 설정되어야 합니다. ::: @@ -691,14 +693,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**세션 ID로 세션 해제** +**세션 ID로 세션 취소** -특정 세션을 해제하려면 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 엔드포인트를 사용하세요. +특정 세션을 취소하려면 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 엔드포인트를 사용하세요. :::note - 이 엔드포인트에 접근하려면 `UserScope.Sessions` 스코프가 필요합니다. -- 계정 센터 설정에서 `Sessions` 필드는 `Edit`이어야 합니다. +- 계정 센터 설정에서 `Sessions` 필드는 `Edit`으로 설정되어야 합니다. ::: ```bash @@ -708,9 +710,60 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} -H 'content-type: application/json' ``` -선택적 쿼리 파라미터: +선택적 쿼리 매개변수: -- `revokeGrantsTarget`: 세션과 함께 해제할 권한의 대상을 선택적으로 지정할 수 있습니다. 가능한 값: - - `all`: 세션과 연관된 모든 권한 해제 - - `firstParty`: 세션과 연관된 자사 앱 권한만 해제(대부분의 경우 권장, 타사 앱 권한은 유지되어 더 나은 사용자 경험 제공) - - 미지정: 기본 동작은 `offline_access` 스코프가 없는 권한만 해제(일반적으로 리프레시 토큰이 없는 세션 권한 해제) +- `revokeGrantsTarget`: 세션과 함께 취소할 권한의 대상을 선택적으로 지정합니다. 가능한 값: + - `all`: 세션과 관련된 모든 권한을 취소합니다. + - `firstParty`: 세션과 관련된 1차 앱 권한만 취소합니다. (대부분의 사용 사례에 권장되며, 사용자의 앱에 대한 접근을 취소하면서 타사 앱 권한은 유지하여 더 나은 사용자 경험을 제공합니다.) + - 지정되지 않음: 기본 동작은 `offline_access` 스코프가 없는 권한을 취소하며, 이는 일반적으로 세션에 대한 리프레시 토큰이 아닌 권한을 취소하는 것을 의미합니다. + +### 사용자 승인 앱 (권한) 관리 \{#manage-user-authorized-apps-grants} + +사용자가 계정 설정 페이지에서 승인된 앱을 검토하고 취소해야 할 때 사용자 승인 앱 (권한) API를 사용하세요. + +:::note + +- 앱 권한 API는 세션 API와 동일한 권한 모델을 공유합니다. +- `UserScope.Sessions` 스코프가 필요합니다. +- 계정 센터 설정에서 `Sessions` 필드가 활성화되어야 합니다: + - 권한을 나열하려면 `ReadOnly` 또는 `Edit`. + - 권한을 취소하려면 `Edit`. + +::: + +**활성 앱 권한 목록** + +현재 사용자의 활성 앱 권한을 나열하려면 [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) 엔드포인트를 사용하세요. + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +선택적 쿼리 매개변수: + +- `appType=firstParty`: 1차 앱 권한만 반환합니다. +- `appType=thirdParty`: 타사 앱 권한만 반환합니다. +- `appType` 생략: 모든 활성 권한을 반환합니다. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**권한 ID로 앱 권한 취소** + +특정 앱 권한을 취소하려면 [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) 엔드포인트를 사용하세요. + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +권한이 취소되면, 해당 권한에 대해 이전에 발급된 불투명 액세스 토큰 및 리프레시 토큰이 무효화됩니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index 500b858058f..02a1f7e09bd 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -4,11 +4,11 @@ sidebar_position: 2 # Management API를 통한 계정 설정 -## 통합 (Integrations) \{#integrations} +## 통합 \{#integrations} -Logto는 사용자 계정을 관리할 수 있는 다양한 Management API를 제공합니다. 이러한 API를 사용하여 최종 사용자를 위한 셀프 서비스 계정 설정 페이지를 구축할 수 있습니다. +Logto는 사용자 계정을 관리하기 위한 다양한 Management API를 제공합니다. 이러한 API를 사용하여 최종 사용자를 위한 셀프 서비스 계정 설정 페이지를 구축할 수 있습니다. -### 아키텍처 (Architecture) \{#architecture} +### 아키텍처 \{#architecture} ```mermaid graph TB @@ -20,9 +20,9 @@ Logto는 사용자 계정을 관리할 수 있는 다양한 Management API를 1. **사용자**: 계정 설정에 접근하고 관리해야 하는 인증된 최종 사용자. 2. **클라이언트 애플리케이션**: 사용자에게 계정 설정 페이지를 제공하는 클라이언트 애플리케이션. 3. **서버 측 애플리케이션**: 클라이언트에 계정 설정 API를 제공하는 서버 측 애플리케이션. Logto Management API와 상호작용합니다. -4. **Logto**: 인증 (Authentication) 및 인가 (Authorization) 서비스로서의 Logto. 사용자 계정 관리를 위한 Management API를 제공합니다. +4. **Logto**: 인증 및 인가 서비스로서의 Logto. 사용자 계정을 관리하기 위한 Management API를 제공합니다. -### 시퀀스 다이어그램 (Sequence diagram) \{#sequence-diagram} +### 시퀀스 다이어그램 \{#sequence-diagram} ```mermaid sequenceDiagram @@ -32,90 +32,90 @@ Logto는 사용자 계정을 관리할 수 있는 다양한 Management API를 participant Server as 서버 측 애플리케이션 participant Logto as Logto - User ->> Client: 클라이언트 앱 접근 + User ->> Client: 클라이언트 앱에 접근 Client ->> Logto: POST /oidc/auth User -->> Logto: 로그인 Logto -->> Client: 클라이언트 앱으로 리디렉션 Client ->> Logto: POST /oidc/token - Logto ->> Client: 액세스 토큰 (Access token) A - Client ->> Server: GET /account-settings (액세스 토큰 A와 함께) - Server ->> Logto: POST /oidc/token (클라이언트 자격 증명과 함께) - Logto ->> Server: 액세스 토큰 (Access token) B - Server ->> Logto: GET /api/users/{userId} (액세스 토큰 B와 함께) - Logto ->> Server: 사용자 정보 - Server ->> Client: 사용자 정보 + Logto ->> Client: 액세스 토큰 A + Client ->> Server: GET /account-settings (액세스 토큰 A 포함) + Server ->> Logto: POST /oidc/token (클라이언트 자격 증명 포함) + Logto ->> Server: 액세스 토큰 B + Server ->> Logto: GET /api/users/{userId} (액세스 토큰 B 포함) + Logto ->> Server: 사용자 세부 정보 + Server ->> Client: 사용자 세부 정보 ``` 1. 사용자가 클라이언트 애플리케이션에 접근합니다. -2. 클라이언트 애플리케이션이 Logto에 인증 요청을 보내고 사용자를 Logto 로그인 페이지로 리디렉션합니다. +2. 클라이언트 애플리케이션은 Logto에 인증 요청을 보내고 사용자를 Logto 로그인 페이지로 리디렉션합니다. 3. 사용자가 Logto에 로그인합니다. 4. 인증된 사용자가 인가 코드와 함께 클라이언트 애플리케이션으로 리디렉션됩니다. -5. 클라이언트 애플리케이션이 셀프 호스팅 계정 설정 API 접근을 위해 Logto에 액세스 토큰을 요청합니다. -6. Logto가 클라이언트 애플리케이션에 액세스 토큰을 발급합니다. -7. 클라이언트 애플리케이션이 사용자 액세스 토큰과 함께 서버 측 애플리케이션에 계정 설정 요청을 보냅니다. -8. 서버 측 애플리케이션이 사용자 액세스 토큰에서 요청자의 신원과 권한을 검증한 후, Logto에 Management API 액세스 토큰을 요청합니다. -9. Logto가 서버 측 애플리케이션에 Management API 액세스 토큰을 발급합니다. -10. 서버 측 애플리케이션이 Management API 액세스 토큰을 사용하여 Logto에서 사용자 데이터를 요청합니다. -11. Logto가 서버의 신원과 Management API 권한을 검증한 후 사용자 데이터를 반환합니다. -12. 서버 측 애플리케이션이 요청자의 권한에 따라 사용자 데이터를 처리하고, 사용자 계정 정보를 클라이언트 애플리케이션에 반환합니다. +5. 클라이언트 애플리케이션은 셀프 호스팅 계정 설정 API 접근을 위해 Logto에 액세스 토큰을 요청합니다. +6. Logto는 클라이언트 애플리케이션에 액세스 토큰을 부여합니다. +7. 클라이언트 애플리케이션은 사용자 액세스 토큰과 함께 서버 측 애플리케이션에 계정 설정 요청을 보냅니다. +8. 서버 측 애플리케이션은 사용자 액세스 토큰에서 요청자의 아이덴티티와 권한을 확인합니다. 그런 다음 Logto에서 Management API 액세스 토큰을 요청합니다. +9. Logto는 서버 측 애플리케이션에 Management API 액세스 토큰을 부여합니다. +10. 서버 측 애플리케이션은 Management API 액세스 토큰을 사용하여 Logto에서 사용자 데이터를 요청합니다. +11. Logto는 서버의 아이덴티티와 Management API 권한을 확인하고 사용자 데이터를 반환합니다. +12. 서버 측 애플리케이션은 요청자의 권한에 따라 사용자 데이터를 처리하고 사용자 계정 세부 정보를 클라이언트 애플리케이션에 반환합니다. -### 서버 측 애플리케이션에 Management API 통합하기 \{#integrate-management-api-to-server-side-application} +### 서버 측 애플리케이션에 Management API 통합 \{#integrate-management-api-to-server-side-application} -서버 측 애플리케이션과 Management API를 통합하는 방법은 [Management API](/integrate-logto/interact-with-management-api/) 섹션을 참고하세요. +서버 측 애플리케이션과 Management API를 통합하는 방법에 대해 알아보려면 [Management API](/integrate-logto/interact-with-management-api/) 섹션을 확인하세요. -## 사용자 관리 API (User Management APIs) \{#user-management-apis} +## 사용자 관리 API \{#user-management-apis} -### 사용자 데이터 스키마 (User data schema) \{#user-data-schema} +### 사용자 데이터 스키마 \{#user-data-schema} -Logto의 사용자 스키마에 대해 더 알고 싶다면 [사용자 데이터 및 커스텀 데이터](/user-management/user-data/) 섹션을 참고하세요. +Logto의 사용자 스키마에 대해 더 알고 싶다면 [사용자 데이터 및 사용자 정의 데이터](/user-management/user-data/) 섹션을 확인하세요. -### 사용자 프로필 및 식별자 관리 API (User profile and identifiers Management APIs) \{#user-profile-and-identifiers-management-apis} +### 사용자 프로필 및 식별자 관리 API \{#user-profile-and-identifiers-management-apis} -사용자 프로필과 식별자는 사용자 관리에 필수적입니다. 다음 API를 사용하여 사용자 프로필과 식별자를 관리할 수 있습니다. +사용자의 프로필과 식별자는 사용자 관리에 필수적입니다. 다음 API를 사용하여 사용자 프로필과 식별자를 관리할 수 있습니다. -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 정보를 조회합니다. | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 사용자 정보를 업데이트합니다. | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 사용자 ID로 사용자 프로필 필드를 업데이트합니다. | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 사용자 ID로 사용자 커스텀 데이터를 조회합니다. | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 사용자 ID로 사용자 커스텀 데이터를 업데이트합니다. | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 사용자 ID로 사용자 정지 상태를 업데이트합니다. | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 세부 정보를 가져옵니다. | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 사용자 세부 정보를 업데이트합니다. | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 사용자 ID로 사용자 프로필 필드를 업데이트합니다. | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 사용자 ID로 사용자 정의 데이터를 가져옵니다. | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 사용자 ID로 사용자 정의 데이터를 업데이트합니다. | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 사용자 ID로 사용자 정지 상태를 업데이트합니다. | -### 이메일 및 전화번호 인증 (Email and phone number verification) \{#email-and-phone-number-verification} +### 이메일 및 전화번호 인증 \{#email-and-phone-number-verification} -Logto 시스템에서 이메일 주소와 전화번호 모두 사용자 식별자로 사용될 수 있으므로, 이들의 인증은 필수적입니다. 이를 지원하기 위해 제공된 이메일 또는 전화번호를 인증할 수 있는 일련의 인증 코드 API를 제공합니다. +Logto 시스템에서 이메일 주소와 전화번호는 사용자 식별자로 사용될 수 있으므로, 이들의 인증이 필수적입니다. 이를 지원하기 위해 제공된 이메일 또는 전화번호를 인증하는 데 도움이 되는 일련의 인증 코드 API를 제공합니다. :::note -새 이메일 또는 전화번호로 사용자 프로필을 업데이트하기 전에 반드시 이메일 또는 전화번호를 인증하세요. +사용자 프로필을 새로운 이메일 또는 전화번호로 업데이트하기 전에 반드시 이메일 또는 전화번호를 인증하세요. ::: | method | path | description | | ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 이메일 또는 전화번호 인증 코드를 전송합니다. | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 이메일 또는 전화번호 인증 코드를 보냅니다. | | POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 인증 코드로 이메일 또는 전화번호를 인증합니다. | -### 사용자 비밀번호 관리 (User password management) \{#user-password-management} +### 사용자 비밀번호 관리 \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 사용자 ID로 현재 비밀번호를 인증합니다. | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 사용자 ID로 비밀번호를 업데이트합니다. | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 사용자 ID로 비밀번호 존재 여부를 확인합니다. | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 사용자 ID로 현재 사용자 비밀번호를 인증합니다. | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 사용자 ID로 사용자 비밀번호를 업데이트합니다. | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 사용자 ID로 사용자가 비밀번호를 가지고 있는지 확인합니다. | :::note -사용자 비밀번호를 업데이트하기 전에 반드시 현재 비밀번호를 인증하세요. +사용자 비밀번호를 업데이트하기 전에 사용자의 현재 비밀번호를 인증하세요. ::: -### 사용자 소셜 아이덴티티 관리 (User social identities management) \{#user-social-identities-management} +### 사용자 소셜 아이덴티티 관리 \{#user-social-identities-management} | method | path | description | | ------ | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 정보를 조회합니다. 소셜 아이덴티티는 `identities` 필드에서 확인할 수 있습니다. | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 인증된 소셜 아이덴티티를 사용자 ID로 연결합니다. | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 사용자 ID로 소셜 아이덴티티 연결을 해제합니다. | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 사용자 ID로 연결된 소셜 아이덴티티를 직접 업데이트합니다. | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 소셜 아이덴티티 제공자의 인가 URI를 가져옵니다. 이 URI를 사용하여 새로운 소셜 아이덴티티 연결을 시작하세요. | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 세부 정보를 가져옵니다. 소셜 아이덴티티는 `identities` 필드에서 찾을 수 있습니다. | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 사용자 ID로 인증된 소셜 아이덴티티를 사용자에게 연결합니다. | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 사용자 ID로 사용자로부터 소셜 아이덴티티를 연결 해제합니다. | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 사용자 ID로 사용자에게 연결된 소셜 아이덴티티를 직접 업데이트합니다. | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 소셜 아이덴티티 제공자의 인가 URI를 가져옵니다. 이 URI를 사용하여 새로운 소셜 아이덴티티 연결을 시작합니다. | ```mermaid sequenceDiagram @@ -126,79 +126,94 @@ sequenceDiagram participant Logto as Logto participant IdP as 소셜 아이덴티티 제공자 - User ->> Client: 소셜 아이덴티티 연결 요청으로 클라이언트 앱 접근 + User ->> Client: 클라이언트 앱에 접근하여 소셜 아이덴티티 연결 요청 Client ->> App: 소셜 아이덴티티 연결 요청 전송 App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri - Logto ->> App: 인가 URI 반환 + Logto ->> App: 인가 URI App ->> Client: 인가 URI 반환 Client ->> IdP: IdP 인가 페이지로 리디렉션 User -->> IdP: IdP에 로그인 IdP ->> Client: 인가 코드와 함께 클라이언트 앱으로 리디렉션 Client ->> Server: 소셜 아이덴티티 연결 요청, IdP 인가 응답 전달 Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: 인가 코드로 IdP에서 사용자 정보 조회 + Logto ->> IdP: 인가 코드를 사용하여 IdP에서 사용자 정보 가져오기 IdP ->> Logto: 사용자 정보 반환 ``` 1. 사용자가 클라이언트 애플리케이션에 접근하여 소셜 아이덴티티 연결을 요청합니다. -2. 클라이언트 애플리케이션이 서버에 소셜 아이덴티티 연결 요청을 전송합니다. -3. 서버가 소셜 아이덴티티 제공자의 인가 URI를 얻기 위해 Logto에 요청을 보냅니다. 요청 시 `state` 파라미터와 `redirect_uri`를 직접 제공해야 합니다. 반드시 소셜 아이덴티티 제공자에 `redirect_uri`를 등록하세요. -4. Logto가 서버에 인가 URI를 반환합니다. -5. 서버가 인가 URI를 클라이언트 애플리케이션에 반환합니다. -6. 클라이언트 애플리케이션이 사용자를 IdP 인가 URI로 리디렉션합니다. +2. 클라이언트 애플리케이션은 서버에 소셜 아이덴티티 연결 요청을 보냅니다. +3. 서버는 소셜 아이덴티티 제공자의 인가 URI를 얻기 위해 Logto에 요청을 보냅니다. 요청 시 `state` 매개변수와 `redirect_uri`를 제공해야 합니다. 소셜 아이덴티티 제공자에 `redirect_uri`를 사전에 등록하세요. +4. Logto는 서버에 인가 URI를 반환합니다. +5. 서버는 클라이언트 애플리케이션에 인가 URI를 반환합니다. +6. 클라이언트 애플리케이션은 사용자를 IdP 인가 URI로 리디렉션합니다. 7. 사용자가 IdP에 로그인합니다. -8. IdP가 인가 코드와 함께 사용자를 `redirect_uri`로 클라이언트 애플리케이션에 리디렉션합니다. -9. 클라이언트 애플리케이션이 `state`를 검증하고 IdP 인가 응답을 서버로 전달합니다. -10. 서버가 Logto에 소셜 아이덴티티를 사용자에 연결하도록 요청합니다. -11. Logto가 인가 코드를 사용하여 IdP에서 사용자 정보를 조회합니다. -12. IdP가 사용자 정보를 Logto에 반환하고, Logto가 소셜 아이덴티티를 사용자에 연결합니다. +8. IdP는 인가 코드와 함께 사용자를 `redirect_uri`를 통해 클라이언트 애플리케이션으로 리디렉션합니다. +9. 클라이언트 애플리케이션은 `state`를 검증하고 IdP 인가 응답을 서버로 전달합니다. +10. 서버는 Logto에 소셜 아이덴티티를 사용자에게 연결하도록 요청합니다. +11. Logto는 인가 코드를 사용하여 IdP에서 사용자 정보를 가져옵니다. +12. IdP는 사용자 정보를 Logto에 반환하고 Logto는 소셜 아이덴티티를 사용자에게 연결합니다. :::note -사용자에 새로운 소셜 아이덴티티를 연결할 때 고려해야 할 몇 가지 제한 사항이 있습니다: +사용자에게 새로운 소셜 아이덴티티를 연결할 때 고려해야 할 몇 가지 제한 사항이 있습니다: -- Management API에는 세션 컨텍스트가 없으므로, 소셜 인증 상태를 안전하게 유지하기 위해 활성 세션이 필요한 소셜 커넥터는 Management API를 통해 연결할 수 없습니다. 지원되지 않는 커넥터에는 apple, 표준 OIDC 및 표준 OAuth 2.0 커넥터가 포함됩니다. -- 같은 이유로, Logto는 인가 응답의 `state` 파라미터를 검증할 수 없습니다. 클라이언트 앱에서 `state` 파라미터를 저장하고 인가 응답을 받을 때 반드시 검증하세요. -- 사전에 소셜 아이덴티티 제공자에 `redirect_uri`를 등록해야 합니다. 그렇지 않으면 소셜 IdP가 사용자를 클라이언트 앱으로 리디렉션하지 않습니다. 소셜 IdP는 사용자 로그인용, 프로필 바인딩 페이지용 등 둘 이상의 콜백 `redirect_uri`를 허용해야 합니다. +- Management API는 세션 컨텍스트가 없으므로, 소셜 인증 상태를 안전하게 유지하기 위해 활성 세션이 필요한 소셜 커넥터는 Management API를 통해 연결할 수 없습니다. 지원되지 않는 커넥터에는 apple, 표준 OIDC 및 표준 OAuth 2.0 커넥터가 포함됩니다. +- 같은 이유로, Logto는 인가 응답에서 `state` 매개변수를 검증할 수 없습니다. 클라이언트 앱에 `state` 매개변수를 저장하고 인가 응답을 받을 때 이를 검증하세요. +- 소셜 아이덴티티 제공자에 `redirect_uri`를 사전에 등록해야 합니다. 그렇지 않으면 소셜 IdP가 사용자를 클라이언트 앱으로 다시 리디렉션하지 않습니다. 소셜 IdP는 사용자 로그인용과 프로필 바인딩 페이지용으로 두 개 이상의 콜백 `redirect_uri`를 허용해야 합니다. ::: -### 사용자 엔터프라이즈 아이덴티티 관리 (User enterprise identities management) \{#user-enterprise-identities-management} +### 사용자 엔터프라이즈 아이덴티티 관리 \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 정보를 조회합니다. 엔터프라이즈 아이덴티티는 `ssoIdentities` 필드에서 확인할 수 있습니다. API에 `includeSsoIdentities=true` 쿼리 파라미터를 추가하세요. | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 사용자 ID로 사용자 세부 정보를 가져옵니다. 엔터프라이즈 아이덴티티는 `ssoIdentities` 필드에서 찾을 수 있습니다. 사용자 세부 정보 API에 `includeSsoIdentities=true` 쿼리 매개변수를 추가하여 포함시킵니다. | -현재 Management API는 사용자에 엔터프라이즈 아이덴티티를 연결하거나 해제하는 기능을 지원하지 않습니다. 연결된 엔터프라이즈 아이덴티티만 표시할 수 있습니다. +현재 Management API는 사용자에게 엔터프라이즈 아이덴티티를 연결하거나 연결 해제하는 것을 지원하지 않습니다. 사용자가 연결한 엔터프라이즈 아이덴티티만 표시할 수 있습니다. -### 개인 액세스 토큰 (Personal access token) \{#personal-access-token} +### 개인 액세스 토큰 \{#personal-access-token} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | 사용자의 모든 개인 액세스 토큰을 조회합니다. | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | 사용자에 새로운 개인 액세스 토큰을 추가합니다. | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 이름으로 사용자의 토큰을 삭제합니다. | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 이름으로 사용자의 토큰을 업데이트합니다. | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | 사용자의 모든 개인 액세스 토큰을 가져옵니다. | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | 사용자에게 새로운 개인 액세스 토큰을 추가합니다. | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 이름으로 사용자의 토큰을 삭제합니다. | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 이름으로 사용자의 토큰을 업데이트합니다. | -개인 액세스 토큰은 사용자가 자격 증명과 상호작용 로그인 없이 [액세스 토큰 (Access token)](https://auth.wiki/access-token)을 안전하게 부여할 수 있는 방법을 제공합니다. [개인 액세스 토큰 사용법](/user-management/personal-access-token)에 대해 더 알아보세요. +개인 액세스 토큰은 사용자가 자격 증명과 상호작용 로그인 없이 [액세스 토큰](https://auth.wiki/access-token)을 부여할 수 있는 안전한 방법을 제공합니다. [개인 액세스 토큰 사용](/user-management/personal-access-token)에 대해 더 알아보세요. -### 사용자 MFA 설정 관리 (User MFA settings management) \{#user-mfa-settings-management} +### 사용자 MFA 설정 관리 \{#user-mfa-settings-management} | method | path | description | | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | 사용자 ID로 사용자 MFA 설정을 조회합니다. | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | 사용자 ID로 사용자 MFA 설정을 가져옵니다. | | POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | 사용자 ID로 사용자 MFA 인증을 설정합니다. | | DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | ID로 사용자 MFA 인증을 삭제합니다. | -### 사용자 계정 삭제 (User account deletion) \{#user-account-deletion} +### 사용자 계정 삭제 \{#user-account-deletion} | method | path | description | | ------ | -------------------------------------------------------------------------------- | -------------------------------- | | DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | 사용자 ID로 사용자를 삭제합니다. | -### 사용자 세션 관리 (User session management) \{#user-session-management} +### 사용자 세션 관리 \{#user-session-management} | method | path | description | | ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | 사용자 ID로 사용자 세션을 조회합니다. | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | 세션 ID로 사용자 세션을 조회합니다. | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | 사용자 ID로 사용자 세션을 가져옵니다. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | 세션 ID로 사용자 세션을 가져옵니다. | | DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | 세션 ID로 사용자 세션을 삭제합니다. | + +### 사용자 승인된 앱 (grants) 관리 \{#manage-user-authorized-apps-grants} + +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | 사용자의 활성 앱 승인을 나열합니다. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | 특정 앱 승인을 ID로 취소합니다. | + +승인 목록에 대한 선택적 쿼리 매개변수: + +- `appType=firstParty`: 퍼스트 파티 앱 승인만 반환합니다. +- `appType=thirdParty`: 서드 파티 앱 승인만 반환합니다. +- `appType` 생략: 모든 활성 승인을 반환합니다. + +승인이 취소되면, 해당 승인에 대해 이전에 발급된 불투명 액세스 토큰 및 리프레시 토큰이 무효화됩니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index 04893f2fe6c..c02d92d50b4 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,235 +1,101 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # 로그아웃 -Logto( OIDC 아이덴티티 제공자 (IdP)로서 )에서의 로그아웃은 다음 두 가지를 모두 포함합니다: +Logto에서 로그아웃은 두 가지 계층으로 구성됩니다: -- **중앙 집중식 Logto 세션** (Logto 도메인 아래의 브라우저 쿠키) -- **분산된 클라이언트 측 인증 상태** (각 앱의 토큰 및 로컬 앱 세션) +- **Logto 세션 로그아웃**: Logto 도메인 하에서 중앙화된 로그인 세션을 종료합니다. +- **앱 로그아웃**: 클라이언트 애플리케이션에서 로컬 세션 상태와 토큰을 지웁니다. -로그아웃 동작을 이해하려면 이 두 계층을 분리해서 보고, **grant**가 이 둘을 어떻게 연결하는지 살펴보는 것이 도움이 됩니다. - -## 핵심 개념 \{#core-concepts} - -### Logto 세션이란? \{#what-is-a-logto-session} - -Logto 세션은 Logto가 관리하는 중앙 집중식 로그인 상태입니다. 인증 (Authentication)에 성공한 후 생성되며, Logto 도메인 아래의 쿠키로 표현됩니다. - -세션 쿠키가 유효하다면, 사용자는 동일한 Logto 테넌트를 신뢰하는 여러 앱에서 조용히 인증 (SSO)될 수 있습니다. - -유효한 세션이 없다면, Logto는 로그인 페이지를 표시합니다. - -### grant란 무엇인가요? \{#what-are-grants} - -**grant**는 특정 사용자 + 클라이언트 애플리케이션 조합에 대한 인가 (Authorization) 상태를 나타냅니다. - -- 하나의 Logto 세션은 여러 클라이언트 앱에 대한 grant를 가질 수 있습니다. -- grant는 발급된 토큰이 연결되는 단위입니다. -- 이 문서 세트에서는 **grant**를 앱 간 인가 단위로 사용합니다. - -### 세션, grant, 클라이언트 인증 상태의 관계 \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto 도메인] - S[Logto 세션] - G1[App A에 대한 grant] - G2[App B에 대한 grant] - end - - subgraph AppA [클라이언트 도메인 A] - A[로컬 세션 / 토큰] - end - - subgraph AppB [클라이언트 도메인 B] - B[로컬 세션 / 토큰] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Logto 세션**은 중앙 집중식 SSO 경험을 제어합니다. -- **클라이언트 로컬 세션/토큰**은 각 앱이 현재 사용자를 로그인 상태로 간주하는지 제어합니다. -- **grant**는 앱별 인가 상태를 나타내며 이 두 세계를 연결합니다. - -## 로그인 요약 (로그아웃이 다계층인 이유) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as 클라이언트 애플리케이션 - end - - box Logto (IdP) - participant OIDC as OIDC 제공자 - participant SignIn as 로그인 페이지 - end - - User ->> Client: 애플리케이션 접근 - Client ->> OIDC: 인증 (Authentication) 위해 리디렉션 - OIDC -->> OIDC: Logto 세션 확인 - OIDC ->> SignIn: 필요 시 로그인 요청 - SignIn ->> OIDC: 사용자 인증 (Authentication) - OIDC -->> OIDC: 세션 및 grant 생성 - OIDC ->> Client: 인가 코드 반환 - Client ->> OIDC: 코드로 토큰 교환 - OIDC -->> Client: 토큰 반환 -``` - -## 앱/디바이스 간 세션 토폴로지 \{#session-topology-across-apps-devices} - -### 공유 세션 쿠키 (동일 브라우저/유저 에이전트) \{#shared-session-cookie-same-browser-user-agent} - -사용자가 동일 브라우저에서 여러 앱에 로그인하면, 해당 앱들은 동일한 Logto 세션 쿠키를 재사용할 수 있으며 SSO 동작이 적용됩니다. - -```mermaid -flowchart TD - U[사용자] - A["클라이언트 애플리케이션 A (클라이언트 도메인 A)"] - B["클라이언트 애플리케이션 B (클라이언트 도메인 B)"] - C{"Logto 세션 존재? (Logto 도메인)"} - D["로그인 페이지 (Logto 도메인)"] - - subgraph UA["유저 에이전트 A (동일 브라우저)"] - U - A - B - C - D - end - - U -->|로그인| A - A -->|Logto로 리디렉션| C - U -->|앱 열기| B - B -->|Logto로 리디렉션| C - C -->|아니오| D - D -->|세션 생성| C -``` - -### 분리된 세션 쿠키 (다른 디바이스/브라우저) \{#isolated-session-cookies-different-devices-browsers} - -다른 브라우저/디바이스는 서로 다른 Logto 쿠키를 가지므로, 로그인 세션 상태가 분리됩니다. - -```mermaid -flowchart TD - U[사용자] - A["클라이언트 애플리케이션 A (클라이언트 도메인 A)"] - C{"Logto 세션 존재? (디바이스 A, Logto 도메인)"} - D["로그인 페이지 (디바이스 A, Logto 도메인)"] - - subgraph DeviceA["유저 에이전트 A"] - A - C - D - end - - B["클라이언트 애플리케이션 B (클라이언트 도메인 B)"] - E{"Logto 세션 존재? (디바이스 B, Logto 도메인)"} - F["로그인 페이지 (디바이스 B, Logto 도메인)"] - - subgraph DeviceB["유저 에이전트 B"] - B - E - F - end - - U -->|로그인| A - A -->|Logto로 리디렉션| C - U -->|로그인| B - B -->|Logto로 리디렉션| E - C -->|아니오| D - E -->|아니오| F - D -->|세션 생성| C - F -->|세션 생성| E -``` +Logto에서 세션이 어떻게 작동하는지 더 잘 이해하려면 [세션](/sessions)을 참조하세요. ## 로그아웃 메커니즘 \{#sign-out-mechanisms} -### 1) 클라이언트 측 로그아웃만 수행 \{#1-client-side-only-sign-out} +### 1) 클라이언트 측에서만 로그아웃 \{#1-client-side-only-sign-out} -클라이언트 앱이 자체 로컬 세션과 토큰 (ID / 액세스 / 리프레시 토큰)을 삭제합니다. 이는 해당 앱의 로컬 상태에서만 사용자를 로그아웃시킵니다. +클라이언트 앱은 자체 로컬 세션과 토큰 (ID / 액세스 / 리프레시 토큰)을 지웁니다. 이는 사용자를 해당 앱의 로컬 상태에서만 로그아웃시킵니다. -- Logto 세션은 여전히 활성일 수 있습니다. -- 동일 Logto 세션 하의 다른 앱들은 여전히 SSO가 가능합니다. +- Logto 세션은 여전히 활성 상태일 수 있습니다. +- 동일한 Logto 세션 하의 다른 앱은 여전히 SSO를 사용할 수 있습니다. ### 2) Logto에서 세션 종료 (현재 Logto 구현에서의 글로벌 로그아웃) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -중앙 집중식 Logto 세션을 삭제하려면, 앱이 사용자를 end session 엔드포인트로 리디렉션합니다. 예시: +중앙화된 Logto 세션을 지우기 위해, 앱은 사용자를 세션 종료 엔드포인트로 리디렉션합니다. 예를 들어: `https://{your-logto-domain}/oidc/session/end` -현재 Logto SDK 동작: +현재 Logto SDK 동작에서는: 1. `signOut()`이 `/session/end`로 리디렉션합니다. -2. 이후 `/session/end/confirm`으로 이동합니다. -3. 기본 confirm 폼이 `logout=true`로 자동 전송됩니다. +2. 그런 다음 `/session/end/confirm`으로 이동합니다. +3. 기본 확인 양식이 `logout=true`를 자동으로 게시합니다. 결과적으로, 현재 SDK 로그아웃은 **글로벌 로그아웃**으로 처리됩니다. -### 글로벌 로그아웃 시 일어나는 일 \{#what-happens-during-global-sign-out} +:::note + +- **글로벌 로그아웃**: 중앙화된 Logto 세션을 취소합니다. + +::: + +### 글로벌 로그아웃 중에 발생하는 일 \{#what-happens-during-global-sign-out} ```mermaid flowchart TD A["클라이언트가 로그아웃 시작"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["중앙 집중식 Logto 세션 삭제"] - D --> E{"앱별 grant 확인"} - E -->|"offline_access 미부여"| F["grant 삭제"] - E -->|"offline_access 부여됨"| G["grant는 grant TTL 만료 시까지 유지"] + C --> D["중앙화된 Logto 세션 취소"] + D --> E{"앱별 권한 확인"} + E -->|"offline_access가 부여되지 않음"| F["권한 취소"] + E -->|"offline_access가 부여됨"| G["권한 TTL이 만료될 때까지 권한 유지"] ``` 글로벌 로그아웃 중: -- 중앙 집중식 Logto 세션이 삭제됩니다. -- 관련 앱 grant는 앱별 인가 상태에 따라 처리됩니다: - - `offline_access`가 **부여되지 않은 경우**, 관련 grant가 삭제됩니다. - - `offline_access`가 **부여된 경우**, end-session으로 grant가 삭제되지 않습니다. -- `offline_access`의 경우, 리프레시 토큰과 grant는 만료 시점까지 유효합니다. +- 중앙화된 Logto 세션이 취소됩니다. +- 관련 앱 권한은 앱 인가 상태에 따라 처리됩니다: + - `offline_access`가 **부여되지 않은** 경우, 관련 권한이 취소됩니다. + - `offline_access`가 **부여된** 경우, 세션 종료로 권한이 취소되지 않습니다. +- `offline_access`의 경우, 리프레시 토큰과 권한은 권한 만료까지 유효합니다. -## grant 수명 및 `offline_access` 영향 \{#grant-lifetime-and-offline-access-impact} +## 권한 수명과 `offline_access` 영향 \{#grant-lifetime-and-offline-access-impact} -- 기본 Logto grant TTL은 **180일**입니다. -- `offline_access`가 부여된 경우, end-session은 해당 앱 grant를 기본적으로 삭제하지 않습니다. -- 해당 grant와 연결된 리프레시 토큰 체인은 grant가 만료(또는 명시적으로 삭제)될 때까지 계속 유효합니다. +- 기본 Logto 권한 TTL은 **180일**입니다. +- `offline_access`가 부여된 경우, 세션 종료는 기본적으로 해당 앱 권한을 취소하지 않습니다. +- 해당 권한과 관련된 리프레시 토큰 체인은 권한이 만료될 때까지 계속될 수 있습니다 (또는 명시적으로 취소될 때까지). ## 연합 로그아웃: 백채널 로그아웃 \{#federated-sign-out-back-channel-logout} 앱 간 일관성을 위해, Logto는 [백채널 로그아웃](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)을 지원합니다. -한 앱에서 사용자가 로그아웃하면, Logto는 동일 세션에 참여하는 모든 앱에 로그아웃 토큰을 각 앱의 등록된 백채널 로그아웃 URI로 전송할 수 있습니다. +사용자가 한 앱에서 로그아웃할 때, Logto는 동일한 세션에 참여하는 모든 앱에 로그아웃 토큰을 각 앱의 등록된 백채널 로그아웃 URI로 보낼 수 있습니다. -앱 백채널 설정에서 `Is session required`가 활성화된 경우, 로그아웃 토큰에 Logto 세션을 식별하는 `sid`가 포함됩니다. +앱 백채널 설정에서 `Is session required`가 활성화된 경우, 로그아웃 토큰에는 Logto 세션을 식별하기 위한 `sid`가 포함됩니다. 일반적인 흐름: 1. 사용자가 한 앱에서 로그아웃을 시작합니다. -2. Logto가 end-session을 처리하고, 등록된 백채널 로그아웃 URI(들)로 로그아웃 토큰을 전송합니다. -3. 각 앱은 로그아웃 토큰을 검증하고 자체 로컬 세션/토큰을 삭제합니다. +2. Logto가 세션 종료를 처리하고 등록된 백채널 로그아웃 URI로 로그아웃 토큰을 보냅니다. +3. 각 앱은 로그아웃 토큰을 검증하고 자체 로컬 세션 / 토큰을 지웁니다. -## Logto SDK에서의 로그아웃 방식 \{#sign-out-methods-in-logto-sdks} +## Logto SDK에서의 로그아웃 방법 \{#sign-out-methods-in-logto-sdks} -- **SPA 및 웹**: `client.signOut()`은 로컬 토큰 저장소를 삭제하고 Logto end-session 엔드포인트로 리디렉션합니다. 로그아웃 후 리디렉션 URI를 지정할 수 있습니다. -- **네이티브 (React Native / Flutter 포함)**: 일반적으로 로컬 토큰 저장소만 삭제합니다. 세션 없는 웹뷰이므로 삭제할 Logto 브라우저 쿠키가 없습니다. +- **SPA 및 웹**: `client.signOut()`은 로컬 토큰 저장소를 지우고 Logto 세션 종료 엔드포인트로 리디렉션합니다. 로그아웃 후 리디렉션 URI를 제공할 수 있습니다. +- **네이티브 (React Native / Flutter 포함)**: 일반적으로 로컬 토큰 저장소만 지웁니다. 세션 없는 웹뷰는 지울 지속적인 Logto 브라우저 쿠키가 없음을 의미합니다. :::note -세션 없는 웹뷰를 지원하지 않거나 `emphasized` 설정을 인식하지 않는 네이티브 애플리케이션 (예: **React Native** 또는 **Flutter** SDK를 사용하는 Android 앱)의 경우, 인증 요청에 `prompt=login` 파라미터를 추가하여 사용자가 다시 로그인하도록 강제할 수 있습니다. +세션 없는 웹뷰를 지원하지 않거나 `emphasized` 설정을 인식하지 않는 네이티브 애플리케이션 (예: **React Native** 또는 **Flutter** SDK를 사용하는 Android 앱)의 경우, 인가 요청에 `prompt=login` 매개변수를 전달하여 사용자가 다시 로그인하도록 강제할 수 있습니다. ::: -## 매번 재인증 강제하기 \{#enforce-re-authentication-on-every-access} +## 모든 접근 시 재인증 강제 \{#enforce-re-authentication-on-every-access} -보안이 중요한 작업의 경우, 인증 (Authentication) 요청에 `prompt=login`을 포함하여 SSO를 우회하고 매번 자격 증명 입력을 강제할 수 있습니다. +고보안 작업의 경우, 인증 요청에 `prompt=login`을 포함하여 SSO를 우회하고 매번 자격 증명을 입력하도록 강제합니다. -리프레시 토큰을 받기 위해 `offline_access`를 요청하는 경우, `consent`, `prompt=login consent`도 함께 포함하세요. +리프레시 토큰을 받기 위해 `offline_access`를 요청하는 경우, `consent`, `prompt=login consent`도 포함합니다. -일반적인 조합 예시: +일반적인 결합 설정: ```txt prompt=login consent @@ -244,8 +110,8 @@ prompt=login consent -- Logto 대시보드에서 백채널 로그아웃 URI가 올바르게 등록되어 있는지 확인하세요. -- 앱이 동일 사용자/세션 컨텍스트에 대해 활성 로그인 상태인지 확인하세요. +- Logto 대시보드에 백채널 로그아웃 URI가 올바르게 등록되어 있는지 확인하세요. +- 동일한 사용자 / 세션 컨텍스트에 대해 앱에 활성 로그인 상태가 있는지 확인하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 90f6fecf9c0..d2c5bfd19e8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: OIDC 인증 (Authentication) 통합을 위한 주요 애플리케이션 파라미터(리디렉션 URI, 엔드포인트, 리프레시 토큰, 백채널 로그아웃 등)를 참고하세요. +description: 리디렉션 URI, 엔드포인트, 리프레시 토큰, 백채널 로그아웃 등을 포함한 OIDC 인증 통합을 위한 주요 애플리케이션 매개변수를 참조하세요. sidebar_position: 6 --- @@ -7,107 +7,106 @@ sidebar_position: 6 ## 소개 \{#introduction} -Logto에서 *애플리케이션*은 Logto 플랫폼에 등록되어 사용자 정보를 액세스하거나 사용자를 대신하여 작업을 수행할 수 있는 권한을 부여받은 특정 소프트웨어 프로그램 또는 서비스를 의미합니다. 애플리케이션은 Logto API에 대한 요청의 출처를 식별하고, 해당 애플리케이션에 접근하는 사용자의 인증 (Authentication) 및 인가 (Authorization) 과정을 관리하는 데 사용됩니다. +Logto에서 *애플리케이션*은 Logto 플랫폼에 등록되어 사용자 정보를 액세스하거나 사용자를 대신하여 작업을 수행할 수 있는 권한을 부여받은 특정 소프트웨어 프로그램 또는 서비스를 의미합니다. 애플리케이션은 Logto API에 대한 요청의 출처를 식별하고, 해당 애플리케이션에 액세스하는 사용자의 인증 및 인가 과정을 관리하는 데 사용됩니다. -Logto의 로그인 경험에서 애플리케이션을 사용하면 사용자가 하나의 위치에서 자신이 인가 (Authorization)된 애플리케이션을 쉽게 접근하고 관리할 수 있으며, 일관되고 안전한 인증 (Authentication) 과정을 제공합니다. 이를 통해 사용자 경험을 간소화하고, 인가 (Authorization)된 사람만이 민감한 정보에 접근하거나 조직을 대신하여 작업을 수행하도록 보장할 수 있습니다. +Logto의 로그인 경험에서 애플리케이션을 사용하면 사용자가 단일 위치에서 승인된 애플리케이션에 쉽게 액세스하고 관리할 수 있으며, 일관되고 안전한 인증 과정을 제공합니다. 이는 사용자 경험을 간소화하고, 조직을 대신하여 민감한 정보에 액세스하거나 작업을 수행하는 권한이 있는 사람만이 이를 수행하도록 보장합니다. -애플리케이션은 Logto의 감사 로그에서도 사용되어 사용자 활동을 추적하고 잠재적인 보안 위협이나 침해를 식별하는 데 활용됩니다. 특정 작업을 특정 애플리케이션과 연관시킴으로써, Logto는 데이터가 어떻게 접근되고 사용되는지에 대한 상세한 인사이트를 제공하여 조직이 보안 및 컴플라이언스 요구 사항을 더 잘 관리할 수 있도록 합니다. -애플리케이션을 Logto와 통합하고 싶다면 [Logto 통합하기](/integrate-logto)를 참고하세요. +애플리케이션은 또한 Logto의 감사 로그에서 사용자 활동을 추적하고 잠재적인 보안 위협이나 침해를 식별하는 데 사용됩니다. 특정 작업을 특정 애플리케이션과 연결함으로써, Logto는 데이터가 어떻게 액세스되고 사용되는지에 대한 상세한 통찰력을 제공할 수 있으며, 조직이 보안 및 준수 요구 사항을 더 잘 관리할 수 있도록 합니다. 애플리케이션을 Logto와 통합하려면 [Logto 통합](/integrate-logto)을 참조하세요. ## 속성 \{#properties} ### 애플리케이션 ID \{#application-id} -*애플리케이션 ID*는 Logto에서 애플리케이션을 식별하기 위한 고유 자동 생성 키이며, OAuth 2.0에서는 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)로 참조됩니다. +*애플리케이션 ID*는 Logto에서 애플리케이션을 식별하기 위한 고유한 자동 생성 키이며, OAuth 2.0에서 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)로 참조됩니다. ### 애플리케이션 유형 \{#application-types} -*애플리케이션*은 다음 중 하나의 애플리케이션 유형이 될 수 있습니다: +*애플리케이션*은 다음 애플리케이션 유형 중 하나일 수 있습니다: -- **네이티브 앱**: 네이티브 환경에서 실행되는 앱입니다. 예: iOS 앱, Android 앱. - - **디바이스 플로우 앱**: 입력이 제한된 디바이스나 헤드리스 애플리케이션(예: 스마트 TV, 게임 콘솔, CLI 도구, IoT 디바이스)을 위한 특별한 네이티브 앱 유형입니다. 표준 리디렉션 기반 플로우 대신 [OAuth 2.0 디바이스 인가 (Authorization) 그랜트](https://auth.wiki/device-flow)를 사용합니다. 자세한 내용은 [디바이스 플로우 빠른 시작](/quick-starts/device-flow)을 참고하세요. -- **싱글 페이지 앱**: 웹 브라우저에서 실행되며, 서버에서 새로운 데이터를 받아 전체 페이지를 새로 고치지 않고 페이지를 업데이트하는 앱입니다. 예: React DOM 앱, Vue 앱. -- **전통적인 웹 앱**: 웹 서버만으로 페이지를 렌더링하고 업데이트하는 앱입니다. 예: JSP, PHP. -- **기계 간 (M2M) 앱**: 사용자 상호작용 없이 서비스 간 직접 통신을 위해 머신 환경에서 실행되는 애플리케이션입니다. +- **네이티브 앱**은 네이티브 환경에서 실행되는 앱입니다. 예: iOS 앱, Android 앱. + - **디바이스 플로우 앱**은 입력이 제한된 디바이스나 헤드리스 애플리케이션 (예: 스마트 TV, 게임 콘솔, CLI 도구, IoT 디바이스)을 위한 특별한 유형의 네이티브 앱입니다. 표준 리디렉션 기반 플로우 대신 [OAuth 2.0 디바이스 인가 부여](https://auth.wiki/device-flow)를 사용합니다. 자세한 내용은 [디바이스 플로우 빠른 시작](/quick-starts/device-flow)을 참조하세요. +- **싱글 페이지 앱**은 웹 브라우저에서 실행되며, 서버에서 새로운 데이터를 받아 페이지를 업데이트하지만 전체 새로운 페이지를 로드하지 않는 앱입니다. 예: React DOM 앱, Vue 앱. +- **전통적인 웹 앱**은 웹 서버에 의해 페이지를 렌더링하고 업데이트하는 앱입니다. 예: JSP, PHP. +- **기계 간 (M2M) 앱**은 사용자 상호작용 없이 직접 서비스 간 통신을 위한 기계 환경에서 실행되는 애플리케이션입니다. -### 애플리케이션 시크릿 \{#application-secret} +### 애플리케이션 비밀 \{#application-secret} -*애플리케이션 시크릿*은 인증 (Authentication) 시스템에서 애플리케이션을 인증하는 데 사용되는 키로, 특히 프라이빗 클라이언트(전통적인 웹 및 M2M 앱)에서 프라이빗 보안 장벽 역할을 합니다. +*애플리케이션 비밀*은 인증 시스템에서 애플리케이션을 인증하는 데 사용되는 키로, 특히 개인 클라이언트 (전통적인 웹 및 M2M 앱)를 위한 개인 보안 장벽입니다. :::tip -싱글 페이지 앱(SPA)과 네이티브 앱은 App secret을 제공하지 않습니다. SPA와 네이티브 앱은 "공개 클라이언트"이므로 시크릿을 안전하게 보관할 수 없습니다(브라우저 코드나 앱 번들은 누구나 볼 수 있음). App secret 대신, Logto는 PKCE, 엄격한 리디렉션 URI / CORS 검증, 단명 액세스 토큰, 리프레시 토큰 회전을 통해 보호합니다. +싱글 페이지 앱 (SPA) 및 네이티브 앱은 앱 비밀을 제공하지 않습니다. SPA 및 네이티브 앱은 "공개 클라이언트"이며 비밀을 유지할 수 없습니다 (브라우저 코드 또는 앱 번들은 검사 가능합니다). 앱 비밀 대신, Logto는 PKCE, 엄격한 리디렉션 URI / CORS 검증, 단기 액세스 토큰, 리프레시 토큰 회전을 통해 이를 보호합니다. ::: ### 애플리케이션 이름 \{#application-name} *애플리케이션 이름*은 사람이 읽을 수 있는 애플리케이션의 이름이며, 관리자 콘솔에 표시됩니다. -*애플리케이션 이름*은 Logto에서 애플리케이션을 관리하는 데 중요한 요소로, 관리자가 플랫폼 내에서 개별 애플리케이션의 활동을 쉽게 식별하고 추적할 수 있게 해줍니다. +*애플리케이션 이름*은 Logto에서 애플리케이션을 관리하는 중요한 구성 요소로, 관리자가 플랫폼 내에서 개별 애플리케이션의 활동을 쉽게 식별하고 추적할 수 있도록 합니다. :::note -*애플리케이션 이름*은 관리자 콘솔에 접근할 수 있는 모든 사용자에게 표시되므로 신중하게 선택해야 합니다. 애플리케이션의 목적과 기능을 정확하게 반영하면서도 이해하기 쉽고 인식하기 쉬워야 합니다. +*애플리케이션 이름*은 관리자 콘솔에 액세스할 수 있는 모든 사용자에게 표시되므로 신중하게 선택해야 합니다. 애플리케이션의 목적과 기능을 정확하게 반영해야 하며, 이해하고 인식하기 쉬워야 합니다. ::: ### 설명 \{#description} -애플리케이션에 대한 간단한 설명이 관리자 콘솔의 애플리케이션 상세 페이지에 표시됩니다. 설명은 애플리케이션의 목적, 기능, 기타 관련 세부 정보를 관리자가 추가로 파악할 수 있도록 제공됩니다. +애플리케이션에 대한 간단한 설명이 관리자 콘솔 애플리케이션 세부 정보 페이지에 표시됩니다. 설명은 애플리케이션의 목적, 기능 및 기타 관련 세부 정보를 관리자가 추가로 제공받을 수 있도록 합니다. ### 리디렉션 URI \{#redirect-uris} -*리디렉션 URI*는 애플리케이션에 대해 미리 구성된 유효한 리디렉션 URI 목록입니다. 사용자가 Logto에 로그인하고 애플리케이션에 접근하려고 할 때, 애플리케이션 설정에 지정된 허용된 URI 중 하나로 리디렉션됩니다. +*리디렉션 URI*는 애플리케이션에 대해 사전 구성된 유효한 리디렉션 URI 목록입니다. 사용자가 Logto에 로그인하고 애플리케이션에 액세스하려고 할 때, 애플리케이션 설정에 지정된 허용된 URI 중 하나로 리디렉션됩니다. -허용된 URI 목록은 인증 (Authentication) 과정에서 애플리케이션이 Logto에 보낸 인가 (Authorization) 요청에 포함된 리디렉션 URI를 검증하는 데 사용됩니다. 인가 (Authorization) 요청에 지정된 리디렉션 URI가 애플리케이션 설정의 허용된 URI 중 하나와 일치하면, 인증 (Authentication)에 성공한 후 해당 URI로 사용자가 리디렉션됩니다. 리디렉션 URI가 허용 목록에 없으면, 사용자는 리디렉션되지 않으며 인증 (Authentication) 과정이 실패합니다. +허용된 URI 목록은 인증 과정에서 애플리케이션이 Logto에 보낸 인가 요청에 포함된 리디렉션 URI를 검증하는 데 사용됩니다. 인가 요청에 지정된 리디렉션 URI가 애플리케이션 설정의 허용된 URI 중 하나와 일치하면, 성공적인 인증 후 사용자는 해당 URI로 리디렉션됩니다. 리디렉션 URI가 허용된 목록에 없으면, 사용자는 리디렉션되지 않으며 인증 과정이 실패합니다. :::note -모든 유효한 리디렉션 URI가 Logto의 애플리케이션 허용 목록에 추가되어야, 인증 (Authentication) 후 사용자가 애플리케이션에 정상적으로 접근할 수 있습니다. +모든 유효한 리디렉션 URI가 Logto의 애플리케이션에 대한 허용 목록에 추가되어야 사용자가 인증 후 애플리케이션에 성공적으로 액세스할 수 있습니다. ::: -[Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2)에서 자세한 정보를 확인할 수 있습니다. +[리디렉션 엔드포인트](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2)를 참조하여 더 많은 정보를 확인할 수 있습니다. - OIDC에서 인가 코드 플로우의 리디렉션 URI 이해하기 + 인가 코드 플로우에서 OIDC의 리디렉션 URI 이해하기 #### 와일드카드 패턴 \{#wildcard-patterns} -_적용 대상: 싱글 페이지 앱, 전통적인 웹 앱_ +_사용 가능: 싱글 페이지 앱, 전통적인 웹 앱_ -리디렉션 URI는 프리뷰 배포 등 동적 환경을 위해 와일드카드 패턴(`*`)을 지원합니다. 와일드카드는 HTTP/HTTPS URI의 호스트명과 경로명(pathname) 구성요소에서 사용할 수 있습니다. +리디렉션 URI는 미리보기 배포와 같은 동적 환경을 위해 와일드카드 패턴 (`*`)을 지원합니다. 와일드카드는 HTTP / HTTPS URI의 호스트명 및 경로명 구성 요소에서 사용할 수 있습니다. **규칙:** -- 와일드카드는 호스트명과 경로명에만 허용됩니다. -- 스킴, 포트, 쿼리 파라미터, 해시 프래그먼트에는 와일드카드를 사용할 수 없습니다. -- 호스트명 와일드카드는 반드시 점(.)을 하나 이상 포함해야 합니다(예: `https://*.example.com/callback`). +- 와일드카드는 호스트명 및 경로명에서만 허용됩니다. +- 와일드카드는 스킴, 포트, 쿼리 매개변수 또는 해시 조각에서는 허용되지 않습니다. +- 호스트명 와일드카드는 최소한 하나의 점을 포함해야 합니다 (예: `https://*.example.com/callback`). **예시:** -- `https://*.example.com/callback` - 모든 서브도메인에 매칭 -- `https://preview-*.example.com/callback` - 프리뷰 배포에 매칭 -- `https://example.com/*/callback` - 모든 경로 세그먼트에 매칭 +- `https://*.example.com/callback` - 모든 하위 도메인과 일치 +- `https://preview-*.example.com/callback` - 미리보기 배포와 일치 +- `https://example.com/*/callback` - 모든 경로 세그먼트와 일치 :::caution -와일드카드 리디렉션 URI는 표준 OIDC가 아니며 공격 표면을 넓힐 수 있습니다. 반드시 필요한 경우에만 사용하고, 가능하면 정확한 리디렉션 URI를 사용하는 것이 좋습니다. +와일드카드 리디렉션 URI는 표준 OIDC가 아니며 공격 표면을 증가시킬 수 있습니다. 가능한 경우 정확한 리디렉션 URI를 선호하고 주의해서 사용하세요. ::: ### 로그아웃 후 리디렉션 URI \{#post-sign-out-redirect-uris} -*로그아웃 후 리디렉션 URI*는 사용자가 Logto에서 로그아웃한 후 리디렉션될 수 있도록 애플리케이션에 미리 구성된 유효한 URI 목록입니다. +*로그아웃 후 리디렉션 URI*는 Logto에서 로그아웃한 후 사용자를 리디렉션하기 위해 애플리케이션에 대해 사전 구성된 유효한 URI 목록입니다. -허용된 _로그아웃 후 리디렉션 URI_ 사용은 OIDC의 RP-Initiated(신뢰 당사자 시작) 로그아웃 명세의 일부입니다. 이 명세는 애플리케이션이 사용자를 위한 로그아웃 요청을 시작하고, 로그아웃 후 미리 구성된 엔드포인트로 사용자를 리디렉션하는 표준화된 방법을 제공합니다. +로그아웃을 위한 허용된 *로그아웃 후 리디렉션 URI*의 사용은 OIDC의 RP-Initiated (Relying Party Initiated) 로그아웃 사양의 일부입니다. 이 사양은 사용자를 위한 로그아웃 요청을 시작하고, 로그아웃 후 사용자를 사전 구성된 엔드포인트로 리디렉션하는 표준화된 방법을 제공합니다. -사용자가 Logto에서 로그아웃하면 세션이 종료되고, 애플리케이션 설정에 지정된 허용된 URI 중 하나로 리디렉션됩니다. 이를 통해 사용자가 로그아웃 후 인가 (Authorization)된 유효한 엔드포인트로만 이동하도록 하여, 알 수 없거나 검증되지 않은 엔드포인트로의 리디렉션과 관련된 무단 접근 및 보안 위험을 방지할 수 있습니다. +사용자가 Logto에서 로그아웃하면, 세션이 종료되고 애플리케이션 설정에 지정된 허용된 URI 중 하나로 리디렉션됩니다. 이는 사용자가 로그아웃 후 승인된 유효한 엔드포인트로만 리디렉션되도록 하여, 알 수 없거나 검증되지 않은 엔드포인트로 사용자를 리디렉션하는 것과 관련된 무단 액세스 및 보안 위험을 방지합니다. -[RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout)에서 자세한 정보를 확인할 수 있습니다. +[RP-initiated 로그아웃](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout)을 참조하여 더 많은 정보를 확인할 수 있습니다. -### CORS 허용 오리진 \{#cors-allowed-origins} +### CORS 허용된 출처 \{#cors-allowed-origins} -*CORS (교차 출처 리소스 공유) 허용 오리진*은 애플리케이션이 Logto 서비스에 요청을 보낼 수 있도록 허용된 오리진 목록입니다. 허용 목록에 포함되지 않은 오리진에서는 Logto 서비스에 요청을 보낼 수 없습니다. +*CORS (Cross-origin resource sharing) 허용된 출처*는 애플리케이션이 Logto 서비스에 요청을 보낼 수 있는 허용된 출처 목록입니다. 허용된 목록에 포함되지 않은 출처는 Logto 서비스에 요청을 보낼 수 없습니다. -CORS 허용 오리진 목록은 무단 도메인에서 Logto 서비스에 접근하는 것을 제한하고, 교차 사이트 요청 위조(CSRF) 공격을 방지하는 데 도움이 됩니다. Logto에서 애플리케이션의 허용 오리진을 지정함으로써, 인가 (Authorization)된 도메인만 서비스에 요청을 보낼 수 있도록 보장할 수 있습니다. +CORS 허용된 출처 목록은 무단 도메인으로부터 Logto 서비스에 대한 액세스를 제한하고, 교차 사이트 요청 위조 (CSRF) 공격을 방지하는 데 사용됩니다. Logto에서 애플리케이션에 대한 허용된 출처를 지정함으로써, 서비스는 승인된 도메인만이 서비스에 요청을 보낼 수 있도록 보장할 수 있습니다. :::note -허용 오리진 목록에는 애플리케이션이 서비스되는 오리진이 포함되어야 합니다. 이를 통해 애플리케이션의 요청은 허용되고, 무단 오리진의 요청은 차단됩니다. +허용된 출처 목록에는 애플리케이션이 제공될 출처가 포함되어야 합니다. 이는 애플리케이션의 요청이 허용되고, 무단 출처의 요청은 차단되도록 보장합니다. ::: ### OpenID 제공자 구성 엔드포인트 \{#openid-provider-configuration-endpoint} @@ -116,69 +115,88 @@ CORS 허용 오리진 목록은 무단 도메인에서 Logto 서비스에 접근 ### 인가 엔드포인트 \{#authorization-endpoint} -*인가 엔드포인트*는 OIDC 용어로, 사용자의 인증 (Authentication) 과정을 시작하는 데 사용되는 필수 엔드포인트입니다. 사용자가 Logto 플랫폼에 등록된 보호된 리소스 또는 애플리케이션에 접근하려고 하면, *인가 엔드포인트*로 리디렉션되어 아이덴티티를 인증 (Authentication)하고 요청된 리소스에 접근할 인가 (Authorization)를 받게 됩니다. +*인가 엔드포인트*는 OIDC 용어로, 사용자의 인증 과정을 시작하는 데 사용되는 필수 엔드포인트입니다. 사용자가 Logto 플랫폼에 등록된 보호된 리소스 또는 애플리케이션에 액세스하려고 할 때, 그들은 *인가 엔드포인트*로 리디렉션되어 자신의 아이덴티티를 인증하고 요청된 리소스에 대한 인가를 얻습니다. -[Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint)에서 자세한 정보를 확인할 수 있습니다. +[인가 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint)를 참조하여 더 많은 정보를 확인할 수 있습니다. ### 토큰 엔드포인트 \{#token-endpoint} -*토큰 엔드포인트*는 OIDC 용어로, OIDC 클라이언트가 OIDC 제공자로부터 액세스 토큰, ID 토큰, 리프레시 토큰을 얻기 위해 사용하는 웹 API 엔드포인트입니다. +*토큰 엔드포인트*는 OIDC 용어로, OIDC 클라이언트가 OIDC 제공자로부터 액세스 토큰, ID 토큰 또는 리프레시 토큰을 얻기 위해 사용하는 웹 API 엔드포인트입니다. -OIDC 클라이언트가 액세스 토큰이나 ID 토큰을 얻어야 할 때, 인가 (Authorization) 그랜트(일반적으로 인가 코드 또는 리프레시 토큰)와 함께 토큰 엔드포인트에 요청을 보냅니다. 토큰 엔드포인트는 인가 (Authorization) 그랜트를 검증하고, 유효하다면 클라이언트에 액세스 토큰이나 ID 토큰을 발급합니다. +OIDC 클라이언트가 액세스 토큰 또는 ID 토큰을 얻어야 할 때, 인가 코드 또는 리프레시 토큰과 같은 인가 부여와 함께 토큰 엔드포인트에 요청을 보냅니다. 토큰 엔드포인트는 인가 부여를 검증하고, 부여가 유효한 경우 클라이언트에게 액세스 토큰 또는 ID 토큰을 발급합니다. -[Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint)에서 자세한 정보를 확인할 수 있습니다. +[토큰 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint)를 참조하여 더 많은 정보를 확인할 수 있습니다. -### Userinfo 엔드포인트 \{#userinfo-endpoint} +### 사용자 정보 엔드포인트 \{#userinfo-endpoint} -OpenID Connect [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). +OpenID Connect [사용자 정보 엔드포인트](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). ### 항상 리프레시 토큰 발급 \{#always-issue-refresh-token} -_적용 대상: 전통적인 웹, SPA_ +_사용 가능: 전통적인 웹, SPA_ -활성화하면, 인증 (Authentication) 요청에 `prompt=consent`가 포함되지 않거나, 스코프에 `offline_access`가 포함되지 않아도 Logto는 항상 리프레시 토큰을 발급합니다. +활성화되면, Logto는 인증 요청에 `prompt=consent`가 표시되지 않거나 스코프에 `offline_access`가 표시되지 않더라도 항상 리프레시 토큰을 발급합니다. -그러나 이 방식은 OpenID Connect와 호환되지 않으며, 일부 써드파티 OAuth 통합(리프레시 토큰이 필요한 경우)에만 필요하므로, 꼭 필요한 경우가 아니면 권장하지 않습니다. +그러나 이 관행은 필요하지 않는 한 권장되지 않습니다 (일반적으로 리프레시 토큰이 필요한 일부 타사 OAuth 통합에 유용함). 이는 OpenID Connect와 호환되지 않으며 잠재적으로 문제를 일으킬 수 있습니다. ### 리프레시 토큰 회전 \{#rotate-refresh-token} _기본값: `true`_ -활성화하면, Logto는 다음 조건 중 하나에 해당하는 경우 토큰 요청 시 새로운 리프레시 토큰을 발급합니다: +활성화되면, Logto는 다음 조건에서 토큰 요청에 대해 새로운 리프레시 토큰을 발급합니다: -- 리프레시 토큰이 1년 동안 회전(새 토큰 발급으로 TTL 연장)된 경우; **또는** -- 리프레시 토큰이 만료 시간에 가까워진 경우(원래 TTL의 70% 이상 경과); **또는** -- 클라이언트가 공개 클라이언트(예: 네이티브 애플리케이션 또는 싱글 페이지 애플리케이션(SPA))인 경우. +- 리프레시 토큰이 1년 동안 회전된 경우 (TTL이 연장되어 새로운 토큰이 발급됨); **또는** +- 리프레시 토큰이 만료 시간에 가까운 경우 (원래 TTL의 70% 이상 경과됨); **또는** +- 클라이언트가 공개 클라이언트인 경우, 예: 네이티브 애플리케이션 또는 싱글 페이지 애플리케이션 (SPA). :::note -공개 클라이언트의 경우, 이 기능이 활성화되어 있으면 리프레시 토큰으로 새로운 액세스 토큰을 교환할 때마다 항상 새로운 리프레시 토큰이 발급됩니다. -공개 클라이언트에서도 이 기능을 비활성화할 수 있지만, 보안상의 이유로 활성화 상태를 유지하는 것이 강력히 권장됩니다. +공개 클라이언트의 경우, 이 기능이 활성화되면 클라이언트가 리프레시 토큰을 사용하여 새로운 액세스 토큰을 교환할 때마다 항상 새로운 리프레시 토큰이 발급됩니다. +이러한 공개 클라이언트에 대해 기능을 비활성화할 수 있지만, 보안상의 이유로 활성화 상태를 유지하는 것이 강력히 권장됩니다. ::: 리프레시 토큰 회전 이해하기 -### 리프레시 토큰 TTL(유효 기간, 일 단위) \{#refresh-token-time-to-live-ttl-in-days} +### 리프레시 토큰의 TTL (Time-to-live) 일수 \{#refresh-token-time-to-live-ttl-in-days} -_적용 대상: SPA 제외; 기본값: 14일_ +_사용 가능: SPA 제외; 기본값: 14일_ -리프레시 토큰이 만료되어 무효화되기 전까지 새로운 액세스 토큰을 요청할 수 있는 기간입니다. 토큰 요청 시 리프레시 토큰의 TTL이 이 값으로 연장됩니다. +리프레시 토큰이 만료되어 무효화되기 전에 새로운 액세스 토큰을 요청할 수 있는 기간입니다. 토큰 요청은 리프레시 토큰의 TTL을 이 값으로 연장합니다. 일반적으로 더 낮은 값이 선호됩니다. -참고: SPA(싱글 페이지 앱)에서는 보안상의 이유로 TTL 연장이 불가능합니다. 즉, Logto는 토큰 요청을 통해 TTL을 연장하지 않습니다. 사용자 경험을 개선하려면 "리프레시 토큰 회전" 기능을 활성화하여 필요 시 Logto가 새로운 리프레시 토큰을 발급하도록 할 수 있습니다. +참고: 보안상의 이유로 SPA (싱글 페이지 앱)에서는 TTL 갱신이 불가능합니다. 이는 Logto가 토큰 요청을 통해 TTL을 연장하지 않음을 의미합니다. 사용자 경험을 향상시키기 위해 "리프레시 토큰 회전" 기능을 활성화하여 필요할 때 Logto가 새로운 리프레시 토큰을 발급할 수 있도록 할 수 있습니다. :::caution 리프레시 토큰과 세션 바인딩 -인가 (Authorization) 요청에 `offline_access` 스코프 없이 리프레시 토큰이 발급된 경우, 해당 토큰은 사용자 세션에 바인딩됩니다. 세션의 TTL은 **14일**로 고정되어 있습니다. 세션이 만료되면, 리프레시 토큰은 자체 TTL 설정과 무관하게 무효화됩니다. +인가 요청에서 `offline_access` 스코프 없이 리프레시 토큰이 발급되면, 사용자 세션에 바인딩됩니다. 세션은 **14일**의 고정 TTL을 가집니다. 세션이 만료되면, 리프레시 토큰은 자체 TTL 설정과 관계없이 무효화됩니다. -리프레시 토큰 TTL 설정이 제대로 적용되도록 하려면, 인가 (Authorization) 요청에 반드시 `offline_access` 스코프를 포함하세요. +리프레시 토큰 TTL 설정이 완전히 적용되도록 하려면, 인가 요청에 `offline_access` 스코프를 포함해야 합니다. ::: ### 백채널 로그아웃 URI \{#backchannel-logout-uri} -OpenID Connect 백채널 로그아웃 엔드포인트입니다. 자세한 내용은 [연합 로그아웃: 백채널 로그아웃](#)을 참고하세요. +OpenID Connect 백채널 로그아웃 엔드포인트입니다. 자세한 내용은 [연합 로그아웃: 백채널 로그아웃](#)을 참조하세요. -### 커스텀 데이터 \{#custom-data} +### 허용된 최대 부여 (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} -사전 정의된 애플리케이션 속성에 포함되지 않은 추가 커스텀 애플리케이션 정보로, 사용자는 비즈니스별 설정 및 구성 등 특정 요구에 따라 자체 커스텀 데이터 필드를 정의할 수 있습니다. +`maxAllowedGrants`는 `customClientMetadata` 아래의 선택적 앱 수준 필드로, 현재 앱에 대한 사용자당 최대 동시 활성 부여 수를 제어합니다. + +- **기본값**: `undefined` (제한 없음) +- **구성된 경우**: 각 성공적인 인가 시, Logto는 현재 앱에서 사용자의 총 활성 부여 수를 확인합니다 (브라우저 및 디바이스 전반에 걸쳐). 제한을 초과하면, Logto는 가장 오래된 부여를 취소합니다. + +이 설정은 앱당 동시 인증된 디바이스를 제한하고자 할 때 유용합니다. + +:::note + +이 필드는 다음에 대해 지원되지 않습니다: + +- 기계 간 앱 +- 보호된 앱 +- SAML 앱 + +::: + +### 사용자 정의 데이터 \{#custom-data} + +미리 정의된 애플리케이션 속성에 나열되지 않은 추가 사용자 정의 애플리케이션 정보로, 사용자는 비즈니스별 설정 및 구성과 같은 특정 요구에 따라 사용자 정의 데이터 필드를 정의할 수 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..a77e2e94d3f --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,168 @@ +# 세션 + +Logto에서 세션은 인증 상태가 앱, 브라우저, 장치 간에 어떻게 생성, 공유, 갱신, 취소되는지를 정의합니다. + +실제로 사용자는 "로그인됨"이라는 하나의 상태를 경험하지만, 시스템 상태는 여러 계층으로 나뉩니다. 이러한 계층을 이해하는 것이 예측 가능한 싱글 사인온 (SSO), 토큰 갱신, 로그아웃 동작을 설계하는 열쇠입니다. + +## Logto의 세션 모델 \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto 도메인"] + S["로그인 세션"] + G1["Grant (앱 A)"] + G2["Grant (앱 B)"] + end + + subgraph AppA ["앱 도메인 A"] + A["로컬 세션 / 토큰"] + end + + subgraph AppB ["앱 도메인 B"] + B["로컬 세션 / 토큰"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto 로그인 세션**: Logto 도메인 쿠키로 저장된 중앙 집중식 로그인 상태입니다. 이는 현재 브라우저 컨텍스트에서 SSO 사용 가능성을 제어합니다. +- **Grant**: `사용자 + 클라이언트 앱`에 대한 앱별 인가 상태입니다. Grant는 중앙 집중식 로그인과 앱 토큰 발급 간의 다리 역할을 합니다. +- **앱 로컬 세션/토큰**: 각 앱의 로컬 인증 상태 (ID / 액세스 / 리프레시 토큰, 앱 세션 쿠키 등)입니다. + +## 핵심 개념 \{#core-concepts} + +### Logto 세션이란 무엇인가요? \{#what-is-a-logto-session} + +Logto 세션은 성공적인 로그인 후 생성되는 중앙 집중식 인증 상태입니다. 여전히 유효하다면, Logto는 동일한 테넌트 내의 다른 앱에 대해 사용자를 조용히 인증할 수 있습니다. 존재하지 않는 경우, 사용자는 다시 로그인해야 합니다. + +### Grant란 무엇인가요? \{#what-are-grants} + +Grant는 특정 사용자와 클라이언트 앱에 연결된 앱 수준의 인가 상태입니다. + +- 하나의 Logto 세션은 여러 앱에 대한 Grant를 가질 수 있습니다. +- 앱에 대한 토큰은 해당 앱의 Grant 하에 발급됩니다. +- Grant를 취소하면 해당 앱의 토큰 기반 접근 능력에 영향을 미칩니다. + +### 세션, Grant, 앱 인증 상태의 관계 \{#how-session-grants-and-app-auth-state-relate} + +- **세션**은 "이 브라우저가 지금 Logto와 SSO를 할 수 있는가?"에 답합니다. +- **Grant**는 "이 사용자가 이 클라이언트 앱에 대해 인가되었는가?"에 답합니다. +- **앱 로컬 세션**은 "이 앱이 현재 사용자를 로그인된 상태로 취급하는가?"에 답합니다. + +## 로그인 및 세션 생성 \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as 클라이언트 애플리케이션 + end + + box Logto + participant OIDC as OIDC 제공자 + participant SignIn as 로그인 페이지 + end + + User ->> Client: 애플리케이션 접근 + Client ->> OIDC: 인가 요청 + OIDC -->> OIDC: 기존 Logto 세션 확인 + OIDC ->> SignIn: 필요 시 로그인 요청 + SignIn ->> OIDC: 사용자 인증 + OIDC -->> OIDC: 세션 및 앱 Grant 생성 + OIDC ->> Client: 인가 코드 반환 + Client ->> OIDC: 코드로 토큰 교환 + OIDC -->> Client: 토큰 반환 +``` + +## 앱 및 장치 간의 세션 토폴로지 \{#session-topology-across-apps-and-devices} + +### 동일한 브라우저: 공유된 Logto 세션 \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[사용자] + A["클라이언트 앱 A"] + B["클라이언트 앱 B"] + C{"Logto 세션이 존재합니까?"} + D["Logto 로그인 페이지"] + + U --> A + A --> C + U --> B + B --> C + C -->|아니오| D +``` + +동일한 브라우저의 앱은 중앙 집중식 Logto 세션 상태를 공유할 수 있으므로, 반복적인 자격 증명 입력 없이 SSO가 가능합니다. + +### 다른 브라우저 또는 장치: 분리된 Logto 세션 \{#different-browsers-or-devices-isolated-logto-sessions} + +각 브라우저 / 장치는 별도의 쿠키 저장소를 가집니다. 장치 A에서 유효한 세션이 장치 B에서 유효한 세션을 의미하지는 않습니다. + +## 세션 수명 주기 \{#session-lifecycle} + +### 1. 생성 \{#1-create} + +사용자 인증 후, Logto는 중앙 집중식 세션과 앱별 Grant를 생성합니다. + +### 2. 재사용 (SSO) \{#2-reuse-sso} + +동일한 브라우저에서 세션 쿠키가 유효한 한, 새로운 인가 요청은 종종 조용히 완료될 수 있습니다. + +### 3. 토큰 갱신 \{#3-renew-tokens} + +앱 접근은 일반적으로 토큰 갱신 흐름을 통해 계속됩니다 (활성화된 경우). 이는 중앙 집중식 Logto 세션이 여전히 존재하는지 여부와는 별개로 앱 수준의 연속성입니다. + +### 4. 취소 / 만료 \{#4-revokeexpire} + +취소는 다양한 계층에서 발생할 수 있습니다: + +- 로컬 앱 로그아웃은 앱 로컬 토큰 / 세션을 제거합니다. +- 세션 종료는 중앙 집중식 Logto 세션을 제거합니다. +- Grant 취소는 앱 수준의 인가 연속성을 제거합니다. + +## 설계 권장 사항 \{#design-recommendations} + +- 앱 로컬 세션 처리를 앱 코드에서 명시적으로 유지하세요. +- Logto 세션, Grant, 앱 로컬 세션을 별도의 계층으로 취급하세요. +- 로그아웃이 앱 로컬만인지 글로벌인지 선택하세요. +- 여러 앱의 일관성을 요구할 때 [백채널 로그아웃](/end-user-flows/sign-out#federated-sign-out-back-channel-logout)을 사용하세요. +- 로그아웃 동작 및 구현 세부 사항은 [로그아웃](/end-user-flows/sign-out)을 참조하세요. + +## 접근 취소를 위한 모범 사례 \{#best-practices-for-revoking-access} + +목표에 따라 다른 취소 전략을 사용하세요: + +- **자사 앱에서 접근 취소**: + `revokeGrantsTarget=firstParty`로 대상 세션을 취소하세요. + 이는 해당 세션과 연결된 자사 앱 전반에서 사용자를 로그아웃시켜 일관된 로그아웃 경험을 만듭니다. + 동시에, `offline_access`가 부여된 타사 앱에 대한 Grant는 계속 사용할 수 있습니다. + 세션 취소 세부 사항은 [사용자 세션 관리](/sessions/manage-user-sessions)를 참조하세요. + +- **타사 앱에 대한 접근 취소**: + 다음 중 하나를 선택하세요: + + - `revokeGrantsTarget=all`로 세션을 취소하여 해당 세션과 연결된 모든 Grant를 취소합니다. + - Grant 관리 API를 통해 특정 Grant를 직접 취소하여 전체 세션 로그아웃을 강제하지 않고 타사 앱 인가를 제거합니다. + Grant별 취소 전략은 [사용자 인가 앱 (Grant) 관리](/sessions/grants-management)를 참조하세요. + +- **Logto 콘솔 사용 시**: + 사용자 세부 정보 페이지에서 Logto는 기본적으로 세션 관리 및 인가된 타사 앱 관리를 제공합니다. + - 세션을 취소하면 자사 앱 Grant도 취소되어 자사 로그아웃 동작이 일관되게 유지됩니다. + - 타사 앱 인가를 취소하면 해당 타사 앱에 대한 Grant가 취소되며, 원래 세션 상태는 변경되지 않습니다. + +## 관련 리소스 \{#related-resources} + +사용자 세션 관리 +사용자 인가 앱 (Grant) 관리 +세션 구성 +로그아웃 +회원가입 및 로그인 + + 인증 흐름 이해하기 + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..1651f7a5a3e --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# 사용자 승인 앱 (권한) 관리 + +앱 권한은 특정 클라이언트 애플리케이션에 대한 사용자 인가 상태를 나타냅니다. + +사용자나 관리자가 승인된 앱을 검토하고 전체 Logto 세션을 취소하지 않고 앱 접근을 취소해야 할 때 권한 관리를 사용하세요. + +권한이 취소되면, 해당 권한에 대해 이전에 발급된 불투명 액세스 토큰과 리프레시 토큰이 무효화됩니다. + +## 올바른 경로 선택하기 \{#choose-the-right-path} + +| 시나리오 | 권장 경로 | +| ------------------------------------------------------- | -------------- | +| 로그인한 사용자가 자신의 앱 인가를 관리하도록 허용 | Account API | +| 관리자나 지원 팀이 특정 사용자의 권한을 관리하도록 허용 | Management API | +| 운영자가 UI에서 타사 앱 인가를 관리하도록 허용 | Admin Console | + +## 직접 권한 관리 API \{#direct-grant-management-apis} + +### Account API (셀프 서비스) \{#account-api-self-service} + +최종 사용자 계정 설정 페이지에서 Account API를 사용하세요: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- 참고: [사용자 승인 앱 (권한) 관리](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (관리 도구) \{#management-api-admin-tools} + +관리 도구 및 지원 워크플로우에서 Management API를 사용하세요: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- 참고: [사용자 승인 앱 (권한) 관리](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### 앱 유형별 권한 목록 필터링 \{#filter-grant-list-by-app-type} + +권한 목록 엔드포인트는 선택적 쿼리 매개변수 `appType`을 지원합니다: + +- `appType=firstParty`: 퍼스트 파티 앱 권한만 나열합니다. +- `appType=thirdParty`: 타사 앱 권한만 나열합니다. +- `appType`을 생략: 모든 활성 권한을 반환합니다. + +## 콘솔에서 타사 앱 인가 관리 \{#manage-third-party-app-authorizations-in-console} + +Logto Console에서 사용자 세부 정보 페이지를 사용하여 승인된 타사 앱을 보고 취소할 수 있습니다. + +- 참고: [사용자 승인 타사 앱 관리](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## 세션 취소 시 권한 취소 \{#revoke-grants-when-revoking-a-session} + +`DELETE /api/my-account/sessions/{sessionId}`를 통해 세션을 취소할 때, 선택적 쿼리 매개변수 `revokeGrantsTarget`을 사용하여 권한 취소 범위를 제어하세요: + +- `all`: 세션과 관련된 모든 앱에 대한 권한을 취소합니다. +- `firstParty`: 퍼스트 파티 앱에 대한 권한만 취소합니다. + +세션 수준의 동작 및 엔드포인트 컨텍스트에 대해서는 [사용자 세션 관리](/sessions/manage-user-sessions) 및 [로그아웃](/end-user-flows/sign-out)을 참조하세요. + +## 관련 리소스 \{#related-resources} + +세션 +사용자 세션 관리 + + Account API에 의한 계정 설정: 사용자 승인 앱 (권한) 관리 + + + Management API에 의한 계정 설정: 사용자 승인 앱 (권한) 관리 + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..bdbca281037 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# 사용자 세션 관리 + +사용자 세션 관리는 사용자와 관리자가 활성 로그인 상태를 검토하고 필요할 때 세션을 취소할 수 있도록 도와줍니다. + +Logto에서는 세 가지 일반적인 경로를 통해 세션을 관리할 수 있습니다: + +- **Account API**: 제품 계정 설정 페이지에서 최종 사용자가 직접 관리할 수 있도록 합니다. +- **Management API**: 관리자 또는 지원 도구가 특정 사용자의 세션을 관리할 수 있도록 합니다. +- **Admin Console**: Logto Console에서 사용자 정의 도구를 구축하지 않고 운영자 워크플로우를 지원합니다. + +## 적절한 API 선택하기 \{#choose-the-right-api} + +| 시나리오 | 추천 API | +| ------------------------------------------------------ | -------------- | +| 로그인한 사용자가 자신의 활성 세션을 관리하도록 허용 | Account API | +| 관리자나 지원 팀이 사용자의 세션을 관리하도록 허용 | Management API | +| 운영자가 Logto Console에서 직접 세션을 관리하도록 허용 | Admin Console | + +## 활성 세션 보기 \{#view-active-sessions} + +### Account API (셀프 서비스) \{#account-api-self-service} + +Account API 세션 엔드포인트를 사용하여 현재 사용자의 활성 세션을 나열합니다. + +- 참조 섹션: [사용자 세션 관리](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 엔드포인트: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +이 기능을 최종 사용자에게 노출하기 전에, Account center 설정에서 세션 관리가 활성화되어 있고 앱이 필요한 Account API 스코프를 요청하는지 확인하세요. + +### Management API (관리 도구) \{#management-api-admin-tools} + +관리 시스템이 특정 사용자의 세션을 나열해야 할 때 Management API를 사용하세요. + +- 참조 섹션: [사용자 세션 관리](/end-user-flows/account-settings/by-management-api#user-session-management) +- 엔드포인트: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- 선택적 세부 정보 엔드포인트: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## 세션 취소 \{#revoke-sessions} + +### Account API (최종 사용자가 자신의 세션 취소) \{#account-api-end-user-revokes-own-sessions} + +최종 사용자는 자신의 세션 목록에서 특정 세션을 취소할 수 있습니다. + +- 참조 섹션: [사용자 세션 관리](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 엔드포인트: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +민감한 작업의 경우, Account API 세션 관리는 접근 전에 사용자 확인이 필요합니다. [확인 기록 ID 얻기](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id)를 참조하세요. + +### Management API (관리자가 사용자 세션 취소) \{#management-api-admin-revokes-user-sessions} + +관리자는 사용자 ID와 세션 ID를 통해 특정 사용자의 세션을 취소할 수 있습니다. + +- 참조 섹션: [사용자 세션 관리](/end-user-flows/account-settings/by-management-api#user-session-management) +- 엔드포인트: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +팀이 Logto Console에서 사용자를 직접 관리하는 경우, 활성 세션을 검토하고 사용자 세부 정보 페이지에서 특정 세션을 취소할 수 있습니다. + +- 참조 섹션: [사용자 활성 세션 관리](/user-management/manage-users#manage-user-active-sessions) + +## 관련 리소스 \{#related-resources} + +세션 +사용자 승인 앱 관리 (grants) + + Account API에 의한 계정 설정: 사용자 세션 관리 + + + Management API에 의한 계정 설정: 사용자 세션 관리 + + + 사용자 관리: 사용자 활성 세션 관리 + diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..ddfcdb639bc --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# 세션 구성 + +세션 구성은 Logto 로그인 세션이 얼마나 오랫동안 활성 상태로 유지되는지와 세션 관련 접근 정책이 어떻게 적용되는지를 테넌트 수준에서 제어합니다. + +이 페이지에서는 다음을 다룹니다: + +- 세션 TTL 구성 +- 앱당 최대 동시 인증된 장치 수 + +## 세션 TTL 구성 \{#session-ttl-configuration} + +세션 TTL은 Logto OIDC 로그인 세션의 최대 수명을 결정합니다. +이는 **테넌트 수준 설정**으로, 한 번 구성되면 해당 테넌트의 모든 앱과 인증 흐름에 적용됩니다. + +### 기본 동작 \{#default-behavior} + +- 기본적으로 세션 TTL은 **14일**입니다. +- 사용자 지정 TTL이 구성되지 않은 경우, Logto는 이 기본 값을 계속 사용합니다. + +### Logto Console을 통한 구성 \{#configure-concurrent-device-limit-via-logto-console} + +Console에서 다음 경로를 통해 세션 TTL을 구성할 수 있습니다: + +Console > Tenant > Settings > OIDC settings + +**Session maximum time to live**를 사용하여 값을 업데이트하세요. + +:::note + +Console은 입력 및 표시를 위해 **일**을 사용하며, 기본 OIDC 세션 구성 / API는 **초**를 사용합니다. + +::: + +### Management API를 통한 구성 \{#configure-via-management-api} + +다음 엔드포인트를 사용하여 OIDC 세션 구성을 읽고 업데이트하세요: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +예시 (`ttl`은 초 단위): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` 초 = 14일. + +:::note + +OSS 배포의 경우, `logto-config`를 변경한 후 서비스 인스턴스를 재시작하여 서버가 최신 OIDC 설정을 적용할 수 있도록 하세요. + +서비스를 재시작하지 않고 OIDC 구성 업데이트를 자동으로 적용하려면, [중앙 redis 캐시 활성화](/logto-oss/central-cache)를 참조하세요. + +::: + +## 앱당 최대 동시 인증된 장치 수 \{#max-concurrent-authenticated-devices-per-app} + +앱당 최대 동시 인증된 장치 수는 각 사용자가 특정 앱에 대해 유지할 수 있는 활성 권한의 수를 제한하는 앱 수준 제어입니다. + +이는 애플리케이션 `customClientMetadata`의 `maxAllowedGrants` 필드를 통해 구성됩니다. +자세한 내용은 [애플리케이션 데이터 구조](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants)를 참조하세요. + +### 동작 \{#behavior} + +`maxAllowedGrants`가 설정되면, Logto는 매번 성공적인 인가 시 현재 앱에 대한 사용자의 활성 권한을 평가합니다. +활성 권한의 수가 제한을 초과하면, Logto는 가장 오래된 권한을 먼저 취소합니다. + +`maxAllowedGrants`가 설정되지 않은 경우, 동시성 제한이 없습니다. + +### Logto Console을 통한 구성 \{#configure-via-logto-console} + +각 앱의 세부 정보 페이지에서 다음 경로를 통해 이를 구성할 수 있습니다: + + + Console > Applications > Application details > Concurrent device limit + + +현재 앱에 대해 사용자당 최대 동시 활성 권한 (장치) 수를 설정하세요. + +:::note + +이 설정은 기계 간 앱, 보호된 앱, SAML 앱에 대해 지원되지 않습니다. + +::: + +## 관련 리소스 \{#related-resources} + +세션 +사용자 세션 관리 +사용자 승인된 앱 (권한) 관리 + + 애플리케이션 데이터 구조: maxAllowedGrants + +Management API와 상호작용 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index 70e1bfc9226..1c5bde50c82 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -4,120 +4,135 @@ sidebar_position: 2 # 사용자 관리 -## Logto Console을 통한 관리 \{#manage-via-logto-console} +## Logto 콘솔을 통한 관리 \{#manage-via-logto-console} ### 사용자 탐색 및 검색 \{#browse-and-search-users} -Logto Console에서 사용자 관리 기능에 접근하려면 Console > 사용자 관리로 이동하세요. 이곳에서 모든 사용자의 테이블 뷰를 볼 수 있습니다. +Logto 콘솔에서 사용자 관리 기능에 접근하려면, 콘솔 > 사용자 관리로 이동하세요. 그곳에서 모든 사용자의 테이블 뷰를 볼 수 있습니다. 테이블은 세 개의 열로 구성되어 있습니다: -- **사용자**: 아바타, 전체 이름, 사용자명, 전화번호, 이메일 등 사용자의 정보를 표시합니다. -- **애플리케이션에서 등록**: 사용자가 처음 등록한 애플리케이션의 이름을 표시합니다. -- **최신 로그인**: 사용자의 가장 최근 로그인 시각을 표시합니다. +- **사용자**: 사용자에 대한 정보, 예를 들어 아바타, 전체 이름, 사용자 이름, 전화번호, 이메일을 표시합니다. +- **애플리케이션에서**: 사용자가 처음 등록한 애플리케이션의 이름을 표시합니다. +- **최신 로그인**: 사용자의 가장 최근 로그인 타임스탬프를 표시합니다. -이 테이블은 [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email)에 대한 키워드 매핑을 지원합니다. +[`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email)에 대한 키워드 매핑을 지원합니다. ### 사용자 추가 \{#add-users} -Console을 사용하여 개발자는 최종 사용자를 위한 새 계정을 생성할 수 있습니다. 화면 오른쪽 상단의 "사용자 추가" 버튼을 클릭하세요. +콘솔을 사용하여 개발자는 최종 사용자에 대한 새 계정을 생성할 수 있습니다. 화면의 오른쪽 상단에 있는 "사용자 추가" 버튼을 클릭하세요. -Logto Console 또는 Management API(사용자가 UI를 통해 직접 등록하는 경우가 아님)로 사용자를 생성할 때는 최소 하나의 식별자: `primary email`, `primary phone`, 또는 `username`을 반드시 입력해야 합니다. `name` 필드는 선택 사항입니다. +Logto 콘솔에서 또는 Management API를 통해 사용자를 생성할 때 (UI를 통해 최종 사용자가 자체 등록한 것이 아님), 최소한 하나의 식별자: `primary email`, `primary phone`, 또는 `username`을 제공해야 합니다. `name` 필드는 선택 사항입니다. -사용자가 생성되면 Logto는 자동으로 임의의 비밀번호를 생성합니다. 초기 비밀번호는 한 번만 표시되지만, 나중에 [비밀번호 재설정](./manage-users#reset-user-password)이 가능합니다. 특정 비밀번호를 설정하려면, 사용자가 생성된 후 Management API의 `patch /api/users/{userId}/password`를 사용하세요. +사용자가 생성된 후, Logto는 자동으로 임의의 비밀번호를 생성합니다. 초기 비밀번호는 한 번만 나타나지만, 나중에 [비밀번호를 재설정](./manage-users#reset-user-password)할 수 있습니다. 특정 비밀번호를 설정하려면, 사용자가 생성된 후 Management API `patch /api/users/{userId}/password`를 사용하여 업데이트하세요. -**입력한 식별자(이메일 주소 / 전화번호 / 사용자명)**와 **초기 비밀번호**를 한 번에 복사할 수 있어, 새 사용자에게 이 정보를 쉽게 전달하여 바로 로그인할 수 있습니다. +**입력된 식별자 (이메일 주소 / 전화번호 / 사용자 이름)**와 **초기 비밀번호**를 한 번의 클릭으로 복사할 수 있어, 새로운 사용자가 로그인하고 시작할 수 있도록 이러한 자격 증명을 쉽게 공유할 수 있습니다. :::tip -초대 전용 등록을 구현하고 싶다면, [매직 링크로 사용자 초대](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)를 권장합니다. 이를 통해 화이트리스트에 등록된 사용자만 직접 등록하고 비밀번호를 설정할 수 있습니다. +초대 전용 등록을 구현하려면, [매직 링크로 사용자 초대](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)를 권장합니다. 이를 통해 화이트리스트에 등록된 사용자만 자체 등록하고 자신의 비밀번호를 설정할 수 있습니다. ::: -### 사용자 프로필 보기 및 수정 \{#view-and-update-the-user-profile} +### 사용자 프로필 보기 및 업데이트 \{#view-and-update-the-user-profile} -사용자 세부 정보를 보려면, 사용자 테이블에서 해당 행을 클릭하세요. "**사용자 세부 정보**" 페이지로 이동하며, 여기서 다음과 같은 프로필 정보를 확인할 수 있습니다: +사용자의 세부 정보를 보려면, 사용자 테이블의 해당 행을 클릭하세요. 그러면 사용자의 프로필 정보를 찾을 수 있는 "**사용자 세부 정보**" 페이지로 이동합니다. 여기에는 다음이 포함됩니다: - **인증 관련 데이터**: - - **이메일 주소** ([primary_email](/user-management/user-data#primary_email)): 수정 가능 - - **전화번호** ([primary_phone](/user-management/user-data#primary_phone)): 수정 가능 - - **사용자명** ([username](/user-management/user-data#username)): 수정 가능 - - **비밀번호** ([has_password](/user-management/user-data#has_password)): 임의의 비밀번호를 재생성할 수 있습니다. "[사용자 비밀번호 재설정](#reset-user-password)" 참고. - - **다단계 인증 (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): 이 사용자가 설정한 모든 인증 요소(예: 패스키, 인증 앱, 백업 코드)를 볼 수 있습니다. 요소는 Console에서 제거할 수 있습니다. - - **패스키**: 테넌트에서 [패스키 로그인](/end-user-flows/sign-up-and-sign-in/passkey-sign-in)이 활성화된 경우, 사용자 세부 정보 페이지에서 사용자의 로그인 패스키를 확인하고 필요시 제거할 수 있습니다. 이 패스키는 MFA와 동일한 WebAuthn 자격 증명 모델을 사용합니다. - - **개인 액세스 토큰**: [개인 액세스 토큰](/user-management/personal-access-token)을 생성, 조회, 이름 변경, 삭제할 수 있습니다. + - **이메일 주소** ([primary_email](/user-management/user-data#primary_email)): 편집 가능 + - **전화번호** ([primary_phone](/user-management/user-data#primary_phone)): 편집 가능 + - **사용자 이름** ([username](/user-management/user-data#username)): 편집 가능 + - **비밀번호** ([has_password](/user-management/user-data#has_password)): 임의의 비밀번호를 재생성할 수 있습니다. "[사용자 비밀번호 재설정](#reset-user-password)"에 대해 더 알아보세요. + - **다단계 인증 (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): 이 사용자가 설정한 모든 인증 요소 (예: 패스키, 인증 앱, 백업 코드)를 봅니다. 콘솔에서 요소를 제거할 수 있습니다. + - **패스키**: 테넌트에서 [패스키 로그인](/end-user-flows/sign-up-and-sign-in/passkey-sign-in)이 활성화된 경우, 사용자 세부 정보 페이지에서 사용자의 로그인 패스키를 보고 필요에 따라 제거할 수 있습니다. 이러한 패스키는 MFA에서 사용되는 동일한 WebAuthn 자격 증명 모델에 의해 지원됩니다. + - **개인 액세스 토큰**: [개인 액세스 토큰](/user-management/personal-access-token)을 생성, 보기, 이름 변경 및 삭제합니다. - **연결**: - **소셜 연결** ([identities](/user-management/user-data#social-identities)): - - 사용자의 연결된 소셜 계정(소셜 ID 및 프로필 정보 포함)을 볼 수 있습니다. 예: Facebook으로 로그인한 경우 "Facebook" 항목이 표시됩니다. - - 기존 소셜 아이덴티티는 제거할 수 있지만, 사용자를 대신해 새 소셜 계정을 연결할 수는 없습니다. - - [토큰 저장](/secret-vault/federated-token-set)이 활성화된 소셜 커넥터의 경우, 연결 상세 페이지에서 액세스 토큰 및 리프레시 토큰을 조회 및 관리할 수 있습니다. + - 사용자의 연결된 소셜 계정, 소셜 제공자로부터 동기화된 소셜 ID 및 프로필 세부 정보를 봅니다 (예: 사용자가 Facebook을 통해 로그인한 경우 "Facebook" 항목이 나타납니다). + - 기존 소셜 아이덴티티를 제거할 수 있지만, 사용자를 대신하여 새로운 소셜 계정을 연결할 수는 없습니다. + - [토큰 저장](/secret-vault/federated-token-set)이 활성화된 소셜 커넥터의 경우, 연결 세부 정보 페이지에서 액세스 토큰 및 리프레시 토큰을 보고 관리할 수 있습니다. - **엔터프라이즈 SSO 연결** ([sso_identities](/user-management/user-data#sso-identities)): - - 사용자의 연결된 엔터프라이즈 아이덴티티(엔터프라이즈 ID 및 프로필 정보 포함)를 볼 수 있습니다. - - Console에서는 엔터프라이즈 SSO 아이덴티티를 추가하거나 제거할 수 없습니다. - - OIDC 기반 엔터프라이즈 커넥터에서 [토큰 저장](/secret-vault/federated-token-set)이 활성화된 경우, 연결 상세 페이지에서 토큰을 조회 및 삭제할 수 있습니다. -- **사용자 프로필 데이터**: 이름, 아바타 URL, 커스텀 데이터, 추가 OpenID Connect 표준 클레임(포함되지 않은 항목). 모든 프로필 필드는 수정 가능합니다. -- **세션**: 사용자의 활성 세션 목록(디바이스 정보, sessionId, GEO 위치 등)을 볼 수 있습니다. 세션 상세 페이지에서 세부 정보를 확인하고 세션을 해제할 수 있습니다. + - 사용자의 연결된 엔터프라이즈 아이덴티티, 엔터프라이즈 아이디 및 엔터프라이즈 아이덴티티 제공자로부터 동기화된 프로필 세부 정보를 봅니다. + - 콘솔에서 엔터프라이즈 SSO 아이덴티티를 추가하거나 제거할 수 없습니다. + - [토큰 저장](/secret-vault/federated-token-set)이 활성화된 OIDC 기반 엔터프라이즈 커넥터의 경우, 연결 세부 정보 페이지에서 토큰을 보고 삭제할 수 있습니다. +- **사용자 프로필 데이터**: 이름, 아바타 URL, 사용자 정의 데이터 및 포함되지 않은 추가 OpenID Connect 표준 클레임. 모든 프로필 필드는 편집 가능합니다. +- **세션**: 세션 ID 및 GEO 위치가 적용되는 경우 장치 정보와 함께 사용자 활성 세션 목록을 봅니다. 세션의 더 많은 세부 정보를 보고 세션 세부 정보 페이지에서 세션을 취소할 수 있습니다. :::warning -소셜 연결을 제거하기 전에, 사용자가 다른 소셜 연결, 전화번호, 이메일, 또는 사용자명-비밀번호 등 대체 로그인 방법을 가지고 있는지 반드시 확인하세요. 다른 로그인 방법이 없다면, 소셜 연결 제거 후 계정에 다시 접근할 수 없습니다. +소셜 연결을 제거하기 전에 사용자가 다른 소셜 연결, 전화번호, 이메일 또는 비밀번호가 있는 사용자 이름과 같은 대체 로그인 방법을 가지고 있는지 확인하는 것이 중요합니다. 사용자가 다른 로그인 방법을 가지고 있지 않으면 소셜 연결이 제거된 후 계정에 다시 접근할 수 없습니다. ::: ### 사용자 활동 보기 \{#view-user-activities} -사용자의 최근 활동을 보려면 "사용자 세부 정보" 페이지의 "사용자 로그" 하위 탭으로 이동하세요. 여기서 사용자의 최근 활동(수행한 작업, 결과, 관련 애플리케이션, 작업 시각 등)을 테이블로 확인할 수 있습니다. +사용자의 최근 활동을 보려면, "사용자 세부 정보" 페이지의 "사용자 로그" 하위 탭으로 이동하세요. 여기에서 사용자의 최근 활동을 표시하는 테이블을 찾을 수 있습니다. 여기에는 수행된 작업, 작업 결과, 관련 애플리케이션 및 사용자가 작업한 시간이 포함됩니다. -테이블 행을 클릭하면 사용자 로그의 상세 정보(IP 주소, user agent, 원시 데이터 등)를 볼 수 있습니다. +테이블 행을 클릭하여 사용자 로그에서 IP 주소, 사용자 에이전트, 원시 데이터 등을 더 자세히 볼 수 있습니다. ### 사용자 정지 \{#suspend-user} -"사용자 세부 정보" 페이지에서 "점 세 개" -> "사용자 정지" 버튼을 클릭하세요. +"사용자 세부 정보" 페이지에서 "세 개의 점" -> "사용자 정지" 버튼을 클릭하세요. -사용자가 정지되면, 해당 사용자는 앱에 로그인할 수 없으며, 현재 액세스 토큰이 만료된 후에는 새 액세스 토큰을 받을 수 없습니다. 또한, 이 사용자가 수행하는 모든 API 요청은 실패하게 됩니다. +사용자가 정지되면, 사용자는 앱에 로그인할 수 없으며 현재 액세스 토큰이 만료된 후 새로운 액세스 토큰을 얻을 수 없습니다. 또한, 이 사용자가 수행한 모든 API 요청은 실패합니다. -이 사용자를 다시 활성화하려면 "점 세 개" -> "사용자 재활성화" 버튼을 클릭하세요. +이 사용자를 다시 활성화하려면, "세 개의 점" -> "사용자 재활성화" 버튼을 클릭하세요. ### 사용자 삭제 \{#delete-user} -"사용자 세부 정보" 페이지에서 "점 세 개" -> "삭제" 버튼을 클릭하세요. 사용자를 삭제하면 되돌릴 수 없습니다. +"사용자 세부 정보" 페이지에서 "세 개의 점" -> "삭제" 버튼을 클릭하세요. 사용자를 삭제하면 되돌릴 수 없습니다. ### 사용자 비밀번호 재설정 \{#reset-user-password} -"사용자 세부 정보" 페이지에서 "점 세 개" -> "비밀번호 재설정" 버튼을 클릭하면, Logto가 자동으로 임의의 비밀번호를 재생성합니다. +"사용자 세부 정보" 페이지에서 "세 개의 점" -> "비밀번호 재설정" 버튼을 클릭하면, Logto가 자동으로 임의의 비밀번호를 재생성합니다. -비밀번호를 재설정한 후, 복사하여 최종 사용자에게 전달하세요. "비밀번호 재설정" 모달이 닫히면 비밀번호를 더 이상 볼 수 없습니다. 만약 복사하지 못했다면, 다시 재설정할 수 있습니다. +비밀번호를 재설정한 후, 이를 복사하여 최종 사용자에게 보내세요. "비밀번호 재설정" 모달이 닫히면 비밀번호를 더 이상 볼 수 없습니다. 이를 유지하는 것을 잊었다면, 다시 재설정할 수 있습니다. -Logto Console에서는 사용자의 특정 비밀번호를 직접 설정할 수 없지만, [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password`를 사용하여 지정할 수 있습니다. +Logto 콘솔에서는 사용자의 특정 비밀번호를 설정할 수 없지만, [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password`를 사용하여 비밀번호를 지정할 수 있습니다. ### 사용자 활성 세션 관리 \{#manage-user-active-sessions} -"사용자 세부 정보" 페이지에서 특정 세션의 "관리" 버튼을 클릭하여 "세션 세부 정보" 페이지로 이동하세요. 여기서 디바이스, 위치, 로그인 시간 등 세션의 상세 정보를 볼 수 있습니다. 해당 세션에서 사용자를 로그아웃시키려면 오른쪽 상단의 "세션 해제" 버튼을 클릭하면 즉시 세션이 해제됩니다. +"사용자 세부 정보" 페이지에서 특정 세션의 "관리" 버튼을 클릭하여 "세션 세부 정보" 페이지로 이동하세요. 여기에서 장치, 위치 및 로그인 시간과 같은 세션에 대한 자세한 정보를 볼 수 있습니다. 이 세션에서 사용자를 로그아웃하려면, 오른쪽 상단 모서리에 있는 "세션 취소" 버튼을 클릭하면 세션이 즉시 취소됩니다. -- 기본적으로 Console에서 세션을 해제하면 해당 세션과 연결된 모든 1st-party 앱 권한도 해제되며, 사용자는 다시 접근하려면 재로그인해야 합니다. 미리 발급된 불투명 토큰(액세스 토큰, 리프레시 토큰)도 즉시 해제됩니다. -- `offline_access` 스코프가 있는 3rd-party 앱의 경우, 세션 해제 시 앱 권한은 기본적으로 해제되지 않으며, 미리 발급된 리프레시 토큰은 권한 만료 전까지 계속 사용할 수 있습니다. +- 기본적으로 콘솔에서 세션을 취소하면 해당 세션과 관련된 모든 1차 앱 권한도 취소되며, 사용자는 접근을 복원하기 위해 다시 로그인해야 합니다. 1차 앱에 사전 발급된 불투명 액세스 토큰 및 리프레시 토큰도 즉시 취소됩니다. +- `offline_access` 스코프가 있는 3차 앱의 경우, 세션을 취소해도 기본적으로 앱 권한이 취소되지 않으며, 사전 발급된 리프레시 토큰은 권한이 만료될 때까지 계속 사용할 수 있습니다. -## 비밀번호 정책 준수 검사 \{#password-compliance-check} +### 사용자 승인된 3차 앱 관리 \{#manage-user-authorized-third-party-apps} -Logto에서 [비밀번호 정책](/security/password-policy)을 업데이트한 후에도 기존 사용자는 현재 비밀번호로 계속 로그인할 수 있습니다. 새로 생성된 계정만 업데이트된 정책을 따라야 합니다. +"사용자 세부 정보" 페이지에서 "승인된 3차 앱" 섹션을 사용하여 사용자의 앱 승인 상태를 검토할 수 있습니다. +이 섹션은 사용자 승인 앱 (권한) 관리 API에 의해 지원됩니다. -더 강력한 보안을 위해, `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience)를 사용하여 사용자의 비밀번호가 기본 로그인 경험에 정의된 현재 정책을 충족하는지 확인할 수 있습니다. 충족하지 않는 경우, [Account API](/end-user-flows/account-settings/by-management-api#user-password-management)를 사용하여 사용자에게 비밀번호 업데이트를 안내하는 커스텀 플로우를 구현할 수 있습니다. +각 승인된 앱에 대해 콘솔은 다음을 표시합니다: -### 사용자 역할 관리 \{#manage-roles-of-users} +- 앱 이름 +- 앱 ID +- 접근 생성 시간 -사용자 세부 정보 페이지의 "역할" 탭에서 원하는 대로 역할을 쉽게 할당하거나 제거할 수 있습니다. 자세한 내용은 [역할 기반 접근 제어 (RBAC)](/authorization/role-based-access-control)를 참고하세요. +접근을 제거해야 하는 경우, 취소 작업을 클릭하고 모달에서 확인하세요. + +앱 승인을 취소하면 해당 앱에 대한 사용자의 모든 활성 3차 권한이 제거됩니다. 또한, 해당 앱에 대한 사전 발급된 불투명 액세스 토큰 및 리프레시 토큰도 즉시 취소됩니다. + +## 비밀번호 준수 검사 \{#password-compliance-check} + +Logto에서 [비밀번호 정책](/security/password-policy)을 업데이트한 후, 기존 사용자는 여전히 현재 비밀번호로 로그인할 수 있습니다. 새로 생성된 계정만이 업데이트된 비밀번호 정책을 따라야 합니다. + +더 강력한 보안을 위해, `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience)를 사용하여 사용자의 비밀번호가 기본 로그인 경험에서 정의된 현재 정책을 충족하는지 확인할 수 있습니다. 그렇지 않은 경우, [Account API](/end-user-flows/account-settings/by-management-api#user-password-management)를 사용하여 사용자에게 비밀번호를 업데이트하도록 사용자 정의 흐름을 통해 알릴 수 있습니다. + +### 사용자의 역할 관리 \{#manage-roles-of-users} + +사용자 세부 정보 페이지의 "역할" 탭에서 원하는 결과를 얻기 위해 역할을 쉽게 할당하거나 제거할 수 있습니다. 자세한 내용은 [역할 기반 접근 제어](/authorization/role-based-access-control)를 확인하세요. ### 사용자가 속한 조직 보기 \{#view-the-organizations-the-user-belongs-to} -Logto는 [조직](/organizations/organization-management)을 지원하며, 구성원 관리를 할 수 있습니다. 사용자 세부 정보를 쉽게 확인하고, 어떤 조직에 속해 있는지 볼 수 있습니다. +Logto는 [조직](/organizations/organization-management)을 지원하며, 그들의 구성원을 관리할 수 있습니다. 사용자 세부 정보를 쉽게 보고 그들이 속한 조직을 확인할 수 있습니다. ## Logto Management API를 통한 관리 \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api)는 Logto 백엔드 서비스에 접근할 수 있는 API 모음입니다. 앞서 언급했듯이, 사용자 API는 이 서비스의 핵심 구성 요소이며 다양한 시나리오를 지원할 수 있습니다. +[Management API](/concepts/core-service/#management-api)는 Logto 백엔드 서비스에 접근할 수 있는 API 모음입니다. 앞서 언급했듯이, 사용자 API는 이 서비스의 중요한 구성 요소이며 다양한 시나리오를 지원할 수 있습니다. -사용자 관련 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API는 `/api/users`에 위치하며, 사용자 활동(로그)은 `/api/logs?userId=:userId`에 위치합니다. +사용자 관련 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API는 `/api/users`에 마운트되어 있으며, 사용자 활동, 즉 사용자 로그는 `/api/logs?userId=:userId`에 있습니다. -Management API를 통해 여러 사용 사례에서 사용자를 관리할 수 있습니다. 예: [고급 사용자 검색](/user-management/advanced-user-search), [대량 계정 생성](https://openapi.logto.io/operation/operation-createuser), [초대 전용 가입](/end-user-flows/sign-up-and-sign-in/disable-user-registration) 등. +Management API를 통해 여러 사용 사례에서 사용자를 관리할 수 있습니다. 예를 들어 [고급 사용자 검색](/user-management/advanced-user-search), [대량 계정 생성](https://openapi.logto.io/operation/operation-createuser), [초대 전용 가입](/end-user-flows/sign-up-and-sign-in/disable-user-registration) 등이 있습니다. ## 자주 묻는 질문 \{#faqs} @@ -125,12 +140,12 @@ Management API를 통해 여러 사용 사례에서 사용자를 관리할 수 -### 특정 사용자의 특정 애플리케이션 접근을 제한하려면 어떻게 해야 하나요? \{#how-to-restrict-access-to-certain-application-for-specific-users} +### 특정 사용자에 대한 특정 애플리케이션 접근을 제한하는 방법은 무엇입니까? \{#how-to-restrict-access-to-certain-application-for-specific-users} -Logto의 [Omni-sign-in](https://logto.io/products/omni-sign-in) 특성상, 인증 전에 사용자의 특정 애플리케이션 접근을 제한하도록 설계되어 있지 않습니다. -하지만, 애플리케이션별 사용자 역할과 권한을 설계하여 API 리소스를 보호하고, 사용자 인증 후 API 접근 시 권한을 검증할 수 있습니다. -자세한 내용은 인가: [역할 기반 접근 제어 (RBAC)](/authorization/role-based-access-control)를 참고하세요. +Logto의 [Omni-sign-in](https://logto.io/products/omni-sign-in) 특성상, 인증 전에 특정 애플리케이션에 대한 사용자 접근을 제한하도록 설계되지 않았습니다. +그러나 여전히 애플리케이션별 사용자 역할과 권한을 설계하여 API 리소스를 보호하고, 사용자 로그인 성공 시 API 접근 시 권한을 검증할 수 있습니다. +자세한 내용은 인가: [역할 기반 접근 제어](/authorization/role-based-access-control)를 참조하세요. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 7893823558c..7e9dd907a34 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,45 +7,45 @@ sidebar_position: 5 # Chaves de assinatura -As [chaves de assinatura OIDC](https://auth.wiki/signing-key) do Logto, também conhecidas como "chaves privadas OIDC" e "chaves de cookie OIDC", são as chaves de assinatura usadas para assinar JWTs ([tokens de acesso (Access tokens)](https://auth.wiki/access-token) e [tokens de ID (ID tokens)](https://auth.wiki/id-token)) e cookies de navegador nas [sessões de login (sign-in sessions)](/end-user-flows/sign-out#what-is-a-logto-session) do Logto. Essas chaves de assinatura são geradas ao inicializar o banco de dados do Logto ([open-source](/logto-oss)) ou ao criar um novo tenant ([Cloud](/logto-cloud)) e podem ser gerenciadas via [CLI](/logto-oss/using-cli) (open-source), Management APIs ou Console UI. +As [chaves de assinatura OIDC](https://auth.wiki/signing-key) do Logto, também conhecidas como "chaves privadas OIDC" e "chaves de cookie OIDC", são as chaves de assinatura usadas para assinar JWTs ([tokens de acesso](https://auth.wiki/access-token) e [tokens de ID](https://auth.wiki/id-token)) e cookies de navegador nas [sessões de login](/sessions#what-is-a-logto-session) do Logto. Essas chaves de assinatura são geradas ao semear o banco de dados do Logto ([código aberto](/logto-oss)) ou ao criar um novo locatário ([Cloud](/logto-cloud)) e podem ser gerenciadas através do [CLI](/logto-oss/using-cli) (código aberto), APIs de Gerenciamento ou Console UI. -Por padrão, o Logto utiliza o algoritmo de curva elíptica (EC) para gerar assinaturas digitais. No entanto, considerando que os usuários frequentemente precisam verificar assinaturas de JWT e muitas ferramentas antigas não suportam o algoritmo EC (apenas suportam RSA), implementamos a funcionalidade de rotação de chaves privadas e permitimos que os usuários escolham o algoritmo de assinatura (incluindo tanto RSA quanto EC). Isso garante compatibilidade com serviços que utilizam ferramentas de verificação de assinatura desatualizadas. +Por padrão, o Logto usa o algoritmo de curva elíptica (EC) para gerar assinaturas digitais. No entanto, considerando que os usuários frequentemente precisam verificar assinaturas de JWT e muitas ferramentas antigas não suportam o algoritmo EC (apenas suportam RSA), implementamos a funcionalidade de rotacionar chaves privadas e permitir que os usuários escolham o algoritmo de assinatura (incluindo tanto RSA quanto EC). Isso garante compatibilidade com serviços que usam ferramentas de verificação de assinatura desatualizadas. :::note -Teoricamente, as chaves de assinatura não devem ser expostas e não possuem tempo de expiração, ou seja, não há necessidade de rotacioná-las. No entanto, rotacionar periodicamente a chave de assinatura após um certo período pode aumentar a segurança. +Teoricamente, as chaves de assinatura não devem ser vazadas e não têm um tempo de expiração, o que significa que não há necessidade de rotacioná-las. No entanto, rotacionar periodicamente a chave de assinatura após um certo período pode aumentar a segurança. ::: ## Como funciona? \{#how-it-works} - **Chave privada OIDC** - Ao inicializar uma instância do Logto, um par de chave pública e chave privada é gerado automaticamente e registrado no provedor OIDC subjacente. Assim, quando o Logto emite um novo JWT (token de acesso ou token de ID), o token é assinado com a chave privada. Enquanto isso, qualquer aplicativo cliente que recebe um JWT pode usar a chave pública correspondente para verificar a assinatura do token, garantindo que o token não foi adulterado por terceiros. A chave privada é protegida no servidor Logto. A chave pública, como o nome sugere, é pública para todos e pode ser acessada através da interface `/oidc/jwks` do endpoint OIDC. Um algoritmo de chave de assinatura pode ser especificado ao gerar a chave privada, e o Logto utiliza o algoritmo EC (Curva Elíptica) por padrão. Os usuários administradores podem alterar o algoritmo padrão para RSA (Rivest-Shamir-Adleman) ao rotacionar as chaves privadas. + Ao inicializar uma instância do Logto, um par de chave pública e chave privada é gerado automaticamente e registrado no provedor OIDC subjacente. Assim, quando o Logto emite um novo JWT (token de acesso ou token de ID), o token é assinado com a chave privada. Ao mesmo tempo, qualquer aplicativo cliente que receba um JWT pode usar a chave pública emparelhada para verificar a assinatura do token, a fim de garantir que o token não foi adulterado por terceiros. A chave privada é protegida no servidor Logto. A chave pública, no entanto, como o nome sugere, é pública para todos e pode ser acessada através da interface `/oidc/jwks` do endpoint OIDC. Um algoritmo de chave de assinatura pode ser especificado ao gerar a chave privada, e o Logto usa o algoritmo EC (Curva Elíptica) por padrão. Os usuários administradores podem alterar o algoritmo padrão para RSA (Rivest-Shamir-Adleman) rotacionando as chaves privadas. - **Chave de cookie OIDC** - Quando o usuário inicia um fluxo de login ou cadastro, uma "sessão OIDC" será criada no servidor, assim como um conjunto de cookies de navegador. Com esses cookies, o navegador pode solicitar à Experience API do Logto para realizar uma série de interações em nome do usuário, como login, cadastro e redefinição de senha. No entanto, ao contrário dos JWTs, os cookies são assinados e verificados apenas pelo próprio serviço OIDC do Logto, não sendo necessárias medidas de criptografia assimétrica. Portanto, não temos pares de chaves públicas para as chaves de assinatura de cookies, nem algoritmos de criptografia assimétrica. + Quando o usuário inicia um fluxo de login ou cadastro, uma "sessão OIDC" será criada no servidor, assim como um conjunto de cookies de navegador. Com esses cookies, o navegador pode solicitar à Logto Experience API para realizar uma série de interações em nome do usuário, como login, cadastro e redefinição de senha. No entanto, ao contrário dos JWTs, os cookies são apenas assinados e verificados pelo próprio serviço OIDC do Logto, medidas de criptografia assimétrica não são necessárias. Portanto, não temos chaves públicas emparelhadas para chaves de assinatura de cookies, nem algoritmos de criptografia assimétrica. -## Rotacionar chaves de assinatura pela Console UI \{#rotate-signing-keys-from-console-ui} +## Rotacionar chaves de assinatura a partir do Console UI \{#rotate-signing-keys-from-console-ui} -O Logto introduz o recurso de "Rotação de Chaves de Assinatura", que permite criar uma nova chave privada OIDC e uma chave de cookie em seu tenant. +O Logto introduz um recurso de "Rotação de Chaves de Assinatura", que permite criar uma nova chave privada OIDC e chave de cookie no seu locatário. -1. Navegue até Console > Chaves de assinatura. Lá, você pode gerenciar tanto as chaves privadas OIDC quanto as chaves de cookie OIDC. +1. Navegue até Console > Configurações do tenant > Configurações de OIDC. Lá, você pode gerenciar tanto as chaves privadas OIDC quanto as chaves de cookie OIDC. 2. Para rotacionar a chave de assinatura, clique no botão "Rotacionar chaves privadas" ou "Rotacionar chaves de cookie". Ao rotacionar as chaves privadas, você tem a opção de alterar o algoritmo de assinatura. 3. Você encontrará uma tabela que lista todas as chaves de assinatura em uso. Observação: Você pode excluir a chave anterior, mas não pode excluir a chave atual. | Status | Descrição | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | - | Atual | Indica que esta chave está atualmente em uso ativo em seus aplicativos e APIs. | - | Anterior | Refere-se a uma chave que foi usada anteriormente, mas foi rotacionada. Tokens existentes com essa chave de assinatura permanecem válidos. | + | Atual | Isso indica que esta chave está atualmente em uso ativo em seus aplicativos e APIs. | + | Anterior | Refere-se a uma chave que foi usada anteriormente, mas foi rotacionada. Tokens existentes com esta chave de assinatura permanecem válidos. | Lembre-se de que a rotação envolve as seguintes três ações: 1. **Criar uma nova chave de assinatura**: Isso exigirá que todos os seus **aplicativos** e **APIs** adotem a nova chave de assinatura. -2. **Rotacionar a chave atual**: A chave existente será designada como "anterior" após a rotação e não será utilizada por novos aplicativos e APIs. No entanto, tokens assinados com essa chave ainda permanecerão válidos. -3. **Remover sua chave anterior**: Chaves rotuladas como "anterior" serão revogadas e removidas da tabela. +2. **Rotacionar a chave atual**: A chave existente será designada como "anterior" após a rotação e não será utilizada por novos aplicativos e APIs criados. No entanto, tokens assinados com esta chave ainda permanecerão válidos. +3. **Remover sua chave anterior**: Chaves rotuladas como "anteriores" serão revogadas e removidas da tabela. :::warning Nunca rotacione chaves de assinatura consecutivamente (duas ou mais vezes), pois isso pode invalidar TODOS os tokens emitidos. -- Para usuários OSS, após rotacionar a chave de assinatura, é necessário reiniciar a instância Logto para que a nova chave de assinatura tenha efeito. -- Para usuários Cloud, a nova chave de assinatura entra em vigor imediatamente após a rotação, mas certifique-se de não rotacionar a chave de assinatura várias vezes consecutivas. +- Para usuários OSS, após rotacionar a chave de assinatura, é necessário reiniciar a instância do Logto para que a nova chave de assinatura entre em vigor. +- Para usuários Cloud, a nova chave de assinatura entra em vigor imediatamente após a rotação, mas certifique-se de não rotacionar a chave de assinatura várias vezes consecutivamente. ::: ## Recursos relacionados \{#related-resources} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index ad2257ce757..a876928a92e 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,5 +1,5 @@ --- -description: Saiba como usar a Account API para gerenciar usuários +description: Aprenda a usar a Account API para gerenciar usuários sidebar_position: 1 --- @@ -7,14 +7,14 @@ sidebar_position: 1 ## O que é a Logto Account API \{#what-is-logto-account-api} -A Logto Account API é um conjunto abrangente de APIs que oferece aos usuários finais acesso direto via API sem a necessidade de passar pela Management API. Aqui estão os destaques: +A Logto Account API é um conjunto abrangente de APIs que oferece aos usuários finais acesso direto à API sem precisar passar pela Management API. Aqui estão os destaques: -- Acesso direto: A Account API permite que os usuários finais acessem e gerenciem diretamente seus próprios perfis de conta sem precisar do repasse pela Management API. -- Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar totalmente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, além de gerenciar conexões sociais. Suporte para MFA e SSO em breve. +- Acesso direto: A Account API capacita os usuários finais a acessar e gerenciar diretamente seus próprios perfis de conta sem exigir o uso da Management API. +- Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar completamente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, bem como gerenciar conexões sociais. Suporte para MFA e SSO em breve. - Controle de acesso global: Os administradores têm controle total e global sobre as configurações de acesso e podem personalizar cada campo. -- Autorização perfeita: A autorização ficou mais fácil do que nunca! Basta usar `client.getAccessToken()` para obter um token de acesso opaco para OP (Logto) e anexá-lo ao cabeçalho Authorization como `Bearer `. +- Autorização sem complicações: A autorização é mais fácil do que nunca! Basta usar `client.getAccessToken()` para obter um token de acesso opaco para OP (Logto) e anexá-lo ao cabeçalho de Autorização como `Bearer `. -Com a Logto Account API, você pode construir um sistema personalizado de gerenciamento de contas, como uma página de perfil totalmente integrada ao Logto. +Com a Logto Account API, você pode construir um sistema de gerenciamento de contas personalizado, como uma página de perfil totalmente integrada ao Logto. Alguns casos de uso frequentes estão listados abaixo: @@ -23,75 +23,77 @@ Alguns casos de uso frequentes estão listados abaixo: - Atualizar senha do usuário - Atualizar identidades do usuário, incluindo email, telefone e conexões sociais - Gerenciar fatores de MFA (verificações) -- Gerenciar sessões do usuário +- Gerenciar sessões de usuário +- Gerenciar aplicativos autorizados do usuário (concessões) -Para saber mais sobre as APIs disponíveis, visite [Referência da Logto Account API](https://openapi.logto.io/group/endpoint-my-account) e [Referência da Logto Verification API](https://openapi.logto.io/group/endpoint-verifications). +Para saber mais sobre as APIs disponíveis, visite [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) e [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). :::note -Os recursos de visualização de conta SSO e exclusão de conta estão atualmente disponíveis através das Management APIs do Logto. Veja [Configurações de conta pela Management API](/end-user-flows/account-settings/by-management-api) para detalhes de implementação. +Os recursos de visualização de conta SSO e exclusão de conta estão atualmente disponíveis através das Logto Management APIs. Veja [Configurações de conta pela Management API](/end-user-flows/account-settings/by-management-api) para detalhes de implementação. ::: ## Como habilitar a Account API \{#how-to-enable-account-api} -Navegue até Console > Login & conta > Central da conta. +Navegue até Console > Sign-in & account > Account center. -A Account API vem desativada por padrão, então seus controles de acesso estão bloqueados. Ative **Habilitar Account API** para ligá-la. +A Account API está desativada por padrão, então seus controles de acesso estão bloqueados. Ative **Enable Account API** para ligá-la. -Uma vez habilitada, configure permissões por campo para identificadores, dados de perfil e acesso a tokens de terceiros. Cada campo suporta `Off`, `ReadOnly` ou `Edit`; o padrão é `Off`. +Uma vez ativada, configure permissões por campo para identificadores, dados de perfil e acesso a tokens de terceiros. Cada campo suporta `Off`, `ReadOnly` ou `Edit`; o padrão é `Off`. 1. **Campos de segurança**: - Os campos incluem: email principal, telefone principal, identidades sociais, senha e MFA. - - Antes que os usuários finais editem esses campos, eles devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação válido por 10 minutos. Veja [Obter um ID de registro de verificação](#get-a-verification-record-id). - - Para usar passkeys WebAuthn para MFA, adicione os domínios do seu app front-end em **WebAuthn Related Origins** para que a central da conta e a experiência de login possam compartilhar passkeys. Veja [Vincular uma nova passkey WebAuthn](#link-a-new-webauthn-passkey). + - Antes que os usuários finais editem esses campos, eles devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação de 10 minutos. Veja [Obter um ID de registro de verificação](#get-a-verification-record-id). + - Para usar chaves de acesso WebAuthn para MFA, adicione os domínios do seu aplicativo front-end a **WebAuthn Related Origins** para que o centro de contas e a experiência de login possam compartilhar chaves de acesso. Veja [Vincular uma nova chave de acesso WebAuthn](#link-a-new-webauthn-passkey). 2. **Campos de perfil**: - - Os campos incluem: nome de usuário, nome, avatar, [perfil](/user-management/user-data#profile) (outros atributos padrão de perfil) e [dados personalizados](/user-management/user-data#custom-data). - - Usuários finais podem editar esses campos sem verificação adicional. + - Os campos incluem: nome de usuário, nome, avatar, [perfil](/user-management/user-data#profile) (outros atributos de perfil padrão) e [dados personalizados](/user-management/user-data#custom-data). + - Os usuários finais podem editar esses campos sem verificação adicional. 3. **Cofre de segredos**: - - Para conectores sociais e corporativos OIDC ou OAuth, o [cofre de segredos](/secret-vault/federated-token-set) do Logto armazena com segurança tokens de acesso e atualização de terceiros após a autenticação. Os apps podem então chamar APIs externas, como sincronizar eventos do Google Agenda, sem pedir que o usuário faça login novamente. A recuperação de tokens fica disponível automaticamente após habilitar a Account API. + - Para conectores sociais e empresariais OIDC ou OAuth, o Logto [cofre de segredos](/secret-vault/federated-token-set) armazena com segurança tokens de acesso e atualização de terceiros após a autenticação. Os aplicativos podem então chamar APIs externas, como sincronizar eventos do Google Calendar, sem solicitar que os usuários façam login novamente. A recuperação de tokens se torna disponível automaticamente uma vez que a Account API é habilitada. 4. **Gerenciamento de sessões**: - - Quando habilitado, os usuários podem visualizar e gerenciar suas sessões ativas, incluindo informações do dispositivo e último login. Também podem revogar sessões para sair de dispositivos específicos. - - Antes de acessar o gerenciamento de sessões, os usuários devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação válido por 10 minutos. Veja [Obter um ID de registro de verificação](#get-a-verification-record-id). + - Quando habilitado, os usuários podem visualizar e gerenciar suas sessões ativas, incluindo informações do dispositivo e última hora de login. Os usuários também podem revogar sessões para sair de dispositivos específicos. + - Essa mesma permissão de campo `Sessions` também controla as APIs de aplicativos autorizados do usuário (visualizar e revogar concessões). + - Antes que os usuários finais acessem o gerenciamento de sessões, eles devem verificar sua identidade via senha, email ou SMS para obter um ID de registro de verificação de 10 minutos. Veja [Obter um ID de registro de verificação](#get-a-verification-record-id). ## Como acessar a Account API \{#how-to-access-account-api} :::note -Para garantir que o token de acesso tenha as permissões apropriadas, certifique-se de configurar corretamente os escopos correspondentes em sua configuração do Logto. +Para garantir que o token de acesso tenha as permissões apropriadas, certifique-se de ter configurado corretamente os escopos correspondentes em sua configuração do Logto. -Por exemplo, para a API `POST /api/my-account/primary-email`, você precisa configurar o escopo `email`; para a API `POST /api/my-account/primary-phone`, configure o escopo `phone`. +Por exemplo, para a API `POST /api/my-account/primary-email`, você precisa configurar o escopo `email`; para a API `POST /api/my-account/primary-phone`, você precisa configurar o escopo `phone`. ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...outras opções - // Adicione os escopos adequados para seu caso de uso. + // Adicione escopos adequados que se encaixem em seus casos de uso. scopes: [ UserScope.Email, // Para as APIs `{POST,DELETE} /api/my-account/primary-email` UserScope.Phone, // Para as APIs `{POST,DELETE} /api/my-account/primary-phone` UserScope.CustomData, // Para gerenciar dados personalizados UserScope.Address, // Para gerenciar endereço UserScope.Identities, // Para APIs relacionadas a identidade e MFA - UserScope.Profile, // Para gerenciar perfil do usuário - UserScope.Sessions, // Para gerenciar sessões do usuário + UserScope.Profile, // Para gerenciar perfil de usuário + UserScope.Sessions, // Para gerenciar sessões de usuário e concessões de aplicativos ], }; ``` ::: -### Buscar um token de acesso \{#fetch-an-access-token} +### Obter um token de acesso \{#fetch-an-access-token} -Após configurar o SDK em seu aplicativo, você pode usar o método `client.getAccessToken()` para buscar um token de acesso. Este token é um token opaco que pode ser usado para acessar a Account API. +Após configurar o SDK em seu aplicativo, você pode usar o método `client.getAccessToken()` para obter um token de acesso. Este token é um token opaco que pode ser usado para acessar a Account API. -Se você não estiver usando o SDK oficial, deve definir o `resource` como vazio na solicitação de concessão de token de acesso para `/oidc/token`. +Se você não estiver usando o SDK oficial, deve definir o `resource` como vazio para a solicitação de concessão de token de acesso para `/oidc/token`. ### Acessar a Account API usando o token de acesso \{#access-account-api-using-access-token} -Você deve incluir o token de acesso no campo `Authorization` dos cabeçalhos HTTP no formato Bearer (`Bearer YOUR_TOKEN`) ao interagir com a Account API. +Você deve incluir o token de acesso no campo `Authorization` dos cabeçalhos HTTP com o formato Bearer (`Bearer YOUR_TOKEN`) ao interagir com a Account API. -Veja um exemplo para obter as informações da conta do usuário: +Aqui está um exemplo para obter as informações da conta do usuário: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -102,14 +104,14 @@ curl https://[tenant-id].logto.app/api/my-account \ ### Recuperar informações da conta do usuário \{#retrieve-user-account-information} -Para obter dados do usuário, utilize o endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). +Para obter dados do usuário, você pode usar o endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile). ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -120,13 +122,13 @@ O corpo da resposta será assim: } ``` -Os campos da resposta podem variar dependendo das configurações da central da conta. +Os campos de resposta podem variar dependendo das configurações do centro de contas. ### Atualizar informações básicas da conta \{#update-basic-account-information} -As informações básicas da conta incluem nome de usuário, nome, avatar, dados personalizados e outras informações de perfil. +As informações básicas da conta incluem o nome de usuário, nome, avatar, dados personalizados e outras informações de perfil. -Para atualizar **username, name, avatar e customData** utilize o endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). +Para atualizar **username, name, avatar, e customData** você pode usar o endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -Para atualizar outras informações de perfil, incluindo **familyName, givenName, middleName, nickname, profile (URL da página de perfil), website, gender, birthdate, zoneinfo, locale e address**, utilize o endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). +Para atualizar outras informações de perfil, incluindo **familyName, givenName, middleName, nickname, profile (URL da página de perfil), website, gender, birthdate, zoneinfo, locale, e address**, você pode usar o endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile). ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -146,11 +148,11 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Gerenciar identificadores e outras informações sensíveis \{#manage-identifiers-and-other-sensitive-information} -Por motivos de segurança, a Account API exige uma camada adicional de autorização para operações que envolvem identificadores e outras informações sensíveis. +Por razões de segurança, a Account API requer uma camada adicional de autorização para operações que envolvem identificadores e outras informações sensíveis. ### Obter um ID de registro de verificação \{#get-a-verification-record-id} -Primeiro, você precisa obter um **ID de registro de verificação** com expiração de 10 minutos (TTL). Ele pode ser usado para verificar a identidade do usuário antes de atualizar informações sensíveis. Isso significa que, uma vez que o usuário verifica sua identidade com senha, código de verificação por email ou SMS, ele tem 10 minutos para atualizar dados relacionados à autenticação, incluindo identificadores, credenciais, vinculação de conta social e MFA. +Primeiro, você precisa obter um **ID de registro de verificação** com uma expiração de 10 minutos (TTL). Isso pode ser usado para verificar a identidade do usuário antes de atualizar informações sensíveis. Isso significa que, uma vez que um usuário verifica com sucesso sua identidade via senha, código de verificação por email ou código de verificação por SMS, ele tem 10 minutos para atualizar seus dados relacionados à autenticação, incluindo identificadores, credenciais, vinculação de contas sociais e MFA. Para obter um ID de registro de verificação, você pode [verificar a senha do usuário](#verify-the-users-password) ou [enviar um código de verificação para o email ou telefone do usuário](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -175,10 +177,10 @@ O corpo da resposta será assim: #### Verificar enviando um código de verificação para o email ou telefone do usuário \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -Para usar este método, é necessário [configurar o conector de email](/connectors/email-connectors/) ou [conector de SMS](/connectors/sms-connectors/) e garantir que o template `UserPermissionValidation` esteja configurado. +Para usar este método, você precisa [configurar o conector de email](/connectors/email-connectors/) ou [conector de SMS](/connectors/sms-connectors/), e certificar-se de que o template `UserPermissionValidation` está configurado. ::: -Usando email como exemplo, solicite um novo código de verificação e obtenha o ID de registro de verificação: +Pegue o email como exemplo, solicite um novo código de verificação e obtenha o ID de registro de verificação: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -196,7 +198,7 @@ O corpo da resposta será assim: } ``` -Ao receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro. +Ao receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro de verificação. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -205,17 +207,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Após verificar o código, você pode usar o ID de registro de verificação para atualizar o identificador do usuário. +Após verificar o código, você pode agora usar o ID de registro de verificação para atualizar o identificador do usuário. Para saber mais sobre verificações, consulte [Verificação de segurança pela Account API](/end-user-flows/security-verification). -### Enviar requisição com ID de registro de verificação \{#send-request-with-verification-record-id} +### Enviar solicitação com ID de registro de verificação \{#send-request-with-verification-record-id} -Ao enviar uma requisição para atualizar o identificador do usuário, inclua o ID de registro de verificação no cabeçalho da requisição com o campo `logto-verification-id`. +Ao enviar uma solicitação para atualizar o identificador do usuário, você precisa incluir o ID de registro de verificação no cabeçalho da solicitação com o campo `logto-verification-id`. ### Atualizar a senha do usuário \{#update-users-password} -Para atualizar a senha do usuário, utilize o endpoint [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword). +Para atualizar a senha do usuário, você pode usar o endpoint [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword). ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -226,16 +228,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -Assim como as senhas criadas durante o cadastro, as senhas definidas pela Account API devem estar em conformidade com a [política de senha](/security/password-policy) que você configurou em Console > Segurança > Política de senha. O Logto retorna resultados detalhados de validação e mensagens de erro caso a senha não atenda à política. +Assim como senhas criadas durante o cadastro, senhas definidas através da Account API devem cumprir com a [política de senhas](/security/password-policy) que você configurou em Console > Security > Password policy. O Logto retorna resultados detalhados de validação e mensagens de erro se a senha não cumprir a política. ::: ### Atualizar ou vincular novo email \{#update-or-link-new-email} :::note -Para usar este método, é necessário [configurar o conector de email](/connectors/email-connectors/) e garantir que o template `BindNewIdentifier` esteja configurado. +Para usar este método, você precisa [configurar o conector de email](/connectors/email-connectors/), e certificar-se de que o template `BindNewIdentifier` está configurado. ::: -Para atualizar ou vincular um novo email, primeiro é necessário provar a posse do email. +Para atualizar ou vincular um novo email, você deve primeiro provar a propriedade do email. Chame o endpoint [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) para solicitar um código de verificação. @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Você encontrará um `verificationId` na resposta e receberá um código de verificação no email; use-o para verificar o email. +Você encontrará um `verificationId` na resposta e receberá um código de verificação no email, use-o para verificar o email. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,34 +257,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Após verificar o código, chame [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) para atualizar o email do usuário, definindo o `verificationId` no corpo da requisição como `newIdentifierVerificationRecordId`. +Após verificar o código, você pode agora chamar [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) para atualizar o email do usuário, defina o `verificationId` no corpo da solicitação como `newIdentifierVerificationRecordId`. :::info[Dois IDs de registro de verificação diferentes] -Esta requisição exige dois IDs de registro de verificação separados: +Esta solicitação requer dois IDs de registro de verificação separados: -- **`logto-verification-id` (cabeçalho)**: Prova a identidade do usuário antes de alterações sensíveis. Obtenha este ID [verificando a senha do usuário](#verify-the-users-password) ou [enviando um código de verificação para o email ou telefone existente do usuário](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). -- **`newIdentifierVerificationRecordId` (corpo)**: Prova a posse do novo endereço de email. Este é o `verificationRecordId` retornado da chamada `POST /api/verifications/verification-code` acima. +- **`logto-verification-id` (cabeçalho)**: Prova a identidade do usuário antes de fazer alterações sensíveis. Obtenha isso [verificando a senha do usuário](#verify-the-users-password) ou [enviando um código de verificação para o email ou telefone existente do usuário](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`newIdentifierVerificationRecordId` (corpo)**: Prova a propriedade do novo endereço de email. Este é o `verificationRecordId` retornado da chamada `POST /api/verifications/verification-code` acima. ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # Verifica a identidade do usuário (por senha ou verificação de email/telefone existente) + # Verifica a identidade do usuário (da senha ou verificação de email/telefone existente) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # O "newIdentifierVerificationRecordId" prova a posse do novo email (do fluxo de verificação acima) + # O "newIdentifierVerificationRecordId" prova a propriedade do novo email (do fluxo de código de verificação acima) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -Assim como emails coletados durante o cadastro, qualquer email vinculado pela Account API deve passar pela verificação de [blocklist](/security/blocklist) que você configurou em Console > Segurança > Blocklist. O Logto rejeitará a requisição e retornará um erro detalhado se o email violar a política. +Assim como emails coletados durante o cadastro, qualquer email vinculado através da Account API deve passar pela verificação da [lista de bloqueio](/security/blocklist) que você configurou em Console > Security > Blocklist. O Logto rejeitará a solicitação e retornará um erro detalhado se o email violar a política. ::: ### Remover o email do usuário \{#remove-the-users-email} -Para remover o email do usuário, utilize o endpoint [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail). +Para remover o email do usuário, você pode usar o endpoint [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail). ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -293,14 +295,14 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Gerenciar telefone \{#manage-phone} :::note -Para usar este método, é necessário [configurar o conector de SMS](/connectors/sms-connectors/) e garantir que o template `BindNewIdentifier` esteja configurado. +Para usar este método, você precisa [configurar o conector de SMS](/connectors/sms-connectors/), e certificar-se de que o template `BindNewIdentifier` está configurado. ::: -Semelhante à atualização de email, utilize o endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) para atualizar ou vincular um novo telefone. E use o endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) para remover o telefone do usuário. +Semelhante à atualização de email, você pode usar o endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) para atualizar ou vincular um novo telefone. E use o endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) para remover o telefone do usuário. ### Vincular uma nova conexão social \{#link-a-new-social-connection} -Para vincular uma nova conexão social, primeiro solicite uma URL de autorização com [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial). +Para vincular uma nova conexão social, primeiro você deve solicitar uma URL de autorização com [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial). ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -310,12 +312,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`: O ID do [conector social](/connectors/social-connectors/). -- `redirectUri`: O URI de redirecionamento após o usuário autorizar o aplicativo; hospede uma página web neste URL e capture o callback. -- `state`: O estado a ser retornado após o usuário autorizar o aplicativo; é uma string aleatória usada para prevenir ataques CSRF. +- `redirectUri`: O URI de redirecionamento após o usuário autorizar o aplicativo, você deve hospedar uma página da web neste URL e capturar o callback. +- `state`: O estado a ser retornado após o usuário autorizar o aplicativo, é uma string aleatória usada para prevenir ataques CSRF. -Na resposta, você encontrará um `verificationRecordId`; guarde-o para uso posterior. +Na resposta, você encontrará um `verificationRecordId`, guarde-o para uso posterior. -Após o usuário autorizar o aplicativo, você receberá um callback no `redirectUri` com o parâmetro `state`. Então, utilize o endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) para verificar a conexão social. +Após o usuário autorizar o aplicativo, você receberá um callback no `redirectUri` com o parâmetro `state`. Então você pode usar o endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) para verificar a conexão social. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,15 +326,15 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -O `connectorData` são os dados retornados pelo conector social após o usuário autorizar o aplicativo; você precisa analisar e obter os parâmetros de consulta do `redirectUri` em sua página de callback e empacotá-los como JSON no campo `connectorData`. +O `connectorData` são os dados retornados pelo conector social após o usuário autorizar o aplicativo, você precisa analisar e obter os parâmetros de consulta do `redirectUri` em sua página de callback e envolvê-los como um JSON como o valor do campo `connectorData`. -Por fim, utilize o endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) para vincular a conexão social. +Finalmente, você pode usar o endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) para vincular a conexão social. :::info[Dois IDs de registro de verificação diferentes] -Esta requisição exige dois IDs de registro de verificação separados: +Esta solicitação requer dois IDs de registro de verificação separados: -- **`logto-verification-id` (cabeçalho)**: Prova a identidade do usuário antes de alterações sensíveis. Obtenha este ID [verificando a senha do usuário](#verify-the-users-password) ou [enviando um código de verificação para o email ou telefone existente do usuário](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). +- **`logto-verification-id` (cabeçalho)**: Prova a identidade do usuário antes de fazer alterações sensíveis. Obtenha isso [verificando a senha do usuário](#verify-the-users-password) ou [enviando um código de verificação para o email ou telefone existente do usuário](#verify-by-sending-a-verification-code-to-the-users-email-or-phone). - **`newIdentifierVerificationRecordId` (corpo)**: Identifica a identidade social a ser vinculada. Este é o `verificationRecordId` retornado da chamada `POST /api/verifications/social` acima. ::: @@ -340,7 +342,7 @@ Esta requisição exige dois IDs de registro de verificação separados: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # Verifica a identidade do usuário (por senha ou verificação de email/telefone existente) + # Verifica a identidade do usuário (da senha ou verificação de email/telefone existente) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ # O "newIdentifierVerificationRecordId" identifica a conexão social a ser vinculada (do fluxo de verificação social acima) @@ -349,7 +351,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ ### Remover uma conexão social \{#remove-a-social-connection} -Para remover uma conexão social, utilize o endpoint [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity). +Para remover uma conexão social, você pode usar o endpoint [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity). ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -357,30 +359,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Vincular uma nova passkey WebAuthn \{#link-a-new-webauthn-passkey} +### Vincular uma nova chave de acesso WebAuthn \{#link-a-new-webauthn-passkey} :::note Lembre-se de [habilitar MFA e WebAuthn](/end-user-flows/mfa) primeiro. ::: :::note -Para usar este método, é necessário habilitar o campo `mfa` nas [configurações da central da conta](#how-to-enable-account-api). +Para usar este método, você precisa habilitar o campo `mfa` nas [configurações do centro de contas](#how-to-enable-account-api). ::: -**Passo 1: Adicione a origem do seu app front-end às origens relacionadas** +**Passo 1: Adicione a origem do seu aplicativo front-end às origens relacionadas** -As passkeys WebAuthn são vinculadas a um hostname específico chamado **Relying Party ID (RP ID)**. Apenas aplicativos hospedados na origem do RP ID podem registrar ou autenticar com essas passkeys. +As chaves de acesso WebAuthn estão vinculadas a um hostname específico chamado **Relying Party ID (RP ID)**. Apenas aplicativos hospedados na origem do RP ID podem registrar ou autenticar com essas chaves de acesso. -Como seu aplicativo front-end chama a Account API de um domínio diferente das páginas de autenticação do Logto, é necessário configurar **Related Origins** para permitir operações de passkey entre origens. +Como seu aplicativo front-end chama a Account API de um domínio diferente das páginas de autenticação do Logto, você precisa configurar **Related Origins** para permitir operações de chave de acesso entre origens. **Como o Logto determina o RP ID:** -- **Configuração padrão**: Se você usa apenas o domínio padrão do Logto `https://[tenant-id].logto.app`, o RP ID é `[tenant-id].logto.app` -- **Domínio personalizado**: Se você configurou um [domínio personalizado](/logto-cloud/custom-domain) como `https://auth.example.com`, o RP ID passa a ser `auth.example.com` +- **Configuração padrão**: Se você usar apenas o domínio padrão do Logto `https://[tenant-id].logto.app`, o RP ID é `[tenant-id].logto.app` +- **Domínio personalizado**: Se você configurou um [domínio personalizado](/logto-cloud/custom-domain) como `https://auth.example.com`, o RP ID se torna `auth.example.com` -**Configurar Related Origins:** +**Configurar Origens Relacionadas:** -Use o endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) para adicionar a origem do seu app front-end. Por exemplo, se a central da conta do seu app roda em `https://account.example.com`: +Use o endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) para adicionar a origem do seu aplicativo front-end. Por exemplo, se o centro de contas do seu aplicativo estiver em `https://account.example.com`: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -O WebAuthn suporta até 5 rótulos eTLD+1 únicos para Related Origins. O eTLD+1 (domínio de topo efetivo mais um rótulo) é a parte registrável do domínio. Por exemplo: +O WebAuthn suporta até 5 rótulos eTLD+1 únicos para Origens Relacionadas. O eTLD+1 (domínio de nível superior efetivo mais um rótulo) é a parte do domínio registrável. Por exemplo: -- `https://example.com`, `https://app.example.com` e `https://auth.example.com` contam como **um** rótulo (`example.com`) -- `https://shopping.com`, `https://shopping.co.uk` e `https://shopping.co.jp` também contam como **um** rótulo (`shopping`) +- `https://example.com`, `https://app.example.com`, e `https://auth.example.com` contam como **um** rótulo (`example.com`) +- `https://shopping.com`, `https://shopping.co.uk`, e `https://shopping.co.jp` também contam como **um** rótulo (`shopping`) - `https://example.com` e `https://another.com` contam como **dois** rótulos -Se precisar suportar mais de 5 domínios diferentes como Related Origins, consulte a documentação [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) para detalhes. +Se você precisar suportar mais de 5 domínios diferentes como Origens Relacionadas, consulte a documentação [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) para detalhes. ::: **Passo 2: Solicitar novas opções de registro** -Use o endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) para solicitar o registro de uma nova passkey. O Logto permite que cada conta de usuário registre múltiplas passkeys. +Use o endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) para solicitar o registro de uma nova chave de acesso. O Logto permite que cada conta de usuário registre várias chaves de acesso. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -421,9 +423,9 @@ Você receberá uma resposta como: } ``` -**Passo 3: Registrar a passkey no navegador local** +**Passo 3: Registrar a chave de acesso no navegador local** -Usando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como exemplo, utilize a função `startRegistration` para registrar a passkey no navegador local. +Pegue [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como exemplo, você pode usar a função `startRegistration` para registrar a chave de acesso no navegador local. ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -435,11 +437,11 @@ const response = await startRegistration({ // Salve a resposta para uso posterior ``` -**Passo 4: Verificar o registro da passkey** +**Passo 4: Verificar o registro da chave de acesso** -Use o endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) para verificar o registro da passkey. +Use o endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) para verificar o registro da chave de acesso. -Esta etapa verifica a assinatura criptográfica gerada pelo autenticador para garantir que a passkey foi criada legitimamente e não foi adulterada durante a transmissão. +Este passo verifica a assinatura criptográfica gerada pelo autenticador para garantir que a chave de acesso foi criada legitimamente e não foi adulterada durante a transmissão. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -451,9 +453,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat - `payload`: A resposta do navegador local no passo 2. - `verificationRecordId`: O ID de registro de verificação retornado pelo servidor no passo 1. -**Passo 5: Vincular a passkey** +**Passo 5: Vincular a chave de acesso** -Por fim, vincule a passkey à conta do usuário usando o endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). +Finalmente, você pode vincular a chave de acesso à conta do usuário usando o endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification). ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário; consulte a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. -- `type`: o tipo do fator MFA, atualmente apenas `WebAuthn` é suportado. +- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário, você pode consultar a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. +- `type`: o tipo do fator de MFA, atualmente apenas `WebAuthn` é suportado. - `newIdentifierVerificationRecordId`: o ID de registro de verificação retornado pelo servidor no passo 1. -### Gerenciar passkeys WebAuthn existentes \{#manage-existing-webauthn-passkeys} +### Gerenciar chaves de acesso WebAuthn existentes \{#manage-existing-webauthn-passkeys} -Para gerenciar passkeys WebAuthn existentes, utilize o endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) para obter as passkeys atuais e outros fatores de verificação MFA. +Para gerenciar chaves de acesso WebAuthn existentes, você pode usar o endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) para obter chaves de acesso atuais e outros fatores de verificação de MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json [ @@ -492,11 +494,11 @@ O corpo da resposta será assim: ``` - `id`: o ID da verificação. -- `type`: o tipo da verificação, `WebAuthn` para passkey WebAuthn. -- `name`: o nome da passkey, campo opcional. -- `agent`: o user agent da passkey. +- `type`: o tipo da verificação, `WebAuthn` para chave de acesso WebAuthn. +- `name`: o nome da chave de acesso, campo opcional. +- `agent`: o agente do usuário da chave de acesso. -Atualize o nome da passkey usando o endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname): +Atualize o nome da chave de acesso usando o endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname): ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Exclua a passkey usando o endpoint [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification): +Exclua a chave de acesso usando o endpoint [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification): ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -521,7 +523,7 @@ Lembre-se de [habilitar MFA e TOTP](/end-user-flows/mfa) primeiro. ::: :::note -Para usar este método, é necessário habilitar o campo `mfa` nas [configurações da central da conta](#how-to-enable-account-api). +Para usar este método, você precisa habilitar o campo `mfa` nas [configurações do centro de contas](#how-to-enable-account-api). ::: **Passo 1: Gerar um segredo TOTP** @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -544,9 +546,9 @@ O corpo da resposta será assim: **Passo 2: Exibir o segredo TOTP para o usuário** -Use o segredo para gerar um QR code ou exibi-lo diretamente ao usuário. O usuário deve adicioná-lo ao seu app autenticador (como Google Authenticator, Microsoft Authenticator ou Authy). +Use o segredo para gerar um código QR ou exibi-lo diretamente para o usuário. O usuário deve adicioná-lo ao seu aplicativo autenticador (como Google Authenticator, Microsoft Authenticator ou Authy). -O formato URI para o QR code deve ser: +O formato URI para o código QR deve ser: ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -560,7 +562,7 @@ otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp **Passo 3: Vincular o fator TOTP** -Após o usuário adicionar o segredo ao app autenticador, ele deve verificá-lo e vinculá-lo à sua conta. Use o endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) para vincular o fator TOTP. +Após o usuário ter adicionado o segredo ao seu aplicativo autenticador, ele precisa verificá-lo e vinculá-lo à sua conta. Use o endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) para vincular o fator TOTP. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,12 +572,12 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Consulte a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. +- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Você pode consultar a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. - `type`: deve ser `Totp`. - `secret`: o segredo TOTP gerado no passo 1. :::note -Um usuário pode ter apenas um fator TOTP por vez. Se o usuário já possui um fator TOTP, tentar adicionar outro resultará em erro 422. +Um usuário pode ter apenas um fator TOTP por vez. Se o usuário já tiver um fator TOTP, tentar adicionar outro resultará em um erro 422. ::: ### Gerenciar códigos de backup \{#manage-backup-codes} @@ -585,7 +587,7 @@ Lembre-se de [habilitar MFA e códigos de backup](/end-user-flows/mfa) primeiro. ::: :::note -Para usar este método, é necessário habilitar o campo `mfa` nas [configurações da central da conta](#how-to-enable-account-api). +Para usar este método, você precisa habilitar o campo `mfa` nas [configurações do centro de contas](#how-to-enable-account-api). ::: **Passo 1: Gerar novos códigos de backup** @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -608,14 +610,14 @@ O corpo da resposta será assim: **Passo 2: Exibir códigos de backup para o usuário** -Antes de vincular os códigos de backup à conta do usuário, exiba-os ao usuário e oriente-o a: +Antes de vincular os códigos de backup à conta do usuário, você deve exibi-los para o usuário e instruí-lo a: - Baixar ou anotar esses códigos imediatamente -- Armazená-los em local seguro +- Armazená-los em um local seguro - Entender que cada código só pode ser usado uma vez -- Saber que esses códigos são o último recurso caso perca acesso aos métodos MFA principais +- Saber que esses códigos são seu último recurso se perder o acesso aos seus métodos principais de MFA -Exiba os códigos em formato claro e fácil de copiar e considere fornecer uma opção de download (por exemplo, como arquivo de texto ou PDF). +Você deve exibir os códigos em um formato claro e fácil de copiar e considerar fornecer uma opção de download (por exemplo, como um arquivo de texto ou PDF). **Passo 3: Vincular códigos de backup à conta do usuário** @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Consulte a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. +- `verification_record_id`: um ID de registro de verificação válido, concedido ao verificar o fator existente do usuário. Você pode consultar a seção [Obter um ID de registro de verificação](#get-a-verification-record-id) para mais detalhes. - `type`: deve ser `BackupCode`. - `codes`: o array de códigos de backup gerados na etapa anterior. :::note -- Um usuário pode ter apenas um conjunto de códigos de backup por vez. Se todos os códigos forem usados, o usuário precisa gerar e vincular novos códigos. -- Códigos de backup não podem ser o único fator MFA. O usuário deve ter pelo menos outro fator MFA (como WebAuthn ou TOTP) habilitado. +- Um usuário pode ter apenas um conjunto de códigos de backup por vez. Se todos os códigos tiverem sido usados, o usuário precisará gerar e vincular novos códigos. +- Códigos de backup não podem ser o único fator de MFA. O usuário deve ter pelo menos um outro fator de MFA (como WebAuthn ou TOTP) habilitado. - Cada código de backup só pode ser usado uma vez. ::: **Visualizar códigos de backup existentes** -Para visualizar códigos de backup existentes e seu status de uso, utilize o endpoint [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes): +Para visualizar códigos de backup existentes e seu status de uso, use o endpoint [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes): ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -O corpo da resposta será assim: +O corpo da resposta seria assim: ```json { @@ -668,18 +670,18 @@ O corpo da resposta será assim: ``` - `code`: o código de backup. -- `usedAt`: o timestamp de quando o código foi usado, `null` se ainda não foi usado. +- `usedAt`: o timestamp quando o código foi usado, `null` se ainda não foi usado. -### Gerenciar sessões do usuário \{#manage-user-sessions} +### Gerenciar sessões de usuário \{#manage-user-sessions} **Listar sessões ativas** -Para listar as sessões ativas do usuário, utilize o endpoint [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions). +Para listar as sessões ativas do usuário, você pode usar o endpoint [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions). :::note - O escopo `UserScope.Sessions` é necessário para acessar este endpoint. -- O campo `Sessions` nas configurações da central da conta deve estar como `ReadOnly` ou `Edit`. +- O campo `Sessions` nas configurações do centro de contas deve estar definido como `ReadOnly` ou `Edit`. ::: @@ -690,14 +692,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**Revogar sessão por ID da sessão** +**Revogar sessão por ID de sessão** -Para revogar uma sessão específica, utilize o endpoint [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid). +Para revogar uma sessão específica, use o endpoint [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid). :::note - O escopo `UserScope.Sessions` é necessário para acessar este endpoint. -- O campo `Sessions` nas configurações da central da conta deve estar como `Edit`. +- O campo `Sessions` nas configurações do centro de contas deve estar definido como `Edit`. ::: ```bash @@ -710,6 +712,57 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} Parâmetros de consulta opcionais: - `revokeGrantsTarget`: Opcionalmente, especifique o alvo das concessões a serem revogadas junto com a sessão. Valores possíveis: - - `all`: Revoga todas as concessões associadas à sessão. - - `firstParty`: Revoga apenas as concessões de apps first-party associadas à sessão. (Recomendado para a maioria dos casos, pois revoga o acesso do seu próprio app mantendo as concessões de apps de terceiros, proporcionando melhor experiência ao usuário.) - - não especificado: O comportamento padrão revoga concessões que não possuem o escopo `offline_access`, o que normalmente significa revogar concessões sem refresh token para a sessão. + - `all`: Revogar todas as concessões associadas à sessão. + - `firstParty`: Revogar apenas concessões de aplicativos de primeira parte associadas à sessão. (Recomendado para a maioria dos casos de uso, pois revoga o acesso ao seu próprio aplicativo enquanto mantém as concessões de aplicativos de terceiros intactas, proporcionando uma melhor experiência ao usuário.) + - não especificado: O comportamento padrão revoga concessões que não têm o escopo `offline_access`, o que geralmente significa revogar concessões não relacionadas a tokens de atualização para a sessão. + +### Gerenciar aplicativos autorizados do usuário (concessões) \{#manage-user-authorized-apps-grants} + +Use as APIs de aplicativos autorizados do usuário (concessões) quando os usuários precisarem revisar e revogar aplicativos autorizados de sua página de configurações de conta. + +:::note + +- As APIs de concessão de aplicativos compartilham o mesmo modelo de permissão que as APIs de sessão. +- O escopo `UserScope.Sessions` é necessário. +- O campo `Sessions` nas configurações do centro de contas deve estar habilitado: + - `ReadOnly` ou `Edit` para listar concessões. + - `Edit` para revogar concessões. + +::: + +**Listar concessões de aplicativos ativas** + +Para listar concessões de aplicativos ativas do usuário atual, use o endpoint [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants). + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Parâmetro de consulta opcional: + +- `appType=firstParty`: Retornar apenas concessões de aplicativos de primeira parte. +- `appType=thirdParty`: Retornar apenas concessões de aplicativos de terceiros. +- Omitir `appType`: Retornar todas as concessões ativas. + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**Revogar concessão de aplicativo por ID de concessão** + +Para revogar uma concessão de aplicativo específica, use o endpoint [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid). + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +Quando uma concessão é revogada, tokens de acesso opacos e tokens de atualização emitidos anteriormente para essa concessão são invalidados. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index fd6c908b90e..fefee6cf1e6 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -2,25 +2,25 @@ sidebar_position: 2 --- -# Configurações de conta via Management API +# Configurações de conta pela Management API ## Integrações \{#integrations} -O Logto fornece diversas Management API para gerenciar contas de usuários. Você pode usar essas APIs para construir uma página de configurações de conta self-service para os usuários finais. +Logto fornece várias Management API para gerenciar contas de usuários. Você pode usar essas APIs para construir uma página de configurações de conta de autoatendimento para usuários finais. ### Arquitetura \{#architecture} ```mermaid graph TB A[Usuário] --> B[Aplicativo cliente] - B -->|Chamada de API de configurações de conta self-hosted|C[Aplicativo do lado do servidor] + B -->|Chamada de API de configurações de conta auto-hospedada|C[Aplicativo do lado do servidor] C -->|Chamada de Management API| D[Logto] ``` 1. **Usuário**: Usuário final autenticado que precisa acessar e gerenciar suas configurações de conta. -2. **Aplicativo cliente**: Seu aplicativo cliente que exibe a página de configurações de conta para o usuário. +2. **Aplicativo cliente**: Seu aplicativo cliente que fornece a página de configurações de conta para o usuário. 3. **Aplicativo do lado do servidor**: Aplicativo do lado do servidor que fornece a API de configurações de conta para o cliente. Interage com a Management API do Logto. -4. **Logto**: Logto como serviço de autenticação e autorização. Fornece a Management API para gerenciar contas de usuários. +4. **Logto**: Logto como o serviço de autenticação e autorização. Fornece a Management API para gerenciar contas de usuários. ### Diagrama de sequência \{#sequence-diagram} @@ -32,10 +32,10 @@ O Logto fornece diversas Management API para gerenciar contas de usuários. Voc participant Server as Aplicativo do lado do servidor participant Logto as Logto - User ->> Client: Acessa o aplicativo cliente + User ->> Client: Acessar aplicativo cliente Client ->> Logto: POST /oidc/auth - User -->> Logto: faz login - Logto -->> Client: Redireciona para o aplicativo cliente + User -->> Logto: fazer login + Logto -->> Client: Redirecionar para aplicativo cliente Client ->> Logto: POST /oidc/token Logto ->> Client: Token de acesso A Client ->> Server: GET /account-settings (com token de acesso A) @@ -49,156 +49,171 @@ O Logto fornece diversas Management API para gerenciar contas de usuários. Voc 1. O usuário acessa o aplicativo cliente. 2. O aplicativo cliente envia a solicitação de autenticação para o Logto e redireciona o usuário para a página de login do Logto. 3. O usuário faz login no Logto. -4. O usuário autenticado é redirecionado de volta ao aplicativo cliente com o código de autorização. -5. O aplicativo cliente solicita o token de acesso ao Logto para acessar a API de configurações de conta self-hosted. -6. O Logto concede o token de acesso ao aplicativo cliente. +4. O usuário autenticado é redirecionado de volta para o aplicativo cliente com o código de autorização. +5. O aplicativo cliente solicita o token de acesso do Logto para o acesso à API de configurações de conta auto-hospedada. +6. Logto concede o token de acesso ao aplicativo cliente. 7. O aplicativo cliente envia a solicitação de configurações de conta para o aplicativo do lado do servidor com o token de acesso do usuário. -8. O aplicativo do lado do servidor verifica a identidade e permissão do solicitante a partir do token de acesso do usuário. Em seguida, solicita um token de acesso à Management API do Logto. -9. O Logto concede o token de acesso à Management API para o aplicativo do lado do servidor. -10. O aplicativo do lado do servidor solicita os dados do usuário ao Logto usando o token de acesso da Management API. -11. O Logto verifica a identidade do servidor e a permissão da Management API e retorna os dados do usuário. +8. O aplicativo do lado do servidor verifica a identidade e a permissão do solicitante a partir do token de acesso do usuário. Em seguida, solicita um token de acesso da Management API do Logto. +9. Logto concede o token de acesso da Management API ao aplicativo do lado do servidor. +10. O aplicativo do lado do servidor solicita os dados do usuário do Logto usando o token de acesso da Management API. +11. Logto verifica a identidade do servidor e a permissão da Management API e retorna os dados do usuário. 12. O aplicativo do lado do servidor processa os dados do usuário com base na permissão do solicitante e retorna os detalhes da conta do usuário para o aplicativo cliente. ### Integrar Management API ao aplicativo do lado do servidor \{#integrate-management-api-to-server-side-application} -Consulte a seção [Management API](/integrate-logto/interact-with-management-api/) para saber como integrar as Management APIs com aplicativos do lado do servidor. +Consulte a seção [Management API](/integrate-logto/interact-with-management-api/) para aprender como integrar as Management APIs com aplicativos do lado do servidor. -## APIs de gerenciamento de usuários \{#user-management-apis} +## APIs de Gerenciamento de Usuários \{#user-management-apis} ### Esquema de dados do usuário \{#user-data-schema} Consulte a seção [dados do usuário e dados personalizados](/user-management/user-data/) para saber mais sobre o esquema de usuário no Logto. -### APIs de gerenciamento de perfil e identificadores do usuário \{#user-profile-and-identifiers-management-apis} +### APIs de gerenciamento de perfil e identificadores de usuário \{#user-profile-and-identifiers-management-apis} O perfil e os identificadores de um usuário são essenciais para o gerenciamento de usuários. Você pode usar as seguintes APIs para gerenciar perfis e identificadores de usuários. -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário pelo ID do usuário. | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Atualizar detalhes do usuário. | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Atualizar campos do perfil do usuário pelo ID. | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obter dados personalizados do usuário pelo ID. | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Atualizar dados personalizados do usuário pelo ID. | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Atualizar status de suspensão do usuário pelo ID. | +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário por ID do usuário. | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | Atualizar detalhes do usuário. | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | Atualizar campos do perfil do usuário por ID do usuário. | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | Obter dados personalizados do usuário por ID do usuário. | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | Atualizar dados personalizados do usuário por ID do usuário. | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | Atualizar status de suspensão do usuário por ID do usuário. | ### Verificação de email e número de telefone \{#email-and-phone-number-verification} -No sistema Logto, tanto endereços de email quanto números de telefone podem servir como identificadores de usuário, tornando sua verificação essencial. Para isso, fornecemos um conjunto de APIs de código de verificação para ajudar a verificar o email ou número de telefone fornecido. +No sistema Logto, tanto endereços de email quanto números de telefone podem servir como identificadores de usuário, tornando sua verificação essencial. Para apoiar isso, fornecemos um conjunto de APIs de código de verificação para ajudar a verificar o email ou número de telefone fornecido. :::note Certifique-se de verificar o email ou número de telefone antes de atualizar o perfil do usuário com um novo email ou número de telefone. ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Enviar código de verificação de email ou telefone. | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Verificar email ou telefone por código de verificação. | +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | Enviar código de verificação de email ou número de telefone. | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | Verificar email ou número de telefone por código de verificação. | -### Gerenciamento de senha do usuário \{#user-password-management} +### Gerenciamento de senha de usuário \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Verificar a senha atual do usuário pelo ID. | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Atualizar a senha do usuário pelo ID. | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Verificar se o usuário possui senha pelo ID. | +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | Verificar senha atual do usuário por ID do usuário. | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | Atualizar senha do usuário por ID do usuário. | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | Verificar se o usuário tem uma senha por ID do usuário. | :::note Certifique-se de verificar a senha atual do usuário antes de atualizar a senha do usuário. ::: -### Gerenciamento de identidades sociais do usuário \{#user-social-identities-management} +### Gerenciamento de identidades sociais de usuário \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário pelo ID. As identidades sociais podem ser encontradas no campo `identities`. | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Vincular uma identidade social autenticada ao usuário pelo ID. | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Desvincular uma identidade social do usuário pelo ID. | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Atualizar diretamente uma identidade social vinculada ao usuário pelo ID. | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obter o URI de autorização para um provedor de identidade social. Use este URI para iniciar uma nova conexão social. | +| método | caminho | descrição | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário por ID do usuário. As identidades sociais podem ser encontradas no campo `identities`. | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | Vincular uma identidade social autenticada ao usuário por ID do usuário. | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | Desvincular uma identidade social do usuário por ID do usuário. | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | Atualizar diretamente uma identidade social vinculada ao usuário por ID do usuário. | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | Obter o URI de autorização para um provedor de identidade social. Use este URI para iniciar uma nova conexão de identidade social. | ```mermaid sequenceDiagram autoNumber participant User as Usuário participant Client as Aplicativo cliente - participant App as aplicativo servidor + participant App as aplicativo do servidor participant Logto as Logto participant IdP as Provedor de identidade social - User ->> Client: Acessa o aplicativo cliente e solicita vincular identidade social - Client ->> App: Envia solicitação para vincular identidade social + User ->> Client: Acessar aplicativo cliente e solicitar vinculação de identidade social + Client ->> App: Enviar solicitação para vincular identidade social App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: URI de autorização - App ->> Client: Retorna URI de autorização - Client ->> IdP: Redireciona para página de autorização do IdP - User -->> IdP: Faz login no IdP - IdP ->> Client: Redireciona para o aplicativo cliente com código de autorização - Client ->> Server: Solicitação de vinculação de identidade social, encaminha resposta de autorização do IdP + App ->> Client: Retornar URI de autorização + Client ->> IdP: Redirecionar para página de autorização do IdP + User -->> IdP: Fazer login no IdP + IdP ->> Client: Redirecionar para aplicativo cliente com código de autorização + Client ->> Server: Solicitação de vinculação de identidade social, encaminhar resposta de autorização do IdP Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: Obtém informações do usuário do IdP usando o código de autorização - IdP ->> Logto: Retorna informações do usuário + Logto ->> IdP: Obter informações do usuário do IdP usando o código de autorização + IdP ->> Logto: Retornar informações do usuário ``` 1. O usuário acessa o aplicativo cliente e solicita vincular uma identidade social. 2. O aplicativo cliente envia uma solicitação ao servidor para vincular uma identidade social. -3. O servidor envia uma solicitação ao Logto para obter o URI de autorização do provedor de identidade social. Você precisa fornecer seu próprio parâmetro `state` e `redirect_uri` na solicitação. Certifique-se de registrar o `redirect_uri` no provedor de identidade social. -4. O Logto retorna o URI de autorização para o servidor. +3. O servidor envia uma solicitação ao Logto para obter o URI de autorização para o provedor de identidade social. Você precisa fornecer seu próprio parâmetro `state` e `redirect_uri` na solicitação. Certifique-se de registrar o `redirect_uri` no provedor de identidade social. +4. Logto retorna o URI de autorização para o servidor. 5. O servidor retorna o URI de autorização para o aplicativo cliente. 6. O aplicativo cliente redireciona o usuário para o URI de autorização do IdP. 7. O usuário faz login no IdP. -8. O IdP redireciona o usuário de volta ao aplicativo cliente usando o `redirect_uri` com o código de autorização. +8. O IdP redireciona o usuário de volta para o aplicativo cliente usando o `redirect_uri` com o código de autorização. 9. O aplicativo cliente valida o `state` e encaminha a resposta de autorização do IdP para o servidor. 10. O servidor envia uma solicitação ao Logto para vincular a identidade social ao usuário. -11. O Logto obtém as informações do usuário do IdP usando o código de autorização. -12. O IdP retorna as informações do usuário ao Logto e o Logto vincula a identidade social ao usuário. +11. Logto obtém as informações do usuário do IdP usando o código de autorização. +12. O IdP retorna as informações do usuário para o Logto e o Logto vincula a identidade social ao usuário. :::note Existem algumas limitações a serem consideradas ao vincular novas identidades sociais a um usuário: -- A Management API não possui contexto de sessão, qualquer conector social que exija uma sessão ativa para manter com segurança o estado da autenticação social não pode ser vinculado via Management API. Conectores não suportados incluem apple, OIDC padrão e conector OAuth 2.0 padrão. +- A Management API não possui nenhum contexto de sessão, qualquer conector social que exija uma sessão ativa para manter com segurança o estado de autenticação social não pode ser vinculado via Management API. Conectores não suportados incluem apple, OIDC padrão e conector OAuth 2.0 padrão. - Pelo mesmo motivo, o Logto não pode verificar o parâmetro `state` na resposta de autorização. Certifique-se de armazenar o parâmetro `state` em seu aplicativo cliente e validá-lo quando a resposta de autorização for recebida. -- Você precisa registrar o `redirect_uri` no provedor de identidade social com antecedência. Caso contrário, o IdP social não redirecionará o usuário de volta ao seu aplicativo cliente. Seu IdP social deve aceitar mais de um `redirect_uri` de callback, um para login do usuário, outro para sua própria página de vinculação de perfil. +- Você precisa registrar o `redirect_uri` no provedor de identidade social com antecedência. Caso contrário, o IdP social não redirecionará o usuário de volta para o seu aplicativo cliente. Seu IdP social deve aceitar mais de um `redirect_uri` de retorno, um para login do usuário, outro para sua própria página de vinculação de perfil. ::: -### Gerenciamento de identidades corporativas do usuário \{#user-enterprise-identities-management} +### Gerenciamento de identidades empresariais de usuário \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário pelo ID. As identidades corporativas podem ser encontradas no campo `ssoIdentities`. Adicione o parâmetro de consulta `includeSsoIdentities=true` para incluí-las. | +| método | caminho | descrição | +| ------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | Obter detalhes do usuário por ID do usuário. As identidades empresariais podem ser encontradas no campo `ssoIdentities`. Adicione o parâmetro de consulta `includeSsoIdentities=true` à API de detalhes do usuário para incluí-las. | -Atualmente, a Management API não suporta vincular ou desvincular identidades corporativas a um usuário. Você só pode exibir as identidades corporativas vinculadas a um usuário. +Atualmente, a Management API não suporta vincular ou desvincular identidades empresariais a um usuário. Você só pode exibir as identidades empresariais vinculadas a um usuário. ### Token de acesso pessoal \{#personal-access-token} -| method | path | description | +| método | caminho | descrição | | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obter todos os tokens de acesso pessoal do usuário. | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | Obter todos os tokens de acesso pessoal para o usuário. | | POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | Adicionar um novo token de acesso pessoal para o usuário. | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Excluir um token do usuário pelo nome. | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Atualizar um token do usuário pelo nome. | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | Excluir um token para o usuário por nome. | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | Atualizar um token para o usuário por nome. | -Tokens de acesso pessoal fornecem uma maneira segura para os usuários concederem [token de acesso (Access token)](https://auth.wiki/access-token) sem usar suas credenciais e login interativo. Saiba mais sobre [como usar tokens de acesso pessoal](/user-management/personal-access-token). +Tokens de acesso pessoal fornecem uma maneira segura para os usuários concederem [token de acesso (Access token)](https://auth.wiki/access-token) sem usar suas credenciais e login interativo. Saiba mais sobre [usando tokens de acesso pessoal](/user-management/personal-access-token). -### Gerenciamento de configurações de MFA do usuário \{#user-mfa-settings-management} +### Gerenciamento de configurações de MFA de usuário \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obter configurações de MFA do usuário pelo ID. | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurar uma verificação de MFA para o usuário. | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Excluir uma verificação de MFA do usuário pelo ID. | +| método | caminho | descrição | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | Obter configurações de MFA do usuário por ID do usuário. | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | Configurar uma verificação de MFA do usuário por ID do usuário. | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | Excluir uma verificação de MFA do usuário por ID. | -### Exclusão de conta do usuário \{#user-account-deletion} +### Exclusão de conta de usuário \{#user-account-deletion} -| method | path | description | -| ------ | -------------------------------------------------------------------------------- | -------------------------------------- | -| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Excluir um usuário pelo ID do usuário. | +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------- | ------------------------------------- | +| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | Excluir um usuário por ID do usuário. | -### Gerenciamento de sessões do usuário \{#user-session-management} +### Gerenciamento de sessão de usuário \{#user-session-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obter sessões do usuário pelo ID. | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obter uma sessão do usuário pelo ID da sessão. | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Excluir uma sessão do usuário pelo ID da sessão. | +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | Obter sessões de usuário por ID do usuário. | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | Obter uma sessão de usuário por ID da sessão. | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | Excluir uma sessão de usuário por ID da sessão. | + +### Gerenciar aplicativos autorizados do usuário (concessões) \{#manage-user-authorized-apps-grants} + +| método | caminho | descrição | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | Listar concessões de aplicativos ativas para o usuário. | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | Revogar uma concessão de aplicativo específica por ID. | + +Parâmetro de consulta opcional para listagem de concessões: + +- `appType=firstParty`: Retornar apenas concessões de aplicativos de primeira parte. +- `appType=thirdParty`: Retornar apenas concessões de aplicativos de terceiros. +- Omitir `appType`: Retornar todas as concessões ativas. + +Quando uma concessão é revogada, tokens de acesso opacos e tokens de atualização emitidos anteriormente para essa concessão são invalidados. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index fff40bc738e..f3f0b89a516 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,178 +1,44 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- # Logout -O logout no Logto (como um provedor de identidade OIDC) envolve ambos: +O logout no Logto envolve duas camadas: -- Uma **sessão centralizada do Logto** (cookie do navegador sob o domínio do Logto), e -- **Estado de autenticação distribuído no lado do cliente** (tokens e sessão local do app em cada aplicativo). +- **Logout da sessão Logto**: Encerra a sessão de login centralizada no domínio Logto. +- **Logout do aplicativo**: Limpa o estado da sessão local e tokens no seu aplicativo cliente. -Para entender o comportamento de logout, ajuda separar essas duas camadas e depois ver como os **grants** as conectam. - -## Conceitos principais \{#core-concepts} - -### O que é uma sessão do Logto? \{#what-is-a-logto-session} - -Uma sessão do Logto é o estado centralizado de login gerenciado pelo Logto. Ela é criada após uma autenticação bem-sucedida e representada por cookies sob o domínio do Logto. - -Se o cookie de sessão for válido, o usuário pode ser autenticado silenciosamente (SSO) em vários aplicativos que confiam no mesmo tenant do Logto. - -Se não existir uma sessão válida, o Logto exibe a página de login. - -### O que são grants? \{#what-are-grants} - -Um **grant** representa o status de autorização para uma combinação específica de usuário + aplicativo cliente. - -- Uma sessão do Logto pode ter grants para vários aplicativos clientes. -- Um grant é o que associa os tokens emitidos. -- Neste conjunto de documentação, use **grant** como a unidade de autorização entre aplicativos. - -### Como sessão, grants e status de autenticação do cliente se relacionam \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Domínio Logto] - S[Sessão do Logto] - G1[Grant para App A] - G2[Grant para App B] - end - - subgraph AppA [Domínio do cliente A] - A[Sessão local / tokens] - end - - subgraph AppB [Domínio do cliente B] - B[Sessão local / tokens] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Sessão do Logto** controla a experiência centralizada de SSO. -- **Sessão/tokens locais do cliente** controlam se cada app atualmente trata o usuário como autenticado. -- **Grants** conectam esses dois mundos representando o estado de autorização específico do app. - -## Recapitulação do login (por que o logout é multi-camadas) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as Aplicativo cliente - end - - box Logto (IdP) - participant OIDC as Provedor OIDC - participant SignIn as Página de login - end - - User ->> Client: Acessa o aplicativo - Client ->> OIDC: Redireciona para autenticação - OIDC -->> OIDC: Verifica sessão do Logto - OIDC ->> SignIn: Solicita login se necessário - SignIn ->> OIDC: Usuário autentica - OIDC -->> OIDC: Cria sessão e grant - OIDC ->> Client: Retorna código de autorização - Client ->> OIDC: Troca código por tokens - OIDC -->> Client: Retorna tokens -``` - -## Topologia de sessão entre apps/dispositivos \{#session-topology-across-apps-devices} - -### Cookie de sessão compartilhado (mesmo navegador/agente de usuário) \{#shared-session-cookie-same-browser-user-agent} - -Se um usuário faz login em vários apps a partir do mesmo navegador, esses apps podem reutilizar o mesmo cookie de sessão do Logto e o comportamento de SSO se aplica. - -```mermaid -flowchart TD - U[Usuário] - A["Aplicativo Cliente A (Domínio do cliente A)"] - B["Aplicativo Cliente B (Domínio do cliente B)"] - C{"Sessão do Logto existe? (Domínio Logto)"} - D["Página de login (Domínio Logto)"] - - subgraph UA["Agente de usuário A (mesmo navegador)"] - U - A - B - C - D - end - - U -->|Fazer login| A - A -->|Redireciona para Logto| C - U -->|Abrir app| B - B -->|Redireciona para Logto| C - C -->|Não| D - D -->|Criar sessão| C -``` - -### Cookies de sessão isolados (diferentes dispositivos/navegadores) \{#isolated-session-cookies-different-devices-browsers} - -Navegadores/dispositivos diferentes mantêm cookies do Logto diferentes, então o estado da sessão de login é isolado. - -```mermaid -flowchart TD - U[Usuário] - A["Aplicativo Cliente A (Domínio do cliente A)"] - C{"Sessão do Logto existe? (Dispositivo A, Domínio Logto)"} - D["Página de login (Dispositivo A, Domínio Logto)"] - - subgraph DeviceA["Agente de usuário A"] - A - C - D - end - - B["Aplicativo Cliente B (Domínio do cliente B)"] - E{"Sessão do Logto existe? (Dispositivo B, Domínio Logto)"} - F["Página de login (Dispositivo B, Domínio Logto)"] - - subgraph DeviceB["Agente de usuário B"] - B - E - F - end - - U -->|Fazer login| A - A -->|Redireciona para Logto| C - U -->|Fazer login| B - B -->|Redireciona para Logto| E - C -->|Não| D - E -->|Não| F - D -->|Criar sessão| C - F -->|Criar sessão| E -``` +Para entender melhor como as sessões funcionam no Logto, veja [Sessões](/sessions). ## Mecanismos de logout \{#sign-out-mechanisms} ### 1) Logout apenas no lado do cliente \{#1-client-side-only-sign-out} -O app cliente limpa sua própria sessão local e tokens (tokens de ID / acesso / atualização). Isso faz o logout do usuário apenas do estado local desse app. +O aplicativo cliente limpa sua própria sessão local e tokens (Tokens de ID / Tokens de acesso / Tokens de atualização). Isso faz com que o usuário saia apenas do estado local desse aplicativo. -- A sessão do Logto pode ainda estar ativa. -- Outros apps sob a mesma sessão do Logto ainda podem usar SSO. +- A sessão Logto pode ainda estar ativa. +- Outros aplicativos sob a mesma sessão Logto podem ainda usar SSO. ### 2) Encerrar sessão no Logto (logout global na implementação atual do Logto) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -Para limpar a sessão centralizada do Logto, o app redireciona o usuário para o endpoint de encerramento de sessão, por exemplo: +Para limpar a sessão centralizada do Logto, o aplicativo redireciona o usuário para o endpoint de encerramento de sessão, por exemplo: -`https://{seu-domínio-logto}/oidc/session/end` +`https://{your-logto-domain}/oidc/session/end` -No comportamento atual do SDK do Logto: +No comportamento atual do Logto SDK: 1. `signOut()` redireciona para `/session/end`. -2. Depois vai para `/session/end/confirm`. -3. O formulário de confirmação padrão faz auto-post com `logout=true`. +2. Em seguida, vai para `/session/end/confirm`. +3. O formulário de confirmação padrão auto-envia `logout=true`. + +Como resultado, o logout atual do SDK é tratado como **logout global**. -Como resultado, o logout pelo SDK atual é tratado como **logout global**. +:::note + +- **Logout global**: Revogar a sessão centralizada do Logto. + +::: ### O que acontece durante o logout global \{#what-happens-during-global-sign-out} @@ -180,77 +46,77 @@ Como resultado, o logout pelo SDK atual é tratado como **logout global**. flowchart TD A["Cliente inicia logout"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["Revoga sessão centralizada do Logto"] - D --> E{"Verifica grant por app"} - E -->|"offline_access não concedido"| F["Revoga grant"] - E -->|"offline_access concedido"| G["Mantém grant até expirar TTL do grant"] + C --> D["Revogar sessão centralizada do Logto"] + D --> E{"Verificar concessão por aplicativo"} + E -->|"offline_access não concedido"| F["Revogar concessão"] + E -->|"offline_access concedido"| G["Manter concessão até que o TTL da concessão expire"] ``` Durante o logout global: - A sessão centralizada do Logto é revogada. -- Grants relacionados aos apps são tratados conforme o estado de autorização do app: - - Se `offline_access` **não** for concedido, os grants relacionados são revogados. - - Se `offline_access` **for** concedido, os grants não são revogados pelo encerramento de sessão. -- Para casos de `offline_access`, tokens de atualização e grants permanecem válidos até a expiração do grant. +- As concessões de aplicativos relacionadas são tratadas por estado de autorização do aplicativo: + - Se `offline_access` **não** for concedido, as concessões relacionadas são revogadas. + - Se `offline_access` **for** concedido, as concessões não são revogadas pelo encerramento da sessão. +- Para casos de `offline_access`, tokens de atualização e concessões permanecem válidos até a expiração da concessão. -## Tempo de vida do grant e impacto do `offline_access` \{#grant-lifetime-and-offline-access-impact} +## Tempo de vida da concessão e impacto de `offline_access` \{#grant-lifetime-and-offline-access-impact} -- O TTL padrão do grant do Logto é **180 dias**. -- Se `offline_access` for concedido, o encerramento de sessão não revoga esse grant do app por padrão. -- A cadeia de tokens de atualização associada a esse grant pode continuar até o grant expirar (ou ser explicitamente revogado). +- O TTL padrão da concessão do Logto é **180 dias**. +- Se `offline_access` for concedido, o encerramento da sessão não revoga essa concessão do aplicativo por padrão. +- A cadeia de tokens de atualização associada a essa concessão pode continuar até que a concessão expire (ou seja explicitamente revogada). -## Logout federado: logout back-channel \{#federated-sign-out-back-channel-logout} +## Logout federado: logout de back-channel \{#federated-sign-out-back-channel-logout} -Para consistência entre apps, o Logto suporta [logout back-channel](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). +Para consistência entre aplicativos, o Logto suporta [logout de back-channel](https://openid.net/specs/openid-connect-backchannel-1_0-final.html). -Quando um usuário faz logout de um app, o Logto pode notificar todos os apps participantes da mesma sessão enviando um token de logout para o URI de logout back-channel registrado de cada app. +Quando um usuário faz logout de um aplicativo, o Logto pode notificar todos os aplicativos participando da mesma sessão enviando um token de logout para o URI de logout de back-channel registrado de cada aplicativo. -Se `Is session required` estiver habilitado nas configurações de back-channel do app, o token de logout inclui `sid` para identificar a sessão do Logto. +Se `Is session required` estiver habilitado nas configurações de back-channel do aplicativo, o token de logout inclui `sid` para identificar a sessão Logto. Fluxo típico: -1. O usuário inicia o logout em um app. -2. O Logto processa o encerramento de sessão e envia token(s) de logout para os URIs de logout back-channel registrados. -3. Cada app valida o token de logout e limpa sua própria sessão/tokens locais. +1. O usuário inicia o logout de um aplicativo. +2. O Logto processa o encerramento da sessão e envia token(s) de logout para o(s) URI(s) de logout de back-channel registrado(s). +3. Cada aplicativo valida o token de logout e limpa sua própria sessão local / tokens. ## Métodos de logout nos SDKs do Logto \{#sign-out-methods-in-logto-sdks} -- **SPA e web**: `client.signOut()` limpa o armazenamento local de tokens e redireciona para o endpoint de encerramento de sessão do Logto. Você pode fornecer um URI de redirecionamento pós-logout. -- **Nativo (incluindo React Native / Flutter)**: normalmente limpa apenas o armazenamento local de tokens. Webview sem sessão significa que não há cookie persistente do Logto no navegador para limpar. +- **SPA e web**: `client.signOut()` limpa o armazenamento de tokens local e redireciona para o endpoint de encerramento de sessão do Logto. Você pode fornecer um URI de redirecionamento pós-logout. +- **Nativo (incluindo React Native / Flutter)**: geralmente limpa apenas o armazenamento de tokens local. Webview sem sessão significa que não há cookie persistente do navegador Logto para limpar. :::note -Para aplicativos nativos que não suportam webview sem sessão ou não reconhecem as configurações `emphasized` (aplicativo Android usando **React Native** ou **Flutter** SDK), você pode forçar o prompt de login novamente passando o parâmetro `prompt=login` na solicitação de autenticação. +Para aplicativos nativos que não suportam webview sem sessão ou não reconhecem as configurações `emphasized` (aplicativo Android usando SDK **React Native** ou **Flutter**), você pode forçar o prompt do usuário a fazer login novamente passando o parâmetro `prompt=login` na solicitação de autorização. ::: -## Forçar reautenticação a cada acesso \{#enforce-re-authentication-on-every-access} +## Forçar re-autenticação em cada acesso \{#enforce-re-authentication-on-every-access} -Para ações de alta segurança, inclua `prompt=login` nas solicitações de autenticação para ignorar o SSO e forçar a entrada de credenciais toda vez. +Para ações de alta segurança, inclua `prompt=login` nas solicitações de autenticação para ignorar o SSO e forçar a entrada de credenciais a cada vez. -Se solicitar `offline_access` (para receber tokens de atualização), inclua também `consent`, `prompt=login consent`. +Se estiver solicitando `offline_access` (para receber tokens de atualização), também inclua `consent`, `prompt=login consent`. -Configuração típica combinada: +Configuração combinada típica: ```txt prompt=login consent ``` -## Perguntas frequentes \{#faqs} +## FAQs \{#faqs}
-### Não estou recebendo as notificações de logout back-channel. \{#im-not-receiving-the-back-channel-logout-notifications} +### Não estou recebendo as notificações de logout de back-channel. \{#im-not-receiving-the-back-channel-logout-notifications} -- Certifique-se de que o URI de logout back-channel está corretamente registrado no painel do Logto. -- Certifique-se de que seu app tem um estado de login ativo para o mesmo contexto de usuário/sessão. +- Certifique-se de que o URI de logout de back-channel esteja corretamente registrado no painel do Logto. +- Certifique-se de que seu aplicativo tenha um estado de login ativo para o mesmo contexto de usuário / sessão.
## Recursos relacionados \{#related-resources} - Entendendo o logout back-channel do OIDC. + Entendendo o logout de back-channel OIDC. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 279d741bbc2..19859fea81c 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,144 +1,144 @@ --- -description: Consulte os principais parâmetros de aplicativo para integração de autenticação OIDC, incluindo URIs de redirecionamento, endpoints, tokens de atualização, logout backchannel, etc. +description: Consulte os principais parâmetros de aplicação para integração de autenticação OIDC, incluindo URIs de redirecionamento, endpoints, tokens de atualização, logout de backchannel, etc. sidebar_position: 6 --- -# Estrutura de dados do aplicativo +# Estrutura de dados da aplicação ## Introdução \{#introduction} -No Logto, um _aplicativo_ refere-se a um programa de software ou serviço específico que está registrado na plataforma Logto e recebeu autorização para acessar informações do usuário ou realizar ações em nome de um usuário. Os aplicativos são usados para identificar a origem das solicitações feitas à API do Logto, bem como para gerenciar o processo de autenticação e autorização para usuários que acessam esses aplicativos. +No Logto, uma _aplicação_ refere-se a um programa de software ou serviço específico que está registrado na plataforma Logto e recebeu autorização para acessar informações do usuário ou realizar ações em nome de um usuário. As aplicações são usadas para identificar a origem das solicitações feitas à API do Logto, bem como para gerenciar o processo de autenticação e autorização para usuários que acessam essas aplicações. -O uso de aplicativos na experiência de login do Logto permite que os usuários acessem e gerenciem facilmente seus aplicativos autorizados a partir de um único local, com um processo de autenticação consistente e seguro. Isso ajuda a simplificar a experiência do usuário e garante que apenas pessoas autorizadas estejam acessando informações sensíveis ou realizando ações em nome da organização. +O uso de aplicações na experiência de login do Logto permite que os usuários acessem e gerenciem facilmente suas aplicações autorizadas a partir de um único local, com um processo de autenticação consistente e seguro. Isso ajuda a simplificar a experiência do usuário e garante que apenas indivíduos autorizados estejam acessando informações sensíveis ou realizando ações em nome da organização. -Os aplicativos também são usados nos logs de auditoria do Logto para rastrear a atividade do usuário e identificar possíveis ameaças ou violações de segurança. Ao associar ações específicas a um determinado aplicativo, o Logto pode fornecer insights detalhados sobre como os dados estão sendo acessados e utilizados, permitindo que as organizações gerenciem melhor seus requisitos de segurança e conformidade. -Se você deseja integrar seu aplicativo ao Logto, veja [Integrar Logto](/integrate-logto). +As aplicações também são usadas nos logs de auditoria do Logto para rastrear a atividade do usuário e identificar quaisquer ameaças ou violações de segurança potenciais. Ao associar ações específicas a uma aplicação em particular, o Logto pode fornecer insights detalhados sobre como os dados estão sendo acessados e usados, permitindo que as organizações gerenciem melhor seus requisitos de segurança e conformidade. +Se você deseja integrar sua aplicação com o Logto, veja [Integrar Logto](/integrate-logto). ## Propriedades \{#properties} -### ID do aplicativo \{#application-id} +### ID da aplicação \{#application-id} -_O ID do aplicativo_ é uma chave única gerada automaticamente para identificar seu aplicativo no Logto, e é referenciado como [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) no OAuth 2.0. +_ID da aplicação_ é uma chave única gerada automaticamente para identificar sua aplicação no Logto, e é referenciada como [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) no OAuth 2.0. -### Tipos de aplicativo \{#application-types} +### Tipos de aplicação \{#application-types} -Um _aplicativo_ pode ser um dos seguintes tipos de aplicativo: +Uma _Aplicação_ pode ser um dos seguintes tipos de aplicação: - **Aplicativo nativo** é um aplicativo que roda em um ambiente nativo. Ex.: aplicativo iOS, aplicativo Android. - - **Aplicativo de fluxo de dispositivo** é um tipo especial de aplicativo nativo para dispositivos com entrada limitada ou aplicativos sem interface gráfica (ex.: smart TVs, consoles de jogos, ferramentas CLI, dispositivos IoT). Ele utiliza o [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) em vez do fluxo padrão baseado em redirecionamento. Veja [Início rápido do fluxo de dispositivo](/quick-starts/device-flow) para detalhes. -- **Aplicativo de página única (SPA)** é um aplicativo que roda em um navegador web, atualizando a página com novos dados do servidor sem recarregar páginas inteiras. Ex.: aplicativo React DOM, aplicativo Vue. + - **Aplicativo de fluxo de dispositivo** é um tipo especial de aplicativo nativo para dispositivos com entrada limitada ou aplicativos sem interface (ex.: smart TVs, consoles de jogos, ferramentas CLI, dispositivos IoT). Ele usa o [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) em vez do fluxo padrão baseado em redirecionamento. Veja [Início rápido do fluxo de dispositivo](/quick-starts/device-flow) para detalhes. +- **Aplicativo de página única** é um aplicativo que roda em um navegador web, que atualiza a página com os novos dados do servidor sem carregar páginas inteiras novas. Ex.: aplicativo React DOM, aplicativo Vue. - **Aplicativo web tradicional** é um aplicativo que renderiza e atualiza páginas apenas pelo servidor web. Ex.: JSP, PHP. -- **Aplicativo máquina para máquina (M2M)** é um aplicativo que roda em um ambiente de máquina para comunicação direta entre serviços, sem interação do usuário. +- **Aplicativo máquina para máquina (M2M)** é uma aplicação que roda em um ambiente de máquina para comunicação direta de serviço para serviço sem interação do usuário. -### Segredo do aplicativo \{#application-secret} +### Segredo da aplicação \{#application-secret} -_O segredo do aplicativo_ é uma chave usada para autenticar o aplicativo no sistema de autenticação, especificamente para clientes privados (aplicativos Web tradicionais e M2M) como uma barreira de segurança privada. +_Segredo da aplicação_ é uma chave usada para autenticar a aplicação no sistema de autenticação, especificamente para clientes privados (aplicativos Web Tradicionais e M2M) como uma barreira de segurança privada. :::tip -Aplicativos de página única (SPAs) e aplicativos nativos não fornecem segredo do aplicativo. SPAs e aplicativos nativos são "clientes públicos" e não podem manter segredos (o código do navegador ou os pacotes do aplicativo podem ser inspecionados). Em vez de um segredo do aplicativo, o Logto os protege com PKCE, validação rigorosa de URI de redirecionamento / CORS, tokens de acesso de curta duração e rotação de token de atualização. +Aplicativos de Página Única (SPAs) e aplicativos Nativos não fornecem Segredo da Aplicação. SPAs e aplicativos Nativos são "clientes públicos" e não podem manter segredos (código do navegador ou pacotes de aplicativos são inspecionáveis). Em vez de um segredo de aplicativo, o Logto os protege com PKCE, validação estrita de URI de redirecionamento / CORS, tokens de acesso de curta duração e rotação de token de atualização. ::: -### Nome do aplicativo \{#application-name} +### Nome da aplicação \{#application-name} -_O nome do aplicativo_ é um nome legível por humanos do aplicativo e será exibido no console de administração. +_Nome da aplicação_ é um nome legível por humanos da aplicação e será exibido no console de administração. -O _nome do aplicativo_ é um componente importante para o gerenciamento de aplicativos no Logto, pois permite que os administradores identifiquem e acompanhem facilmente a atividade de aplicativos individuais dentro da plataforma. +O _Nome da aplicação_ é um componente importante do gerenciamento de aplicações no Logto, pois permite que os administradores identifiquem e rastreiem facilmente a atividade de aplicações individuais dentro da plataforma. :::note -É importante observar que o _nome do aplicativo_ deve ser escolhido com cuidado, pois será visível para todos os usuários que têm acesso ao console de administração. Ele deve refletir com precisão o propósito e a função do aplicativo, além de ser fácil de entender e reconhecer. +É importante notar que o _Nome da aplicação_ deve ser escolhido cuidadosamente, pois será visível para todos os usuários que têm acesso ao console de administração. Ele deve refletir com precisão o propósito e a função da aplicação, além de ser fácil de entender e reconhecer. ::: ### Descrição \{#description} -Uma breve descrição do aplicativo será exibida na página de detalhes do aplicativo no console de administração. A descrição tem como objetivo fornecer aos administradores informações adicionais sobre o aplicativo, como seu propósito, funcionalidades e outros detalhes relevantes. +Uma breve descrição da aplicação será exibida na página de detalhes da aplicação no console de administração. A descrição destina-se a fornecer aos administradores informações adicionais sobre a aplicação, como seu propósito, funcionalidade e quaisquer outros detalhes relevantes. ### URIs de redirecionamento \{#redirect-uris} -_URIs de redirecionamento_ são uma lista de URIs de redirecionamento válidas que foram pré-configuradas para um aplicativo. Quando um usuário faz login no Logto e tenta acessar o aplicativo, ele é redirecionado para um dos URIs permitidos especificados nas configurações do aplicativo. +_URIs de redirecionamento_ são uma lista de URIs de redirecionamento válidos que foram pré-configurados para uma aplicação. Quando um usuário faz login no Logto e tenta acessar a aplicação, ele é redirecionado para um dos URIs permitidos especificados nas configurações da aplicação. -A lista de URIs permitidas é usada para validar o URI de redirecionamento incluído na solicitação de autorização enviada pelo aplicativo ao Logto durante o processo de autenticação. Se o URI de redirecionamento especificado na solicitação de autorização corresponder a um dos URIs permitidos nas configurações do aplicativo, o usuário será redirecionado para esse URI após a autenticação bem-sucedida. Se o URI de redirecionamento não estiver na lista permitida, o usuário não será redirecionado e o processo de autenticação falhará. +A lista de URIs permitidos é usada para validar o URI de redirecionamento que está incluído na solicitação de autorização enviada pela aplicação ao Logto durante o processo de autenticação. Se o URI de redirecionamento especificado na solicitação de autorização corresponder a um dos URIs permitidos nas configurações da aplicação, o usuário será redirecionado para esse URI após a autenticação bem-sucedida. Se o URI de redirecionamento não estiver na lista permitida, o usuário não será redirecionado e o processo de autenticação falhará. :::note -É importante garantir que todos os URIs de redirecionamento válidos sejam adicionados à lista permitida para um aplicativo no Logto, para garantir que os usuários possam acessar o aplicativo com sucesso após a autenticação. +É importante garantir que todos os URIs de redirecionamento válidos sejam adicionados à lista permitida para uma aplicação no Logto, a fim de garantir que os usuários possam acessar a aplicação com sucesso após a autenticação. ::: -Você pode conferir o [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) para mais informações. +Você pode conferir o [Endpoint de redirecionamento](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) para mais informações. - Entendendo URIs de redirecionamento em OIDC com Authorization Code Flow + Compreendendo URIs de redirecionamento em OIDC com Fluxo de Código de Autorização -#### Padrões curinga \{#wildcard-patterns} +#### Padrões de curinga \{#wildcard-patterns} -_Disponibilidade: Aplicativo de página única, aplicativo web tradicional_ +_Disponibilidade: Aplicativo de página única, Aplicativo web tradicional_ -Os URIs de redirecionamento suportam padrões curinga (`*`) para ambientes dinâmicos, como implantações de preview. Curingas podem ser usados nos componentes de hostname e pathname de URIs HTTP/HTTPS. +Os URIs de redirecionamento suportam padrões de curinga (`*`) para ambientes dinâmicos, como implantações de visualização. Curingas podem ser usados nos componentes de nome de host e caminho dos URIs HTTP/HTTPS. **Regras:** -- Curingas só são permitidos no hostname e pathname +- Curingas são permitidos apenas no nome de host e caminho - Curingas não são permitidos no esquema, porta, parâmetros de consulta ou fragmentos de hash -- Curingas no hostname devem incluir pelo menos um ponto (ex.: `https://*.example.com/callback`) +- Curingas no nome de host devem incluir pelo menos um ponto (ex.: `https://*.example.com/callback`) **Exemplos:** - `https://*.example.com/callback` - corresponde a qualquer subdomínio -- `https://preview-*.example.com/callback` - corresponde a implantações de preview +- `https://preview-*.example.com/callback` - corresponde a implantações de visualização - `https://example.com/*/callback` - corresponde a qualquer segmento de caminho :::caution -URIs de redirecionamento curinga não são padrão OIDC e podem aumentar a superfície de ataque. Use com cuidado e prefira URIs de redirecionamento exatos sempre que possível. +URIs de redirecionamento com curinga não são padrão OIDC e podem aumentar a superfície de ataque. Use com cuidado e prefira URIs de redirecionamento exatos sempre que possível. ::: -### URIs de redirecionamento pós-logout \{#post-sign-out-redirect-uris} +### URIs de redirecionamento pós logout \{#post-sign-out-redirect-uris} -_URIs de redirecionamento pós-logout_ são uma lista de URIs válidas que foram pré-configuradas para um aplicativo redirecionar o usuário após ele sair do Logto. +_URIs de redirecionamento pós logout_ são uma lista de URIs válidos que foram pré-configurados para uma aplicação redirecionar o usuário após ele ter feito logout do Logto. -O uso de _URIs de redirecionamento pós-logout_ permitidas para logout faz parte da especificação de logout iniciado pela RP (Relying Party Initiated) no OIDC. Essa especificação fornece um método padronizado para aplicativos iniciarem uma solicitação de logout para um usuário, que inclui redirecionar o usuário para um endpoint pré-configurado após ele sair. +O uso de _URIs de redirecionamento pós logout_ permitidos para Logout faz parte da especificação de Logout Iniciado pelo RP (Relying Party) no OIDC. Esta especificação fornece um método padronizado para aplicações iniciarem uma solicitação de logout para um usuário, que inclui redirecionar o usuário para um endpoint pré-configurado após ele ter feito logout. -Quando um usuário faz logout do Logto, sua sessão é encerrada e ele é redirecionado para um dos URIs permitidos especificados nas configurações do aplicativo. Isso garante que o usuário seja direcionado apenas para endpoints autorizados e válidos após sair, ajudando a evitar acessos não autorizados e riscos de segurança associados ao redirecionamento de usuários para endpoints desconhecidos ou não verificados. +Quando um usuário faz logout do Logto, sua sessão é encerrada e ele é redirecionado para um dos URIs permitidos especificados nas configurações da aplicação. Isso garante que o usuário seja direcionado apenas para endpoints autorizados e válidos após ter feito logout, ajudando a prevenir acesso não autorizado e riscos de segurança associados ao redirecionamento de usuários para endpoints desconhecidos ou não verificados. -Você pode conferir o [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) para mais informações. +Você pode conferir o [Logout iniciado pelo RP](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) para mais informações. -### Origens permitidas para CORS \{#cors-allowed-origins} +### Origens permitidas pelo CORS \{#cors-allowed-origins} -_As origens permitidas para CORS (Cross-origin resource sharing)_ são uma lista de origens permitidas a partir das quais um aplicativo pode fazer solicitações ao serviço Logto. Qualquer origem que não esteja incluída na lista permitida não poderá fazer solicitações ao serviço Logto. +As _origens permitidas pelo CORS (Cross-origin resource sharing)_ são uma lista de origens permitidas das quais uma aplicação pode fazer solicitações ao serviço Logto. Qualquer origem que não esteja incluída na lista permitida não poderá fazer solicitações ao serviço Logto. -A lista de origens permitidas para CORS é usada para restringir o acesso ao serviço Logto a partir de domínios não autorizados e para ajudar a prevenir ataques de falsificação de solicitação entre sites (CSRF). Ao especificar as origens permitidas para um aplicativo no Logto, o serviço pode garantir que apenas domínios autorizados possam fazer solicitações ao serviço. +A lista de origens permitidas pelo CORS é usada para restringir o acesso ao serviço Logto de domínios não autorizados e para ajudar a prevenir ataques de falsificação de solicitação entre sites (CSRF). Ao especificar as origens permitidas para uma aplicação no Logto, o serviço pode garantir que apenas domínios autorizados possam fazer solicitações ao serviço. :::note -A lista de origens permitidas deve conter a origem onde o aplicativo será servido. Isso garante que as solicitações do aplicativo sejam permitidas, enquanto solicitações de origens não autorizadas sejam bloqueadas. +A lista de origens permitidas deve conter a origem onde a aplicação será servida. Isso garante que as solicitações da aplicação sejam permitidas, enquanto solicitações de origens não autorizadas são bloqueadas. ::: ### Endpoint de configuração do provedor OpenID \{#openid-provider-configuration-endpoint} -O endpoint para [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). +O endpoint para [Descoberta do OpenID Connect](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). ### Endpoint de autorização \{#authorization-endpoint} -_Endpoint de autorização_ é um termo OIDC, e é um endpoint obrigatório usado para iniciar o processo de autenticação de um usuário. Quando um usuário tenta acessar um recurso protegido ou aplicativo registrado na plataforma Logto, ele será redirecionado para o _Endpoint de autorização_ para autenticar sua identidade e obter autorização para acessar o recurso solicitado. +_Endpoint de Autorização_ é um termo do OIDC, e é um endpoint necessário que é usado para iniciar o processo de autenticação para um usuário. Quando um usuário tenta acessar um recurso ou aplicação protegida que foi registrada na plataforma Logto, ele será redirecionado para o _Endpoint de Autorização_ para autenticar sua identidade e obter autorização para acessar o recurso solicitado. -Você pode conferir o [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) para mais informações. +Você pode conferir o [Endpoint de Autorização](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) para mais informações. ### Endpoint de token \{#token-endpoint} -_Endpoint de token_ é um termo OIDC, é um endpoint de API web usado por um cliente OIDC para obter um token de acesso, um token de ID ou um token de atualização de um provedor OIDC. +_Endpoint de Token_ é um termo do OIDC, é um endpoint de API web que é usado por um cliente OIDC para obter um token de acesso, um token de ID ou um token de atualização de um provedor OIDC. -Quando um cliente OIDC precisa obter um token de acesso ou token de ID, ele envia uma solicitação ao Endpoint de token com uma concessão de autorização, que normalmente é um código de autorização ou um token de atualização. O Endpoint de token então valida a concessão de autorização e emite um token de acesso ou token de ID para o cliente se a concessão for válida. +Quando um cliente OIDC precisa obter um token de acesso ou token de ID, ele envia uma solicitação ao Endpoint de Token com uma concessão de autorização, que é tipicamente um código de autorização ou um token de atualização. O Endpoint de Token então valida a concessão de autorização e emite um token de acesso ou token de ID para o cliente se a concessão for válida. -Você pode conferir o [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) para mais informações. +Você pode conferir o [Endpoint de Token](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) para mais informações. -### Endpoint userinfo \{#userinfo-endpoint} +### Endpoint de informações do usuário \{#userinfo-endpoint} -O [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) do OpenID Connect. +O [Endpoint de Informações do Usuário](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) do OpenID Connect. ### Sempre emitir token de atualização \{#always-issue-refresh-token} _Disponibilidade: Web tradicional, SPA_ -Quando ativado, o Logto sempre emitirá tokens de atualização, independentemente de `prompt=consent` estar presente na solicitação de autenticação, ou `offline_access` estar presente nos escopos. +Quando ativado, o Logto sempre emitirá tokens de atualização, independentemente de `prompt=consent` ser apresentado na solicitação de autenticação, nem `offline_access` ser apresentado nos escopos. -No entanto, essa prática não é recomendada, a menos que seja necessário (geralmente é útil para algumas integrações OAuth de terceiros que exigem token de atualização), pois não é compatível com OpenID Connect e pode causar problemas. +No entanto, essa prática é desencorajada, a menos que necessário (geralmente é útil para algumas integrações de OAuth de terceiros que exigem token de atualização), pois não é compatível com o OpenID Connect e pode potencialmente causar problemas. ### Rotacionar token de atualização \{#rotate-refresh-token} @@ -146,39 +146,58 @@ _Padrão: `true`_ Quando ativado, o Logto emitirá um novo token de atualização para solicitações de token sob as seguintes condições: -- Se o token de atualização foi rotacionado (teve seu TTL prolongado emitindo um novo) por um ano; **OU** -- Se o token de atualização estiver próximo do tempo de expiração (>=70% do Tempo de Vida (TTL) original passado); **OU** -- Se o cliente for um cliente público, ex.: aplicativo nativo ou aplicativo de página única (SPA). +- Se o token de atualização tiver sido rotacionado (ter seu TTL prolongado emitindo um novo) por um ano; **OU** +- Se o token de atualização estiver próximo do seu tempo de expiração (>=70% do seu Tempo de Vida (TTL) original passado); **OU** +- Se o cliente for um cliente público, ex.: Aplicativo Nativo ou aplicativo de página única (SPA). :::note Para clientes públicos, quando esse recurso está ativado, um novo token de atualização sempre será emitido quando o cliente estiver trocando por um novo token de acesso usando o token de atualização. -Embora você ainda possa desativar o recurso para esses clientes públicos, é altamente recomendado mantê-lo ativado por motivos de segurança. +Embora você ainda possa desativar o recurso para esses clientes públicos, é altamente recomendável mantê-lo ativado por razões de segurança. ::: - Entendendo a rotação de token de atualização + Compreendendo a rotação de token de atualização ### Tempo de vida (TTL) do token de atualização em dias \{#refresh-token-time-to-live-ttl-in-days} _Disponibilidade: Não SPA; Padrão: 14 dias_ -A duração pela qual um token de atualização pode ser usado para solicitar novos tokens de acesso antes de expirar e se tornar inválido. As solicitações de token estenderão o TTL do token de atualização para esse valor. +A duração pela qual um token de atualização pode ser usado para solicitar novos tokens de acesso antes de expirar e se tornar inválido. As solicitações de token estenderão o TTL do token de atualização para este valor. -Normalmente, um valor mais baixo é preferido. +Tipicamente, um valor mais baixo é preferido. -Nota: A atualização do TTL não está disponível em SPA (aplicativo de página única) por motivos de segurança. Isso significa que o Logto não estenderá o TTL por meio de solicitações de token. Para melhorar a experiência do usuário, você pode ativar o recurso "Rotacionar token de atualização", permitindo que o Logto emita um novo token de atualização quando necessário. +Nota: A atualização do TTL não está disponível em SPA (aplicativo de página única) por razões de segurança. Isso significa que o Logto não estenderá o TTL através de solicitações de token. Para melhorar a experiência do usuário, você pode ativar o recurso "Rotacionar token de atualização", permitindo que o Logto emita um novo token de atualização quando necessário. :::caution Token de atualização e vinculação de sessão -Quando um token de atualização é emitido **sem** o escopo `offline_access` na solicitação de autorização, ele será vinculado à sessão do usuário. A sessão tem um TTL fixo de **14 dias**. Após a expiração da sessão, o token de atualização se torna inválido independentemente da configuração de TTL do próprio token. +Quando um token de atualização é emitido **sem** o escopo `offline_access` na solicitação de autorização, ele será vinculado à sessão do usuário. A sessão tem um TTL fixo de **14 dias**. Após a expiração da sessão, o token de atualização se torna inválido, independentemente da configuração de seu próprio TTL. Para garantir que a configuração de TTL do token de atualização tenha efeito total, certifique-se de incluir o escopo `offline_access` em sua solicitação de autorização. ::: -### URI de logout backchannel \{#backchannel-logout-uri} +### URI de logout de backchannel \{#backchannel-logout-uri} -O endpoint de logout backchannel do OpenID Connect. Veja [Logout federado: logout back-channel](#) para mais informações. +O endpoint de logout de backchannel do OpenID Connect. Veja [Logout federado: Logout de backchannel](#) para mais informações. + +### Concessões máximas permitidas (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` é um campo opcional a nível de aplicativo em `customClientMetadata` que controla o número máximo de concessões ativas simultâneas por usuário para o aplicativo atual. + +- **Padrão**: `undefined` (sem limite) +- **Quando configurado**: Em cada autorização bem-sucedida, o Logto verifica as concessões ativas totais para o usuário no aplicativo atual (em navegadores e dispositivos). Se o limite for excedido, o Logto revoga as concessões mais antigas. + +Essa configuração é útil quando você deseja limitar dispositivos autenticados simultâneos por aplicativo. + +:::note + +Este campo não é suportado para: + +- Aplicativos máquina para máquina +- Aplicativos protegidos +- Aplicativos SAML + +::: ### Dados personalizados \{#custom-data} -Informações adicionais personalizadas do aplicativo não listadas nas propriedades predefinidas do aplicativo; os usuários podem definir seus próprios campos de dados personalizados de acordo com suas necessidades específicas, como configurações e definições específicas do negócio. +Informações adicionais personalizadas da aplicação não listadas nas propriedades de aplicação pré-definidas, os usuários podem definir seus próprios campos de dados personalizados de acordo com suas necessidades específicas, como configurações e configurações específicas de negócios. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..6cea8cd8f07 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,170 @@ +# Sessões + +As sessões no Logto definem como o estado de autenticação é criado, compartilhado, atualizado e revogado entre aplicativos, navegadores e dispositivos. + +Na prática, os usuários experimentam "logado" como um estado único, mas o estado do sistema é dividido em várias camadas. Compreender essas camadas é a chave para projetar comportamentos previsíveis de SSO, renovação de tokens e logout. + +## Modelo de sessão no Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Domínio Logto"] + S["Sessão de login"] + G1["Concessão (App A)"] + G2["Concessão (App B)"] + end + + subgraph AppA ["Domínio do App A"] + A["Sessão local / tokens"] + end + + subgraph AppB ["Domínio do App B"] + B["Sessão local / tokens"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Sessão de login do Logto**: Estado de login centralizado armazenado como cookies de domínio Logto. Isso controla a disponibilidade de SSO no contexto do navegador atual. +- **Concessão (Grant)**: Estado de autorização específico do aplicativo para `usuário + aplicativo cliente`. As concessões são a ponte entre o login centralizado e a emissão de tokens do aplicativo. +- **Sessão/tokens locais do aplicativo**: Estado de autenticação local em cada aplicativo (tokens de ID/acesso/atualização, cookie de sessão do aplicativo, etc.). + +## Conceitos principais \{#core-concepts} + +### O que é uma sessão do Logto? \{#what-is-a-logto-session} + +Uma sessão do Logto é o estado de autenticação centralizado criado após um login bem-sucedido. Se ainda for válida, o Logto pode autenticar usuários silenciosamente para outros aplicativos no mesmo locatário. Se não existir, os usuários devem fazer login novamente. + +### O que são concessões? \{#what-are-grants} + +Uma concessão é um estado de autorização em nível de aplicativo vinculado a um usuário específico e aplicativo cliente. + +- Uma sessão do Logto pode ter concessões para vários aplicativos. +- Tokens para um aplicativo são emitidos sob a concessão desse aplicativo. +- Revogar uma concessão afeta a capacidade desse aplicativo de continuar o acesso baseado em token. + +### Como sessão, concessões e estado de autenticação do aplicativo se relacionam \{#how-session-grants-and-app-auth-state-relate} + +- **Sessão** responde: "Este navegador pode fazer SSO com o Logto agora?" +- **Concessão** responde: "Este usuário está autorizado para este aplicativo cliente?" +- **Sessão local do aplicativo** responde: "Este aplicativo atualmente trata o usuário como logado?" + +## Criação de login e sessão \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as Aplicativo cliente + end + + box Logto + participant OIDC as Provedor OIDC + participant SignIn as Página de login + end + + User ->> Client: Acessar aplicativo + Client ->> OIDC: Solicitação de autorização + OIDC -->> OIDC: Verificar sessão existente do Logto + OIDC ->> SignIn: Solicitar login, se necessário + SignIn ->> OIDC: Usuário autentica + OIDC -->> OIDC: Criar sessão e concessão de aplicativo + OIDC ->> Client: Retornar código de autorização + Client ->> OIDC: Trocar código por tokens + OIDC -->> Client: Retornar tokens +``` + +## Topologia de sessão entre aplicativos e dispositivos \{#session-topology-across-apps-and-devices} + +### Mesmo navegador: sessão Logto compartilhada \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[Usuário] + A["Aplicativo Cliente A"] + B["Aplicativo Cliente B"] + C{"Sessão Logto existe?"} + D["Página de login do Logto"] + + U --> A + A --> C + U --> B + B --> C + C -->|Não| D +``` + +Aplicativos no mesmo navegador podem compartilhar o estado de sessão centralizado do Logto, para que o SSO possa ocorrer sem a necessidade de inserir credenciais repetidamente. + +### Navegadores ou dispositivos diferentes: sessões Logto isoladas \{#different-browsers-or-devices-isolated-logto-sessions} + +Cada navegador/dispositivo possui armazenamento de cookies separado. Uma sessão válida no Dispositivo A não implica uma sessão válida no Dispositivo B. + +## Ciclo de vida da sessão \{#session-lifecycle} + +### 1. Criar \{#1-create} + +Após a autenticação do usuário, o Logto cria uma sessão centralizada e uma concessão específica do aplicativo. + +### 2. Reutilizar (SSO) \{#2-reuse-sso} + +Enquanto os cookies de sessão forem válidos no mesmo navegador, novas solicitações de autorização podem frequentemente ser concluídas silenciosamente. + +### 3. Renovar tokens \{#3-renew-tokens} + +O acesso ao aplicativo geralmente continua através de fluxos de atualização de tokens (quando habilitado). Isso é continuidade em nível de aplicativo, separado de se a sessão centralizada do Logto ainda existe. + +### 4. Revogar/expirar \{#4-revokeexpire} + +A revogação pode ocorrer em diferentes camadas: + +- Logout local do aplicativo remove tokens/sessão local do aplicativo. +- Encerrar sessão remove a sessão centralizada do Logto. +- Revogação de concessão remove a continuidade de autorização em nível de aplicativo. + +## Recomendações de design \{#design-recommendations} + +- Mantenha o tratamento de sessão local do aplicativo explícito no código do seu aplicativo. +- Trate a sessão do Logto, concessões e sessão local do aplicativo como camadas separadas. +- Escolha se o logout deve ser apenas local do aplicativo ou global. +- Use [logout de back-channel](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) quando a consistência entre múltiplos aplicativos for necessária. +- Para detalhes sobre comportamento e implementação de logout, veja [Logout](/end-user-flows/sign-out). + +## Melhores práticas para revogar acesso \{#best-practices-for-revoking-access} + +Use diferentes estratégias de revogação com base no seu objetivo: + +- **Revogar acesso dos seus aplicativos de primeira parte**: + Revogue a sessão alvo com `revokeGrantsTarget=firstParty`. + Isso desconecta o usuário em aplicativos de primeira parte associados a essa sessão, criando uma experiência de logout consistente. + Ao mesmo tempo, concessões para aplicativos de terceiros que têm `offline_access` concedido podem permanecer disponíveis para integrações contínuas. + Veja [Gerenciar sessões de usuário](/sessions/manage-user-sessions) para detalhes sobre revogação de sessão. + +- **Revogar acesso a aplicativos de terceiros**: + Escolha uma das seguintes opções: + + - Revogue a sessão com `revokeGrantsTarget=all` para revogar todas as concessões associadas a essa sessão. + - Revogue concessões específicas diretamente através das APIs de gerenciamento de concessões para remover autorizações de aplicativos de terceiros sem forçar o logout completo da sessão. + Veja [Gerenciar aplicativos autorizados do usuário (concessões)](/sessions/grants-management) para estratégias de revogação específicas de concessões. + +- **Ao usar o Logto Console**: + Na página de detalhes do usuário, o Logto fornece tanto o gerenciamento de sessões quanto o gerenciamento de aplicativos de terceiros autorizados prontos para uso. + - Revogar uma sessão também revoga concessões de aplicativos de primeira parte, para manter o comportamento de logout de primeira parte consistente. + - Revogar uma autorização de aplicativo de terceiros revoga concessões para esse aplicativo de terceiros enquanto mantém o status original da sessão inalterado. + +## Recursos relacionados \{#related-resources} + +Gerenciar sessões de usuário + + Gerenciar aplicativos autorizados do usuário (concessões) + +Configuração de sessão +Logout +Cadastro e login + + Compreender o fluxo de autenticação + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..b5aa6e7b93b --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,72 @@ +--- +sidebar_position: 2 +--- + +# Gerenciar aplicativos autorizados do usuário (concessões) + +As concessões de aplicativos representam o estado de autorização do usuário para aplicativos clientes específicos. + +Use o gerenciamento de concessões quando usuários ou administradores precisarem revisar aplicativos autorizados e revogar o acesso ao aplicativo sem revogar toda a sessão do Logto. + +Quando as concessões são revogadas, os tokens de acesso opacos e tokens de atualização emitidos anteriormente para essas concessões são invalidados. + +## Escolha o caminho certo \{#choose-the-right-path} + +| Cenário | Caminho recomendado | +| -------------------------------------------------------------------------------------------- | ------------------- | +| Permitir que usuários conectados gerenciem suas próprias autorizações de aplicativos | Account API | +| Permitir que administradores ou equipes de suporte gerenciem concessões para um usuário alvo | Management API | +| Permitir que operadores gerenciem autorizações de aplicativos de terceiros na interface | Admin Console | + +## APIs de gerenciamento direto de concessões \{#direct-grant-management-apis} + +### Account API (autoatendimento) \{#account-api-self-service} + +Use o Account API nas páginas de configurações de conta do usuário final: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- Referência: [Gerenciar aplicativos autorizados do usuário (concessões)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (ferramentas administrativas) \{#management-api-admin-tools} + +Use o Management API em ferramentas administrativas e fluxos de suporte: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- Referência: [Gerenciar aplicativos autorizados do usuário (concessões)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### Filtrar lista de concessões por tipo de aplicativo \{#filter-grant-list-by-app-type} + +Os endpoints de listagem de concessões suportam o parâmetro de consulta opcional `appType`: + +- `appType=firstParty`: Listar apenas concessões de aplicativos de primeira parte. +- `appType=thirdParty`: Listar apenas concessões de aplicativos de terceiros. +- Omitir `appType`: Retornar todas as concessões ativas. + +## Gerenciar autorizações de aplicativos de terceiros no Console \{#manage-third-party-app-authorizations-in-console} + +No Logto Console, use a página de detalhes do usuário para visualizar e revogar aplicativos de terceiros autorizados. + +- Referência: [Gerenciar aplicativos de terceiros autorizados do usuário](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## Revogar concessões ao revogar uma sessão \{#revoke-grants-when-revoking-a-session} + +Ao revogar uma sessão via `DELETE /api/my-account/sessions/{sessionId}`, use o parâmetro de consulta opcional `revokeGrantsTarget` para controlar o escopo de revogação de concessões: + +- `all`: Revogar concessões para todos os aplicativos associados à sessão. +- `firstParty`: Revogar concessões apenas para aplicativos de primeira parte. + +Para comportamento em nível de sessão e contexto de endpoint, veja [Gerenciar sessões de usuário](/sessions/manage-user-sessions) e [Sair](/end-user-flows/sign-out). + +## Recursos relacionados \{#related-resources} + +Sessões +Gerenciar sessões de usuário + + Configurações de conta pelo Account API: Gerenciar aplicativos autorizados do usuário (concessões) + + + Configurações de conta pelo Management API: Gerenciar aplicativos autorizados do usuário + (concessões) + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..7069447c294 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 1 +--- + +# Gerenciar sessões de usuário + +O gerenciamento de sessões de usuário ajuda usuários e administradores a revisar estados de login ativos e revogar sessões quando necessário. + +No Logto, você pode gerenciar sessões através de três caminhos comuns: + +- **Account API**: Para autoatendimento do usuário final na página de configurações da conta do seu produto. +- **Management API**: Para ferramentas de administração ou suporte gerenciarem sessões de qualquer usuário. +- **Admin Console**: Para fluxos de trabalho de operadores no Logto Console sem a necessidade de criar ferramentas personalizadas. + +## Escolha a API certa \{#choose-the-right-api} + +| Cenário | API Recomendada | +| ------------------------------------------------------------------------------------ | --------------- | +| Permitir que usuários logados gerenciem suas próprias sessões ativas | Account API | +| Permitir que administradores ou equipes de suporte gerenciem sessões para um usuário | Management API | +| Permitir que operadores gerenciem sessões diretamente no Logto Console | Admin Console | + +## Visualizar sessões ativas \{#view-active-sessions} + +### Account API (autoatendimento) \{#account-api-self-service} + +Use o endpoint de sessão do Account API para listar as sessões ativas do usuário atual. + +- Seção de referência: [Gerenciar sessões de usuário](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +Antes de expor essa capacidade aos usuários finais, certifique-se de que o gerenciamento de sessões está habilitado nas configurações do centro de contas e que seu aplicativo solicita o escopo necessário do Account API. + +### Management API (ferramentas de administração) \{#management-api-admin-tools} + +Use o Management API quando seu sistema de administração precisar listar sessões para um usuário alvo. + +- Seção de referência: [Gerenciamento de sessões de usuário](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Endpoint de detalhes opcionais: [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## Revogar sessões \{#revoke-sessions} + +### Account API (usuário final revoga suas próprias sessões) \{#account-api-end-user-revokes-own-sessions} + +Usuários finais podem revogar uma sessão específica de sua própria lista de sessões. + +- Seção de referência: [Gerenciar sessões de usuário](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +Para operações sensíveis, o gerenciamento de sessões do Account API requer verificação do usuário antes do acesso. Veja [Obter um ID de registro de verificação](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id). + +### Management API (admin revoga sessões de usuário) \{#management-api-admin-revokes-user-sessions} + +Administradores podem revogar a sessão de um usuário alvo pelo ID do usuário e ID da sessão. + +- Seção de referência: [Gerenciamento de sessões de usuário](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +Se sua equipe gerencia usuários diretamente no Logto Console, você pode revisar sessões ativas e revogar sessões específicas na página de detalhes do usuário. + +- Seção de referência: [Gerenciar sessões ativas de usuário](/user-management/manage-users#manage-user-active-sessions) + +## Recursos relacionados \{#related-resources} + +Sessões + + Gerenciar aplicativos autorizados pelo usuário (concessões) + + + Configurações de conta pelo Account API: Gerenciar sessões de usuário + + + Configurações de conta pelo Management API: Gerenciamento de sessões de usuário + + + Gerenciamento de usuários: Gerenciar sessões ativas de usuário + diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..da5f2777434 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,109 @@ +--- +sidebar_position: 3 +--- + +# Configuração de sessão + +A configuração de sessão define controles em nível de locatário para quanto tempo as sessões de login do Logto permanecem ativas e como as políticas de acesso relacionadas à sessão são aplicadas. + +Esta página cobre: + +- Configuração de TTL de sessão +- Máximo de dispositivos autenticados simultaneamente por aplicativo + +## Configuração de TTL de sessão \{#session-ttl-configuration} + +O TTL de sessão determina o tempo de vida máximo da sessão de login OIDC do Logto. +É uma **configuração em nível de locatário**: uma vez configurada, aplica-se a todos os aplicativos e fluxos de autenticação nesse locatário. + +### Comportamento padrão \{#default-behavior} + +- Por padrão, o TTL de sessão é de **14 dias**. +- Se nenhum TTL personalizado for configurado, o Logto continuará a usar esse valor padrão. + +### Configurar via Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +Você pode configurar o TTL de sessão no Console em: + +Console > Tenant > Settings > OIDC settings + +Use **Tempo máximo de vida da sessão** para atualizar o valor. + +:::note + +O Console usa **dias** para entrada e exibição, enquanto a configuração / API de sessão OIDC subjacente usa **segundos**. + +::: + +### Configurar via Management API \{#configure-via-management-api} + +Use esses endpoints para ler e atualizar a configuração de sessão OIDC: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +Exemplo (`ttl` em segundos): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` segundos = 14 dias. + +:::note + +Para implantações OSS, reinicie a instância do serviço após alterar `logto-config` para que o servidor possa captar as configurações OIDC mais recentes. + +Para aplicar atualizações de configuração OIDC automaticamente sem reiniciar o serviço, [habilite o cache central redis](/logto-oss/central-cache). + +::: + +## Máximo de dispositivos autenticados simultaneamente por aplicativo \{#max-concurrent-authenticated-devices-per-app} + +O máximo de dispositivos autenticados simultaneamente por aplicativo é um controle em nível de aplicativo que limita quantas concessões ativas cada usuário pode manter para um aplicativo específico. + +Isso é configurado através do campo `maxAllowedGrants` no `customClientMetadata` do aplicativo. +Saiba mais em [Estrutura de dados do aplicativo](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants). + +### Comportamento \{#behavior} + +Quando `maxAllowedGrants` é definido, o Logto avalia as concessões ativas do usuário para o aplicativo atual em cada autorização bem-sucedida. +Se o número de concessões ativas exceder o limite, o Logto revoga as concessões mais antigas primeiro. + +Se `maxAllowedGrants` não estiver definido, não há limite de concorrência. + +### Configurar via Logto Console \{#configure-via-logto-console} + +Você pode configurar isso na página de detalhes de cada aplicativo em: + + + Console > Applications > Application details > Concurrent device limit + + +Defina o número máximo de concessões ativas simultâneas (dispositivos) por usuário para o aplicativo atual. + +:::note + +Essa configuração não é suportada para aplicativos máquina para máquina, aplicativos protegidos e aplicativos SAML. + +::: + +## Recursos relacionados \{#related-resources} + +Sessões +Gerenciar sessões de usuário + + Gerenciar aplicativos autorizados pelo usuário (concessões) + + + Estrutura de dados do aplicativo: maxAllowedGrants + +Interagir com Management API diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index d9f37f22cef..fb106d4457b 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -12,114 +12,129 @@ Para acessar a funcionalidade de gerenciamento de usuários no Logto Console, na A tabela consiste em três colunas: -- **Usuário**: Exibe informações sobre o usuário, como avatar, nome completo, nome de usuário, número de telefone e e-mail. +- **Usuário**: Exibe informações sobre o usuário, como seu avatar, nome completo, nome de usuário, número de telefone e email. - **Do aplicativo**: Exibe o nome do aplicativo com o qual o usuário se registrou inicialmente. -- **Último login**: Exibe o carimbo de data / hora do login mais recente do usuário. +- **Último login**: Exibe o timestamp do login mais recente do usuário. -Há suporte para mapeamento de palavras-chave para [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email). +Ela suporta mapeamento de palavras-chave para [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email). ### Adicionar usuários \{#add-users} -Usando o Console, desenvolvedores podem criar novas contas para usuários finais. Para isso, clique no botão "Adicionar usuário" no canto superior direito da tela. +Usando o Console, os desenvolvedores podem criar novas contas para usuários finais. Para fazer isso, clique no botão "Adicionar usuário" no canto superior direito da tela. -Ao criar um usuário no Logto Console ou via Management API (não auto-registro pelo usuário final via UI), você deve fornecer pelo menos um identificador: `primary email`, `primary phone` ou `username`. O campo `name` é opcional. +Ao criar um usuário no Logto Console ou via Management API (não registrado pelo próprio usuário final via UI), você deve fornecer pelo menos um identificador: `primary email`, `primary phone` ou `username`. O campo `name` é opcional. -Após a criação do usuário, o Logto irá gerar automaticamente uma senha aleatória. A senha inicial aparecerá apenas uma vez, mas você pode [redefinir a senha](./manage-users#reset-user-password) posteriormente. Se quiser definir uma senha específica, utilize o Management API `patch /api/users/{userId}/password` para atualizá-la após a criação do usuário. +Após a criação do usuário, o Logto gerará automaticamente uma senha aleatória. A senha inicial aparecerá apenas uma vez, mas você pode [redefinir a senha](./manage-users#reset-user-password) posteriormente. Se você quiser definir uma senha específica, use o Management API `patch /api/users/{userId}/password` para atualizá-la após a criação do usuário. -Você pode copiar os **identificadores inseridos (endereço de e-mail / número de telefone / nome de usuário)** e a **senha inicial** com um clique, facilitando o compartilhamento dessas credenciais com o novo usuário para que ele possa fazer login e começar a usar. +Você pode copiar os **identificadores inseridos (endereço de email / número de telefone / nome de usuário)** e a **senha inicial** com um clique, facilitando o compartilhamento dessas credenciais com o novo usuário para que ele possa fazer login e começar. :::tip -Se você deseja implementar registro apenas por convite, recomendamos [convidar usuários com um link mágico](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Isso permite que apenas usuários na lista branca se auto-registrem e definam sua própria senha. +Se você deseja implementar registro apenas por convite, recomendamos [convidar usuários com um link mágico](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended). Isso permite que apenas usuários na lista de permissões se registrem e definam sua própria senha. ::: ### Visualizar e atualizar o perfil do usuário \{#view-and-update-the-user-profile} -Para visualizar os detalhes de um usuário, basta clicar na linha correspondente na tabela de usuários. Isso o levará à página "**Detalhes do usuário**", onde você pode encontrar as informações do perfil do usuário, incluindo: +Para visualizar os detalhes de um usuário, basta clicar na linha correspondente na tabela de usuários. Isso o levará à página "**Detalhes do Usuário**", onde você pode encontrar as informações do perfil do usuário, incluindo: - **Dados relacionados à autenticação**: - - **Endereço de e-mail** ([primary_email](/user-management/user-data#primary_email)): Editável + - **Endereço de email** ([primary_email](/user-management/user-data#primary_email)): Editável - **Número de telefone** ([primary_phone](/user-management/user-data#primary_phone)): Editável - **Nome de usuário** ([username](/user-management/user-data#username)): Editável - - **Senha** ([has_password](/user-management/user-data#has_password)): Você pode gerar uma senha aleatória novamente. Saiba mais em "[Redefinir senha do usuário](#reset-user-password)". - - **Autenticação multifatorial (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Veja todos os fatores de autenticação (por exemplo, passkeys, aplicativos autenticadores, códigos de backup) que este usuário configurou. Os fatores podem ser removidos no Console. - - **Passkeys**: Quando o [login com passkey](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) está habilitado no tenant, você também pode visualizar as passkeys de login do usuário na página de detalhes e removê-las se necessário. Essas passkeys são baseadas no mesmo modelo de credencial WebAuthn usado pelo MFA. - - **Token de acesso pessoal**: Crie, visualize, renomeie e exclua [tokens de acesso pessoal](/user-management/personal-access-token). + - **Senha** ([has_password](/user-management/user-data#has_password)): Você pode regenerar uma senha aleatória. Saiba mais sobre "[Redefinir senha do usuário](#reset-user-password)". + - **Autenticação multifatorial (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): Veja todos os fatores de autenticação (por exemplo, chaves de acesso, aplicativos autenticadores, códigos de backup) que este usuário configurou. Os fatores podem ser removidos no Console. + - **Chaves de acesso**: Quando o [login com chave de acesso](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) está habilitado no locatário, você também pode visualizar as chaves de acesso de login do usuário na página de detalhes do usuário e removê-las, se necessário. Essas chaves de acesso são suportadas pelo mesmo modelo de credencial WebAuthn usado pelo MFA. + - **Token de acesso pessoal**: Criar, visualizar, renomear e excluir [tokens de acesso pessoal](/user-management/personal-access-token). - **Conexão**: - **Conexões sociais** ([identities](/user-management/user-data#social-identities)): - - Veja as contas sociais vinculadas do usuário, incluindo IDs sociais e detalhes de perfil sincronizados dos provedores sociais (por exemplo, uma entrada "Facebook" aparecerá se o usuário fez login via Facebook). + - Veja as contas sociais vinculadas do usuário, incluindo IDs sociais e detalhes do perfil sincronizados de seus provedores sociais (por exemplo, uma entrada "Facebook" aparecerá se o usuário fez login via Facebook). - Você pode remover identidades sociais existentes, mas não pode vincular novas contas sociais em nome do usuário. - Para conectores sociais com [armazenamento de token](/secret-vault/federated-token-set) habilitado, você pode visualizar e gerenciar tokens de acesso e tokens de atualização na página de detalhes da conexão. - - **Conexões SSO corporativas (Enterprise SSO)** ([sso_identities](/user-management/user-data#sso-identities)): - - Veja as identidades corporativas vinculadas do usuário, incluindo IDs corporativos e detalhes de perfil sincronizados dos provedores de identidade corporativos. + - **Conexões SSO corporativas** ([sso_identities](/user-management/user-data#sso-identities)): + - Veja as identidades corporativas vinculadas do usuário, incluindo IDs corporativos e detalhes do perfil sincronizados de seus provedores de identidade corporativos. - Você não pode adicionar ou remover identidades SSO corporativas no Console. - Para conectores corporativos baseados em OIDC com [armazenamento de token](/secret-vault/federated-token-set) habilitado, você pode visualizar e excluir tokens na página de detalhes da conexão. -- **Dados do perfil do usuário**: nome, URL do avatar, dados personalizados e reivindicações padrão adicionais do OpenID Connect que não estão incluídas. Todos esses campos de perfil são editáveis. -- **Sessões**: Veja a lista de sessões ativas do usuário, incluindo informações do dispositivo, sessionId e localização geográfica, se aplicável. Veja mais detalhes de uma sessão e revogue-a na página de detalhes da sessão. +- **Dados do perfil do usuário**: nome, URL do avatar, dados personalizados e reivindicações padrão do OpenID Connect que não estão incluídas. Todos esses campos de perfil são editáveis. +- **Sessões**: Veja a lista de sessões ativas do usuário, incluindo informações do dispositivo, sessionId e localização GEO, se aplicável. Veja mais detalhes de uma sessão e revogue-a na página de detalhes da sessão. :::warning -É importante confirmar que o usuário possui um método alternativo de login antes de remover uma conexão social, como outra conexão social, número de telefone, e-mail ou nome de usuário com senha. Se o usuário não tiver outro método de login, ele não poderá acessar sua conta novamente após a remoção da conexão social. +É importante confirmar que o usuário tem um método alternativo de login antes de remover uma conexão social, como outra conexão social, número de telefone, email ou nome de usuário com senha. Se o usuário não tiver nenhum outro método de login, ele não poderá acessar sua conta novamente uma vez que a conexão social for removida. ::: ### Visualizar atividades do usuário \{#view-user-activities} -Para visualizar as atividades recentes de um usuário, navegue até a sub-aba "Logs do usuário" na página de detalhes do usuário. Aqui, você encontrará uma tabela que exibe as atividades recentes do usuário, incluindo a ação realizada, o resultado da ação, o aplicativo relacionado e o horário em que o usuário agiu. +Para visualizar as atividades recentes de um usuário, navegue até a sub-aba "Logs do usuário" na página "Detalhes do usuário". Aqui, você pode encontrar uma tabela que exibe as atividades recentes do usuário, incluindo a ação realizada, o resultado da ação, o aplicativo relacionado e o horário em que o usuário agiu. -Clique na linha da tabela para ver mais detalhes no log do usuário, como endereço IP, agente do usuário, dados brutos, etc. +Clique na linha da tabela para ver mais detalhes no log do usuário, por exemplo, endereço IP, agente do usuário, dados brutos, etc. ### Suspender usuário \{#suspend-user} -Na página de detalhes do usuário, clique em "Três pontos" -> botão "Suspender usuário". +Na página "Detalhes do usuário", clique em "Três pontos" -> botão "Suspender usuário". -Uma vez suspenso, o usuário não poderá fazer login no seu aplicativo e não poderá obter um novo token de acesso após o atual expirar. Além disso, qualquer solicitação de API feita por esse usuário falhará. +Uma vez que um usuário é suspenso, ele não poderá fazer login no seu aplicativo e não poderá obter um novo token de acesso após o atual expirar. Além disso, qualquer solicitação de API feita por esse usuário falhará. -Se quiser reativar esse usuário, basta clicar em "Três pontos" -> botão "Reativar usuário". +Se você quiser reativar esse usuário, pode fazê-lo clicando em "Três pontos" -> botão "Reativar usuário". ### Excluir usuário \{#delete-user} -Na página de detalhes do usuário, clique em "Três pontos" -> botão "Excluir". A exclusão do usuário não pode ser desfeita. +Na página "Detalhes do usuário", clique em "Três pontos" -> botão "Excluir". A exclusão do usuário não pode ser desfeita. ### Redefinir senha do usuário \{#reset-user-password} -Na página de detalhes do usuário, clique em "Três pontos" -> botão "Redefinir senha", e então o Logto irá gerar automaticamente uma senha aleatória. +Na página "Detalhes do usuário", clique em "Três pontos" -> botão "Redefinir senha", e então o Logto regenerará automaticamente uma senha aleatória. -Após redefinir a senha, copie e envie para o usuário final. Uma vez que o modal "Redefinir senha" for fechado, você não poderá mais visualizar a senha. Se esquecer de anotá-la, pode redefinir novamente. +Após redefinir a senha, copie e envie-a para o usuário final. Uma vez que o modal "Redefinir senha" é fechado, você não poderá mais visualizar a senha. Se esquecer de mantê-la, poderá redefini-la novamente. Você não pode definir uma senha específica para usuários no Logto Console, mas pode usar o [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` para especificar uma senha. ### Gerenciar sessões ativas do usuário \{#manage-user-active-sessions} -Na página de detalhes do usuário, navegue até a página "Detalhes da sessão" clicando no botão "Gerenciar" de uma sessão específica. Aqui você pode visualizar informações detalhadas sobre a sessão, como dispositivo, localização e horário de login. Se quiser desconectar o usuário dessa sessão, basta clicar no botão "Revogar sessão" no canto superior direito, e a sessão será revogada imediatamente. +Na página "Detalhes do usuário", navegue até a página "Detalhes da sessão" clicando no botão "Gerenciar" de uma sessão específica. Aqui você pode visualizar informações detalhadas sobre a sessão, como o dispositivo, localização e horário de login. Se você quiser desconectar o usuário dessa sessão, basta clicar no botão "Revogar sessão" no canto superior direito, e a sessão será imediatamente revogada. -- Por padrão, revogar uma sessão no Console também revogará todas as permissões de aplicativos de primeira parte associadas àquela sessão, e o usuário precisará fazer login novamente para restaurar o acesso. Quaisquer tokens opacos de acesso e tokens de atualização pré-emitidos para aplicativos de primeira parte também serão revogados imediatamente. -- Para aplicativos de terceiros com escopo `offline_access`, revogar uma sessão não revoga a permissão do aplicativo por padrão, e quaisquer tokens de atualização pré-emitidos ainda podem ser usados até que a permissão expire. +- Por padrão, revogar uma sessão no Console também revogará todas as concessões de aplicativos de primeira parte associadas a essa sessão, e o usuário precisará fazer login novamente para restaurar o acesso. Quaisquer tokens de acesso opacos pré-emitidos e tokens de atualização para aplicativos de primeira parte também serão revogados imediatamente. +- Para aplicativos de terceiros com escopo `offline_access`, revogar uma sessão não revoga a concessão do aplicativo por padrão, quaisquer tokens de atualização pré-emitidos ainda podem ser usados até que a concessão expire. + +### Gerenciar aplicativos de terceiros autorizados pelo usuário \{#manage-user-authorized-third-party-apps} + +Na página "Detalhes do usuário", você pode usar a seção "Aplicativos de terceiros autorizados" para revisar o status de autorização de aplicativos para o usuário. +Esta seção é suportada pelas APIs de gerenciamento de aplicativos autorizados pelo usuário (concessões). + +Para cada aplicativo autorizado, o Console mostra: + +- Nome do aplicativo +- ID do aplicativo +- Hora de criação do acesso + +Se você precisar remover o acesso, clique na ação de revogação e confirme no modal. + +Revogar uma autorização de aplicativo remove todas as concessões de terceiros ativas associadas a esse aplicativo para o usuário. Também revogará quaisquer tokens de acesso opacos pré-emitidos e tokens de atualização para esse aplicativo imediatamente. ## Verificação de conformidade de senha \{#password-compliance-check} -Após atualizar a [política de senha](/security/password-policy) no Logto, usuários existentes ainda poderão fazer login com suas senhas atuais. Apenas contas recém-criadas precisarão seguir a política de senha atualizada. +Após atualizar a [política de senha](/security/password-policy) no Logto, os usuários existentes ainda podem fazer login com suas senhas atuais. Apenas contas recém-criadas serão obrigadas a seguir a política de senha atualizada. -Para impor uma segurança mais forte, você pode usar o `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) para verificar se a senha de um usuário atende à política atual definida na experiência de login padrão. Se não atender, você pode solicitar ao usuário que atualize sua senha com um fluxo personalizado usando o [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). +Para impor uma segurança mais forte, você pode usar o `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) para verificar se a senha de um usuário atende à política atual definida na experiência de login padrão. Se não atender, você pode solicitar que o usuário atualize sua senha com um fluxo personalizado usando [Account API](/end-user-flows/account-settings/by-management-api#user-password-management). ### Gerenciar papéis dos usuários \{#manage-roles-of-users} -Na aba "Papéis" da página de detalhes do usuário, você pode facilmente atribuir ou remover papéis conforme necessário. Consulte [Controle de acesso baseado em papel (RBAC)](/authorization/role-based-access-control) para mais detalhes. +Na aba "Papéis" da página de detalhes do usuário, você pode facilmente atribuir ou remover papéis para atender ao seu resultado desejado. Consulte [Controle de acesso baseado em papel (RBAC)](/authorization/role-based-access-control) para mais detalhes. ### Visualizar as organizações às quais o usuário pertence \{#view-the-organizations-the-user-belongs-to} -O Logto suporta [organizações](/organizations/organization-management) e pode gerenciar seus membros. Você pode facilmente visualizar os detalhes do usuário e ver a qual organização ele pertence. +Logto suporta [organizações](/organizations/organization-management) e pode gerenciar seus membros. Você pode facilmente visualizar os detalhes do usuário e ver a qual organização ele pertence. ## Gerenciar via Logto Management API \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) é um conjunto de APIs que fornecem acesso ao serviço backend do Logto. Como mencionado anteriormente, a API de usuário é um componente crítico desse serviço e pode suportar uma ampla variedade de cenários. +[Management API](/concepts/core-service/#management-api) é uma coleção de APIs que fornecem acesso ao serviço de backend do Logto. Como mencionado anteriormente, a API de usuário é um componente crítico deste serviço e pode suportar uma ampla gama de cenários. -As APIs [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) relacionadas a usuários estão disponíveis em `/api/users`, exceto para atividades do usuário, ou seja, logs de usuário em `/api/logs?userId=:userId`. +As APIs [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) relacionadas ao usuário são montadas em `/api/users`, exceto para as atividades do usuário, ou seja, logs do usuário `/api/logs?userId=:userId`. -Você pode gerenciar usuários através do Management API em vários casos de uso, como [pesquisa avançada de usuários](/user-management/advanced-user-search), [criação em massa de contas](https://openapi.logto.io/operation/operation-createuser), [registro apenas por convite](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. +Você pode gerenciar usuários através do Management API em vários casos de uso. Como [pesquisa avançada de usuários](/user-management/advanced-user-search), [criação em massa de contas](https://openapi.logto.io/operation/operation-createuser), [registro apenas por convite](/end-user-flows/sign-up-and-sign-in/disable-user-registration), etc. -## Perguntas frequentes (FAQs) \{#faqs} +## FAQs \{#faqs}
@@ -129,8 +144,8 @@ Você pode gerenciar usuários através do Management API em vários casos de us -Devido à natureza do [Omni-sign-in](https://logto.io/products/omni-sign-in) do Logto, ele não foi projetado para restringir o acesso do usuário a determinados aplicativos antes da autenticação. -No entanto, você ainda pode definir papéis e permissões específicas por aplicativo para proteger seus recursos de API, e validar permissões no acesso à API após o login bem-sucedido do usuário. +Devido à natureza do [Omni-sign-in](https://logto.io/products/omni-sign-in) do Logto, ele não é projetado para restringir o acesso do usuário a determinados aplicativos antes da autenticação. +No entanto, você ainda pode projetar papéis e permissões específicos de aplicativos para proteger seus recursos de API e validar permissões no acesso à API após o login bem-sucedido do usuário. Consulte Autorização: [Controle de acesso baseado em papel (RBAC)](/authorization/role-based-access-control) para mais informações.
diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index f09607b5923..11148d1f0b8 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -1,55 +1,53 @@ --- id: signing-keys -title: คีย์สำหรับลงนาม (Signing keys) -sidebar_label: คีย์สำหรับลงนาม (Signing keys) +title: คีย์การลงนาม +sidebar_label: คีย์การลงนาม sidebar_position: 5 --- -# คีย์สำหรับลงนาม (Signing keys) +# คีย์การลงนาม -คีย์สำหรับลงนาม OIDC ของ Logto ([OIDC signing keys](https://auth.wiki/signing-key)) หรือที่รู้จักกันในชื่อ "OIDC private keys" และ "OIDC cookie keys" คือคีย์ที่ใช้สำหรับลงนาม JWTs ([โทเค็นการเข้าถึง (Access tokens)](https://auth.wiki/access-token) และ [โทเค็น ID (ID tokens)](https://auth.wiki/id-token)) และคุกกี้ของเบราว์เซอร์ใน [เซสชันการลงชื่อเข้าใช้ (sign-in sessions)](/end-user-flows/sign-out#what-is-a-logto-session) ของ Logto คีย์เหล่านี้จะถูกสร้างขึ้นเมื่อมีการ seed ฐานข้อมูล Logto ([โอเพ่นซอร์ส](/logto-oss)) หรือสร้าง tenant ใหม่ ([Cloud](/logto-cloud)) และสามารถจัดการได้ผ่าน [CLI](/logto-oss/using-cli) (โอเพ่นซอร์ส), Management API หรือ Console UI +คีย์การลงนาม [OIDC ของ Logto](https://auth.wiki/signing-key) หรือที่รู้จักกันในชื่อ "OIDC private keys" และ "OIDC cookie keys" เป็นคีย์การลงนามที่ใช้ในการลงนาม JWTs ([โทเค็นการเข้าถึง (access tokens)](https://auth.wiki/access-token) และ [โทเค็น ID (ID tokens)](https://auth.wiki/id-token)) และคุกกี้ของเบราว์เซอร์ใน [เซสชันการลงชื่อเข้าใช้](/sessions#what-is-a-logto-session) ของ Logto คีย์การลงนามเหล่านี้ถูกสร้างขึ้นเมื่อทำการเริ่มต้นฐานข้อมูล Logto ([open-source](/logto-oss)) หรือสร้างผู้เช่าใหม่ ([Cloud](/logto-cloud)) และสามารถจัดการได้ผ่าน [CLI](/logto-oss/using-cli) (open-source), Management APIs หรือ Console UI -โดยปกติ Logto จะใช้ อัลกอริทึม elliptic curve (EC) ในการสร้างลายเซ็นดิจิทัล อย่างไรก็ตาม เนื่องจากผู้ใช้มักต้องตรวจสอบลายเซ็นของ JWT และเครื่องมือรุ่นเก่าหลายตัวไม่รองรับอัลกอริทึม EC (รองรับเฉพาะ RSA) เราจึงได้เพิ่มฟีเจอร์สำหรับหมุน (rotate) คีย์ส่วนตัวและให้ผู้ใช้เลือกอัลกอริทึมสำหรับลายเซ็น (ทั้ง RSA และ EC) เพื่อให้แน่ใจว่าสามารถใช้งานร่วมกับบริการที่ใช้เครื่องมือตรวจสอบลายเซ็นรุ่นเก่าได้ +โดยค่าเริ่มต้น Logto ใช้อัลกอริทึม elliptic curve (EC) ในการสร้างลายเซ็นดิจิทัล อย่างไรก็ตาม เนื่องจากผู้ใช้มักต้องการตรวจสอบลายเซ็น JWT และเครื่องมือเก่าหลายตัวไม่รองรับอัลกอริทึม EC (รองรับเฉพาะ RSA) เราจึงได้พัฒนาฟังก์ชันการหมุนคีย์ส่วนตัวและอนุญาตให้ผู้ใช้เลือกอัลกอริทึมลายเซ็น (รวมถึงทั้ง RSA และ EC) เพื่อให้แน่ใจว่าระบบสามารถทำงานร่วมกับบริการที่ใช้เครื่องมือตรวจสอบลายเซ็นที่ล้าสมัยได้ :::note -ตามทฤษฎีแล้ว คีย์สำหรับลงนามไม่ควรถูกเปิดเผยและไม่มีวันหมดอายุ หมายความว่าไม่จำเป็นต้องหมุนคีย์ แต่การหมุนคีย์เป็นระยะหลังจากใช้งานไปช่วงเวลาหนึ่งจะช่วยเพิ่มความปลอดภัย +ในทางทฤษฎี คีย์การลงนามไม่ควรถูกเปิดเผยและไม่มีเวลาหมดอายุ หมายความว่าไม่จำเป็นต้องหมุนคีย์ อย่างไรก็ตาม การหมุนคีย์การลงนามเป็นระยะหลังจากช่วงเวลาหนึ่งสามารถเพิ่มความปลอดภัยได้ ::: -## ทำงานอย่างไร? \{#how-it-works} +## มันทำงานอย่างไร? \{#how-it-works} -- **OIDC private key** - เมื่อเริ่มต้น Logto instance จะมีการสร้างคู่คีย์ public / private ขึ้นโดยอัตโนมัติและลงทะเบียนใน OIDC provider ที่อยู่เบื้องหลัง ดังนั้นเมื่อ Logto ออก JWT ใหม่ (โทเค็นการเข้าถึง หรือ โทเค็น ID) โทเค็นจะถูกลงนามด้วยคีย์ส่วนตัว ในขณะเดียวกัน แอปพลิเคชันไคลเอนต์ใด ๆ ที่ได้รับ JWT สามารถใช้คีย์สาธารณะที่จับคู่กันเพื่อตรวจสอบลายเซ็นของโทเค็น เพื่อให้แน่ใจว่าโทเค็นไม่ได้ถูกแก้ไขโดยบุคคลที่สาม คีย์ส่วนตัวจะถูกป้องกันไว้บนเซิร์ฟเวอร์ Logto ส่วนคีย์สาธารณะจะเปิดเผยต่อสาธารณะและเข้าถึงได้ผ่านอินเทอร์เฟซ `/oidc/jwks` ของ OIDC endpoint สามารถระบุอัลกอริทึมของคีย์สำหรับลงนามได้ขณะสร้างคีย์ส่วนตัว โดย Logto จะใช้อัลกอริทึม EC (Elliptic Curve) เป็นค่าเริ่มต้น ผู้ดูแลระบบสามารถเปลี่ยนอัลกอริทึมเริ่มต้นเป็น RSA (Rivest-Shamir-Adleman) ได้โดยการหมุนคีย์ส่วนตัว -- **OIDC cookie key** - เมื่อผู้ใช้เริ่มต้น flow การลงชื่อเข้าใช้หรือสมัครสมาชิก จะมีการสร้าง "OIDC session" บนเซิร์ฟเวอร์ พร้อมกับชุดคุกกี้ในเบราว์เซอร์ ด้วยคุกกี้เหล่านี้ เบราว์เซอร์สามารถร้องขอ Logto Experience API เพื่อดำเนินการต่าง ๆ ในนามของผู้ใช้ เช่น ลงชื่อเข้าใช้ สมัครสมาชิก และรีเซ็ตรหัสผ่าน อย่างไรก็ตาม แตกต่างจาก JWT คุกกี้จะถูกลงนามและตรวจสอบโดยบริการ OIDC ของ Logto เองเท่านั้น ไม่จำเป็นต้องใช้การเข้ารหัสแบบอสมมาตร (asymmetric cryptography) ดังนั้นเราจึงไม่มีคีย์สาธารณะคู่กับคีย์สำหรับลงนามคุกกี้ และไม่ใช้อัลกอริทึมเข้ารหัสแบบอสมมาตร +- **OIDC private key** เมื่อเริ่มต้นใช้งาน Logto จะมีการสร้างคู่คีย์สาธารณะและคีย์ส่วนตัวโดยอัตโนมัติและลงทะเบียนในผู้ให้บริการ OIDC ที่อยู่เบื้องหลัง ดังนั้นเมื่อ Logto ออก JWT ใหม่ (โทเค็นการเข้าถึงหรือโทเค็น ID) โทเค็นจะถูกลงนามด้วยคีย์ส่วนตัว ในขณะเดียวกัน แอปพลิเคชันลูกค้าที่ได้รับ JWT สามารถใช้คีย์สาธารณะที่จับคู่กันเพื่อตรวจสอบลายเซ็นของโทเค็น เพื่อให้แน่ใจว่าโทเค็นไม่ได้ถูกแก้ไขโดยบุคคลที่สาม คีย์ส่วนตัวจะถูกป้องกันบนเซิร์ฟเวอร์ Logto ส่วนคีย์สาธารณะตามชื่อคือสาธารณะสำหรับทุกคน และสามารถเข้าถึงได้ผ่านอินเทอร์เฟซ `/oidc/jwks` ของ OIDC endpoint อัลกอริทึมคีย์การลงนามสามารถระบุได้เมื่อสร้างคีย์ส่วนตัว และ Logto ใช้อัลกอริทึม EC (Elliptic Curve) เป็นค่าเริ่มต้น ผู้ใช้ที่เป็นผู้ดูแลระบบสามารถเปลี่ยนอัลกอริทึมเริ่มต้นเป็น RSA (Rivest-Shamir-Adleman) โดยการหมุนคีย์ส่วนตัว +- **OIDC cookie key** เมื่อผู้ใช้เริ่มต้นการลงชื่อเข้าใช้หรือสมัครสมาชิก จะมีการสร้าง "OIDC session" บนเซิร์ฟเวอร์ รวมถึงชุดของคุกกี้เบราว์เซอร์ ด้วยคุกกี้เหล่านี้ เบราว์เซอร์สามารถร้องขอ Logto Experience API เพื่อดำเนินการโต้ตอบต่าง ๆ ในนามของผู้ใช้ เช่น การลงชื่อเข้าใช้ การสมัครสมาชิก และการรีเซ็ตรหัสผ่าน อย่างไรก็ตาม ไม่เหมือนกับ JWTs คุกกี้จะถูกลงนามและตรวจสอบโดยบริการ OIDC ของ Logto เอง ไม่จำเป็นต้องใช้มาตรการการเข้ารหัสแบบอสมมาตร ดังนั้นเราจึงไม่มีคีย์สาธารณะที่จับคู่กันสำหรับคีย์การลงนามคุกกี้ หรืออัลกอริทึมการเข้ารหัสแบบอสมมาตร -## หมุนคีย์สำหรับลงนามจาก Console UI \{#rotate-signing-keys-from-console-ui} +## หมุนคีย์การลงนามจาก Console UI \{#rotate-signing-keys-from-console-ui} -Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่วยให้คุณสร้าง OIDC private key และ cookie key ใหม่ใน tenant ของคุณ +Logto แนะนำฟีเจอร์ "Signing Keys Rotation" ซึ่งช่วยให้คุณสร้าง OIDC private key และ cookie key ใหม่ในผู้เช่าของคุณ -1. ไปที่ Console > Signing keys จากนั้นคุณสามารถจัดการทั้ง OIDC private keys และ OIDC cookie keys ได้ +1. ไปที่ คอนโซล > การตั้งค่าเทนเนนต์ > การกำหนดค่า OIDC จากนั้นคุณสามารถจัดการทั้ง OIDC private keys และ OIDC cookie keys ได้ 2. หากต้องการหมุนคีย์สำหรับลงนาม ให้คลิกปุ่ม "Rotate private keys" หรือ "Rotate cookie keys" เมื่อหมุนคีย์ส่วนตัว คุณสามารถเลือกอัลกอริทึมสำหรับลงนามได้ด้วย 3. คุณจะพบตารางที่แสดงคีย์สำหรับลงนามทั้งหมดที่ใช้งานอยู่ หมายเหตุ: คุณสามารถลบคีย์ก่อนหน้าได้ แต่ไม่สามารถลบคีย์ปัจจุบันได้ - | สถานะ | คำอธิบาย | - | -------- | ------------------------------------------------------------------------------------------ | - | ปัจจุบัน | หมายถึงคีย์นี้กำลังถูกใช้งานอยู่ในแอปพลิเคชันและ API ของคุณ | - | ก่อนหน้า | หมายถึงคีย์ที่เคยใช้งานมาก่อนแต่ถูกหมุนออกแล้ว โทเค็นที่ลงนามด้วยคีย์นี้ยังคงใช้งานได้อยู่ | + | สถานะ | คำอธิบาย | + | -------- | ---------------------------------------------------------------------------------- | + | ปัจจุบัน | หมายถึงคีย์นี้กำลังใช้งานอยู่ในแอปพลิเคชันและ API ของคุณ | + | ก่อนหน้า | หมายถึงคีย์ที่เคยใช้งานแต่ถูกหมุนออกแล้ว โทเค็นที่มีคีย์การลงนามนี้ยังคงใช้ได้อยู่ | -โปรดจำไว้ว่าการหมุนคีย์เกี่ยวข้องกับ 3 ขั้นตอนดังนี้: +โปรดจำไว้ว่าการหมุนเกี่ยวข้องกับการดำเนินการสามอย่างต่อไปนี้: -1. **สร้างคีย์สำหรับลงนามใหม่**: แอปพลิเคชัน **และ** API ทั้งหมดของคุณจะต้องใช้คีย์สำหรับลงนามใหม่นี้ -2. **หมุนคีย์ปัจจุบัน**: คีย์ที่มีอยู่จะถูกกำหนดสถานะเป็น "ก่อนหน้า" หลังการหมุน และจะไม่ถูกใช้กับแอปพลิเคชันและ API ที่สร้างใหม่ อย่างไรก็ตาม โทเค็นที่ลงนามด้วยคีย์นี้ยังคงใช้งานได้ -3. **ลบคีย์ก่อนหน้าของคุณ**: คีย์ที่มีสถานะ "ก่อนหน้า" จะถูกเพิกถอนและลบออกจากตาราง +1. **สร้างคีย์การลงนามใหม่**: สิ่งนี้จะต้องให้ **แอปพลิเคชัน** และ **API** ของคุณทั้งหมดใช้คีย์การลงนามใหม่ +2. **หมุนคีย์ปัจจุบัน**: คีย์ที่มีอยู่จะถูกกำหนดเป็น "ก่อนหน้า" หลังจากการหมุนและจะไม่ถูกใช้โดยแอปพลิเคชันและ API ที่สร้างขึ้นใหม่ อย่างไรก็ตาม โทเค็นที่ลงนามด้วยคีย์นี้ยังคงใช้ได้ +3. **ลบคีย์ก่อนหน้าของคุณ**: คีย์ที่ถูกระบุว่า "ก่อนหน้า" จะถูกเพิกถอนและลบออกจากตาราง :::warning -ห้ามหมุนคีย์สำหรับลงนามติดต่อกัน (สองครั้งขึ้นไป) เพราะอาจทำให้โทเค็นที่ออกไปแล้ว **ทั้งหมด** ใช้งานไม่ได้ +อย่าหมุนคีย์การลงนามติดต่อกัน (สองครั้งหรือมากกว่า) เนื่องจากอาจทำให้โทเค็นที่ออกทั้งหมดไม่ถูกต้อง -- สำหรับผู้ใช้ OSS หลังจากหมุนคีย์สำหรับลงนามแล้ว ต้องรีสตาร์ท Logto instance เพื่อให้คีย์ใหม่มีผล -- สำหรับผู้ใช้ Cloud คีย์สำหรับลงนามใหม่จะมีผลทันทีหลังการหมุน แต่โปรดอย่าหมุนคีย์สำหรับลงนามหลายครั้งติดต่อกัน +- สำหรับผู้ใช้ OSS หลังจากหมุนคีย์การลงนาม จำเป็นต้องรีสตาร์ท Logto instance เพื่อให้คีย์การลงนามใหม่มีผล +- สำหรับผู้ใช้ Cloud คีย์การลงนามใหม่จะมีผลทันทีหลังจากการหมุน แต่โปรดตรวจสอบว่าอย่าหมุนคีย์การลงนามหลายครั้งติดต่อกัน ::: ## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} - แนะนำอัลกอริทึม EC และ RSA สำหรับการลงนามใน JWT + บทนำสู่อัลกอริทึมการลงนาม EC และ RSA ใน JWT diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 0551df2e772..b87e237faf8 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -3,33 +3,34 @@ description: เรียนรู้วิธีใช้ Account API เพื sidebar_position: 1 --- -# การตั้งค่าบัญชีผู้ใช้ด้วย Account API +# การตั้งค่าบัญชีโดย Account API ## Logto Account API คืออะไร \{#what-is-logto-account-api} -Logto Account API คือชุด API ที่ครอบคลุมซึ่งเปิดให้ผู้ใช้ปลายทางเข้าถึง API ได้โดยตรงโดยไม่ต้องผ่าน Management API จุดเด่นมีดังนี้: +Logto Account API เป็นชุด API ที่ครอบคลุมซึ่งให้ผู้ใช้ปลายทางเข้าถึง API ได้โดยตรงโดยไม่ต้องผ่าน Management API นี่คือจุดเด่น: -- เข้าถึงโดยตรง: Account API ให้อำนาจผู้ใช้ปลายทางในการเข้าถึงและจัดการโปรไฟล์บัญชีของตนเองโดยตรง โดยไม่ต้องผ่าน Management API -- การจัดการโปรไฟล์ผู้ใช้และอัตลักษณ์: ผู้ใช้สามารถจัดการโปรไฟล์และการตั้งค่าความปลอดภัยได้อย่างเต็มที่ รวมถึงการอัปเดตข้อมูลอัตลักษณ์ เช่น อีเมล เบอร์โทรศัพท์ รหัสผ่าน และการจัดการการเชื่อมต่อโซเชียล รองรับ MFA และ SSO กำลังจะมาเร็ว ๆ นี้ -- การควบคุมการเข้าถึงระดับโกลบอล: ผู้ดูแลระบบมีสิทธิ์ควบคุมการเข้าถึงทั้งหมดและสามารถปรับแต่งแต่ละฟิลด์ได้ -- การอนุญาต (Authorization) ที่ไร้รอยต่อ: การอนุญาตง่ายกว่าที่เคย! เพียงใช้ `client.getAccessToken()` เพื่อรับโทเค็นการเข้าถึงทึบ (opaque access token) สำหรับ OP (Logto) และแนบไปกับ Authorization header เป็น `Bearer ` +- การเข้าถึงโดยตรง: Account API ช่วยให้ผู้ใช้ปลายทางสามารถเข้าถึงและจัดการโปรไฟล์บัญชีของตนเองได้โดยตรงโดยไม่ต้องใช้ Management API +- การจัดการโปรไฟล์ผู้ใช้และอัตลักษณ์: ผู้ใช้สามารถจัดการโปรไฟล์และการตั้งค่าความปลอดภัยของตนเองได้อย่างเต็มที่ รวมถึงความสามารถในการอัปเดตข้อมูลอัตลักษณ์ เช่น อีเมล โทรศัพท์ และรหัสผ่าน รวมถึงการจัดการการเชื่อมต่อทางสังคม การสนับสนุน MFA และ SSO กำลังจะมาเร็ว ๆ นี้ +- การควบคุมการเข้าถึงทั่วโลก: ผู้ดูแลระบบมีการควบคุมการเข้าถึงอย่างเต็มที่และสามารถปรับแต่งแต่ละฟิลด์ได้ +- การอนุญาตที่ราบรื่น: การอนุญาตง่ายกว่าที่เคย! เพียงใช้ `client.getAccessToken()` เพื่อรับโทเค็นการเข้าถึงทึบสำหรับ OP (Logto) และแนบไปกับส่วนหัว Authorization เป็น `Bearer ` -ด้วย Logto Account API คุณสามารถสร้างระบบจัดการบัญชีผู้ใช้แบบกำหนดเอง เช่น หน้าโปรไฟล์ ที่ผสานรวมกับ Logto ได้อย่างสมบูรณ์ +ด้วย Logto Account API คุณสามารถสร้างระบบจัดการบัญชีที่กำหนดเอง เช่น หน้าโปรไฟล์ที่ผสานรวมกับ Logto ได้อย่างเต็มที่ -ตัวอย่างการใช้งานที่พบบ่อย เช่น: +กรณีการใช้งานที่พบบ่อยมีดังนี้: - ดึงข้อมูลโปรไฟล์ผู้ใช้ - อัปเดตโปรไฟล์ผู้ใช้ - อัปเดตรหัสผ่านผู้ใช้ -- อัปเดตอัตลักษณ์ผู้ใช้ เช่น อีเมล เบอร์โทรศัพท์ และการเชื่อมต่อโซเชียล +- อัปเดตอัตลักษณ์ผู้ใช้รวมถึงอีเมล โทรศัพท์ และการเชื่อมต่อทางสังคม - จัดการปัจจัย MFA (การยืนยัน) - จัดการเซสชันผู้ใช้ +- จัดการแอปที่ผู้ใช้อนุญาต (การให้สิทธิ์) -ดูรายละเอียด API ที่มีได้ที่ [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) และ [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) +เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับ API ที่มีอยู่ โปรดเยี่ยมชม [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) และ [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) :::note -ฟีเจอร์ดูบัญชี SSO และลบบัญชี มีให้ใช้งานผ่าน Logto Management APIs ดูรายละเอียดการใช้งานที่ [การตั้งค่าบัญชีผู้ใช้ด้วย Management API](/end-user-flows/account-settings/by-management-api) +ฟีเจอร์การดูบัญชี SSO และการลบบัญชีมีให้บริการผ่าน Logto Management APIs ดู [การตั้งค่าบัญชีโดย Management API](/end-user-flows/account-settings/by-management-api) สำหรับรายละเอียดการใช้งาน ::: @@ -37,79 +38,80 @@ Logto Account API คือชุด API ที่ครอบคลุมซึ ไปที่ Console > Sign-in & account > Account center -Account API ถูกปิดใช้งานโดยค่าเริ่มต้น ดังนั้นการควบคุมการเข้าถึงจะถูกล็อกไว้ ให้สลับเปิด **Enable Account API** เพื่อเปิดใช้งาน +Account API ถูกปิดโดยค่าเริ่มต้น ดังนั้นการควบคุมการเข้าถึงจะถูกล็อก สลับ **Enable Account API** เพื่อเปิดใช้งาน -เมื่อเปิดใช้งานแล้ว ให้กำหนดสิทธิ์แต่ละฟิลด์สำหรับ identifiers, ข้อมูลโปรไฟล์ และการเข้าถึงโทเค็นของบุคคลที่สาม แต่ละฟิลด์รองรับ `Off`, `ReadOnly` หรือ `Edit` โดยค่าเริ่มต้นคือ `Off` +เมื่อเปิดใช้งานแล้ว ให้กำหนดสิทธิ์ต่อฟิลด์สำหรับตัวระบุ ข้อมูลโปรไฟล์ และการเข้าถึงโทเค็นของบุคคลที่สาม แต่ละฟิลด์รองรับ `Off`, `ReadOnly`, หรือ `Edit`; ค่าเริ่มต้นคือ `Off` 1. **ฟิลด์ความปลอดภัย**: - - ฟิลด์ประกอบด้วย: อีเมลหลัก, เบอร์โทรหลัก, อัตลักษณ์โซเชียล, รหัสผ่าน และ MFA - - ก่อนที่ผู้ใช้ปลายทางจะแก้ไขฟิลด์เหล่านี้ ต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับรหัสยืนยัน (verification record ID) ที่มีอายุ 10 นาที ดู [รับรหัสยืนยัน (verification record id)](#get-a-verification-record-id) - - หากต้องการใช้ WebAuthn passkey สำหรับ MFA ให้เพิ่มโดเมนแอป front-end ของคุณใน **WebAuthn Related Origins** เพื่อให้ account center และหน้าลงชื่อเข้าใช้สามารถแชร์ passkey ได้ ดู [เชื่อมโยง WebAuthn passkey ใหม่](#link-a-new-webauthn-passkey) + - ฟิลด์ประกอบด้วย: อีเมลหลัก โทรศัพท์หลัก อัตลักษณ์ทางสังคม รหัสผ่าน และ MFA + - ก่อนที่ผู้ใช้ปลายทางจะสามารถแก้ไขฟิลด์เหล่านี้ได้ พวกเขาต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับ ID บันทึกการยืนยัน 10 นาที ดู [Get a verification record id](#get-a-verification-record-id) + - เพื่อใช้ WebAuthn passkeys สำหรับ MFA ให้เพิ่มโดเมนแอป front-end ของคุณไปยัง **WebAuthn Related Origins** เพื่อให้ศูนย์บัญชีและประสบการณ์การลงชื่อเข้าใช้สามารถแชร์ passkeys ได้ ดู [Link a new WebAuthn passkey](#link-a-new-webauthn-passkey) 2. **ฟิลด์โปรไฟล์**: - - ฟิลด์ประกอบด้วย: ชื่อผู้ใช้, ชื่อ, อวาตาร์, [profile](/user-management/user-data#profile) (แอตทริบิวต์โปรไฟล์มาตรฐานอื่น ๆ) และ [custom data](/user-management/user-data#custom-data) - - ผู้ใช้ปลายทางสามารถแก้ไขฟิลด์เหล่านี้ได้โดยไม่ต้องยืนยันตัวตนเพิ่มเติม + - ฟิลด์ประกอบด้วย: ชื่อผู้ใช้ ชื่อ รูปประจำตัว [โปรไฟล์](/user-management/user-data#profile) (คุณลักษณะโปรไฟล์มาตรฐานอื่น ๆ) และ [ข้อมูลที่กำหนดเอง](/user-management/user-data#custom-data) + - ผู้ใช้ปลายทางสามารถแก้ไขได้โดยไม่ต้องมีการยืนยันเพิ่มเติม 3. **Secret vault**: - - สำหรับ OIDC หรือ OAuth social และ enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) จะเก็บโทเค็นการเข้าถึงและรีเฟรชของบุคคลที่สามอย่างปลอดภัยหลังการยืนยันตัวตน แอปสามารถเรียก API ภายนอก เช่น ซิงค์กิจกรรม Google Calendar ได้โดยไม่ต้องให้ผู้ใช้ลงชื่อเข้าใช้ซ้ำ การดึงโทเค็นจะพร้อมใช้งานโดยอัตโนมัติเมื่อเปิด Account API + - สำหรับ OIDC หรือ OAuth social และ enterprise connectors, Logto [secret vault](/secret-vault/federated-token-set) เก็บโทเค็นการเข้าถึงและรีเฟรชของบุคคลที่สามอย่างปลอดภัยหลังการยืนยัน แอปสามารถเรียก API ภายนอก เช่น การซิงค์เหตุการณ์ Google Calendar โดยไม่ต้องขอให้ผู้ใช้ลงชื่อเข้าใช้อีกครั้ง การดึงโทเค็นจะพร้อมใช้งานโดยอัตโนมัติเมื่อเปิดใช้งาน Account API 4. **การจัดการเซสชัน**: - - เมื่อเปิดใช้งาน ผู้ใช้สามารถดูและจัดการเซสชันที่ใช้งานอยู่ รวมถึงข้อมูลอุปกรณ์และเวลาลงชื่อเข้าใช้ล่าสุด ผู้ใช้ยังสามารถเพิกถอนเซสชันเพื่อออกจากระบบจากอุปกรณ์เฉพาะได้ - - ก่อนที่ผู้ใช้ปลายทางจะเข้าถึงการจัดการเซสชัน ต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับรหัสยืนยัน (verification record ID) ที่มีอายุ 10 นาที ดู [รับรหัสยืนยัน (verification record id)](#get-a-verification-record-id) + - เมื่อเปิดใช้งาน ผู้ใช้สามารถดูและจัดการเซสชันที่ใช้งานอยู่ รวมถึงข้อมูลอุปกรณ์และเวลาลงชื่อเข้าใช้ล่าสุด ผู้ใช้ยังสามารถเพิกถอนเซสชันเพื่อออกจากระบบจากอุปกรณ์เฉพาะ + - สิทธิ์ฟิลด์ `Sessions` เดียวกันนี้ยังควบคุม API แอปที่ผู้ใช้อนุญาต (การให้สิทธิ์) (ดูและเพิกถอนการให้สิทธิ์) + - ก่อนที่ผู้ใช้ปลายทางจะเข้าถึงการจัดการเซสชัน พวกเขาต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับ ID บันทึกการยืนยัน 10 นาที ดู [Get a verification record id](#get-a-verification-record-id) ## วิธีเข้าถึง Account API \{#how-to-access-account-api} :::note -เพื่อให้แน่ใจว่า access token มีสิทธิ์ที่เหมาะสม โปรดกำหนดค่า scopes ที่เกี่ยวข้องใน Logto config ของคุณให้ถูกต้อง +เพื่อให้แน่ใจว่าโทเค็นการเข้าถึงมีสิทธิ์ที่เหมาะสม ตรวจสอบให้แน่ใจว่าคุณได้กำหนดขอบเขตที่สอดคล้องกันใน Logto config ของคุณอย่างถูกต้อง -ตัวอย่างเช่น สำหรับ API `POST /api/my-account/primary-email` คุณต้องกำหนดค่า scope `email` สำหรับ API `POST /api/my-account/primary-phone` คุณต้องกำหนดค่า scope `phone` +ตัวอย่างเช่น สำหรับ API `POST /api/my-account/primary-email` คุณต้องกำหนดขอบเขต `email`; สำหรับ API `POST /api/my-account/primary-phone` คุณต้องกำหนดขอบเขต `phone` ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...ตัวเลือกอื่น ๆ - // เพิ่ม scopes ที่เหมาะสมกับกรณีใช้งานของคุณ + // เพิ่มขอบเขตที่เหมาะสมที่ตรงกับกรณีการใช้งานของคุณ scopes: [ - UserScope.Email, // สำหรับ `{POST,DELETE} /api/my-account/primary-email` - UserScope.Phone, // สำหรับ `{POST,DELETE} /api/my-account/primary-phone` - UserScope.CustomData, // จัดการ custom data - UserScope.Address, // จัดการ address + UserScope.Email, // สำหรับ API `{POST,DELETE} /api/my-account/primary-email` + UserScope.Phone, // สำหรับ API `{POST,DELETE} /api/my-account/primary-phone` + UserScope.CustomData, // เพื่อจัดการข้อมูลที่กำหนดเอง + UserScope.Address, // เพื่อจัดการที่อยู่ UserScope.Identities, // สำหรับ API ที่เกี่ยวข้องกับอัตลักษณ์และ MFA - UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้ - UserScope.Sessions, // จัดการเซสชันผู้ใช้ + UserScope.Profile, // เพื่อจัดการโปรไฟล์ผู้ใช้ + UserScope.Sessions, // เพื่อจัดการเซสชันผู้ใช้และการให้สิทธิ์แอป ], }; ``` ::: -### ดึง access token \{#fetch-an-access-token} +### ดึงโทเค็นการเข้าถึง \{#fetch-an-access-token} -หลังจากตั้งค่า SDK ในแอปของคุณแล้ว คุณสามารถใช้เมธอด `client.getAccessToken()` เพื่อดึง access token ซึ่งเป็นโทเค็นทึบ (opaque token) ที่ใช้เข้าถึง Account API ได้ +หลังจากตั้งค่า SDK ในแอปพลิเคชันของคุณแล้ว คุณสามารถใช้เมธอด `client.getAccessToken()` เพื่อดึงโทเค็นการเข้าถึง โทเค็นนี้เป็นโทเค็นทึบที่สามารถใช้เข้าถึง Account API ได้ -หากคุณไม่ได้ใช้ SDK อย่างเป็นทางการ ให้ตั้งค่า `resource` เป็นค่าว่างสำหรับ access token grant request ไปที่ `/oidc/token` +หากคุณไม่ได้ใช้ SDK อย่างเป็นทางการ คุณควรกำหนด `resource` ให้ว่างเปล่าสำหรับคำขอโทเค็นการเข้าถึงไปยัง `/oidc/token` -### เข้าถึง Account API ด้วย access token \{#access-account-api-using-access-token} +### เข้าถึง Account API โดยใช้โทเค็นการเข้าถึง \{#access-account-api-using-access-token} -คุณควรแนบ access token ในฟิลด์ `Authorization` ของ HTTP headers ในรูปแบบ Bearer (`Bearer YOUR_TOKEN`) เมื่อเรียกใช้งาน Account API +คุณควรรวมโทเค็นการเข้าถึงในฟิลด์ `Authorization` ของส่วนหัว HTTP ในรูปแบบ Bearer (`Bearer YOUR_TOKEN`) เมื่อโต้ตอบกับ Account API -ตัวอย่างการดึงข้อมูลบัญชีผู้ใช้: +นี่คือตัวอย่างการดึงข้อมูลบัญชีผู้ใช้: ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน \{#manage-basic-account-information} +## จัดการข้อมูลบัญชีพื้นฐาน \{#manage-basic-account-information} ### ดึงข้อมูลบัญชีผู้ใช้ \{#retrieve-user-account-information} -เพื่อดึงข้อมูลผู้ใช้ สามารถใช้ endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) +เพื่อดึงข้อมูลผู้ใช้ คุณสามารถใช้ endpoint [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -120,13 +122,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -ฟิลด์ใน response อาจแตกต่างกันไปตามการตั้งค่า account center +ฟิลด์ตอบกลับอาจแตกต่างกันไปขึ้นอยู่กับการตั้งค่าศูนย์บัญชี -### อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน \{#update-basic-account-information} +### อัปเดตข้อมูลบัญชีพื้นฐาน \{#update-basic-account-information} -ข้อมูลบัญชีผู้ใช้พื้นฐาน ได้แก่ ชื่อผู้ใช้, ชื่อ, อวาตาร์, custom data และข้อมูลโปรไฟล์อื่น ๆ +ข้อมูลบัญชีพื้นฐานประกอบด้วยชื่อผู้ใช้ ชื่อ รูปประจำตัว ข้อมูลที่กำหนดเอง และข้อมูลโปรไฟล์อื่น ๆ -เพื่ออัปเดต **username, name, avatar, และ customData** ใช้ endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) +เพื่ออัปเดต **username, name, avatar, และ customData** คุณสามารถใช้ endpoint [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -เพื่ออัปเดตข้อมูลโปรไฟล์อื่น ๆ เช่น **familyName, givenName, middleName, nickname, profile (profile page URL), website, gender, birthdate, zoneinfo, locale, และ address** ใช้ endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) +เพื่ออัปเดตข้อมูลโปรไฟล์อื่น ๆ รวมถึง **familyName, givenName, middleName, nickname, profile (URL หน้าข้อมูล), website, gender, birthdate, zoneinfo, locale, และ address** คุณสามารถใช้ endpoint [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -144,17 +146,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## จัดการ identifiers และข้อมูลสำคัญอื่น ๆ \{#manage-identifiers-and-other-sensitive-information} +## จัดการตัวระบุและข้อมูลที่ละเอียดอ่อนอื่น ๆ \{#manage-identifiers-and-other-sensitive-information} -ด้วยเหตุผลด้านความปลอดภัย Account API ต้องการการอนุญาต (Authorization) เพิ่มเติมสำหรับการดำเนินการที่เกี่ยวข้องกับ identifiers และข้อมูลสำคัญอื่น ๆ +ด้วยเหตุผลด้านความปลอดภัย Account API ต้องการชั้นการอนุญาตเพิ่มเติมสำหรับการดำเนินการที่เกี่ยวข้องกับตัวระบุและข้อมูลที่ละเอียดอ่อนอื่น ๆ -### รับรหัสยืนยัน (verification record id) \{#get-a-verification-record-id} +### รับ ID บันทึกการยืนยัน \{#get-a-verification-record-id} -ก่อนอื่น คุณต้องขอ **verification record ID** ที่มีอายุ 10 นาที (TTL) เพื่อใช้ยืนยันตัวตนผู้ใช้ก่อนอัปเดตข้อมูลสำคัญ หมายความว่าเมื่อผู้ใช้ยืนยันตัวตนสำเร็จผ่านรหัสผ่าน, อีเมล หรือ SMS จะมีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน เช่น identifiers, credentials, การเชื่อมต่อโซเชียล และ MFA +ก่อนอื่น คุณต้องได้รับ **ID บันทึกการยืนยัน** ที่มีอายุการใช้งาน 10 นาที (TTL) ซึ่งสามารถใช้เพื่อยืนยันตัวตนของผู้ใช้ก่อนที่จะอัปเดตข้อมูลที่ละเอียดอ่อน ซึ่งหมายความว่าเมื่อผู้ใช้ยืนยันตัวตนของตนเองผ่านรหัสผ่าน รหัสยืนยันทางอีเมล หรือรหัสยืนยันทาง SMS สำเร็จแล้ว พวกเขามีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน รวมถึงตัวระบุ ข้อมูลประจำตัว การเชื่อมต่อบัญชีสังคม และ MFA -เพื่อขอ verification record ID คุณสามารถ [ยืนยันรหัสผ่านผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) +เพื่อรับ ID บันทึกการยืนยัน คุณสามารถ [ยืนยันรหัสผ่านของผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) -#### ยืนยันรหัสผ่านผู้ใช้ \{#verify-the-users-password} +#### ยืนยันรหัสผ่านของผู้ใช้ \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -172,13 +174,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### ยืนยันโดยส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้ \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### ยืนยันโดยการส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้ \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -หากใช้วิธีนี้ คุณต้อง [ตั้งค่า email connector](/connectors/email-connectors/) หรือ [SMS connector](/connectors/sms-connectors/) และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template `UserPermissionValidation` แล้ว +เพื่อใช้วิธีนี้ คุณต้อง [กำหนดค่าตัวเชื่อมต่ออีเมล](/connectors/email-connectors/) หรือ [ตัวเชื่อมต่อ SMS](/connectors/sms-connectors/) และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต `UserPermissionValidation` แล้ว ::: -ตัวอย่างการขอรหัสยืนยันทางอีเมลและรับ verification record ID: +ใช้ตัวอย่างอีเมล ขอรหัสยืนยันใหม่และรับ ID บันทึกการยืนยัน: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -196,7 +198,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -เมื่อได้รับรหัสยืนยันแล้ว สามารถใช้รหัสนั้นอัปเดตสถานะการยืนยันของ verification record ได้ +เมื่อได้รับรหัสยืนยันแล้ว คุณสามารถใช้มันเพื่ออัปเดตสถานะการยืนยันของบันทึกการยืนยัน ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -205,17 +207,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -หลังจากยืนยันรหัสแล้ว คุณสามารถใช้ verification record ID เพื่ออัปเดต identifier ของผู้ใช้ได้ +หลังจากยืนยันรหัสแล้ว คุณสามารถใช้ ID บันทึกการยืนยันเพื่ออัปเดตตัวระบุของผู้ใช้ -ดูรายละเอียดเพิ่มเติมเกี่ยวกับการยืนยันได้ที่ [Security verification by Account API](/end-user-flows/security-verification) +เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับการยืนยัน โปรดดู [Security verification by Account API](/end-user-flows/security-verification) -### ส่ง request พร้อม verification record id \{#send-request-with-verification-record-id} +### ส่งคำขอพร้อม ID บันทึกการยืนยัน \{#send-request-with-verification-record-id} -เมื่อส่ง request เพื่ออัปเดต identifier ของผู้ใช้ ต้องแนบ verification record ID ใน request header ด้วยฟิลด์ `logto-verification-id` +เมื่อส่งคำขอเพื่ออัปเดตตัวระบุของผู้ใช้ คุณต้องรวม ID บันทึกการยืนยันในส่วนหัวของคำขอด้วยฟิลด์ `logto-verification-id` -### อัปเดตรหัสผ่านผู้ใช้ \{#update-users-password} +### อัปเดตรหัสผ่านของผู้ใช้ \{#update-users-password} -เพื่ออัปเดตรหัสผ่านผู้ใช้ ใช้ endpoint [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) +เพื่ออัปเดตรหัสผ่านของผู้ใช้ คุณสามารถใช้ endpoint [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -226,16 +228,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -เช่นเดียวกับรหัสผ่านที่สร้างระหว่างสมัครใช้งาน รหัสผ่านที่ตั้งผ่าน Account API ต้องเป็นไปตาม [นโยบายรหัสผ่าน](/security/password-policy) ที่คุณตั้งค่าไว้ใน Console > Security > Password policy Logto จะส่งผลการตรวจสอบและข้อความผิดพลาดโดยละเอียดหากรหัสผ่านไม่ผ่านนโยบาย +เช่นเดียวกับรหัสผ่านที่สร้างขึ้นในระหว่างการลงทะเบียน รหัสผ่านที่ตั้งผ่าน Account API ต้องเป็นไปตาม [นโยบายรหัสผ่าน](/security/password-policy) ที่คุณกำหนดใน Console > Security > Password policy Logto จะส่งผลการตรวจสอบและข้อความแสดงข้อผิดพลาดโดยละเอียดหากรหัสผ่านไม่เป็นไปตามนโยบาย ::: ### อัปเดตหรือเชื่อมโยงอีเมลใหม่ \{#update-or-link-new-email} :::note -หากใช้วิธีนี้ คุณต้อง [ตั้งค่า email connector](/connectors/email-connectors/) และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template `BindNewIdentifier` แล้ว +เพื่อใช้วิธีนี้ คุณต้อง [กำหนดค่าตัวเชื่อมต่ออีเมล](/connectors/email-connectors/) และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต `BindNewIdentifier` แล้ว ::: -เพื่ออัปเดตหรือเชื่อมโยงอีเมลใหม่ ต้องพิสูจน์ความเป็นเจ้าของอีเมลนั้นก่อน +เพื่ออัปเดตหรือเชื่อมโยงอีเมลใหม่ คุณควรพิสูจน์ความเป็นเจ้าของอีเมลก่อน เรียก endpoint [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) เพื่อขอรหัสยืนยัน @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -คุณจะพบ `verificationId` ใน response และได้รับรหัสยืนยันทางอีเมล ใช้รหัสนี้เพื่อยืนยันอีเมล +คุณจะพบ `verificationId` ในการตอบกลับ และได้รับรหัสยืนยันในอีเมล ใช้มันเพื่อยืนยันอีเมล ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,34 +257,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -หลังจากยืนยันรหัสแล้ว สามารถเรียก [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) เพื่ออัปเดตอีเมลของผู้ใช้ โดยตั้งค่า `verificationId` ใน request body เป็น `newIdentifierVerificationRecordId` +หลังจากยืนยันรหัสแล้ว คุณสามารถเรียก [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) เพื่ออัปเดตอีเมลของผู้ใช้ โดยตั้งค่า `verificationId` ในเนื้อหาคำขอเป็น `newIdentifierVerificationRecordId` -:::info[รหัสยืนยันสองชุดที่แตกต่างกัน] +:::info[ID บันทึกการยืนยันสองรายการที่แตกต่างกัน] -request นี้ต้องใช้ verification record ID สองชุด: +คำขอนี้ต้องการ ID บันทึกการยืนยันสองรายการที่แยกจากกัน: -- **`logto-verification-id` (header)**: พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย [ยืนยันรหัสผ่านผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมล/โทรศัพท์เดิมของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) -- **`newIdentifierVerificationRecordId` (body)**: พิสูจน์ความเป็นเจ้าของอีเมลใหม่ คือ `verificationRecordId` ที่ได้จาก `POST /api/verifications/verification-code` ข้างต้น +- **`logto-verification-id` (header)**: พิสูจน์ตัวตนของผู้ใช้ก่อนทำการเปลี่ยนแปลงที่ละเอียดอ่อน รับได้โดย [ยืนยันรหัสผ่านของผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ที่มีอยู่ของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) +- **`newIdentifierVerificationRecordId` (body)**: พิสูจน์ความเป็นเจ้าของของที่อยู่อีเมลใหม่ นี่คือ `verificationRecordId` ที่ส่งกลับจากการเรียก `POST /api/verifications/verification-code` ข้างต้น ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # พิสูจน์ตัวตนผู้ใช้ (จากรหัสผ่านหรืออีเมล/โทรศัพท์เดิม) + # พิสูจน์ตัวตนของผู้ใช้ (จากการยืนยันรหัสผ่านหรืออีเมล/โทรศัพท์ที่มีอยู่) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" พิสูจน์ความเป็นเจ้าของอีเมลใหม่ (จาก flow รหัสยืนยันข้างต้น) + # "newIdentifierVerificationRecordId" พิสูจน์ความเป็นเจ้าของของอีเมลใหม่ (จากกระบวนการยืนยันรหัสข้างต้น) --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -เช่นเดียวกับอีเมลที่เก็บระหว่างสมัครใช้งาน อีเมลใด ๆ ที่เชื่อมโยงผ่าน Account API ต้องผ่านการตรวจสอบ [blocklist](/security/blocklist) ที่คุณตั้งค่าไว้ใน Console > Security > Blocklist Logto จะปฏิเสธ request และส่ง error โดยละเอียดหากอีเมลละเมิดนโยบาย +เช่นเดียวกับอีเมลที่เก็บรวบรวมในระหว่างการลงทะเบียน อีเมลใด ๆ ที่เชื่อมโยงผ่าน Account API ต้องผ่านการตรวจสอบ [blocklist](/security/blocklist) ที่คุณกำหนดใน Console > Security > Blocklist Logto จะปฏิเสธคำขอและส่งข้อผิดพลาดโดยละเอียดหากอีเมลละเมิดนโยบาย ::: ### ลบอีเมลของผู้ใช้ \{#remove-the-users-email} -เพื่อลบอีเมลของผู้ใช้ ใช้ endpoint [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) +เพื่อลบอีเมลของผู้ใช้ คุณสามารถใช้ endpoint [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -290,17 +292,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### จัดการเบอร์โทรศัพท์ \{#manage-phone} +### จัดการโทรศัพท์ \{#manage-phone} :::note -หากใช้วิธีนี้ คุณต้อง [ตั้งค่า SMS connector](/connectors/sms-connectors/) และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template `BindNewIdentifier` แล้ว +เพื่อใช้วิธีนี้ คุณต้อง [กำหนดค่าตัวเชื่อมต่อ SMS](/connectors/sms-connectors/) และตรวจสอบให้แน่ใจว่าได้กำหนดค่าเทมเพลต `BindNewIdentifier` แล้ว ::: -คล้ายกับการอัปเดตอีเมล คุณสามารถใช้ endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) เพื่ออัปเดตหรือเชื่อมโยงเบอร์โทรใหม่ และใช้ endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) เพื่อลบเบอร์โทรของผู้ใช้ +คล้ายกับการอัปเดตอีเมล คุณสามารถใช้ endpoint [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) เพื่ออัปเดตหรือเชื่อมโยงโทรศัพท์ใหม่ และใช้ endpoint [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) เพื่อลบโทรศัพท์ของผู้ใช้ -### เชื่อมโยงโซเชียลใหม่ \{#link-a-new-social-connection} +### เชื่อมโยงการเชื่อมต่อทางสังคมใหม่ \{#link-a-new-social-connection} -เพื่อเชื่อมโยงโซเชียลใหม่ ต้องขอ authorization URL ก่อนด้วย [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) +เพื่อเชื่อมโยงการเชื่อมต่อทางสังคมใหม่ ก่อนอื่นคุณควรขอ URL การอนุญาตด้วย [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -309,13 +311,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`: ID ของ [social connector](/connectors/social-connectors/) -- `redirectUri`: URI ที่จะ redirect หลังผู้ใช้อนุญาตแอป คุณควรโฮสต์หน้าเว็บที่ URL นี้และดัก callback -- `state`: ค่าที่จะถูกส่งกลับหลังผู้ใช้อนุญาตแอป เป็นสตริงสุ่มเพื่อป้องกัน CSRF +- `connectorId`: ID ของ [ตัวเชื่อมต่อทางสังคม](/connectors/social-connectors/) +- `redirectUri`: URI ที่จะเปลี่ยนเส้นทางหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณควรโฮสต์หน้าเว็บที่ URL นี้และจับการเรียกกลับ +- `state`: สถานะที่จะส่งกลับหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน เป็นสตริงสุ่มที่ใช้เพื่อป้องกันการโจมตี CSRF -ใน response จะมี `verificationRecordId` ให้เก็บไว้ใช้ในขั้นตอนถัดไป +ในการตอบกลับ คุณจะพบ `verificationRecordId` เก็บไว้เพื่อใช้ในภายหลัง -หลังผู้ใช้อนุญาตแอป คุณจะได้รับ callback ที่ `redirectUri` พร้อมพารามิเตอร์ `state` จากนั้นใช้ endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) เพื่อตรวจสอบการเชื่อมโยงโซเชียล +หลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณจะได้รับการเรียกกลับที่ `redirectUri` พร้อมกับพารามิเตอร์ `state` จากนั้นคุณสามารถใช้ endpoint [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) เพื่อยืนยันการเชื่อมต่อทางสังคม ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,32 +326,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` คือข้อมูลที่ได้จาก social connector หลังผู้ใช้อนุญาตแอป คุณต้องดึง query parameters จาก `redirectUri` ในหน้า callback ของคุณและห่อเป็น JSON ในฟิลด์ `connectorData` +`connectorData` คือข้อมูลที่ส่งกลับโดยตัวเชื่อมต่อทางสังคมหลังจากที่ผู้ใช้อนุญาตแอปพลิเคชัน คุณต้องแยกและรับพารามิเตอร์การค้นหาจาก `redirectUri` ในหน้าการเรียกกลับของคุณ และห่อหุ้มเป็น JSON เป็นค่าของฟิลด์ `connectorData` -สุดท้าย ใช้ endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) เพื่อเชื่อมโยงโซเชียล +สุดท้าย คุณสามารถใช้ endpoint [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) เพื่อเชื่อมโยงการเชื่อมต่อทางสังคม -:::info[รหัสยืนยันสองชุดที่แตกต่างกัน] +:::info[ID บันทึกการยืนยันสองรายการที่แตกต่างกัน] -request นี้ต้องใช้ verification record ID สองชุด: +คำขอนี้ต้องการ ID บันทึกการยืนยันสองรายการที่แยกจากกัน: -- **`logto-verification-id` (header)**: พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย [ยืนยันรหัสผ่านผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมล/โทรศัพท์เดิมของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) -- **`newIdentifierVerificationRecordId` (body)**: ระบุอัตลักษณ์โซเชียลที่จะเชื่อมโยง คือ `verificationRecordId` ที่ได้จาก `POST /api/verifications/social` ข้างต้น +- **`logto-verification-id` (header)**: พิสูจน์ตัวตนของผู้ใช้ก่อนทำการเปลี่ยนแปลงที่ละเอียดอ่อน รับได้โดย [ยืนยันรหัสผ่านของผู้ใช้](#verify-the-users-password) หรือ [ส่งรหัสยืนยันไปยังอีเมลหรือโทรศัพท์ที่มีอยู่ของผู้ใช้](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) +- **`newIdentifierVerificationRecordId` (body)**: ระบุอัตลักษณ์ทางสังคมที่กำลังเชื่อมโยง นี่คือ `verificationRecordId` ที่ส่งกลับจากการเรียก `POST /api/verifications/social` ข้างต้น ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # พิสูจน์ตัวตนผู้ใช้ (จากรหัสผ่านหรืออีเมล/โทรศัพท์เดิม) + # พิสูจน์ตัวตนของผู้ใช้ (จากการยืนยันรหัสผ่านหรืออีเมล/โทรศัพท์ที่มีอยู่) -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" ระบุโซเชียลที่จะเชื่อมโยง (จาก flow social verification ข้างต้น) + # "newIdentifierVerificationRecordId" ระบุการเชื่อมต่อทางสังคมที่จะเชื่อมโยง (จากกระบวนการยืนยันทางสังคมข้างต้น) --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### ลบโซเชียลที่เชื่อมโยง \{#remove-a-social-connection} +### ลบการเชื่อมต่อทางสังคม \{#remove-a-social-connection} -เพื่อลบโซเชียลที่เชื่อมโยง ใช้ endpoint [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) +เพื่อลบการเชื่อมต่อทางสังคม คุณสามารถใช้ endpoint [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -364,23 +366,23 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto ::: :::note -หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ `mfa` ใน [การตั้งค่า account center](#how-to-enable-account-api) +เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ `mfa` ใน [การตั้งค่าศูนย์บัญชี](#how-to-enable-account-api) ::: -**ขั้นตอนที่ 1: เพิ่ม origin ของแอป front-end ของคุณใน Related Origins** +**ขั้นตอนที่ 1: เพิ่มต้นทางแอป front-end ของคุณไปยังต้นทางที่เกี่ยวข้อง** -WebAuthn passkey จะผูกกับ hostname เฉพาะที่เรียกว่า **Relying Party ID (RP ID)** เฉพาะแอปที่โฮสต์บน origin ของ RP ID เท่านั้นที่สามารถลงทะเบียนหรือยืนยันตัวตนด้วย passkey เหล่านั้นได้ +WebAuthn passkeys ถูกผูกกับชื่อโฮสต์เฉพาะที่เรียกว่า **Relying Party ID (RP ID)** เฉพาะแอปพลิเคชันที่โฮสต์บนต้นทางของ RP ID เท่านั้นที่สามารถลงทะเบียนหรือยืนยันด้วย passkeys เหล่านั้น -เนื่องจากแอป front-end ของคุณเรียก Account API จากโดเมนที่ต่างจากหน้าลงชื่อเข้าใช้ของ Logto คุณต้องตั้งค่า **Related Origins** เพื่ออนุญาตการดำเนินการ passkey ข้าม origin +เนื่องจากแอปพลิเคชัน front-end ของคุณเรียก Account API จากโดเมนที่แตกต่างจากหน้าการยืนยันตัวตนของ Logto คุณต้องกำหนดค่า **Related Origins** เพื่ออนุญาตการดำเนินการ passkey ข้ามต้นทาง -**Logto กำหนด RP ID อย่างไร:** +**วิธีที่ Logto กำหนด RP ID:** -- **ค่าเริ่มต้น**: หากใช้โดเมนเริ่มต้นของ Logto `https://[tenant-id].logto.app` RP ID คือ `[tenant-id].logto.app` -- **Custom domain**: หากตั้งค่า [custom domain](/logto-cloud/custom-domain) เช่น `https://auth.example.com` RP ID จะเป็น `auth.example.com` +- **การตั้งค่าเริ่มต้น**: หากคุณใช้โดเมนเริ่มต้นของ Logto เพียงอย่างเดียว `https://[tenant-id].logto.app` RP ID คือ `[tenant-id].logto.app` +- **โดเมนที่กำหนดเอง**: หากคุณได้กำหนดค่า [โดเมนที่กำหนดเอง](/logto-cloud/custom-domain) เช่น `https://auth.example.com` RP ID จะกลายเป็น `auth.example.com` -**ตั้งค่า Related Origins:** +**กำหนดค่า Related Origins:** -ใช้ endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) เพื่อเพิ่ม origin ของแอป front-end ของคุณ เช่น ถ้า account center ของแอปรันที่ `https://account.example.com`: +ใช้ endpoint [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) เพื่อเพิ่มต้นทางแอปพลิเคชัน front-end ของคุณ ตัวอย่างเช่น หากศูนย์บัญชีของแอปของคุณทำงานบน `https://account.example.com`: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn รองรับได้สูงสุด 5 label eTLD+1 ที่ไม่ซ้ำกันสำหรับ Related Origins โดย eTLD+1 (effective top-level domain plus one label) คือส่วนโดเมนที่ลงทะเบียนได้ เช่น: +WebAuthn รองรับสูงสุด 5 ป้าย eTLD+1 ที่ไม่ซ้ำกันสำหรับ Related Origins eTLD+1 (โดเมนระดับบนสุดที่มีผลบังคับใช้บวกหนึ่งป้าย) คือส่วนโดเมนที่สามารถลงทะเบียนได้ ตัวอย่างเช่น: -- `https://example.com`, `https://app.example.com`, และ `https://auth.example.com` นับเป็น **หนึ่ง** label (`example.com`) -- `https://shopping.com`, `https://shopping.co.uk`, และ `https://shopping.co.jp` ก็นับเป็น **หนึ่ง** label (`shopping`) -- `https://example.com` และ `https://another.com` นับเป็น **สอง** label +- `https://example.com`, `https://app.example.com`, และ `https://auth.example.com` นับเป็น **หนึ่ง** ป้าย (`example.com`) +- `https://shopping.com`, `https://shopping.co.uk`, และ `https://shopping.co.jp` นับเป็น **หนึ่ง** ป้าย (`shopping`) +- `https://example.com` และ `https://another.com` นับเป็น **สอง** ป้าย -หากต้องการรองรับมากกว่า 5 โดเมนที่แตกต่างกันสำหรับ Related Origins ดูรายละเอียดที่ [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) +หากคุณต้องการรองรับมากกว่า 5 โดเมนที่แตกต่างกันเป็น Related Origins โปรดดูเอกสาร [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) สำหรับรายละเอียด ::: -**ขั้นตอนที่ 2: ขอ registration options ใหม่** +**ขั้นตอนที่ 2: ขอการลงทะเบียนใหม่** -ใช้ endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) เพื่อขอ registration สำหรับ passkey ใหม่ Logto อนุญาตให้แต่ละบัญชีผู้ใช้ลงทะเบียน passkey ได้หลายอัน +ใช้ endpoint [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) เพื่อขอลงทะเบียนสำหรับ passkey ใหม่ Logto อนุญาตให้แต่ละบัญชีผู้ใช้ลงทะเบียน passkeys หลายรายการ ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -411,7 +413,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -response ที่ได้จะเป็น: +คุณจะได้รับการตอบกลับเช่น: ```json { @@ -421,25 +423,25 @@ response ที่ได้จะเป็น: } ``` -**ขั้นตอนที่ 3: ลงทะเบียน passkey ในเบราว์เซอร์** +**ขั้นตอนที่ 3: ลงทะเบียน passkey ในเบราว์เซอร์ท้องถิ่น** -ตัวอย่างใช้ [`@simplewebauthn/browser`](https://simplewebauthn.dev/) สามารถใช้ฟังก์ชัน `startRegistration` เพื่อสร้าง passkey ในเบราว์เซอร์ +ใช้ [`@simplewebauthn/browser`](https://simplewebauthn.dev/) เป็นตัวอย่าง คุณสามารถใช้ฟังก์ชัน `startRegistration` เพื่อลงทะเบียน passkey ในเบราว์เซอร์ท้องถิ่น ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // ข้อมูลที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1 + optionsJSON: registrationOptions, // ข้อมูลที่ส่งกลับโดยเซิร์ฟเวอร์ในขั้นตอนที่ 1 }); -// บันทึก response ไว้ใช้ในขั้นตอนถัดไป +// บันทึกการตอบกลับเพื่อใช้ในภายหลัง ``` **ขั้นตอนที่ 4: ยืนยันการลงทะเบียน passkey** -ใช้ endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) เพื่อตรวจสอบการลงทะเบียน passkey +ใช้ endpoint [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) เพื่อยืนยันการลงทะเบียน passkey -ขั้นตอนนี้จะตรวจสอบลายเซ็นดิจิทัลที่สร้างโดย authenticator เพื่อให้แน่ใจว่า passkey ถูกสร้างขึ้นอย่างถูกต้องและไม่ถูกแก้ไขระหว่างส่งข้อมูล +ขั้นตอนนี้ยืนยันลายเซ็นคริปโตกราฟีที่สร้างโดยตัวตรวจสอบเพื่อให้แน่ใจว่า passkey ถูกสร้างขึ้นอย่างถูกต้องและไม่ได้ถูกแก้ไขระหว่างการส่ง ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -448,12 +450,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`: response จากเบราว์เซอร์ในขั้นตอนที่ 2 -- `verificationRecordId`: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1 +- `payload`: การตอบกลับจากเบราว์เซอร์ท้องถิ่นในขั้นตอนที่ 2 +- `verificationRecordId`: ID บันทึกการยืนยันที่ส่งกลับโดยเซิร์ฟเวอร์ในขั้นตอนที่ 1 **ขั้นตอนที่ 5: เชื่อมโยง passkey** -สุดท้าย เชื่อมโยง passkey กับบัญชีผู้ใช้โดยใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) +สุดท้าย คุณสามารถเชื่อมโยง passkey กับบัญชีผู้ใช้โดยใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ [รับรหัสยืนยัน (verification record ID)](#get-a-verification-record-id) -- `type`: ประเภทของ MFA factor ปัจจุบันรองรับเฉพาะ `WebAuthn` -- `newIdentifierVerificationRecordId`: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1 +- `verification_record_id`: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน [Get a verification record ID](#get-a-verification-record-id) +- `type`: ประเภทของปัจจัย MFA ปัจจุบันรองรับเฉพาะ `WebAuthn` +- `newIdentifierVerificationRecordId`: ID บันทึกการยืนยันที่ส่งกลับโดยเซิร์ฟเวอร์ในขั้นตอนที่ 1 -### จัดการ WebAuthn passkey ที่มีอยู่ \{#manage-existing-webauthn-passkeys} +### จัดการ WebAuthn passkeys ที่มีอยู่ \{#manage-existing-webauthn-passkeys} -เพื่อจัดการ WebAuthn passkey ที่มีอยู่ ใช้ endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) เพื่อดึง passkey ปัจจุบันและปัจจัย MFA อื่น ๆ +เพื่อจัดการ WebAuthn passkeys ที่มีอยู่ คุณสามารถใช้ endpoint [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) เพื่อรับ passkeys ปัจจุบันและปัจจัยการยืนยัน MFA อื่น ๆ ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json [ @@ -493,8 +495,8 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ - `id`: ID ของการยืนยัน - `type`: ประเภทของการยืนยัน `WebAuthn` สำหรับ WebAuthn passkey -- `name`: ชื่อของ passkey (optional) -- `agent`: user agent ของ passkey +- `name`: ชื่อของ passkey ฟิลด์ที่ไม่จำเป็น +- `agent`: ตัวแทนผู้ใช้ของ passkey อัปเดตชื่อ passkey โดยใช้ endpoint [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname): @@ -521,7 +523,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v ::: :::note -หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ `mfa` ใน [การตั้งค่า account center](#how-to-enable-account-api) +เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ `mfa` ใน [การตั้งค่าศูนย์บัญชี](#how-to-enable-account-api) ::: **ขั้นตอนที่ 1: สร้าง TOTP secret** @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -544,9 +546,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp **ขั้นตอนที่ 2: แสดง TOTP secret ให้ผู้ใช้** -ใช้ secret นี้สร้าง QR code หรือแสดงให้ผู้ใช้โดยตรง ผู้ใช้ควรเพิ่ม secret นี้ในแอป authenticator (เช่น Google Authenticator, Microsoft Authenticator หรือ Authy) +ใช้ secret เพื่อสร้าง QR code หรือแสดงโดยตรงให้ผู้ใช้ ผู้ใช้ควรเพิ่มมันลงในแอปยืนยันตัวตนของตนเอง (เช่น Google Authenticator, Microsoft Authenticator, หรือ Authy) -รูปแบบ URI สำหรับ QR code คือ: +รูปแบบ URI สำหรับ QR code ควรเป็น: ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -560,7 +562,7 @@ otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp **ขั้นตอนที่ 3: ผูกปัจจัย TOTP** -หลังผู้ใช้เพิ่ม secret ในแอป authenticator แล้ว ต้องยืนยันและผูกกับบัญชีผู้ใช้ ใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) เพื่อผูกปัจจัย TOTP +หลังจากที่ผู้ใช้ได้เพิ่ม secret ลงในแอปยืนยันตัวตนของตนเองแล้ว พวกเขาจำเป็นต้องยืนยันและผูกมันกับบัญชีของตนเอง ใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) เพื่อผูกปัจจัย TOTP ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,27 +572,27 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ [รับรหัสยืนยัน (verification record ID)](#get-a-verification-record-id) +- `verification_record_id`: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน [Get a verification record ID](#get-a-verification-record-id) - `type`: ต้องเป็น `Totp` -- `secret`: TOTP secret ที่สร้างในขั้นตอนที่ 1 +- `secret`: TOTP secret ที่สร้างขึ้นในขั้นตอนที่ 1 :::note -ผู้ใช้สามารถมีปัจจัย TOTP ได้เพียงหนึ่งชุดเท่านั้น หากมีอยู่แล้ว การเพิ่มใหม่จะได้ error 422 +ผู้ใช้สามารถมีปัจจัย TOTP ได้เพียงหนึ่งรายการในแต่ละครั้ง หากผู้ใช้มีปัจจัย TOTP อยู่แล้ว การพยายามเพิ่มอีกหนึ่งรายการจะส่งผลให้เกิดข้อผิดพลาด 422 ::: -### จัดการ backup codes \{#manage-backup-codes} +### จัดการรหัสสำรอง \{#manage-backup-codes} :::note -อย่าลืม [เปิดใช้งาน MFA และ backup codes](/end-user-flows/mfa) ก่อน +อย่าลืม [เปิดใช้งาน MFA และรหัสสำรอง](/end-user-flows/mfa) ก่อน ::: :::note -หากใช้วิธีนี้ คุณต้องเปิดฟิลด์ `mfa` ใน [การตั้งค่า account center](#how-to-enable-account-api) +เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ `mfa` ใน [การตั้งค่าศูนย์บัญชี](#how-to-enable-account-api) ::: -**ขั้นตอนที่ 1: สร้าง backup codes ใหม่** +**ขั้นตอนที่ 1: สร้างรหัสสำรองใหม่** -ใช้ endpoint [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) เพื่อสร้าง backup codes ชุดใหม่ 10 รหัส +ใช้ endpoint [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) เพื่อสร้างชุดรหัสสำรองใหม่ 10 รหัส ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -606,20 +608,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back } ``` -**ขั้นตอนที่ 2: แสดง backup codes ให้ผู้ใช้** +**ขั้นตอนที่ 2: แสดงรหัสสำรองให้ผู้ใช้** -ก่อนผูก backup codes กับบัญชีผู้ใช้ คุณต้องแสดงรหัสเหล่านี้ให้ผู้ใช้และแนะนำให้: +ก่อนที่จะผูกมัดรหัสสำรองกับบัญชีของผู้ใช้ คุณต้องแสดงให้ผู้ใช้และแนะนำให้พวกเขา: -- ดาวน์โหลดหรือจดรหัสเหล่านี้ทันที +- ดาวน์โหลดหรือจดบันทึกรหัสเหล่านี้ทันที - เก็บไว้ในที่ปลอดภัย -- เข้าใจว่ารหัสแต่ละชุดใช้ได้เพียงครั้งเดียว -- ทราบว่ารหัสเหล่านี้คือทางเลือกสุดท้ายหากสูญเสียการเข้าถึง MFA หลัก +- เข้าใจว่ารหัสแต่ละรหัสสามารถใช้ได้เพียงครั้งเดียว +- ทราบว่ารหัสเหล่านี้เป็นทางเลือกสุดท้ายหากพวกเขาสูญเสียการเข้าถึงวิธี MFA หลักของตนเอง -ควรแสดงรหัสในรูปแบบที่ชัดเจน ง่ายต่อการคัดลอก และอาจมีตัวเลือกให้ดาวน์โหลด (เช่น ไฟล์ข้อความหรือ PDF) +คุณควรแสดงรหัสในรูปแบบที่ชัดเจนและง่ายต่อการคัดลอก และพิจารณาให้ตัวเลือกการดาวน์โหลด (เช่น เป็นไฟล์ข้อความหรือ PDF) -**ขั้นตอนที่ 3: ผูก backup codes กับบัญชีผู้ใช้** +**ขั้นตอนที่ 3: ผูกมัดรหัสสำรองกับบัญชีผู้ใช้** -ใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) เพื่อผูก backup codes กับบัญชีผู้ใช้ +ใช้ endpoint [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) เพื่อผูกมัดรหัสสำรองกับบัญชีของผู้ใช้ ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ [รับรหัสยืนยัน (verification record ID)](#get-a-verification-record-id) +- `verification_record_id`: ID บันทึกการยืนยันที่ถูกต้อง ได้รับจากการยืนยันปัจจัยที่มีอยู่ของผู้ใช้ คุณสามารถดูรายละเอียดเพิ่มเติมได้ในส่วน [Get a verification record ID](#get-a-verification-record-id) - `type`: ต้องเป็น `BackupCode` -- `codes`: อาร์เรย์ของ backup codes ที่สร้างในขั้นตอนก่อนหน้า +- `codes`: อาร์เรย์ของรหัสสำรองที่สร้างขึ้นในขั้นตอนก่อนหน้า :::note -- ผู้ใช้สามารถมี backup codes ได้เพียงชุดเดียว หากใช้หมดแล้วต้องสร้างและผูกใหม่ -- backup codes ไม่สามารถเป็น MFA factor เดียวได้ ผู้ใช้ต้องมี MFA factor อื่น (เช่น WebAuthn หรือ TOTP) อย่างน้อยหนึ่งรายการ -- backup code แต่ละรหัสใช้ได้เพียงครั้งเดียว +- ผู้ใช้สามารถมีชุดรหัสสำรองได้เพียงชุดเดียวในแต่ละครั้ง หากรหัสทั้งหมดถูกใช้แล้ว ผู้ใช้จำเป็นต้องสร้างและผูกมัดรหัสใหม่ +- รหัสสำรองไม่สามารถเป็นปัจจัย MFA เพียงอย่างเดียวได้ ผู้ใช้ต้องมีปัจจัย MFA อื่นอย่างน้อยหนึ่งรายการ (เช่น WebAuthn หรือ TOTP) ที่เปิดใช้งาน +- รหัสสำรองแต่ละรหัสสามารถใช้ได้เพียงครั้งเดียว ::: -**ดู backup codes ที่มีอยู่** +**ดูรหัสสำรองที่มีอยู่** -เพื่อดู backup codes ที่มีอยู่และสถานะการใช้งาน ใช้ endpoint [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes): +เพื่อดูรหัสสำรองที่มีอยู่และสถานะการใช้งานของพวกเขา ใช้ endpoint [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes): ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -ตัวอย่าง response: +เนื้อหาตอบกลับจะมีลักษณะดังนี้: ```json { @@ -667,19 +669,19 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes } ``` -- `code`: backup code -- `usedAt`: เวลาที่ใช้รหัสนี้ `null` หากยังไม่ถูกใช้ +- `code`: รหัสสำรอง +- `usedAt`: เวลาที่รหัสถูกใช้ `null` หากยังไม่ได้ใช้ ### จัดการเซสชันผู้ใช้ \{#manage-user-sessions} -**แสดงรายการเซสชันที่ใช้งานอยู่** +**รายการเซสชันที่ใช้งานอยู่** -เพื่อแสดงรายการเซสชันที่ใช้งานของผู้ใช้ ใช้ endpoint [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) +เพื่อแสดงรายการเซสชันที่ใช้งานอยู่ของผู้ใช้ คุณสามารถใช้ endpoint [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) :::note -- ต้องใช้ scope `UserScope.Sessions` เพื่อเข้าถึง endpoint นี้ -- ฟิลด์ `Sessions` ในการตั้งค่า account center ต้องตั้งเป็น `ReadOnly` หรือ `Edit` +- ต้องการขอบเขต `UserScope.Sessions` เพื่อเข้าถึง endpoint นี้ +- ฟิลด์ `Sessions` ในการตั้งค่าศูนย์บัญชีต้องตั้งค่าเป็น `ReadOnly` หรือ `Edit` ::: @@ -690,14 +692,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**เพิกถอนเซสชันด้วย session ID** +**เพิกถอนเซสชันโดยใช้ ID เซสชัน** เพื่อเพิกถอนเซสชันเฉพาะ ใช้ endpoint [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) :::note -- ต้องใช้ scope `UserScope.Sessions` เพื่อเข้าถึง endpoint นี้ -- ฟิลด์ `Sessions` ในการตั้งค่า account center ต้องตั้งเป็น `Edit` +- ต้องการขอบเขต `UserScope.Sessions` เพื่อเข้าถึง endpoint นี้ +- ฟิลด์ `Sessions` ในการตั้งค่าศูนย์บัญชีต้องตั้งค่าเป็น `Edit` ::: ```bash @@ -707,9 +709,60 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} -H 'content-type: application/json' ``` -พารามิเตอร์ query ที่เลือกได้: +พารามิเตอร์การค้นหาเพิ่มเติม: -- `revokeGrantsTarget`: ระบุเป้าหมายของ grant ที่จะเพิกถอนพร้อมกับเซสชัน ค่าที่เป็นไปได้: - - `all`: เพิกถอน grant ทั้งหมดที่เกี่ยวข้องกับเซสชัน - - `firstParty`: เพิกถอนเฉพาะ grant ของแอป first-party ที่เกี่ยวข้องกับเซสชัน (แนะนำสำหรับกรณีส่วนใหญ่ เพราะเพิกถอนการเข้าถึงเฉพาะแอปของคุณเองโดยยังคง grant ของแอป third-party ไว้ เพื่อประสบการณ์ผู้ใช้ที่ดีกว่า) - - ไม่ระบุ: พฤติกรรมเริ่มต้นจะเพิกถอน grant ที่ไม่มี scope `offline_access` ซึ่งโดยทั่วไปหมายถึงการเพิกถอน grant ที่ไม่ใช่ refresh token สำหรับเซสชันนั้น +- `revokeGrantsTarget`: ระบุเป้าหมายของการให้สิทธิ์ที่จะเพิกถอนพร้อมกับเซสชัน ค่าเป็นไปได้: + - `all`: เพิกถอนการให้สิทธิ์ทั้งหมดที่เกี่ยวข้องกับเซสชัน + - `firstParty`: เพิกถอนเฉพาะการให้สิทธิ์แอป first-party ที่เกี่ยวข้องกับเซสชัน (แนะนำสำหรับกรณีการใช้งานส่วนใหญ่ เนื่องจากจะเพิกถอนการเข้าถึงสำหรับแอปของคุณเองในขณะที่รักษาการให้สิทธิ์แอป third-party ไว้ ทำให้ประสบการณ์ผู้ใช้ดีขึ้น) + - ไม่ระบุ: พฤติกรรมเริ่มต้นเพิกถอนการให้สิทธิ์ที่ไม่มีขอบเขต `offline_access` ซึ่งโดยทั่วไปหมายถึงการเพิกถอนการให้สิทธิ์ที่ไม่ใช่โทเค็นรีเฟรชสำหรับเซสชัน + +### จัดการแอปที่ผู้ใช้อนุญาต (การให้สิทธิ์) \{#manage-user-authorized-apps-grants} + +ใช้ API แอปที่ผู้ใช้อนุญาต (การให้สิทธิ์) เมื่อผู้ใช้ต้องการตรวจสอบและเพิกถอนแอปที่อนุญาตจากหน้าการตั้งค่าบัญชีของตนเอง + +:::note + +- API การให้สิทธิ์แอปใช้โมเดลสิทธิ์เดียวกันกับ API เซสชัน +- ต้องการขอบเขต `UserScope.Sessions` +- ฟิลด์ `Sessions` ในการตั้งค่าศูนย์บัญชีต้องเปิดใช้งาน: + - `ReadOnly` หรือ `Edit` เพื่อแสดงรายการการให้สิทธิ์ + - `Edit` เพื่อเพิกถอนการให้สิทธิ์ + +::: + +**แสดงรายการการให้สิทธิ์แอปที่ใช้งานอยู่** + +เพื่อแสดงรายการการให้สิทธิ์แอปที่ใช้งานอยู่ของผู้ใช้ปัจจุบัน ใช้ endpoint [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +พารามิเตอร์การค้นหาเพิ่มเติม: + +- `appType=firstParty`: ส่งคืนเฉพาะการให้สิทธิ์แอป first-party +- `appType=thirdParty`: ส่งคืนเฉพาะการให้สิทธิ์แอป third-party +- ละเว้น `appType`: ส่งคืนการให้สิทธิ์ที่ใช้งานอยู่ทั้งหมด + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**เพิกถอนการให้สิทธิ์แอปโดยใช้ ID การให้สิทธิ์** + +เพื่อเพิกถอนการให้สิทธิ์แอปเฉพาะ ใช้ endpoint [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +เมื่อการให้สิทธิ์ถูกเพิกถอน โทเค็นการเข้าถึงทึบและโทเค็นรีเฟรชที่ออกก่อนหน้านี้สำหรับการให้สิทธิ์นั้นจะถูกทำให้เป็นโมฆะ diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index dc770e4e360..dd4f3a3aca9 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -2,203 +2,218 @@ sidebar_position: 2 --- -# การตั้งค่าบัญชีผู้ใช้ผ่าน Management API +# การตั้งค่าบัญชีโดย Management API -## การเชื่อมต่อระบบ \{#integrations} +## การผสานรวม \{#integrations} -Logto มี Management API หลายรายการสำหรับจัดการบัญชีผู้ใช้ คุณสามารถใช้ API เหล่านี้เพื่อสร้างหน้าตั้งค่าบัญชีแบบบริการตนเองสำหรับผู้ใช้ปลายทาง +Logto มี Management API หลายตัวเพื่อจัดการบัญชีผู้ใช้ คุณสามารถใช้ API เหล่านี้เพื่อสร้างหน้าการตั้งค่าบัญชีที่ผู้ใช้สามารถจัดการได้ด้วยตนเอง ### สถาปัตยกรรม \{#architecture} ```mermaid graph TB - A[ผู้ใช้] --> B[แอปพลิเคชันฝั่งไคลเอนต์] - B -->|เรียก API ตั้งค่าบัญชีแบบโฮสต์เอง|C[แอปพลิเคชันฝั่งเซิร์ฟเวอร์] - C -->|เรียก Management API| D[Logto] + A[User] --> B[Client application] + B -->|Self-hosted account settings API call|C[Server-side application] + C -->|Management API call| D[Logto] ``` -1. **ผู้ใช้**: ผู้ใช้ปลายทางที่ได้รับการยืนยันตัวตนแล้วซึ่งต้องการเข้าถึงและจัดการการตั้งค่าบัญชีของตน -2. **แอปพลิเคชันฝั่งไคลเอนต์**: แอปพลิเคชันฝั่งไคลเอนต์ของคุณที่ให้บริการหน้าตั้งค่าบัญชีแก่ผู้ใช้ -3. **แอปพลิเคชันฝั่งเซิร์ฟเวอร์**: แอปพลิเคชันฝั่งเซิร์ฟเวอร์ที่ให้บริการ API ตั้งค่าบัญชีแก่ไคลเอนต์ และเชื่อมต่อกับ Logto Management API -4. **Logto**: Logto ในฐานะบริการการยืนยันตัวตน (Authentication) และการอนุญาต (Authorization) ให้บริการ Management API สำหรับจัดการบัญชีผู้ใช้ +1. **User**: ผู้ใช้ที่ได้รับการยืนยันตัวตนซึ่งต้องการเข้าถึงและจัดการการตั้งค่าบัญชีของตน +2. **Client application**: แอปพลิเคชันของคุณที่ให้บริการหน้าการตั้งค่าบัญชีแก่ผู้ใช้ +3. **Server-side application**: แอปพลิเคชันฝั่งเซิร์ฟเวอร์ที่ให้บริการ API การตั้งค่าบัญชีแก่ไคลเอนต์ ทำงานร่วมกับ Logto Management API +4. **Logto**: Logto ในฐานะบริการการยืนยันตัวตนและการอนุญาต ให้บริการ Management API เพื่อจัดการบัญชีผู้ใช้ -### ลำดับขั้นตอน \{#sequence-diagram} +### แผนภาพลำดับ \{#sequence-diagram} ```mermaid sequenceDiagram autonumber - actor User as ผู้ใช้ - participant Client as แอปไคลเอนต์ - participant Server as แอปเซิร์ฟเวอร์ + actor User as User + participant Client as Client app + participant Server as Server-side application participant Logto as Logto - User ->> Client: เข้าถึงแอปไคลเอนต์ + User ->> Client: Access client app Client ->> Logto: POST /oidc/auth - User -->> Logto: ลงชื่อเข้าใช้ - Logto -->> Client: เปลี่ยนเส้นทางกลับไปยังแอปไคลเอนต์ + User -->> Logto: sign in + Logto -->> Client: Redirect to client app Client ->> Logto: POST /oidc/token - Logto ->> Client: โทเค็นการเข้าถึง A - Client ->> Server: GET /account-settings (พร้อมโทเค็นการเข้าถึง A) - Server ->> Logto: POST /oidc/token (พร้อม client credentials) - Logto ->> Server: โทเค็นการเข้าถึง B - Server ->> Logto: GET /api/users/{userId} (พร้อมโทเค็นการเข้าถึง B) - Logto ->> Server: รายละเอียดผู้ใช้ - Server ->> Client: รายละเอียดผู้ใช้ + Logto ->> Client: Access token A + Client ->> Server: GET /account-settings (with access token A) + Server ->> Logto: POST /oidc/token (with client credentials) + Logto ->> Server: Access token B + Server ->> Logto: GET /api/users/{userId} (with access token B) + Logto ->> Server: User details + Server ->> Client: User details ``` -1. ผู้ใช้เข้าถึงแอปพลิเคชันฝั่งไคลเอนต์ -2. แอปไคลเอนต์ส่งคำขอการยืนยันตัวตน (Authentication request) ไปยัง Logto และเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าลงชื่อเข้าใช้ของ Logto +1. ผู้ใช้เข้าถึงแอปพลิเคชันไคลเอนต์ +2. แอปพลิเคชันไคลเอนต์ส่งคำขอการยืนยันตัวตนไปยัง Logto และเปลี่ยนเส้นทางผู้ใช้ไปยังหน้าลงชื่อเข้าใช้ของ Logto 3. ผู้ใช้ลงชื่อเข้าใช้ Logto -4. ผู้ใช้ที่ได้รับการยืนยันตัวตนแล้วจะถูกเปลี่ยนเส้นทางกลับไปยังแอปไคลเอนต์พร้อมโค้ดการอนุญาต (authorization code) -5. แอปไคลเอนต์ขอโทเค็นการเข้าถึง (Access token) จาก Logto สำหรับเข้าถึง API ตั้งค่าบัญชีแบบโฮสต์เอง -6. Logto ออกโทเค็นการเข้าถึงให้แอปไคลเอนต์ -7. แอปไคลเอนต์ส่งคำขอตั้งค่าบัญชีไปยังแอปเซิร์ฟเวอร์พร้อมโทเค็นการเข้าถึงของผู้ใช้ -8. แอปเซิร์ฟเวอร์ตรวจสอบตัวตนและสิทธิ์ของผู้ร้องขอจากโทเค็นการเข้าถึงของผู้ใช้ จากนั้นขอโทเค็นการเข้าถึง Management API จาก Logto -9. Logto ออกโทเค็นการเข้าถึง Management API ให้แอปเซิร์ฟเวอร์ -10. แอปเซิร์ฟเวอร์ขอข้อมูลผู้ใช้จาก Logto โดยใช้โทเค็นการเข้าถึง Management API -11. Logto ตรวจสอบตัวตนของเซิร์ฟเวอร์และสิทธิ์ Management API แล้วส่งข้อมูลผู้ใช้กลับ -12. แอปเซิร์ฟเวอร์ประมวลผลข้อมูลผู้ใช้ตามสิทธิ์ของผู้ร้องขอและส่งรายละเอียดบัญชีผู้ใช้กลับไปยังแอปไคลเอนต์ +4. ผู้ใช้ที่ได้รับการยืนยันตัวตนจะถูกเปลี่ยนเส้นทางกลับไปยังแอปพลิเคชันไคลเอนต์พร้อมรหัสการอนุญาต +5. แอปพลิเคชันไคลเอนต์ขอโทเค็นการเข้าถึงจาก Logto สำหรับการเข้าถึง API การตั้งค่าบัญชีที่โฮสต์เอง +6. Logto ให้โทเค็นการเข้าถึงแก่แอปพลิเคชันไคลเอนต์ +7. แอปพลิเคชันไคลเอนต์ส่งคำขอการตั้งค่าบัญชีไปยังแอปพลิเคชันฝั่งเซิร์ฟเวอร์พร้อมโทเค็นการเข้าถึงของผู้ใช้ +8. แอปพลิเคชันฝั่งเซิร์ฟเวอร์ตรวจสอบตัวตนและสิทธิ์ของผู้ร้องขอจากโทเค็นการเข้าถึงของผู้ใช้ จากนั้นขอโทเค็นการเข้าถึง Management API จาก Logto +9. Logto ให้โทเค็นการเข้าถึง Management API แก่แอปพลิเคชันฝั่งเซิร์ฟเวอร์ +10. แอปพลิเคชันฝั่งเซิร์ฟเวอร์ขอข้อมูลผู้ใช้จาก Logto โดยใช้โทเค็นการเข้าถึง Management API +11. Logto ตรวจสอบตัวตนของเซิร์ฟเวอร์และสิทธิ์ Management API และส่งคืนข้อมูลผู้ใช้ +12. แอปพลิเคชันฝั่งเซิร์ฟเวอร์ประมวลผลข้อมูลผู้ใช้ตามสิทธิ์ของผู้ร้องขอและส่งคืนรายละเอียดบัญชีผู้ใช้ไปยังแอปพลิเคชันไคลเอนต์ -### การเชื่อมต่อ Management API กับแอปฝั่งเซิร์ฟเวอร์ \{#integrate-management-api-to-server-side-application} +### การผสานรวม Management API กับแอปพลิเคชันฝั่งเซิร์ฟเวอร์ \{#integrate-management-api-to-server-side-application} -ดูหัวข้อ [Management API](/integrate-logto/interact-with-management-api/) เพื่อเรียนรู้วิธีเชื่อมต่อ Management API กับแอปพลิเคชันฝั่งเซิร์ฟเวอร์ +ตรวจสอบส่วน [Management API](/integrate-logto/interact-with-management-api/) เพื่อเรียนรู้วิธีผสานรวม Management API กับแอปพลิเคชันฝั่งเซิร์ฟเวอร์ ## User Management APIs \{#user-management-apis} ### โครงสร้างข้อมูลผู้ใช้ \{#user-data-schema} -ดูหัวข้อ [ข้อมูลผู้ใช้และข้อมูลกำหนดเอง](/user-management/user-data/) เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับโครงสร้างข้อมูลผู้ใช้ใน Logto +ตรวจสอบส่วน [ข้อมูลผู้ใช้และข้อมูลที่กำหนดเอง](/user-management/user-data/) เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับโครงสร้างข้อมูลผู้ใช้ใน Logto -### Management API สำหรับโปรไฟล์และตัวระบุผู้ใช้ \{#user-profile-and-identifiers-management-apis} +### User profile และ Identifiers Management APIs \{#user-profile-and-identifiers-management-apis} -โปรไฟล์และตัวระบุของผู้ใช้เป็นสิ่งสำคัญสำหรับการจัดการผู้ใช้ คุณสามารถใช้ API ต่อไปนี้เพื่อจัดการโปรไฟล์และตัวระบุของผู้ใช้ +โปรไฟล์และตัวระบุของผู้ใช้มีความสำคัญสำหรับการจัดการผู้ใช้ คุณสามารถใช้ API ต่อไปนี้เพื่อจัดการโปรไฟล์และตัวระบุของผู้ใช้ -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้ตาม user ID | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | อัปเดตรายละเอียดผู้ใช้ | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | อัปเดตฟิลด์โปรไฟล์ผู้ใช้ตาม user ID | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | รับข้อมูลกำหนดเองของผู้ใช้ตาม user ID | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | อัปเดตข้อมูลกำหนดเองของผู้ใช้ตาม user ID | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | อัปเดตสถานะระงับบัญชีผู้ใช้ตาม user ID | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้โดย user ID | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | อัปเดตรายละเอียดผู้ใช้ | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | อัปเดตฟิลด์โปรไฟล์ผู้ใช้โดย user ID | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | รับข้อมูลที่กำหนดเองของผู้ใช้โดย user ID | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | อัปเดตข้อมูลที่กำหนดเองของผู้ใช้โดย user ID | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | อัปเดตสถานะการระงับของผู้ใช้โดย user ID | ### การยืนยันอีเมลและหมายเลขโทรศัพท์ \{#email-and-phone-number-verification} -ในระบบ Logto ทั้งอีเมลและหมายเลขโทรศัพท์สามารถใช้เป็นตัวระบุผู้ใช้ได้ ดังนั้นการยืนยันจึงเป็นสิ่งสำคัญ เพื่อรองรับสิ่งนี้ เรามี API สำหรับรหัสยืนยันเพื่อช่วยยืนยันอีเมลหรือหมายเลขโทรศัพท์ที่ให้มา +ในระบบ Logto ทั้งที่อยู่อีเมลและหมายเลขโทรศัพท์สามารถทำหน้าที่เป็นตัวระบุผู้ใช้ได้ การยืนยันจึงเป็นสิ่งสำคัญ เพื่อสนับสนุนสิ่งนี้ เรามีชุด API รหัสยืนยันเพื่อช่วยยืนยันอีเมลหรือหมายเลขโทรศัพท์ที่ให้มา :::note -โปรดตรวจสอบให้แน่ใจว่ายืนยันอีเมลหรือหมายเลขโทรศัพท์ก่อนอัปเดตโปรไฟล์ผู้ใช้ด้วยอีเมลหรือหมายเลขโทรศัพท์ใหม่ +ตรวจสอบให้แน่ใจว่าได้ยืนยันอีเมลหรือหมายเลขโทรศัพท์ก่อนที่จะอัปเดตโปรไฟล์ผู้ใช้ด้วยอีเมลหรือหมายเลขโทรศัพท์ใหม่ ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | ส่งรหัสยืนยันอีเมลหรือหมายเลขโทรศัพท์ | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | ยืนยันอีเมลหรือหมายเลขโทรศัพท์ด้วยรหัสยืนยัน | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | ส่งรหัสยืนยันอีเมลหรือหมายเลขโทรศัพท์ | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | ยืนยันอีเมลหรือหมายเลขโทรศัพท์โดยรหัสยืนยัน | ### การจัดการรหัสผ่านผู้ใช้ \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | ตรวจสอบรหัสผ่านปัจจุบันของผู้ใช้ตาม user ID | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | อัปเดตรหัสผ่านผู้ใช้ตาม user ID | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | ตรวจสอบว่าผู้ใช้มีรหัสผ่านหรือไม่ตาม user ID | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | ยืนยันรหัสผ่านปัจจุบันของผู้ใช้โดย user ID | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | อัปเดตรหัสผ่านผู้ใช้โดย user ID | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | ตรวจสอบว่าผู้ใช้มีรหัสผ่านโดย user ID หรือไม่ | :::note -โปรดตรวจสอบรหัสผ่านปัจจุบันของผู้ใช้ก่อนอัปเดตรหัสผ่านใหม่ +ตรวจสอบให้แน่ใจว่าได้ยืนยันรหัสผ่านปัจจุบันของผู้ใช้ก่อนที่จะอัปเดตรหัสผ่านของผู้ใช้ ::: -### การจัดการโซเชียลไอดีของผู้ใช้ \{#user-social-identities-management} +### การจัดการอัตลักษณ์โซเชียลของผู้ใช้ \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้ตาม user ID โซเชียลไอดีจะอยู่ในฟิลด์ `identities` | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | เชื่อมต่อโซเชียลไอดีที่ได้รับการยืนยันกับผู้ใช้ตาม user ID | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | ยกเลิกการเชื่อมต่อโซเชียลไอดีออกจากผู้ใช้ตาม user ID | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | อัปเดตโซเชียลไอดีที่เชื่อมต่อกับผู้ใช้โดยตรงตาม user ID | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | รับ authorization URI สำหรับผู้ให้บริการโซเชียลไอดี ใช้ URI นี้เพื่อเริ่มการเชื่อมต่อโซเชียลไอดีใหม่ | +| method | path | description | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้โดย user ID อัตลักษณ์โซเชียลสามารถพบได้ในฟิลด์ `identities` | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | เชื่อมโยงอัตลักษณ์โซเชียลที่ได้รับการยืนยันกับผู้ใช้โดย user ID | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | ยกเลิกการเชื่อมโยงอัตลักษณ์โซเชียลจากผู้ใช้โดย user ID | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | อัปเดตอัตลักษณ์โซเชียลที่เชื่อมโยงกับผู้ใช้โดย user ID โดยตรง | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | รับ URI การอนุญาตสำหรับผู้ให้บริการอัตลักษณ์โซเชียล ใช้ URI นี้เพื่อเริ่มการเชื่อมต่ออัตลักษณ์โซเชียลใหม่ | ```mermaid sequenceDiagram autoNumber - participant User as ผู้ใช้ - participant Client as แอปไคลเอนต์ - participant App as แอปเซิร์ฟเวอร์ + participant User as User + participant Client as Client app + participant App as server app participant Logto as Logto - participant IdP as ผู้ให้บริการโซเชียลไอดี + participant IdP as Social identity provider - User ->> Client: เข้าถึงแอปไคลเอนต์ ขอเชื่อมต่อโซเชียลไอดี - Client ->> App: ส่งคำขอเชื่อมต่อโซเชียลไอดี + User ->> Client: Access client app request to bind social identity + Client ->> App: Send request to bind social identity App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: Authorization URI - App ->> Client: ส่งคืน Authorization URI - Client ->> IdP: เปลี่ยนเส้นทางไปยังหน้าการอนุญาตของ IdP - User -->> IdP: ลงชื่อเข้าใช้ IdP - IdP ->> Client: เปลี่ยนเส้นทางกลับไปยังแอปไคลเอนต์พร้อม authorization code - Client ->> Server: คำขอเชื่อมต่อโซเชียลไอดี ส่งต่อการตอบกลับจาก IdP + App ->> Client: Return authorization URI + Client ->> IdP: Redirect to IdP authorization page + User -->> IdP: Sign in to IdP + IdP ->> Client: Redirect to client app with authorization code + Client ->> Server: Link social identity request, forward IdP authorization response Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: รับข้อมูลผู้ใช้จาก IdP โดยใช้ authorization code - IdP ->> Logto: ส่งคืนข้อมูลผู้ใช้ + Logto ->> IdP: Get user info from IdP using authorization code + IdP ->> Logto: Return user info ``` -1. ผู้ใช้เข้าถึงแอปไคลเอนต์และขอเชื่อมต่อโซเชียลไอดี -2. แอปไคลเอนต์ส่งคำขอไปยังเซิร์ฟเวอร์เพื่อเชื่อมต่อโซเชียลไอดี -3. เซิร์ฟเวอร์ส่งคำขอไปยัง Logto เพื่อขอ authorization URI สำหรับผู้ให้บริการโซเชียลไอดี คุณต้องระบุ `state` parameter และ `redirect_uri` ของคุณเองในคำขอ และต้องลงทะเบียน `redirect_uri` กับผู้ให้บริการโซเชียลไอดีล่วงหน้า -4. Logto ส่งคืน authorization URI ให้เซิร์ฟเวอร์ -5. เซิร์ฟเวอร์ส่ง authorization URI กลับไปยังแอปไคลเอนต์ -6. แอปไคลเอนต์เปลี่ยนเส้นทางผู้ใช้ไปยัง authorization URI ของ IdP +1. ผู้ใช้เข้าถึงแอปพลิเคชันไคลเอนต์และขอเชื่อมโยงอัตลักษณ์โซเชียล +2. แอปพลิเคชันไคลเอนต์ส่งคำขอไปยังเซิร์ฟเวอร์เพื่อเชื่อมโยงอัตลักษณ์โซเชียล +3. เซิร์ฟเวอร์ส่งคำขอไปยัง Logto เพื่อรับ URI การอนุญาตสำหรับผู้ให้บริการอัตลักษณ์โซเชียล คุณต้องระบุพารามิเตอร์ `state` และ `redirect_uri` ของคุณเองในคำขอ ตรวจสอบให้แน่ใจว่าได้ลงทะเบียน `redirect_uri` ในผู้ให้บริการอัตลักษณ์โซเชียล +4. Logto ส่งคืน URI การอนุญาตไปยังเซิร์ฟเวอร์ +5. เซิร์ฟเวอร์ส่งคืน URI การอนุญาตไปยังแอปพลิเคชันไคลเอนต์ +6. แอปพลิเคชันไคลเอนต์เปลี่ยนเส้นทางผู้ใช้ไปยัง URI การอนุญาตของ IdP 7. ผู้ใช้ลงชื่อเข้าใช้ IdP -8. IdP เปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปไคลเอนต์โดยใช้ `redirect_uri` พร้อม authorization code -9. แอปไคลเอนต์ตรวจสอบ `state` และส่งต่อการตอบกลับจาก IdP ไปยังเซิร์ฟเวอร์ -10. เซิร์ฟเวอร์ส่งคำขอไปยัง Logto เพื่อเชื่อมต่อโซเชียลไอดีกับผู้ใช้ -11. Logto รับข้อมูลผู้ใช้จาก IdP โดยใช้ authorization code -12. IdP ส่งข้อมูลผู้ใช้กลับไปยัง Logto และ Logto เชื่อมต่อโซเชียลไอดีกับผู้ใช้ +8. IdP เปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปพลิเคชันไคลเอนต์โดยใช้ `redirect_uri` พร้อมรหัสการอนุญาต +9. แอปพลิเคชันไคลเอนต์ตรวจสอบ `state` และส่งต่อการตอบสนองการอนุญาตของ IdP ไปยังเซิร์ฟเวอร์ +10. เซิร์ฟเวอร์ส่งคำขอไปยัง Logto เพื่อเชื่อมโยงอัตลักษณ์โซเชียลกับผู้ใช้ +11. Logto รับข้อมูลผู้ใช้จาก IdP โดยใช้รหัสการอนุญาต +12. IdP ส่งคืนข้อมูลผู้ใช้ไปยัง Logto และ Logto เชื่อมโยงอัตลักษณ์โซเชียลกับผู้ใช้ :::note -มีข้อจำกัดบางประการที่ควรพิจารณาเมื่อเชื่อมต่อโซเชียลไอดีใหม่กับผู้ใช้: +มีข้อจำกัดบางประการที่ต้องพิจารณาเมื่อเชื่อมโยงอัตลักษณ์โซเชียลใหม่กับผู้ใช้: -- Management API ไม่มี session context ใด ๆ ตัวเชื่อมต่อโซเชียลที่ต้องการ session ที่ใช้งานอยู่เพื่อรักษาสถานะการยืนยันตัวตนโซเชียลอย่างปลอดภัยจะไม่สามารถเชื่อมต่อผ่าน Management API ได้ ตัวเชื่อมต่อที่ไม่รองรับได้แก่ apple, OIDC มาตรฐาน และ OAuth 2.0 มาตรฐาน -- ด้วยเหตุผลเดียวกัน Logto ไม่สามารถตรวจสอบ `state` parameter ในการตอบกลับการอนุญาตได้ โปรดเก็บ `state` parameter ในแอปไคลเอนต์ของคุณและตรวจสอบเมื่อได้รับการตอบกลับการอนุญาต -- คุณต้องลงทะเบียน `redirect_uri` กับผู้ให้บริการโซเชียลไอดีล่วงหน้า มิฉะนั้น IdP จะไม่เปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปไคลเอนต์ของคุณ IdP ของคุณต้องรองรับ callback `redirect_uri` มากกว่าหนึ่งรายการ ได้แก่ สำหรับการลงชื่อเข้าใช้ และสำหรับหน้าผูกโปรไฟล์ของคุณเอง +- Management API ไม่มีบริบทเซสชันใด ๆ ตัวเชื่อมต่อโซเชียลใด ๆ ที่ต้องการเซสชันที่ใช้งานอยู่เพื่อรักษาสถานะการยืนยันตัวตนโซเชียลอย่างปลอดภัยไม่สามารถเชื่อมโยงผ่าน Management API ได้ ตัวเชื่อมต่อที่ไม่รองรับรวมถึง apple, OIDC มาตรฐาน และตัวเชื่อมต่อ OAuth 2.0 มาตรฐาน +- ด้วยเหตุผลเดียวกัน Logto ไม่สามารถตรวจสอบพารามิเตอร์ `state` ในการตอบสนองการอนุญาตได้ ตรวจสอบให้แน่ใจว่าได้จัดเก็บพารามิเตอร์ `state` ในแอปไคลเอนต์ของคุณและตรวจสอบเมื่อได้รับการตอบสนองการอนุญาต +- คุณต้องลงทะเบียน `redirect_uri` กับผู้ให้บริการอัตลักษณ์โซเชียลล่วงหน้า มิฉะนั้น IdP โซเชียลจะไม่เปลี่ยนเส้นทางผู้ใช้กลับไปยังแอปไคลเอนต์ของคุณ IdP โซเชียลของคุณต้องยอมรับ `redirect_uri` การเรียกกลับมากกว่าหนึ่งรายการ หนึ่งสำหรับการลงชื่อเข้าใช้ผู้ใช้ หนึ่งสำหรับหน้าการเชื่อมโยงโปรไฟล์ของคุณเอง ::: -### การจัดการไอดีองค์กรของผู้ใช้ \{#user-enterprise-identities-management} +### การจัดการอัตลักษณ์องค์กรของผู้ใช้ \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้ตาม user ID ไอดีองค์กรจะอยู่ในฟิลด์ `ssoIdentities` เพิ่ม query parameter `includeSsoIdentities=true` ใน API รายละเอียดผู้ใช้เพื่อแสดงข้อมูลนี้ | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | รับรายละเอียดผู้ใช้โดย user ID อัตลักษณ์องค์กรสามารถพบได้ในฟิลด์ `ssoIdentities` เพิ่มพารามิเตอร์การค้นหา `includeSsoIdentities=true` ใน API รายละเอียดผู้ใช้เพื่อรวมอัตลักษณ์องค์กร | -ขณะนี้ Management API ยังไม่รองรับการเชื่อมหรือยกเลิกการเชื่อมไอดีองค์กรกับผู้ใช้ คุณสามารถแสดงเฉพาะไอดีองค์กรที่เชื่อมกับผู้ใช้เท่านั้น +ปัจจุบัน Management API ไม่รองรับการเชื่อมโยงหรือยกเลิกการเชื่อมโยงอัตลักษณ์องค์กรกับผู้ใช้ คุณสามารถแสดงอัตลักษณ์องค์กรที่เชื่อมโยงกับผู้ใช้ได้เท่านั้น -### Personal access token \{#personal-access-token} +### โทเค็นการเข้าถึงส่วนบุคคล \{#personal-access-token} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | รับ personal access token ทั้งหมดของผู้ใช้ | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | เพิ่ม personal access token ใหม่ให้ผู้ใช้ | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | ลบโทเค็นของผู้ใช้ตามชื่อ | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | อัปเดตโทเค็นของผู้ใช้ตามชื่อ | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | รับโทเค็นการเข้าถึงส่วนบุคคลทั้งหมดสำหรับผู้ใช้ | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | เพิ่มโทเค็นการเข้าถึงส่วนบุคคลใหม่สำหรับผู้ใช้ | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | ลบโทเค็นสำหรับผู้ใช้โดยชื่อ | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | อัปเดตโทเค็นสำหรับผู้ใช้โดยชื่อ | -Personal access token เป็นวิธีที่ปลอดภัยสำหรับผู้ใช้ในการให้ [โทเค็นการเข้าถึง (Access token)](https://auth.wiki/access-token) โดยไม่ต้องใช้ข้อมูลรับรองหรือการลงชื่อเข้าใช้แบบโต้ตอบ ดูเพิ่มเติมเกี่ยวกับ [การใช้ personal access token](/user-management/personal-access-token) +โทเค็นการเข้าถึงส่วนบุคคลให้วิธีที่ปลอดภัยสำหรับผู้ใช้ในการให้ [โทเค็นการเข้าถึง (Access token)](https://auth.wiki/access-token) โดยไม่ต้องใช้ข้อมูลประจำตัวและการลงชื่อเข้าใช้แบบโต้ตอบ เรียนรู้เพิ่มเติมเกี่ยวกับ [การใช้โทเค็นการเข้าถึงส่วนบุคคล](/user-management/personal-access-token) ### การจัดการการตั้งค่า MFA ของผู้ใช้ \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | รับการตั้งค่า MFA ของผู้ใช้ตาม user ID | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | ตั้งค่า MFA ให้ผู้ใช้ตาม user ID | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | ลบการยืนยัน MFA ของผู้ใช้ตาม ID | +| method | path | description | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | รับการตั้งค่า MFA ของผู้ใช้โดย user ID | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | ตั้งค่าการยืนยันตัวตน MFA ของผู้ใช้โดย user ID | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | ลบการยืนยันตัวตน MFA ของผู้ใช้โดย ID | ### การลบบัญชีผู้ใช้ \{#user-account-deletion} -| method | path | description | -| ------ | -------------------------------------------------------------------------------- | ------------------------ | -| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | ลบบัญชีผู้ใช้ตาม user ID | +| method | path | description | +| ------ | -------------------------------------------------------------------------------- | ------------------- | +| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | ลบผู้ใช้โดย user ID | -### การจัดการเซสชันของผู้ใช้ \{#user-session-management} +### การจัดการเซสชันผู้ใช้ \{#user-session-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | รับเซสชันของผู้ใช้ตาม user ID | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | รับเซสชันของผู้ใช้ตาม session ID | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | ลบเซสชันของผู้ใช้ตาม session ID | +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------------- | ----------------------------- | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | รับเซสชันผู้ใช้โดย user ID | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | รับเซสชันผู้ใช้โดย session ID | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | ลบเซสชันผู้ใช้โดย session ID | + +### การจัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants) \{#manage-user-authorized-apps-grants} + +| method | path | description | +| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | แสดงรายการการอนุญาตแอปที่ใช้งานอยู่สำหรับผู้ใช้ | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | ยกเลิกการอนุญาตแอปเฉพาะโดย ID | + +พารามิเตอร์การค้นหาเพิ่มเติมสำหรับการแสดงรายการการอนุญาต: + +- `appType=firstParty`: แสดงเฉพาะการอนุญาตแอป first-party +- `appType=thirdParty`: แสดงเฉพาะการอนุญาตแอป third-party +- ละเว้น `appType`: แสดงการอนุญาตที่ใช้งานอยู่ทั้งหมด + +เมื่อการอนุญาตถูกยกเลิก โทเค็นการเข้าถึงทึบและโทเค็นรีเฟรชที่ออกก่อนหน้านี้สำหรับการอนุญาตนั้นจะถูกทำให้เป็นโมฆะ diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index ab111e412e5..e9f2f518f0a 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,235 +1,101 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- -# การออกจากระบบ (Sign-out) +# การลงชื่อออก -การออกจากระบบใน Logto (ในฐานะผู้ให้บริการข้อมูลระบุตัวตน OIDC) เกี่ยวข้องกับทั้ง: +การลงชื่อออกใน Logto ประกอบด้วยสองชั้น: -- **เซสชัน Logto ส่วนกลาง** (คุกกี้เบราว์เซอร์ภายใต้โดเมน Logto) -- **สถานะการยืนยันตัวตนฝั่งไคลเอนต์แบบกระจาย** (โทเค็นและเซสชันแอปในแต่ละแอป) +- **การลงชื่อออกจากเซสชัน Logto**: สิ้นสุดเซสชันการลงชื่อเข้าใช้แบบรวมศูนย์ภายใต้โดเมน Logto +- **การลงชื่อออกจากแอป**: ล้างสถานะเซสชันและโทเค็นในแอปพลิเคชันลูกค้าของคุณ -เพื่อให้เข้าใจพฤติกรรมการออกจากระบบ ควรแยกสองชั้นนี้ออกจากกัน แล้วดูว่า **grant** เชื่อมโยงกันอย่างไร +เพื่อให้เข้าใจวิธีการทำงานของเซสชันใน Logto ได้ดีขึ้น ดูที่ [Sessions](/sessions) -## แนวคิดหลัก \{#core-concepts} +## กลไกการลงชื่อออก \{#sign-out-mechanisms} -### เซสชัน Logto คืออะไร? \{#what-is-a-logto-session} +### 1) การลงชื่อออกเฉพาะฝั่งลูกค้า \{#1-client-side-only-sign-out} -เซสชัน Logto คือสถานะการลงชื่อเข้าใช้ส่วนกลางที่จัดการโดย Logto สร้างขึ้นหลังจากการยืนยันตัวตนสำเร็จ และแสดงด้วยคุกกี้ภายใต้โดเมน Logto +แอปพลิเคชันลูกค้าล้างเซสชันและโทเค็น (โทเค็น ID / โทเค็นการเข้าถึง / โทเค็นรีเฟรช) ของตัวเอง ซึ่งจะลงชื่อผู้ใช้ออกจากสถานะภายในแอปนั้นเท่านั้น -หากคุกกี้เซสชันยังใช้ได้ ผู้ใช้สามารถยืนยันตัวตนแบบเงียบ (SSO) ข้ามหลายแอปที่เชื่อถือ Logto tenant เดียวกันได้ +- เซสชัน Logto อาจยังคงใช้งานอยู่ +- แอปอื่น ๆ ภายใต้เซสชัน Logto เดียวกันอาจยังคง SSO ได้ -หากไม่มีเซสชันที่ถูกต้อง Logto จะแสดงหน้าลงชื่อเข้าใช้ +### 2) สิ้นสุดเซสชันที่ Logto (การลงชื่อออกแบบรวมศูนย์ใน Logto ปัจจุบัน) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -### Grant คืออะไร? \{#what-are-grants} +เพื่อเคลียร์เซสชัน Logto แบบรวมศูนย์ แอปจะเปลี่ยนเส้นทางผู้ใช้ไปยังจุดสิ้นสุดเซสชัน เช่น: -**Grant** แทนสถานะการอนุญาตสำหรับผู้ใช้ + แอปไคลเอนต์แต่ละคู่ - -- เซสชัน Logto หนึ่งอันสามารถมี grant สำหรับหลายแอปไคลเอนต์ -- Grant คือสิ่งที่โทเค็นที่ออกให้ผูกอยู่ด้วย -- ในชุดเอกสารนี้ ใช้ **grant** เป็นหน่วยการอนุญาตข้ามแอป - -### ความสัมพันธ์ระหว่างเซสชัน, grant, และสถานะการยืนยันตัวตนของไคลเอนต์ \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto domain] - S[เซสชัน Logto] - G1[Grant สำหรับ App A] - G2[Grant สำหรับ App B] - end - - subgraph AppA [Client domain A] - A[เซสชัน / โทเค็นภายในแอป] - end - - subgraph AppB [Client domain B] - B[เซสชัน / โทเค็นภายในแอป] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **เซสชัน Logto** ควบคุมประสบการณ์ SSO ส่วนกลาง -- **เซสชัน / โทเค็นภายในแอป** ควบคุมว่าผู้ใช้ยังถือว่า “ลงชื่อเข้าใช้” ในแต่ละแอปหรือไม่ -- **Grant** เชื่อมสองโลกนี้ด้วยการแทนสถานะการอนุญาตเฉพาะแอป - -## ทบทวนการลงชื่อเข้าใช้ (เหตุใดการออกจากระบบจึงมีหลายชั้น) \{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as แอปไคลเอนต์ - end - - box Logto (IdP) - participant OIDC as ผู้ให้บริการ OIDC - participant SignIn as หน้าลงชื่อเข้าใช้ - end - - User ->> Client: เข้าใช้งานแอป - Client ->> OIDC: เปลี่ยนเส้นทางเพื่อยืนยันตัวตน - OIDC -->> OIDC: ตรวจสอบเซสชัน Logto - OIDC ->> SignIn: ขอให้ลงชื่อเข้าใช้หากจำเป็น - SignIn ->> OIDC: ผู้ใช้ยืนยันตัวตน - OIDC -->> OIDC: สร้างเซสชันและ grant - OIDC ->> Client: ส่งรหัสการอนุญาตกลับ - Client ->> OIDC: แลกรหัสเป็นโทเค็น - OIDC -->> Client: ส่งโทเค็นกลับ -``` - -## โทโพโลยีเซสชันข้ามแอป / อุปกรณ์ \{#session-topology-across-apps-devices} - -### คุกกี้เซสชันร่วม (เบราว์เซอร์ / user agent เดียวกัน) \{#shared-session-cookie-same-browser-user-agent} - -หากผู้ใช้ลงชื่อเข้าใช้หลายแอปจากเบราว์เซอร์เดียวกัน แอปเหล่านั้นสามารถใช้คุกกี้เซสชัน Logto เดียวกันและใช้ SSO ได้ - -```mermaid -flowchart TD - U[ผู้ใช้] - A["แอปไคลเอนต์ A (Client domain A)"] - B["แอปไคลเอนต์ B (Client domain B)"] - C{"มีเซสชัน Logto หรือไม่? (Logto domain)"} - D["หน้าลงชื่อเข้าใช้ (Logto domain)"] - - subgraph UA["User agent A (เบราว์เซอร์เดียวกัน)"] - U - A - B - C - D - end - - U -->|ลงชื่อเข้าใช้| A - A -->|เปลี่ยนเส้นทางไป Logto| C - U -->|เปิดแอป| B - B -->|เปลี่ยนเส้นทางไป Logto| C - C -->|ไม่มี| D - D -->|สร้างเซสชัน| C -``` - -### คุกกี้เซสชันแยก (อุปกรณ์ / เบราว์เซอร์ต่างกัน) \{#isolated-session-cookies-different-devices-browsers} - -เบราว์เซอร์ / อุปกรณ์ต่างกันจะถือคุกกี้ Logto คนละชุด ทำให้สถานะเซสชันแยกจากกัน - -```mermaid -flowchart TD - U[ผู้ใช้] - A["แอปไคลเอนต์ A (Client domain A)"] - C{"มีเซสชัน Logto หรือไม่? (Device A, Logto domain)"} - D["หน้าลงชื่อเข้าใช้ (Device A, Logto domain)"] - - subgraph DeviceA["User agent A"] - A - C - D - end - - B["แอปไคลเอนต์ B (Client domain B)"] - E{"มีเซสชัน Logto หรือไม่? (Device B, Logto domain)"} - F["หน้าลงชื่อเข้าใช้ (Device B, Logto domain)"] - - subgraph DeviceB["User agent B"] - B - E - F - end - - U -->|ลงชื่อเข้าใช้| A - A -->|เปลี่ยนเส้นทางไป Logto| C - U -->|ลงชื่อเข้าใช้| B - B -->|เปลี่ยนเส้นทางไป Logto| E - C -->|ไม่มี| D - E -->|ไม่มี| F - D -->|สร้างเซสชัน| C - F -->|สร้างเซสชัน| E -``` - -## กลไกการออกจากระบบ \{#sign-out-mechanisms} - -### 1) ออกจากระบบเฉพาะฝั่งไคลเอนต์ \{#1-client-side-only-sign-out} - -แอปไคลเอนต์ล้างเซสชันและโทเค็นภายในแอปของตนเอง (โทเค็น ID / การเข้าถึง / รีเฟรช) ผู้ใช้จะออกจากสถานะในแอปนั้นเท่านั้น - -- เซสชัน Logto อาจยังคงอยู่ -- แอปอื่นที่อยู่ภายใต้เซสชัน Logto เดียวกันยังคงใช้ SSO ได้ +`https://{your-logto-domain}/oidc/session/end` -### 2) End-session ที่ Logto (ออกจากระบบทั่วทั้งระบบใน Logto เวอร์ชันปัจจุบัน) \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +ในพฤติกรรม SDK ของ Logto ปัจจุบัน: -เพื่อล้างเซสชัน Logto ส่วนกลาง แอปจะเปลี่ยนเส้นทางผู้ใช้ไปยัง endpoint end session เช่น +1. `signOut()` เปลี่ยนเส้นทางไปที่ `/session/end` +2. จากนั้นไปที่ `/session/end/confirm` +3. ฟอร์มยืนยันเริ่มต้นจะโพสต์ `logout=true` โดยอัตโนมัติ -`https://{your-logto-domain}/oidc/session/end` +ผลลัพธ์คือการลงชื่อออกใน SDK ปัจจุบันถือเป็น **การลงชื่อออกแบบรวมศูนย์** -ในพฤติกรรม SDK Logto ปัจจุบัน: +:::note -1. `signOut()` เปลี่ยนเส้นทางไป `/session/end` -2. จากนั้นไปที่ `/session/end/confirm` -3. ฟอร์มยืนยันเริ่มต้นจะส่ง `logout=true` อัตโนมัติ +- **การลงชื่อออกแบบรวมศูนย์**: ยกเลิกเซสชัน Logto แบบรวมศูนย์ -ดังนั้น การออกจากระบบผ่าน SDK ปัจจุบันจะถือเป็น **การออกจากระบบทั่วทั้งระบบ** +::: -### เกิดอะไรขึ้นระหว่างการออกจากระบบทั่วทั้งระบบ \{#what-happens-during-global-sign-out} +### เกิดอะไรขึ้นระหว่างการลงชื่อออกแบบรวมศูนย์ \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["แอปเริ่มออกจากระบบ"] --> B["/session/end"] + A["ลูกค้าเริ่มการลงชื่อออก"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["เพิกถอนเซสชัน Logto ส่วนกลาง"] - D --> E{"ตรวจสอบ grant ต่อแอป"} - E -->|"ไม่ได้รับ offline_access"| F["เพิกถอน grant"] - E -->|"ได้รับ offline_access"| G["คง grant ไว้จนกว่า grant TTL จะหมดอายุ"] + C --> D["ยกเลิกเซสชัน Logto แบบรวมศูนย์"] + D --> E{"ตรวจสอบการให้สิทธิ์ต่อแอป"} + E -->|"offline_access ไม่ได้รับการให้สิทธิ์"| F["ยกเลิกการให้สิทธิ์"] + E -->|"offline_access ได้รับการให้สิทธิ์"| G["เก็บการให้สิทธิ์จนกว่าจะหมดอายุ"] ``` -ระหว่างการออกจากระบบทั่วทั้งระบบ: +ระหว่างการลงชื่อออกแบบรวมศูนย์: -- เซสชัน Logto ส่วนกลางจะถูกเพิกถอน -- grant ที่เกี่ยวข้องจะถูกจัดการตามสถานะการอนุญาตของแต่ละแอป: - - หาก **ไม่ได้** รับ `offline_access` grant ที่เกี่ยวข้องจะถูกเพิกถอน - - หาก **ได้รับ** `offline_access` grant จะไม่ถูกเพิกถอนโดย end-session -- ในกรณี `offline_access` โทเค็นรีเฟรชและ grant จะยังคงใช้ได้จนกว่า grant จะหมดอายุ +- เซสชัน Logto แบบรวมศูนย์ถูกยกเลิก +- การให้สิทธิ์แอปที่เกี่ยวข้องจะถูกจัดการตามสถานะการอนุญาตของแอป: + - หาก `offline_access` **ไม่ได้** รับการให้สิทธิ์ การให้สิทธิ์ที่เกี่ยวข้องจะถูกยกเลิก + - หาก `offline_access` **ได้รับ** การให้สิทธิ์ การให้สิทธิ์จะไม่ถูกยกเลิกโดยการสิ้นสุดเซสชัน +- สำหรับกรณี `offline_access` โทเค็นรีเฟรชและการให้สิทธิ์ยังคงใช้ได้จนกว่าจะหมดอายุ -## อายุของ grant และผลกระทบของ `offline_access` \{#grant-lifetime-and-offline-access-impact} +## อายุการให้สิทธิ์และผลกระทบของ `offline_access` \{#grant-lifetime-and-offline-access-impact} -- ค่าเริ่มต้น TTL ของ grant ใน Logto คือ **180 วัน** -- หากได้รับ `offline_access` end-session จะไม่เพิกถอน grant ของแอปนั้นโดยปริยาย -- สายโทเค็นรีเฟรชที่ผูกกับ grant นั้นจะใช้ได้จนกว่า grant จะหมดอายุ (หรือถูกเพิกถอนโดยตรง) +- ค่าเริ่มต้นของอายุการให้สิทธิ์ Logto คือ **180 วัน** +- หาก `offline_access` ได้รับการให้สิทธิ์ การสิ้นสุดเซสชันจะไม่ยกเลิกการให้สิทธิ์แอปนั้นโดยค่าเริ่มต้น +- โซ่โทเค็นรีเฟรชที่เกี่ยวข้องกับการให้สิทธิ์นั้นสามารถดำเนินต่อไปได้จนกว่าการให้สิทธิ์จะหมดอายุ (หรือถูกยกเลิกโดยเฉพาะ) -## การออกจากระบบแบบ federated: back-channel logout \{#federated-sign-out-back-channel-logout} +## การลงชื่อออกแบบรวมศูนย์: การออกจากระบบผ่านช่องทางหลัง \{#federated-sign-out-back-channel-logout} -เพื่อความสอดคล้องข้ามแอป Logto รองรับ [back-channel logout](https://openid.net/specs/openid-connect-backchannel-1_0-final.html) +เพื่อความสอดคล้องระหว่างแอป Logto รองรับ [การออกจากระบบผ่านช่องทางหลัง](https://openid.net/specs/openid-connect-backchannel-1_0-final.html) -เมื่อผู้ใช้ออกจากระบบจากแอปหนึ่ง Logto สามารถแจ้งทุกแอปที่อยู่ในเซสชันเดียวกันโดยส่ง logout token ไปยัง back-channel logout URI ที่ลงทะเบียนไว้ของแต่ละแอป +เมื่อผู้ใช้ลงชื่อออกจากแอปหนึ่ง Logto สามารถแจ้งเตือนแอปทั้งหมดที่เข้าร่วมในเซสชันเดียวกันโดยส่งโทเค็นออกจากระบบไปยัง URI การออกจากระบบผ่านช่องทางหลังที่ลงทะเบียนไว้ของแต่ละแอป -หากเปิดใช้งาน `Is session required` ในการตั้งค่า back-channel ของแอป logout token จะมี `sid` เพื่อระบุเซสชัน Logto +หาก `Is session required` เปิดใช้งานในการตั้งค่าช่องทางหลังของแอป โทเค็นออกจากระบบจะรวม `sid` เพื่อระบุเซสชัน Logto -ลำดับทั่วไป: +กระบวนการทั่วไป: -1. ผู้ใช้เริ่มออกจากระบบจากแอปหนึ่ง -2. Logto ประมวลผล end-session และส่ง logout token ไปยัง back-channel logout URI ที่ลงทะเบียนไว้ -3. แต่ละแอปตรวจสอบ logout token และล้างเซสชัน / โทเค็นภายในแอปของตนเอง +1. ผู้ใช้เริ่มการลงชื่อออกจากแอปหนึ่ง +2. Logto ประมวลผลการสิ้นสุดเซสชันและส่งโทเค็นออกจากระบบไปยัง URI การออกจากระบบผ่านช่องทางหลังที่ลงทะเบียนไว้ +3. แต่ละแอปตรวจสอบโทเค็นออกจากระบบและล้างเซสชัน / โทเค็นภายในของตัวเอง -## วิธีการออกจากระบบใน Logto SDKs \{#sign-out-methods-in-logto-sdks} +## วิธีการลงชื่อออกใน Logto SDKs \{#sign-out-methods-in-logto-sdks} -- **SPA และเว็บ**: `client.signOut()` ล้างโทเค็นใน local storage และเปลี่ยนเส้นทางไปยัง Logto end-session endpoint คุณสามารถระบุ post-logout redirect URI ได้ -- **Native (รวม React Native / Flutter)**: โดยปกติจะล้างโทเค็นใน local storage เท่านั้น webview แบบไม่มีเซสชันหมายถึงไม่มีคุกกี้ Logto ในเบราว์เซอร์ให้ล้าง +- **SPA และเว็บ**: `client.signOut()` ล้างการเก็บโทเค็นภายในและเปลี่ยนเส้นทางไปยังจุดสิ้นสุดเซสชัน Logto คุณสามารถระบุ URI เปลี่ยนเส้นทางหลังการออกจากระบบได้ +- **เนทีฟ (รวมถึง React Native / Flutter)**: มักจะล้างการเก็บโทเค็นภายในเท่านั้น เว็บวิวที่ไม่มีเซสชันหมายถึงไม่มีคุกกี้เบราว์เซอร์ Logto ที่คงอยู่ให้ล้าง :::note -สำหรับแอป native ที่ไม่รองรับ webview แบบไม่มีเซสชัน หรือไม่รู้จักการตั้งค่า `emphasized` (แอป Android ที่ใช้ **React Native** หรือ **Flutter** SDK) คุณสามารถบังคับให้ผู้ใช้ต้องลงชื่อเข้าใช้อีกครั้งโดยส่งพารามิเตอร์ `prompt=login` ในคำขอการยืนยันตัวตน +สำหรับแอปพลิเคชันเนทีฟที่ไม่รองรับเว็บวิวที่ไม่มีเซสชันหรือไม่รู้จักการตั้งค่าที่ `emphasized` (แอป Android ที่ใช้ **React Native** หรือ **Flutter** SDK) คุณสามารถบังคับให้ผู้ใช้ลงชื่อเข้าใช้อีกครั้งโดยส่งพารามิเตอร์ `prompt=login` ในคำขอการอนุญาต ::: -## บังคับให้ยืนยันตัวตนใหม่ทุกครั้งที่เข้าใช้งาน \{#enforce-re-authentication-on-every-access} +## บังคับการยืนยันตัวตนใหม่ทุกครั้งที่เข้าถึง \{#enforce-re-authentication-on-every-access} -สำหรับการดำเนินการที่ต้องการความปลอดภัยสูง ให้ใส่ `prompt=login` ในคำขอการยืนยันตัวตนเพื่อข้าม SSO และบังคับให้กรอกข้อมูลรับรองทุกครั้ง +สำหรับการดำเนินการที่มีความปลอดภัยสูง ให้รวม `prompt=login` ในคำขอการยืนยันตัวตนเพื่อข้าม SSO และบังคับให้ป้อนข้อมูลรับรองทุกครั้ง -หากขอ `offline_access` (เพื่อรับโทเค็นรีเฟรช) ให้ใส่ `consent` ด้วย เช่น `prompt=login consent` +หากขอ `offline_access` (เพื่อรับโทเค็นรีเฟรช) ให้รวม `consent`, `prompt=login consent` -การตั้งค่ารวมที่พบบ่อย: +การตั้งค่ารวมทั่วไป: ```txt prompt=login consent @@ -240,17 +106,17 @@ prompt=login consent
-### ฉันไม่ได้รับการแจ้งเตือน back-channel logout \{#im-not-receiving-the-back-channel-logout-notifications} +### ฉันไม่ได้รับการแจ้งเตือนการออกจากระบบผ่านช่องทางหลัง \{#im-not-receiving-the-back-channel-logout-notifications} -- ตรวจสอบว่าได้ลงทะเบียน back-channel logout URI ใน Logto dashboard อย่างถูกต้อง -- ตรวจสอบว่าแอปของคุณมีสถานะลงชื่อเข้าใช้ที่ใช้งานอยู่สำหรับผู้ใช้ / เซสชันเดียวกัน +- ตรวจสอบให้แน่ใจว่า URI การออกจากระบบผ่านช่องทางหลังลงทะเบียนถูกต้องในแดชบอร์ด Logto +- ตรวจสอบให้แน่ใจว่าแอปของคุณมีสถานะการลงชื่อเข้าใช้ที่ใช้งานอยู่สำหรับบริบทผู้ใช้ / เซสชันเดียวกัน
## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} - ทำความเข้าใจ OIDC back-channel logout + ทำความเข้าใจการออกจากระบบผ่านช่องทางหลังของ OIDC diff --git a/i18n/th/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/th/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index fce22b6b0cf..62cc2e64472 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: อ้างอิงพารามิเตอร์สำคัญของแอปพลิเคชันสำหรับการผสานรวมการยืนยันตัวตน OIDC รวมถึง redirect URIs, endpoints, โทเค็นรีเฟรช (refresh tokens), การออกจากระบบแบบ backchannel ฯลฯ +description: อ้างอิงถึงพารามิเตอร์แอปพลิเคชันหลักสำหรับการรวมการยืนยันตัวตน OIDC รวมถึง redirect URIs, endpoints, โทเค็นรีเฟรช, การออกจากระบบ backchannel เป็นต้น sidebar_position: 6 --- @@ -7,107 +7,106 @@ sidebar_position: 6 ## บทนำ \{#introduction} -ใน Logto _แอปพลิเคชัน_ หมายถึงโปรแกรมซอฟต์แวร์หรือบริการเฉพาะที่ลงทะเบียนกับแพลตฟอร์ม Logto และได้รับการอนุญาต (Authorization) ให้เข้าถึงข้อมูลผู้ใช้หรือดำเนินการในนามของผู้ใช้ แอปพลิเคชันถูกใช้เพื่อระบุแหล่งที่มาของคำขอที่ส่งไปยัง Logto API รวมถึงจัดการกระบวนการการยืนยันตัวตน (Authentication) และการอนุญาต (Authorization) สำหรับผู้ใช้ที่เข้าถึงแอปเหล่านั้น +ใน Logto, _แอปพลิเคชัน_ หมายถึงโปรแกรมซอฟต์แวร์หรือบริการเฉพาะที่ลงทะเบียนกับแพลตฟอร์ม Logto และได้รับการอนุญาตให้เข้าถึงข้อมูลผู้ใช้หรือดำเนินการในนามของผู้ใช้ แอปพลิเคชันถูกใช้เพื่อระบุแหล่งที่มาของคำขอที่ส่งไปยัง Logto API รวมถึงจัดการกระบวนการการยืนยันตัวตน (Authentication) และการอนุญาต (Authorization) สำหรับผู้ใช้ที่เข้าถึงแอปพลิเคชันเหล่านั้น -การใช้แอปพลิเคชันในประสบการณ์การลงชื่อเข้าใช้ของ Logto ช่วยให้ผู้ใช้สามารถเข้าถึงและจัดการแอปที่ได้รับอนุญาตได้อย่างง่ายดายจากที่เดียว ด้วยกระบวนการยืนยันตัวตนที่สม่ำเสมอและปลอดภัย สิ่งนี้ช่วยให้ประสบการณ์ผู้ใช้ราบรื่นและมั่นใจได้ว่ามีเพียงผู้ที่ได้รับอนุญาตเท่านั้นที่เข้าถึงข้อมูลสำคัญหรือดำเนินการในนามขององค์กร +การใช้แอปพลิเคชันในประสบการณ์การลงชื่อเข้าใช้ของ Logto ช่วยให้ผู้ใช้สามารถเข้าถึงและจัดการแอปพลิเคชันที่ได้รับอนุญาตได้จากที่เดียว ด้วยกระบวนการยืนยันตัวตนที่สม่ำเสมอและปลอดภัย สิ่งนี้ช่วยให้ประสบการณ์ของผู้ใช้ราบรื่นและมั่นใจได้ว่ามีเพียงบุคคลที่ได้รับอนุญาตเท่านั้นที่สามารถเข้าถึงข้อมูลที่ละเอียดอ่อนหรือดำเนินการในนามขององค์กร -แอปพลิเคชันยังถูกใช้ในบันทึกการตรวจสอบ (audit logs) ของ Logto เพื่อติดตามกิจกรรมของผู้ใช้และระบุภัยคุกคามหรือการละเมิดความปลอดภัยที่อาจเกิดขึ้น โดยการเชื่อมโยงการกระทำเฉพาะกับแอปพลิเคชัน Logto สามารถให้ข้อมูลเชิงลึกอย่างละเอียดเกี่ยวกับวิธีการเข้าถึงและใช้ข้อมูล ช่วยให้องค์กรจัดการข้อกำหนดด้านความปลอดภัยและการปฏิบัติตามข้อกำหนดได้ดียิ่งขึ้น -หากคุณต้องการผสานรวมแอปของคุณกับ Logto ดูที่ [Integrate Logto](/integrate-logto) +แอปพลิเคชันยังถูกใช้ในบันทึกการตรวจสอบของ Logto เพื่อติดตามกิจกรรมของผู้ใช้และระบุภัยคุกคามหรือการละเมิดความปลอดภัยที่อาจเกิดขึ้น โดยการเชื่อมโยงการกระทำเฉพาะกับแอปพลิเคชันเฉพาะ Logto สามารถให้ข้อมูลเชิงลึกที่ละเอียดเกี่ยวกับวิธีการเข้าถึงและใช้ข้อมูล ช่วยให้องค์กรจัดการความต้องการด้านความปลอดภัยและการปฏิบัติตามข้อกำหนดได้ดียิ่งขึ้น หากคุณต้องการรวมแอปพลิเคชันของคุณกับ Logto ดูที่ [Integrate Logto](/integrate-logto) ## คุณสมบัติ \{#properties} ### Application ID \{#application-id} -_Application ID_ คือคีย์ที่สร้างขึ้นโดยอัตโนมัติและไม่ซ้ำกันเพื่อระบุแอปของคุณใน Logto และถูกอ้างถึงว่าเป็น [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) ใน OAuth 2.0 +_Application ID_ เป็นคีย์ที่สร้างขึ้นโดยอัตโนมัติเพื่อระบุแอปพลิเคชันของคุณใน Logto และถูกอ้างอิงว่าเป็น [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/) ใน OAuth 2.0 ### ประเภทของแอปพลิเคชัน \{#application-types} -_แอปพลิเคชัน_ สามารถเป็นหนึ่งในประเภทต่อไปนี้: +_แอปพลิเคชัน_ สามารถเป็นหนึ่งในประเภทแอปพลิเคชันต่อไปนี้: -- **Native app** คือแอปที่ทำงานในสภาพแวดล้อมเนทีฟ เช่น iOS app, Android app - - **Device flow app** คือ native app ประเภทพิเศษสำหรับอุปกรณ์ที่จำกัดการป้อนข้อมูลหรือแอปแบบไม่มีหัว (headless) (เช่น สมาร์ททีวี, เกมคอนโซล, CLI tools, อุปกรณ์ IoT) โดยใช้ [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) แทน flow แบบ redirect มาตรฐาน ดู [Device flow quick start](/quick-starts/device-flow) สำหรับรายละเอียด -- **Single page app** คือแอปที่ทำงานในเว็บเบราว์เซอร์ ซึ่งอัปเดตหน้าเว็บด้วยข้อมูลใหม่จากเซิร์ฟเวอร์โดยไม่ต้องโหลดหน้าใหม่ทั้งหมด เช่น React DOM app, Vue app -- **Traditional web app** คือแอปที่เรนเดอร์และอัปเดตหน้าโดยเว็บเซิร์ฟเวอร์เท่านั้น เช่น JSP, PHP -- **Machine-to-machine (M2M) app** คือแอปที่ทำงานในสภาพแวดล้อมของเครื่องเพื่อสื่อสารระหว่างบริการโดยตรงโดยไม่ต้องมีการโต้ตอบกับผู้ใช้ +- **แอปเนทีฟ** เป็นแอปที่ทำงานในสภาพแวดล้อมเนทีฟ เช่น แอป iOS, แอป Android + - **แอป Device flow** เป็นประเภทพิเศษของแอปเนทีฟสำหรับอุปกรณ์ที่มีข้อจำกัดในการป้อนข้อมูลหรือแอปพลิเคชันที่ไม่มีหัว (เช่น สมาร์ททีวี, คอนโซลเกม, เครื่องมือ CLI, อุปกรณ์ IoT) ใช้ [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) แทนการไหลแบบ redirect มาตรฐาน ดู [Device flow quick start](/quick-starts/device-flow) สำหรับรายละเอียด +- **แอปหน้าเดียว** เป็นแอปที่ทำงานในเว็บเบราว์เซอร์ ซึ่งอัปเดตหน้าเว็บด้วยข้อมูลใหม่จากเซิร์ฟเวอร์โดยไม่ต้องโหลดหน้าใหม่ทั้งหมด เช่น แอป React DOM, แอป Vue +- **แอปเว็บแบบดั้งเดิม** เป็นแอปที่เรนเดอร์และอัปเดตหน้าเว็บโดยเซิร์ฟเวอร์เว็บเพียงอย่างเดียว เช่น JSP, PHP +- **แอปเครื่องต่อเครื่อง (M2M)** เป็นแอปพลิเคชันที่ทำงานในสภาพแวดล้อมเครื่องสำหรับการสื่อสารบริการต่อบริการโดยตรงโดยไม่มีการโต้ตอบของผู้ใช้ ### Application secret \{#application-secret} -_Application secret_ คือคีย์ที่ใช้ในการยืนยันตัวตนของแอปในระบบการยืนยันตัวตน โดยเฉพาะสำหรับ private clients (Traditional Web และ M2M apps) เพื่อเป็นเกราะป้องกันความปลอดภัย +_Application secret_ เป็นคีย์ที่ใช้ในการยืนยันตัวตนของแอปพลิเคชันในระบบการยืนยันตัวตน โดยเฉพาะสำหรับไคลเอนต์ส่วนตัว (แอปเว็บแบบดั้งเดิมและแอป M2M) เป็นอุปสรรคความปลอดภัยส่วนตัว :::tip -Single Page Apps (SPAs) และ Native apps จะไม่มี App secret เนื่องจาก SPAs และ Native apps เป็น "public clients" และไม่สามารถเก็บความลับได้ (โค้ดเบราว์เซอร์หรือ app bundle สามารถถูกตรวจสอบได้) แทนที่จะใช้ app secret, Logto จะปกป้องด้วย PKCE, การตรวจสอบ redirect URI/CORS อย่างเข้มงวด, access token อายุสั้น และการหมุนเวียน refresh-token +แอปหน้าเดียว (SPAs) และแอปเนทีฟไม่มีการให้ App secret SPAs และแอปเนทีฟเป็น "ไคลเอนต์สาธารณะ" และไม่สามารถเก็บความลับได้ (โค้ดเบราว์เซอร์หรือบันเดิลแอปสามารถตรวจสอบได้) แทนที่จะใช้ app secret, Logto ปกป้องพวกเขาด้วย PKCE, การตรวจสอบ redirect URI / CORS ที่เข้มงวด, โทเค็นการเข้าถึงที่มีอายุสั้น และการหมุนเวียนโทเค็นรีเฟรช ::: -### Application name \{#application-name} +### ชื่อแอปพลิเคชัน \{#application-name} -_Application name_ คือชื่อที่มนุษย์อ่านเข้าใจได้ของแอปพลิเคชันและจะแสดงใน admin console +_ชื่อแอปพลิเคชัน_ เป็นชื่อที่มนุษย์อ่านได้ของแอปพลิเคชันและจะแสดงในคอนโซลผู้ดูแลระบบ -_Application name_ เป็นองค์ประกอบสำคัญในการจัดการแอปใน Logto เพราะช่วยให้ผู้ดูแลระบบสามารถระบุและติดตามกิจกรรมของแต่ละแอปในแพลตฟอร์มได้อย่างง่ายดาย +_ชื่อแอปพลิเคชัน_ เป็นองค์ประกอบสำคัญในการจัดการแอปพลิเคชันใน Logto เนื่องจากช่วยให้ผู้ดูแลระบบสามารถระบุและติดตามกิจกรรมของแอปพลิเคชันแต่ละตัวในแพลตฟอร์มได้อย่างง่ายดาย :::note -ควรเลือก _Application name_ อย่างระมัดระวัง เพราะจะแสดงให้ผู้ใช้ทุกคนที่เข้าถึง admin console เห็น ควรสะท้อนวัตถุประสงค์และฟังก์ชันของแอปอย่างถูกต้อง และเข้าใจง่าย +สิ่งสำคัญคือต้องเลือก _ชื่อแอปพลิเคชัน_ อย่างระมัดระวัง เนื่องจากจะมองเห็นได้สำหรับผู้ใช้ทุกคนที่มีสิทธิ์เข้าถึงคอนโซลผู้ดูแลระบบ ควรสะท้อนถึงวัตถุประสงค์และฟังก์ชันของแอปพลิเคชันอย่างถูกต้อง ในขณะเดียวกันก็ง่ายต่อการเข้าใจและจดจำ ::: ### คำอธิบาย \{#description} -คำอธิบายสั้น ๆ ของแอปพลิเคชันจะแสดงในหน้ารายละเอียดแอปของ admin console คำอธิบายนี้มีไว้เพื่อให้ข้อมูลเพิ่มเติมแก่ผู้ดูแลระบบ เช่น วัตถุประสงค์ ฟังก์ชัน และรายละเอียดอื่น ๆ ที่เกี่ยวข้อง +คำอธิบายสั้น ๆ ของแอปพลิเคชันจะแสดงในหน้ารายละเอียดแอปพลิเคชันของคอนโซลผู้ดูแลระบบ คำอธิบายมีวัตถุประสงค์เพื่อให้ข้อมูลเพิ่มเติมเกี่ยวกับแอปพลิเคชันแก่ผู้ดูแลระบบ เช่น วัตถุประสงค์, ฟังก์ชันการทำงาน และรายละเอียดที่เกี่ยวข้องอื่น ๆ ### Redirect URIs \{#redirect-uris} -_Redirect URIs_ คือรายการของ redirect URI ที่ถูกต้องซึ่งถูกกำหนดไว้ล่วงหน้าสำหรับแอปพลิเคชัน เมื่อผู้ใช้ลงชื่อเข้าใช้ Logto และพยายามเข้าถึงแอปพลิเคชัน พวกเขาจะถูกเปลี่ยนเส้นทางไปยังหนึ่งใน URI ที่อนุญาตตามที่ระบุไว้ในการตั้งค่าแอป +_Redirect URIs_ เป็นรายการของ URIs ที่ถูกต้องที่ได้ถูกกำหนดล่วงหน้าสำหรับแอปพลิเคชัน เมื่อผู้ใช้ลงชื่อเข้าใช้ Logto และพยายามเข้าถึงแอปพลิเคชัน พวกเขาจะถูกเปลี่ยนเส้นทางไปยังหนึ่งใน URIs ที่อนุญาตที่ระบุในการตั้งค่าแอปพลิเคชัน -รายการ URI ที่อนุญาตนี้ใช้สำหรับตรวจสอบ redirect URI ที่รวมอยู่ในคำขอการอนุญาตที่แอปส่งไปยัง Logto ระหว่างกระบวนการยืนยันตัวตน หาก redirect URI ที่ระบุในคำขอการอนุญาตตรงกับ URI ที่อนุญาตในแอป ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยัง URI นั้นหลังจากยืนยันตัวตนสำเร็จ หาก redirect URI ไม่อยู่ในรายการที่อนุญาต ผู้ใช้จะไม่ถูกเปลี่ยนเส้นทางและกระบวนการยืนยันตัวตนจะล้มเหลว +รายการ URIs ที่อนุญาตถูกใช้เพื่อตรวจสอบความถูกต้องของ redirect URI ที่รวมอยู่ในคำขอการอนุญาตที่ส่งโดยแอปพลิเคชันไปยัง Logto ระหว่างกระบวนการยืนยันตัวตน หาก redirect URI ที่ระบุในคำขอการอนุญาตตรงกับหนึ่งใน URIs ที่อนุญาตในการตั้งค่าแอปพลิเคชัน ผู้ใช้จะถูกเปลี่ยนเส้นทางไปยัง URI นั้นหลังจากการยืนยันตัวตนสำเร็จ หาก redirect URI ไม่อยู่ในรายการที่อนุญาต ผู้ใช้จะไม่ถูกเปลี่ยนเส้นทางและกระบวนการยืนยันตัวตนจะล้มเหลว :::note -ควรตรวจสอบให้แน่ใจว่าได้เพิ่ม redirect URI ที่ถูกต้องทั้งหมดลงในรายการที่อนุญาตของแอปใน Logto เพื่อให้ผู้ใช้สามารถเข้าถึงแอปได้สำเร็จหลังจากยืนยันตัวตน +สิ่งสำคัญคือต้องแน่ใจว่า URIs ที่ถูกต้องทั้งหมดถูกเพิ่มไปยังรายการที่อนุญาตสำหรับแอปพลิเคชันใน Logto เพื่อให้แน่ใจว่าผู้ใช้สามารถเข้าถึงแอปพลิเคชันได้สำเร็จหลังจากการยืนยันตัวตน ::: -คุณสามารถดูข้อมูลเพิ่มเติมได้ที่ [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) +คุณสามารถดู [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) สำหรับข้อมูลเพิ่มเติม ทำความเข้าใจ Redirect URIs ใน OIDC ด้วย Authorization Code Flow -#### รูปแบบ Wildcard \{#wildcard-patterns} +#### รูปแบบไวด์การ์ด \{#wildcard-patterns} -_ใช้ได้กับ: Single page app, Traditional web app_ +_ความพร้อมใช้งาน: แอปหน้าเดียว, แอปเว็บแบบดั้งเดิม_ -Redirect URIs รองรับรูปแบบ wildcard (`*`) สำหรับสภาพแวดล้อมแบบไดนามิก เช่น การ deploy แบบ preview สามารถใช้ wildcard ในส่วน hostname และ pathname ของ HTTP/HTTPS URI ได้ +Redirect URIs รองรับรูปแบบไวด์การ์ด (`*`) สำหรับสภาพแวดล้อมแบบไดนามิก เช่น การปรับใช้ตัวอย่างล่วงหน้า ไวด์การ์ดสามารถใช้ในส่วนประกอบ hostname และ pathname ของ HTTP / HTTPS URIs **กฎ:** -- อนุญาตให้ใช้ wildcard เฉพาะใน hostname และ pathname เท่านั้น -- ไม่อนุญาตให้ใช้ wildcard ใน scheme, port, query parameters หรือ hash fragments -- wildcard ใน hostname ต้องมีจุดอย่างน้อยหนึ่งจุด (เช่น `https://*.example.com/callback`) +- ไวด์การ์ดได้รับอนุญาตเฉพาะใน hostname และ pathname +- ไวด์การ์ดไม่ได้รับอนุญาตใน scheme, port, query parameters หรือ hash fragments +- ไวด์การ์ด hostname ต้องมีอย่างน้อยหนึ่งจุด (เช่น `https://*.example.com/callback`) **ตัวอย่าง:** -- `https://*.example.com/callback` - ตรงกับทุก subdomain -- `https://preview-*.example.com/callback` - ตรงกับการ deploy แบบ preview -- `https://example.com/*/callback` - ตรงกับทุก path segment +- `https://*.example.com/callback` - ตรงกับทุกซับโดเมน +- `https://preview-*.example.com/callback` - ตรงกับการปรับใช้ตัวอย่างล่วงหน้า +- `https://example.com/*/callback` - ตรงกับทุกส่วนของเส้นทาง :::caution -Wildcard redirect URIs ไม่ใช่มาตรฐาน OIDC และอาจเพิ่มความเสี่ยงด้านความปลอดภัย ควรใช้ด้วยความระมัดระวังและควรใช้ redirect URI ที่ตรงเป๊ะเมื่อเป็นไปได้ +Redirect URIs ที่ใช้ไวด์การ์ดไม่ใช่มาตรฐาน OIDC และสามารถเพิ่มพื้นผิวการโจมตีได้ ใช้อย่างระมัดระวังและควรใช้ Redirect URIs ที่แน่นอนเมื่อเป็นไปได้ ::: ### Post sign-out redirect URIs \{#post-sign-out-redirect-uris} -_Post sign-out redirect URIs_ คือรายการ URI ที่ถูกต้องซึ่งถูกกำหนดไว้ล่วงหน้าสำหรับแอปพลิเคชันเพื่อเปลี่ยนเส้นทางผู้ใช้หลังจากออกจากระบบ Logto +_Post sign-out redirect URIs_ เป็นรายการของ URIs ที่ถูกต้องที่ได้ถูกกำหนดล่วงหน้าสำหรับแอปพลิเคชันเพื่อเปลี่ยนเส้นทางผู้ใช้หลังจากที่พวกเขาได้ลงชื่อออกจาก Logto -การใช้ Allowed _Post Sign-out Redirect URIs_ สำหรับ Logout เป็นส่วนหนึ่งของข้อกำหนด RP-Initiated (Relying Party Initiated) Logout ใน OIDC ซึ่งเป็นวิธีมาตรฐานสำหรับแอปในการเริ่มคำขอออกจากระบบให้ผู้ใช้ รวมถึงการเปลี่ยนเส้นทางผู้ใช้ไปยัง endpoint ที่กำหนดไว้ล่วงหน้าหลังจากออกจากระบบ +การใช้ Allowed _Post Sign-out Redirect URIs_ สำหรับ Logout เป็นส่วนหนึ่งของข้อกำหนด RP-Initiated (Relying Party Initiated) Logout ใน OIDC ข้อกำหนดนี้ให้วิธีการมาตรฐานสำหรับแอปพลิเคชันในการเริ่มคำขอออกจากระบบสำหรับผู้ใช้ ซึ่งรวมถึงการเปลี่ยนเส้นทางผู้ใช้ไปยัง endpoint ที่กำหนดล่วงหน้าหลังจากที่พวกเขาได้ลงชื่อออก -เมื่อผู้ใช้ออกจากระบบ Logto เซสชันของพวกเขาจะสิ้นสุดและจะถูกเปลี่ยนเส้นทางไปยัง URI ที่อนุญาตตามที่ระบุไว้ในการตั้งค่าแอป เพื่อให้แน่ใจว่าผู้ใช้จะถูกเปลี่ยนเส้นทางไปยัง endpoint ที่ได้รับอนุญาตและถูกต้องเท่านั้นหลังจากออกจากระบบ ช่วยป้องกันการเข้าถึงโดยไม่ได้รับอนุญาตและความเสี่ยงด้านความปลอดภัยที่เกี่ยวข้องกับการเปลี่ยนเส้นทางไปยัง endpoint ที่ไม่รู้จักหรือไม่ได้รับการตรวจสอบ +เมื่อผู้ใช้ลงชื่อออกจาก Logto เซสชันของพวกเขาจะถูกยุติและพวกเขาจะถูกเปลี่ยนเส้นทางไปยังหนึ่งใน URIs ที่อนุญาตที่ระบุในการตั้งค่าแอปพลิเคชัน สิ่งนี้ช่วยให้มั่นใจว่าผู้ใช้จะถูกเปลี่ยนเส้นทางไปยัง endpoint ที่ได้รับอนุญาตและถูกต้องเท่านั้นหลังจากที่พวกเขาได้ลงชื่อออก ช่วยป้องกันการเข้าถึงที่ไม่ได้รับอนุญาตและความเสี่ยงด้านความปลอดภัยที่เกี่ยวข้องกับการเปลี่ยนเส้นทางผู้ใช้ไปยัง endpoint ที่ไม่รู้จักหรือไม่ได้รับการยืนยัน -คุณสามารถดูข้อมูลเพิ่มเติมได้ที่ [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) +คุณสามารถดู [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) สำหรับข้อมูลเพิ่มเติม ### CORS allowed origins \{#cors-allowed-origins} -_CORS (Cross-origin resource sharing) allowed origins_ คือรายการ origin ที่อนุญาตให้แอปพลิเคชันส่งคำขอไปยังบริการ Logto ได้ Origin ที่ไม่ได้อยู่ในรายการนี้จะไม่สามารถส่งคำขอไปยังบริการ Logto ได้ +_CORS (Cross-origin resource sharing) allowed origins_ เป็นรายการของต้นทางที่ได้รับอนุญาตจากที่แอปพลิเคชันสามารถทำคำขอไปยังบริการ Logto ได้ ต้นทางใดที่ไม่รวมอยู่ในรายการที่อนุญาตจะไม่สามารถทำคำขอไปยังบริการ Logto ได้ -รายการ CORS allowed origins ใช้เพื่อจำกัดการเข้าถึงบริการ Logto จากโดเมนที่ไม่ได้รับอนุญาต และช่วยป้องกันการโจมตีแบบ cross-site request forgery (CSRF) โดยการระบุ origin ที่อนุญาตสำหรับแอปใน Logto จะช่วยให้แน่ใจว่ามีเพียงโดเมนที่ได้รับอนุญาตเท่านั้นที่สามารถส่งคำขอไปยังบริการได้ +รายการ CORS allowed origins ถูกใช้เพื่อจำกัดการเข้าถึงบริการ Logto จากโดเมนที่ไม่ได้รับอนุญาต และเพื่อช่วยป้องกันการโจมตี cross-site request forgery (CSRF) โดยการระบุต้นทางที่อนุญาตสำหรับแอปพลิเคชันใน Logto บริการสามารถมั่นใจได้ว่าเฉพาะโดเมนที่ได้รับอนุญาตเท่านั้นที่สามารถทำคำขอไปยังบริการได้ :::note -รายการ allowed origins ควรมี origin ที่แอปจะถูกให้บริการอยู่ เพื่อให้แน่ใจว่าคำขอจากแอปจะได้รับอนุญาต ในขณะที่คำขอจาก origin ที่ไม่ได้รับอนุญาตจะถูกบล็อก +รายการต้นทางที่อนุญาตควรมีต้นทางที่แอปพลิเคชันจะถูกให้บริการ สิ่งนี้ช่วยให้มั่นใจว่าคำขอจากแอปพลิเคชันจะได้รับอนุญาต ในขณะที่คำขอจากต้นทางที่ไม่ได้รับอนุญาตจะถูกบล็อก ::: ### OpenID provider configuration endpoint \{#openid-provider-configuration-endpoint} @@ -116,69 +115,88 @@ Endpoint สำหรับ [OpenID Connect Discovery](https://openid.net/specs/ ### Authorization endpoint \{#authorization-endpoint} -_Authorization Endpoint_ เป็นคำศัพท์ของ OIDC และเป็น endpoint ที่จำเป็นสำหรับเริ่มกระบวนการยืนยันตัวตนของผู้ใช้ เมื่อผู้ใช้พยายามเข้าถึงทรัพยากรหรือแอปที่ได้รับการลงทะเบียนกับ Logto พวกเขาจะถูกเปลี่ยนเส้นทางไปยัง _Authorization Endpoint_ เพื่อยืนยันตัวตนและขออนุญาตเข้าถึงทรัพยากรที่ร้องขอ +_Authorization Endpoint_ เป็นคำศัพท์ OIDC และเป็น endpoint ที่จำเป็นที่ใช้ในการเริ่มกระบวนการยืนยันตัวตนสำหรับผู้ใช้ เมื่อผู้ใช้พยายามเข้าถึงทรัพยากรหรือแอปพลิเคชันที่ได้รับการป้องกันที่ได้ลงทะเบียนกับแพลตฟอร์ม Logto พวกเขาจะถูกเปลี่ยนเส้นทางไปยัง _Authorization Endpoint_ เพื่อยืนยันตัวตนของพวกเขาและได้รับการอนุญาตให้เข้าถึงทรัพยากรที่ร้องขอ -คุณสามารถดูข้อมูลเพิ่มเติมได้ที่ [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) +คุณสามารถดู [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) สำหรับข้อมูลเพิ่มเติม ### Token endpoint \{#token-endpoint} -_Token Endpoint_ เป็นคำศัพท์ของ OIDC เป็น endpoint ของเว็บ API ที่ OIDC client ใช้เพื่อขอรับโทเค็นการเข้าถึง (access token), โทเค็น ID (ID token) หรือโทเค็นรีเฟรช (refresh token) จาก OIDC provider +_Token Endpoint_ เป็นคำศัพท์ OIDC เป็น endpoint ของเว็บ API ที่ใช้โดยไคลเอนต์ OIDC เพื่อรับโทเค็นการเข้าถึง, โทเค็น ID, หรือโทเค็นรีเฟรชจากผู้ให้บริการ OIDC -เมื่อ OIDC client ต้องการขอรับ access token หรือ ID token จะส่งคำขอไปยัง Token Endpoint พร้อม authorization grant ซึ่งโดยทั่วไปคือ authorization code หรือ refresh token จากนั้น Token Endpoint จะตรวจสอบ authorization grant และออก access token หรือ ID token ให้ client หาก grant ถูกต้อง +เมื่อไคลเอนต์ OIDC ต้องการรับโทเค็นการเข้าถึงหรือโทเค็น ID มันจะส่งคำขอไปยัง Token Endpoint พร้อมกับการอนุญาต grant ซึ่งมักจะเป็นโค้ดการอนุญาตหรือโทเค็นรีเฟรช Token Endpoint จะตรวจสอบการอนุญาต grant และออกโทเค็นการเข้าถึงหรือโทเค็น ID ให้กับไคลเอนต์หาก grant นั้นถูกต้อง -คุณสามารถดูข้อมูลเพิ่มเติมได้ที่ [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) +คุณสามารถดู [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) สำหรับข้อมูลเพิ่มเติม ### Userinfo endpoint \{#userinfo-endpoint} OpenID Connect [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) -### Always issue refresh token \{#always-issue-refresh-token} +### ออกโทเค็นรีเฟรชเสมอ \{#always-issue-refresh-token} -_ใช้ได้กับ: Traditional web, SPA_ +_ความพร้อมใช้งาน: เว็บแบบดั้งเดิม, SPA_ -เมื่อเปิดใช้งาน Logto จะออกโทเค็นรีเฟรช (refresh tokens) เสมอ ไม่ว่าจะมี `prompt=consent` ในคำขอการยืนยันตัวตนหรือไม่ หรือมี `offline_access` ในขอบเขต (scopes) หรือไม่ก็ตาม +เมื่อเปิดใช้งาน Logto จะออกโทเค็นรีเฟรชเสมอ โดยไม่คำนึงถึงว่ามี `prompt=consent` ในคำขอการยืนยันตัวตนหรือไม่ หรือมี `offline_access` ในขอบเขตหรือไม่ -อย่างไรก็ตาม ไม่แนะนำให้ใช้แนวทางนี้เว้นแต่จำเป็น (โดยปกติจะใช้กับการผสานรวม OAuth ของบุคคลที่สามที่ต้องการ refresh token) เพราะไม่สอดคล้องกับ OpenID Connect และอาจก่อให้เกิดปัญหาได้ +อย่างไรก็ตาม การปฏิบัตินี้ไม่แนะนำเว้นแต่จำเป็น (มักจะมีประโยชน์สำหรับการรวม OAuth ของบุคคลที่สามบางอย่างที่ต้องการโทเค็นรีเฟรช) เนื่องจากไม่เข้ากันกับ OpenID Connect และอาจทำให้เกิดปัญหาได้ -### Rotate refresh token \{#rotate-refresh-token} +### หมุนเวียนโทเค็นรีเฟรช \{#rotate-refresh-token} _ค่าเริ่มต้น: `true`_ -เมื่อเปิดใช้งาน Logto จะออก refresh token ใหม่สำหรับคำขอโทเค็นภายใต้เงื่อนไขต่อไปนี้: +เมื่อเปิดใช้งาน Logto จะออกโทเค็นรีเฟรชใหม่สำหรับคำขอโทเค็นภายใต้เงื่อนไขต่อไปนี้: -- หาก refresh token ถูกหมุนเวียน (TTL ถูกขยายโดยการออกใหม่) เป็นเวลาหนึ่งปี; **หรือ** -- หาก refresh token ใกล้หมดอายุ (>=70% ของ TTL เดิมผ่านไปแล้ว); **หรือ** -- หาก client เป็น public client เช่น Native application หรือ single page application (SPA) +- หากโทเค็นรีเฟรชถูกหมุนเวียน (มี TTL ขยายโดยการออกใหม่) เป็นเวลาหนึ่งปี; **หรือ** +- หากโทเค็นรีเฟรชใกล้หมดอายุ (>=70% ของ Time to Live (TTL) ดั้งเดิมผ่านไป); **หรือ** +- หากไคลเอนต์เป็นไคลเอนต์สาธารณะ เช่น แอปพลิเคชันเนทีฟหรือแอปหน้าเดียว (SPA) :::note -สำหรับ public clients เมื่อเปิดใช้งานฟีเจอร์นี้ จะมีการออก refresh token ใหม่เสมอเมื่อ client แลกเปลี่ยน refresh token เป็น access token ใหม่ -แม้ว่าคุณจะสามารถปิดฟีเจอร์นี้สำหรับ public clients ได้ แต่ขอแนะนำอย่างยิ่งให้เปิดไว้เพื่อเหตุผลด้านความปลอดภัย +สำหรับไคลเอนต์สาธารณะ เมื่อเปิดใช้งานฟีเจอร์นี้ โทเค็นรีเฟรชใหม่จะถูกออกเสมอเมื่อไคลเอนต์แลกเปลี่ยนเพื่อรับโทเค็นการเข้าถึงใหม่โดยใช้โทเค็นรีเฟรช +แม้ว่าคุณยังสามารถปิดฟีเจอร์นี้สำหรับไคลเอนต์สาธารณะเหล่านั้นได้ แต่ขอแนะนำอย่างยิ่งให้เปิดใช้งานเพื่อเหตุผลด้านความปลอดภัย ::: - ทำความเข้าใจการหมุนเวียน refresh token + ทำความเข้าใจการหมุนเวียนโทเค็นรีเฟรช -### อายุ refresh token (TTL) เป็นวัน \{#refresh-token-time-to-live-ttl-in-days} +### เวลาในการมีชีวิตของโทเค็นรีเฟรช (TTL) ในวัน \{#refresh-token-time-to-live-ttl-in-days} -_ใช้ได้กับ: ไม่ใช่ SPA; ค่าเริ่มต้น: 14 วัน_ +_ความพร้อมใช้งาน: ไม่ใช่ SPA; ค่าเริ่มต้น: 14 วัน_ -ระยะเวลาที่ refresh token สามารถใช้ขอ access token ใหม่ได้ก่อนหมดอายุและกลายเป็นโมฆะ คำขอโทเค็นจะขยาย TTL ของ refresh token เป็นค่านี้ +ระยะเวลาที่โทเค็นรีเฟรชสามารถใช้เพื่อขอโทเค็นการเข้าถึงใหม่ก่อนที่จะหมดอายุและกลายเป็นโมฆะ คำขอโทเค็นจะขยาย TTL ของโทเค็นรีเฟรชเป็นค่านี้ -โดยทั่วไป ค่าที่ต่ำกว่าจะดีกว่า +โดยทั่วไป ค่าที่ต่ำกว่าจะเป็นที่ต้องการ -หมายเหตุ: SPA (single page app) จะไม่สามารถขยาย TTL refresh token ได้ด้วยเหตุผลด้านความปลอดภัย หมายความว่า Logto จะไม่ขยาย TTL ผ่านคำขอโทเค็น เพื่อปรับปรุงประสบการณ์ผู้ใช้ คุณสามารถเปิดฟีเจอร์ "Rotate refresh token" เพื่อให้ Logto ออก refresh token ใหม่เมื่อจำเป็น +หมายเหตุ: การรีเฟรช TTL ไม่สามารถใช้ได้ใน SPA (แอปหน้าเดียว) ด้วยเหตุผลด้านความปลอดภัย ซึ่งหมายความว่า Logto จะไม่ขยาย TTL ผ่านคำขอโทเค็น เพื่อปรับปรุงประสบการณ์ของผู้ใช้ คุณสามารถเปิดใช้งานฟีเจอร์ "หมุนเวียนโทเค็นรีเฟรช" เพื่อให้ Logto ออกโทเค็นรีเฟรชใหม่เมื่อจำเป็น -:::caution โทเค็นรีเฟรช (refresh token) และการผูกกับเซสชัน -เมื่อ refresh token ถูกออก **โดยไม่มี** ขอบเขต `offline_access` ในคำขอการอนุญาต มันจะถูกผูกกับเซสชันของผู้ใช้ โดยเซสชันจะมี TTL คงที่ **14 วัน** หลังจากเซสชันหมดอายุ refresh token จะกลายเป็นโมฆะไม่ว่าค่า TTL ของมันจะตั้งไว้เท่าใดก็ตาม +:::caution การผูกโทเค็นรีเฟรชและเซสชัน +เมื่อโทเค็นรีเฟรชถูกออก **โดยไม่มี** ขอบเขต `offline_access` ในคำขอการอนุญาต มันจะถูกผูกกับเซสชันของผู้ใช้ เซสชันมี TTL คงที่ **14 วัน** หลังจากเซสชันหมดอายุ โทเค็นรีเฟรชจะกลายเป็นโมฆะโดยไม่คำนึงถึงการตั้งค่า TTL ของมันเอง -เพื่อให้การตั้งค่า TTL ของ refresh token มีผลเต็มที่ ต้องแน่ใจว่าได้ใส่ขอบเขต `offline_access` ในคำขอการอนุญาตของคุณ +เพื่อให้แน่ใจว่าการตั้งค่า TTL ของโทเค็นรีเฟรชมีผลเต็มที่ ตรวจสอบให้แน่ใจว่าได้รวมขอบเขต `offline_access` ในคำขอการอนุญาตของคุณ ::: ### Backchannel logout URI \{#backchannel-logout-uri} -Endpoint สำหรับ OpenID Connect backchannel logout ดู [Federated sign-out: Back-channel logout](#) สำหรับข้อมูลเพิ่มเติม +OpenID Connect backchannel logout endpoint ดู [Federated sign-out: Back-channel logout](#) สำหรับข้อมูลเพิ่มเติม -### ข้อมูลกำหนดเอง \{#custom-data} +### Max allowed grants (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} -ข้อมูลเพิ่มเติมของแอปพลิเคชันที่ไม่ได้อยู่ในคุณสมบัติที่กำหนดไว้ล่วงหน้า ผู้ใช้สามารถกำหนดฟิลด์ข้อมูลกำหนดเองตามความต้องการเฉพาะ เช่น การตั้งค่าทางธุรกิจหรือการกำหนดค่าต่าง ๆ +`maxAllowedGrants` เป็นฟิลด์ระดับแอปที่เป็นทางเลือกภายใต้ `customClientMetadata` ที่ควบคุมจำนวนสูงสุดของ grants ที่ใช้งานพร้อมกันต่อผู้ใช้สำหรับแอปปัจจุบัน + +- **ค่าเริ่มต้น**: `undefined` (ไม่มีขีดจำกัด) +- **เมื่อกำหนดค่า**: ในแต่ละการอนุญาตที่สำเร็จ Logto จะตรวจสอบจำนวน grants ที่ใช้งานทั้งหมดสำหรับผู้ใช้ในแอปปัจจุบัน (ข้ามเบราว์เซอร์และอุปกรณ์) หากเกินขีดจำกัด Logto จะเพิกถอน grants ที่เก่าที่สุด + +การตั้งค่านี้มีประโยชน์เมื่อคุณต้องการจำกัดอุปกรณ์ที่ยืนยันตัวตนพร้อมกันต่อแอป + +:::note + +ฟิลด์นี้ไม่รองรับสำหรับ: + +- แอปเครื่องต่อเครื่อง +- แอปที่ได้รับการป้องกัน +- แอป SAML + +::: + +### ข้อมูลที่กำหนดเอง \{#custom-data} + +ข้อมูลแอปพลิเคชันที่กำหนดเองเพิ่มเติมที่ไม่ได้ระบุในคุณสมบัติแอปพลิเคชันที่กำหนดไว้ล่วงหน้า ผู้ใช้สามารถกำหนดฟิลด์ข้อมูลที่กำหนดเองตามความต้องการเฉพาะของพวกเขา เช่น การตั้งค่าและการกำหนดค่าที่เฉพาะเจาะจงสำหรับธุรกิจ diff --git a/i18n/th/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..d5ebb931e26 --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,168 @@ +# เซสชัน + +เซสชันใน Logto กำหนดวิธีการสร้าง แบ่งปัน รีเฟรช และเพิกถอนสถานะการยืนยันตัวตนระหว่างแอป เบราว์เซอร์ และอุปกรณ์ต่าง ๆ + +ในทางปฏิบัติ ผู้ใช้จะรู้สึกว่า "ลงชื่อเข้าใช้" เป็นสถานะเดียว แต่สถานะของระบบถูกแบ่งออกเป็นหลายชั้น การเข้าใจชั้นเหล่านี้เป็นกุญแจสำคัญในการออกแบบพฤติกรรม SSO การต่ออายุโทเค็น และการลงชื่อออกที่สามารถคาดการณ์ได้ + +## โมเดลเซสชันใน Logto \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto domain"] + S["เซสชันการลงชื่อเข้าใช้"] + G1["Grant (App A)"] + G2["Grant (App B)"] + end + + subgraph AppA ["App domain A"] + A["เซสชัน / โทเค็นภายในแอป"] + end + + subgraph AppB ["App domain B"] + B["เซสชัน / โทเค็นภายในแอป"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **เซสชันการลงชื่อเข้าใช้ของ Logto**: สถานะการลงชื่อเข้าใช้ที่ถูกเก็บไว้ในรูปแบบคุกกี้ของโดเมน Logto ซึ่งควบคุมความพร้อมใช้งานของ SSO ในบริบทของเบราว์เซอร์ปัจจุบัน +- **Grant**: สถานะการอนุญาตเฉพาะแอปสำหรับ `user + client app` Grants เป็นสะพานเชื่อมระหว่างการลงชื่อเข้าใช้แบบรวมศูนย์และการออกโทเค็นของแอป +- **เซสชัน / โทเค็นภายในแอป**: สถานะการยืนยันตัวตนภายในแอปแต่ละแอป (โทเค็น ID / การเข้าถึง / รีเฟรช, คุกกี้เซสชันแอป ฯลฯ) + +## แนวคิดหลัก \{#core-concepts} + +### เซสชัน Logto คืออะไร? \{#what-is-a-logto-session} + +เซสชัน Logto คือสถานะการยืนยันตัวตนแบบรวมศูนย์ที่ถูกสร้างขึ้นหลังจากการลงชื่อเข้าใช้สำเร็จ หากยังคงมีผล Logto สามารถยืนยันตัวตนผู้ใช้ได้อย่างเงียบ ๆ สำหรับแอปอื่นในผู้เช่าเดียวกัน หากไม่มีอยู่ ผู้ใช้ต้องลงชื่อเข้าใช้อีกครั้ง + +### Grant คืออะไร? \{#what-are-grants} + +Grant คือสถานะการอนุญาตระดับแอปที่ผูกกับผู้ใช้และแอปไคลเอนต์เฉพาะ + +- เซสชัน Logto หนึ่งสามารถมี Grant สำหรับหลายแอป +- โทเค็นสำหรับแอปจะออกภายใต้ Grant ของแอปนั้น +- การเพิกถอน Grant จะส่งผลต่อความสามารถของแอปนั้นในการเข้าถึงแบบใช้โทเค็นต่อไป + +### ความสัมพันธ์ระหว่างเซสชัน, Grant, และสถานะการยืนยันตัวตนของแอป \{#how-session-grants-and-app-auth-state-relate} + +- **เซสชัน** ตอบคำถาม: "เบราว์เซอร์นี้สามารถทำ SSO กับ Logto ได้ตอนนี้หรือไม่?" +- **Grant** ตอบคำถาม: "ผู้ใช้นี้ได้รับอนุญาตสำหรับแอปไคลเอนต์นี้หรือไม่?" +- **เซสชันภายในแอป** ตอบคำถาม: "แอปนี้ปัจจุบันถือว่าผู้ใช้ลงชื่อเข้าใช้หรือไม่?" + +## การลงชื่อเข้าใช้และการสร้างเซสชัน \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as แอปพลิเคชันไคลเอนต์ + end + + box Logto + participant OIDC as ผู้ให้บริการ OIDC + participant SignIn as หน้าลงชื่อเข้าใช้ + end + + User ->> Client: เข้าถึงแอปพลิเคชัน + Client ->> OIDC: คำขอการอนุญาต + OIDC -->> OIDC: ตรวจสอบเซสชัน Logto ที่มีอยู่ + OIDC ->> SignIn: ขอให้ลงชื่อเข้าใช้หากจำเป็น + SignIn ->> OIDC: ผู้ใช้ยืนยันตัวตน + OIDC -->> OIDC: สร้างเซสชันและ Grant ของแอป + OIDC ->> Client: ส่งคืนรหัสการอนุญาต + Client ->> OIDC: แลกรหัสเพื่อรับโทเค็น + OIDC -->> Client: ส่งคืนโทเค็น +``` + +## โทโพโลยีเซสชันระหว่างแอปและอุปกรณ์ \{#session-topology-across-apps-and-devices} + +### เบราว์เซอร์เดียวกัน: เซสชัน Logto ที่แชร์ \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[ผู้ใช้] + A["แอปไคลเอนต์ A"] + B["แอปไคลเอนต์ B"] + C{"เซสชัน Logto มีอยู่หรือไม่?"} + D["หน้าลงชื่อเข้าใช้ Logto"] + + U --> A + A --> C + U --> B + B --> C + C -->|No| D +``` + +แอปในเบราว์เซอร์เดียวกันสามารถแชร์สถานะเซสชัน Logto แบบรวมศูนย์ได้ ดังนั้น SSO สามารถเกิดขึ้นได้โดยไม่ต้องป้อนข้อมูลรับรองซ้ำ + +### เบราว์เซอร์หรืออุปกรณ์ต่างกัน: เซสชัน Logto ที่แยกกัน \{#different-browsers-or-devices-isolated-logto-sessions} + +แต่ละเบราว์เซอร์ / อุปกรณ์มีการเก็บคุกกี้แยกกัน เซสชันที่ถูกต้องบนอุปกรณ์ A ไม่ได้หมายความว่าเซสชันที่ถูกต้องบนอุปกรณ์ B + +## วงจรชีวิตเซสชัน \{#session-lifecycle} + +### 1. สร้าง \{#1-create} + +หลังจากการยืนยันตัวตนของผู้ใช้ Logto จะสร้างเซสชันแบบรวมศูนย์และ Grant เฉพาะแอป + +### 2. ใช้ซ้ำ (SSO) \{#2-reuse-sso} + +ตราบใดที่คุกกี้เซสชันยังคงมีผลในเบราว์เซอร์เดียวกัน คำขอการอนุญาตใหม่สามารถเสร็จสิ้นได้อย่างเงียบ ๆ + +### 3. ต่ออายุโทเค็น \{#3-renew-tokens} + +การเข้าถึงแอปมักจะดำเนินต่อไปผ่านกระบวนการรีเฟรชโทเค็น (เมื่อเปิดใช้งาน) นี่คือความต่อเนื่องระดับแอป แยกจากการที่เซสชัน Logto แบบรวมศูนย์ยังคงมีอยู่หรือไม่ + +### 4. เพิกถอน / หมดอายุ \{#4-revokeexpire} + +การเพิกถอนสามารถเกิดขึ้นได้ในหลายชั้น: + +- การลงชื่อออกจากแอปภายในจะลบโทเค็น / เซสชันภายในแอป +- การสิ้นสุดเซสชันจะลบเซสชัน Logto แบบรวมศูนย์ +- การเพิกถอน Grant จะลบความต่อเนื่องของการอนุญาตระดับแอป + +## คำแนะนำในการออกแบบ \{#design-recommendations} + +- จัดการเซสชันภายในแอปอย่างชัดเจนในโค้ดแอปของคุณ +- ถือว่าเซสชัน Logto, Grant, และเซสชันภายในแอปเป็นชั้นแยกกัน +- เลือกว่าการลงชื่อออกควรเป็นเฉพาะแอปหรือทั่วโลก +- ใช้ [back-channel logout](/end-user-flows/sign-out#federated-sign-out-back-channel-logout) เมื่อจำเป็นต้องมีความสอดคล้องกันหลายแอป +- สำหรับพฤติกรรมการลงชื่อออกและรายละเอียดการใช้งาน ดู [Sign-out](/end-user-flows/sign-out) + +## แนวทางปฏิบัติที่ดีที่สุดสำหรับการเพิกถอนการเข้าถึง \{#best-practices-for-revoking-access} + +ใช้กลยุทธ์การเพิกถอนที่แตกต่างกันตามเป้าหมายของคุณ: + +- **เพิกถอนการเข้าถึงจากแอปของคุณเอง**: + เพิกถอนเซสชันเป้าหมายด้วย `revokeGrantsTarget=firstParty`. + สิ่งนี้จะลงชื่อผู้ใช้ออกจากแอปของคุณเองที่เกี่ยวข้องกับเซสชันนั้น ซึ่งสร้างประสบการณ์การลงชื่อออกที่สอดคล้องกัน + ในขณะเดียวกัน Grant สำหรับแอปของบุคคลที่สามที่มีการให้ `offline_access` สามารถยังคงใช้ได้สำหรับการผสานรวมที่ต่อเนื่อง + ดู [จัดการเซสชันผู้ใช้](/sessions/manage-user-sessions) สำหรับรายละเอียดการเพิกถอนเซสชัน + +- **เพิกถอนการเข้าถึงแอปของบุคคลที่สาม**: + เลือกหนึ่งในตัวเลือกต่อไปนี้: + + - เพิกถอนเซสชันด้วย `revokeGrantsTarget=all` เพื่อเพิกถอน Grant ทั้งหมดที่เกี่ยวข้องกับเซสชันนั้น + - เพิกถอน Grant เฉพาะโดยตรงผ่าน API การจัดการ Grant เพื่อเอาการอนุญาตแอปของบุคคลที่สามออกโดยไม่ต้องบังคับให้ลงชื่อออกจากเซสชันทั้งหมด + ดู [จัดการแอปที่ผู้ใช้อนุญาต (Grant)](/sessions/grants-management) สำหรับกลยุทธ์การเพิกถอนเฉพาะ Grant + +- **เมื่อใช้ Logto Console**: + ในหน้ารายละเอียดผู้ใช้ Logto มีการจัดการเซสชันและการจัดการแอปของบุคคลที่สามที่ได้รับอนุญาตในตัว + - การเพิกถอนเซสชันจะเพิกถอน Grant ของแอปของคุณเองด้วย เพื่อให้พฤติกรรมการลงชื่อออกของแอปของคุณเองสอดคล้องกัน + - การเพิกถอนการอนุญาตแอปของบุคคลที่สามจะเพิกถอน Grant สำหรับแอปของบุคคลที่สามนั้นในขณะที่ยังคงสถานะเซสชันเดิมไม่เปลี่ยนแปลง + +## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} + +จัดการเซสชันผู้ใช้ +จัดการแอปที่ผู้ใช้อนุญาต (Grant) +การกำหนดค่าเซสชัน +การลงชื่อออก +การลงชื่อสมัครใช้และลงชื่อเข้าใช้ + + เข้าใจกระบวนการยืนยันตัวตน + diff --git a/i18n/th/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/th/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..7076a7c84fe --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants) + +Grant ของแอปแสดงถึงสถานะการอนุญาตของผู้ใช้สำหรับแอปพลิเคชันลูกค้าเฉพาะ + +ใช้การจัดการ grants เมื่อผู้ใช้หรือผู้ดูแลระบบต้องการตรวจสอบแอปที่ได้รับอนุญาตและเพิกถอนการเข้าถึงแอปโดยไม่ต้องเพิกถอนเซสชัน Logto ทั้งหมด + +เมื่อ grants ถูกเพิกถอน โทเค็นการเข้าถึงทึบ (opaque access tokens) และโทเค็นรีเฟรช (refresh tokens) ที่ออกให้ก่อนหน้านี้สำหรับ grants เหล่านั้นจะถูกทำให้ไม่ถูกต้อง + +## เลือกเส้นทางที่ถูกต้อง \{#choose-the-right-path} + +| สถานการณ์ | เส้นทางที่แนะนำ | +| --------------------------------------------------------------- | --------------- | +| ให้ผู้ใช้ที่ลงชื่อเข้าใช้จัดการการอนุญาตแอปของตนเอง | Account API | +| ให้ผู้ดูแลระบบหรือทีมสนับสนุนจัดการ grants สำหรับผู้ใช้เป้าหมาย | Management API | +| ให้ผู้ปฏิบัติงานจัดการการอนุญาตแอปของบุคคลที่สามใน UI | Admin Console | + +## API การจัดการ grant โดยตรง \{#direct-grant-management-apis} + +### Account API (บริการตนเอง) \{#account-api-self-service} + +ใช้ Account API ในหน้าการตั้งค่าบัญชีผู้ใช้ปลายทาง: + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- อ้างอิง: [จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants)](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API (เครื่องมือผู้ดูแลระบบ) \{#management-api-admin-tools} + +ใช้ Management API ในเครื่องมือผู้ดูแลระบบและกระบวนการสนับสนุน: + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- อ้างอิง: [จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants)](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### กรองรายการ grant ตามประเภทแอป \{#filter-grant-list-by-app-type} + +จุดสิ้นสุดการแสดงรายการ grant รองรับพารามิเตอร์การค้นหา `appType` ที่เป็นทางเลือก: + +- `appType=firstParty`: แสดงรายการ grant ของแอป first-party เท่านั้น +- `appType=thirdParty`: แสดงรายการ grant ของแอป third-party เท่านั้น +- ละเว้น `appType`: แสดงรายการ grant ที่ใช้งานอยู่ทั้งหมด + +## จัดการการอนุญาตแอป third-party ใน Console \{#manage-third-party-app-authorizations-in-console} + +ใน Logto Console ใช้หน้ารายละเอียดผู้ใช้เพื่อดูและเพิกถอนแอป third-party ที่ได้รับอนุญาต + +- อ้างอิง: [จัดการแอป third-party ที่ได้รับอนุญาตของผู้ใช้](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## เพิกถอน grants เมื่อเพิกถอนเซสชัน \{#revoke-grants-when-revoking-a-session} + +เมื่อเพิกถอนเซสชันผ่าน `DELETE /api/my-account/sessions/{sessionId}` ใช้พารามิเตอร์การค้นหา `revokeGrantsTarget` ที่เป็นทางเลือกเพื่อควบคุมขอบเขตการเพิกถอน grant: + +- `all`: เพิกถอน grants สำหรับแอปทั้งหมดที่เกี่ยวข้องกับเซสชัน +- `firstParty`: เพิกถอน grants สำหรับแอป first-party เท่านั้น + +สำหรับพฤติกรรมระดับเซสชันและบริบทของจุดสิ้นสุด ดู [จัดการเซสชันของผู้ใช้](/sessions/manage-user-sessions) และ [ลงชื่อออก](/end-user-flows/sign-out) + +## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} + +Sessions +จัดการเซสชันของผู้ใช้ + + การตั้งค่าบัญชีโดย Account API: จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants) + + + การตั้งค่าบัญชีโดย Management API: จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants) + diff --git a/i18n/th/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/th/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..24bf55c868a --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# จัดการเซสชันของผู้ใช้ + +การจัดการเซสชันของผู้ใช้ช่วยให้ผู้ใช้และผู้ดูแลระบบตรวจสอบสถานะการลงชื่อเข้าใช้ที่ใช้งานอยู่และเพิกถอนเซสชันเมื่อจำเป็น + +ใน Logto คุณสามารถจัดการเซสชันผ่านสามเส้นทางทั่วไป: + +- **Account API**: สำหรับการบริการตนเองของผู้ใช้ปลายทางในหน้าการตั้งค่าบัญชีผลิตภัณฑ์ของคุณ +- **Management API**: สำหรับเครื่องมือผู้ดูแลระบบหรือสนับสนุนเพื่อจัดการเซสชันสำหรับผู้ใช้ใด ๆ +- **Admin Console**: สำหรับกระบวนการทำงานของผู้ปฏิบัติงานใน Logto Console โดยไม่ต้องสร้างเครื่องมือที่กำหนดเอง + +## เลือก API ที่เหมาะสม \{#choose-the-right-api} + +| สถานการณ์ | API ที่แนะนำ | +| ------------------------------------------------------ | -------------- | +| ให้ผู้ใช้ที่ลงชื่อเข้าใช้จัดการเซสชันที่ใช้งานของตนเอง | Account API | +| ให้ผู้ดูแลระบบหรือทีมสนับสนุนจัดการเซสชันสำหรับผู้ใช้ | Management API | +| ให้ผู้ปฏิบัติงานจัดการเซสชันโดยตรงใน Logto Console | Admin Console | + +## ดูเซสชันที่ใช้งานอยู่ \{#view-active-sessions} + +### Account API (บริการตนเอง) \{#account-api-self-service} + +ใช้ endpoint ของ Account API เพื่อแสดงรายการเซสชันที่ใช้งานอยู่ของผู้ใช้ปัจจุบัน + +- ส่วนอ้างอิง: [จัดการเซสชันของผู้ใช้](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +ก่อนที่จะเปิดเผยความสามารถนี้ให้กับผู้ใช้ปลายทาง ตรวจสอบให้แน่ใจว่าการจัดการเซสชันเปิดใช้งานในการตั้งค่า Account center และแอปของคุณร้องขอขอบเขต Account API ที่จำเป็น + +### Management API (เครื่องมือผู้ดูแลระบบ) \{#management-api-admin-tools} + +ใช้ Management API เมื่อระบบผู้ดูแลของคุณต้องการแสดงรายการเซสชันสำหรับผู้ใช้เป้าหมาย + +- ส่วนอ้างอิง: [การจัดการเซสชันของผู้ใช้](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- Endpoint รายละเอียดเพิ่มเติม (ไม่บังคับ): [`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## เพิกถอนเซสชัน \{#revoke-sessions} + +### Account API (ผู้ใช้ปลายทางเพิกถอนเซสชันของตนเอง) \{#account-api-end-user-revokes-own-sessions} + +ผู้ใช้ปลายทางสามารถเพิกถอนเซสชันเฉพาะจากรายการเซสชันของตนเอง + +- ส่วนอ้างอิง: [จัดการเซสชันของผู้ใช้](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- Endpoint: [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +สำหรับการดำเนินการที่ละเอียดอ่อน การจัดการเซสชันของ Account API ต้องการการยืนยันตัวตนของผู้ใช้ก่อนเข้าถึง ดู [รับ ID บันทึกการยืนยัน](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id) + +### Management API (ผู้ดูแลระบบเพิกถอนเซสชันของผู้ใช้) \{#management-api-admin-revokes-user-sessions} + +ผู้ดูแลระบบสามารถเพิกถอนเซสชันของผู้ใช้เป้าหมายโดยใช้ user ID และ session ID + +- ส่วนอ้างอิง: [การจัดการเซสชันของผู้ใช้](/end-user-flows/account-settings/by-management-api#user-session-management) +- Endpoint: [`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +หากทีมของคุณจัดการผู้ใช้โดยตรงใน Logto Console คุณสามารถตรวจสอบเซสชันที่ใช้งานอยู่และเพิกถอนเซสชันเฉพาะจากหน้ารายละเอียดผู้ใช้ + +- ส่วนอ้างอิง: [จัดการเซสชันที่ใช้งานของผู้ใช้](/user-management/manage-users#manage-user-active-sessions) + +## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} + +เซสชัน +จัดการแอปที่ได้รับอนุญาตของผู้ใช้ (grants) + + การตั้งค่าบัญชีโดย Account API: จัดการเซสชันของผู้ใช้ + + + การตั้งค่าบัญชีโดย Management API: การจัดการเซสชันของผู้ใช้ + + + การจัดการผู้ใช้: จัดการเซสชันที่ใช้งานของผู้ใช้ + diff --git a/i18n/th/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/th/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..f02ccfa1142 --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# การกำหนดค่าช่วงเวลาเซสชัน + +การกำหนดค่าช่วงเวลาเซสชันกำหนดการควบคุมในระดับผู้เช่าสำหรับระยะเวลาที่เซสชันการลงชื่อเข้าใช้ Logto ยังคงใช้งานได้และวิธีการบังคับใช้นโยบายการเข้าถึงที่เกี่ยวข้องกับเซสชัน + +หน้านี้ครอบคลุม: + +- การกำหนดค่า TTL ของเซสชัน +- จำนวนอุปกรณ์ที่ยืนยันตัวตนพร้อมกันสูงสุดต่อแอป + +## การกำหนดค่า TTL ของเซสชัน \{#session-ttl-configuration} + +TTL ของเซสชันกำหนดอายุการใช้งานสูงสุดของเซสชันการลงชื่อเข้าใช้ OIDC ของ Logto +เป็น **การตั้งค่าระดับผู้เช่า**: เมื่อกำหนดค่าแล้ว จะใช้กับทุกแอปและกระบวนการยืนยันตัวตนในผู้เช่านั้น + +### พฤติกรรมเริ่มต้น \{#default-behavior} + +- โดยค่าเริ่มต้น TTL ของเซสชันคือ **14 วัน** +- หากไม่มีการกำหนดค่า TTL ที่กำหนดเอง Logto จะใช้ค่านี้เป็นค่าเริ่มต้นต่อไป + +### กำหนดค่าผ่าน Logto Console \{#configure-concurrent-device-limit-via-logto-console} + +คุณสามารถกำหนดค่า TTL ของเซสชันใน Console ได้ที่: + +Console > Tenant > Settings > OIDC settings + +ใช้ **Session maximum time to live** เพื่ออัปเดตค่า + +:::note + +Console ใช้ **วัน** สำหรับการป้อนข้อมูลและการแสดงผล ในขณะที่การกำหนดค่าเซสชัน OIDC / API ใช้ **วินาที** + +::: + +### กำหนดค่าผ่าน Management API \{#configure-via-management-api} + +ใช้ endpoints เหล่านี้เพื่ออ่านและอัปเดตการกำหนดค่าเซสชัน OIDC: + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +ตัวอย่าง (`ttl` ในวินาที): + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` วินาที = 14 วัน + +:::note + +สำหรับการปรับใช้ OSS ให้รีสตาร์ทอินสแตนซ์บริการหลังจากเปลี่ยน `logto-config` เพื่อให้เซิร์ฟเวอร์สามารถรับการตั้งค่า OIDC ล่าสุดได้ + +เพื่อใช้การอัปเดตการกำหนดค่า OIDC โดยอัตโนมัติโดยไม่ต้องรีสตาร์ทบริการ [เปิดใช้งาน central redis cache](/logto-oss/central-cache) + +::: + +## จำนวนอุปกรณ์ที่ยืนยันตัวตนพร้อมกันสูงสุดต่อแอป \{#max-concurrent-authenticated-devices-per-app} + +จำนวนอุปกรณ์ที่ยืนยันตัวตนพร้อมกันสูงสุดต่อแอปเป็นการควบคุมระดับแอปที่จำกัดจำนวนการให้สิทธิ์ที่ใช้งานอยู่ที่ผู้ใช้แต่ละคนสามารถเก็บไว้สำหรับแอปเฉพาะ + +สิ่งนี้ถูกกำหนดผ่านฟิลด์ `maxAllowedGrants` ใน `customClientMetadata` ของแอปพลิเคชัน +เรียนรู้เพิ่มเติมใน [โครงสร้างข้อมูลแอปพลิเคชัน](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants) + +### พฤติกรรม \{#behavior} + +เมื่อกำหนด `maxAllowedGrants` แล้ว Logto จะประเมินการให้สิทธิ์ที่ใช้งานอยู่ของผู้ใช้สำหรับแอปปัจจุบันในทุกการอนุญาตที่สำเร็จ +หากจำนวนการให้สิทธิ์ที่ใช้งานอยู่เกินขีดจำกัด Logto จะเพิกถอนการให้สิทธิ์ที่เก่าที่สุดก่อน + +หากไม่ได้กำหนด `maxAllowedGrants` จะไม่มีการจำกัดความพร้อมกัน + +### กำหนดค่าผ่าน Logto Console \{#configure-via-logto-console} + +คุณสามารถกำหนดค่านี้ในหน้ารายละเอียดของแต่ละแอปได้ที่: + + + Console > Applications > Application details > Concurrent device limit + + +กำหนดจำนวนสูงสุดของการให้สิทธิ์ที่ใช้งานพร้อมกัน (อุปกรณ์) ต่อผู้ใช้สำหรับแอปปัจจุบัน + +:::note + +การตั้งค่านี้ไม่รองรับสำหรับแอปเครื่องต่อเครื่อง แอปที่ได้รับการป้องกัน และแอป SAML + +::: + +## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} + +Sessions +จัดการเซสชันผู้ใช้ +จัดการแอปที่ผู้ใช้ได้รับอนุญาต (grants) + + โครงสร้างข้อมูลแอปพลิเคชัน: maxAllowedGrants + +โต้ตอบกับ Management API diff --git a/i18n/th/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/th/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index ca423a81413..4ad70ce4ace 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -8,116 +8,131 @@ sidebar_position: 2 ### เรียกดูและค้นหาผู้ใช้ \{#browse-and-search-users} -เพื่อเข้าถึงฟังก์ชันการจัดการผู้ใช้ใน Logto Console ให้ไปที่ Console > การจัดการผู้ใช้ เมื่อเข้าไปแล้ว คุณจะเห็นตารางแสดงผู้ใช้ทั้งหมด +เพื่อเข้าถึงฟังก์ชันการจัดการผู้ใช้ใน Logto Console ให้ไปที่ Console > การจัดการผู้ใช้ เมื่ออยู่ที่นั่น คุณจะเห็นมุมมองตารางของผู้ใช้ทั้งหมด -ตารางประกอบด้วย 3 คอลัมน์: +ตารางประกอบด้วยสามคอลัมน์: -- **ผู้ใช้**: แสดงข้อมูลเกี่ยวกับผู้ใช้ เช่น อวาตาร์ ชื่อเต็ม ชื่อผู้ใช้ หมายเลขโทรศัพท์ และอีเมล +- **ผู้ใช้**: แสดงข้อมูลเกี่ยวกับผู้ใช้ เช่น รูปประจำตัว ชื่อเต็ม ชื่อผู้ใช้ หมายเลขโทรศัพท์ และอีเมล - **จากแอปพลิเคชัน**: แสดงชื่อแอปพลิเคชันที่ผู้ใช้ลงทะเบียนครั้งแรก - **การลงชื่อเข้าใช้ล่าสุด**: แสดงเวลาที่ผู้ใช้ลงชื่อเข้าใช้ล่าสุด -รองรับการค้นหาด้วยคีย์เวิร์ดสำหรับ [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email) +รองรับการแมปคีย์เวิร์ดสำหรับ [`name`](/user-management/user-data#name), [`id`](/user-management/user-data#id), [`username`](/user-management/user-data#username), [`primary-phone`](/user-management/user-data#primary_phone), [`primary-email`](/user-management/user-data#primary_email) ### เพิ่มผู้ใช้ \{#add-users} -นักพัฒนาสามารถสร้างบัญชีใหม่ให้ผู้ใช้ปลายทางผ่าน Console ได้ โดยคลิกปุ่ม "เพิ่มผู้ใช้" ที่มุมขวาบนของหน้าจอ +โดยใช้ Console นักพัฒนาสามารถสร้างบัญชีใหม่สำหรับผู้ใช้ปลายทางได้ ในการทำเช่นนั้น ให้คลิกที่ปุ่ม "เพิ่มผู้ใช้" ที่มุมขวาบนของหน้าจอ -เมื่อสร้างผู้ใช้ใน Logto Console หรือผ่าน Management API (ไม่ใช่การลงทะเบียนด้วยตนเองผ่าน UI) คุณต้องระบุ identifier อย่างน้อยหนึ่งรายการ ได้แก่ `primary email`, `primary phone` หรือ `username` ส่วน `name` เป็นตัวเลือก +เมื่อสร้างผู้ใช้ใน Logto Console หรือผ่าน Management API (ไม่ใช่ผู้ใช้ปลายทางที่ลงทะเบียนด้วยตนเองผ่าน UI) คุณต้องระบุอย่างน้อยหนึ่งตัวระบุ: `primary email`, `primary phone`, หรือ `username` ฟิลด์ `name` เป็นทางเลือก -หลังจากสร้างผู้ใช้แล้ว Logto จะสร้างรหัสผ่านแบบสุ่มให้อัตโนมัติ รหัสผ่านเริ่มต้นจะแสดงเพียงครั้งเดียว แต่คุณสามารถ [รีเซ็ตรหัสผ่าน](./manage-users#reset-user-password) ได้ในภายหลัง หากต้องการตั้งรหัสผ่านเฉพาะ ให้ใช้ Management API `patch /api/users/{userId}/password` เพื่ออัปเดตหลังจากสร้างผู้ใช้แล้ว +หลังจากสร้างผู้ใช้แล้ว Logto จะสร้างรหัสผ่านแบบสุ่มโดยอัตโนมัติ รหัสผ่านเริ่มต้นจะแสดงเพียงครั้งเดียว แต่คุณสามารถ [รีเซ็ตรหัสผ่าน](./manage-users#reset-user-password) ได้ในภายหลัง หากคุณต้องการตั้งค่ารหัสผ่านเฉพาะ ให้ใช้ Management API `patch /api/users/{userId}/password` เพื่ออัปเดตหลังจากสร้างผู้ใช้แล้ว -คุณสามารถคัดลอก **identifier ที่กรอก (ที่อยู่อีเมล / หมายเลขโทรศัพท์ / ชื่อผู้ใช้)** และ **รหัสผ่านเริ่มต้น** ได้ในคลิกเดียว เพื่อให้แบ่งปันข้อมูลเข้าสู่ระบบกับผู้ใช้ใหม่ได้สะดวก +คุณสามารถคัดลอก **ตัวระบุที่ป้อน (ที่อยู่อีเมล / หมายเลขโทรศัพท์ / ชื่อผู้ใช้)** และ **รหัสผ่านเริ่มต้น** ได้ด้วยคลิกเดียว ทำให้ง่ายต่อการแชร์ข้อมูลรับรองเหล่านี้กับผู้ใช้ใหม่เพื่อให้พวกเขาสามารถลงชื่อเข้าใช้และเริ่มต้นได้ :::tip -หากต้องการให้ลงทะเบียนเฉพาะผู้ที่ได้รับเชิญ แนะนำให้ [เชิญผู้ใช้ด้วย magic link](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended) วิธีนี้จะอนุญาตเฉพาะผู้ใช้ที่อยู่ใน whitelist ให้ลงทะเบียนและตั้งรหัสผ่านเอง +หากคุณต้องการใช้การลงทะเบียนเฉพาะผู้ที่ได้รับเชิญ เราแนะนำให้ [เชิญผู้ใช้ด้วยลิงก์เวทมนตร์](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended) ซึ่งจะอนุญาตให้เฉพาะผู้ใช้ที่อยู่ในรายการที่อนุญาตเท่านั้นที่สามารถลงทะเบียนด้วยตนเองและตั้งรหัสผ่านของตนเองได้ ::: ### ดูและอัปเดตโปรไฟล์ผู้ใช้ \{#view-and-update-the-user-profile} -เพื่อดูรายละเอียดของผู้ใช้ ให้คลิกแถวที่ต้องการในตารางผู้ใช้ จะเข้าสู่หน้า "**รายละเอียดผู้ใช้**" ซึ่งจะแสดงข้อมูลโปรไฟล์ของผู้ใช้ รวมถึง: +เพื่อดูรายละเอียดของผู้ใช้ เพียงคลิกที่แถวที่สอดคล้องกันในตารางผู้ใช้ ซึ่งจะนำคุณไปยังหน้า "**รายละเอียดผู้ใช้**" ที่คุณสามารถดูข้อมูลโปรไฟล์ของผู้ใช้ได้ รวมถึง: -- **ข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน (Authentication)**: - - **ที่อยู่อีเมล** ([primary_email](/user-management/user-data#primary_email)): แก้ไขได้ - - **หมายเลขโทรศัพท์** ([primary_phone](/user-management/user-data#primary_phone)): แก้ไขได้ - - **ชื่อผู้ใช้** ([username](/user-management/user-data#username)): แก้ไขได้ - - **รหัสผ่าน** ([has_password](/user-management/user-data#has_password)): สามารถสร้างรหัสผ่านแบบสุ่มใหม่ได้ ดูเพิ่มเติมที่ "[รีเซ็ตรหัสผ่านผู้ใช้](#reset-user-password)" - - **การยืนยันตัวตนหลายปัจจัย (Multi-factor authentication; MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): ดูปัจจัยการยืนยันตัวตนทั้งหมด (เช่น passkey, แอป authenticator, รหัสสำรอง) ที่ผู้ใช้ตั้งค่าไว้ สามารถลบปัจจัยเหล่านี้ใน Console ได้ - - **Passkey**: เมื่อเปิดใช้งาน [การลงชื่อเข้าใช้ด้วย passkey](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) ใน tenant คุณสามารถดู passkey ที่ผู้ใช้ตั้งค่าไว้และลบได้หากต้องการ Passkey เหล่านี้ใช้โมเดล credential เดียวกับ MFA - - **Personal access token**: สร้าง ดู เปลี่ยนชื่อ และลบ [personal access tokens](/user-management/personal-access-token) +- **ข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน**: + - **ที่อยู่อีเมล** ([primary_email](/user-management/user-data#primary_email)): สามารถแก้ไขได้ + - **หมายเลขโทรศัพท์** ([primary_phone](/user-management/user-data#primary_phone)): สามารถแก้ไขได้ + - **ชื่อผู้ใช้** ([username](/user-management/user-data#username)): สามารถแก้ไขได้ + - **รหัสผ่าน** ([has_password](/user-management/user-data#has_password)): คุณสามารถสร้างรหัสผ่านแบบสุ่มใหม่ได้ เรียนรู้เพิ่มเติมเกี่ยวกับ "[รีเซ็ตรหัสผ่านผู้ใช้](#reset-user-password)" + - **การยืนยันตัวตนหลายปัจจัย (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): ดูปัจจัยการยืนยันตัวตนทั้งหมด (เช่น passkeys, แอปยืนยันตัวตน, รหัสสำรอง) ที่ผู้ใช้ตั้งค่าไว้ สามารถลบปัจจัยใน Console ได้ + - **Passkeys**: เมื่อ [การลงชื่อเข้าใช้ด้วย passkey](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) เปิดใช้งานในผู้เช่า คุณสามารถดู passkeys การลงชื่อเข้าใช้ของผู้ใช้ในหน้ารายละเอียดผู้ใช้และลบออกได้หากจำเป็น Passkeys เหล่านี้ได้รับการสนับสนุนโดยโมเดล WebAuthn credential เดียวกันที่ใช้โดย MFA + - **โทเค็นการเข้าถึงส่วนบุคคล**: สร้าง ดู เปลี่ยนชื่อ และลบ [โทเค็นการเข้าถึงส่วนบุคคล](/user-management/personal-access-token) - **การเชื่อมต่อ**: - - **การเชื่อมต่อโซเชียล (Social connections)** ([identities](/user-management/user-data#social-identities)): - - ดูบัญชีโซเชียลที่เชื่อมโยงกับผู้ใช้ รวมถึง social ID และข้อมูลโปรไฟล์ที่ซิงก์จากผู้ให้บริการโซเชียล (เช่น หากผู้ใช้ลงชื่อเข้าใช้ด้วย Facebook จะมีรายการ "Facebook" ปรากฏ) - - สามารถลบ social identity ที่มีอยู่ได้ แต่ไม่สามารถเชื่อมโยงบัญชีโซเชียลใหม่แทนผู้ใช้ - - สำหรับตัวเชื่อมต่อโซเชียลที่เปิด [token storage](/secret-vault/federated-token-set) สามารถดูและจัดการ access token และ refresh token ได้ในหน้ารายละเอียดการเชื่อมต่อ + - **การเชื่อมต่อโซเชียล** ([identities](/user-management/user-data#social-identities)): + - ดูบัญชีโซเชียลที่เชื่อมโยงของผู้ใช้ รวมถึง ID โซเชียลและรายละเอียดโปรไฟล์ที่ซิงค์จากผู้ให้บริการโซเชียลของพวกเขา (เช่น จะมีรายการ "Facebook" ปรากฏขึ้นหากผู้ใช้ลงชื่อเข้าใช้ผ่าน Facebook) + - คุณสามารถลบตัวตนโซเชียลที่มีอยู่ได้ แต่ไม่สามารถเชื่อมโยงบัญชีโซเชียลใหม่ในนามของผู้ใช้ได้ + - สำหรับตัวเชื่อมต่อโซเชียลที่เปิดใช้งาน [การจัดเก็บโทเค็น](/secret-vault/federated-token-set) คุณสามารถดูและจัดการโทเค็นการเข้าถึงและโทเค็นรีเฟรชในหน้ารายละเอียดการเชื่อมต่อได้ - **การเชื่อมต่อ Enterprise SSO** ([sso_identities](/user-management/user-data#sso-identities)): - - ดู enterprise identity ที่เชื่อมโยงกับผู้ใช้ รวมถึง enterprise ID และข้อมูลโปรไฟล์ที่ซิงก์จากผู้ให้บริการข้อมูลระบุตัวตนขององค์กร - - ไม่สามารถเพิ่มหรือลบ enterprise SSO identity ใน Console ได้ - - สำหรับตัวเชื่อมต่อองค์กรที่ใช้ OIDC และเปิด [token storage](/secret-vault/federated-token-set) สามารถดูและลบ token ได้ในหน้ารายละเอียดการเชื่อมต่อ -- **ข้อมูลโปรไฟล์ผู้ใช้**: ชื่อ, URL อวาตาร์, ข้อมูล custom, และ OpenID Connect standard claims อื่น ๆ ที่ไม่ได้รวมไว้ ทุกฟิลด์โปรไฟล์เหล่านี้สามารถแก้ไขได้ -- **เซสชัน**: ดูรายการเซสชันที่ผู้ใช้กำลังใช้งาน รวมถึงข้อมูลอุปกรณ์ sessionId และตำแหน่ง GEO (ถ้ามี) ดูรายละเอียดเพิ่มเติมของเซสชันและเพิกถอนเซสชันได้ในหน้ารายละเอียดเซสชัน + - ดูตัวตนองค์กรที่เชื่อมโยงของผู้ใช้ รวมถึง ID องค์กรและรายละเอียดโปรไฟล์ที่ซิงค์จากผู้ให้บริการข้อมูลระบุตัวตนขององค์กร + - คุณไม่สามารถเพิ่มหรือลบตัวตน Enterprise SSO ใน Console ได้ + - สำหรับตัวเชื่อมต่อองค์กรที่ใช้ OIDC ที่เปิดใช้งาน [การจัดเก็บโทเค็น](/secret-vault/federated-token-set) คุณสามารถดูและลบโทเค็นในหน้ารายละเอียดการเชื่อมต่อได้ +- **ข้อมูลโปรไฟล์ผู้ใช้**: ชื่อ, URL รูปประจำตัว, ข้อมูลที่กำหนดเอง, และการอ้างสิทธิ์มาตรฐาน OpenID Connect เพิ่มเติมที่ไม่รวมอยู่ ข้อมูลโปรไฟล์ทั้งหมดนี้สามารถแก้ไขได้ +- **เซสชัน**: ดูรายการเซสชันที่ใช้งานของผู้ใช้ รวมถึงข้อมูลอุปกรณ์ sessionId และตำแหน่งที่ตั้งทางภูมิศาสตร์หากมี ดูรายละเอียดเพิ่มเติมของเซสชันและเพิกถอนในหน้ารายละเอียดเซสชัน :::warning -ควรตรวจสอบให้แน่ใจว่าผู้ใช้มีวิธีลงชื่อเข้าใช้อื่นก่อนลบการเชื่อมต่อโซเชียล เช่น การเชื่อมต่อโซเชียลอื่น หมายเลขโทรศัพท์ อีเมล หรือชื่อผู้ใช้พร้อมรหัสผ่าน หากไม่มีวิธีอื่น ผู้ใช้จะไม่สามารถเข้าถึงบัญชีได้อีกหลังจากลบการเชื่อมต่อโซเชียล +สิ่งสำคัญคือต้องยืนยันว่าผู้ใช้มีวิธีการลงชื่อเข้าใช้ทางเลือกก่อนที่จะลบการเชื่อมต่อโซเชียล เช่น การเชื่อมต่อโซเชียลอื่น หมายเลขโทรศัพท์ อีเมล หรือชื่อผู้ใช้พร้อมรหัสผ่าน หากผู้ใช้ไม่มีวิธีการลงชื่อเข้าใช้อื่น พวกเขาจะไม่สามารถเข้าถึงบัญชีของตนได้อีกเมื่อการเชื่อมต่อโซเชียลถูกลบ ::: ### ดูกิจกรรมของผู้ใช้ \{#view-user-activities} -เพื่อดูประวัติกิจกรรมล่าสุดของผู้ใช้ ให้ไปที่แท็บย่อย "User logs" ในหน้า "รายละเอียดผู้ใช้" จะมีตารางแสดงกิจกรรมล่าสุดของผู้ใช้ เช่น การกระทำที่เกิดขึ้น ผลลัพธ์ของการกระทำนั้น แอปที่เกี่ยวข้อง และเวลาที่ผู้ใช้ดำเนินการ +เพื่อดูการทำงานล่าสุดของผู้ใช้ ให้ไปที่แท็บย่อย "บันทึกผู้ใช้" ในหน้ารายละเอียดผู้ใช้ ที่นี่คุณจะพบตารางที่แสดงการทำงานล่าสุดของผู้ใช้ รวมถึงการกระทำที่ดำเนินการ ผลลัพธ์ของการกระทำ แอปพลิเคชันที่เกี่ยวข้อง และเวลาที่ผู้ใช้ดำเนินการ -คลิกแถวในตารางเพื่อดูรายละเอียดเพิ่มเติมใน user log เช่น IP address, user agent, raw data ฯลฯ +คลิกที่แถวในตารางเพื่อดูรายละเอียดเพิ่มเติมในบันทึกผู้ใช้ เช่น ที่อยู่ IP, user agent, ข้อมูลดิบ ฯลฯ ### ระงับผู้ใช้ \{#suspend-user} -ในหน้า "รายละเอียดผู้ใช้" คลิก "จุดสามจุด" -> ปุ่ม "ระงับผู้ใช้" +ในหน้ารายละเอียดผู้ใช้ คลิกปุ่ม "สามจุด" -> "ระงับผู้ใช้" -เมื่อผู้ใช้ถูกระงับ จะไม่สามารถลงชื่อเข้าใช้แอปของคุณและจะไม่สามารถขอรับ access token ใหม่หลังจาก token ปัจจุบันหมดอายุ นอกจากนี้ คำขอ API ใด ๆ ที่ผู้ใช้นี้ส่งจะล้มเหลว +เมื่อผู้ใช้ถูกระงับ ผู้ใช้จะไม่สามารถลงชื่อเข้าใช้แอปของคุณและจะไม่สามารถรับโทเค็นการเข้าถึงใหม่หลังจากที่โทเค็นปัจจุบันหมดอายุ นอกจากนี้ คำขอ API ใด ๆ ที่ทำโดยผู้ใช้นี้จะล้มเหลว -หากต้องการเปิดใช้งานผู้ใช้นี้อีกครั้ง ให้คลิก "จุดสามจุด" -> ปุ่ม "เปิดใช้งานผู้ใช้" +หากคุณต้องการเปิดใช้งานผู้ใช้นี้อีกครั้ง คุณสามารถทำได้โดยคลิกปุ่ม "สามจุด" -> "เปิดใช้งานผู้ใช้ใหม่" ### ลบผู้ใช้ \{#delete-user} -ในหน้า "รายละเอียดผู้ใช้" คลิก "จุดสามจุด" -> ปุ่ม "ลบ" การลบผู้ใช้ไม่สามารถย้อนกลับได้ +ในหน้ารายละเอียดผู้ใช้ คลิกปุ่ม "สามจุด" -> "ลบ" การลบผู้ใช้ไม่สามารถยกเลิกได้ ### รีเซ็ตรหัสผ่านผู้ใช้ \{#reset-user-password} -ในหน้า "รายละเอียดผู้ใช้" คลิก "จุดสามจุด" -> ปุ่ม "รีเซ็ตรหัสผ่าน" จากนั้น Logto จะสร้างรหัสผ่านแบบสุ่มใหม่ให้อัตโนมัติ +ในหน้ารายละเอียดผู้ใช้ คลิกปุ่ม "สามจุด" -> "รีเซ็ตรหัสผ่าน" จากนั้น Logto จะสร้างรหัสผ่านแบบสุ่มใหม่โดยอัตโนมัติ -หลังจากรีเซ็ตรหัสผ่านแล้ว ให้คัดลอกและส่งให้ผู้ใช้ปลายทาง เมื่อปิดหน้าต่าง "รีเซ็ตรหัสผ่าน" แล้ว จะไม่สามารถดูรหัสผ่านได้อีก หากลืมบันทึกไว้ สามารถรีเซ็ตใหม่ได้ +หลังจากที่คุณรีเซ็ตรหัสผ่านแล้ว ให้คัดลอกและส่งให้ผู้ใช้ปลายทาง เมื่อปิดหน้าต่าง "รีเซ็ตรหัสผ่าน" คุณจะไม่สามารถดูรหัสผ่านได้อีก หากคุณลืมเก็บไว้ คุณสามารถรีเซ็ตได้อีกครั้ง -คุณไม่สามารถตั้งรหัสผ่านเฉพาะให้ผู้ใช้ใน Logto Console ได้ แต่สามารถใช้ [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` เพื่อระบุรหัสผ่านได้ +คุณไม่สามารถตั้งรหัสผ่านเฉพาะสำหรับผู้ใช้ใน Logto Console แต่คุณสามารถใช้ [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` เพื่อระบุรหัสผ่านได้ -### จัดการเซสชันที่ผู้ใช้กำลังใช้งาน \{#manage-user-active-sessions} +### จัดการเซสชันที่ใช้งานของผู้ใช้ \{#manage-user-active-sessions} -ในหน้า "รายละเอียดผู้ใช้" ไปที่หน้า "รายละเอียดเซสชัน" โดยคลิกปุ่ม "จัดการ" ของเซสชันที่ต้องการ ที่นี่คุณสามารถดูข้อมูลรายละเอียดของเซสชัน เช่น อุปกรณ์ ตำแหน่ง และเวลาลงชื่อเข้าใช้ หากต้องการออกจากระบบผู้ใช้จากเซสชันนี้ ให้คลิกปุ่ม "เพิกถอนเซสชัน" ที่มุมขวาบน เซสชันจะถูกเพิกถอนทันที +ในหน้ารายละเอียดผู้ใช้ ไปที่หน้ารายละเอียดเซสชันโดยคลิกที่ปุ่ม "จัดการ" ของเซสชันเฉพาะ ที่นี่คุณสามารถดูข้อมูลรายละเอียดเกี่ยวกับเซสชัน เช่น อุปกรณ์ ตำแหน่งที่ตั้ง และเวลาลงชื่อเข้าใช้ หากคุณต้องการออกจากระบบผู้ใช้จากเซสชันนี้ เพียงคลิกปุ่ม "เพิกถอนเซสชัน" ที่มุมขวาบน และเซสชันจะถูกเพิกถอนทันที -- โดยปกติการเพิกถอนเซสชันใน Console จะเพิกถอน grant ของแอป first-party ทั้งหมดที่เกี่ยวข้องกับเซสชันนั้นด้วย และผู้ใช้ต้องลงชื่อเข้าใช้อีกครั้งเพื่อเข้าถึงใหม่ โทเค็นทึบ (Opaque token) และโทเค็นรีเฟรช (Refresh token) ที่ออกให้แอป first-party ก่อนหน้านี้จะถูกเพิกถอนทันที -- สำหรับแอป third-party ที่มีขอบเขต `offline_access` การเพิกถอนเซสชันจะไม่เพิกถอน grant ของแอปโดยอัตโนมัติ โทเค็นรีเฟรชที่ออกไว้ก่อนหน้านี้ยังคงใช้ได้จนกว่า grant จะหมดอายุ +- โดยค่าเริ่มต้น การเพิกถอนเซสชันใน Console จะเพิกถอนการให้สิทธิ์แอปแรกทั้งหมดที่เกี่ยวข้องกับเซสชันนั้นด้วย และผู้ใช้จะต้องลงชื่อเข้าใช้อีกครั้งเพื่อกู้คืนการเข้าถึง โทเค็นการเข้าถึงทึบและโทเค็นรีเฟรชที่ออกล่วงหน้าให้กับแอปแรกจะถูกเพิกถอนทันที +- สำหรับแอปที่สามที่มีขอบเขต `offline_access` การเพิกถอนเซสชันจะไม่เพิกถอนการให้สิทธิ์แอปโดยค่าเริ่มต้น โทเค็นรีเฟรชที่ออกล่วงหน้าสามารถใช้งานได้จนกว่าการให้สิทธิ์จะหมดอายุ -## ตรวจสอบความสอดคล้องของรหัสผ่าน \{#password-compliance-check} +### จัดการแอปที่ได้รับอนุญาตจากผู้ใช้ที่สาม \{#manage-user-authorized-third-party-apps} -หลังจากคุณอัปเดต [นโยบายรหัสผ่าน](/security/password-policy) ใน Logto ผู้ใช้เดิมยังคงสามารถลงชื่อเข้าใช้ด้วยรหัสผ่านเดิมได้ จะมีผลเฉพาะบัญชีใหม่ที่สร้างขึ้นเท่านั้นที่ต้องปฏิบัติตามนโยบายรหัสผ่านใหม่ +ในหน้ารายละเอียดผู้ใช้ คุณสามารถใช้ส่วน "แอปที่ได้รับอนุญาตจากผู้ใช้ที่สาม" เพื่อตรวจสอบสถานะการอนุญาตแอปสำหรับผู้ใช้ +ส่วนนี้ได้รับการสนับสนุนโดย API การจัดการแอปที่ได้รับอนุญาตจากผู้ใช้ -เพื่อบังคับใช้ความปลอดภัยที่เข้มงวดยิ่งขึ้น คุณสามารถใช้ `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) เพื่อตรวจสอบว่ารหัสผ่านของผู้ใช้ตรงตามนโยบายปัจจุบันที่กำหนดไว้ในประสบการณ์การลงชื่อเข้าใช้เริ่มต้นหรือไม่ หากไม่ตรง คุณสามารถแจ้งให้ผู้ใช้อัปเดตรหัสผ่านผ่าน flow แบบกำหนดเองโดยใช้ [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) +สำหรับแต่ละแอปที่ได้รับอนุญาต Console จะแสดง: + +- ชื่อแอป +- App ID +- เวลาสร้างการเข้าถึง + +หากคุณต้องการลบการเข้าถึง ให้คลิกการกระทำเพิกถอนและยืนยันในหน้าต่าง + +การเพิกถอนการอนุญาตแอปจะลบการให้สิทธิ์ที่สามทั้งหมดที่เกี่ยวข้องกับแอปนั้นสำหรับผู้ใช้ นอกจากนี้ยังจะเพิกถอนโทเค็นการเข้าถึงทึบและโทเค็นรีเฟรชที่ออกล่วงหน้าสำหรับแอปนั้นทันที + +## การตรวจสอบความสอดคล้องของรหัสผ่าน \{#password-compliance-check} + +หลังจากที่คุณอัปเดต [นโยบายรหัสผ่าน](/security/password-policy) ใน Logto ผู้ใช้ที่มีอยู่ยังคงสามารถลงชื่อเข้าใช้ด้วยรหัสผ่านปัจจุบันของพวกเขาได้ เฉพาะบัญชีที่สร้างใหม่เท่านั้นที่จะต้องปฏิบัติตามนโยบายรหัสผ่านที่อัปเดต + +เพื่อบังคับใช้ความปลอดภัยที่แข็งแกร่งขึ้น คุณสามารถใช้ `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) เพื่อตรวจสอบว่ารหัสผ่านของผู้ใช้ตรงตามนโยบายปัจจุบันที่กำหนดไว้ในประสบการณ์การลงชื่อเข้าใช้เริ่มต้นหรือไม่ หากไม่ตรง คุณสามารถแจ้งให้ผู้ใช้อัปเดตรหัสผ่านของพวกเขาด้วยกระบวนการที่กำหนดเองโดยใช้ [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) ### จัดการบทบาทของผู้ใช้ \{#manage-roles-of-users} -ในแท็บ "บทบาท" ของหน้าโปรไฟล์ผู้ใช้ คุณสามารถกำหนดหรือลบบทบาทได้อย่างง่ายดาย ดูรายละเอียดที่ [การควบคุมการเข้าถึงตามบทบาท (RBAC)](/authorization/role-based-access-control) +ในแท็บ "บทบาท" ของหน้ารายละเอียดผู้ใช้ คุณสามารถกำหนดหรือยกเลิกบทบาทได้อย่างง่ายดายเพื่อตอบสนองผลลัพธ์ที่คุณต้องการ ตรวจสอบ [การควบคุมการเข้าถึงตามบทบาท (RBAC)](/authorization/role-based-access-control) สำหรับรายละเอียด ### ดูองค์กรที่ผู้ใช้สังกัด \{#view-the-organizations-the-user-belongs-to} -Logto รองรับ [องค์กร](/organizations/organization-management) และสามารถจัดการสมาชิกได้ คุณสามารถดูรายละเอียดผู้ใช้และดูว่าอยู่ในองค์กรใดได้อย่างง่ายดาย +Logto รองรับ [องค์กร](/organizations/organization-management) และสามารถจัดการสมาชิกของพวกเขาได้ คุณสามารถดูรายละเอียดผู้ใช้และดูว่าเขาสังกัดองค์กรใดได้อย่างง่ายดาย ## จัดการผ่าน Logto Management API \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) คือชุด API ที่ให้สิทธิ์เข้าถึงบริการ backend ของ Logto ดังที่กล่าวไปแล้ว API ที่เกี่ยวข้องกับผู้ใช้เป็นส่วนสำคัญของบริการนี้และรองรับกรณีการใช้งานที่หลากหลาย +[Management API](/concepts/core-service/#management-api) เป็นชุดของ API ที่ให้การเข้าถึงบริการ backend ของ Logto ดังที่กล่าวไปแล้ว API ผู้ใช้เป็นส่วนสำคัญของบริการนี้และสามารถรองรับสถานการณ์ต่าง ๆ ได้หลากหลาย -API แบบ [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) ที่เกี่ยวข้องกับผู้ใช้จะอยู่ที่ `/api/users` ยกเว้นกิจกรรมของผู้ใช้ (user logs) ซึ่งอยู่ที่ `/api/logs?userId=:userId` +API [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) ที่เกี่ยวข้องกับผู้ใช้จะถูกติดตั้งที่ `/api/users` ยกเว้นกิจกรรมของผู้ใช้ เช่น บันทึกผู้ใช้ `/api/logs?userId=:userId` -คุณสามารถจัดการผู้ใช้ผ่าน Management API ได้ในหลายกรณี เช่น [การค้นหาผู้ใช้ขั้นสูง](/user-management/advanced-user-search), [การสร้างบัญชีจำนวนมาก](https://openapi.logto.io/operation/operation-createuser), [การลงทะเบียนแบบเชิญเท่านั้น](/end-user-flows/sign-up-and-sign-in/disable-user-registration) เป็นต้น +คุณสามารถจัดการผู้ใช้ผ่าน Management API ในหลายกรณีการใช้งาน เช่น [การค้นหาผู้ใช้ขั้นสูง](/user-management/advanced-user-search), [การสร้างบัญชีจำนวนมาก](https://openapi.logto.io/operation/operation-createuser), [การลงทะเบียนเฉพาะผู้ที่ได้รับเชิญ](/end-user-flows/sign-up-and-sign-in/disable-user-registration) เป็นต้น ## คำถามที่พบบ่อย \{#faqs} @@ -125,10 +140,12 @@ API แบบ [RESTful](https://en.wikipedia.org/wiki/Representational_state_tra -### จะจำกัดการเข้าถึงแอปพลิเคชันบางตัวสำหรับผู้ใช้เฉพาะกลุ่มได้อย่างไร? \{#how-to-restrict-access-to-certain-application-for-specific-users} +### วิธีจำกัดการเข้าถึงแอปพลิเคชันบางอย่างสำหรับผู้ใช้เฉพาะ \{#how-to-restrict-access-to-certain-application-for-specific-users} -เนื่องจากธรรมชาติของ [Omni-sign-in](https://logto.io/products/omni-sign-in) ของ Logto จึงไม่ได้ออกแบบมาเพื่อจำกัดการเข้าถึงแอปพลิเคชันบางตัวก่อนการยืนยันตัวตน อย่างไรก็ตาม คุณยังสามารถออกแบบบทบาทและสิทธิ์ของผู้ใช้เฉพาะแอปเพื่อปกป้องทรัพยากร API ของคุณ และตรวจสอบสิทธิ์เมื่อผู้ใช้ลงชื่อเข้าใช้สำเร็จ ดูรายละเอียดที่ การอนุญาต (Authorization): [การควบคุมการเข้าถึงตามบทบาท (RBAC)](/authorization/role-based-access-control) +เนื่องจากธรรมชาติของ [Omni-sign-in](https://logto.io/products/omni-sign-in) ของ Logto จึงไม่ได้ออกแบบมาเพื่อจำกัดการเข้าถึงของผู้ใช้ไปยังแอปพลิเคชันบางอย่างก่อนการยืนยันตัวตน +อย่างไรก็ตาม คุณยังสามารถออกแบบบทบาทและสิทธิ์ของผู้ใช้เฉพาะแอปเพื่อปกป้องทรัพยากร API ของคุณ และตรวจสอบสิทธิ์ในการเข้าถึง API เมื่อผู้ใช้ลงชื่อเข้าใช้สำเร็จ +ดูเพิ่มเติมที่ การอนุญาต: [การควบคุมการเข้าถึงตามบทบาท (RBAC)](/authorization/role-based-access-control) สำหรับข้อมูลเพิ่มเติม diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 51d374efa09..4ea54fe7d6d 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -7,49 +7,49 @@ sidebar_position: 5 # 签名密钥 -Logto [OIDC 签名密钥](https://auth.wiki/signing-key)，也被称为 “OIDC 私钥” 和 “OIDC Cookie 密钥”，是用于在 Logto [登录会话](/end-user-flows/sign-out#what-is-a-logto-session) 中签署 JWT（[访问令牌 (Access token)](https://auth.wiki/access-token) 和 [ID 令牌 (ID token)](https://auth.wiki/id-token)）以及浏览器 Cookie 的签名密钥。这些签名密钥会在初始化 Logto 数据库（[开源版](/logto-oss)）或创建新租户（[云端](/logto-cloud)）时生成，并可通过 [CLI](/logto-oss/using-cli)（开源版）、Management API 或控制台界面进行管理。 +Logto [OIDC 签名密钥](https://auth.wiki/signing-key)，也称为 "OIDC 私钥" 和 "OIDC cookie 密钥"，是用于在 Logto [登录会话](/sessions#what-is-a-logto-session)中签署 JWT（[访问令牌](https://auth.wiki/access-token) 和 [ID 令牌](https://auth.wiki/id-token)）和浏览器 cookie 的签名密钥。这些签名密钥是在初始化 Logto 数据库时生成的（[开源](/logto-oss)）或创建新租户时生成的（[Cloud](/logto-cloud)），可以通过 [CLI](/logto-oss/using-cli)（开源）、Management API 或控制台 UI 进行管理。 -默认情况下，Logto 使用椭圆曲线（EC）算法生成数字签名。然而，考虑到用户经常需要验证 JWT 签名，并且许多旧工具不支持 EC 算法（只支持 RSA），我们实现了私钥轮换功能，并允许用户选择签名算法（包括 RSA 和 EC）。这确保了与使用过时签名验证工具的服务兼容。 +默认情况下，Logto 使用椭圆曲线 (EC) 算法生成数字签名。然而，考虑到用户经常需要验证 JWT 签名，而许多旧工具不支持 EC 算法（仅支持 RSA），我们实现了旋转私钥的功能，并允许用户选择签名算法（包括 RSA 和 EC）。这确保了与使用过时签名验证工具的服务的兼容性。 :::note -理论上，签名密钥不应泄露且没有过期时间，也就是说无需轮换。但定期在一段时间后轮换签名密钥可以提升安全性。 +理论上，签名密钥不应泄露且没有过期时间，这意味着无需旋转它们。然而，在一定时间后定期旋转签名密钥可以增强安全性。 ::: -## 工作原理 \{#how-it-works} +## 它是如何工作的？\{#how-it-works} - **OIDC 私钥** - 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并注册到底层 OIDC 提供方。因此，当 Logto 颁发新的 JWT（访问令牌 (Access token) 或 ID 令牌 (ID token)）时，令牌会用私钥进行签名。同时，任何接收到 JWT 的客户端应用都可以使用配对的公钥来验证令牌签名，以确保令牌未被第三方篡改。私钥在 Logto 服务器上受到保护。而公钥，顾名思义，是公开的，任何人都可以通过 OIDC 端点的 `/oidc/jwks` 接口访问。在生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过轮换私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。 -- **OIDC Cookie 密钥** - 当用户发起登录或注册流程时，服务器上会创建一个 “OIDC 会话”，以及一组浏览器 Cookie。借助这些 Cookie，浏览器可以代表用户请求 Logto 体验 (Experience) API 执行一系列交互，如登录、注册和重置密码。但与 JWT 不同，Cookie 仅由 Logto OIDC 服务自身签名和验证，不需要非对称加密措施。因此，Cookie 签名密钥没有配对的公钥，也不使用非对称加密算法。 + 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并在底层 OIDC 提供商中注册。因此，当 Logto 颁发新的 JWT（访问令牌或 ID 令牌）时，令牌会使用私钥进行签名。同时，任何接收到 JWT 的客户端应用程序都可以使用配对的公钥验证令牌签名，以确保令牌未被任何第三方篡改。私钥在 Logto 服务器上受到保护。然而，正如其名称所示，公钥是公开的，可以通过 OIDC 端点的 `/oidc/jwks` 接口访问。生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过旋转私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。 +- **OIDC cookie 密钥** + 当用户启动登录或注册流程时，服务器上会创建一个 "OIDC 会话"，以及一组浏览器 cookie。通过这些 cookie，浏览器可以请求 Logto Experience API 代表用户执行一系列交互，例如登录、注册和重置密码。然而，与 JWT 不同，cookie 仅由 Logto OIDC 服务本身签名和验证，不需要非对称加密措施。因此，我们没有用于 cookie 签名密钥的配对公钥，也没有非对称加密算法。 -## 通过控制台界面轮换签名密钥 \{#rotate-signing-keys-from-console-ui} +## 从控制台 UI 旋转签名密钥 \{#rotate-signing-keys-from-console-ui} -Logto 引入了 “签名密钥轮换” 功能，允许你在租户中创建新的 OIDC 私钥和 Cookie 密钥。 +Logto 引入了“签名密钥旋转”功能，允许你在租户中创建新的 OIDC 私钥和 cookie 密钥。 -1. 进入 控制台 > 签名密钥。在这里，你可以管理 OIDC 私钥和 OIDC Cookie 密钥。 +1. 进入 控制台 > 租户设置 > OIDC 配置。在这里，你可以管理 OIDC 私钥和 OIDC Cookie 密钥。 2. 若要轮换签名密钥，点击 “轮换私钥” 或 “轮换 Cookie 密钥” 按钮。轮换私钥时，你可以选择更改签名算法。 3. 你会看到一个表格，列出了所有正在使用的签名密钥。注意：你可以删除之前的密钥，但不能删除当前正在使用的密钥。 - | 状态 | 描述 | - | ---- | ------------------------------------------------------------------------ | - | 当前 | 表示该密钥目前在你的应用和 API 中处于激活使用状态。 | - | 之前 | 指的是之前使用过但已被轮换的密钥。使用该签名密钥签发的现有令牌仍然有效。 | + | 状态 | 描述 | + | ---- | ---------------------------------------------------------------------- | + | 当前 | 表示此密钥当前在你的应用程序和 API 中处于活动使用状态。 | + | 以前 | 指的是以前使用过但已被旋转出的密钥。使用此签名密钥的现有令牌仍然有效。 | -请记住，轮换涉及以下三个操作： +请记住，旋转涉及以下三个操作： -1. **创建新签名密钥**：这将要求你的所有**应用程序**和**API**采用新的签名密钥。 -2. **轮换当前密钥**：轮换后，现有密钥将被标记为 “之前”，不会被新创建的应用和 API 使用。但用该密钥签名的令牌仍然有效。 -3. **移除之前的密钥**：标记为 “之前” 的密钥将被吊销并从表格中移除。 +1. **创建新的签名密钥**：这将要求你的所有 **应用程序** 和 **API** 采用新的签名密钥。 +2. **旋转当前密钥**：现有密钥在旋转后将被指定为“以前”，并且不会被新创建的应用程序和 API 使用。然而，使用此密钥签名的令牌仍然有效。 +3. **移除以前的密钥**：标记为“以前”的密钥将被撤销并从表中移除。 :::warning -切勿连续（两次或多次）轮换签名密钥，否则可能导致所有已签发的令牌失效。 +切勿连续旋转签名密钥（两次或更多次），因为这可能会使所有已颁发的令牌失效。 -- 对于 OSS 用户，轮换签名密钥后需要重启 Logto 实例，新签名密钥才会生效。 -- 对于云端用户，新签名密钥在轮换后立即生效，但请确保不要连续多次轮换签名密钥。 +- 对于 OSS 用户，旋转签名密钥后，需要重启 Logto 实例以使新签名密钥生效。 +- 对于 Cloud 用户，新签名密钥在旋转后立即生效，但请确保不要连续多次旋转签名密钥。 ::: ## 相关资源 \{#related-resources} - JWT 中 EC 与 RSA 签名算法简介 + JWT 中的 EC 和 RSA 签名算法介绍 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 5ce681e4398..7b08ca0e16c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -7,89 +7,91 @@ sidebar_position: 1 ## 什么是 Logto Account API \{#what-is-logto-account-api} -Logto Account API 是一套全面的 API，允许终端用户直接通过 API 访问，无需经过 Management API。主要亮点如下： +Logto Account API 是一组全面的 API，允许终端用户直接访问 API，而无需通过 Management API。以下是其亮点： -- 直接访问：Account API 让终端用户可以直接访问和管理自己的账户资料，无需通过 Management API 中转。 -- 用户资料与身份管理：用户可以完全管理自己的资料和安全设置，包括更新身份信息（如邮箱、手机号和密码），以及管理社交账号绑定。MFA 和 SSO 支持即将上线。 -- 全局访问控制：管理员可以对访问设置进行全局控制，并自定义每个字段的权限。 -- 无缝授权 (Authorization)：授权 (Authorization) 变得前所未有的简单！只需使用 `client.getAccessToken()` 获取 OP（Logto）的不透明令牌 (Opaque token)，并将其作为 `Bearer ` 附加到 Authorization 头部即可。 +- 直接访问：Account API 使终端用户能够直接访问和管理自己的账户资料，而无需中转 Management API。 +- 用户资料和身份管理：用户可以完全管理他们的资料和安全设置，包括更新身份信息（如电子邮件、电话和密码）以及管理社交连接。MFA 和 SSO 支持即将推出。 +- 全局访问控制：管理员拥有完整的全局控制权，可以自定义每个字段。 +- 无缝授权 (Authorization)：授权 (Authorization) 比以往更简单！只需使用 `client.getAccessToken()` 获取 OP (Logto) 的不透明访问令牌，并将其作为 `Bearer ` 附加到 Authorization 头中。 -通过 Logto Account API，你可以构建一个与 Logto 完全集成的自定义账户管理系统，比如个人资料页。 +通过 Logto Account API，你可以构建一个自定义的账户管理系统，如与 Logto 完全集成的个人资料页面。 -常见的使用场景包括： +以下是一些常见的使用场景： -- 获取用户资料 +- 检索用户资料 - 更新用户资料 - 更新用户密码 -- 更新用户身份信息，包括邮箱、手机号和社交账号 -- 管理 MFA 因子（验证方式） +- 更新用户身份信息，包括电子邮件、电话和社交连接 +- 管理 MFA 因素（验证） - 管理用户会话 +- 管理用户授权的应用程序（授权） -想了解更多可用 API，请访问 [Logto Account API 参考文档](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 参考文档](https://openapi.logto.io/group/endpoint-verifications)。 +要了解更多可用的 API，请访问 [Logto Account API 参考](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 参考](https://openapi.logto.io/group/endpoint-verifications)。 :::note -SSO 账户查看和账户删除功能目前通过 Logto Management API 提供。实现细节请参见 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 +SSO 账户查看和账户删除功能目前通过 Logto Management API 提供。有关实现细节，请参阅 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 ::: ## 如何启用 Account API \{#how-to-enable-account-api} -进入 控制台 > 登录与账户 > 账户中心。 +导航到 控制台 > 登录和账户 > 账户中心。 -Account API 默认关闭，因此其访问控制是锁定的。切换 **启用 Account API** 开关即可开启。 +Account API 默认关闭，因此其访问控制被锁定。切换 **启用 Account API** 以打开它。 -开启后，可以为标识符、资料数据和第三方令牌访问配置每个字段的权限。每个字段支持 `关闭`、`只读` 或 `可编辑`，默认是 `关闭`。 +启用后，为标识符、资料数据和第三方令牌访问配置每个字段的权限。每个字段支持 `Off`、`ReadOnly` 或 `Edit`；默认是 `Off`。 1. **安全字段**： - - 包括：主邮箱、主手机号、社交身份、密码和 MFA。 - - 终端用户在编辑这些字段前，必须通过密码、邮箱或短信验证身份，获取一个 10 分钟有效的验证记录 ID。详见 [获取验证记录 ID](#get-a-verification-record-id)。 - - 若要使用 WebAuthn 密钥作为 MFA，请将前端应用域名添加到 **WebAuthn 相关来源**，以便账户中心和登录体验共享密钥。详见 [绑定新的 WebAuthn 密钥](#link-a-new-webauthn-passkey)。 + - 字段包括：主电子邮件、主电话、社交身份、密码和 MFA。 + - 在终端用户编辑这些字段之前，他们必须通过密码、电子邮件或短信验证身份，以获得 10 分钟的验证记录 ID。请参阅 [获取验证记录 ID](#get-a-verification-record-id)。 + - 要使用 WebAuthn 密钥进行 MFA，请将你的前端应用程序域添加到 **WebAuthn 相关来源**，以便账户中心和登录体验可以共享密钥。请参阅 [链接新的 WebAuthn 密钥](#link-a-new-webauthn-passkey)。 2. **资料字段**： - - 包括：用户名、姓名、头像、[profile](/user-management/user-data#profile)（其他标准资料属性）和 [custom data](/user-management/user-data#custom-data)。 - - 终端用户可直接编辑，无需额外验证。 -3. **密钥库**： - - 对于 OIDC 或 OAuth 社交和企业连接器，Logto [密钥库](/secret-vault/federated-token-set) 会在认证后安全存储第三方访问令牌 (Access token) 和刷新令牌 (Refresh token)。应用可调用外部 API，如同步 Google 日历事件，无需再次提示用户登录。启用 Account API 后，令牌检索功能自动开放。 + - 字段包括：用户名、姓名、头像、[资料](/user-management/user-data#profile)（其他标准资料属性）和[自定义数据](/user-management/user-data#custom-data)。 + - 终端用户可以在不进行额外验证的情况下编辑这些字段。 +3. **秘密保险库**： + - 对于 OIDC 或 OAuth 社交和企业连接器，Logto [秘密保险库](/secret-vault/federated-token-set) 在认证后安全地存储第三方访问和刷新令牌。应用程序可以调用外部 API，例如同步 Google 日历事件，而无需再次提示用户登录。一旦启用 Account API，令牌检索将自动可用。 4. **会话管理**： - - 启用后，用户可查看和管理活跃会话，包括设备信息和上次登录时间。用户还可撤销会话，实现特定设备登出。 - - 终端用户访问会话管理前，需通过密码、邮箱或短信验证身份，获取一个 10 分钟有效的验证记录 ID。详见 [获取验证记录 ID](#get-a-verification-record-id)。 + - 启用后，用户可以查看和管理他们的活动会话，包括设备信息和上次登录时间。用户还可以撤销会话以从特定设备注销。 + - 同一 `Sessions` 字段权限也控制用户授权的应用程序（授权）API（查看和撤销授权）。 + - 在终端用户访问会话管理之前，他们必须通过密码、电子邮件或短信验证身份，以获得 10 分钟的验证记录 ID。请参阅 [获取验证记录 ID](#get-a-verification-record-id)。 ## 如何访问 Account API \{#how-to-access-account-api} :::note -为确保访问令牌 (Access token) 拥有合适的权限，请确保你已在 Logto 配置中正确设置了对应的权限 (Scopes)。 +为了确保访问令牌具有适当的权限，请确保在 Logto 配置中正确配置了相应的权限 (Scopes)。 -例如，`POST /api/my-account/primary-email` API 需要配置 `email` 权限；`POST /api/my-account/primary-phone` API 需要配置 `phone` 权限。 +例如，对于 `POST /api/my-account/primary-email` API，你需要配置 `email` 权限；对于 `POST /api/my-account/primary-phone` API，你需要配置 `phone` 权限。 ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...其他选项 - // 添加适合你用例的权限 (Scopes)。 + // 添加适合你的用例的适当权限。 scopes: [ UserScope.Email, // 用于 `{POST,DELETE} /api/my-account/primary-email` API UserScope.Phone, // 用于 `{POST,DELETE} /api/my-account/primary-phone` API - UserScope.CustomData, // 管理自定义数据 - UserScope.Address, // 管理地址 + UserScope.CustomData, // 用于管理自定义数据 + UserScope.Address, // 用于管理地址 UserScope.Identities, // 用于身份和 MFA 相关 API - UserScope.Profile, // 管理用户资料 - UserScope.Sessions, // 管理用户会话 + UserScope.Profile, // 用于管理用户资料 + UserScope.Sessions, // 用于管理用户会话和应用程序授权 ], }; ``` ::: -### 获取访问令牌 (Access token) \{#fetch-an-access-token} +### 获取访问令牌 \{#fetch-an-access-token} -在应用中配置好 SDK 后，可以使用 `client.getAccessToken()` 方法获取访问令牌 (Access token)。该令牌为不透明令牌 (Opaque token)，可用于访问 Account API。 +在你的应用程序中设置 SDK 后，你可以使用 `client.getAccessToken()` 方法获取访问令牌。此令牌是不透明令牌，可用于访问 Account API。 -如果你未使用官方 SDK，请在访问令牌授权请求 `/oidc/token` 时将 `resource` 设为空。 +如果你没有使用官方 SDK，你应该在访问令牌授予请求到 `/oidc/token` 时将 `resource` 设置为空。 ### 使用访问令牌访问 Account API \{#access-account-api-using-access-token} -与 Account API 交互时，应在 HTTP 头部的 `Authorization` 字段中以 Bearer 格式（`Bearer YOUR_TOKEN`）携带访问令牌。 +在与 Account API 交互时，你应该在 HTTP 头的 `Authorization` 字段中以 Bearer 格式（`Bearer YOUR_TOKEN`）包含访问令牌。 以下是获取用户账户信息的示例： @@ -98,18 +100,18 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## 管理基础账户信息 \{#manage-basic-account-information} +## 管理基本账户信息 \{#manage-basic-account-information} -### 获取用户账户信息 \{#retrieve-user-account-information} +### 检索用户账户信息 \{#retrieve-user-account-information} -获取用户数据，可使用 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 接口。 +要获取用户数据，你可以使用 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 端点。 ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -响应体示例： +响应体如下： ```json { @@ -120,13 +122,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -响应字段会根据账户中心设置有所不同。 +响应字段可能会根据账户中心设置而有所不同。 -### 更新基础账户信息 \{#update-basic-account-information} +### 更新基本账户信息 \{#update-basic-account-information} -基础账户信息包括用户名、姓名、头像、自定义数据以及其他资料信息。 +基本账户信息包括用户名、姓名、头像、自定义数据和其他资料信息。 -要更新 **用户名、姓名、头像和 customData**，可使用 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 接口。 +要更新 **用户名、姓名、头像和自定义数据**，你可以使用 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 端点。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -要更新其他资料信息，包括 **familyName、givenName、middleName、nickname、profile（个人主页 URL）、website、gender、birthdate、zoneinfo、locale 和 address**，可使用 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 接口。 +要更新其他资料信息，包括 **familyName、givenName、middleName、nickname、profile（个人资料页面 URL）、website、gender、birthdate、zoneinfo、locale 和 address**，你可以使用 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 端点。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -144,17 +146,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 管理标识符及其他敏感信息 \{#manage-identifiers-and-other-sensitive-information} +## 管理标识符和其他敏感信息 \{#manage-identifiers-and-other-sensitive-information} -出于安全考虑，Account API 对涉及标识符及其他敏感信息的操作增加了一层授权 (Authorization)。 +出于安全原因，Account API 需要对涉及标识符和其他敏感信息的操作进行额外的授权 (Authorization) 层。 ### 获取验证记录 ID \{#get-a-verification-record-id} -首先，你需要获取一个 **验证记录 ID**，有效期为 10 分钟（TTL）。该 ID 用于在更新敏感信息前验证用户身份。即用户通过密码、邮箱验证码或短信验证码验证身份后，有 10 分钟时间可更新认证 (Authentication) 相关数据，包括标识符、凭证、社交账号绑定和 MFA。 +首先，你需要获取一个具有 10 分钟过期时间（TTL）的 **验证记录 ID**。这可以用于在更新敏感信息之前验证用户的身份。这意味着一旦用户通过密码、电子邮件验证码或短信验证码成功验证其身份，他们就有 10 分钟的时间来更新与认证 (Authentication) 相关的数据，包括标识符、凭据、社交账户链接和 MFA。 -获取验证记录 ID 的方式有：[验证用户密码](#verify-the-users-password) 或 [向用户邮箱或手机号发送验证码](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)。 +要获取验证记录 ID，你可以 [验证用户的密码](#verify-the-users-password) 或 [向用户的电子邮件或电话发送验证码](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)。 -#### 验证用户密码 \{#verify-the-users-password} +#### 验证用户的密码 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -响应体示例： +响应体如下： ```json { @@ -172,13 +174,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 通过发送验证码到用户邮箱或手机号验证 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 通过向用户的电子邮件或电话发送验证码进行验证 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -使用此方法需先 [配置邮箱连接器](/connectors/email-connectors/) 或 [短信连接器](/connectors/sms-connectors/)，并确保已配置 `UserPermissionValidation` 模板。 +要使用此方法，你需要 [配置电子邮件连接器](/connectors/email-connectors/) 或 [SMS 连接器](/connectors/sms-connectors/)，并确保配置了 `UserPermissionValidation` 模板。 ::: -以邮箱为例，请求新的验证码并获取验证记录 ID： +以电子邮件为例，请求一个新的验证码并获取验证记录 ID： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -响应体示例： +响应体如下： ```json { @@ -196,7 +198,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -收到验证码后，可用其更新验证记录的验证状态。 +收到验证码后，你可以使用它来更新验证记录的验证状态。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -205,17 +207,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -验证通过后，即可使用验证记录 ID 更新用户标识符。 +在验证代码后，你现在可以使用验证记录 ID 来更新用户的标识符。 -如需了解更多验证相关内容，请参见 [通过 Account API 进行安全验证](/end-user-flows/security-verification)。 +要了解更多关于验证的信息，请参阅 [通过 Account API 进行安全验证](/end-user-flows/security-verification)。 -### 携带验证记录 ID 发送请求 \{#send-request-with-verification-record-id} +### 发送带有验证记录 ID 的请求 \{#send-request-with-verification-record-id} -在发送更新用户标识符的请求时，需要在请求头中通过 `logto-verification-id` 字段携带验证记录 ID。 +在发送请求以更新用户的标识符时，你需要在请求头中包含验证记录 ID，并使用 `logto-verification-id` 字段。 ### 更新用户密码 \{#update-users-password} -要更新用户密码，可使用 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 接口。 +要更新用户密码，你可以使用 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 端点。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -226,18 +228,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -与注册时设置的密码一样，通过 Account API 设置的密码也必须符合你在 控制台 > 安全 > 密码策略 配置的 [密码策略](/security/password-policy)。如不符合策略，Logto 会返回详细的校验结果和错误信息。 +与注册时创建的密码一样，通过 Account API 设置的密码必须符合你在 控制台 > 安全 > 密码策略 中配置的 [密码策略](/security/password-policy)。如果密码不符合策略，Logto 将返回详细的验证结果和错误消息。 ::: -### 更新或绑定新邮箱 \{#update-or-link-new-email} +### 更新或链接新的电子邮件 \{#update-or-link-new-email} :::note -使用此方法需先 [配置邮箱连接器](/connectors/email-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 +要使用此方法，你需要 [配置电子邮件连接器](/connectors/email-connectors/)，并确保配置了 `BindNewIdentifier` 模板。 ::: -要更新或绑定新邮箱，需先证明对该邮箱的所有权。 +要更新或链接新的电子邮件，你首先需要证明对该电子邮件的所有权。 -调用 [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) 接口请求验证码。 +调用 [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) 端点请求验证码。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -你将在响应中获得 `verificationId`，并在邮箱中收到验证码，使用验证码进行邮箱验证。 +你将在响应中找到一个 `verificationId`，并在电子邮件中收到验证码，使用它来验证电子邮件。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,34 +257,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -验证通过后，可调用 [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) 更新用户邮箱，将 `verificationId` 作为 `newIdentifierVerificationRecordId` 放入请求体。 +在验证代码后，你现在可以调用 [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) 来更新用户的电子邮件，将 `verificationId` 设置为请求体中的 `newIdentifierVerificationRecordId`。 :::info[两个不同的验证记录 ID] -此请求需要两个独立的验证记录 ID： +此请求需要两个单独的验证记录 ID： -- **`logto-verification-id`（请求头）**：证明用户身份，用于敏感操作前。可通过 [验证用户密码](#verify-the-users-password) 或 [发送验证码到现有邮箱或手机号](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 获得。 -- **`newIdentifierVerificationRecordId`（请求体）**：证明对新邮箱的所有权。即上文 `POST /api/verifications/verification-code` 返回的 `verificationRecordId`。 +- **`logto-verification-id`（头部）**：在进行敏感更改之前证明用户的身份。通过 [验证用户的密码](#verify-the-users-password) 或 [向用户的现有电子邮件或电话发送验证码](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 获取。 +- **`newIdentifierVerificationRecordId`（主体）**：证明新电子邮件地址的所有权。这是从上面的 `POST /api/verifications/verification-code` 调用返回的 `verificationRecordId`。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # 验证用户身份（来自密码或现有邮箱/手机号验证） + # 验证用户身份（通过密码或现有电子邮件/电话验证） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" 证明新邮箱所有权（来自上方验证码流程） + # "newIdentifierVerificationRecordId" 证明新电子邮件的所有权（来自上面的验证码流程） --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -与注册时收集的邮箱一样，通过 Account API 绑定的邮箱也必须通过你在 控制台 > 安全 > 黑名单 配置的 [黑名单](/security/blocklist) 校验。如邮箱违反策略，Logto 会拒绝请求并返回详细错误。 +与注册时收集的电子邮件一样，通过 Account API 链接的任何电子邮件必须通过你在 控制台 > 安全 > 阻止列表 中配置的 [阻止列表](/security/blocklist) 验证。如果电子邮件违反策略，Logto 将拒绝请求并返回详细错误。 ::: -### 移除用户邮箱 \{#remove-the-users-email} +### 删除用户的电子邮件 \{#remove-the-users-email} -要移除用户邮箱，可使用 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 接口。 +要删除用户的电子邮件，你可以使用 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 端点。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -290,17 +292,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 管理手机号 \{#manage-phone} +### 管理电话 \{#manage-phone} :::note -使用此方法需先 [配置短信连接器](/connectors/sms-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 +要使用此方法，你需要 [配置 SMS 连接器](/connectors/sms-connectors/)，并确保配置了 `BindNewIdentifier` 模板。 ::: -与更新邮箱类似，可使用 [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 接口更新或绑定新手机号。使用 [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 接口移除用户手机号。 +类似于更新电子邮件，你可以使用 [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 端点更新或链接新的电话。并使用 [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 端点删除用户的电话。 -### 绑定新的社交账号 \{#link-a-new-social-connection} +### 链接新的社交连接 \{#link-a-new-social-connection} -要绑定新的社交账号，首先需通过 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) 请求授权 URL。 +要链接新的社交连接，首先你应该使用 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) 请求授权 URL。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -309,13 +311,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`：对应 [社交连接器](/connectors/social-connectors/) 的 ID。 -- `redirectUri`：用户授权后跳转的 URI，你需在此 URL 上托管网页并捕获回调。 -- `state`：授权后返回的状态参数，建议为随机字符串，用于防止 CSRF 攻击。 +- `connectorId`：[社交连接器](/connectors/social-connectors/)的 ID。 +- `redirectUri`：用户授权应用程序后的重定向 URI，你应该在此 URL 上托管一个网页并捕获回调。 +- `state`：用户授权应用程序后返回的状态，它是一个用于防止 CSRF 攻击的随机字符串。 -响应中会有 `verificationRecordId`，请妥善保存。 +在响应中，你会找到一个 `verificationRecordId`，请保留以备后用。 -用户授权后，你将在 `redirectUri` 上收到带有 `state` 参数的回调。然后可使用 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 验证社交账号。 +在用户授权应用程序后，你将在 `redirectUri` 上收到带有 `state` 参数的回调。然后你可以使用 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 端点验证社交连接。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,32 +326,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` 是用户授权后社交连接器返回的数据，你需在回调页面解析 `redirectUri` 的查询参数，并将其封装为 JSON 作为 `connectorData` 字段值。 +`connectorData` 是用户授权应用程序后社交连接器返回的数据，你需要在回调页面中解析并获取 `redirectUri` 的查询参数，并将其包装为 JSON 作为 `connectorData` 字段的值。 -最后，可使用 [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 绑定社交账号。 +最后，你可以使用 [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 端点链接社交连接。 :::info[两个不同的验证记录 ID] -此请求需要两个独立的验证记录 ID： +此请求需要两个单独的验证记录 ID： -- **`logto-verification-id`（请求头）**：证明用户身份，用于敏感操作前。可通过 [验证用户密码](#verify-the-users-password) 或 [发送验证码到现有邮箱或手机号](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 获得。 -- **`newIdentifierVerificationRecordId`（请求体）**：标识要绑定的社交身份。即上文 `POST /api/verifications/social` 返回的 `verificationRecordId`。 +- **`logto-verification-id`（头部）**：在进行敏感更改之前证明用户的身份。通过 [验证用户的密码](#verify-the-users-password) 或 [向用户的现有电子邮件或电话发送验证码](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 获取。 +- **`newIdentifierVerificationRecordId`（主体）**：标识要链接的社交身份。这是从上面的 `POST /api/verifications/social` 调用返回的 `verificationRecordId`。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # 验证用户身份（来自密码或现有邮箱/手机号验证） + # 验证用户身份（通过密码或现有电子邮件/电话验证） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" 标识要绑定的社交账号（来自上方社交验证流程） + # "newIdentifierVerificationRecordId" 标识要链接的社交连接（来自上面的社交验证流程） --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### 移除社交账号 \{#remove-a-social-connection} +### 删除社交连接 \{#remove-a-social-connection} -要移除社交账号，可使用 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 接口。 +要删除社交连接，你可以使用 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 端点。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -357,30 +359,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### 绑定新的 WebAuthn 密钥 \{#link-a-new-webauthn-passkey} +### 链接新的 WebAuthn 密钥 \{#link-a-new-webauthn-passkey} :::note -请先 [启用 MFA 和 WebAuthn](/end-user-flows/mfa)。 +记得先 [启用 MFA 和 WebAuthn](/end-user-flows/mfa)。 ::: :::note -使用此方法需在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 +要使用此方法，你需要在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 ::: -**步骤 1：将前端应用域名添加到相关来源** +**步骤 1：将你的前端应用程序来源添加到相关来源** -WebAuthn 密钥绑定到特定主机名（RP ID）。只有托管在 RP ID 来源的应用才能注册或认证 (Authentication) 这些密钥。 +WebAuthn 密钥绑定到一个特定的主机名，称为 **Relying Party ID (RP ID)**。只有托管在 RP ID 来源上的应用程序才能注册或使用这些密钥进行认证。 -由于你的前端应用与 Logto 认证 (Authentication) 页面域名不同，需要配置 **相关来源** 以允许跨域密钥操作。 +由于你的前端应用程序从与 Logto 认证页面不同的域调用 Account API，你需要配置 **相关来源** 以允许跨域密钥操作。 **Logto 如何确定 RP ID：** -- **默认配置**：仅使用 Logto 默认域名 `https://[tenant-id].logto.app` 时，RP ID 为 `[tenant-id].logto.app` -- **自定义域名**：如配置了 [自定义域名](/logto-cloud/custom-domain) `https://auth.example.com`，RP ID 为 `auth.example.com` +- **默认设置**：如果你只使用 Logto 的默认域 `https://[tenant-id].logto.app`，则 RP ID 是 `[tenant-id].logto.app` +- **自定义域**：如果你配置了一个 [自定义域](/logto-cloud/custom-domain)，如 `https://auth.example.com`，则 RP ID 变为 `auth.example.com` **配置相关来源：** -使用 [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 接口添加前端应用来源。例如，账户中心运行在 `https://account.example.com`： +使用 [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 端点添加你的前端应用程序的来源。例如，如果你的应用程序的账户中心运行在 `https://account.example.com`： ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn 最多支持 5 个唯一 eTLD+1 标签作为相关来源。eTLD+1（有效顶级域加一标签）为可注册域部分。例如： +WebAuthn 支持最多 5 个唯一的 eTLD+1 标签作为相关来源。eTLD+1（有效顶级域加一个标签）是可注册域部分。例如： -- `https://example.com`、`https://app.example.com`、`https://auth.example.com` 计为 **一个** 标签（`example.com`） -- `https://shopping.com`、`https://shopping.co.uk`、`https://shopping.co.jp` 也计为 **一个** 标签（`shopping`） +- `https://example.com`、`https://app.example.com` 和 `https://auth.example.com` 计为 **一个** 标签（`example.com`） +- `https://shopping.com`、`https://shopping.co.uk` 和 `https://shopping.co.jp` 也计为 **一个** 标签（`shopping`） - `https://example.com` 和 `https://another.com` 计为 **两个** 标签 -如需支持超过 5 个不同域名作为相关来源，请参考 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 文档。 +如果你需要支持超过 5 个不同的域作为相关来源，请参阅 [相关来源请求](https://passkeys.dev/docs/advanced/related-origins/) 文档以获取详细信息。 ::: **步骤 2：请求新的注册选项** -使用 [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 接口请求注册新密钥。Logto 允许每个账户注册多个密钥。 +使用 [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 端点请求注册新的密钥。Logto 允许每个用户账户注册多个密钥。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -411,7 +413,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -响应体示例： +你将收到如下响应： ```json { @@ -421,25 +423,25 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat } ``` -**步骤 3：在本地浏览器注册密钥** +**步骤 3：在本地浏览器中注册密钥** -以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 为例，可用 `startRegistration` 方法在本地浏览器注册密钥。 +以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 为例，你可以使用 `startRegistration` 函数在本地浏览器中注册密钥。 ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // 第一步服务器返回的数据 + optionsJSON: registrationOptions, // 第 1 步中服务器返回的数据 }); -// 保存 response 以备后用 +// 保存响应以备后用 ``` **步骤 4：验证密钥注册** -使用 [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 接口验证密钥注册。 +使用 [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 端点验证密钥注册。 -此步骤会验证认证器生成的加密签名，确保密钥合法创建且传输过程中未被篡改。 +此步骤验证由认证器生成的加密签名，以确保密钥是合法创建的，并且在传输过程中没有被篡改。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -448,12 +450,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`：第二步本地浏览器返回的响应。 -- `verificationRecordId`：第一步服务器返回的验证记录 ID。 +- `payload`：第 2 步中本地浏览器的响应。 +- `verificationRecordId`：第 1 步中服务器返回的验证记录 ID。 -**步骤 5：绑定密钥** +**步骤 5：链接密钥** -最后，可通过 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 接口将密钥绑定到用户账户。 +最后，你可以使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端点将密钥链接到用户的账户。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 -- `type`：MFA 因子类型，目前仅支持 `WebAuthn`。 -- `newIdentifierVerificationRecordId`：第一步服务器返回的验证记录 ID。 +- `verification_record_id`：一个有效的验证记录 ID，通过验证用户的现有因素获得，你可以参考 [获取验证记录 ID](#get-a-verification-record-id) 部分以获取更多详细信息。 +- `type`：MFA 因素的类型，目前仅支持 `WebAuthn`。 +- `newIdentifierVerificationRecordId`：第 1 步中服务器返回的验证记录 ID。 -### 管理已有 WebAuthn 密钥 \{#manage-existing-webauthn-passkeys} +### 管理现有的 WebAuthn 密钥 \{#manage-existing-webauthn-passkeys} -管理已有 WebAuthn 密钥，可使用 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 获取当前密钥及其他 MFA 验证因子。 +要管理现有的 WebAuthn 密钥，你可以使用 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 端点获取当前密钥和其他 MFA 验证因素。 ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -响应体示例： +响应体如下： ```json [ @@ -491,12 +493,12 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`：验证因子 ID。 -- `type`：验证因子类型，WebAuthn 密钥为 `WebAuthn`。 -- `name`：密钥名称，选填。 -- `agent`：密钥的 user agent。 +- `id`：验证的 ID。 +- `type`：验证的类型，`WebAuthn` 表示 WebAuthn 密钥。 +- `name`：密钥的名称，可选字段。 +- `agent`：密钥的用户代理。 -通过 [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 接口更新密钥名称： +使用 [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 端点更新密钥名称： ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -通过 [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 接口删除密钥： +使用 [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 端点删除密钥： ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -514,19 +516,19 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'logto-verification-id: ' ``` -### 绑定新的 TOTP \{#link-a-new-totp} +### 链接新的 TOTP \{#link-a-new-totp} :::note -请先 [启用 MFA 和 TOTP](/end-user-flows/mfa)。 +记得先 [启用 MFA 和 TOTP](/end-user-flows/mfa)。 ::: :::note -使用此方法需在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 +要使用此方法，你需要在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 ::: **步骤 1：生成 TOTP 密钥** -使用 [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 接口生成 TOTP 密钥。 +使用 [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 端点生成 TOTP 密钥。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -响应体示例： +响应体如下： ```json { @@ -542,11 +544,11 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp } ``` -**步骤 2：向用户展示 TOTP 密钥** +**步骤 2：向用户显示 TOTP 密钥** -使用密钥生成二维码或直接展示给用户。用户应将其添加到自己的认证器应用（如 Google Authenticator、Microsoft Authenticator 或 Authy）。 +使用密钥生成二维码或直接显示给用户。用户应将其添加到他们的认证器应用程序（如 Google Authenticator、Microsoft Authenticator 或 Authy）。 -二维码的 URI 格式为： +二维码的 URI 格式应为： ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -558,9 +560,9 @@ otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp ``` -**步骤 3：绑定 TOTP 因子** +**步骤 3：绑定 TOTP 因素** -用户将密钥添加到认证器应用后，需要验证并绑定到账户。使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 接口绑定 TOTP 因子。 +在用户将密钥添加到他们的认证器应用程序后，他们需要验证并将其绑定到他们的账户。使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端点绑定 TOTP 因素。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,27 +572,27 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 +- `verification_record_id`：一个有效的验证记录 ID，通过验证用户的现有因素获得。你可以参考 [获取验证记录 ID](#get-a-verification-record-id) 部分以获取更多详细信息。 - `type`：必须为 `Totp`。 -- `secret`：第一步生成的 TOTP 密钥。 +- `secret`：第 1 步中生成的 TOTP 密钥。 :::note -每个用户只能有一个 TOTP 因子。如已存在 TOTP 因子，尝试添加会返回 422 错误。 +用户一次只能拥有一个 TOTP 因素。如果用户已经有一个 TOTP 因素，尝试添加另一个将导致 422 错误。 ::: -### 管理备份码 \{#manage-backup-codes} +### 管理备份代码 \{#manage-backup-codes} :::note -请先 [启用 MFA 和备份码](/end-user-flows/mfa)。 +记得先 [启用 MFA 和备份代码](/end-user-flows/mfa)。 ::: :::note -使用此方法需在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 +要使用此方法，你需要在 [账户中心设置](#how-to-enable-account-api) 中启用 `mfa` 字段。 ::: -**步骤 1：生成新备份码** +**步骤 1：生成新的备份代码** -使用 [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 接口生成一组新的 10 个备份码。 +使用 [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 端点生成一组新的 10 个备份代码。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -响应体示例： +响应体如下： ```json { @@ -606,20 +608,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back } ``` -**步骤 2：向用户展示备份码** +**步骤 2：向用户显示备份代码** -在绑定备份码前，必须将其展示给用户，并提示： +在将备份代码绑定到用户账户之前，你必须将它们显示给用户，并指示他们： -- 立即下载或抄写这些备份码 -- 妥善保管 -- 每个备份码只能使用一次 -- 这些备份码是丢失主 MFA 方法后的最后救援手段 +- 立即下载或写下这些代码 +- 将它们存储在安全的位置 +- 了解每个代码只能使用一次 +- 知道这些代码是他们失去对主要 MFA 方法的访问权限时的最后手段 -建议以清晰、易复制的格式展示，并提供下载选项（如文本文件或 PDF）。 +你应该以清晰、易于复制的格式显示代码，并考虑提供下载选项（例如，作为文本文件或 PDF）。 -**步骤 3：将备份码绑定到用户账户** +**步骤 3：将备份代码绑定到用户账户** -使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 接口将备份码绑定到用户账户。 +使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端点将备份代码绑定到用户账户。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 +- `verification_record_id`：一个有效的验证记录 ID，通过验证用户的现有因素获得。你可以参考 [获取验证记录 ID](#get-a-verification-record-id) 部分以获取更多详细信息。 - `type`：必须为 `BackupCode`。 -- `codes`：上一步生成的备份码数组。 +- `codes`：在上一步中生成的备份代码数组。 :::note -- 每个用户只能有一组备份码。如全部用完，需重新生成并绑定新备份码。 -- 备份码不能作为唯一 MFA 因子。用户必须至少启用一种其他 MFA 因子（如 WebAuthn 或 TOTP）。 -- 每个备份码只能使用一次。 +- 用户一次只能拥有一组备份代码。如果所有代码都已使用，用户需要生成并绑定新代码。 +- 备份代码不能是唯一的 MFA 因素。用户必须至少启用一个其他 MFA 因素（如 WebAuthn 或 TOTP）。 +- 每个备份代码只能使用一次。 ::: -**查看已有备份码** +**查看现有备份代码** -要查看已有备份码及其使用状态，可使用 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 接口： +要查看现有备份代码及其使用状态，请使用 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 端点： ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -响应体示例： +响应体如下： ```json { @@ -667,19 +669,19 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes } ``` -- `code`：备份码。 -- `usedAt`：备份码使用时间，未使用为 `null`。 +- `code`：备份代码。 +- `usedAt`：代码使用的时间戳，如果尚未使用则为 `null`。 ### 管理用户会话 \{#manage-user-sessions} -**列出活跃会话** +**列出活动会话** -要列出用户活跃会话，可使用 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 接口。 +要列出用户的活动会话，你可以使用 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 端点。 :::note -- 访问此接口需配置 `UserScope.Sessions` 权限。 -- 账户中心设置中的 `Sessions` 字段需设为 `只读` 或 `可编辑`。 +- 需要 `UserScope.Sessions` 权限才能访问此端点。 +- 账户中心设置中的 `Sessions` 字段必须设置为 `ReadOnly` 或 `Edit`。 ::: @@ -690,14 +692,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**按会话 ID 撤销会话** +**通过会话 ID 撤销会话** -要撤销指定会话，使用 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 接口。 +要撤销特定会话，请使用 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 端点。 :::note -- 访问此接口需配置 `UserScope.Sessions` 权限。 -- 账户中心设置中的 `Sessions` 字段需设为 `可编辑`。 +- 需要 `UserScope.Sessions` 权限才能访问此端点。 +- 账户中心设置中的 `Sessions` 字段必须设置为 `Edit`。 ::: ```bash @@ -709,7 +711,58 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} 可选查询参数： -- `revokeGrantsTarget`：可选，指定撤销会话时要撤销的授权目标。可选值： - - `all`：撤销与该会话关联的所有授权。 - - `firstParty`：仅撤销与该会话关联的第一方应用授权（推荐大多数场景，既撤销自有应用访问，又保留第三方应用授权，提升用户体验）。 - - 未指定：默认行为为撤销未包含 `offline_access` 权限的授权，通常意味着撤销该会话的非刷新令牌授权。 +- `revokeGrantsTarget`：可选地指定要与会话一起撤销的授权目标。可能的值： + - `all`：撤销与会话关联的所有授权。 + - `firstParty`：仅撤销与会话关联的第一方应用程序授权。（推荐用于大多数用例，因为它撤销了你自己的应用程序的访问权限，同时保留了第三方应用程序授权，从而提供更好的用户体验。） + - 未指定：默认行为是撤销没有 `offline_access` 权限的授权，这通常意味着撤销会话的非刷新令牌授权。 + +### 管理用户授权的应用程序（授权）\{#manage-user-authorized-apps-grants} + +当用户需要从其账户设置页面查看和撤销授权的应用程序时，使用用户授权的应用程序（授权）API。 + +:::note + +- 应用程序授权 API 与会话 API 共享相同的权限模型。 +- 需要 `UserScope.Sessions` 权限。 +- 账户中心设置中的 `Sessions` 字段必须启用： + - `ReadOnly` 或 `Edit` 以列出授权。 + - `Edit` 以撤销授权。 + +::: + +**列出活动应用程序授权** + +要列出当前用户的活动应用程序授权，请使用 [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) 端点。 + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +可选查询参数： + +- `appType=firstParty`：仅返回第一方应用程序授权。 +- `appType=thirdParty`：仅返回第三方应用程序授权。 +- 省略 `appType`：返回所有活动授权。 + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**通过授权 ID 撤销应用程序授权** + +要撤销特定应用程序授权，请使用 [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) 端点。 + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +当授权被撤销时，先前为该授权颁发的不透明访问令牌和刷新令牌将失效。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index 1844c434b5a..44536aa379b 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -6,21 +6,21 @@ sidebar_position: 2 ## 集成 \{#integrations} -Logto 提供了多种 Management API 用于管理用户账户。你可以使用这些 API 为终端用户构建自助账户设置页面。 +Logto 提供了多种 Management API 来管理用户账户。你可以使用这些 API 为终端用户构建一个自助账户设置页面。 ### 架构 \{#architecture} ```mermaid graph TB A[用户] --> B[客户端应用] - B -->|自托管账户设置 API 调用|C[服务端应用] + B -->|自托管账户设置 API 调用|C[服务器端应用] C -->|Management API 调用| D[Logto] ``` -1. **用户**：已认证 (Authentication) 的终端用户，需要访问和管理自己的账户设置。 +1. **用户**：需要访问和管理其账户设置的已认证终端用户。 2. **客户端应用**：为用户提供账户设置页面的客户端应用。 -3. **服务端应用**：为客户端提供账户设置 API 的服务端应用。与 Logto Management API 交互。 -4. **Logto**：作为认证 (Authentication) 与授权 (Authorization) 服务的 Logto。提供用于管理用户账户的 Management API。 +3. **服务器端应用**：为客户端提供账户设置 API 的服务器端应用。与 Logto Management API 交互。 +4. **Logto**：作为认证 (Authentication) 和授权 (Authorization) 服务的 Logto。提供用于管理用户账户的 Management API。 ### 时序图 \{#sequence-diagram} @@ -29,161 +29,161 @@ Logto 提供了多种 Management API 用于管理用户账户。你可以使用 autonumber actor User as 用户 participant Client as 客户端应用 - participant Server as 服务端应用 + participant Server as 服务器端应用 participant Logto as Logto - 用户 ->> 客户端应用: 访问客户端应用 - 客户端应用 ->> Logto: POST /oidc/auth - 用户 -->> Logto: 登录 - Logto -->> 客户端应用: 重定向回客户端应用 - 客户端应用 ->> Logto: POST /oidc/token - Logto ->> 客户端应用: 访问令牌 (Access token) A - 客户端应用 ->> 服务端应用: GET /account-settings（携带访问令牌 (Access token) A） - 服务端应用 ->> Logto: POST /oidc/token（携带客户端凭证） - Logto ->> 服务端应用: 访问令牌 (Access token) B - 服务端应用 ->> Logto: GET /api/users/{userId}（携带访问令牌 (Access token) B） - Logto ->> 服务端应用: 用户详情 - 服务端应用 ->> 客户端应用: 用户详情 + User ->> Client: 访问客户端应用 + Client ->> Logto: POST /oidc/auth + User -->> Logto: 登录 + Logto -->> Client: 重定向到客户端应用 + Client ->> Logto: POST /oidc/token + Logto ->> Client: 访问令牌 (Access token) A + Client ->> Server: GET /account-settings (携带访问令牌 A) + Server ->> Logto: POST /oidc/token (使用客户端凭证) + Logto ->> Server: 访问令牌 (Access token) B + Server ->> Logto: GET /api/users/{userId} (携带访问令牌 B) + Logto ->> Server: 用户详情 + Server ->> Client: 用户详情 ``` 1. 用户访问客户端应用。 -2. 客户端应用向 Logto 发送认证请求，并重定向用户到 Logto 登录页面。 -3. 用户在 Logto 上完成登录。 -4. 已认证 (Authentication) 用户被重定向回客户端应用，并携带授权码。 -5. 客户端应用向 Logto 请求访问令牌 (Access token)，用于自托管账户设置 API 访问。 -6. Logto 向客户端应用颁发访问令牌 (Access token)。 -7. 客户端应用携带用户访问令牌 (Access token) 向服务端应用发起账户设置请求。 -8. 服务端应用从用户访问令牌 (Access token) 验证请求者身份和权限，然后向 Logto 请求 Management API 访问令牌 (Access token)。 -9. Logto 向服务端应用颁发 Management API 访问令牌 (Access token)。 -10. 服务端应用使用 Management API 访问令牌 (Access token) 向 Logto 请求用户数据。 -11. Logto 验证服务端身份和 Management API 权限，并返回用户数据。 -12. 服务端应用根据请求者权限处理用户数据，并将用户账户详情返回给客户端应用。 - -### 集成 Management API 到服务端应用 \{#integrate-management-api-to-server-side-application} - -查看 [Management API](/integrate-logto/interact-with-management-api/) 章节，了解如何将 Management API 集成到服务端应用。 +2. 客户端应用向 Logto 发送认证 (Authentication) 请求，并将用户重定向到 Logto 登录页面。 +3. 用户登录到 Logto。 +4. 已认证 (Authentication) 的用户被重定向回客户端应用，并携带授权令牌。 +5. 客户端应用请求 Logto 的访问令牌 (Access token) 以访问自托管账户设置 API。 +6. Logto 向客户端应用授予访问令牌 (Access token)。 +7. 客户端应用携带用户访问令牌向服务器端应用发送账户设置请求。 +8. 服务器端应用从用户访问令牌中验证请求者的身份和权限。然后请求 Logto 的 Management API 访问令牌。 +9. Logto 向服务器端应用授予 Management API 访问令牌。 +10. 服务器端应用使用 Management API 访问令牌向 Logto 请求用户数据。 +11. Logto 验证服务器的身份和 Management API 权限，并返回用户数据。 +12. 服务器端应用根据请求者的权限处理用户数据，并将用户账户详情返回给客户端应用。 + +### 将 Management API 集成到服务器端应用 \{#integrate-management-api-to-server-side-application} + +查看 [Management API](/integrate-logto/interact-with-management-api/) 部分，了解如何将 Management API 集成到服务器端应用中。 ## 用户管理 API \{#user-management-apis} -### 用户数据结构 \{#user-data-schema} +### 用户数据架构 \{#user-data-schema} -查看 [用户数据与自定义数据](/user-management/user-data/) 章节，了解 Logto 中的用户数据结构。 +查看 [用户数据和自定义数据](/user-management/user-data/) 部分，了解 Logto 中的用户架构。 -### 用户资料与标识符管理 API \{#user-profile-and-identifiers-management-apis} +### 用户资料和标识符管理 API \{#user-profile-and-identifiers-management-apis} -用户的资料和标识符是用户管理的核心。你可以使用以下 API 管理用户资料和标识符。 +用户的资料和标识符对于用户管理至关重要。你可以使用以下 API 来管理用户资料和标识符。 -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。 | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 更新用户详情。 | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 通过用户 ID 更新用户资料字段。 | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 通过用户 ID 获取用户自定义数据。 | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 通过用户 ID 更新用户自定义数据。 | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 通过用户 ID 更新用户封禁状态。 | +| 方法 | 路径 | 描述 | +| ----- | -------------------------------------------------------------------------------------------------------- | -------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。 | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 更新用户详情。 | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 通过用户 ID 更新用户资料字段。 | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 通过用户 ID 获取用户自定义数据。 | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 通过用户 ID 更新用户自定义数据。 | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 通过用户 ID 更新用户暂停状态。 | -### 邮箱和手机号验证 \{#email-and-phone-number-verification} +### 电子邮件和电话号码验证 \{#email-and-phone-number-verification} -在 Logto 系统中，邮箱地址和手机号都可以作为用户标识符，因此验证它们非常重要。为此，我们提供了一套验证码 API，帮助你验证提供的邮箱或手机号。 +在 Logto 系统中，电子邮件地址和电话号码都可以作为用户标识符，因此验证它们至关重要。为此，我们提供了一组验证码 API 来帮助验证提供的电子邮件或电话号码。 :::note -在用新邮箱或手机号更新用户资料前，请确保已验证该邮箱或手机号。 +在使用新电子邮件或电话号码更新用户资料之前，请确保验证电子邮件或电话号码。 ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 发送邮箱或手机号验证码。 | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 通过验证码验证邮箱或手机号。 | +| 方法 | 路径 | 描述 | +| ---- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 发送电子邮件或电话号码验证码。 | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 通过验证码验证电子邮件或电话号码。 | ### 用户密码管理 \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------ | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 通过用户 ID 验证当前用户密码。 | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 通过用户 ID 更新用户密码。 | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 通过用户 ID 检查用户是否设置了密码。 | +| 方法 | 路径 | 描述 | +| ----- | -------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 通过用户 ID 验证当前用户密码。 | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 通过用户 ID 更新用户密码。 | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 检查用户是否通过用户 ID 设置了密码。 | :::note -在更新用户密码前，请确保已验证用户当前密码。 +在更新用户密码之前，请确保验证用户的当前密码。 ::: ### 用户社交身份管理 \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。社交身份可在 `identities` 字段中找到。 | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 通过用户 ID 绑定已认证 (Authentication) 的社交身份。 | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 通过用户 ID 解绑社交身份。 | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 通过用户 ID 直接更新已绑定的社交身份。 | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 获取社交身份提供商的授权 URI。使用该 URI 发起新的社交身份绑定流程。 | +| 方法 | 路径 | 描述 | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。社交身份可以在 `identities` 字段中找到。 | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 通过用户 ID 将已认证的社交身份链接到用户。 | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 通过用户 ID 从用户中取消链接社交身份。 | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 通过用户 ID 直接更新链接到用户的社交身份。 | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 获取社交身份提供商的授权 URI。使用此 URI 启动新的社交身份连接。 | ```mermaid sequenceDiagram autoNumber participant User as 用户 participant Client as 客户端应用 - participant App as 服务端应用 + participant App as 服务器应用 participant Logto as Logto participant IdP as 社交身份提供商 - 用户 ->> 客户端应用: 访问客户端应用，请求绑定社交身份 - 客户端应用 ->> 服务端应用: 发送绑定社交身份请求 - 服务端应用 ->> Logto: POST /api/connectors/{connectorId}/authorization-uri - Logto ->> 服务端应用: 授权 URI - 服务端应用 ->> 客户端应用: 返回授权 URI - 客户端应用 ->> 社交身份提供商: 跳转到 IdP 授权页面 - 用户 -->> 社交身份提供商: 登录 IdP - 社交身份提供商 ->> 客户端应用: 携带授权码重定向回客户端应用 - 客户端应用 ->> 服务端应用: 绑定社交身份请求，转发 IdP 授权响应 - 服务端应用 ->> Logto: POST /api/users/{userId}/identities - Logto ->> 社交身份提供商: 使用授权码获取用户信息 - 社交身份提供商 ->> Logto: 返回用户信息 + User ->> Client: 访问客户端应用请求绑定社交身份 + Client ->> App: 发送请求绑定社交身份 + App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri + Logto ->> App: 授权 URI + App ->> Client: 返回授权 URI + Client ->> IdP: 重定向到 IdP 授权页面 + User -->> IdP: 登录到 IdP + IdP ->> Client: 使用授权码重定向到客户端应用 + Client ->> Server: 链接社交身份请求，转发 IdP 授权响应 + Server ->> Logto: POST /api/users/{userId}/identities + Logto ->> IdP: 使用授权码从 IdP 获取用户信息 + IdP ->> Logto: 返回用户信息 ``` 1. 用户访问客户端应用并请求绑定社交身份。 -2. 客户端应用向服务端发送绑定社交身份请求。 -3. 服务端向 Logto 请求社交身份提供商的授权 URI。你需要在请求中提供自定义的 `state` 参数和 `redirect_uri`，并确保已在社交身份提供商处注册该 `redirect_uri`。 -4. Logto 将授权 URI 返回给服务端。 -5. 服务端将授权 URI 返回给客户端应用。 +2. 客户端应用向服务器发送请求以绑定社交身份。 +3. 服务器向 Logto 发送请求以获取社交身份提供商的授权 URI。你需要在请求中提供自己的 `state` 参数和 `redirect_uri`。确保在社交身份提供商中注册 `redirect_uri`。 +4. Logto 将授权 URI 返回给服务器。 +5. 服务器将授权 URI 返回给客户端应用。 6. 客户端应用将用户重定向到 IdP 授权 URI。 -7. 用户在 IdP 上完成登录。 -8. IdP 使用 `redirect_uri` 携带授权码将用户重定向回客户端应用。 -9. 客户端应用校验 `state` 并将 IdP 授权响应转发给服务端。 -10. 服务端向 Logto 发送请求，将社交身份绑定到用户。 +7. 用户登录到 IdP。 +8. IdP 使用授权码将用户重定向回客户端应用。 +9. 客户端应用验证 `state` 并将 IdP 授权响应转发给服务器。 +10. 服务器向 Logto 发送请求，将社交身份链接到用户。 11. Logto 使用授权码从 IdP 获取用户信息。 -12. IdP 将用户信息返回给 Logto，Logto 将社交身份绑定到用户。 +12. IdP 将用户信息返回给 Logto，Logto 将社交身份链接到用户。 :::note -通过 Management API 为用户绑定新社交身份时，有以下限制： +在将新社交身份链接到用户时，需要考虑一些限制： -- Management API 不具备任何会话上下文，任何需要活动会话以安全维护社交认证 (Authentication) 状态的社交连接器都无法通过 Management API 绑定。不支持的连接器包括 apple、标准 OIDC 及标准 OAuth 2.0 连接器。 -- 同样原因，Logto 无法校验授权响应中的 `state` 参数。请确保你在客户端应用中存储 `state` 参数，并在收到授权响应时进行校验。 -- 你需要提前在社交身份提供商处注册 `redirect_uri`。否则，社交 IdP 不会将用户重定向回你的客户端应用。你的社交 IdP 必须支持多个回调 `redirect_uri`，一个用于用户登录，一个用于你的个人资料绑定页面。 +- Management API 没有任何会话上下文，任何需要活动会话以安全维护社交认证 (Authentication) 状态的社交连接器都不能通过 Management API 链接。不支持的连接器包括 apple、标准 OIDC 和标准 OAuth 2.0 连接器。 +- 出于同样的原因，Logto 无法验证授权响应中的 `state` 参数。请确保在客户端应用中存储 `state` 参数，并在收到授权响应时进行验证。 +- 你需要提前将 `redirect_uri` 注册到社交身份提供商。否则，社交 IdP 将不会将用户重定向回你的客户端应用。你的社交 IdP 必须接受多个回调 `redirect_uri`，一个用于用户登录，一个用于你自己的资料绑定页面。 ::: ### 用户企业身份管理 \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。企业身份可在 `ssoIdentities` 字段中找到。为用户详情 API 添加 `includeSsoIdentities=true` 查询参数以包含企业身份。 | +| 方法 | 路径 | 描述 | +| ---- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 通过用户 ID 获取用户详情。企业身份可以在 `ssoIdentities` 字段中找到。添加 `includeSsoIdentities=true` 查询参数到用户详情 API 以包含它们。 | -目前，Management API 不支持为用户绑定或解绑企业身份。你只能展示已绑定到用户的企业身份。 +目前，Management API 不支持将企业身份链接或取消链接到用户。你只能显示链接到用户的企业身份。 ### 个人访问令牌 \{#personal-access-token} -| method | path | description | +| 方法 | 路径 | 描述 | | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | | GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | 获取用户的所有个人访问令牌。 | | POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | 为用户添加新的个人访问令牌。 | | DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 通过名称删除用户的令牌。 | | PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 通过名称更新用户的令牌。 | -个人访问令牌为用户提供了一种安全的方式，无需使用凭证和交互式登录即可授予 [访问令牌 (Access token)](https://auth.wiki/access-token)。了解更多 [个人访问令牌的用法](/user-management/personal-access-token)。 +个人访问令牌为用户提供了一种安全的方式来授予 [访问令牌 (Access token)](https://auth.wiki/access-token)，而无需使用他们的凭据和交互式登录。了解更多关于[使用个人访问令牌](/user-management/personal-access-token)的信息。 ### 用户 MFA 设置管理 \{#user-mfa-settings-management} -| method | path | description | +| 方法 | 路径 | 描述 | | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | | GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | 通过用户 ID 获取用户 MFA 设置。 | | POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | 通过用户 ID 设置用户 MFA 验证。 | @@ -191,14 +191,29 @@ sequenceDiagram ### 用户账户删除 \{#user-account-deletion} -| method | path | description | +| 方法 | 路径 | 描述 | | ------ | -------------------------------------------------------------------------------- | ---------------------- | | DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | 通过用户 ID 删除用户。 | ### 用户会话管理 \{#user-session-management} -| method | path | description | +| 方法 | 路径 | 描述 | | ------ | -------------------------------------------------------------------------------------------------------------- | -------------------------- | | GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | 通过用户 ID 获取用户会话。 | | GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | 通过会话 ID 获取用户会话。 | | DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | 通过会话 ID 删除用户会话。 | + +### 管理用户授权的应用程序（授权）\{#manage-user-authorized-apps-grants} + +| 方法 | 路径 | 描述 | +| ------ | -------------------------------------------------------------------------------------------------------- | -------------------------- | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | 列出用户的活动应用授权。 | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | 通过 ID 撤销特定应用授权。 | + +授权列表的可选查询参数： + +- `appType=firstParty`：仅返回第一方应用授权。 +- `appType=thirdParty`：仅返回第三方应用授权。 +- 省略 `appType`：返回所有活动授权。 + +当授权被撤销时，先前为该授权颁发的不透明访问令牌 (Opaque token) 和刷新令牌 (Refresh token) 将失效。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index 031cff7da6a..76fac26d5df 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,254 +1,120 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- -# 登出 +# 注销 -在 Logto（作为 OIDC 身份提供商 (IdP)）中，登出涉及以下两个部分： +在 Logto 中，注销涉及两个层面： -- **中心化的 Logto 会话**（Logto 域下的浏览器 Cookie），以及 -- **分布式客户端认证 (Authentication) 状态**（每个应用中的令牌和本地应用会话）。 +- **Logto 会话注销**：结束 Logto 域下的集中登录会话。 +- **应用程序注销**：清除客户端应用程序中的本地会话状态和令牌。 -为了理解登出行为，建议将这两个层次分开，然后了解**授权令牌 (grant)** 如何连接它们。 +要更好地理解 Logto 中会话的工作原理，请参阅 [会话](/sessions)。 -## 核心概念 \{#core-concepts} +## 注销机制 \{#sign-out-mechanisms} -### 什么是 Logto 会话？\{#what-is-a-logto-session} +### 1) 仅客户端注销 \{#1-client-side-only-sign-out} -Logto 会话是由 Logto 管理的中心化登录状态。它在认证 (Authentication) 成功后创建，并通过 Logto 域下的 Cookie 表示。 +客户端应用程序清除其自身的本地会话和令牌（ID 令牌 / 访问令牌 / 刷新令牌）。这仅将用户从该应用程序的本地状态中注销。 -如果会话 Cookie 有效，用户可以在信任同一 Logto 租户的多个应用间实现静默认证 (Authentication)（单点登录 (SSO)）。 +- Logto 会话可能仍然活跃。 +- 其他在同一 Logto 会话下的应用程序可能仍然可以单点登录 (SSO)。 -如果没有有效会话，Logto 会显示登录页面。 +### 2) 在 Logto 结束会话（当前 Logto 实现中的全局注销） \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -### 什么是授权令牌 (grant)？\{#what-are-grants} +要清除集中式 Logto 会话，应用程序将用户重定向到结束会话端点，例如： -**授权令牌 (grant)** 表示特定用户 + 客户端应用的授权 (Authorization) 状态。 - -- 一个 Logto 会话可以拥有多个客户端应用的授权令牌 (grant)。 -- 授权令牌 (grant) 是已颁发令牌所关联的对象。 -- 在本文档中，**授权令牌 (grant)** 用作跨应用授权 (Authorization) 单元。 - -### 会话、授权令牌 (grant) 和客户端认证 (Authentication) 状态的关系 \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto 域] - S[Logto 会话] - G1[App A 的授权令牌 (grant)] - G2[App B 的授权令牌 (grant)] - end - - subgraph AppA [客户端域 A] - A[本地会话 / 令牌] - end - - subgraph AppB [客户端域 B] - B[本地会话 / 令牌] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Logto 会话** 控制中心化的单点登录 (SSO) 体验。 -- **客户端本地会话 / 令牌** 控制每个应用当前是否将用户视为已登录。 -- **授权令牌 (grant)** 通过表示应用特定的授权 (Authorization) 状态连接这两个世界。 - -## 登录回顾（为什么登出是多层次的）\{#sign-in-recap-why-sign-out-is-multi-layered} - -```mermaid -sequenceDiagram - autonumber - actor User - - box Relying Party (RP) - participant Client as 客户端应用 - end - - box Logto (IdP) - participant OIDC as OIDC 提供方 - participant SignIn as 登录页面 - end - - User ->> Client: 访问应用 - Client ->> OIDC: 跳转进行认证 (Authentication) - OIDC -->> OIDC: 检查 Logto 会话 - OIDC ->> SignIn: 如有需要，提示登录 - SignIn ->> OIDC: 用户完成认证 (Authentication) - OIDC -->> OIDC: 创建会话和授权令牌 (grant) - OIDC ->> Client: 返回授权码 - Client ->> OIDC: 用授权码换取令牌 - OIDC -->> Client: 返回令牌 -``` - -## 跨应用 / 设备的会话拓扑结构 \{#session-topology-across-apps-devices} - -### 共享会话 Cookie（同一浏览器 / 用户代理）\{#shared-session-cookie-same-browser-user-agent} - -如果用户在同一浏览器中登录多个应用，这些应用可以复用同一个 Logto 会话 Cookie，并应用单点登录 (SSO) 行为。 - -```mermaid -flowchart TD - U[用户] - A["客户端应用 A（客户端域 A）"] - B["客户端应用 B（客户端域 B）"] - C{"Logto 会话存在？（Logto 域）"} - D["登录页面（Logto 域）"] - - subgraph UA["用户代理 A（同一浏览器）"] - U - A - B - C - D - end - - U -->|登录| A - A -->|跳转到 Logto| C - U -->|打开应用| B - B -->|跳转到 Logto| C - C -->|否| D - D -->|创建会话| C -``` - -### 隔离的会话 Cookie（不同设备 / 浏览器）\{#isolated-session-cookies-different-devices-browsers} - -不同浏览器 / 设备持有不同的 Logto Cookie，因此登录会话状态是隔离的。 - -```mermaid -flowchart TD - U[用户] - A["客户端应用 A（客户端域 A）"] - C{"Logto 会话存在？（设备 A，Logto 域）"} - D["登录页面（设备 A，Logto 域）"] - - subgraph DeviceA["用户代理 A"] - A - C - D - end - - B["客户端应用 B（客户端域 B）"] - E{"Logto 会话存在？（设备 B，Logto 域）"} - F["登录页面（设备 B，Logto 域）"] - - subgraph DeviceB["用户代理 B"] - B - E - F - end - - U -->|登录| A - A -->|跳转到 Logto| C - U -->|登录| B - B -->|跳转到 Logto| E - C -->|否| D - E -->|否| F - D -->|创建会话| C - F -->|创建会话| E -``` - -## 登出机制 \{#sign-out-mechanisms} - -### 1）仅客户端登出 \{#1-client-side-only-sign-out} - -客户端应用清除自身的本地会话和令牌（ID / 访问令牌 / 刷新令牌）。这只会让用户在该应用的本地状态下登出。 - -- Logto 会话可能仍然有效。 -- 其他在同一 Logto 会话下的应用仍可单点登录 (SSO)。 +`https://{your-logto-domain}/oidc/session/end` -### 2）在 Logto 端结束会话（当前 Logto 实现下的全局登出）\{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +在当前 Logto SDK 行为中： -要清除中心化的 Logto 会话，应用需将用户重定向到结束会话端点，例如： +1. `signOut()` 重定向到 `/session/end`。 +2. 然后它进入 `/session/end/confirm`。 +3. 默认确认表单自动提交 `logout=true`。 -`https://{your-logto-domain}/oidc/session/end` +因此，当前 SDK 注销被视为**全局注销**。 -在当前 Logto SDK 行为中： +:::note -1. `signOut()` 会重定向到 `/session/end`。 -2. 然后跳转到 `/session/end/confirm`。 -3. 默认确认表单会自动提交 `logout=true`。 +- **全局注销**：撤销集中式 Logto 会话。 -因此，当前 SDK 的登出被视为**全局登出**。 +::: -### 全局登出时发生了什么 \{#what-happens-during-global-sign-out} +### 全局注销期间发生了什么 \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["客户端发起登出"] --> B["/session/end"] + A["客户端开始注销"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["撤销中心化 Logto 会话"] - D --> E{"检查每个应用的授权令牌 (grant)"} - E -->|"未授予 offline_access"| F["撤销授权令牌 (grant)"] - E -->|"已授予 offline_access"| G["保留授权令牌 (grant) 直到 TTL 到期"] + C --> D["撤销集中式 Logto 会话"] + D --> E{"检查每个应用程序的授权"} + E -->|"未授予 offline_access"| F["撤销授权"] + E -->|"授予 offline_access"| G["保留授权直到授权 TTL 过期"] ``` -在全局登出过程中： +在全局注销期间： -- 中心化的 Logto 会话被撤销。 -- 相关应用的授权令牌 (grant) 根据应用授权 (Authorization) 状态处理： - - 如果**未**授予 `offline_access`，相关授权令牌 (grant) 会被撤销。 - - 如果**已**授予 `offline_access`，结束会话不会撤销该授权令牌 (grant)。 -- 对于 `offline_access` 情况，刷新令牌和授权令牌 (grant) 会一直有效，直到授权令牌 (grant) 过期。 +- 集中式 Logto 会话被撤销。 +- 相关应用程序授权根据每个应用程序的授权状态进行处理： + - 如果未授予 `offline_access`，相关授权将被撤销。 + - 如果授予了 `offline_access`，授权不会被结束会话撤销。 +- 对于 `offline_access` 情况，刷新令牌和授权在授权过期前仍然有效。 -## 授权令牌 (grant) 生命周期与 `offline_access` 影响 \{#grant-lifetime-and-offline-access-impact} +## 授权生命周期和 `offline_access` 影响 \{#grant-lifetime-and-offline-access-impact} -- Logto 授权令牌 (grant) 默认 TTL 为 **180 天**。 -- 如果授予了 `offline_access`，结束会话默认不会撤销该应用的授权令牌 (grant)。 -- 与该授权令牌 (grant) 关联的刷新令牌链可持续有效，直到授权令牌 (grant) 过期（或被显式撤销）。 +- 默认 Logto 授权 TTL 为 **180 天**。 +- 如果授予了 `offline_access`，结束会话默认不会撤销该应用程序授权。 +- 与该授权相关的刷新令牌链可以继续，直到授权过期（或被显式撤销）。 -## 联邦登出：后端通道登出 \{#federated-sign-out-back-channel-logout} +## 联邦注销：后端通道注销 \{#federated-sign-out-back-channel-logout} -为实现跨应用一致性，Logto 支持 [后端通道登出](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)。 +为了跨应用程序的一致性，Logto 支持 [后端通道注销](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)。 -当用户从某个应用登出时，Logto 会向所有参与同一会话的应用发送登出令牌，通知它们的已注册后端通道登出 URI。 +当用户从一个应用程序注销时，Logto 可以通过向每个应用程序注册的后端通道注销 URI 发送注销令牌来通知参与同一会话的所有应用程序。 -如果在应用后端通道设置中启用了 `Is session required`，则登出令牌会包含 `sid` 以标识 Logto 会话。 +如果在应用程序后端通道设置中启用了 `Is session required`，则注销令牌将包含 `sid` 以标识 Logto 会话。 典型流程： -1. 用户从某个应用发起登出。 -2. Logto 处理结束会话，并向已注册的后端通道登出 URI 发送登出令牌。 -3. 每个应用验证登出令牌并清除自身的本地会话 / 令牌。 +1. 用户从一个应用程序启动注销。 +2. Logto 处理结束会话并向注册的后端通道注销 URI 发送注销令牌。 +3. 每个应用程序验证注销令牌并清除其自身的本地会话 / 令牌。 -## Logto SDK 中的登出方式 \{#sign-out-methods-in-logto-sdks} +## Logto SDK 中的注销方法 \{#sign-out-methods-in-logto-sdks} -- **SPA 和 Web**：`client.signOut()` 会清除本地令牌存储，并重定向到 Logto 结束会话端点。你可以提供登出后的重定向 URI。 -- **原生（包括 React Native / Flutter）**：通常只清除本地令牌存储。无会话的 webview 意味着没有持久化的 Logto 浏览器 Cookie 需要清除。 +- **SPA 和 Web**：`client.signOut()` 清除本地令牌存储并重定向到 Logto 结束会话端点。你可以提供一个注销后重定向 URI。 +- **原生应用（包括 React Native / Flutter）**：通常仅清除本地令牌存储。无会话的 webview 意味着没有持久的 Logto 浏览器 cookie 需要清除。 :::note -对于不支持无会话 webview 或无法识别 `emphasized` 设置的原生应用（如使用 **React Native** 或 **Flutter** SDK 的 Android 应用），你可以在认证 (Authentication) 请求中传递 `prompt=login` 参数，强制用户再次登录。 +对于不支持无会话 webview 或不识别 `emphasized` 设置的原生应用程序（使用 **React Native** 或 **Flutter** SDK 的 Android 应用程序），你可以通过在授权请求中传递 `prompt=login` 参数来强制用户再次登录。 ::: -## 强制每次访问都重新认证 (Authentication) \{#enforce-re-authentication-on-every-access} +## 强制每次访问重新认证 (Authentication) \{#enforce-re-authentication-on-every-access} -对于高安全性操作，在认证 (Authentication) 请求中包含 `prompt=login`，以绕过单点登录 (SSO)，每次都强制输入凭证。 +对于高安全性操作，在认证请求中包含 `prompt=login` 以绕过 SSO 并每次强制输入凭据。 -如果请求 `offline_access`（以获取刷新令牌），还需包含 `consent`，即 `prompt=login consent`。 +如果请求 `offline_access`（以接收刷新令牌），还需包含 `consent`，即 `prompt=login consent`。 -典型组合设置： +典型的组合设置： ```txt prompt=login consent ``` -## 常见问题 \{#faqs} +## 常见问题解答 \{#faqs}
-### 我没有收到后端通道登出通知。 \{#im-not-receiving-the-back-channel-logout-notifications} +### 我没有收到后端通道注销通知。 \{#im-not-receiving-the-back-channel-logout-notifications} -- 请确保后端通道登出 URI 已在 Logto 控制台正确注册。 -- 请确保你的应用在相同用户 / 会话上下文下有活跃的登录状态。 +- 确保后端通道注销 URI 在 Logto 仪表板中正确注册。 +- 确保你的应用程序对同一用户 / 会话上下文具有活动的登录状态。
## 相关资源 \{#related-resources} -理解 OIDC 后端通道登出。 +理解 OIDC 后端通道注销。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 0fe5073a562..abda53820e1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,41 +1,40 @@ --- -description: 参考 OIDC 认证 (Authentication) 集成的关键应用参数，包括重定向 URI、端点、刷新令牌 (Refresh token)、后端注销等。 +description: 参考 OIDC 认证 (Authentication) 集成的关键应用参数，包括重定向 URI、端点、刷新令牌、后端注销等。 sidebar_position: 6 --- # 应用数据结构 -## 简介 \{#introduction} +## 介绍 \{#introduction} -在 Logto 中，_应用_ 指的是在 Logto 平台上注册并被授权访问用户信息或代表用户执行操作的特定软件程序或服务。应用用于标识向 Logto API 发起请求的来源，并管理用户访问这些应用时的认证 (Authentication) 和授权 (Authorization) 流程。 +在 Logto 中，_应用_ 指的是在 Logto 平台上注册的软件程序或服务，并被授予访问用户信息或代表用户执行操作的授权。应用用于识别向 Logto API 发出请求的来源，以及管理用户访问这些应用的认证 (Authentication) 和授权 (Authorization) 过程。 -在 Logto 的登录体验中使用应用，可以让用户从一个位置轻松访问和管理他们已授权的应用，并拥有一致且安全的认证 (Authentication) 流程。这有助于简化用户体验，并确保只有被授权的人员才能访问敏感信息或代表组织执行操作。 +在 Logto 的登录体验中使用应用允许用户从一个位置轻松访问和管理他们授权的应用，并提供一致且安全的认证 (Authentication) 过程。这有助于简化用户体验，并确保只有授权的个人才能访问敏感信息或代表组织执行操作。 -应用还用于 Logto 的审计日志中，用于追踪用户活动并识别任何潜在的安全威胁或漏洞。通过将特定操作与某个应用关联，Logto 能够提供有关数据如何被访问和使用的详细洞察，帮助组织更好地管理其安全和合规性要求。 -如果你想将你的应用集成到 Logto，请参阅 [集成 Logto](/integrate-logto)。 +应用还用于 Logto 的审计日志中，以跟踪用户活动并识别任何潜在的安全威胁或漏洞。通过将特定操作与特定应用关联，Logto 可以提供有关数据如何被访问和使用的详细见解，使组织能够更好地管理其安全性和合规性要求。如果你想将应用与 Logto 集成，请参阅[集成 Logto](/integrate-logto)。 ## 属性 \{#properties} ### 应用 ID \{#application-id} -_应用 ID_ 是用于在 Logto 中唯一标识你的应用的自动生成密钥，在 OAuth 2.0 中被称为 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)。 +_应用 ID_ 是一个用于在 Logto 中标识你的应用的唯一自动生成的密钥，在 OAuth 2.0 中被称为 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)。 ### 应用类型 \{#application-types} _应用_ 可以是以下应用类型之一： -- **原生应用** 是在原生环境中运行的应用。例如 iOS 应用、Android 应用。 - - **设备流应用** 是一种特殊类型的原生应用，适用于输入受限的设备或无头应用（如智能电视、游戏主机、CLI 工具、IoT 设备）。它使用 [OAuth 2.0 设备授权许可](https://auth.wiki/device-flow) 替代标准的基于重定向的流程。详情见 [设备流快速入门](/quick-starts/device-flow)。 -- **单页应用 (Single page app)** 是在网页浏览器中运行的应用，通过从服务器获取新数据来更新页面，而无需加载整个新页面。例如 React DOM 应用、Vue 应用。 -- **传统 Web 应用** 是仅由 Web 服务器渲染和更新页面的应用。例如 JSP、PHP。 -- **机器对机器 (M2M) 应用** 是在机器环境中运行、用于直接服务间通信且无需用户交互的应用。 +- **原生应用**是在本地环境中运行的应用。例如，iOS 应用，Android 应用。 + - **设备流应用**是一种特殊类型的原生应用，适用于输入受限设备或无头应用（例如，智能电视、游戏机、CLI 工具、IoT 设备）。它使用 [OAuth 2.0 设备授权许可](https://auth.wiki/device-flow) 而不是标准的基于重定向的流程。详情请参阅[设备流快速入门](/quick-starts/device-flow)。 +- **单页应用**是在网络浏览器中运行的应用，它通过从服务器获取新数据来更新页面，而无需加载整个新页面。例如，React DOM 应用，Vue 应用。 +- **传统 Web 应用**是由 Web 服务器单独渲染和更新页面的应用。例如，JSP，PHP。 +- **机器对机器 (M2M) 应用**是在机器环境中运行的应用，用于直接的服务对服务通信，无需用户交互。 ### 应用密钥 \{#application-secret} -_应用密钥_ 是用于在认证 (Authentication) 系统中认证应用的密钥，专为私有客户端（传统 Web 和 M2M 应用）作为私有安全屏障。 +_应用密钥_ 是用于在认证 (Authentication) 系统中认证 (Authentication) 应用的密钥，特别是对于私有客户端（传统 Web 和 M2M 应用）作为私有安全屏障。 :::tip -单页应用 (SPA) 和原生应用不提供应用密钥。SPA 和原生应用属于“公共客户端”，无法保密密钥（浏览器代码或应用包可被检查）。Logto 通过 PKCE、严格的重定向 URI / CORS 校验、短生命周期访问令牌 (Access token) 和刷新令牌 (Refresh token) 轮换来保护它们，而不是使用应用密钥。 +单页应用 (SPA) 和原生应用不提供应用密钥。SPA 和原生应用是“公共客户端”，无法保密（浏览器代码或应用包是可检查的）。Logto 通过 PKCE、严格的重定向 URI / CORS 验证、短期访问令牌和刷新令牌轮换来保护它们，而不是应用密钥。 ::: ### 应用名称 \{#application-name} @@ -45,140 +44,156 @@ _应用名称_ 是应用的人类可读名称，将显示在管理控制台中 _应用名称_ 是在 Logto 中管理应用的重要组成部分，因为它允许管理员轻松识别和跟踪平台内各个应用的活动。 :::note -需要注意的是，_应用名称_ 应谨慎选择，因为它会对所有有权访问管理控制台的用户可见。它应准确反映应用的用途和功能，同时易于理解和识别。 +需要注意的是，_应用名称_ 应该被仔细选择，因为它将对所有有权访问管理控制台的用户可见。它应该准确反映应用的目的和功能，同时也易于理解和识别。 ::: ### 描述 \{#description} -应用的简要描述将显示在管理控制台的应用详情页。描述旨在为管理员提供有关应用的更多信息，如其用途、功能及其他相关细节。 +应用的简要描述将显示在管理控制台的应用详情页面上。描述旨在为管理员提供有关应用的附加信息，例如其目的、功能和任何其他相关细节。 ### 重定向 URI \{#redirect-uris} -_重定向 URI_ 是为应用预先配置的一组有效重定向 URI。当用户登录 Logto 并尝试访问应用时，他们会被重定向到应用设置中指定的允许 URI 之一。 +_重定向 URI_ 是为应用预先配置的一组有效重定向 URI。当用户登录到 Logto 并尝试访问应用时，他们将被重定向到应用设置中指定的允许 URI 之一。 -允许的 URI 列表用于校验应用在认证 (Authentication) 过程中向 Logto 发送的授权请求中包含的重定向 URI。如果授权请求中指定的重定向 URI 与应用设置中的允许 URI 之一匹配，则用户在认证 (Authentication) 成功后会被重定向到该 URI。如果重定向 URI 不在允许列表中，用户将不会被重定向，认证 (Authentication) 流程也会失败。 +允许的 URI 列表用于验证应用在认证 (Authentication) 过程中发送给 Logto 的授权请求中包含的重定向 URI。如果授权请求中指定的重定向 URI 与应用设置中的允许 URI 之一匹配，则用户在成功认证 (Authentication) 后将被重定向到该 URI。如果重定向 URI 不在允许列表中，用户将不会被重定向，认证 (Authentication) 过程将失败。 :::note -务必确保所有有效的重定向 URI 都已添加到 Logto 应用的允许列表中，以确保用户在认证 (Authentication) 后能够成功访问应用。 +确保所有有效的重定向 URI 都被添加到 Logto 中应用的允许列表中，以确保用户在认证 (Authentication) 后能够成功访问应用。 ::: -你可以查阅 [重定向端点](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) 了解更多信息。 +你可以查看 [重定向端点](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) 以获取更多信息。 - 理解 OIDC 授权码流程中的重定向 URI + 理解 OIDC 中的重定向 URI 与授权码流程 #### 通配符模式 \{#wildcard-patterns} -_适用范围：单页应用、传统 Web 应用_ +_适用范围：单页应用，传统 Web 应用_ -重定向 URI 支持通配符模式（`*`），适用于如预览部署等动态环境。通配符可用于 HTTP/HTTPS URI 的主机名和路径名部分。 +重定向 URI 支持通配符模式 (`*`) 以适应动态环境，例如预览部署。通配符可以用于 HTTP / HTTPS URI 的主机名和路径名组件。 **规则：** -- 通配符仅允许出现在主机名和路径名中 -- 通配符不允许出现在协议、端口、查询参数或哈希片段中 -- 主机名通配符必须包含至少一个点（例如 `https://*.example.com/callback`） +- 通配符仅允许在主机名和路径名中使用 +- 通配符不允许在方案、端口、查询参数或哈希片段中使用 +- 主机名通配符必须至少包含一个点（例如，`https://*.example.com/callback`） **示例：** -- `https://*.example.com/callback` - 匹配任意子域名 +- `https://*.example.com/callback` - 匹配任何子域 - `https://preview-*.example.com/callback` - 匹配预览部署 -- `https://example.com/*/callback` - 匹配任意路径段 +- `https://example.com/*/callback` - 匹配任何路径段 :::caution -通配符重定向 URI 并非标准 OIDC，且可能增加攻击面。请谨慎使用，并尽可能优先使用精确的重定向 URI。 +通配符重定向 URI 不是标准 OIDC，可能会增加攻击面。请谨慎使用，并尽可能使用精确的重定向 URI。 ::: -### 注销后重定向 URI \{#post-sign-out-redirect-uris} +### 签出后重定向 URI \{#post-sign-out-redirect-uris} -_注销后重定向 URI_ 是为应用预先配置的一组有效 URI，用于在用户从 Logto 注销后重定向用户。 +_签出后重定向 URI_ 是为应用预先配置的一组有效 URI，用于在用户从 Logto 签出后重定向用户。 -允许的 _注销后重定向 URI_ 用于注销，是 OIDC 中 RP 发起（Relying Party Initiated）注销规范的一部分。该规范为应用发起用户注销请求提供了标准化方法，包括在用户注销后重定向到预先配置的端点。 +使用允许的 _签出后重定向 URI_ 进行注销是 OIDC 中 RP 发起（依赖方发起）注销规范的一部分。此规范提供了一种标准化的方法，允许应用为用户发起注销请求，包括在用户签出后将其重定向到预先配置的端点。 -当用户从 Logto 注销时，其会话被终止，并被重定向到应用设置中指定的允许 URI 之一。这确保用户仅被引导到授权且有效的端点，防止因重定向到未知或未验证端点而导致的未授权访问和安全风险。 +当用户从 Logto 签出时，他们的会话将被终止，并被重定向到应用设置中指定的允许 URI 之一。这确保了用户在签出后仅被引导到授权和有效的端点，有助于防止未经授权的访问和与将用户重定向到未知或未经验证的端点相关的安全风险。 -你可以查阅 [RP 发起注销](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) 了解更多信息。 +你可以查看 [RP 发起的注销](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) 以获取更多信息。 ### CORS 允许的来源 \{#cors-allowed-origins} -_CORS（跨域资源共享）允许的来源_ 是允许应用向 Logto 服务发起请求的来源列表。不在允许列表中的来源将无法向 Logto 服务发起请求。 +_CORS（跨域资源共享）允许的来源_ 是一组允许的来源，应用可以从这些来源向 Logto 服务发出请求。任何不在允许列表中的来源将无法向 Logto 服务发出请求。 -CORS 允许的来源列表用于限制来自未授权域名对 Logto 服务的访问，并有助于防止跨站请求伪造（CSRF）攻击。通过在 Logto 中为应用指定允许的来源，服务可以确保只有被授权的域名能够向服务发起请求。 +CORS 允许的来源列表用于限制未经授权的域对 Logto 服务的访问，并帮助防止跨站请求伪造 (CSRF) 攻击。通过在 Logto 中为应用指定允许的来源，服务可以确保只有授权的域能够向服务发出请求。 :::note -允许的来源列表应包含应用实际部署的来源。这确保来自应用的请求被允许，而来自未授权来源的请求会被阻止。 +允许的来源列表应包含应用将被服务的来源。这确保了来自应用的请求被允许，而来自未经授权来源的请求被阻止。 ::: -### OpenID 提供方配置端点 \{#openid-provider-configuration-endpoint} +### OpenID 提供者配置端点 \{#openid-provider-configuration-endpoint} -[OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) 的端点。 +[OpenID Connect 发现](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest)的端点。 ### 授权端点 \{#authorization-endpoint} -_授权端点_ 是 OIDC 术语，是用于启动用户认证 (Authentication) 流程的必需端点。当用户尝试访问已在 Logto 平台注册的受保护资源或应用时，他们会被重定向到 _授权端点_ 以认证 (Authentication) 身份并获得访问所请求资源的授权 (Authorization)。 +_授权端点_ 是一个 OIDC 术语，它是用于启动用户认证 (Authentication) 过程的必需端点。当用户尝试访问已在 Logto 平台上注册的受保护资源或应用时，他们将被重定向到 _授权端点_ 以认证 (Authentication) 其身份并获得访问请求资源的授权。 -你可以查阅 [授权端点](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) 了解更多信息。 +你可以查看 [授权端点](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) 以获取更多信息。 ### 令牌端点 \{#token-endpoint} -_令牌端点_ 是 OIDC 术语，是 OIDC 客户端用于从 OIDC 提供方获取访问令牌 (Access token)、ID 令牌 (ID token) 或刷新令牌 (Refresh token) 的 Web API 端点。 +_令牌端点_ 是一个 OIDC 术语，它是一个 Web API 端点，OIDC 客户端用于从 OIDC 提供者获取访问令牌、ID 令牌或刷新令牌。 -当 OIDC 客户端需要获取访问令牌 (Access token) 或 ID 令牌 (ID token) 时，会携带授权许可（通常是授权码或刷新令牌 (Refresh token)）向令牌端点发起请求。令牌端点会校验授权许可，如果有效则向客户端签发访问令牌 (Access token) 或 ID 令牌 (ID token)。 +当 OIDC 客户端需要获取访问令牌或 ID 令牌时，它会向令牌端点发送一个包含授权许可的请求，通常是授权码或刷新令牌。令牌端点然后验证授权许可，如果许可有效，则向客户端发放访问令牌或 ID 令牌。 -你可以查阅 [令牌端点](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) 了解更多信息。 +你可以查看 [令牌端点](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) 以获取更多信息。 -### Userinfo 端点 \{#userinfo-endpoint} +### 用户信息端点 \{#userinfo-endpoint} -OpenID Connect [UserInfo 端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 +OpenID Connect [用户信息端点](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 -### 总是签发刷新令牌 (Refresh token) \{#always-issue-refresh-token} +### 始终发放刷新令牌 \{#always-issue-refresh-token} -_适用范围：传统 Web、SPA_ +_适用范围：传统 Web，SPA_ -启用后，无论认证 (Authentication) 请求中是否包含 `prompt=consent`，或权限 (Scope) 中是否包含 `offline_access`，Logto 都会始终签发刷新令牌 (Refresh token)。 +启用后，Logto 将始终发放刷新令牌，无论认证 (Authentication) 请求中是否出现 `prompt=consent`，也无论权限 (Scopes) 中是否出现 `offline_access`。 -但除非必要（通常用于某些需要刷新令牌 (Refresh token) 的第三方 OAuth 集成），否则不建议这样做，因为这与 OpenID Connect 不兼容，且可能带来潜在问题。 +然而，除非必要（通常对某些需要刷新令牌的第三方 OAuth 集成有用），否则不建议这样做，因为这与 OpenID Connect 不兼容，可能会导致问题。 -### 刷新令牌 (Refresh token) 轮换 \{#rotate-refresh-token} +### 刷新令牌轮换 \{#rotate-refresh-token} -_默认值：`true`_ +_默认：`true`_ -启用后，Logto 会在以下情况下为令牌请求签发新的刷新令牌 (Refresh token)： +启用后，Logto 将在以下条件下为令牌请求发放新的刷新令牌： -- 如果刷新令牌 (Refresh token) 已轮换（通过签发新令牌延长其 TTL）一年；**或** -- 如果刷新令牌 (Refresh token) 接近过期时间（原始生存时间 (TTL) 已过去 >=70%）；**或** +- 如果刷新令牌已被轮换（通过发放新令牌延长其 TTL）一年；**或** +- 如果刷新令牌接近其过期时间（>=70% 的原始生存时间 (TTL) 已过）；**或** - 如果客户端是公共客户端，例如原生应用或单页应用 (SPA)。 :::note -对于公共客户端，启用该功能后，每当客户端使用刷新令牌 (Refresh token) 换取新访问令牌 (Access token) 时，都会签发新的刷新令牌 (Refresh token)。 -虽然你仍可以为这些公共客户端关闭该功能，但出于安全考虑，强烈建议保持启用状态。 +对于公共客户端，当启用此功能时，客户端使用刷新令牌交换新访问令牌时将始终发放新刷新令牌。虽然你仍然可以为这些公共客户端关闭此功能，但强烈建议出于安全原因保持启用。 ::: - - 理解刷新令牌 (Refresh token) 轮换 - +理解刷新令牌轮换 -### 刷新令牌 (Refresh token) 生存时间 (TTL)（天）\{#refresh-token-time-to-live-ttl-in-days} +### 刷新令牌生存时间 (TTL)（天）\{#refresh-token-time-to-live-ttl-in-days} -_适用范围：非 SPA；默认值：14 天_ +_适用范围：非 SPA；默认：14 天_ -刷新令牌 (Refresh token) 可用于请求新访问令牌 (Access token) 的有效期，过期后将失效。每次令牌请求会将刷新令牌 (Refresh token) 的 TTL 延长到该值。 +刷新令牌在过期并失效之前可用于请求新访问令牌的持续时间。令牌请求将刷新令牌的 TTL 扩展到此值。 -通常建议设置较低的值。 +通常，较低的值是首选。 -注意：出于安全原因，SPA（单页应用）不支持 TTL 刷新。这意味着 Logto 不会通过令牌请求延长 TTL。为提升用户体验，你可以启用“刷新令牌 (Refresh token) 轮换”功能，让 Logto 在必要时签发新的刷新令牌 (Refresh token)。 +注意：出于安全原因，SPA（单页应用）中不提供 TTL 刷新。这意味着 Logto 不会通过令牌请求来扩展 TTL。为了提升用户体验，你可以启用“刷新令牌轮换”功能，允许 Logto 在必要时发放新刷新令牌。 -:::caution 刷新令牌 (Refresh token) 与会话绑定 -当刷新令牌 (Refresh token) 在授权请求中**未包含** `offline_access` 权限 (Scope) 时，将绑定到用户会话。会话的固定 TTL 为 **14 天**。会话过期后，刷新令牌 (Refresh token) 无论自身 TTL 设置如何都将失效。 +:::caution 刷新令牌和会话绑定 +当在授权请求中**没有**包含 `offline_access` 权限 (Scope) 时发放的刷新令牌将绑定到用户会话。会话的固定 TTL 为 **14 天**。会话过期后，刷新令牌将失效，无论其自身的 TTL 设置如何。 -如需刷新令牌 (Refresh token) TTL 设置完全生效，请确保在授权请求中包含 `offline_access` 权限 (Scope)。 +为了确保刷新令牌 TTL 设置完全生效，请确保在授权请求中包含 `offline_access` 权限 (Scope)。 ::: ### 后端注销 URI \{#backchannel-logout-uri} -OpenID Connect 后端注销端点。详见 [联合注销：后端注销](#)。 +OpenID Connect 后端注销端点。有关更多信息，请参阅 [联合注销：后端注销](#)。 + +### 最大允许授权 (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` 是 `customClientMetadata` 下的一个可选应用级字段，用于控制当前应用每个用户的最大并发活动授权数。 + +- **默认**：`undefined`（无限制） +- **配置时**：在每次成功授权时，Logto 会检查当前应用中用户的总活动授权数（跨浏览器和设备）。如果超过限制，Logto 将撤销最旧的授权。 + +当你想限制每个应用的并发认证 (Authentication) 设备时，此设置非常有用。 + +:::note + +此字段不支持以下应用： + +- 机器对机器应用 +- 受保护应用 +- SAML 应用 + +::: ### 自定义数据 \{#custom-data} -除预定义应用属性外的其他自定义应用信息，用户可根据具体需求自定义数据字段，如业务相关设置和配置。 +未在预定义应用属性中列出的其他自定义应用信息，用户可以根据其具体需求定义自己的自定义数据字段，例如业务特定的设置和配置。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..98fee679481 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,165 @@ +# 会话 + +在 Logto 中，会话定义了如何在应用程序、浏览器和设备之间创建、共享、刷新和撤销认证 (Authentication) 状态。 + +实际上，用户体验到的“已登录”是一种状态，但系统状态被分为多个层次。理解这些层次是设计可预测的单点登录 (SSO)、令牌更新和注销行为的关键。 + +## Logto 中的会话模型 \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto 域"] + S["登录会话"] + G1["授权 (Grant) (应用程序 A)"] + G2["授权 (Grant) (应用程序 B)"] + end + + subgraph AppA ["应用程序域 A"] + A["本地会话 / 令牌"] + end + + subgraph AppB ["应用程序域 B"] + B["本地会话 / 令牌"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto 登录会话**：作为 Logto 域 cookie 存储的集中登录状态。这控制了当前浏览器上下文中的 SSO 可用性。 +- **授权 (Grant)**：特定于应用程序的 `用户 + 客户端应用程序` 授权 (Authorization) 状态。授权 (Grants) 是集中登录和应用程序令牌发放之间的桥梁。 +- **应用程序本地会话/令牌**：每个应用程序中的本地认证 (Authentication) 状态（ID/访问/刷新令牌、应用程序会话 cookie 等）。 + +## 核心概念 \{#core-concepts} + +### 什么是 Logto 会话？\{#what-is-a-logto-session} + +Logto 会话是成功登录后创建的集中认证 (Authentication) 状态。如果它仍然有效，Logto 可以在同一租户中的其他应用程序中静默认证 (Authentication) 用户。如果不存在，用户必须重新登录。 + +### 什么是授权 (Grants)？\{#what-are-grants} + +授权 (Grant) 是与特定用户和客户端应用程序相关联的应用程序级别授权 (Authorization) 状态。 + +- 一个 Logto 会话可以有多个应用程序的授权 (Grants)。 +- 应用程序的令牌是在该应用程序的授权 (Grant) 下发放的。 +- 撤销授权 (Grant) 会影响该应用程序继续基于令牌访问的能力。 + +### 会话、授权 (Grants) 和应用程序认证 (Authentication) 状态之间的关系 \{#how-session-grants-and-app-auth-state-relate} + +- **会话**回答：“这个浏览器现在可以与 Logto 进行 SSO 吗？” +- **授权 (Grant)**回答：“这个用户是否被授权 (Authorization) 使用这个客户端应用程序？” +- **应用程序本地会话**回答：“这个应用程序当前是否将用户视为已登录？” + +## 登录和会话创建 \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as 客户端应用程序 + end + + box Logto + participant OIDC as OIDC 提供商 + participant SignIn as 登录页面 + end + + User ->> Client: 访问应用程序 + Client ->> OIDC: 授权请求 + OIDC -->> OIDC: 检查现有 Logto 会话 + OIDC ->> SignIn: 如有需要，提示登录 + SignIn ->> OIDC: 用户认证 (Authentication) + OIDC -->> OIDC: 创建会话和应用程序授权 (Grant) + OIDC ->> Client: 返回授权代码 + Client ->> OIDC: 用代码交换令牌 + OIDC -->> Client: 返回令牌 +``` + +## 跨应用程序和设备的会话拓扑 \{#session-topology-across-apps-and-devices} + +### 同一浏览器：共享 Logto 会话 \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[用户] + A["客户端应用程序 A"] + B["客户端应用程序 B"] + C{"Logto 会话存在吗？"} + D["Logto 登录页面"] + + U --> A + A --> C + U --> B + B --> C + C -->|否| D +``` + +同一浏览器中的应用程序可以共享集中 Logto 会话状态，因此 SSO 可以在不重复输入凭据的情况下发生。 + +### 不同浏览器或设备：隔离的 Logto 会话 \{#different-browsers-or-devices-isolated-logto-sessions} + +每个浏览器/设备都有单独的 cookie 存储。设备 A 上的有效会话并不意味着设备 B 上也有有效会话。 + +## 会话生命周期 \{#session-lifecycle} + +### 1. 创建 \{#1-create} + +用户认证 (Authentication) 后，Logto 创建一个集中会话和一个应用程序特定的授权 (Grant)。 + +### 2. 重用 (SSO) \{#2-reuse-sso} + +只要会话 cookie 在同一浏览器中有效，新授权请求通常可以静默完成。 + +### 3. 更新令牌 \{#3-renew-tokens} + +应用程序访问通常通过令牌刷新流程（如果启用）继续。这是应用程序级别的连续性，与集中 Logto 会话是否仍然存在无关。 + +### 4. 撤销/过期 \{#4-revokeexpire} + +撤销可以在不同层次发生： + +- 本地应用程序注销会移除应用程序本地令牌/会话。 +- 结束会话会移除集中 Logto 会话。 +- 授权 (Grant) 撤销会移除应用程序级别的授权 (Authorization) 连续性。 + +## 设计建议 \{#design-recommendations} + +- 在你的应用程序代码中明确处理应用程序本地会话。 +- 将 Logto 会话、授权 (Grants) 和应用程序本地会话视为独立的层次。 +- 选择注销是仅限于应用程序本地还是全局。 +- 当需要多应用程序一致性时，使用 [后端通道注销](/end-user-flows/sign-out#federated-sign-out-back-channel-logout)。 +- 有关注销行为和实现细节，请参见 [注销](/end-user-flows/sign-out)。 + +## 撤销访问的最佳实践 \{#best-practices-for-revoking-access} + +根据你的目标使用不同的撤销策略： + +- **撤销对你的第一方应用程序的访问**： + 使用 `revokeGrantsTarget=firstParty` 撤销目标会话。这会使用户在与该会话关联的第一方应用程序中注销，从而创建一致的注销体验。同时，授予 `offline_access` 的第三方应用程序的授权 (Grants) 可以继续用于持续集成。有关会话撤销的详细信息，请参见 [管理用户会话](/sessions/manage-user-sessions)。 + +- **撤销对第三方应用程序的访问**： + 选择以下之一： + + - 使用 `revokeGrantsTarget=all` 撤销会话，以撤销与该会话关联的所有授权 (Grants)。 + - 通过授权 (Grant) 管理 API 直接撤销特定授权 (Grants)，以移除第三方应用程序授权 (Authorization)，而不强制完全会话注销。 + 有关授权 (Grant) 特定撤销策略，请参见 [管理用户授权应用程序 (Grants)](/sessions/grants-management)。 + +- **使用 Logto 控制台时**： + 在用户详细信息页面，Logto 提供了开箱即用的会话管理和授权第三方应用程序管理。 + - 撤销会话也会撤销第一方应用程序授权 (Grants)，以保持第一方注销行为一致。 + - 撤销第三方应用程序授权 (Authorization) 会撤销该第三方应用程序的授权 (Grants)，同时保持原始会话状态不变。 + +## 相关资源 \{#related-resources} + +管理用户会话 +管理用户授权应用程序 (Grants) +会话配置 +注销 +注册和登录 + + 理解认证 (Authentication) 流程 + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..2643f8725a5 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# 管理用户授权的应用程序（授权） + +应用程序授权表示用户对特定客户端应用程序的授权状态。 + +当用户或管理员需要查看已授权的应用程序并撤销应用程序访问而不撤销整个 Logto 会话时，可以使用授权管理。 + +当授权被撤销时，之前为这些授权颁发的不透明访问令牌和刷新令牌将失效。 + +## 选择正确的路径 \{#choose-the-right-path} + +| 场景 | 推荐路径 | +| -------------------------------------- | -------------- | +| 让已登录用户管理自己的应用程序授权 | Account API | +| 让管理员或支持团队为目标用户管理授权 | Management API | +| 让操作员在 UI 中管理第三方应用程序授权 | Admin Console | + +## 直接授权管理 API \{#direct-grant-management-apis} + +### Account API（自助服务）\{#account-api-self-service} + +在终端用户账户设置页面中使用 Account API： + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- 参考：[管理用户授权的应用程序（授权）](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API（管理工具）\{#management-api-admin-tools} + +在管理工具和支持工作流中使用 Management API： + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- 参考：[管理用户授权的应用程序（授权）](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### 按应用程序类型筛选授权列表 \{#filter-grant-list-by-app-type} + +授权列表端点支持可选查询参数 `appType`： + +- `appType=firstParty`：仅列出第一方应用程序授权。 +- `appType=thirdParty`：仅列出第三方应用程序授权。 +- 省略 `appType`：返回所有活动授权。 + +## 在控制台中管理第三方应用程序授权 \{#manage-third-party-app-authorizations-in-console} + +在 Logto 控制台中，使用用户详细信息页面查看和撤销已授权的第三方应用程序。 + +- 参考：[管理用户授权的第三方应用程序](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## 撤销会话时撤销授权 \{#revoke-grants-when-revoking-a-session} + +通过 `DELETE /api/my-account/sessions/{sessionId}` 撤销会话时，使用可选查询参数 `revokeGrantsTarget` 控制授权撤销范围： + +- `all`：撤销与会话关联的所有应用程序的授权。 +- `firstParty`：仅撤销第一方应用程序的授权。 + +有关会话级别行为和端点上下文，请参阅 [管理用户会话](/sessions/manage-user-sessions) 和 [注销](/end-user-flows/sign-out)。 + +## 相关资源 \{#related-resources} + +Sessions +管理用户会话 + + 通过 Account API 进行账户设置：管理用户授权的应用程序（授权） + + + 通过 Management API 进行账户设置：管理用户授权的应用程序（授权） + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..ebcecacfc1b --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# 管理用户会话 + +用户会话管理帮助用户和管理员查看活动登录状态，并在需要时撤销会话。 + +在 Logto 中，你可以通过三种常见路径管理会话： + +- **Account API**：用于产品账户设置页面中的终端用户自助服务。 +- **Management API**：用于管理员或支持工具管理任何用户的会话。 +- **Admin Console**：用于在 Logto 控制台中进行操作员工作流，而无需构建自定义工具。 + +## 选择合适的 API \{#choose-the-right-api} + +| 场景 | 推荐的 API | +| ------------------------------------- | -------------- | +| 让已登录用户管理自己的活动会话 | Account API | +| 让管理员或支持团队管理用户的会话 | Management API | +| 让操作员直接在 Logto 控制台中管理会话 | Admin Console | + +## 查看活动会话 \{#view-active-sessions} + +### Account API（自助服务）\{#account-api-self-service} + +使用 Account API 会话端点列出当前用户的活动会话。 + +- 参考部分：[管理用户会话](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 端点：[`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +在向终端用户公开此功能之前，请确保在 Account center 设置中启用了会话管理，并且你的应用请求了所需的 Account API 权限。 + +### Management API（管理工具）\{#management-api-admin-tools} + +当你的管理系统需要列出目标用户的会话时，使用 Management API。 + +- 参考部分：[用户会话管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- 端点：[`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- 可选详细信息端点：[`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## 撤销会话 \{#revoke-sessions} + +### Account API（终端用户撤销自己的会话）\{#account-api-end-user-revokes-own-sessions} + +终端用户可以从自己的会话列表中撤销特定会话。 + +- 参考部分：[管理用户会话](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 端点：[`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +对于敏感操作，Account API 会话管理需要用户验证后才能访问。请参阅 [获取验证记录 ID](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id)。 + +### Management API（管理员撤销用户会话）\{#management-api-admin-revokes-user-sessions} + +管理员可以通过用户 ID 和会话 ID 撤销目标用户的会话。 + +- 参考部分：[用户会话管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- 端点：[`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +如果你的团队直接在 Logto 控制台中管理用户，你可以查看活动会话并从用户详细信息页面撤销特定会话。 + +- 参考部分：[管理用户活动会话](/user-management/manage-users#manage-user-active-sessions) + +## 相关资源 \{#related-resources} + +会话 +管理用户授权的应用程序（授权） + + Account API 的账户设置：管理用户会话 + + + Management API 的账户设置：用户会话管理 + + + 用户管理：管理用户活动会话 + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..b28bb7b5a3f --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# 会话配置 + +会话配置定义了租户级别的控制，用于确定 Logto 登录会话的有效时长以及如何执行与会话相关的访问策略。 + +本页内容包括： + +- 会话 TTL 配置 +- 每个应用的最大并发认证设备数 + +## 会话 TTL 配置 \{#session-ttl-configuration} + +会话 TTL 决定了 Logto OIDC 登录会话的最长生命周期。 +这是一个**租户级别的设置**：一旦配置，它将适用于该租户中的所有应用和认证 (Authentication) 流程。 + +### 默认行为 \{#default-behavior} + +- 默认情况下，会话 TTL 为 **14 天**。 +- 如果没有配置自定义 TTL，Logto 将继续使用此默认值。 + +### 通过 Logto Console 配置 \{#configure-concurrent-device-limit-via-logto-console} + +你可以在 Console 中配置会话 TTL，路径为： + +Console > Tenant > Settings > OIDC settings + +使用 **Session maximum time to live** 来更新该值。 + +:::note + +Console 使用**天**作为输入和显示单位，而底层的 OIDC 会话配置 / API 使用**秒**。 + +::: + +### 通过 Management API 配置 \{#configure-via-management-api} + +使用以下端点读取和更新 OIDC 会话配置： + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +示例（`ttl` 以秒为单位）： + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` 秒 = 14 天。 + +:::note + +对于 OSS 部署，在更改 `logto-config` 后重启服务实例，以便服务器可以获取最新的 OIDC 设置。 + +要在不重启服务的情况下自动应用 OIDC 配置更新，请[启用中央 redis 缓存](/logto-oss/central-cache)。 + +::: + +## 每个应用的最大并发认证设备数 \{#max-concurrent-authenticated-devices-per-app} + +每个应用的最大并发认证设备数是一个应用级别的控制，用于限制每个用户可以为特定应用保持的活动授权数量。 + +这是通过应用程序 `customClientMetadata` 中的 `maxAllowedGrants` 字段配置的。 +在 [应用程序数据结构](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants) 中了解更多。 + +### 行为 \{#behavior} + +当设置了 `maxAllowedGrants` 时，Logto 会在每次成功授权时评估用户当前应用的活动授权。 +如果活动授权数量超过限制，Logto 会优先撤销最早的授权。 + +如果未设置 `maxAllowedGrants`，则没有并发限制。 + +### 通过 Logto Console 配置 \{#configure-via-logto-console} + +你可以在每个应用的详细信息页面下配置此项，路径为： + + + Console > Applications > Application details > Concurrent device limit + + +为当前应用设置每个用户的最大并发活动授权（设备）数量。 + +:::note + +此设置不支持机器对机器应用、受保护应用和 SAML 应用。 + +::: + +## 相关资源 \{#related-resources} + +会话 +管理用户会话 +管理用户授权应用（授权） + + 应用程序数据结构：maxAllowedGrants + +与 Management API 交互 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index 9107c81a88c..d8287aee976 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -8,129 +8,144 @@ sidebar_position: 2 ### 浏览和搜索用户 \{#browse-and-search-users} -要在 Logto 控制台访问用户管理功能，请导航至 控制台 > 用户管理。进入后，你将看到所有用户的表格视图。 +要访问 Logto 控制台中的用户管理功能，请导航到 控制台 > 用户管理。进入后，你将看到所有用户的表格视图。 -该表格包含三列： +该表格由三列组成： -- **用户**：显示用户的信息，如头像、全名、用户名、手机号和邮箱 -- **来自应用**：显示用户最初注册时使用的应用名称 +- **用户**：显示有关用户的信息，例如他们的头像、全名、用户名、电话号码和电子邮件 +- **来自应用程序**：显示用户最初注册的应用程序名称 - **最近登录**：显示用户最近一次登录的时间戳。 -支持对 [`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) 进行关键词映射搜索。 +它支持 [`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) 的关键字映射。 ### 添加用户 \{#add-users} -通过控制台，开发者可以为终端用户创建新账号。只需点击屏幕右上角的“添加用户”按钮即可。 +使用控制台，开发者可以为终端用户创建新账户。为此，请点击屏幕右上角的“添加用户”按钮。 -在 Logto 控制台或通过 Management API 创建用户时（不是终端用户通过 UI 自助注册），你必须至少提供一个标识符：`primary email`、`primary phone` 或 `username`。`name` 字段为可选项。 +在 Logto 控制台中或通过 Management API 创建用户时（不是通过 UI 自注册的终端用户），你必须至少提供一个标识符：`primary email`、`primary phone` 或 `username`。`name` 字段是可选的。 -用户创建后，Logto 会自动生成一个随机密码。初始密码只会显示一次，但你可以[重置密码](./manage-users#reset-user-password)。如果你想设置特定密码，请在用户创建后使用 Management API 的 `patch /api/users/{userId}/password` 进行更新。 +用户创建后，Logto 将自动生成一个随机密码。初始密码只会出现一次，但你可以稍后[重置密码](./manage-users#reset-user-password)。如果你想设置一个特定的密码，可以在用户创建后使用 Management API `patch /api/users/{userId}/password` 进行更新。 -你可以一键复制**输入的标识符（邮箱地址 / 手机号 / 用户名）**和**初始密码**，方便将这些凭证分享给新用户，让他们可以登录并开始使用。 +你可以一键复制**输入的标识符（电子邮件地址 / 电话号码 / 用户名）**和**初始密码**，方便地将这些凭据分享给新用户，以便他们登录并开始使用。 :::tip -如果你想实现仅限邀请注册，推荐使用[魔法链接邀请用户](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)。这样只有白名单用户可以自助注册并设置自己的密码。 +如果你想实现仅限邀请的注册，我们建议[使用魔法链接邀请用户](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)。这允许只有白名单用户可以自注册并设置自己的密码。 ::: ### 查看和更新用户资料 \{#view-and-update-the-user-profile} -要查看用户详情，只需点击用户表格中的对应行。你将进入“**用户详情**”页面，可以查看用户的资料信息，包括： +要查看用户的详细信息，只需点击用户表中的相应行。这将带你进入“**用户详情**”页面，在这里你可以找到用户的资料信息，包括： - **认证 (Authentication) 相关数据**： - - **邮箱地址**（[primary_email](/user-management/user-data#primary_email)）：可编辑 - - **手机号**（[primary_phone](/user-management/user-data#primary_phone)）：可编辑 - - **用户名**（[username](/user-management/user-data#username)）：可编辑 - - **密码**（[has_password](/user-management/user-data#has_password)）：可以重新生成随机密码。了解更多“[重置用户密码](#reset-user-password)”。 - - **多因素认证 (MFA)**（[mfa_verification_factor](/user-management/user-data#mfa_verification_factors)）：查看该用户已设置的所有认证因子（如通行密钥、认证器应用、备份码）。可以在控制台移除因子。 - - **通行密钥**：当租户启用[通行密钥登录](/end-user-flows/sign-up-and-sign-in/passkey-sign-in)后，你也可以在用户详情页查看和移除用户的登录通行密钥。这些通行密钥与 MFA 使用相同的 WebAuthn 凭证模型。 + - **电子邮件地址** ([primary_email](/user-management/user-data#primary_email))：可编辑 + - **电话号码** ([primary_phone](/user-management/user-data#primary_phone))：可编辑 + - **用户名** ([username](/user-management/user-data#username))：可编辑 + - **密码** ([has_password](/user-management/user-data#has_password))：你可以重新生成一个随机密码。了解更多关于“[重置用户密码](#reset-user-password)”的信息。 + - **多因素认证 (MFA)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors))：查看用户已设置的所有认证 (Authentication) 因素（例如，通行密钥、认证器应用、备份代码）。可以在控制台中移除因素。 + - **通行密钥**：当租户中启用[通行密钥登录](/end-user-flows/sign-up-and-sign-in/passkey-sign-in)时，你还可以在用户详情页面查看用户的登录通行密钥，并在需要时移除它们。这些通行密钥由 MFA 使用的相同 WebAuthn 凭证模型支持。 - **个人访问令牌**：创建、查看、重命名和删除[个人访问令牌](/user-management/personal-access-token)。 - **连接**： - - **社交连接**（[identities](/user-management/user-data#social-identities)）： - - 查看用户已绑定的社交账号，包括社交 ID 及从社交提供方同步的资料详情（如用户通过 Facebook 登录，则会显示“Facebook”条目）。 - - 你可以移除已有的社交身份，但不能代用户绑定新的社交账号。 - - 对于启用[token 存储](/secret-vault/federated-token-set)的社交连接器，可以在连接详情页查看和管理访问令牌 (access tokens) 和刷新令牌 (refresh tokens)。 - - **企业单点登录 (SSO) 连接**（[sso_identities](/user-management/user-data#sso-identities)）： - - 查看用户已绑定的企业身份，包括企业 ID 及从企业身份提供方同步的资料详情。 - - 你无法在控制台添加或移除企业 SSO 身份。 - - 对于基于 OIDC 的企业连接器，若启用[token 存储](/secret-vault/federated-token-set)，可在连接详情页查看和删除令牌。 -- **用户资料数据**：姓名、头像 URL、自定义数据，以及未包含的其他 OpenID Connect 标准声明。这些资料字段均可编辑。 -- **会话**：查看用户的活跃会话列表，包括设备信息、sessionId 和地理位置（如适用）。可查看更多会话详情，并在会话详情页撤销该会话。 + - **社交连接** ([identities](/user-management/user-data#social-identities))： + - 查看用户关联的社交账户，包括从其社交提供商同步的社交 ID 和资料详情（例如，如果用户通过 Facebook 登录，将出现一个“Facebook”条目）。 + - 你可以移除现有的社交身份，但不能代表用户关联新的社交账户。 + - 对于启用了[令牌存储](/secret-vault/federated-token-set)的社交连接器，你可以在连接详情页面查看和管理访问令牌和刷新令牌。 + - **企业 SSO 连接** ([sso_identities](/user-management/user-data#sso-identities))： + - 查看用户关联的企业身份，包括从其企业身份提供商同步的企业 ID 和资料详情。 + - 你不能在控制台中添加或移除企业 SSO 身份。 + - 对于基于 OIDC 的企业连接器，启用了[令牌存储](/secret-vault/federated-token-set)的，你可以在连接详情页面查看和删除令牌。 +- **用户资料数据**：姓名、头像 URL、自定义数据和未包含的其他 OpenID Connect 标准声明。所有这些资料字段都是可编辑的。 +- **会话**：查看用户活动会话列表，包括设备信息 sessionId 和地理位置（如果适用）。在会话详情页面查看更多会话详情并撤销它。 :::warning -在移除社交连接前，请务必确认用户还有其他登录方式，如其他社交连接、手机号、邮箱或用户名加密码。否则用户将无法再次访问其账号。 +在移除社交连接之前，确认用户有其他登录方法非常重要，例如另一个社交连接、电话号码、电子邮件或用户名和密码。如果用户没有其他登录方法，一旦社交连接被移除，他们将无法再次访问其账户。 ::: ### 查看用户活动 \{#view-user-activities} -要查看用户的近期活动，请在“用户详情”页切换到“用户日志”子标签。这里有一张表格，显示用户的近期操作，包括执行的动作、结果、相关应用及操作时间。 +要查看用户的最近活动，请导航到“用户详情”页面的“用户日志”子选项卡。在这里，你可以找到一个表格，显示用户的最近活动，包括执行的操作、操作结果、相关应用程序以及用户执行操作的时间。 -点击表格行可查看更多日志详情，如 IP 地址、用户代理、原始数据等。 +点击表格行以在用户日志中查看更多详细信息，例如 IP 地址、用户代理、原始数据等。 -### 挂起用户 \{#suspend-user} +### 暂停用户 \{#suspend-user} -在“用户详情”页，点击“三点”->“挂起用户”按钮。 +在“用户详情”页面，点击“三点” -> “暂停用户”按钮。 -用户被挂起后，将无法登录你的应用，也无法在当前访问令牌过期后获取新的访问令牌。此外，该用户发起的任何 API 请求都会失败。 +一旦用户被暂停，该用户将无法登录你的应用程序，并且在当前访问令牌过期后无法获取新的访问令牌。此外，该用户发出的任何 API 请求都将失败。 -如需恢复该用户，只需点击“三点”->“恢复用户”按钮。 +如果你想重新激活此用户，可以通过点击“三点” -> “重新激活用户”按钮来实现。 ### 删除用户 \{#delete-user} -在“用户详情”页，点击“三点”->“删除”按钮。删除用户操作不可撤销。 +在“用户详情”页面，点击“三点” -> “删除”按钮。删除用户无法撤销。 ### 重置用户密码 \{#reset-user-password} -在“用户详情”页，点击“三点”->“重置密码”按钮，Logto 会自动重新生成一个随机密码。 +在“用户详情”页面，点击“三点” -> “重置密码”按钮，然后 Logto 将自动重新生成一个随机密码。 -重置密码后，请复制并发送给终端用户。关闭“重置密码”弹窗后将无法再次查看密码。如忘记保存，可再次重置。 +重置密码后，复制并发送给终端用户。一旦“重置密码”模态关闭，你将无法再查看密码。如果忘记保存，可以再次重置。 -你无法在 Logto 控制台为用户设置特定密码，但可以使用 [Management API](/integrate-logto/interact-with-management-api) 的 `PATCH /api/users/{userId}/password` 指定密码。 +你不能在 Logto 控制台中为用户设置特定密码，但可以使用 [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` 来指定密码。 -### 管理用户活跃会话 \{#manage-user-active-sessions} +### 管理用户活动会话 \{#manage-user-active-sessions} -在“用户详情”页，点击某个会话的“管理”按钮进入“会话详情”页。你可以查看该会话的详细信息，如设备、位置和登录时间。如需让用户退出该会话，只需点击右上角的“撤销会话”按钮，会话将立即失效。 +在“用户详情”页面，通过点击特定会话的“管理”按钮导航到“会话详情”页面。在这里，你可以查看有关会话的详细信息，例如设备、位置和登录时间。如果你想让用户退出此会话，只需点击右上角的“撤销会话”按钮，会话将立即被撤销。 -- 默认情况下，在控制台撤销会话也会撤销与该会话关联的所有一方应用授权，用户需重新登录以恢复访问。所有已发放给一方应用的不透明访问令牌 (opaque access tokens) 和刷新令牌 (refresh tokens) 也会立即失效。 -- 对于带有 `offline_access` 权限的三方应用，撤销会话默认不会撤销应用授权，已发放的刷新令牌可继续使用，直到授权过期。 +- 默认情况下，在控制台中撤销会话也将撤销与该会话相关的所有第一方应用程序授权，用户需要重新登录以恢复访问。任何预先发放给第一方应用程序的不透明访问令牌和刷新令牌也将立即被撤销。 +- 对于具有 `offline_access` 权限的第三方应用程序，撤销会话默认不会撤销应用程序授权，任何预先发放的刷新令牌仍可使用，直到授权过期。 + +### 管理用户授权的第三方应用程序 \{#manage-user-authorized-third-party-apps} + +在“用户详情”页面，你可以使用“授权的第三方应用程序”部分查看用户的应用程序授权状态。 +此部分由用户授权应用程序（授权）管理 API 支持。 + +对于每个授权的应用程序，控制台显示： + +- 应用程序名称 +- 应用程序 ID +- 访问创建时间 + +如果需要移除访问权限，请点击撤销操作并在模态中确认。 + +撤销应用程序授权将移除与该应用程序相关的所有活动第三方授权，并立即撤销该应用程序的任何预先发放的不透明访问令牌和刷新令牌。 ## 密码合规性检查 \{#password-compliance-check} -在你更新 Logto 的[密码策略](/security/password-policy)后，现有用户仍可使用当前密码登录。只有新创建的账号才需遵循更新后的密码策略。 +在 Logto 中更新[密码策略](/security/password-policy)后，现有用户仍可以使用其当前密码登录。只有新创建的账户才需要遵循更新后的密码策略。 -为加强安全性，你可以使用 `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) 检查用户密码是否符合默认登录体验下的当前策略。如不符合，可通过自定义流程结合 [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) 提示用户更新密码。 +为了加强安全性，你可以使用 `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) 检查用户的密码是否符合默认登录体验中定义的当前策略。如果不符合，你可以使用 [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) 提示用户通过自定义流程更新其密码。 -### 管理用户角色 \{#manage-roles-of-users} +### 管理用户的角色 \{#manage-roles-of-users} -在用户详情页的“角色”标签下，你可以轻松分配或移除角色以满足需求。详情见[基于角色的访问控制 (RBAC)](/authorization/role-based-access-control)。 +在用户详情页面的“角色”选项卡中，你可以轻松分配或移除角色以实现所需的结果。查看[基于角色的访问控制 (RBAC)](/authorization/role-based-access-control)以获取详细信息。 -### 查看用户所属组织 \{#view-the-organizations-the-user-belongs-to} +### 查看用户所属的组织 \{#view-the-organizations-the-user-belongs-to} -Logto 支持[组织 (Organizations)](/organizations/organization-management)并可管理其成员。你可以轻松查看用户详情及其所属组织。 +Logto 支持[组织 (Organizations)](/organizations/organization-management)并可以管理其成员。你可以轻松查看用户详情并查看他们所属的组织。 ## 通过 Logto Management API 管理 \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) 是一组用于访问 Logto 后端服务的 API。如前所述，用户 API 是该服务的重要组成部分，可支持多种场景。 +[Management API](/concepts/core-service/#management-api) 是一组提供对 Logto 后端服务访问的 API。如前所述，用户 API 是此服务的关键组件，可以支持广泛的场景。 -与用户相关的 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API 挂载在 `/api/users`，用户活动（即用户日志）除外，日志接口为 `/api/logs?userId=:userId`。 +与用户相关的 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API 挂载在 `/api/users`，除了用户活动，即用户日志 `/api/logs?userId=:userId`。 -你可以在多种场景下通过 Management API 管理用户，如[高级用户搜索](/user-management/advanced-user-search)、[批量创建账号](https://openapi.logto.io/operation/operation-createuser)、[仅限邀请注册](/end-user-flows/sign-up-and-sign-in/disable-user-registration)等。 +你可以在多个用例中通过 Management API 管理用户。例如[高级用户搜索](/user-management/advanced-user-search)、[批量创建账户](https://openapi.logto.io/operation/operation-createuser)、[仅限邀请注册](/end-user-flows/sign-up-and-sign-in/disable-user-registration)等。 -## 常见问题 \{#faqs} +## 常见问题解答 \{#faqs}
-### 如何限制特定用户访问某些应用？ \{#how-to-restrict-access-to-certain-application-for-specific-users} +### 如何限制特定用户对某些应用程序的访问？ \{#how-to-restrict-access-to-certain-application-for-specific-users} -由于 Logto 的 [Omni-sign-in](https://logto.io/products/omni-sign-in) 特性，设计上并不支持在认证 (Authentication) 前限制用户访问某些应用。 -但你仍然可以为应用设计特定的用户角色和权限来保护你的 API 资源，并在用户成功登录后在 API 访问时校验权限。 -详见授权 (Authorization)：[基于角色的访问控制 (RBAC)](/authorization/role-based-access-control)。 +由于 Logto 的 [Omni-sign-in](https://logto.io/products/omni-sign-in) 特性，它并不设计用于在认证 (Authentication) 之前限制用户对某些应用程序的访问。 +然而，你仍然可以设计特定于应用程序的用户角色和权限来保护你的 API 资源，并在用户成功登录后验证 API 访问权限。 +有关更多信息，请参阅授权 (Authorization)：[基于角色的访问控制 (RBAC)](/authorization/role-based-access-control)。
diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 13515424f9e..0a81096863f 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -1,55 +1,55 @@ --- id: signing-keys -title: 簽章金鑰 (Signing keys) -sidebar_label: 簽章金鑰 (Signing keys) +title: 簽署金鑰 +sidebar_label: 簽署金鑰 sidebar_position: 5 --- -# 簽章金鑰 (Signing keys) +# 簽署金鑰 -Logto [OIDC 簽章金鑰](https://auth.wiki/signing-key)（又稱「OIDC 私鑰」與「OIDC Cookie 金鑰」），是用於簽署 JWT（[存取權杖 (Access tokens)](https://auth.wiki/access-token) 與 [ID 權杖 (ID tokens)](https://auth.wiki/id-token)）以及 Logto [登入階段 (Sign-in sessions)](/end-user-flows/sign-out#what-is-a-logto-session) 中的瀏覽器 Cookie 的簽章金鑰。這些簽章金鑰會在初始化 Logto 資料庫（[開源版](/logto-oss)）或建立新租戶（[雲端版](/logto-cloud)）時產生，並可透過 [CLI](/logto-oss/using-cli)（開源版）、Management API 或 Console UI 進行管理。 +Logto 的 [OIDC 簽署金鑰](https://auth.wiki/signing-key)，也稱為「OIDC 私密金鑰」和「OIDC cookie 金鑰」，是用於簽署 JWT（[存取權杖 (Access tokens)](https://auth.wiki/access-token) 和 [ID 權杖 (ID tokens)](https://auth.wiki/id-token)）以及 Logto [登入會話](/sessions#what-is-a-logto-session)中的瀏覽器 cookie 的簽署金鑰。這些簽署金鑰在初始化 Logto 資料庫時（[開源](/logto-oss)）或創建新租戶時（[Cloud](/logto-cloud)）生成，並可透過 [CLI](/logto-oss/using-cli)（開源）、Management API 或 Console UI 進行管理。 -預設情況下，Logto 使用橢圓曲線（EC）演算法產生數位簽章。然而，考量到使用者常需驗證 JWT 簽章，且許多舊有工具不支援 EC 演算法（僅支援 RSA），我們實作了私鑰輪替功能，並允許使用者選擇簽章演算法（包含 RSA 與 EC）。這確保了與使用舊版簽章驗證工具的服務相容。 +預設情況下，Logto 使用橢圓曲線（EC）算法生成數位簽章。然而，考慮到使用者經常需要驗證 JWT 簽章，且許多舊工具不支援 EC 算法（僅支援 RSA），我們實現了旋轉私密金鑰的功能，並允許使用者選擇簽章算法（包括 RSA 和 EC）。這確保了與使用過時簽章驗證工具的服務的相容性。 :::note -理論上，簽章金鑰不應外洩且無過期時間，意即無需輪替。但定期在一段時間後輪替簽章金鑰可提升安全性。 +理論上，簽署金鑰不應洩露且沒有過期時間，這意味著不需要旋轉它們。然而，定期在一定時間後旋轉簽署金鑰可以增強安全性。 ::: ## 運作原理 \{#how-it-works} -- **OIDC 私鑰 (OIDC private key)** - 當初始化 Logto 實例時，會自動產生一對公鑰與私鑰，並註冊於底層 OIDC 提供者。當 Logto 發行新的 JWT（存取權杖或 ID 權杖）時，會以私鑰簽署該權杖。此時，任何收到 JWT 的用戶端應用程式都可使用對應的公鑰驗證權杖簽章，以確保權杖未被第三方竄改。私鑰會在 Logto 伺服器上受到保護，而公鑰則如其名，對所有人公開，可透過 OIDC 端點的 `/oidc/jwks` 介面存取。產生私鑰時可指定簽章金鑰演算法，Logto 預設使用 EC（橢圓曲線）演算法。管理員可透過輪替私鑰將預設演算法改為 RSA（Rivest-Shamir-Adleman）。 -- **OIDC Cookie 金鑰 (OIDC cookie key)** - 當使用者啟動登入或註冊流程時，伺服器會建立一個「OIDC 階段 (Session)」以及一組瀏覽器 Cookie。藉由這些 Cookie，瀏覽器可向 Logto 使用體驗 (Experience) API 發送請求，代表使用者執行一系列互動，例如登入、註冊與重設密碼。然而，與 JWT 不同，Cookie 僅由 Logto OIDC 服務本身簽署與驗證，無需非對稱加密。因此，Cookie 簽章金鑰沒有對應的公鑰，也不採用非對稱加密演算法。 +- **OIDC 私密金鑰** + 當初始化 Logto 實例時，會自動生成一對公鑰和私密金鑰，並在底層 OIDC 提供者中註冊。因此，當 Logto 發行新的 JWT（存取權杖或 ID 權杖）時，權杖會使用私密金鑰簽署。同時，任何接收到 JWT 的客戶端應用程式都可以使用配對的公鑰驗證權杖簽章，以確保權杖未被第三方篡改。私密金鑰在 Logto 伺服器上受到保護。然而，正如名稱所示，公鑰是公開的，可以透過 OIDC 端點的 `/oidc/jwks` 介面訪問。生成私密金鑰時可以指定簽署金鑰算法，Logto 預設使用 EC（橢圓曲線）算法。管理員使用者可以透過旋轉私密金鑰將預設算法更改為 RSA（Rivest-Shamir-Adleman）。 +- **OIDC cookie 金鑰** + 當使用者啟動登入或註冊流程時，伺服器上會創建一個「OIDC 會話」，以及一組瀏覽器 cookie。透過這些 cookie，瀏覽器可以請求 Logto Experience API 代表使用者執行一系列互動，例如登入、註冊和重設密碼。然而，與 JWT 不同，cookie 僅由 Logto OIDC 服務本身簽署和驗證，不需要非對稱加密措施。因此，我們沒有 cookie 簽署金鑰的配對公鑰，也沒有非對稱加密算法。 -## 透過 Console UI 輪替簽章金鑰 \{#rotate-signing-keys-from-console-ui} +## 從 Console UI 旋轉簽署金鑰 \{#rotate-signing-keys-from-console-ui} -Logto 提供「簽章金鑰輪替」功能，讓你能在租戶中建立新的 OIDC 私鑰與 Cookie 金鑰。 +Logto 引入了「簽署金鑰旋轉」功能，允許你在租戶中創建新的 OIDC 私密金鑰和 cookie 金鑰。 -1. 前往 Console > 簽章金鑰 (Signing keys)，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。 +1. 前往 控制台 > 租戶設定 > OIDC 設定，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。 2. 若要輪替簽章金鑰，請點擊「輪替私鑰 (Rotate private keys)」或「輪替 Cookie 金鑰 (Rotate cookie keys)」按鈕。輪替私鑰時，你可選擇更換簽章演算法。 3. 你會看到一個表格，列出所有正在使用的簽章金鑰。注意：你可以刪除「前一組」金鑰，但無法刪除「目前」金鑰。 - | 狀態 | 說明 | - | ----------------- | ---------------------------------------------------------------- | - | 目前 (Current) | 表示此金鑰目前正用於你的應用程式與 API。 | - | 前一組 (Previous) | 指的是先前使用但已被輪替的金鑰。以此金鑰簽署的現有權杖仍然有效。 | + | 狀態 | 描述 | + | ---- | -------------------------------------------------------------------- | + | 當前 | 表示此金鑰目前在你的應用程式和 API 中處於活動使用中。 | + | 先前 | 指的是先前使用過但已被旋轉的金鑰。使用此簽署金鑰的現有權杖仍然有效。 | -請記得，輪替包含以下三個動作： +請記住，旋轉涉及以下三個動作： -1. **建立新簽章金鑰**：這將要求所有 **應用程式** 與 **API** 採用新簽章金鑰。 -2. **輪替目前金鑰**：輪替後，現有金鑰會標記為「前一組」，不再用於新建立的應用程式與 API。但以此金鑰簽署的權杖仍然有效。 -3. **移除前一組金鑰**：標記為「前一組」的金鑰將被撤銷並從表格中移除。 +1. **創建新簽署金鑰**：這將要求所有你的 **應用程式** 和 **API** 採用新的簽署金鑰。 +2. **旋轉當前金鑰**：現有金鑰在旋轉後將被指定為「先前」，不會被新創建的應用程式和 API 使用。然而，使用此金鑰簽署的權杖仍然有效。 +3. **移除先前的金鑰**：標記為「先前」的金鑰將被撤銷並從表格中移除。 :::warning -切勿連續（兩次或以上）輪替簽章金鑰，否則可能導致所有已發行權杖失效。 +切勿連續旋轉簽署金鑰（兩次或更多次），因為這可能會使所有已發行的權杖失效。 -- 對於 OSS 使用者，輪替簽章金鑰後需重新啟動 Logto 實例，新金鑰才會生效。 -- 對於雲端版使用者，輪替後新金鑰立即生效，但請務必避免連續多次輪替簽章金鑰。 +- 對於 OSS 使用者，旋轉簽署金鑰後，需要重新啟動 Logto 實例以使新簽署金鑰生效。 +- 對於 Cloud 使用者，新簽署金鑰在旋轉後立即生效，但請確保不要連續多次旋轉簽署金鑰。 ::: ## 相關資源 \{#related-resources} - - JWT 中 EC 與 RSA 簽章演算法介紹 (Introduction to EC and RSA signing algorithms in JWT) + + JWT 中 EC 和 RSA 簽署算法介紹 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 7f9664c7ce5..cf48001a048 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,80 +1,82 @@ --- -description: 學習如何使用 Account API 管理使用者 +description: 瞭解如何使用 Account API 管理使用者 sidebar_position: 1 --- -# 透過 Account API 管理帳號設定 +# 使用 Account API 設定帳戶 ## 什麼是 Logto Account API \{#what-is-logto-account-api} -Logto Account API 是一組完整的 API，讓終端使用者可以直接透過 API 存取帳號，而無需經過 Management API。重點如下： +Logto Account API 是一組完整的 API，讓終端使用者可以直接存取 API，而不需要透過 Management API。以下是其亮點： -- 直接存取：Account API 讓終端使用者能直接存取並管理自己的帳號資料，無需透過 Management API 中繼。 -- 使用者資料與身分管理：使用者可完整管理個人資料與安全設定，包括更新身分資訊（如 email、手機、密碼）及管理社交連結。MFA 與 SSO 支援即將推出。 -- 全域存取控制：管理員可對存取設定進行完整、全域的控管，並可自訂每個欄位。 -- 無縫授權 (Authorization)：授權 (Authorization) 變得前所未有地簡單！只需使用 `client.getAccessToken()` 取得 Logto 的不透明權杖 (Opaque token)，並將其以 `Bearer ` 附加於 Authorization 標頭即可。 +- 直接存取：Account API 讓終端使用者可以直接存取並管理自己的帳戶資料，而不需要透過 Management API。 +- 使用者資料和身分管理：使用者可以完全管理自己的資料和安全設定，包括更新電子郵件、電話和密碼等身分資訊，以及管理社交連結。MFA 和 SSO 支援即將推出。 +- 全域存取控制：管理員擁有完整的全域控制權，可以自訂每個欄位。 +- 無縫授權：授權變得前所未有的簡單！只需使用 `client.getAccessToken()` 取得 Logto 的不透明存取權杖，並將其附加到 Authorization 標頭中作為 `Bearer `。 -透過 Logto Account API，你可以打造如個人資料頁等完全整合 Logto 的自訂帳號管理系統。 +使用 Logto Account API，你可以建立一個自訂的帳戶管理系統，例如與 Logto 完全整合的個人資料頁面。 -常見應用場景如下： +以下列出一些常見的使用案例： - 取得使用者資料 - 更新使用者資料 - 更新使用者密碼 -- 更新使用者身分（包含 email、手機、社交連結） -- 管理 MFA 驗證因素 -- 管理使用者工作階段 +- 更新使用者身分，包括電子郵件、電話和社交連結 +- 管理 MFA 因素（驗證） +- 管理使用者會話 +- 管理使用者授權的應用程式（授權） -想了解更多可用 API，請參閱 [Logto Account API 參考文件](https://openapi.logto.io/group/endpoint-my-account) 與 [Logto Verification API 參考文件](https://openapi.logto.io/group/endpoint-verifications)。 +要瞭解更多可用的 API，請造訪 [Logto Account API 參考](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 參考](https://openapi.logto.io/group/endpoint-verifications)。 :::note -SSO 帳號檢視與帳號刪除功能目前僅能透過 Logto Management API 使用。實作細節請參考 [透過 Management API 管理帳號設定](/end-user-flows/account-settings/by-management-api)。 +SSO 帳戶檢視和帳戶刪除功能目前可透過 Logto Management API 使用。請參閱 [使用 Management API 設定帳戶](/end-user-flows/account-settings/by-management-api) 以獲取實作細節。 ::: ## 如何啟用 Account API \{#how-to-enable-account-api} -前往 Console > 登入與帳號 > 帳號中心。 +前往 控制台 > 登入與帳戶 > 帳戶中心。 -Account API 預設為關閉，因此其存取控制設定為鎖定。切換 **啟用 Account API** 以開啟功能。 +Account API 預設為關閉狀態，因此其存取控制被鎖定。切換 **啟用 Account API** 以開啟它。 -啟用後，可針對識別資訊、個人資料與第三方權杖存取設定每個欄位的權限。每個欄位支援 `Off`、`ReadOnly` 或 `Edit`，預設為 `Off`。 +啟用後，為識別符、資料和第三方權杖存取配置每個欄位的權限。每個欄位支援 `Off`、`ReadOnly` 或 `Edit`；預設為 `Off`。 1. **安全欄位**： - - 包含：主要 email、主要手機、社交身分、密碼、MFA。 - - 終端使用者在編輯這些欄位前，必須透過密碼、email 或簡訊驗證身分，取得 10 分鐘有效的驗證紀錄 ID。詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 - - 若要使用 WebAuthn passkey 作為 MFA，請將前端應用程式網域加入 **WebAuthn 相關來源**，以便帳號中心與登入體驗共用 passkey。詳見 [連結新的 WebAuthn passkey](#link-a-new-webauthn-passkey)。 -2. **個人資料欄位**： - - 包含：使用者名稱、姓名、大頭貼、[profile](/user-management/user-data#profile)（其他標準個人資料屬性）、[自訂資料](/user-management/user-data#custom-data)。 - - 終端使用者可直接編輯這些欄位，無需額外驗證。 + - 欄位包括：主要電子郵件、主要電話、社交身分、密碼和 MFA。 + - 在終端使用者編輯這些欄位之前，他們必須透過密碼、電子郵件或簡訊驗證其身分，以獲得 10 分鐘的驗證記錄 ID。請參閱 [取得驗證記錄 ID](#get-a-verification-record-id)。 + - 若要使用 WebAuthn 密鑰作為 MFA，請將你的前端應用程式網域新增到 **WebAuthn 相關來源**，以便帳戶中心和登入體驗可以共享密鑰。請參閱 [連結新的 WebAuthn 密鑰](#link-a-new-webauthn-passkey)。 +2. **資料欄位**： + - 欄位包括：使用者名稱、姓名、大頭貼、[資料](/user-management/user-data#profile)（其他標準資料屬性）和[自訂資料](/user-management/user-data#custom-data)。 + - 終端使用者可以在不需額外驗證的情況下編輯這些欄位。 3. **秘密保管庫**： - - 對於 OIDC 或 OAuth 社交與企業連接器，Logto [秘密保管庫](/secret-vault/federated-token-set) 會在驗證後安全儲存第三方 access / refresh token。應用程式可直接呼叫外部 API（如同步 Google Calendar 事件），無需再次提示使用者登入。啟用 Account API 後即可自動取得權杖。 -4. **工作階段管理**： - - 啟用後，使用者可檢視並管理目前啟用的工作階段，包括裝置資訊與上次登入時間。也可撤銷特定裝置的工作階段以登出。 - - 終端使用者在存取工作階段管理前，必須透過密碼、email 或簡訊驗證身分，取得 10 分鐘有效的驗證紀錄 ID。詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 + - 對於 OIDC 或 OAuth 社交和企業連接器，Logto [秘密保管庫](/secret-vault/federated-token-set) 在驗證後安全地儲存第三方存取和重新整理權杖。應用程式可以呼叫外部 API，例如同步 Google 日曆事件，而不需再次提示使用者登入。權杖檢索在啟用 Account API 後自動可用。 +4. **會話管理**： + - 啟用後，使用者可以檢視和管理其活動會話，包括裝置資訊和上次登入時間。使用者還可以撤銷會話以從特定裝置登出。 + - 此 `Sessions` 欄位權限也控制使用者授權的應用程式（授權）API（檢視和撤銷授權）。 + - 在終端使用者存取會話管理之前，他們必須透過密碼、電子郵件或簡訊驗證其身分，以獲得 10 分鐘的驗證記錄 ID。請參閱 [取得驗證記錄 ID](#get-a-verification-record-id)。 ## 如何存取 Account API \{#how-to-access-account-api} :::note -為確保存取權杖具備正確權限，請確認你已在 Logto 設定中正確配置對應的權限範圍 (Scopes)。 +為確保存取權杖具有適當的權限，請確保你已在 Logto 配置中正確配置相應的權限範圍。 -例如，`POST /api/my-account/primary-email` API 需配置 `email` 權限範圍；`POST /api/my-account/primary-phone` API 需配置 `phone` 權限範圍。 +例如，對於 `POST /api/my-account/primary-email` API，你需要配置 `email` 權限範圍；對於 `POST /api/my-account/primary-phone` API，你需要配置 `phone` 權限範圍。 ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...其他選項 - // 根據需求新增合適的權限範圍 + // 新增適合你的使用案例的適當權限範圍。 scopes: [ UserScope.Email, // 用於 `{POST,DELETE} /api/my-account/primary-email` API UserScope.Phone, // 用於 `{POST,DELETE} /api/my-account/primary-phone` API - UserScope.CustomData, // 管理自訂資料 - UserScope.Address, // 管理地址 - UserScope.Identities, // 用於身分與 MFA 相關 API - UserScope.Profile, // 管理使用者個人資料 - UserScope.Sessions, // 管理使用者工作階段 + UserScope.CustomData, // 用於管理自訂資料 + UserScope.Address, // 用於管理地址 + UserScope.Identities, // 用於身分和 MFA 相關 API + UserScope.Profile, // 用於管理使用者資料 + UserScope.Sessions, // 用於管理使用者會話和應用程式授權 ], }; ``` @@ -83,33 +85,33 @@ const config: LogtoConfig = { ### 取得存取權杖 \{#fetch-an-access-token} -在應用程式中設定好 SDK 後，可使用 `client.getAccessToken()` 方法取得存取權杖。此權杖為不透明權杖 (Opaque token)，可用於存取 Account API。 +在應用程式中設置 SDK 後，你可以使用 `client.getAccessToken()` 方法來取得存取權杖。此權杖是不透明權杖，可用於存取 Account API。 -若未使用官方 SDK，則在向 `/oidc/token` 請求存取權杖時，應將 `resource` 設為空字串。 +如果你未使用官方 SDK，應在存取權杖授權請求 `/oidc/token` 中將 `resource` 設為空。 ### 使用存取權杖存取 Account API \{#access-account-api-using-access-token} -與 Account API 互動時，請將存取權杖以 Bearer 格式（`Bearer YOUR_TOKEN`）放在 HTTP 標頭的 `Authorization` 欄位。 +在與 Account API 互動時，應在 HTTP 標頭的 `Authorization` 欄位中包含存取權杖，格式為 Bearer (`Bearer YOUR_TOKEN`)。 -以下為取得使用者帳號資訊的範例： +以下是一個取得使用者帳戶資訊的範例： ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## 管理基本帳號資訊 \{#manage-basic-account-information} +## 管理基本帳戶資訊 \{#manage-basic-account-information} -### 取得使用者帳號資訊 \{#retrieve-user-account-information} +### 取得使用者帳戶資訊 \{#retrieve-user-account-information} -可使用 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 端點取得使用者資料。 +要取得使用者資料，你可以使用 [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) 端點。 ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -120,13 +122,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -回應欄位會依帳號中心設定而有所不同。 +回應欄位可能會根據帳戶中心設定而有所不同。 -### 更新基本帳號資訊 \{#update-basic-account-information} +### 更新基本帳戶資訊 \{#update-basic-account-information} -基本帳號資訊包含使用者名稱、姓名、大頭貼、自訂資料及其他個人資料。 +基本帳戶資訊包括使用者名稱、姓名、大頭貼、自訂資料和其他資料資訊。 -要更新 **username、name、avatar、customData**，可使用 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 端點。 +要更新 **username, name, avatar, 和 customData**，你可以使用 [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) 端點。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -135,7 +137,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -要更新其他個人資料（如 **familyName、givenName、middleName、nickname、profile（個人頁面網址）、website、gender、birthdate、zoneinfo、locale、address**），可使用 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 端點。 +要更新其他資料資訊，包括 **familyName, givenName, middleName, nickname, profile (資料頁面 URL), website, gender, birthdate, zoneinfo, locale, 和 address**，你可以使用 [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) 端點。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -144,17 +146,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 管理識別資訊與其他敏感資料 \{#manage-identifiers-and-other-sensitive-information} +## 管理識別符和其他敏感資訊 \{#manage-identifiers-and-other-sensitive-information} -出於安全考量，Account API 對涉及識別資訊與其他敏感資料的操作需額外授權 (Authorization) 驗證。 +出於安全考量，Account API 需要額外的授權層來進行涉及識別符和其他敏感資訊的操作。 -### 取得驗證紀錄 ID \{#get-a-verification-record-id} +### 取得驗證記錄 ID \{#get-a-verification-record-id} -首先，你需要取得一組 **驗證紀錄 ID**，有效期限為 10 分鐘（TTL）。這可用於在更新敏感資料前驗證使用者身分。也就是說，當使用者成功透過密碼、email 驗證碼或簡訊驗證碼驗證身分後，有 10 分鐘可更新與驗證 (Authentication) 相關的資料，包括識別資訊、憑證、社交帳號連結與 MFA。 +首先，你需要取得一個具有 10 分鐘有效期（TTL）的 **驗證記錄 ID**。這可用於在更新敏感資訊之前驗證使用者的身分。這意味著一旦使用者透過密碼、電子郵件驗證碼或簡訊驗證碼成功驗證其身分，他們有 10 分鐘的時間來更新其驗證相關資料，包括識別符、憑證、社交帳戶連結和 MFA。 -取得驗證紀錄 ID 的方式有：[驗證使用者密碼](#verify-the-users-password) 或 [發送驗證碼到使用者 email 或手機](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)。 +要取得驗證記錄 ID，你可以 [驗證使用者的密碼](#verify-the-users-password) 或 [向使用者的電子郵件或電話發送驗證碼](#verify-by-sending-a-verification-code-to-the-users-email-or-phone)。 -#### 驗證使用者密碼 \{#verify-the-users-password} +#### 驗證使用者的密碼 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -163,7 +165,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -172,13 +174,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 發送驗證碼到使用者 email 或手機 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 向使用者的電子郵件或電話發送驗證碼 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -使用此方法前，需先 [設定 email 連接器](/connectors/email-connectors/) 或 [SMS 連接器](/connectors/sms-connectors/)，並確保已設定 `UserPermissionValidation` 範本。 +要使用此方法，你需要 [配置電子郵件連接器](/connectors/email-connectors/) 或 [簡訊連接器](/connectors/sms-connectors/)，並確保已配置 `UserPermissionValidation` 模板。 ::: -以 email 為例，請求新的驗證碼並取得驗證紀錄 ID： +以電子郵件為例，請求新的驗證碼並取得驗證記錄 ID： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -187,7 +189,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -196,7 +198,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -收到驗證碼後，可用於更新驗證紀錄的驗證狀態。 +收到驗證碼後，你可以使用它來更新驗證記錄的驗證狀態。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -205,17 +207,17 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -驗證成功後，即可使用驗證紀錄 ID 更新使用者識別資訊。 +驗證碼驗證後，你現在可以使用驗證記錄 ID 來更新使用者的識別符。 -更多驗證相關說明，請參閱 [透過 Account API 進行安全驗證](/end-user-flows/security-verification)。 +要瞭解更多關於驗證的資訊，請參閱 [透過 Account API 進行安全驗證](/end-user-flows/security-verification)。 -### 夾帶驗證紀錄 ID 發送請求 \{#send-request-with-verification-record-id} +### 使用驗證記錄 ID 發送請求 \{#send-request-with-verification-record-id} -在發送更新使用者識別資訊的請求時，需於請求標頭中以 `logto-verification-id` 欄位夾帶驗證紀錄 ID。 +在發送請求以更新使用者的識別符時，你需要在請求標頭中包含驗證記錄 ID，使用 `logto-verification-id` 欄位。 -### 更新使用者密碼 \{#update-users-password} +### 更新使用者的密碼 \{#update-users-password} -要更新使用者密碼，可使用 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 端點。 +要更新使用者的密碼，你可以使用 [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) 端點。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/password \ @@ -226,18 +228,18 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \ ``` :::tip -與註冊時設定密碼相同，透過 Account API 設定的密碼必須符合你在 Console > 安全性 > 密碼政策 設定的 [密碼政策](/security/password-policy)。若密碼不符政策，Logto 會回傳詳細驗證結果與錯誤訊息。 +與註冊時創建的密碼一樣，透過 Account API 設定的密碼必須符合你在 控制台 > 安全 > 密碼政策 中配置的 [密碼政策](/security/password-policy)。如果密碼不符合政策，Logto 會返回詳細的驗證結果和錯誤訊息。 ::: -### 更新或連結新 email \{#update-or-link-new-email} +### 更新或連結新的電子郵件 \{#update-or-link-new-email} :::note -使用此方法前，需先 [設定 email 連接器](/connectors/email-connectors/)，並確保已設定 `BindNewIdentifier` 範本。 +要使用此方法，你需要 [配置電子郵件連接器](/connectors/email-connectors/)，並確保已配置 `BindNewIdentifier` 模板。 ::: -要更新或連結新 email，需先證明 email 擁有權。 +要更新或連結新的電子郵件，你應首先證明該電子郵件的所有權。 -呼叫 [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) 端點請求驗證碼。 +呼叫 [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) 端點以請求驗證碼。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -246,7 +248,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -回應中會有 `verificationId`，並會收到 email 驗證碼，請用於驗證 email。 +你將在回應中找到 `verificationId`，並在電子郵件中收到驗證碼，使用它來驗證電子郵件。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -255,34 +257,34 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -驗證成功後，即可呼叫 [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) 更新使用者 email，並將 `verificationId` 作為 `newIdentifierVerificationRecordId` 放入請求內容。 +驗證碼驗證後，你現在可以呼叫 [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) 來更新使用者的電子郵件，將 `verificationId` 設為請求主體中的 `newIdentifierVerificationRecordId`。 -:::info[兩組不同的驗證紀錄 ID] +:::info[兩個不同的驗證記錄 ID] -此請求需兩組不同的驗證紀錄 ID： +此請求需要兩個不同的驗證記錄 ID： -- **`logto-verification-id`（標頭）**：證明使用者身分以進行敏感操作。可透過 [驗證使用者密碼](#verify-the-users-password) 或 [發送驗證碼到現有 email 或手機](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 取得。 -- **`newIdentifierVerificationRecordId`（內容）**：證明新 email 擁有權。即上述 `POST /api/verifications/verification-code` 回傳的 `verificationRecordId`。 +- **`logto-verification-id`（標頭）**：在進行敏感更改之前證明使用者的身分。透過 [驗證使用者的密碼](#verify-the-users-password) 或 [向使用者的現有電子郵件或電話發送驗證碼](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 獲得。 +- **`newIdentifierVerificationRecordId`（主體）**：證明新電子郵件地址的所有權。這是從上述 `POST /api/verifications/verification-code` 呼叫返回的 `verificationRecordId`。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'authorization: Bearer ' \ - # 驗證使用者身分（來自密碼或現有 email/手機驗證） + # 驗證使用者身分（來自密碼或現有電子郵件/電話驗證） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" 證明新 email 擁有權（來自上述驗證流程） + # "newIdentifierVerificationRecordId" 證明新電子郵件的所有權（來自上述驗證碼流程） --data-raw '{"email":"...","newIdentifierVerificationRecordId":""}' ``` :::tip -與註冊時收集 email 相同，透過 Account API 連結的 email 必須通過你在 Console > 安全性 > 封鎖清單 設定的 [封鎖清單](/security/blocklist) 驗證。若 email 違反政策，Logto 會拒絕請求並回傳詳細錯誤。 +與註冊時收集的電子郵件一樣，透過 Account API 連結的任何電子郵件必須通過你在 控制台 > 安全 > 封鎖清單 中配置的 [封鎖清單](/security/blocklist) 驗證。如果電子郵件違反政策，Logto 將拒絕請求並返回詳細錯誤。 ::: -### 移除使用者 email \{#remove-the-users-email} +### 移除使用者的電子郵件 \{#remove-the-users-email} -要移除使用者 email，可使用 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 端點。 +要移除使用者的電子郵件，你可以使用 [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) 端點。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -290,17 +292,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 管理手機 \{#manage-phone} +### 管理電話 \{#manage-phone} :::note -使用此方法前，需先 [設定 SMS 連接器](/connectors/sms-connectors/)，並確保已設定 `BindNewIdentifier` 範本。 +要使用此方法，你需要 [配置簡訊連接器](/connectors/sms-connectors/)，並確保已配置 `BindNewIdentifier` 模板。 ::: -與 email 更新流程類似，可使用 [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 端點更新或連結新手機。移除手機則使用 [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 端點。 +類似於更新電子郵件，你可以使用 [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) 端點來更新或連結新的電話。並使用 [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) 端點來移除使用者的電話。 -### 連結新的社交帳號 \{#link-a-new-social-connection} +### 連結新的社交連結 \{#link-a-new-social-connection} -要連結新的社交帳號，首先需透過 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial) 取得授權網址。 +要連結新的社交連結，首先你應請求授權 URL，使用 [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial)。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -309,13 +311,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`：對應 [社交連接器](/connectors/social-connectors/) 的 ID。 -- `redirectUri`：使用者授權應用程式後的導向網址，需在此網址架設網頁並接收回呼。 -- `state`：授權後回傳的狀態字串，用於防止 CSRF 攻擊。 +- `connectorId`：[社交連接器](/connectors/social-connectors/) 的 ID。 +- `redirectUri`：使用者授權應用程式後的重定向 URI，你應在此 URL 上託管一個網頁並捕獲回調。 +- `state`：使用者授權應用程式後返回的狀態，它是一個隨機字串，用於防止 CSRF 攻擊。 -回應中會有 `verificationRecordId`，請妥善保存。 +在回應中，你將找到一個 `verificationRecordId`，請保留以供後續使用。 -使用者授權應用程式後，會於 `redirectUri` 收到帶有 `state` 參數的回呼。接著可使用 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 端點驗證社交連結。 +在使用者授權應用程式後，你將在 `redirectUri` 上收到帶有 `state` 參數的回調。然後你可以使用 [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) 端點來驗證社交連結。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -324,32 +326,32 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` 為社交連接器授權後回傳的資料，需於回呼頁面解析 `redirectUri` 的查詢參數並包裝為 JSON。 +`connectorData` 是使用者授權應用程式後由社交連接器返回的資料，你需要解析並從回調頁面的 `redirectUri` 中獲取查詢參數，並將它們包裝為 JSON 作為 `connectorData` 欄位的值。 -最後，可使用 [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 端點連結社交帳號。 +最後，你可以使用 [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) 端點來連結社交連結。 -:::info[兩組不同的驗證紀錄 ID] +:::info[兩個不同的驗證記錄 ID] -此請求需兩組不同的驗證紀錄 ID： +此請求需要兩個不同的驗證記錄 ID： -- **`logto-verification-id`（標頭）**：證明使用者身分以進行敏感操作。可透過 [驗證使用者密碼](#verify-the-users-password) 或 [發送驗證碼到現有 email 或手機](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 取得。 -- **`newIdentifierVerificationRecordId`（內容）**：標識要連結的社交身分。即上述 `POST /api/verifications/social` 回傳的 `verificationRecordId`。 +- **`logto-verification-id`（標頭）**：在進行敏感更改之前證明使用者的身分。透過 [驗證使用者的密碼](#verify-the-users-password) 或 [向使用者的現有電子郵件或電話發送驗證碼](#verify-by-sending-a-verification-code-to-the-users-email-or-phone) 獲得。 +- **`newIdentifierVerificationRecordId`（主體）**：識別要連結的社交身分。這是從上述 `POST /api/verifications/social` 呼叫返回的 `verificationRecordId`。 ::: ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ -H 'authorization: Bearer ' \ - # 驗證使用者身分（來自密碼或現有 email/手機驗證） + # 驗證使用者身分（來自密碼或現有電子郵件/電話驗證） -H 'logto-verification-id: ' \ -H 'content-type: application/json' \ - # "newIdentifierVerificationRecordId" 標識要連結的社交帳號（來自上述驗證流程） + # "newIdentifierVerificationRecordId" 證明要連結的社交連結（來自上述社交驗證流程） --data-raw '{"newIdentifierVerificationRecordId":""}' ``` -### 移除社交帳號 \{#remove-a-social-connection} +### 移除社交連結 \{#remove-a-social-connection} -要移除社交帳號，可使用 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 端點。 +要移除社交連結，你可以使用 [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) 端點。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -357,30 +359,30 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### 連結新的 WebAuthn passkey \{#link-a-new-webauthn-passkey} +### 連結新的 WebAuthn 密鑰 \{#link-a-new-webauthn-passkey} :::note -請先 [啟用 MFA 與 WebAuthn](/end-user-flows/mfa)。 +記得先 [啟用 MFA 和 WebAuthn](/end-user-flows/mfa)。 ::: :::note -使用此方法前，需於 [帳號中心設定](#how-to-enable-account-api) 啟用 `mfa` 欄位。 +要使用此方法，你需要在 [帳戶中心設定](#how-to-enable-account-api) 中啟用 `mfa` 欄位。 ::: -**步驟 1：將前端應用程式來源加入相關來源** +**步驟 1：將你的前端應用程式來源新增到相關來源** -WebAuthn passkey 綁定於特定主機名稱（**Relying Party ID, RP ID**）。僅在該 RP ID 的來源下運作的應用程式可註冊或驗證該 passkey。 +WebAuthn 密鑰綁定到一個特定的主機名，稱為 **Relying Party ID (RP ID)**。只有在 RP ID 的來源上託管的應用程式才能註冊或驗證這些密鑰。 -由於你的前端應用程式與 Logto 驗證頁面網域不同，需設定 **相關來源** 以允許跨來源 passkey 操作。 +由於你的前端應用程式從與 Logto 驗證頁面不同的網域呼叫 Account API，你需要配置 **相關來源** 以允許跨來源密鑰操作。 -**Logto 如何判斷 RP ID：** +**Logto 如何確定 RP ID：** -- **預設情境**：僅使用 Logto 預設網域 `https://[tenant-id].logto.app` 時，RP ID 為 `[tenant-id].logto.app` -- **自訂網域**：若設定 [自訂網域](/logto-cloud/custom-domain)（如 `https://auth.example.com`），RP ID 為 `auth.example.com` +- **預設設置**：如果你只使用 Logto 的預設網域 `https://[tenant-id].logto.app`，則 RP ID 是 `[tenant-id].logto.app` +- **自訂網域**：如果你已配置 [自訂網域](/logto-cloud/custom-domain)，例如 `https://auth.example.com`，則 RP ID 變為 `auth.example.com` -**設定相關來源：** +**配置相關來源：** -使用 [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 端點新增前端應用程式來源。例如帳號中心運行於 `https://account.example.com`： +使用 [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) 端點將你的前端應用程式的來源新增。例如，如果你的應用程式帳戶中心運行在 `https://account.example.com`： ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -391,19 +393,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ :::note -WebAuthn 最多支援 5 組唯一 eTLD+1 標籤作為相關來源。eTLD+1（有效頂級網域加一層）為可註冊的網域部分。例如： +WebAuthn 支援最多 5 個唯一的 eTLD+1 標籤作為相關來源。eTLD+1（有效頂級域加一個標籤）是可註冊的域部分。例如： -- `https://example.com`、`https://app.example.com`、`https://auth.example.com` 算作 **一** 組（`example.com`） -- `https://shopping.com`、`https://shopping.co.uk`、`https://shopping.co.jp` 也算作 **一** 組（`shopping`） -- `https://example.com` 與 `https://another.com` 算作 **兩** 組 +- `https://example.com`、`https://app.example.com` 和 `https://auth.example.com` 計為 **一** 個標籤（`example.com`） +- `https://shopping.com`、`https://shopping.co.uk` 和 `https://shopping.co.jp` 也計為 **一** 個標籤（`shopping`） +- `https://example.com` 和 `https://another.com` 計為 **兩** 個標籤 -若需支援超過 5 組不同網域，請參閱 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 文件。 +如果你需要支援超過 5 個不同的網域作為相關來源，請參閱 [相關來源請求](https://passkeys.dev/docs/advanced/related-origins/) 文件以獲取詳細資訊。 ::: **步驟 2：請求新的註冊選項** -使用 [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 端點請求註冊新 passkey。Logto 允許每個帳號註冊多組 passkey。 +使用 [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) 端點請求註冊新密鑰。Logto 允許每個使用者帳戶註冊多個密鑰。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -411,7 +413,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -回應內容範例如下： +你將收到如下回應： ```json { @@ -421,25 +423,25 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat } ``` -**步驟 3：於本地瀏覽器註冊 passkey** +**步驟 3：在本地瀏覽器中註冊密鑰** -以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 為例，可用 `startRegistration` 函式於本地瀏覽器註冊 passkey。 +以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 為例，你可以使用 `startRegistration` 函數在本地瀏覽器中註冊密鑰。 ```ts import { startRegistration } from '@simplewebauthn/browser'; // ... const response = await startRegistration({ - optionsJSON: registrationOptions, // 步驟 1 伺服器回傳資料 + optionsJSON: registrationOptions, // 步驟 1 中伺服器返回的資料 }); -// 儲存 response 以供後續使用 +// 保存回應以供後續使用 ``` -**步驟 4：驗證 passkey 註冊** +**步驟 4：驗證密鑰註冊** -使用 [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 端點驗證 passkey 註冊。 +使用 [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) 端點驗證密鑰註冊。 -此步驟會驗證驗證器產生的加密簽章，確保 passkey 合法建立且傳輸過程未被竄改。 +此步驟驗證由驗證器生成的加密簽名，以確保密鑰是合法創建的，並且在傳輸過程中未被篡改。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -448,12 +450,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`：步驟 2 本地瀏覽器回傳的資料。 -- `verificationRecordId`：步驟 1 伺服器回傳的驗證紀錄 ID。 +- `payload`：步驟 2 中本地瀏覽器的回應。 +- `verificationRecordId`：步驟 1 中伺服器返回的驗證記錄 ID。 -**步驟 5：連結 passkey** +**步驟 5：連結密鑰** -最後，可使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點將 passkey 連結至使用者帳號。 +最後，你可以使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點將密鑰連結到使用者的帳戶。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -463,20 +465,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因素，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 -- `type`：MFA 因素類型，目前僅支援 `WebAuthn`。 -- `newIdentifierVerificationRecordId`：步驟 1 伺服器回傳的驗證紀錄 ID。 +- `verification_record_id`：有效的驗證記錄 ID，透過驗證使用者的現有因素獲得，你可以參考 [取得驗證記錄 ID](#get-a-verification-record-id) 部分以獲取更多詳細資訊。 +- `type`：MFA 因素的類型，目前僅支援 `WebAuthn`。 +- `newIdentifierVerificationRecordId`：步驟 1 中伺服器返回的驗證記錄 ID。 -### 管理現有 WebAuthn passkey \{#manage-existing-webauthn-passkeys} +### 管理現有的 WebAuthn 密鑰 \{#manage-existing-webauthn-passkeys} -要管理現有 WebAuthn passkey，可使用 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 端點取得目前 passkey 與其他 MFA 驗證因素。 +要管理現有的 WebAuthn 密鑰，你可以使用 [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) 端點來獲取當前密鑰和其他 MFA 驗證因素。 ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -回應內容範例如下： +回應主體將如下所示： ```json [ @@ -491,12 +493,12 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`：驗證因素 ID。 -- `type`：驗證因素類型，WebAuthn passkey 為 `WebAuthn`。 -- `name`：passkey 名稱，為選填欄位。 -- `agent`：passkey 的 user agent。 +- `id`：驗證的 ID。 +- `type`：驗證的類型，`WebAuthn` 表示 WebAuthn 密鑰。 +- `name`：密鑰的名稱，可選欄位。 +- `agent`：密鑰的使用者代理。 -更新 passkey 名稱可使用 [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 端點： +使用 [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) 端點更新密鑰名稱： ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -506,7 +508,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -刪除 passkey 可使用 [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 端點： +使用 [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) 端點刪除密鑰： ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ @@ -517,16 +519,16 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v ### 連結新的 TOTP \{#link-a-new-totp} :::note -請先 [啟用 MFA 與 TOTP](/end-user-flows/mfa)。 +記得先 [啟用 MFA 和 TOTP](/end-user-flows/mfa)。 ::: :::note -使用此方法前，需於 [帳號中心設定](#how-to-enable-account-api) 啟用 `mfa` 欄位。 +要使用此方法，你需要在 [帳戶中心設定](#how-to-enable-account-api) 中啟用 `mfa` 欄位。 ::: -**步驟 1：產生 TOTP 密鑰** +**步驟 1：生成 TOTP 秘密** -使用 [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 端點產生 TOTP 密鑰。 +使用 [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) 端點生成 TOTP 秘密。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ @@ -534,7 +536,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp -H 'content-type: application/json' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -542,11 +544,11 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp } ``` -**步驟 2：將 TOTP 密鑰顯示給使用者** +**步驟 2：向使用者顯示 TOTP 秘密** -使用密鑰產生 QR code 或直接顯示給使用者，讓其加入驗證器 app（如 Google Authenticator、Microsoft Authenticator 或 Authy）。 +使用秘密生成 QR 碼或直接顯示給使用者。使用者應將其新增到其驗證器應用程式（例如 Google Authenticator、Microsoft Authenticator 或 Authy）。 -QR code URI 格式如下： +QR 碼的 URI 格式應為： ``` otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] @@ -560,7 +562,7 @@ otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp **步驟 3：綁定 TOTP 因素** -使用者將密鑰加入驗證器 app 後，需驗證並綁定至帳號。使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點綁定 TOTP 因素。 +使用者將秘密新增到其驗證器應用程式後，他們需要驗證並將其綁定到其帳戶。使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點綁定 TOTP 因素。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -570,27 +572,27 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"Totp","secret":"..."}' ``` -- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因素，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 +- `verification_record_id`：有效的驗證記錄 ID，透過驗證使用者的現有因素獲得。你可以參考 [取得驗證記錄 ID](#get-a-verification-record-id) 部分以獲取更多詳細資訊。 - `type`：必須為 `Totp`。 -- `secret`：步驟 1 產生的 TOTP 密鑰。 +- `secret`：步驟 1 中生成的 TOTP 秘密。 :::note -每位使用者同時僅能有一組 TOTP 因素。若已存在 TOTP 因素，新增時會回傳 422 錯誤。 +使用者一次只能有一個 TOTP 因素。如果使用者已經有 TOTP 因素，嘗試新增另一個將導致 422 錯誤。 ::: -### 管理備用驗證碼 \{#manage-backup-codes} +### 管理備份碼 \{#manage-backup-codes} :::note -請先 [啟用 MFA 與備用驗證碼](/end-user-flows/mfa)。 +記得先 [啟用 MFA 和備份碼](/end-user-flows/mfa)。 ::: :::note -使用此方法前，需於 [帳號中心設定](#how-to-enable-account-api) 啟用 `mfa` 欄位。 +要使用此方法，你需要在 [帳戶中心設定](#how-to-enable-account-api) 中啟用 `mfa` 欄位。 ::: -**步驟 1：產生新備用驗證碼** +**步驟 1：生成新的備份碼** -使用 [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 端點產生一組 10 組備用驗證碼。 +使用 [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) 端點生成一組新的 10 個備份碼。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ @@ -598,7 +600,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back -H 'content-type: application/json' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -606,20 +608,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/back } ``` -**步驟 2：將備用驗證碼顯示給使用者** +**步驟 2：向使用者顯示備份碼** -在綁定備用驗證碼前，必須將其顯示給使用者，並提醒： +在將備份碼綁定到使用者帳戶之前，你必須將它們顯示給使用者並指導他們： -- 立即下載或抄寫這些驗證碼 -- 妥善保存於安全處 -- 每組驗證碼僅能使用一次 -- 若失去主要 MFA 方法，這些驗證碼為最後救援手段 +- 立即下載或記下這些碼 +- 將它們儲存在安全的位置 +- 瞭解每個碼只能使用一次 +- 知道這些碼是他們失去對主要 MFA 方法的存取權時的最後手段 -建議以清楚、易於複製的格式顯示，並可提供下載（如文字檔或 PDF）。 +你應以清晰、易於複製的格式顯示這些碼，並考慮提供下載選項（例如作為文字檔或 PDF）。 -**步驟 3：綁定備用驗證碼至帳號** +**步驟 3：將備份碼綁定到使用者帳戶** -使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點綁定備用驗證碼至帳號。 +使用 [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) 端點將備份碼綁定到使用者帳戶。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -629,28 +631,28 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' ``` -- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因素，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 +- `verification_record_id`：有效的驗證記錄 ID，透過驗證使用者的現有因素獲得。你可以參考 [取得驗證記錄 ID](#get-a-verification-record-id) 部分以獲取更多詳細資訊。 - `type`：必須為 `BackupCode`。 -- `codes`：前述步驟產生的備用驗證碼陣列。 +- `codes`：在前一步生成的備份碼陣列。 :::note -- 每位使用者同時僅能有一組備用驗證碼。若全部用盡，需重新產生並綁定新組。 -- 備用驗證碼不能是唯一的 MFA 因素。使用者必須至少啟用一種其他 MFA（如 WebAuthn 或 TOTP）。 -- 每組備用驗證碼僅能使用一次。 +- 使用者一次只能有一組備份碼。如果所有碼都已使用，使用者需要生成並綁定新碼。 +- 備份碼不能是唯一的 MFA 因素。使用者必須啟用至少一個其他 MFA 因素（例如 WebAuthn 或 TOTP）。 +- 每個備份碼只能使用一次。 ::: -**檢視現有備用驗證碼** +**檢視現有的備份碼** -要檢視現有備用驗證碼及其使用狀態，請使用 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 端點： +要檢視現有的備份碼及其使用狀態，使用 [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) 端點： ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ -H 'authorization: Bearer ' ``` -回應內容範例如下： +回應主體將如下所示： ```json { @@ -667,19 +669,19 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes } ``` -- `code`：備用驗證碼。 -- `usedAt`：驗證碼使用時間，未使用為 `null`。 +- `code`：備份碼。 +- `usedAt`：碼使用的時間戳，若尚未使用則為 `null`。 -### 管理使用者工作階段 \{#manage-user-sessions} +### 管理使用者會話 \{#manage-user-sessions} -**列出啟用中的工作階段** +**列出活動會話** -要列出使用者啟用中的工作階段，可使用 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 端點。 +要列出使用者的活動會話，你可以使用 [`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) 端點。 :::note -- 需有 `UserScope.Sessions` 權限範圍才能存取此端點。 -- 帳號中心設定中的 `Sessions` 欄位需設為 `ReadOnly` 或 `Edit`。 +- 需要 `UserScope.Sessions` 權限範圍才能存取此端點。 +- 帳戶中心設定中的 `Sessions` 欄位必須設為 `ReadOnly` 或 `Edit`。 ::: @@ -690,14 +692,14 @@ curl https://[tenant-id].logto.app/api/my-account/sessions \ -H 'content-type: application/json' ``` -**依 session ID 撤銷工作階段** +**按會話 ID 撤銷會話** -要撤銷特定工作階段，請使用 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 端點。 +要撤銷特定會話，使用 [`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) 端點。 :::note -- 需有 `UserScope.Sessions` 權限範圍才能存取此端點。 -- 帳號中心設定中的 `Sessions` 欄位需設為 `Edit`。 +- 需要 `UserScope.Sessions` 權限範圍才能存取此端點。 +- 帳戶中心設定中的 `Sessions` 欄位必須設為 `Edit`。 ::: ```bash @@ -709,7 +711,58 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} 可選查詢參數： -- `revokeGrantsTarget`：可選，指定要連同 session 一併撤銷的授權目標。可用值： - - `all`：撤銷與該 session 相關的所有授權。 - - `firstParty`：僅撤銷與該 session 相關的第一方應用程式授權。（大多數情境建議使用，僅撤銷自家 app 存取權，保留第三方 app 授權，提升使用者體驗。） - - 未指定：預設僅撤銷未含 `offline_access` 權限範圍的授權，通常代表撤銷該 session 的非 refresh token 授權。 +- `revokeGrantsTarget`：可選地指定要撤銷的授權目標。可能的值： + - `all`：撤銷與會話相關的所有授權。 + - `firstParty`：僅撤銷與會話相關的第一方應用程式授權。（推薦用於大多數使用案例，因為它撤銷你自己的應用程式的存取權，同時保留第三方應用程式授權，提供更好的使用者體驗。） + - 未指定：預設行為撤銷不具有 `offline_access` 權限範圍的授權，這通常意味著撤銷會話的非重新整理權杖授權。 + +### 管理使用者授權的應用程式（授權） \{#manage-user-authorized-apps-grants} + +當使用者需要從其帳戶設定頁面檢視和撤銷授權的應用程式時，使用使用者授權的應用程式（授權）API。 + +:::note + +- 應用程式授權 API 與會話 API 共享相同的權限模型。 +- 需要 `UserScope.Sessions` 權限範圍。 +- 帳戶中心設定中的 `Sessions` 欄位必須啟用： + - `ReadOnly` 或 `Edit` 以列出授權。 + - `Edit` 以撤銷授權。 + +::: + +**列出活動應用程式授權** + +要列出當前使用者的活動應用程式授權，使用 [`GET /api/my-account/grants`](https://openapi.logto.io/operation/operation-getgrants) 端點。 + +```bash +curl https://[tenant-id].logto.app/api/my-account/grants \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +可選查詢參數： + +- `appType=firstParty`：僅返回第一方應用程式授權。 +- `appType=thirdParty`：僅返回第三方應用程式授權。 +- 省略 `appType`：返回所有活動授權。 + +```bash +curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +**按授權 ID 撤銷應用程式授權** + +要撤銷特定應用程式授權，使用 [`DELETE /api/my-account/grants/{grantId}`](https://openapi.logto.io/operation/operation-deletegrantbyid) 端點。 + +```bash +curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' +``` + +當授權被撤銷時，先前發出的不透明存取權杖和重新整理權杖將失效。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx index 1c8ccf1bdc9..6d3430639c5 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-management-api.mdx @@ -2,203 +2,218 @@ sidebar_position: 2 --- -# 透過 Management API 管理帳戶設定 +# 使用 Management API 管理帳戶設定 -## 整合方式 \{#integrations} +## 整合 \{#integrations} -Logto 提供多種 Management API 來管理使用者帳戶。你可以利用這些 API 為終端使用者打造自助帳戶設定頁面。 +Logto 提供多種 Management API 來管理使用者帳戶。你可以使用這些 API 為終端使用者建立自助帳戶設定頁面。 -### 架構說明 \{#architecture} +### 架構 \{#architecture} ```mermaid graph TB - A[使用者 (User)] --> B[用戶端應用程式 (Client application)] - B -->|自架帳戶設定 API 呼叫 (Self-hosted account settings API call)|C[伺服器端應用程式 (Server-side application)] - C -->|Management API 呼叫 (Management API call)| D[Logto] + A[使用者] --> B[客戶端應用程式] + B -->|自託管帳戶設定 API 呼叫|C[伺服器端應用程式] + C -->|Management API 呼叫| D[Logto] ``` -1. **使用者 (User)**：已驗證且需要存取與管理帳戶設定的終端使用者。 -2. **用戶端應用程式 (Client application)**：提供帳戶設定頁面的應用程式。 -3. **伺服器端應用程式 (Server-side application)**：對用戶端提供帳戶設定 API，並與 Logto Management API 互動。 -4. **Logto**：作為驗證 (Authentication) 與授權 (Authorization) 服務，提供 Management API 以管理使用者帳戶。 +1. **使用者**：需要存取和管理其帳戶設定的已驗證終端使用者。 +2. **客戶端應用程式**：提供帳戶設定頁面的客戶端應用程式。 +3. **伺服器端應用程式**：提供帳戶設定 API 的伺服器端應用程式，與 Logto Management API 互動。 +4. **Logto**：作為驗證 (Authentication) 和授權 (Authorization) 服務的 Logto，提供管理使用者帳戶的 Management API。 -### 時序圖 \{#sequence-diagram} +### 序列圖 \{#sequence-diagram} ```mermaid sequenceDiagram autonumber - actor User as 使用者 (User) - participant Client as 用戶端應用程式 (Client app) - participant Server as 伺服器端應用程式 (Server-side application) + actor User as 使用者 + participant Client as 客戶端應用程式 + participant Server as 伺服器端應用程式 participant Logto as Logto - User ->> Client: 存取用戶端應用程式 + User ->> Client: 存取客戶端應用程式 Client ->> Logto: POST /oidc/auth User -->> Logto: 登入 - Logto -->> Client: 重新導向回用戶端應用程式 + Logto -->> Client: 重定向至客戶端應用程式 Client ->> Logto: POST /oidc/token - Logto ->> Client: 存取權杖 (Access token) A - Client ->> Server: GET /account-settings（附帶存取權杖 (Access token) A） - Server ->> Logto: POST /oidc/token（使用 client credentials） - Logto ->> Server: 存取權杖 (Access token) B - Server ->> Logto: GET /api/users/{userId}（附帶存取權杖 (Access token) B） + Logto ->> Client: 存取權杖 A + Client ->> Server: GET /account-settings (附存取權杖 A) + Server ->> Logto: POST /oidc/token (附客戶端憑證) + Logto ->> Server: 存取權杖 B + Server ->> Logto: GET /api/users/{userId} (附存取權杖 B) Logto ->> Server: 使用者詳細資料 Server ->> Client: 使用者詳細資料 ``` -1. 使用者存取用戶端應用程式。 -2. 用戶端應用程式向 Logto 發送驗證請求並將使用者導向 Logto 登入頁面。 +1. 使用者存取客戶端應用程式。 +2. 客戶端應用程式向 Logto 發送驗證請求並將使用者重定向至 Logto 登入頁面。 3. 使用者登入 Logto。 -4. 驗證後的使用者被導回用戶端應用程式，並帶有授權碼。 -5. 用戶端應用程式向 Logto 請求存取權杖 (Access token) 以存取自架帳戶設定 API。 -6. Logto 發放存取權杖 (Access token) 給用戶端應用程式。 -7. 用戶端應用程式攜帶使用者存取權杖 (Access token) 向伺服器端應用程式發送帳戶設定請求。 -8. 伺服器端應用程式驗證請求者身分與權限，並向 Logto 請求 Management API 存取權杖 (Access token)。 -9. Logto 發放 Management API 存取權杖 (Access token) 給伺服器端應用程式。 -10. 伺服器端應用程式使用 Management API 存取權杖 (Access token) 向 Logto 請求使用者資料。 -11. Logto 驗證伺服器身分與 Management API 權限後回傳使用者資料。 -12. 伺服器端應用程式根據請求者權限處理使用者資料並回傳帳戶詳細資料給用戶端應用程式。 +4. 已驗證的使用者被重定向回客戶端應用程式，並附帶授權碼。 +5. 客戶端應用程式向 Logto 請求存取權杖以存取自託管帳戶設定 API。 +6. Logto 向客戶端應用程式授予存取權杖。 +7. 客戶端應用程式使用使用者存取權杖向伺服器端應用程式發送帳戶設定請求。 +8. 伺服器端應用程式從使用者存取權杖中驗證請求者的身分和權限，然後向 Logto 請求 Management API 存取權杖。 +9. Logto 向伺服器端應用程式授予 Management API 存取權杖。 +10. 伺服器端應用程式使用 Management API 存取權杖向 Logto 請求使用者資料。 +11. Logto 驗證伺服器的身分和 Management API 權限，並返回使用者資料。 +12. 伺服器端應用程式根據請求者的權限處理使用者資料，並將使用者帳戶詳細資料返回給客戶端應用程式。 -### 將 Management API 整合至伺服器端應用程式 \{#integrate-management-api-to-server-side-application} +### 將 Management API 整合到伺服器端應用程式 \{#integrate-management-api-to-server-side-application} -請參閱 [Management API](/integrate-logto/interact-with-management-api/) 章節，瞭解如何將 Management API 整合至伺服器端應用程式。 +查看 [Management API](/integrate-logto/interact-with-management-api/) 部分以了解如何將 Management API 與伺服器端應用程式整合。 ## 使用者管理 API \{#user-management-apis} -### 使用者資料結構 \{#user-data-schema} +### 使用者資料架構 \{#user-data-schema} -請參閱 [使用者資料與自訂資料](/user-management/user-data/) 章節，瞭解 Logto 中的使用者資料結構。 +查看 [使用者資料和自訂資料](/user-management/user-data/) 部分以了解 Logto 中的使用者架構。 -### 使用者個人資料與識別資訊管理 API \{#user-profile-and-identifiers-management-apis} +### 使用者資料和識別碼管理 API \{#user-profile-and-identifiers-management-apis} -使用者的個人資料與識別資訊是使用者管理的核心。你可以使用下列 API 管理使用者個人資料與識別資訊。 +使用者的資料和識別碼對於使用者管理至關重要。你可以使用以下 API 來管理使用者資料和識別碼。 -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 依 user ID 取得使用者詳細資料。 | -| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 更新使用者詳細資料。 | -| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 依 user ID 更新使用者個人資料欄位。 | -| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 依 user ID 取得使用者自訂資料。 | -| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 依 user ID 更新使用者自訂資料。 | -| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 依 user ID 更新使用者停權狀態。 | +| 方法 | 路徑 | 描述 | +| ----- | -------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 根據使用者 ID 獲取使用者詳細資料。 | +| PATCH | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-updateuser) | 更新使用者詳細資料。 | +| PATCH | [/api/users/\{userId\}/profile](https://openapi.logto.io/operation/operation-updateuserprofile) | 根據使用者 ID 更新使用者資料欄位。 | +| GET | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-listusercustomdata) | 根據使用者 ID 獲取使用者自訂資料。 | +| PATCH | [/api/users/\{userId\}/custom-data](https://openapi.logto.io/operation/operation-updateusercustomdata) | 根據使用者 ID 更新使用者自訂資料。 | +| PATCH | [/api/users/\{userId\}/is-suspended](https://openapi.logto.io/operation/operation-updateuserissuspended) | 根據使用者 ID 更新使用者停權狀態。 | -### 電子郵件與手機號碼驗證 \{#email-and-phone-number-verification} +### 電子郵件和電話號碼驗證 \{#email-and-phone-number-verification} -在 Logto 系統中，電子郵件地址與手機號碼皆可作為使用者識別資訊，因此驗證這些資訊非常重要。為此，我們提供一組驗證碼 API，協助驗證所提供的電子郵件或手機號碼。 +在 Logto 系統中，電子郵件地址和電話號碼都可以作為使用者識別碼，因此驗證它們是必要的。為此，我們提供了一組驗證碼 API 來協助驗證提供的電子郵件或電話號碼。 :::note -請務必在將新電子郵件或手機號碼更新至使用者個人資料前，先完成驗證。 +在更新使用者資料中的新電子郵件或電話號碼之前，請確保已驗證該電子郵件或電話號碼。 ::: -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 發送電子郵件或手機號碼驗證碼。 | -| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 透過驗證碼驗證電子郵件或手機號碼。 | +| 方法 | 路徑 | 描述 | +| ---- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| POST | [/api/verifications/verification-code](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) | 發送電子郵件或電話號碼驗證碼。 | +| POST | [/api/verifications/verification-code/verify](https://openapi.logto.io/operation/operation-verifyverificationbyverificationcode) | 透過驗證碼驗證電子郵件或電話號碼。 | ### 使用者密碼管理 \{#user-password-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------- | -| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 依 user ID 驗證目前使用者密碼。 | -| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 依 user ID 更新使用者密碼。 | -| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 依 user ID 檢查使用者是否設有密碼。 | +| 方法 | 路徑 | 描述 | +| ----- | -------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| POST | [/api/users/\{userId\}/password/verify](https://openapi.logto.io/operation/operation-verifyuserpassword) | 根據使用者 ID 驗證當前使用者密碼。 | +| PATCH | [/api/users/\{userId\}/password](https://openapi.logto.io/operation/operation-updateuserpassword) | 根據使用者 ID 更新使用者密碼。 | +| GET | [/api/users/\{userId\}/has-password](https://openapi.logto.io/operation/operation-getuserhaspassword) | 根據使用者 ID 檢查使用者是否有密碼。 | :::note -請務必在更新使用者密碼前，先驗證使用者目前密碼。 +在更新使用者密碼之前，請確保已驗證使用者的當前密碼。 ::: ### 使用者社交身分管理 \{#user-social-identities-management} -| method | path | description | -| ------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 依 user ID 取得使用者詳細資料。社交身分可於 `identities` 欄位中找到。 | -| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 依 user ID 綁定已驗證的社交身分。 | -| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 依 user ID 解除綁定社交身分。 | -| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 依 user ID 直接更新已綁定的社交身分。 | -| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 取得社交身分提供者的授權 URI。使用此 URI 發起新的社交身分連結流程。 | +| 方法 | 路徑 | 描述 | +| ------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| GET | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-getuser) | 根據使用者 ID 獲取使用者詳細資料。社交身分可在 `identities` 欄位中找到。 | +| POST | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-createuseridentity) | 根據使用者 ID 將已驗證的社交身分連結到使用者。 | +| DELETE | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-deleteuseridentity) | 根據使用者 ID 將社交身分從使用者中解除連結。 | +| PUT | [/api/users/\{userId\}/identities](https://openapi.logto.io/operation/operation-replaceuseridentity) | 根據使用者 ID 直接更新已連結到使用者的社交身分。 | +| POST | [/api/connectors/\{connectorId\}/authorization-uri](https://openapi.logto.io/operation/operation-createconnectorauthorizationuri) | 獲取社交身分提供者的授權 URI。使用此 URI 來啟動新的社交身分連結。 | ```mermaid sequenceDiagram autoNumber - participant User as 使用者 (User) - participant Client as 用戶端應用程式 (Client app) - participant App as 伺服器應用程式 (server app) + participant User as 使用者 + participant Client as 客戶端應用程式 + participant App as 伺服器應用程式 participant Logto as Logto - participant IdP as 社交身分提供者 (Social identity provider) + participant IdP as 社交身分提供者 - User ->> Client: 存取用戶端應用程式並請求綁定社交身分 - Client ->> App: 發送綁定社交身分請求 + User ->> Client: 存取客戶端應用程式請求綁定社交身分 + Client ->> App: 發送請求綁定社交身分 App ->> Logto: POST /api/connectors/{connectorId}/authorization-uri Logto ->> App: 授權 URI - App ->> Client: 回傳授權 URI - Client ->> IdP: 重新導向至 IdP 授權頁面 + App ->> Client: 返回授權 URI + Client ->> IdP: 重定向至 IdP 授權頁面 User -->> IdP: 登入 IdP - IdP ->> Client: 以授權碼導回用戶端應用程式 - Client ->> Server: 綁定社交身分請求，轉發 IdP 授權回應 + IdP ->> Client: 使用授權碼重定向至客戶端應用程式 + Client ->> Server: 連結社交身分請求，轉發 IdP 授權回應 Server ->> Logto: POST /api/users/{userId}/identities - Logto ->> IdP: 以授權碼向 IdP 取得使用者資訊 - IdP ->> Logto: 回傳使用者資訊 + Logto ->> IdP: 使用授權碼從 IdP 獲取使用者資訊 + IdP ->> Logto: 返回使用者資訊 ``` -1. 使用者存取用戶端應用程式並請求綁定社交身分。 -2. 用戶端應用程式向伺服器發送綁定社交身分請求。 -3. 伺服器向 Logto 請求取得社交身分提供者的授權 URI。你需在請求中提供自訂 `state` 參數與 `redirect_uri`，並確保已在社交身分提供者註冊該 `redirect_uri`。 -4. Logto 回傳授權 URI 給伺服器。 -5. 伺服器將授權 URI 回傳給用戶端應用程式。 -6. 用戶端應用程式將使用者導向至 IdP 授權 URI。 +1. 使用者存取客戶端應用程式並請求綁定社交身分。 +2. 客戶端應用程式向伺服器發送請求以綁定社交身分。 +3. 伺服器向 Logto 發送請求以獲取社交身分提供者的授權 URI。你需要在請求中提供自己的 `state` 參數和 `redirect_uri`。確保在社交身分提供者中註冊 `redirect_uri`。 +4. Logto 將授權 URI 返回給伺服器。 +5. 伺服器將授權 URI 返回給客戶端應用程式。 +6. 客戶端應用程式將使用者重定向至 IdP 授權 URI。 7. 使用者登入 IdP。 -8. IdP 以 `redirect_uri` 及授權碼將使用者導回用戶端應用程式。 -9. 用戶端應用程式驗證 `state` 並將 IdP 授權回應轉發給伺服器。 -10. 伺服器向 Logto 發送請求，將社交身分綁定至使用者。 -11. Logto 以授權碼向 IdP 取得使用者資訊。 -12. IdP 回傳使用者資訊給 Logto，Logto 完成社交身分綁定。 +8. IdP 使用 `redirect_uri` 和授權碼將使用者重定向回客戶端應用程式。 +9. 客戶端應用程式驗證 `state` 並將 IdP 授權回應轉發給伺服器。 +10. 伺服器向 Logto 發送請求以將社交身分連結到使用者。 +11. Logto 使用授權碼從 IdP 獲取使用者資訊。 +12. IdP 將使用者資訊返回給 Logto，Logto 將社交身分連結到使用者。 :::note -透過 Management API 綁定新社交身分時需注意以下限制： +在將新社交身分連結到使用者時，有一些限制需要考慮： -- Management API 無任何 session 上下文，任何需主動 session 以安全維護社交驗證狀態的社交連接器皆無法透過 Management API 綁定。不支援的連接器包含 apple、標準 OIDC 及標準 OAuth 2.0 連接器。 -- 同理，Logto 無法驗證授權回應中的 `state` 參數。請務必在用戶端應用程式儲存 `state` 並於收到授權回應時驗證。 -- 你需預先將 `redirect_uri` 註冊至社交身分提供者。否則，社交 IdP 將無法將使用者導回你的用戶端應用程式。你的社交 IdP 必須允許多個 callback `redirect_uri`，一個用於使用者登入，一個用於個人資料綁定頁面。 +- Management API 沒有任何會話上下文，任何需要活動會話以安全維護社交驗證狀態的社交連接器都不能通過 Management API 連結。不支援的連接器包括 apple、標準 OIDC 和標準 OAuth 2.0 連接器。 +- 出於同樣的原因，Logto 無法驗證授權回應中的 `state` 參數。確保在客戶端應用程式中儲存 `state` 參數，並在收到授權回應時進行驗證。 +- 你需要提前在社交身分提供者中註冊 `redirect_uri`。否則，社交 IdP 不會將使用者重定向回你的客戶端應用程式。你的社交 IdP 必須接受多個回調 `redirect_uri`，一個用於使用者登入，一個用於你自己的資料綁定頁面。 ::: ### 使用者企業身分管理 \{#user-enterprise-identities-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 依 user ID 取得使用者詳細資料。企業身分可於 `ssoIdentities` 欄位中找到。於使用者詳細資料 API 加上 `includeSsoIdentities=true` 查詢參數即可取得。 | +| 方法 | 路徑 | 描述 | +| ---- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| GET | [/api/users/\{userId\}?includeSsoIdentities=true](https://openapi.logto.io/operation/operation-getuser) | 根據使用者 ID 獲取使用者詳細資料。企業身分可在 `ssoIdentities` 欄位中找到。將 `includeSsoIdentities=true` 查詢參數添加到使用者詳細資料 API 中以包含它們。 | -目前 Management API 尚不支援將企業身分綁定或解除綁定至使用者。你僅能顯示已綁定的企業身分。 +目前，Management API 不支援將企業身分連結或解除連結到使用者。你只能顯示已連結到使用者的企業身分。 -### 個人存取權杖 (Personal access token) \{#personal-access-token} +### 個人存取權杖 \{#personal-access-token} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- | -| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | 取得使用者所有個人存取權杖 (Personal access tokens)。 | -| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | 新增使用者個人存取權杖 (Personal access token)。 | -| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 依名稱刪除使用者權杖。 | -| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 依名稱更新使用者權杖。 | +| 方法 | 路徑 | 描述 | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | +| GET | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-listuserpersonalaccesstokens) | 獲取使用者的所有個人存取權杖。 | +| POST | [/api/users/\{userId\}/personal-access-tokens](https://openapi.logto.io/operation/operation-createuserpersonalaccesstoken) | 為使用者新增個人存取權杖。 | +| DELETE | [/api/users/\{userId\}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-deleteuserpersonalaccesstoken) | 根據名稱刪除使用者的權杖。 | +| PATCH | [/api/users/\{userId\s}/personal-access-tokens/\{name\}](https://openapi.logto.io/operation/operation-updateuserpersonalaccesstoken) | 根據名稱更新使用者的權杖。 | -個人存取權杖 (Personal access tokens) 提供使用者在不需輸入憑證與互動式登入的情況下，安全授權 [存取權杖 (Access token)](https://auth.wiki/access-token)。詳情請參閱 [使用個人存取權杖](/user-management/personal-access-token)。 +個人存取權杖為使用者提供了一種安全的方式來授予 [存取權杖 (Access token)](https://auth.wiki/access-token)，而無需使用其憑證和互動式登入。了解更多關於 [使用個人存取權杖](/user-management/personal-access-token)。 -### 使用者多重要素驗證 (MFA) 設定管理 \{#user-mfa-settings-management} +### 使用者 MFA 設定管理 \{#user-mfa-settings-management} -| method | path | description | -| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | -| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | 依 user ID 取得使用者 MFA 設定。 | -| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | 依 user ID 設定使用者 MFA 驗證。 | -| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | 依 ID 刪除使用者 MFA 驗證。 | +| 方法 | 路徑 | 描述 | +| ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | +| GET | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-listusermfaverifications) | 根據使用者 ID 獲取使用者 MFA 設定。 | +| POST | [/api/users/\{userId\}/mfa-verifications](https://openapi.logto.io/operation/operation-createusermfaverification) | 根據使用者 ID 設定使用者 MFA 驗證。 | +| DELETE | [/api/users/\{userId\}/mfa-verifications/\{verificationId\}](https://openapi.logto.io/operation/operation-deleteusermfaverification) | 根據 ID 刪除使用者 MFA 驗證。 | ### 使用者帳戶刪除 \{#user-account-deletion} -| method | path | description | -| ------ | -------------------------------------------------------------------------------- | ----------------------- | -| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | 依 user ID 刪除使用者。 | +| 方法 | 路徑 | 描述 | +| ------ | -------------------------------------------------------------------------------- | -------------------------- | +| DELETE | [/api/users/\{userId\}](https://openapi.logto.io/operation/operation-deleteuser) | 根據使用者 ID 刪除使用者。 | -### 使用者工作階段管理 \{#user-session-management} +### 使用者會話管理 \{#user-session-management} -| method | path | description | -| ------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | 依 user ID 取得使用者工作階段。 | -| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | 依 session ID 取得使用者工作階段。 | -| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | 依 session ID 刪除使用者工作階段。 | +| 方法 | 路徑 | 描述 | +| ------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| GET | [/api/users/\{userId\}/sessions](https://openapi.logto.io/operation/operation-listusersessions) | 根據使用者 ID 獲取使用者會話。 | +| GET | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-getusersession) | 根據會話 ID 獲取使用者會話。 | +| DELETE | [/api/users/\{userId\}/sessions/\{sessionId\}](https://openapi.logto.io/operation/operation-deleteusersession) | 根據會話 ID 刪除使用者會話。 | + +### 管理使用者授權的應用程式（授權）\{#manage-user-authorized-apps-grants} + +| 方法 | 路徑 | 描述 | +| ------ | -------------------------------------------------------------------------------------------------------- | ------------------------------ | +| GET | [/api/users/\{userId\}/grants](https://openapi.logto.io/operation/operation-listusergrants) | 列出使用者的活動應用程式授權。 | +| DELETE | [/api/users/\{userId\}/grants/\{grantId\}](https://openapi.logto.io/operation/operation-deleteusergrant) | 根據 ID 撤銷特定應用程式授權。 | + +授權列表的可選查詢參數： + +- `appType=firstParty`：僅返回第一方應用程式授權。 +- `appType=thirdParty`：僅返回第三方應用程式授權。 +- 省略 `appType`：返回所有活動授權。 + +當授權被撤銷時，先前發出的不透明存取權杖和重新整理權杖將失效。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx index 6313d904c7e..cffd56412f0 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/sign-out.mdx @@ -1,235 +1,101 @@ --- -sidebar_position: 8 +sidebar_position: 7.5 --- -# 登出 (Sign-out) +# 登出 -在 Logto（作為 OIDC 身分提供者）中，登出涉及： +在 Logto 中，登出涉及兩個層面： -- **集中式 Logto 工作階段**（Logto 網域下的瀏覽器 cookie），以及 -- **分散式用戶端驗證狀態**（每個應用程式中的權杖和本地應用程式工作階段）。 +- **Logto 會話登出**：結束在 Logto 網域下的集中登入會話。 +- **應用程式登出**：清除客戶端應用程式中的本地會話狀態和權杖。 -為了理解登出行為，建議將這兩層分開，並了解 **授權單元 (grants)** 如何連結它們。 +若要更好地理解 Logto 中的會話運作方式，請參閱 [Sessions](/sessions)。 -## 核心概念 \{#core-concepts} - -### 什麼是 Logto 工作階段？ \{#what-is-a-logto-session} - -Logto 工作階段是由 Logto 管理的集中式登入狀態。它在驗證成功後建立，並以 Logto 網域下的 cookie 表示。 - -如果工作階段 cookie 有效，使用者可以在多個信任同一 Logto 租戶的應用程式間靜默驗證（單一登入，SSO）。 - -若不存在有效的工作階段，Logto 會顯示登入頁面。 - -### 什麼是授權單元 (grants)？ \{#what-are-grants} - -**授權單元 (grant)** 代表特定使用者 + 用戶端應用程式組合的授權狀態。 - -- 一個 Logto 工作階段可以擁有多個用戶端應用程式的授權單元。 -- 授權單元是已發行權杖所關聯的對象。 -- 在本文件集中，**授權單元 (grant)** 作為跨應用程式的授權單位。 - -### 工作階段、授權單元與用戶端驗證狀態的關係 \{#how-session-grants-and-client-auth-status-relate} - -```mermaid -flowchart LR - subgraph Logto [Logto 網域] - S[Logto 工作階段 (Logto session)] - G1[App A 的授權單元 (Grant for App A)] - G2[App B 的授權單元 (Grant for App B)] - end - - subgraph AppA [用戶端網域 A] - A[本地工作階段 / 權杖 (Local session / tokens)] - end - - subgraph AppB [用戶端網域 B] - B[本地工作階段 / 權杖 (Local session / tokens)] - end - - S --> G1 - S --> G2 - G1 --> A - G2 --> B -``` - -- **Logto 工作階段** 控制集中式單一登入 (SSO) 體驗。 -- **用戶端本地工作階段 / 權杖** 控制每個應用程式是否將使用者視為已登入。 -- **授權單元 (grants)** 透過代表應用程式專屬授權狀態，連結這兩個世界。 - -## 登入回顧（為什麼登出是多層次的） \{#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 提供者 (OIDC provider) - participant SignIn as 登入頁面 (Sign-in page) - end - - User ->> Client: 存取應用程式 (Access application) - Client ->> OIDC: 重新導向進行驗證 (Redirect for authentication) - OIDC -->> OIDC: 檢查 Logto 工作階段 (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} - -### 共用工作階段 cookie（同一瀏覽器 / 使用者代理） \{#shared-session-cookie-same-browser-user-agent} - -若使用者從同一瀏覽器登入多個應用程式，這些應用程式可重用同一 Logto 工作階段 cookie，並享有單一登入 (SSO) 行為。 - -```mermaid -flowchart TD - U[使用者 (User)] - A["用戶端應用程式 A (Client domain A)"] - B["用戶端應用程式 B (Client domain B)"] - C{"Logto 工作階段存在？ (Logto domain)"} - D["登入頁面 (Logto domain)"] - - subgraph UA["使用者代理 A (同一瀏覽器)"] - U - A - B - C - D - end - - U -->|登入| A - A -->|重新導向至 Logto| C - U -->|開啟應用程式| B - B -->|重新導向至 Logto| C - C -->|否| D - D -->|建立工作階段| C -``` - -### 隔離的工作階段 cookie（不同裝置 / 瀏覽器） \{#isolated-session-cookies-different-devices-browsers} +## 登出機制 \{#sign-out-mechanisms} -不同瀏覽器 / 裝置持有不同的 Logto cookie，因此登入工作階段彼此隔離。 +### 1) 僅客戶端登出 \{#1-client-side-only-sign-out} -```mermaid -flowchart TD - U[使用者 (User)] - A["用戶端應用程式 A (Client domain A)"] - C{"Logto 工作階段存在？ (Device A, Logto domain)"} - D["登入頁面 (Device A, Logto domain)"] - - subgraph DeviceA["使用者代理 A"] - A - C - D - end - - B["用戶端應用程式 B (Client domain B)"] - E{"Logto 工作階段存在？ (Device B, Logto domain)"} - F["登入頁面 (Device B, Logto domain)"] - - subgraph DeviceB["使用者代理 B"] - B - E - F - end - - U -->|登入| A - A -->|重新導向至 Logto| C - U -->|登入| B - B -->|重新導向至 Logto| E - C -->|否| D - E -->|否| F - D -->|建立工作階段| C - F -->|建立工作階段| E -``` +客戶端應用程式清除其本地會話和權杖（ID 權杖 / 存取權杖 / 重新整理權杖）。這僅登出該應用程式的本地狀態。 -## 登出機制 \{#sign-out-mechanisms} +- Logto 會話可能仍然有效。 +- 其他在相同 Logto 會話下的應用程式可能仍可單一登入 (SSO)。 -### 1) 僅用戶端登出 \{#1-client-side-only-sign-out} +### 2) 在 Logto 結束會話（目前 Logto 實作中的全域登出） \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} -用戶端應用程式清除自身本地工作階段與權杖（ID / 存取 / 重新整理權杖）。這僅將使用者從該應用程式的本地狀態登出。 +要清除集中式 Logto 會話，應用程式將使用者重定向到結束會話端點，例如： -- Logto 工作階段可能仍然有效。 -- 其他同一 Logto 工作階段下的應用程式仍可單一登入 (SSO)。 +`https://{your-logto-domain}/oidc/session/end` -### 2) Logto 端結束工作階段（目前 Logto 實作下的全域登出） \{#2-end-session-at-logto-global-sign-out-in-current-logto-implementation} +在目前 Logto SDK 的行為中： -若要清除集中式 Logto 工作階段，應用程式會將使用者重新導向至結束工作階段端點，例如： +1. `signOut()` 會重定向到 `/session/end`。 +2. 然後進入 `/session/end/confirm`。 +3. 預設確認表單自動提交 `logout=true`。 -`https://{your-logto-domain}/oidc/session/end` +因此，目前的 SDK 登出被視為 **全域登出**。 -目前 Logto SDK 行為如下： +:::note -1. `signOut()` 會重新導向至 `/session/end`。 -2. 接著進入 `/session/end/confirm`。 -3. 預設確認表單會自動提交 `logout=true`。 +- **全域登出**：撤銷集中式 Logto 會話。 -因此，目前 SDK 的登出被視為 **全域登出**。 +::: -### 全域登出時會發生什麼事 \{#what-happens-during-global-sign-out} +### 全域登出期間發生的情況 \{#what-happens-during-global-sign-out} ```mermaid flowchart TD - A["用戶端啟動登出 (Client starts sign-out)"] --> B["/session/end"] + A["客戶端開始登出"] --> B["/session/end"] B --> C["/session/end/confirm (logout=true)"] - C --> D["撤銷集中式 Logto 工作階段 (Revoke centralized Logto session)"] - D --> E{"檢查每個應用程式授權單元 (Check per-app grant)"} - E -->|"未授予 offline_access"| F["撤銷授權單元 (Revoke grant)"] - E -->|"已授予 offline_access"| G["保留授權單元直到 TTL 到期 (Keep grant until grant TTL expires)"] + C --> D["撤銷集中式 Logto 會話"] + D --> E{"檢查每個應用程式授權"} + E -->|"未授予 offline_access"| F["撤銷授權"] + E -->|"已授予 offline_access"| G["保留授權直到授權 TTL 到期"] ``` -全域登出期間： +在全域登出期間： -- 集中式 Logto 工作階段會被撤銷。 -- 相關應用程式授權單元依應用程式授權狀態處理： - - 若 **未**授予 `offline_access`，相關授權單元會被撤銷。 - - 若 **已**授予 `offline_access`，結束工作階段不會撤銷該授權單元。 -- 對於 `offline_access` 情境，重新整理權杖與授權單元會持續有效，直到授權單元到期。 +- 集中式 Logto 會話被撤銷。 +- 相關應用程式授權根據每個應用程式的授權狀態處理： + - 若 **未** 授予 `offline_access`，相關授權被撤銷。 + - 若 **已** 授予 `offline_access`，結束會話不會撤銷授權。 +- 對於 `offline_access` 的情況，重新整理權杖和授權在授權到期前仍然有效。 -## 授權單元存續時間與 `offline_access` 影響 \{#grant-lifetime-and-offline-access-impact} +## 授權有效期與 `offline_access` 影響 \{#grant-lifetime-and-offline-access-impact} -- Logto 預設授權單元 TTL 為 **180 天**。 -- 若授予 `offline_access`，結束工作階段預設不會撤銷該應用程式授權單元。 -- 與該授權單元關聯的重新整理權杖可持續使用，直到授權單元到期（或被明確撤銷）。 +- 預設 Logto 授權 TTL 為 **180 天**。 +- 若授予 `offline_access`，結束會話預設不會撤銷該應用程式授權。 +- 與該授權相關的重新整理權杖鏈可持續運行，直到授權到期（或被明確撤銷）。 -## 聯合登出：後端通道登出 (back-channel logout) \{#federated-sign-out-back-channel-logout} +## 聯邦登出：後端通道登出 \{#federated-sign-out-back-channel-logout} -為了跨應用程式一致性，Logto 支援 [後端通道登出 (back-channel logout)](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)。 +為了跨應用程式的一致性，Logto 支援 [後端通道登出](https://openid.net/specs/openid-connect-backchannel-1_0-final.html)。 -當使用者從某個應用程式登出時，Logto 會向所有參與同一工作階段的應用程式發送登出權杖至其註冊的後端通道登出 URI。 +當使用者從一個應用程式登出時，Logto 可以透過向每個應用程式註冊的後端通道登出 URI 發送登出權杖，通知參與相同會話的所有應用程式。 -若應用程式後端通道設定中啟用 `Is session required`，登出權杖會包含 `sid` 以識別 Logto 工作階段。 +如果在應用程式的後端通道設定中啟用了 `Is session required`，則登出權杖會包含 `sid` 以識別 Logto 會話。 典型流程： -1. 使用者從某個應用程式啟動登出。 -2. Logto 處理結束工作階段，並向註冊的後端通道登出 URI 發送登出權杖。 -3. 各應用程式驗證登出權杖並清除自身本地工作階段 / 權杖。 +1. 使用者從一個應用程式啟動登出。 +2. Logto 處理結束會話並向註冊的後端通道登出 URI 發送登出權杖。 +3. 每個應用程式驗證登出權杖並清除其本地會話 / 權杖。 -## Logto SDK 的登出方法 \{#sign-out-methods-in-logto-sdks} +## Logto SDK 中的登出方法 \{#sign-out-methods-in-logto-sdks} -- **SPA 與網頁**：`client.signOut()` 會清除本地權杖儲存並重新導向至 Logto 結束工作階段端點。你可以提供登出後重新導向 URI。 -- **原生（包含 React Native / Flutter）**：通常僅清除本地權杖儲存。無持久 Logto 瀏覽器 cookie 可清除（sessionless webview）。 +- **SPA 和網頁**：`client.signOut()` 清除本地權杖存儲並重定向到 Logto 結束會話端點。你可以提供登出後重定向 URI。 +- **原生應用程式（包括 React Native / Flutter）**：通常僅清除本地權杖存儲。無會話的 webview 意味著沒有持久的 Logto 瀏覽器 cookie 需要清除。 :::note -對於不支援 sessionless webview 或未識別 `emphasized` 設定的原生應用程式（如 **React Native** 或 **Flutter** SDK 的 Android 應用程式），你可以在驗證請求中傳遞 `prompt=login` 參數，強制使用者再次登入。 +對於不支援無會話 webview 或不識別 `emphasized` 設定的原生應用程式（使用 **React Native** 或 **Flutter** SDK 的 Android 應用程式），你可以在授權請求中傳遞 `prompt=login` 參數來強制使用者再次登入。 ::: -## 強制每次存取都重新驗證 \{#enforce-re-authentication-on-every-access} +## 強制每次存取重新驗證 \{#enforce-re-authentication-on-every-access} -對於高安全性操作，在驗證請求中加入 `prompt=login`，可繞過 SSO 並每次強制輸入憑證。 +對於高安全性操作，在驗證請求中包含 `prompt=login` 以繞過 SSO 並每次強制輸入憑證。 -若請求 `offline_access`（以取得重新整理權杖），也請加入 `consent`，即 `prompt=login consent`。 +如果請求 `offline_access`（以接收重新整理權杖），也包含 `consent`，`prompt=login consent`。 -典型組合設定： +典型的組合設定： ```txt prompt=login consent @@ -244,13 +110,11 @@ prompt=login consent -- 請確認後端通道登出 URI 已正確註冊於 Logto 控制台。 -- 請確認你的應用程式對同一使用者 / 工作階段上下文有有效登入狀態。 +- 確保後端通道登出 URI 已正確註冊在 Logto 控制台。 +- 確保你的應用程式對相同使用者 / 會話上下文有活動的登入狀態。 ## 相關資源 \{#related-resources} - - 理解 OIDC 後端通道登出 (Understanding OIDC back-channel logout)。 - +理解 OIDC 後端通道登出。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx index 50acb176ef1..5856db9e6cc 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/integrate-logto/application-data-structure.mdx @@ -1,5 +1,5 @@ --- -description: 參考 OIDC 驗證 (Authentication) 整合所需的關鍵應用程式參數，包括 redirect URI、端點、重新整理權杖 (Refresh token)、後端登出 (Backchannel logout) 等。 +description: 參考 OIDC 驗證整合的關鍵應用程式參數，包括 redirect URIs、端點、重新整理權杖、後台登出等。 sidebar_position: 6 --- @@ -7,178 +7,194 @@ sidebar_position: 6 ## 簡介 \{#introduction} -在 Logto 中，_應用程式_ 指的是已註冊於 Logto 平台，並獲授權可存取使用者資訊或代表使用者執行操作的特定軟體程式或服務。應用程式用於識別向 Logto API 發出的請求來源，以及管理使用者存取這些應用程式時的驗證 (Authentication) 與授權 (Authorization) 流程。 +在 Logto 中，_應用程式_ 指的是在 Logto 平台上註冊並獲得授權以存取使用者資訊或代表使用者執行操作的特定軟體程式或服務。應用程式用於識別向 Logto API 發出的請求來源，並管理使用者存取這些應用程式的驗證和授權過程。 -在 Logto 的登入體驗 (Sign-in experience) 中使用應用程式，讓使用者能從單一位置輕鬆存取並管理其已授權的應用程式，並享有一致且安全的驗證流程。這有助於簡化使用者體驗，並確保只有授權個體能存取敏感資訊或代表組織執行操作。 +在 Logto 的登入體驗中使用應用程式，讓使用者能夠從單一位置輕鬆存取和管理其授權的應用程式，並提供一致且安全的驗證過程。這有助於簡化使用者體驗，確保只有授權的個人能夠存取敏感資訊或代表組織執行操作。 -應用程式也用於 Logto 的稽核日誌 (Audit logs) 中，以追蹤使用者活動並識別潛在的安全威脅或漏洞。透過將特定操作與特定應用程式關聯，Logto 能提供資料存取與使用的詳細洞察，協助組織更好地管理其安全性與合規需求。 -若你想將應用程式與 Logto 整合，請參閱 [整合 Logto](/integrate-logto)。 +應用程式也用於 Logto 的審計日誌中，以追蹤使用者活動並識別任何潛在的安全威脅或漏洞。透過將特定操作與特定應用程式關聯，Logto 可以提供有關資料如何被存取和使用的詳細見解，讓組織更好地管理其安全性和合規性要求。如果你想將應用程式與 Logto 整合，請參閱 [整合 Logto](/integrate-logto)。 ## 屬性 \{#properties} ### 應用程式 ID \{#application-id} -_應用程式 ID_ 是用於識別你在 Logto 中應用程式的唯一自動產生金鑰，在 OAuth 2.0 中稱為 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)。 +_應用程式 ID_ 是一個自動生成的唯一鍵，用於在 Logto 中識別你的應用程式，在 OAuth 2.0 中被稱為 [client id](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/)。 ### 應用程式類型 \{#application-types} -_應用程式_ 可為下列其中一種應用程式類型： +_應用程式_ 可以是以下應用程式類型之一： -- **原生應用程式 (Native app)**：運行於原生環境的應用程式。例如 iOS app、Android app。 - - **裝置流程應用程式 (Device flow app)**：專為輸入受限裝置或無頭應用（如智慧電視、遊戲主機、CLI 工具、IoT 裝置）設計的特殊原生應用程式。它使用 [OAuth 2.0 Device Authorization Grant](https://auth.wiki/device-flow) 取代標準的重導向流程。詳情請參閱 [Device flow 快速入門](/quick-starts/device-flow)。 -- **單頁應用程式 (Single page app)**：運行於網頁瀏覽器中，能在不重新載入整個頁面的情況下更新伺服器資料的應用程式。例如 React DOM app、Vue app。 -- **傳統網頁應用程式 (Traditional web app)**：僅由網頁伺服器渲染與更新頁面的應用程式。例如 JSP、PHP。 -- **機器對機器 (M2M) 應用程式**：運行於機器環境、無需使用者互動即可進行服務對服務通訊的應用程式。 +- **原生應用程式** 是在原生環境中運行的應用程式。例如，iOS 應用程式、Android 應用程式。 + - **裝置流應用程式** 是一種特殊類型的原生應用程式，適用於輸入受限的裝置或無頭應用程式（例如，智慧電視、遊戲主機、CLI 工具、IoT 裝置）。它使用 [OAuth 2.0 裝置授權授予](https://auth.wiki/device-flow) 而非標準的重定向流程。詳情請參閱 [裝置流快速入門](/quick-starts/device-flow)。 +- **單頁應用程式** 是在網頁瀏覽器中運行的應用程式，透過從伺服器獲取新資料來更新頁面，而不需加載整個新頁面。例如，React DOM 應用程式、Vue 應用程式。 +- **傳統網頁應用程式** 是由網頁伺服器單獨渲染和更新頁面的應用程式。例如，JSP、PHP。 +- **機器對機器 (M2M) 應用程式** 是在機器環境中運行的應用程式，用於直接的服務對服務通信，無需使用者互動。 ### 應用程式密鑰 \{#application-secret} -_應用程式密鑰_ 是用於驗證 (Authentication) 系統中應用程式身分的金鑰，專為私有客戶端（傳統網頁與 M2M 應用程式）作為私密安全屏障。 +_應用程式密鑰_ 是用於在驗證系統中驗證應用程式的密鑰，特別是針對私有客戶端（傳統網頁和 M2M 應用程式）作為私有安全屏障。 :::tip -單頁應用程式 (SPA) 與原生應用程式不提供應用程式密鑰。SPA 與原生應用程式屬於「公開客戶端」，無法安全保存密鑰（瀏覽器程式碼或應用程式包可被檢查）。Logto 以 PKCE、嚴格的 redirect URI / CORS 驗證、短效存取權杖 (Access token) 與重新整理權杖 (Refresh token) 輪替來保護這些應用程式。 +單頁應用程式 (SPA) 和原生應用程式不提供應用程式密鑰。SPA 和原生應用程式是「公共客戶端」，無法保密（瀏覽器代碼或應用程式包可被檢查）。Logto 透過 PKCE、嚴格的 redirect URI/CORS 驗證、短期存取權杖和重新整理權杖輪換來保護它們。 ::: ### 應用程式名稱 \{#application-name} -_應用程式名稱_ 是應用程式的人類可讀名稱，會顯示於管理主控台。 +_應用程式名稱_ 是應用程式的人類可讀名稱，將顯示在管理控制台中。 -_應用程式名稱_ 是 Logto 應用程式管理的重要組成部分，讓管理員能輕鬆識別並追蹤平台內各應用程式的活動。 +_應用程式名稱_ 是在 Logto 中管理應用程式的重要組成部分，因為它允許管理員輕鬆識別和追蹤平台中各個應用程式的活動。 :::note -請注意，_應用程式名稱_ 應謹慎選擇，因為所有有權存取管理主控台的使用者都能看到。名稱應準確反映應用程式的用途與功能，並易於理解與辨識。 +需要注意的是，_應用程式名稱_ 應謹慎選擇，因為它將對所有有權訪問管理控制台的使用者可見。它應準確反映應用程式的目的和功能，同時易於理解和識別。 ::: ### 描述 \{#description} -應用程式的簡要描述會顯示於管理主控台的應用程式詳細頁。描述旨在為管理員提供應用程式的額外資訊，例如用途、功能及其他相關細節。 +應用程式的簡短描述將顯示在管理控制台的應用程式詳細資訊頁面上。描述旨在為管理員提供有關應用程式的其他資訊，例如其目的、功能和任何其他相關細節。 -### Redirect URI \{#redirect-uris} +### Redirect URIs \{#redirect-uris} -_Redirect URI_ 是預先為應用程式設定的一組有效重導向 URI。當使用者登入 Logto 並嘗試存取應用程式時，會被重導向至應用程式設定中允許的 URI 之一。 +_Redirect URIs_ 是為應用程式預先配置的一組有效的重定向 URI。當使用者登入 Logto 並嘗試訪問應用程式時，他們將被重定向到應用程式設定中指定的允許 URI 之一。 -允許的 URI 清單用於驗證應用程式在驗證 (Authentication) 流程中發送給 Logto 的授權請求所包含的 redirect URI。若授權請求中的 redirect URI 與應用程式設定中的允許 URI 之一相符，則使用者驗證成功後會被重導向至該 URI。若 redirect URI 不在允許清單中，則不會重導向，驗證流程將失敗。 +允許的 URI 列表用於驗證應用程式在驗證過程中發送給 Logto 的授權請求中包含的重定向 URI。如果授權請求中指定的重定向 URI 與應用程式設定中的允許 URI 之一匹配，則使用者在成功驗證後將被重定向到該 URI。如果重定向 URI 不在允許列表中，則使用者將不會被重定向，驗證過程將失敗。 :::note -請確保所有有效的 redirect URI 都已加入 Logto 應用程式的允許清單，以確保使用者驗證後能順利存取應用程式。 +確保所有有效的重定向 URI 都已添加到 Logto 中應用程式的允許列表中，以確保使用者在驗證後能夠成功訪問應用程式。 ::: -你可以參考 [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) 以獲得更多資訊。 +你可以查看 [Redirection endpoint](https://datatracker.ietf.org/doc/html/rfc6749#section-3.1.2) 以獲取更多資訊。 - 了解 OIDC 授權碼流程中的 Redirect URI + 理解 OIDC 中的重定向 URI 與授權碼流程 -#### 萬用字元模式 \{#wildcard-patterns} +#### 通配符模式 \{#wildcard-patterns} -_適用範圍：單頁應用程式、傳統網頁應用程式_ +_可用性：單頁應用程式、傳統網頁應用程式_ -Redirect URI 支援萬用字元（`*`）模式，適用於如預覽部署等動態環境。萬用字元可用於 HTTP / HTTPS URI 的主機名稱與路徑部分。 +重定向 URI 支援通配符模式 (`*`) 用於動態環境，例如預覽部署。通配符可以用於 HTTP/HTTPS URI 的主機名和路徑名組件。 **規則：** -- 僅允許在主機名稱與路徑中使用萬用字元 -- 不允許在協定、連接埠、查詢參數或 hash fragment 中使用萬用字元 -- 主機名稱萬用字元必須包含至少一個點（例如 `https://*.example.com/callback`） +- 通配符僅允許在主機名和路徑名中使用 +- 通配符不允許在協議、端口、查詢參數或哈希片段中使用 +- 主機名通配符必須至少包含一個點（例如，`https://*.example.com/callback`） **範例：** -- `https://*.example.com/callback` - 匹配任何子網域 +- `https://*.example.com/callback` - 匹配任何子域 - `https://preview-*.example.com/callback` - 匹配預覽部署 -- `https://example.com/*/callback` - 匹配任一路徑段 +- `https://example.com/*/callback` - 匹配任何路徑段 :::caution -萬用字元 redirect URI 並非標準 OIDC，且可能增加攻擊面。請謹慎使用，並盡可能優先使用精確的 redirect URI。 +通配符重定向 URI 不是標準 OIDC，可能增加攻擊面。請謹慎使用，並在可能的情況下優先使用精確的重定向 URI。 ::: -### 登出後重導向 URI \{#post-sign-out-redirect-uris} +### 登出後重定向 URIs \{#post-sign-out-redirect-uris} -_登出後重導向 URI_ 是預先為應用程式設定的一組有效 URI，供使用者自 Logto 登出後重導向。 +_登出後重定向 URIs_ 是為應用程式預先配置的一組有效 URI，用於在使用者從 Logto 登出後重定向使用者。 -允許的 _登出後重導向 URI_ 用於 OIDC 的 RP-Initiated（Relying Party Initiated）Logout 規範。此規範為應用程式發起使用者登出請求提供標準化方法，包含在使用者登出後重導向至預先設定的端點。 +使用允許的 _登出後重定向 URIs_ 是 OIDC 中 RP 發起（Relying Party Initiated）登出規範的一部分。此規範提供了一種標準化的方法，讓應用程式為使用者發起登出請求，這包括在使用者登出後將其重定向到預先配置的端點。 -當使用者自 Logto 登出時，其工作階段將終止，並被重導向至應用程式設定中允許的 URI 之一。這確保使用者僅被導向至授權且有效的端點，避免將使用者重導向至未知或未驗證端點所帶來的未授權存取與安全風險。 +當使用者從 Logto 登出時，他們的會話將被終止，並被重定向到應用程式設定中指定的允許 URI 之一。這確保使用者在登出後僅被引導到授權和有效的端點，幫助防止未經授權的訪問和與重定向使用者到未知或未驗證端點相關的安全風險。 -你可以參考 [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) 以獲得更多資訊。 +你可以查看 [RP-initiated logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout) 以獲取更多資訊。 -### CORS 允許來源 \{#cors-allowed-origins} +### CORS 允許的來源 \{#cors-allowed-origins} -_CORS（跨來源資源共用）允許來源_ 是允許應用程式向 Logto 服務發送請求的來源清單。不在允許清單中的來源將無法對 Logto 服務發送請求。 +_CORS（跨來源資源共享）允許的來源_ 是一組允許的來源，這些來源可以向 Logto 服務發送請求。任何不在允許列表中的來源將無法向 Logto 服務發送請求。 -CORS 允許來源清單用於限制未授權網域對 Logto 服務的存取，並協助防範跨站請求偽造（CSRF）攻擊。透過在 Logto 為應用程式指定允許來源，服務可確保僅授權網域能發送請求。 +CORS 允許的來源列表用於限制未經授權的域對 Logto 服務的訪問，並幫助防止跨站請求偽造（CSRF）攻擊。透過在 Logto 中為應用程式指定允許的來源，服務可以確保只有授權的域能夠向服務發送請求。 :::note -允許來源清單應包含應用程式實際服務的來源。這可確保來自應用程式的請求被允許，而未授權來源的請求則會被阻擋。 +允許的來源列表應包含應用程式將被提供的來源。這確保來自應用程式的請求被允許，而來自未經授權來源的請求被阻止。 ::: -### OpenID 提供者設定端點 \{#openid-provider-configuration-endpoint} +### OpenID 提供者配置端點 \{#openid-provider-configuration-endpoint} [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest) 的端點。 ### 授權端點 \{#authorization-endpoint} -_授權端點 (Authorization Endpoint)_ 是 OIDC 術語，是用於啟動使用者驗證流程的必要端點。當使用者嘗試存取已註冊於 Logto 平台的受保護資源或應用程式時，會被重導向至 _授權端點_ 以驗證身分並取得存取所請求資源的授權。 +_授權端點_ 是 OIDC 的一個術語，是用於啟動使用者驗證過程的必需端點。當使用者嘗試訪問已在 Logto 平台上註冊的受保護資源或應用程式時，他們將被重定向到 _授權端點_ 以驗證其身分並獲得訪問請求資源的授權。 -你可以參考 [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) 以獲得更多資訊。 +你可以查看 [授權端點](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) 以獲取更多資訊。 ### 權杖端點 \{#token-endpoint} -_權杖端點 (Token Endpoint)_ 是 OIDC 術語，是 OIDC 客戶端用來向 OIDC 提供者取得存取權杖 (Access token)、ID 權杖 (ID token) 或重新整理權杖 (Refresh token) 的 Web API 端點。 +_權杖端點_ 是 OIDC 的一個術語，是 OIDC 客戶端用來從 OIDC 提供者獲取存取權杖、ID 權杖或重新整理權杖的 Web API 端點。 -當 OIDC 客戶端需要取得存取權杖或 ID 權杖時，會攜帶授權憑證（通常為授權碼或重新整理權杖）向權杖端點發送請求。權杖端點驗證授權憑證，若有效則發放存取權杖或 ID 權杖給客戶端。 +當 OIDC 客戶端需要獲取存取權杖或 ID 權杖時，它會向權杖端點發送一個授權授予請求，通常是授權碼或重新整理權杖。權杖端點然後驗證授權授予，如果授予有效，則向客戶端發出存取權杖或 ID 權杖。 -你可以參考 [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) 以獲得更多資訊。 +你可以查看 [權杖端點](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) 以獲取更多資訊。 -### Userinfo 端點 \{#userinfo-endpoint} +### 使用者資訊端點 \{#userinfo-endpoint} -OpenID Connect [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 +OpenID Connect [使用者資訊端點](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)。 -### 總是發放重新整理權杖 (Refresh token) \{#always-issue-refresh-token} +### 總是發出重新整理權杖 \{#always-issue-refresh-token} -_適用範圍：傳統網頁、SPA_ +_可用性：傳統網頁、SPA_ -啟用後，Logto 將總是發放重新整理權杖 (Refresh token)，無論驗證請求中是否帶有 `prompt=consent`，或權限範圍 (Scope) 是否包含 `offline_access`。 +啟用後，Logto 將始終發出重新整理權杖，無論驗證請求中是否出現 `prompt=consent`，或權限範圍中是否出現 `offline_access`。 -但除非必要（通常僅第三方 OAuth 整合需重新整理權杖時才有用），否則不建議這麼做，因為這不符合 OpenID Connect 標準，且可能導致問題。 +然而，除非必要（通常對於某些需要重新整理權杖的第三方 OAuth 整合有用），否則不建議這樣做，因為這與 OpenID Connect 不兼容，可能會導致問題。 -### 重新整理權杖 (Refresh token) 輪替 \{#rotate-refresh-token} +### 重新整理權杖輪換 \{#rotate-refresh-token} -_預設值：`true`_ +_預設：`true`_ -啟用後，Logto 會在下列情況下，針對權杖請求發放新的重新整理權杖 (Refresh token)： +啟用後，Logto 將在以下條件下為權杖請求發出新的重新整理權杖： -- 若重新整理權杖已輪替（TTL 已延長）達一年；**或** -- 若重新整理權杖即將到期（已過原始存活時間 (TTL) 的 70% 以上）；**或** -- 若客戶端為公開客戶端，例如原生應用程式或單頁應用程式 (SPA)。 +- 如果重新整理權杖已被輪換（透過發出新權杖延長其 TTL）一年；**或** +- 如果重新整理權杖接近其過期時間（>=70% 的原始存活時間 (TTL) 已過）；**或** +- 如果客戶端是公共客戶端，例如原生應用程式或單頁應用程式 (SPA)。 :::note -對於公開客戶端，啟用此功能後，每當客戶端以重新整理權杖換取新存取權杖時，Logto 都會發放新的重新整理權杖。 -雖然你仍可為這些公開客戶端關閉此功能，但強烈建議為安全考量保持啟用。 +對於公共客戶端，啟用此功能時，當客戶端使用重新整理權杖交換新存取權杖時，將始終發出新的重新整理權杖。 +雖然你仍然可以為這些公共客戶端關閉此功能，但強烈建議出於安全原因保持啟用。 ::: - - 了解重新整理權杖 (Refresh token) 輪替 - +理解重新整理權杖輪換 -### 重新整理權杖 (Refresh token) 存活時間（TTL，天）\{#refresh-token-time-to-live-ttl-in-days} +### 重新整理權杖存活時間 (TTL)（以天為單位）\{#refresh-token-time-to-live-ttl-in-days} -_適用範圍：非 SPA；預設值：14 天_ +_可用性：非 SPA；預設：14 天_ -重新整理權杖可用於請求新存取權杖的有效期間，逾期即失效。每次權杖請求會將重新整理權杖的 TTL 延長至此值。 +重新整理權杖在過期並失效之前可用於請求新存取權杖的時間。權杖請求將把重新整理權杖的 TTL 延長到此值。 -通常建議設較低的值。 +通常，較低的值是首選。 -注意：SPA（單頁應用程式）因安全考量不支援 TTL 延長。這表示 Logto 不會透過權杖請求延長 TTL。為提升使用者體驗，你可啟用「重新整理權杖輪替」功能，讓 Logto 在必要時發放新重新整理權杖。 +注意：出於安全原因，SPA（單頁應用程式）中無法刷新 TTL。這意味著 Logto 不會透過權杖請求延長 TTL。為了提升使用者體驗，你可以啟用「重新整理權杖輪換」功能，允許 Logto 在必要時發出新的重新整理權杖。 -:::caution 重新整理權杖與工作階段綁定 -若在授權請求中**未**帶上 `offline_access` 權限範圍 (Scope) 發放重新整理權杖，該權杖將綁定於使用者工作階段。工作階段 TTL 固定為 **14 天**。工作階段過期後，重新整理權杖即失效，無論其自身 TTL 設定為何。 +:::caution 重新整理權杖和會話綁定 +當在授權請求中**未**包含 `offline_access` 權限範圍時，發出的重新整理權杖將綁定到使用者會話。會話的固定 TTL 為 **14 天**。會話過期後，無論重新整理權杖的 TTL 設定如何，該權杖都將失效。 -若要讓重新整理權杖 TTL 設定完全生效，請確保在授權請求中包含 `offline_access` 權限範圍 (Scope)。 +為確保重新整理權杖 TTL 設定完全生效，請確保在授權請求中包含 `offline_access` 權限範圍。 ::: -### 後端登出 URI \{#backchannel-logout-uri} +### 後台登出 URI \{#backchannel-logout-uri} + +OpenID Connect 後台登出端點。詳情請參閱 [聯邦登出：後台登出](#)。 + +### 最大允許授權 (`maxAllowedGrants`) \{#max-allowed-grants-maxallowedgrants} + +`maxAllowedGrants` 是 `customClientMetadata` 下的一個可選應用程式級別欄位，用於控制當前應用程式中每個使用者的最大並發活動授權數量。 + +- **預設**：`undefined`（無限制） +- **當配置時**：在每次成功授權時，Logto 會檢查當前應用程式中使用者的總活動授權數量（跨瀏覽器和裝置）。如果超過限制，Logto 將撤銷最舊的授權。 + +當你想限制每個應用程式的並發驗證裝置時，此設置很有用。 -OpenID Connect 後端登出端點。詳情請參閱 [聯邦登出：後端登出](#)。 +:::note + +此欄位不支援： + +- 機器對機器應用程式 +- 受保護應用程式 +- SAML 應用程式 + +::: ### 自訂資料 \{#custom-data} -未列於預設應用程式屬性中的額外自訂應用程式資訊，使用者可依自身需求定義自訂資料欄位，例如業務專屬設定與配置。 +未列在預定義應用程式屬性中的其他自訂應用程式資訊，使用者可以根據其特定需求定義自己的自訂資料欄位，例如業務特定的設置和配置。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/README.mdx new file mode 100644 index 00000000000..62cba0ba367 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/README.mdx @@ -0,0 +1,168 @@ +# 工作階段 + +在 Logto 中，工作階段定義了如何在應用程式、瀏覽器和設備之間建立、共享、刷新和撤銷驗證狀態。 + +實際上，使用者體驗到的「已登入」是一種狀態，但系統狀態被分為多個層次。理解這些層次是設計可預測的單一登入 (SSO)、權杖更新和登出行為的關鍵。 + +## Logto 中的工作階段模型 \{#session-model-in-logto} + +```mermaid +flowchart LR + subgraph Logto ["Logto 領域"] + S["登入工作階段"] + G1["授權 (App A)"] + G2["授權 (App B)"] + end + + subgraph AppA ["應用程式領域 A"] + A["本地工作階段 / 權杖"] + end + + subgraph AppB ["應用程式領域 B"] + B["本地工作階段 / 權杖"] + end + + S --> G1 + S --> G2 + G1 --> A + G2 --> B +``` + +- **Logto 登入工作階段**：集中式登入狀態，儲存在 Logto 領域的 cookie 中。這控制了當前瀏覽器上下文中的 SSO 可用性。 +- **授權 (Grant)**：針對 `user + client app` 的應用程式特定授權狀態。授權是集中式登入與應用程式權杖發行之間的橋樑。 +- **應用程式本地工作階段 / 權杖**：每個應用程式中的本地驗證狀態（ID / 存取 / 重新整理權杖、應用程式工作階段 cookie 等）。 + +## 核心概念 \{#core-concepts} + +### 什麼是 Logto 工作階段？ \{#what-is-a-logto-session} + +Logto 工作階段是成功登入後創建的集中式驗證狀態。如果它仍然有效，Logto 可以在同一租戶中的其他應用程式中靜默驗證使用者。如果不存在，使用者必須重新登入。 + +### 什麼是授權 (Grants)？ \{#what-are-grants} + +授權是與特定使用者和客戶端應用程式相關的應用程式層級授權狀態。 + +- 一個 Logto 工作階段可以有多個應用程式的授權。 +- 應用程式的權杖是在該應用程式的授權下發行的。 +- 撤銷授權會影響該應用程式繼續基於權杖存取的能力。 + +### 工作階段、授權和應用程式驗證狀態的關係 \{#how-session-grants-and-app-auth-state-relate} + +- **工作階段**回答：「這個瀏覽器現在可以與 Logto 進行 SSO 嗎？」 +- **授權**回答：「這個使用者是否被授權使用這個客戶端應用程式？」 +- **應用程式本地工作階段**回答：「這個應用程式目前是否將使用者視為已登入？」 + +## 登入和工作階段創建 \{#sign-in-and-session-creation} + +```mermaid +sequenceDiagram + autonumber + actor User + + box Relying Party + participant Client as 客戶端應用程式 + end + + box Logto + participant OIDC as OIDC 提供者 + participant SignIn as 登入頁面 + end + + User ->> Client: 存取應用程式 + Client ->> OIDC: 授權請求 + OIDC -->> OIDC: 檢查現有 Logto 工作階段 + OIDC ->> SignIn: 如有需要提示登入 + SignIn ->> OIDC: 使用者驗證 + OIDC -->> OIDC: 創建工作階段和應用程式授權 + OIDC ->> Client: 返回授權碼 + Client ->> OIDC: 交換代碼以獲取權杖 + OIDC -->> Client: 返回權杖 +``` + +## 應用程式和設備之間的工作階段拓撲 \{#session-topology-across-apps-and-devices} + +### 同一瀏覽器：共享 Logto 工作階段 \{#same-browser-shared-logto-session} + +```mermaid +flowchart TD + U[使用者] + A["客戶端應用程式 A"] + B["客戶端應用程式 B"] + C{"Logto 工作階段存在嗎？"} + D["Logto 登入頁面"] + + U --> A + A --> C + U --> B + B --> C + C -->|否| D +``` + +同一瀏覽器中的應用程式可以共享集中式 Logto 工作階段狀態，因此 SSO 可以在不重複輸入憑證的情況下發生。 + +### 不同瀏覽器或設備：隔離的 Logto 工作階段 \{#different-browsers-or-devices-isolated-logto-sessions} + +每個瀏覽器 / 設備都有單獨的 cookie 儲存。設備 A 上的有效工作階段並不意味著設備 B 上也有有效的工作階段。 + +## 工作階段生命週期 \{#session-lifecycle} + +### 1. 創建 \{#1-create} + +使用者驗證後，Logto 創建集中式工作階段和應用程式特定的授權。 + +### 2. 重用 (SSO) \{#2-reuse-sso} + +只要工作階段 cookie 在同一瀏覽器中有效，新授權請求通常可以靜默完成。 + +### 3. 更新權杖 \{#3-renew-tokens} + +應用程式存取通常透過權杖刷新流程（啟用時）繼續。這是應用程式層級的連續性，與集中式 Logto 工作階段是否仍然存在無關。 + +### 4. 撤銷 / 過期 \{#4-revokeexpire} + +撤銷可以在不同層次發生： + +- 本地應用程式登出會移除應用程式本地權杖 / 工作階段。 +- 結束工作階段會移除集中式 Logto 工作階段。 +- 授權撤銷會移除應用程式層級的授權連續性。 + +## 設計建議 \{#design-recommendations} + +- 在應用程式代碼中明確處理應用程式本地工作階段。 +- 將 Logto 工作階段、授權和應用程式本地工作階段視為獨立層次。 +- 選擇登出應僅限於應用程式本地還是全域。 +- 當需要多應用程式一致性時，使用 [後台通道登出](/end-user-flows/sign-out#federated-sign-out-back-channel-logout)。 +- 有關登出行為和實施細節，請參閱 [登出](/end-user-flows/sign-out)。 + +## 撤銷存取的最佳實踐 \{#best-practices-for-revoking-access} + +根據你的目標使用不同的撤銷策略： + +- **撤銷第一方應用程式的存取**： + 使用 `revokeGrantsTarget=firstParty` 撤銷目標工作階段。 + 這會讓使用者在與該工作階段相關的第一方應用程式中登出，創造一致的登出體驗。 + 同時，對於已授予 `offline_access` 的第三方應用程式，授權仍可用於持續整合。 + 有關工作階段撤銷的詳細資訊，請參閱 [管理使用者工作階段](/sessions/manage-user-sessions)。 + +- **撤銷對第三方應用程式的存取**： + 選擇以下之一： + + - 使用 `revokeGrantsTarget=all` 撤銷工作階段，以撤銷與該工作階段相關的所有授權。 + - 直接透過授權管理 API 撤銷特定授權，以移除第三方應用程式授權，而不強制完全工作階段登出。 + 有關授權特定撤銷策略，請參閱 [管理使用者授權應用程式（授權）](/sessions/grants-management)。 + +- **使用 Logto Console 時**： + 在使用者詳細資訊頁面，Logto 提供現成的工作階段管理和授權第三方應用程式管理。 + - 撤銷工作階段同時撤銷第一方應用程式授權，以保持第一方登出行為一致。 + - 撤銷第三方應用程式授權會撤銷該第三方應用程式的授權，同時保持原始工作階段狀態不變。 + +## 相關資源 \{#related-resources} + +管理使用者工作階段 +管理使用者授權應用程式（授權） +工作階段配置 +登出 +註冊和登入 + + 理解驗證流程 + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx new file mode 100644 index 00000000000..7319c533364 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/grants-management.mdx @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# 管理使用者授權的應用程式（授權） + +應用程式授權代表使用者對特定客戶端應用程式的授權狀態。 + +當使用者或管理員需要檢視授權的應用程式並撤銷應用程式存取權，而不撤銷整個 Logto 會話時，可以使用授權管理。 + +當授權被撤銷時，先前發出的不透明存取權杖和重新整理權杖將失效。 + +## 選擇正確的路徑 \{#choose-the-right-path} + +| 情境 | 推薦路徑 | +| -------------------------------------- | -------------- | +| 讓已登入的使用者管理自己的應用程式授權 | Account API | +| 讓管理員或支援團隊管理目標使用者的授權 | Management API | +| 讓操作員在 UI 中管理第三方應用程式授權 | Admin Console | + +## 直接授權管理 API \{#direct-grant-management-apis} + +### Account API（自助服務）\{#account-api-self-service} + +在終端使用者帳戶設定頁面中使用 Account API： + +- `GET /api/my-account/grants` +- `DELETE /api/my-account/grants/{grantId}` +- 參考：[管理使用者授權的應用程式（授權）](/end-user-flows/account-settings/by-account-api#manage-user-authorized-apps-grants) + +### Management API（管理工具）\{#management-api-admin-tools} + +在管理工具和支援工作流程中使用 Management API： + +- `GET /api/users/{userId}/grants` +- `DELETE /api/users/{userId}/grants/{grantId}` +- 參考：[管理使用者授權的應用程式（授權）](/end-user-flows/account-settings/by-management-api#manage-user-authorized-apps-grants) + +### 按應用程式類型篩選授權列表 \{#filter-grant-list-by-app-type} + +授權列表端點支援可選的查詢參數 `appType`： + +- `appType=firstParty`：僅列出第一方應用程式授權。 +- `appType=thirdParty`：僅列出第三方應用程式授權。 +- 省略 `appType`：返回所有活動授權。 + +## 在 Console 中管理第三方應用程式授權 \{#manage-third-party-app-authorizations-in-console} + +在 Logto Console 中，使用使用者詳細資料頁面查看和撤銷授權的第三方應用程式。 + +- 參考：[管理使用者授權的第三方應用程式](/user-management/manage-users#manage-user-authorized-third-party-apps) + +## 撤銷會話時撤銷授權 \{#revoke-grants-when-revoking-a-session} + +透過 `DELETE /api/my-account/sessions/{sessionId}` 撤銷會話時，使用可選的查詢參數 `revokeGrantsTarget` 控制授權撤銷範圍： + +- `all`：撤銷與會話相關的所有應用程式的授權。 +- `firstParty`：僅撤銷第一方應用程式的授權。 + +有關會話層級行為和端點上下文，請參閱 [管理使用者會話](/sessions/manage-user-sessions) 和 [登出](/end-user-flows/sign-out)。 + +## 相關資源 \{#related-resources} + +Sessions +管理使用者會話 + + 透過 Account API 的帳戶設定：管理使用者授權的應用程式（授權） + + + 透過 Management API 的帳戶設定：管理使用者授權的應用程式（授權） + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx new file mode 100644 index 00000000000..dd52fb02432 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/manage-user-sessions.mdx @@ -0,0 +1,78 @@ +--- +sidebar_position: 1 +--- + +# 管理使用者工作階段 + +使用者工作階段管理幫助使用者和管理員檢視活躍的登入狀態，並在需要時撤銷工作階段。 + +在 Logto 中，你可以透過三種常見途徑管理工作階段： + +- **Account API**：用於產品帳戶設定頁面中的終端使用者自助服務。 +- **Management API**：用於管理員或支援工具管理任何使用者的工作階段。 +- **Admin Console**：用於在 Logto Console 中的操作員工作流程，無需建立自訂工具。 + +## 選擇合適的 API \{#choose-the-right-api} + +| 情境 | 推薦的 API | +| ------------------------------------------- | -------------- | +| 讓已登入的使用者管理自己的活躍工作階段 | Account API | +| 讓管理員或支援團隊管理使用者的工作階段 | Management API | +| 讓操作員直接在 Logto Console 中管理工作階段 | Admin Console | + +## 檢視活躍工作階段 \{#view-active-sessions} + +### Account API（自助服務）\{#account-api-self-service} + +使用 Account API 的工作階段端點列出當前使用者的活躍工作階段。 + +- 參考部分：[管理使用者工作階段](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 端點：[`GET /api/my-account/sessions`](https://openapi.logto.io/operation/operation-getsessions) + +在向終端使用者公開此功能之前，請確保在 Account center 設定中啟用了工作階段管理，並且你的應用程式請求了所需的 Account API 權限範圍。 + +### Management API（管理工具）\{#management-api-admin-tools} + +當你的管理系統需要列出目標使用者的工作階段時，使用 Management API。 + +- 參考部分：[使用者工作階段管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- 端點：[`GET /api/users/{userId}/sessions`](https://openapi.logto.io/operation/operation-listusersessions) +- 可選詳細資訊端點：[`GET /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-getusersession) + +## 撤銷工作階段 \{#revoke-sessions} + +### Account API（終端使用者撤銷自己的工作階段）\{#account-api-end-user-revokes-own-sessions} + +終端使用者可以從自己的工作階段列表中撤銷特定工作階段。 + +- 參考部分：[管理使用者工作階段](/end-user-flows/account-settings/by-account-api#manage-user-sessions) +- 端點：[`DELETE /api/my-account/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deletesessionbyid) + +對於敏感操作，Account API 工作階段管理需要使用者驗證後才能存取。請參閱 [取得驗證記錄 ID](/end-user-flows/account-settings/by-account-api#get-a-verification-record-id)。 + +### Management API（管理員撤銷使用者工作階段）\{#management-api-admin-revokes-user-sessions} + +管理員可以透過使用者 ID 和工作階段 ID 撤銷目標使用者的工作階段。 + +- 參考部分：[使用者工作階段管理](/end-user-flows/account-settings/by-management-api#user-session-management) +- 端點：[`DELETE /api/users/{userId}/sessions/{sessionId}`](https://openapi.logto.io/operation/operation-deleteusersession) + +## Admin Console \{#admin-console} + +如果你的團隊直接在 Logto Console 中管理使用者，你可以從使用者詳細資訊頁面檢視活躍工作階段並撤銷特定工作階段。 + +- 參考部分：[管理使用者活躍工作階段](/user-management/manage-users#manage-user-active-sessions) + +## 相關資源 \{#related-resources} + +工作階段 +管理使用者授權的應用程式（授權） + + Account API 帳戶設定：管理使用者工作階段 + + + Management API 帳戶設定：使用者工作階段管理 + + + 使用者管理：管理使用者活躍工作階段 + diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx new file mode 100644 index 00000000000..711ee7e56cb --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/sessions/session-configs.mdx @@ -0,0 +1,107 @@ +--- +sidebar_position: 3 +--- + +# 工作階段配置 + +工作階段配置定義了租戶層級的控制，決定 Logto 登入工作階段的持續時間以及如何執行與工作階段相關的存取政策。 + +本頁內容包括： + +- 工作階段 TTL 配置 +- 每個應用程式的最大同時驗證裝置數 + +## 工作階段 TTL 配置 \{#session-ttl-configuration} + +工作階段 TTL 決定了 Logto OIDC 登入工作階段的最長壽命。 +這是一個 **租戶層級的設定**：一旦配置，將適用於該租戶中的所有應用程式和驗證流程。 + +### 預設行為 \{#default-behavior} + +- 預設情況下，工作階段 TTL 為 **14 天**。 +- 如果未配置自訂 TTL，Logto 將繼續使用此預設值。 + +### 通過 Logto Console 配置 \{#configure-concurrent-device-limit-via-logto-console} + +你可以在 Console 中配置工作階段 TTL： + +Console > Tenant > Settings > OIDC settings + +使用 **Session maximum time to live** 來更新值。 + +:::note + +Console 使用 **天** 作為輸入和顯示單位，而底層的 OIDC 工作階段配置 / API 使用 **秒**。 + +::: + +### 通過 Management API 配置 \{#configure-via-management-api} + +使用以下端點來讀取和更新 OIDC 工作階段配置： + +- `GET /api/configs/oidc/session` +- `PATCH /api/configs/oidc/session` + +範例（`ttl` 以秒為單位）： + +```bash +curl https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' +``` + +```bash +curl -X PATCH https://[tenant-id].logto.app/api/configs/oidc/session \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' \ + --data-raw '{"ttl":1209600}' +``` + +`1209600` 秒 = 14 天。 + +:::note + +對於 OSS 部署，修改 `logto-config` 後需重啟服務實例，以便伺服器能夠獲取最新的 OIDC 設定。 + +若要在不重啟服務的情況下自動應用 OIDC 配置更新，請[啟用中央 redis 快取](/logto-oss/central-cache)。 + +::: + +## 每個應用程式的最大同時驗證裝置數 \{#max-concurrent-authenticated-devices-per-app} + +每個應用程式的最大同時驗證裝置數是一個應用程式層級的控制，限制每個使用者對特定應用程式可以保持的活動授權數量。 + +這是通過應用程式 `customClientMetadata` 中的 `maxAllowedGrants` 欄位配置的。 +了解更多請參閱 [應用程式資料結構](/integrate-logto/application-data-structure#max-allowed-grants-maxallowedgrants)。 + +### 行為 \{#behavior} + +當設置 `maxAllowedGrants` 時，Logto 會在每次成功授權時評估使用者對當前應用程式的活動授權。 +如果活動授權數量超過限制，Logto 會優先撤銷最早的授權。 + +如果未設置 `maxAllowedGrants`，則無並發限制。 + +### 通過 Logto Console 配置 \{#configure-via-logto-console} + +你可以在每個應用程式的詳細資訊頁面中配置此項： + + + Console > Applications > Application details > Concurrent device limit + + +設置每個使用者對當前應用程式的最大同時活動授權（裝置）數量。 + +:::note + +此設置不支援機器對機器應用程式、受保護應用程式和 SAML 應用程式。 + +::: + +## 相關資源 \{#related-resources} + +工作階段 +管理使用者工作階段 +管理使用者授權的應用程式（授權） + + 應用程式資料結構：maxAllowedGrants + +與 Management API 互動 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx index c2a07658538..95333c881ea 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/user-management/manage-users.mdx @@ -4,120 +4,135 @@ sidebar_position: 2 # 管理使用者 -## 透過 Logto Console 管理 \{#manage-via-logto-console} +## 通過 Logto Console 管理 \{#manage-via-logto-console} -### 瀏覽與搜尋使用者 \{#browse-and-search-users} +### 瀏覽和搜尋使用者 \{#browse-and-search-users} -要在 Logto Console 存取使用者管理功能，請前往 Console > 使用者管理。進入後，你會看到所有使用者的表格檢視。 +要在 Logto Console 中訪問使用者管理功能，請導航至 Console > User management。進入後，你將看到所有使用者的表格視圖。 -此表格包含三個欄位： +該表格由三個欄位組成： -- **使用者**：顯示使用者資訊，如頭像、全名、使用者名稱、電話號碼與電子郵件 -- **來自應用程式**：顯示該使用者最初註冊時所用的應用程式名稱 -- **最近登入**：顯示使用者最近一次登入的時間戳記 +- **使用者**：顯示使用者的資訊，如頭像、全名、使用者名稱、電話號碼和電子郵件 +- **來自應用程式**：顯示使用者最初註冊的應用程式名稱 +- **最近登入**：顯示使用者最近一次登入的時間戳。 -支援 [`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) 的關鍵字對應搜尋。 +它支援 [`name`](/user-management/user-data#name)、[`id`](/user-management/user-data#id)、[`username`](/user-management/user-data#username)、[`primary-phone`](/user-management/user-data#primary_phone)、[`primary-email`](/user-management/user-data#primary_email) 的關鍵字映射。 ### 新增使用者 \{#add-users} -開發者可透過 Console 為終端使用者建立新帳號。只需點擊畫面右上角的「新增使用者」按鈕。 +使用 Console，開發者可以為終端使用者創建新帳戶。要這樣做，請點擊螢幕右上角的「新增使用者」按鈕。 -在 Logto Console 或透過 Management API 建立使用者時（非終端使用者自行 UI 註冊），你必須至少提供一個識別資訊：`primary email`、`primary phone` 或 `username`。`name` 欄位為選填。 +在 Logto Console 或通過 Management API 創建使用者時（而非使用者通過 UI 自行註冊），你必須提供至少一個識別符：`primary email`、`primary phone` 或 `username`。`name` 欄位是可選的。 -使用者建立後，Logto 會自動產生一組隨機密碼。初始密碼僅顯示一次，但你可於後續 [重設密碼](./manage-users#reset-user-password)。若需設定特定密碼，請於建立後使用 Management API `patch /api/users/{userId}/password` 進行更新。 +使用者創建後，Logto 將自動生成一個隨機密碼。初始密碼僅顯示一次，但你可以稍後 [重設密碼](./manage-users#reset-user-password)。如果你想設置特定密碼，請在創建使用者後使用 Management API `patch /api/users/{userId}/password` 進行更新。 -你可以一鍵複製**輸入的識別資訊（電子郵件 / 電話號碼 / 使用者名稱）**與**初始密碼**，方便將這些憑證分享給新使用者，讓他們登入並開始使用。 +你可以一鍵複製 **輸入的識別符（電子郵件地址 / 電話號碼 / 使用者名稱）** 和 **初始密碼**，方便地將這些憑證分享給新使用者，以便他們登入並開始使用。 :::tip -若你想實作邀請制註冊，建議使用 [邀請使用者並發送魔法連結](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)。這樣僅白名單使用者可自行註冊並設定密碼。 +如果你想實現僅限邀請的註冊，我們建議 [使用魔術連結邀請使用者](/end-user-flows/sign-up-and-sign-in/disable-user-registration#option-1-invite-user-with-magic-link-recommended)。這樣只有白名單中的使用者才能自行註冊並設置自己的密碼。 ::: -### 檢視與更新使用者資料 \{#view-and-update-the-user-profile} - -點擊使用者表格中的對應列，即可檢視該使用者的詳細資料。你將進入「**使用者詳情**」頁面，內容包含： - -- **驗證 (Authentication) 相關資料**： - - **電子郵件地址**（[primary_email](/user-management/user-data#primary_email)）：可編輯 - - **電話號碼**（[primary_phone](/user-management/user-data#primary_phone)）：可編輯 - - **使用者名稱**（[username](/user-management/user-data#username)）：可編輯 - - **密碼**（[has_password](/user-management/user-data#has_password)）：可重新產生隨機密碼。詳見「[重設使用者密碼](#reset-user-password)」。 - - **多重要素驗證 (MFA, Multi-factor authentication)**（[mfa_verification_factor](/user-management/user-data#mfa_verification_factors)）：檢視該使用者已設定的所有驗證因子（如通行密鑰、驗證器 App、備用代碼），可於 Console 移除因子。 - - **通行密鑰 (Passkeys)**：當租戶啟用 [通行密鑰登入](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) 時，你也可在使用者詳情頁檢視並移除該使用者的登入通行密鑰。這些通行密鑰與 MFA 採用相同 WebAuthn 憑證模型。 - - **個人存取權杖 (Personal access token)**：建立、檢視、重新命名與刪除 [個人存取權杖](/user-management/personal-access-token)。 -- **連線**： - - **社交連線**（[identities](/user-management/user-data#social-identities)）： - - 檢視使用者已綁定的社交帳號，包括社交 ID 與從社交平台同步的個人資料（如使用 Facebook 登入則會顯示「Facebook」條目）。 - - 可移除現有社交身分，但無法代替使用者新增新的社交帳號。 - - 若社交連接器啟用 [權杖儲存](/secret-vault/federated-token-set)，可於連線詳情頁檢視與管理存取權杖與重新整理權杖。 - - **企業級單一登入 (Enterprise SSO) 連線**（[sso_identities](/user-management/user-data#sso-identities)）： - - 檢視使用者已綁定的企業身分，包括企業 ID 與從企業身分提供者同步的個人資料。 - - Console 不支援新增或移除企業 SSO 身分。 - - 若 OIDC 型企業連接器啟用 [權杖儲存](/secret-vault/federated-token-set)，可於連線詳情頁檢視與刪除權杖。 -- **使用者個人資料**：姓名、頭像 URL、自訂資料，以及其他未列出的 OpenID Connect 標準宣告。這些欄位皆可編輯。 -- **工作階段 (Sessions)**：檢視使用者的所有啟用工作階段，包括裝置資訊、sessionId 與地理位置（如適用）。可進一步檢視工作階段詳情並撤銷。 +### 查看和更新使用者資料 \{#view-and-update-the-user-profile} + +要查看使用者的詳細資訊，只需點擊使用者表格中的相應行。這將帶你進入「**使用者詳細資訊**」頁面，你可以在此找到使用者的資料資訊，包括： + +- **驗證 (Authentication) 相關數據**： + - **電子郵件地址** ([primary_email](/user-management/user-data#primary_email))：可編輯 + - **電話號碼** ([primary_phone](/user-management/user-data#primary_phone))：可編輯 + - **使用者名稱** ([username](/user-management/user-data#username))：可編輯 + - **密碼** ([has_password](/user-management/user-data#has_password))：你可以重新生成隨機密碼。了解更多關於「[重設使用者密碼](#reset-user-password)」的信息。 + - **多重要素驗證 (MFA, Multi-factor authentication)** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors))：查看此使用者已設置的所有驗證因素（例如，通行密鑰、驗證器應用程式、備份代碼）。可以在 Console 中移除因素。 + - **通行密鑰**：當租戶啟用了 [通行密鑰登入](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) 時，你也可以在使用者詳細資訊頁面查看使用者的登入通行密鑰，並在需要時移除它們。這些通行密鑰由 MFA 使用的相同 WebAuthn 憑證模型支持。 + - **個人存取權杖**：創建、查看、重命名和刪除 [個人存取權杖](/user-management/personal-access-token)。 +- **連接**： + - **社交連接** ([identities](/user-management/user-data#social-identities))： + - 查看使用者已連接的社交帳戶，包括社交 ID 和從其社交提供者同步的資料詳細資訊（例如，如果使用者通過 Facebook 登入，將顯示「Facebook」條目）。 + - 你可以移除現有的社交身分，但不能代表使用者連接新的社交帳戶。 + - 對於啟用了 [權杖存儲](/secret-vault/federated-token-set) 的社交連接器，你可以在連接詳細頁面查看和管理存取權杖和重新整理權杖。 + - **企業級單一登入 (Enterprise SSO) 連接** ([sso_identities](/user-management/user-data#sso-identities))： + - 查看使用者已連接的企業身分，包括企業 ID 和從其企業身分提供者同步的資料詳細資訊。 + - 你不能在 Console 中新增或移除企業 SSO 身分。 + - 對於基於 OIDC 的企業連接器，若啟用了 [權杖存儲](/secret-vault/federated-token-set)，你可以在連接詳細頁面查看和刪除權杖。 +- **使用者資料**：姓名、頭像 URL、自訂數據和其他未包含的 OpenID Connect 標準宣告。所有這些資料欄位均可編輯。 +- **會話**：查看使用者的活動會話列表，包括裝置資訊、sessionId 和地理位置（如果適用）。在會話詳細頁面查看更多會話詳細資訊並撤銷它。 :::warning -在移除社交連線前，請務必確認使用者有其他登入方式，例如其他社交連線、電話號碼、電子郵件或使用者名稱 / 密碼。否則移除後，使用者將無法再次登入其帳號。 +在移除社交連接之前，確認使用者有其他登入方法非常重要，例如其他社交連接、電話號碼、電子郵件或使用者名稱與密碼。如果使用者沒有其他登入方法，一旦移除社交連接，他們將無法再次訪問其帳戶。 ::: -### 檢視使用者活動紀錄 \{#view-user-activities} +### 查看使用者活動 \{#view-user-activities} -要檢視使用者近期活動，請至「使用者詳情」頁的「使用者日誌」子分頁。這裡會顯示一個表格，包含使用者近期執行的動作、結果、相關應用程式與執行時間。 +要查看使用者的最近活動，請導航至「使用者詳細資訊」頁面的「使用者日誌」子標籤。在這裡，你可以找到顯示使用者最近活動的表格，包括執行的操作、操作結果、相關應用程式和使用者執行操作的時間。 -點擊表格列可檢視該活動的更多細節，如 IP 位址、user agent、原始資料等。 +點擊表格行以在使用者日誌中查看更多詳細資訊，例如 IP 地址、使用者代理、原始數據等。 -### 停用使用者 \{#suspend-user} +### 暫停使用者 \{#suspend-user} -於「使用者詳情」頁，點擊「三點」->「停用使用者」按鈕。 +在「使用者詳細資訊」頁面，點擊「三點」->「暫停使用者」按鈕。 -使用者被停用後，將無法登入你的應用程式，且現有存取權杖過期後無法再取得新權杖。此外，該使用者發出的任何 API 請求都會失敗。 +一旦使用者被暫停，該使用者將無法登入你的應用程式，並且在當前存取權杖過期後無法獲得新的存取權杖。此外，該使用者發出的任何 API 請求都將失敗。 -若需重新啟用該使用者，可點擊「三點」->「重新啟用使用者」按鈕。 +如果你想重新激活此使用者，可以點擊「三點」->「重新激活使用者」按鈕。 ### 刪除使用者 \{#delete-user} -於「使用者詳情」頁，點擊「三點」->「刪除」按鈕。刪除後無法復原。 +在「使用者詳細資訊」頁面，點擊「三點」->「刪除」按鈕。刪除使用者無法撤銷。 ### 重設使用者密碼 \{#reset-user-password} -於「使用者詳情」頁，點擊「三點」->「重設密碼」按鈕，Logto 將自動重新產生一組隨機密碼。 +在「使用者詳細資訊」頁面，點擊「三點」->「重設密碼」按鈕，然後 Logto 將自動重新生成一個隨機密碼。 -重設密碼後，請複製並傳送給終端使用者。關閉「重設密碼」視窗後將無法再次檢視密碼，若忘記保存可再次重設。 +重設密碼後，複製並發送給終端使用者。一旦「重設密碼」模態關閉，你將無法再查看密碼。如果忘記保存，可以再次重設。 -你無法在 Logto Console 為使用者設定特定密碼，但可使用 [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` 指定密碼。 +你不能在 Logto Console 中為使用者設置特定密碼，但可以使用 [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` 指定密碼。 -### 管理使用者啟用工作階段 \{#manage-user-active-sessions} +### 管理使用者活動會話 \{#manage-user-active-sessions} -於「使用者詳情」頁，點擊特定工作階段的「管理」按鈕進入「工作階段詳情」頁。你可檢視該工作階段的詳細資訊，如裝置、地點與登入時間。若需讓使用者登出該工作階段，只需點擊右上角的「撤銷工作階段」按鈕，該工作階段將立即失效。 +在「使用者詳細資訊」頁面，點擊特定會話的「管理」按鈕進入「會話詳細資訊」頁面。在這裡，你可以查看會話的詳細資訊，例如裝置、位置和登入時間。如果你想讓使用者從此會話中登出，只需點擊右上角的「撤銷會話」按鈕，會話將立即被撤銷。 -- 預設在 Console 撤銷工作階段時，會同時撤銷該工作階段關聯的所有第一方應用程式授權，使用者需重新登入才能恢復存取。所有已發出的不透明權杖 (Opaque token) 與重新整理權杖 (Refresh token) 也會立即撤銷。 -- 對於具有 `offline_access` 權限範圍的第三方應用程式，撤銷工作階段預設不會撤銷應用程式授權，已發出的重新整理權杖仍可使用，直到授權過期。 +- 默認情況下，在 Console 中撤銷會話也會撤銷與該會話相關的所有第一方應用程式授權，使用者需要重新登入以恢復存取。任何預先發行的 不透明存取權杖 和 重新整理權杖 給第一方應用程式也將立即被撤銷。 +- 對於具有 `offline_access` 權限範圍的第三方應用程式，撤銷會話默認不會撤銷應用程式授權，任何預先發行的重新整理權杖仍可使用，直到授權過期。 + +### 管理使用者授權的第三方應用程式 \{#manage-user-authorized-third-party-apps} + +在「使用者詳細資訊」頁面，你可以使用「授權的第三方應用程式」部分查看使用者的應用程式授權狀態。 +此部分由使用者授權應用程式（授權）管理 API 支持。 + +對於每個授權的應用程式，Console 顯示： + +- 應用程式名稱 +- 應用程式 ID +- 存取創建時間 + +如果需要移除存取，點擊撤銷操作並在模態中確認。 + +撤銷應用程式授權將移除該應用程式與使用者相關的所有活動第三方授權。它還將立即撤銷該應用程式的任何預先發行的 不透明存取權杖 和 重新整理權杖。 ## 密碼合規性檢查 \{#password-compliance-check} -當你在 Logto 更新 [密碼政策](/security/password-policy) 後，現有使用者仍可用原密碼登入。僅新建立帳號需遵循最新密碼政策。 +在 Logto 中更新 [密碼政策](/security/password-policy) 後，現有使用者仍可以使用其當前密碼登入。只有新創建的帳戶需要遵循更新的密碼政策。 -為強化安全性，你可使用 `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) 檢查使用者密碼是否符合預設登入體驗下的現行政策。若不符合，可透過自訂流程提示使用者使用 [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) 更新密碼。 +為了強化安全性，你可以使用 `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) 檢查使用者的密碼是否符合默認登入體驗中定義的當前政策。如果不符合，你可以使用 [Account API](/end-user-flows/account-settings/by-management-api#user-password-management) 提示使用者通過自訂流程更新其密碼。 -### 管理使用者角色 \{#manage-roles-of-users} +### 管理使用者的角色 \{#manage-roles-of-users} -在使用者詳情頁的「角色 (Roles)」分頁，你可輕鬆指派或移除角色以達到預期效果。詳見 [角色型存取控制 (RBAC)](/authorization/role-based-access-control)。 +在使用者詳細資訊頁面的「角色」標籤中，你可以輕鬆地分配或移除角色以達到預期效果。詳細資訊請查看 [角色型存取控制 (RBAC)](/authorization/role-based-access-control)。 -### 檢視使用者所屬組織 \{#view-the-organizations-the-user-belongs-to} +### 查看使用者所屬的組織 \{#view-the-organizations-the-user-belongs-to} -Logto 支援 [組織 (Organizations)](/organizations/organization-management) 並可管理其成員。你可輕鬆檢視使用者詳情並查詢其所屬組織。 +Logto 支援 [組織](/organizations/organization-management) 並可以管理其成員。你可以輕鬆查看使用者詳細資訊並查看他們所屬的組織。 -## 透過 Logto Management API 管理 \{#manage-via-logto-management-api} +## 通過 Logto Management API 管理 \{#manage-via-logto-management-api} -[Management API](/concepts/core-service/#management-api) 是一組存取 Logto 後端服務的 API。如前所述，使用者 API 是此服務的重要組件，可支援多種情境。 +[Management API](/concepts/core-service/#management-api) 是一組提供 Logto 後端服務存取的 API。如前所述，使用者 API 是此服務的重要組成部分，並且可以支持多種場景。 -與使用者相關的 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API 掛載於 `/api/users`，僅使用者活動（即使用者日誌 `/api/logs?userId=:userId`）例外。 +與使用者相關的 [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API 安裝在 `/api/users`，除了使用者活動，即使用者日誌 `/api/logs?userId=:userId`。 -你可在多種情境下透過 Management API 管理使用者，例如 [進階使用者搜尋](/user-management/advanced-user-search)、[批次建立帳號](https://openapi.logto.io/operation/operation-createuser)、[邀請制註冊](/end-user-flows/sign-up-and-sign-in/disable-user-registration) 等。 +你可以在多種使用情境中通過 Management API 管理使用者。例如 [進階使用者搜尋](/user-management/advanced-user-search)、[批量創建帳戶](https://openapi.logto.io/operation/operation-createuser)、[僅限邀請註冊](/end-user-flows/sign-up-and-sign-in/disable-user-registration) 等。 ## 常見問題 \{#faqs} @@ -125,12 +140,12 @@ Logto 支援 [組織 (Organizations)](/organizations/organization-management) -### 如何限制特定使用者存取某些應用程式？ \{#how-to-restrict-access-to-certain-application-for-specific-users} +### 如何限制特定使用者對某些應用程式的存取？ \{#how-to-restrict-access-to-certain-application-for-specific-users} -由於 Logto 的 [Omni-sign-in](https://logto.io/products/omni-sign-in) 特性，設計上不支援在驗證 (Authentication) 前限制使用者存取特定應用程式。 -不過，你仍可設計應用程式專屬的使用者角色與權限，保護你的 API 資源，並於使用者成功登入後在 API 存取時驗證權限。 -詳見授權 (Authorization)：[角色型存取控制 (RBAC)](/authorization/role-based-access-control)。 +由於 Logto 的 [Omni-sign-in](https://logto.io/products/omni-sign-in) 特性，它並未設計為在驗證之前限制使用者對某些應用程式的存取。 +然而，你仍然可以設計應用程式特定的使用者角色和權限來保護你的 API 資源，並在使用者成功登入後驗證 API 存取的權限。 +有關更多資訊，請參閱授權：[角色型存取控制 (RBAC)](/authorization/role-based-access-control)。 From 727dcdc57d67ff7276f63e7300d04f41680bb068 Mon Sep 17 00:00:00 2001 From: simeng-li Date: Tue, 31 Mar 2026 11:47:05 +0800 Subject: [PATCH 4/4] fix: fix lint fix lint --- .../current/developers/signing-keys.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 3d624e1dc15..0fb74115335 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -26,8 +26,8 @@ Logto [OIDC 서명 키](https://auth.wiki/signing-key), "OIDC 개인 키" 및 "O Logto는 "서명 키 회전" 기능을 도입하여 테넌트에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있습니다. -1. Console > 테넌트 설정 > OIDC 구성로 이동하세요. 여기서 - OIDC 개인 키와 OIDC 쿠키 키를 모두 관리할 수 있습니다. +1. Console > 테넌트 설정 > OIDC 구성로 + 이동하세요. 여기서 OIDC 개인 키와 OIDC 쿠키 키를 모두 관리할 수 있습니다. 2. 서명 키를 교체하려면 "개인 키 교체" 또는 "쿠키 키 교체" 버튼을 클릭하세요. 개인 키를 교체할 때는 서명 알고리즘을 변경할 수도 있습니다. 3. 사용 중인 모든 서명 키가 나열된 테이블을 확인할 수 있습니다. 참고: 이전 키는 삭제할 수 있지만, 현재 사용 중인 키는 삭제할 수 없습니다.