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 55a89e068ca..a2416852ea7 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,29 +1,29 @@ --- -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-Zugang ermöglicht, ohne die Management API verwenden zu müssen. Hier die wichtigsten Punkte: - Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto-Profil zuzugreifen und dieses zu verwalten, ohne die Weiterleitung über die Management API zu benötigen. -- Verwaltung von Benutzerprofilen und Identitäten: 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. Unterstützung für MFA und SSO folgt in Kürze. +- Verwaltung von Benutzerprofilen und Identitäten: 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 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) war noch nie so einfach! 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. :::note Um sicherzustellen, dass das Zugangstoken (Access token) die entsprechenden Berechtigungen (Permissions) hat, stelle sicher, dass du die entsprechenden Berechtigungen (Scopes) in deiner Logto-Konfiguration korrekt eingerichtet hast. -Beispielsweise musst du für die `POST /api/my-account/primary-email` API die Berechtigung (Scope) `email` konfigurieren; für die `POST /api/my-account/primary-phone` API die Berechtigung (Scope) `phone`. +Zum Beispiel benötigst du für die `POST /api/my-account/primary-email` API die Berechtigung (Scope) `email`; für die `POST /api/my-account/primary-phone` API die Berechtigung (Scope) `phone`. ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { - // ...andere Optionen + // ...weitere Optionen // Füge die passenden Berechtigungen (Scopes) hinzu, die zu deinem Anwendungsfall passen. scopes: [ UserScope.Email, // Für `{POST,DELETE} /api/my-account/primary-email` APIs @@ -38,27 +38,29 @@ const config: LogtoConfig = { ::: -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 individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig mit 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 sozialer Verbindungen aktualisieren +- Benutzeridentitäten wie E-Mail, Telefon und soziale Verbindungen aktualisieren - MFA-Faktoren (Verifizierungen) 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 -Dedizierte Account APIs für die folgenden Einstellungen kommen bald: MFA, SSO, benutzerdefinierte Daten (user) und Kontolöschung. In der Zwischenzeit kannst du diese Funktionen mit den Logto Management APIs umsetzen. Siehe [Kontoeinstellungen über Management API](/end-user-flows/account-settings/by-management-api) für weitere Details. +Dedizierte Account APIs für die folgenden Einstellungen erscheinen in Kürze: SSO, Benutzerdefinierte Daten (Custom data) und Kontolöschung. In der Zwischenzeit kannst du diese Funktionen mit den Logto Management APIs umsetzen. Siehe [Kontoeinstellungen über die Management API](/end-user-flows/account-settings/by-management-api) für weitere Details. + +MFA-Management-APIs (TOTP und Backup-Codes) befinden sich derzeit in der Entwicklung und sind nur verfügbar, wenn das Flag `isDevFeaturesEnabled` auf `true` gesetzt ist. WebAuthn-Passkey-Management ist vollständig verfügbar. ::: ## Wie aktiviere ich die Account API \{#how-to-enable-account-api} Standardmäßig ist die Account API deaktiviert. Um sie zu aktivieren, musst du die [Management API](/integrate-logto/interact-with-management-api) verwenden, um die globalen Einstellungen zu aktualisieren. -Der API-Endpunkt `/api/account-center` kann verwendet werden, um die Einstellungen des Account Centers abzurufen und zu aktualisieren. Du kannst ihn verwenden, um die Account API zu aktivieren oder zu deaktivieren und die Felder anzupassen. +Der API-Endpunkt `/api/account-center` kann verwendet werden, um die Einstellungen des Account Centers abzurufen und zu aktualisieren. Du kannst ihn nutzen, um die Account API zu aktivieren oder zu deaktivieren und die Felder anzupassen. Beispielanfrage: @@ -87,9 +89,9 @@ Weitere Details zur API findest du in der [Logto Management API Referenz](https: ### Zugangstoken (Access token) 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 opakes 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 (Access token) abzurufen. Dieses Token ist ein opaker Token (Opaque token), das für den Zugriff auf die Account API verwendet werden kann. -Wenn du nicht das offizielle SDK verwendest, solltest du das Feld `resource` für die Zugangstoken-Anfrage an `/oidc/token` leer lassen. +Wenn du das offizielle SDK nicht verwendest, solltest du das Feld `resource` für die Access Token Grant-Anfrage an `/oidc/token` leer lassen. ### Zugriff auf die Account API mit Zugangstoken (Access token) \{#access-account-api-using-access-token} @@ -111,7 +113,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -Der Antwort-Body sieht etwa so aus: +Die Antwort sieht beispielsweise so aus: ```json { @@ -126,7 +128,7 @@ Die Antwortfelder können je nach Account Center-Einstellungen variieren. ### Grundlegende Kontoinformationen aktualisieren \{#update-basic-account-information} -Zu den grundlegenden Kontoinformationen gehören Benutzername, Name, Avatar und Profil. +Grundlegende Kontoinformationen umfassen Benutzername, Name, Avatar und Profil. Um Benutzername, Name und Avatar zu aktualisieren, kannst du den Endpunkt `PATCH /api/my-account` verwenden. @@ -150,15 +152,15 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ Aus Sicherheitsgründen erfordert die Account API eine zusätzliche Autorisierungsebene für Vorgänge, die Identifikatoren und andere sensible Informationen betreffen. -### Eine Verifizierungsdatensatz-ID abrufen \{#get-a-verification-record-id} +### Eine Verifizierungsdatensatz-ID erhalten \{#get-a-verification-record-id} -Zuerst musst du eine Verifizierungsdatensatz-ID erhalten. Diese kann verwendet werden, um die Identität des Benutzers beim Aktualisieren von Identifikatoren zu überprüfen. +Zuerst musst du eine Verifizierungsdatensatz-ID erhalten. Diese kann verwendet werden, um die Identität des Benutzers beim Aktualisieren von Identifikatoren zu verifizieren. -Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du das Passwort des Benutzers überprüfen oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden. +Um eine Verifizierungsdatensatz-ID zu erhalten, kannst du das Passwort des Benutzers verifizieren oder einen Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden. -Um mehr über Verifizierungen zu erfahren, siehe [Sicherheitsverifizierung über Account API](/end-user-flows/security-verification). +Weitere Informationen zu Verifizierungen findest du unter [Sicherheitsverifizierung über die Account API](/end-user-flows/security-verification). -#### Passwort des Benutzers überprüfen \{#verify-the-users-password} +#### Passwort des Benutzers verifizieren \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -167,7 +169,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -Der Antwort-Body sieht etwa so aus: +Die Antwort sieht beispielsweise so aus: ```json { @@ -176,10 +178,10 @@ Der Antwort-Body sieht etwa so aus: } ``` -#### Überprüfung 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} +#### Verifizierungscode an die E-Mail oder das Telefon des Benutzers senden \{#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 eingerichtet ist. ::: Am Beispiel E-Mail: Fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID: @@ -191,7 +193,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Der Antwort-Body sieht etwa so aus: +Die Antwort sieht beispielsweise so aus: ```json { @@ -209,16 +211,28 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Nach der Überprüfung des Codes kannst du nun die Verifizierungsdatensatz-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. ### Anfrage mit Verifizierungsdatensatz-ID senden \{#send-request-with-verification-record-id} -Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungsdatensatz-ID im Anfrage-Header mit dem Feld `logto-verification-id` angeben. +Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungsdatensatz-ID im Request-Header mit dem Feld `logto-verification-id` angeben. + +### Passwort des Benutzers aktualisieren \{#update-users-password} + +Um das Passwort des Benutzers zu aktualisieren, kannst du den Endpunkt `POST /api/my-account/password` verwenden. + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` ### 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 eingerichtet ist. ::: Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, musst du zunächst den Besitz der E-Mail nachweisen. @@ -241,10 +255,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Nach der Verifizierung des Codes kannst du nun die E-Mail des Benutzers aktualisieren. Setze die `verificationId` im Anfrage-Body als `newIdentifierVerificationRecordId`. +Nach der Verifizierung des Codes kannst du nun die E-Mail des Benutzers aktualisieren. Setze die `verificationId` im Request-Body als `newIdentifierVerificationRecordId`. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -264,7 +278,7 @@ 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 eingerichtet ist. ::: Ähnlich wie beim Aktualisieren der E-Mail kannst du den Endpunkt `PATCH /api/my-account/primary-phone` verwenden, um ein neues Telefon zu aktualisieren oder zu verknüpfen. Und den Endpunkt `DELETE /api/my-account/primary-phone`, um das Telefon des Benutzers zu entfernen. @@ -281,12 +295,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `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 erfassen. -- `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. +- `redirectUri`: Die Redirect-URI nach der Autorisierung der Anwendung durch den Benutzer. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen. +- `state`: Der State, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es handelt sich um einen zufälligen String, der zur Verhinderung von CSRF-Angriffen verwendet wird. 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 Parameter `state`. Dann kannst du den Endpunkt `POST /api/verifications/social/verify` verwenden, um die soziale Verbindung zu verifizieren. +Nachdem der Benutzer die Anwendung autorisiert hat, erhältst du einen Callback an der `redirectUri` mit dem Parameter `state`. Dann kannst du den Endpunkt `POST /api/verifications/social/verify` verwenden, um die soziale Verbindung zu verifizieren. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -295,7 +309,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -Das `connectorData` ist die von dem Social Connector nach der Autorisierung des Benutzers zurückgegebene Daten. Du musst die Query-Parameter aus der `redirectUri` auf deiner Callback-Seite extrahieren und sie als JSON als Wert des Feldes `connectorData` übergeben. +Das `connectorData` sind die Daten, die vom Social Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Query-Parameter aus der `redirectUri` auf deiner Callback-Seite extrahieren und sie als JSON im Feld `connectorData` übergeben. Abschließend kannst du den Endpunkt `POST /api/my-account/identities` verwenden, um die soziale Verbindung zu verknüpfen. @@ -317,10 +331,10 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Neues WebAuthn-Passkey verknüpfen \{#link-a-new-webauthn-passkey} +### Neuen WebAuthn-Passkey verknüpfen \{#link-a-new-webauthn-passkey} :::note -Denke daran, zuerst [MFA und WebAuthn aktivieren](/end-user-flows/mfa). +Denke daran, zuerst [MFA und WebAuthn zu aktivieren](/end-user-flows/mfa). ::: :::note @@ -331,7 +345,7 @@ Um diese Methode zu verwenden, musst du das Feld `mfa` in den Account Center-Ein Ein Passkey im Browser ist an einen bestimmten Hostnamen (RP ID) gebunden, und nur der Origin der RP ID kann verwendet werden, um einen Passkey zu registrieren oder zu verifizieren. Da deine Frontend-App, die die Anfrage an die Account API sendet, nicht dieselbe ist wie die Logto-Anmeldeseite, musst du den Origin deiner Frontend-App zur Liste der zugehörigen Origins hinzufügen. Dadurch kann deine Frontend-App einen Passkey unter anderen RP IDs registrieren und verifizieren. -Standardmäßig setzt Logto die RP ID auf die Tenant-Domain, z. B. wenn deine Tenant-Domain `https://example.logto.app` ist, ist die RP ID `example.logto.app`. Wenn du eine benutzerdefinierte Domain verwendest, ist die RP ID die benutzerdefinierte Domain, z. B. bei `https://auth.example.com` ist die RP ID `auth.example.com`. +Standardmäßig setzt Logto die RP ID auf die Tenant-Domain, z. B. wenn deine Tenant-Domain `https://example.logto.app` ist, ist die RP ID `example.logto.app`. Wenn du eine eigene Domain verwendest, ist die RP ID die eigene Domain, z. B. bei `https://auth.example.com` ist die RP ID `auth.example.com`. Füge nun den Origin deiner Frontend-App zu den zugehörigen Origins hinzu, z. B. wenn der Origin deiner Frontend-App `https://account.example.com` ist: @@ -398,20 +412,20 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id`: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wird. Siehe den Abschnitt [Eine Verifizierungsdatensatz-ID abrufen](#get-a-verification-record-id) für weitere Details. -- `type`: Der Typ des MFA-Faktors, derzeit wird nur `WebAuthn` unterstützt. +- `verification_record_id`: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Weitere Details findest du im Abschnitt [Eine Verifizierungsdatensatz-ID erhalten](#get-a-verification-record-id). +- `type`: Der Typ des MFA-Faktors, aktuell wird nur `WebAuthn` unterstützt. - `newIdentifierVerificationRecordId`: Die vom Server in Schritt 1 zurückgegebene Verifizierungsdatensatz-ID. -### Bestehendes WebAuthn-Passkey verwalten \{#manage-existing-webauthn-passkey} +### Bestehenden WebAuthn-Passkey verwalten \{#manage-existing-webauthn-passkey} -Um ein bestehendes WebAuthn-Passkey zu verwalten, kannst du den Endpunkt `GET /api/my-account/mfa-verifications` verwenden, um aktuelle Passkeys und andere MFA-Verifizierungsfaktoren abzurufen. +Um einen bestehenden WebAuthn-Passkey zu verwalten, kannst du den Endpunkt `GET /api/my-account/mfa-verifications` verwenden, um aktuelle Passkeys und andere MFA-Verifizierungsfaktoren abzurufen. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -Der Antwort-Body sieht etwa so aus: +Die Antwort sieht beispielsweise so aus: ```json [ @@ -448,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### Neues 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 aktivieren. +::: + +**Schritt 1: TOTP-Secret generieren.** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +Die Antwort sieht beispielsweise so aus: + +```json +{ + "secret": "..." +} +``` + +**Schritt 2: TOTP-Secret dem Benutzer anzeigen.** + +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. + +Das URI-Format für den QR-Code sollte sein: + +``` +otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] +``` + +Beispiel: + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**Schritt 3: TOTP-Faktor binden.** + +Nachdem der Benutzer das Secret zu seiner Authenticator-App hinzugefügt hat, muss er es verifizieren und an sein Konto binden: + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Weitere Details findest du im Abschnitt [Eine Verifizierungsdatensatz-ID erhalten](#get-a-verification-record-id). +- `type`: Muss `Totp` sein. +- `secret`: Das in Schritt 1 generierte TOTP-Secret. + +:::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. +::: + +### Backup-Codes verwalten \{#manage-backup-codes} + +:::note +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 aktivieren. +::: + +**Schritt 1: Neue Backup-Codes generieren:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +Die Antwort sieht beispielsweise so aus: + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**Schritt 2: Backup-Codes dem Benutzer anzeigen:** + +:::important +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 +- Verstehe, dass jeder Code nur einmal verwendet werden kann +- Wisse, dass diese Codes die letzte Rettung sind, falls der Zugriff auf die primären MFA-Methoden verloren geht + +Du solltest die Codes in einem klaren, einfach zu kopierenden Format anzeigen und eine Download-Option (z. B. als Textdatei oder PDF) anbieten. +::: + +**Schritt 3: Backup-Codes an das Benutzerkonto binden:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`: Eine gültige Verifizierungsdatensatz-ID, die durch die Verifizierung des bestehenden Faktors des Benutzers gewährt wurde. Weitere Details findest du im Abschnitt [Eine Verifizierungsdatensatz-ID erhalten](#get-a-verification-record-id). +- `type`: Muss `BackupCode` sein. +- `codes`: Das Array der in Schritt 1 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. +- Jeder Backup-Code kann nur einmal verwendet werden. + +::: + +**Vorhandene Backup-Codes anzeigen:** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +Die Antwort sieht beispielsweise so aus: + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`: Der Backup-Code. +- `usedAt`: Der Zeitstempel, wann der Code verwendet wurde, `null`, wenn noch nicht verwendet. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/de/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index c2eeaed914c..d800a6845a1 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -13,8 +13,8 @@ Wenn du einen separaten Mandanten für die **Produktions**- (Prod-)Umgebung oder Klicke auf „Mandanten erstellen“ und dann: - Name für den Mandanten -- Wähle eine [Mandanten-Datenregion](#tenant-region) -- Wähle den [Mandantentyp](#tenant-types-dev-vs-prod) (Umgebung) +- Wähle eine [Mandanten-Datenregion](#tenant-region) aus +- Wähle den [Mandantentyp](#tenant-types-dev-vs-prod) (Umgebung) aus Für einen bestehenden Mandanten gehe zu Konsole > Mandanteneinstellungen > Einstellungen. Hier kannst du: @@ -27,7 +27,7 @@ Für einen bestehenden Mandanten gehe zu Konsole > Man ## Mandantenregion \{#tenant-region} -Wenn du einen Mandanten erstellst, kannst du die Region wählen, in der die Mandantendaten gespeichert werden. Diese kann nach der Erstellung des Mandanten nicht mehr geändert werden. Folgende Regionen stehen zur Verfügung: +Wenn du einen Mandanten erstellst, kannst du die Region auswählen, in der die Mandantendaten gespeichert werden. Sie kann nach der Erstellung des Mandanten nicht mehr geändert werden. Hier sind die verfügbaren Regionen: - Europa (Niederlande) - West-USA (Arizona) @@ -36,7 +36,7 @@ Wenn du einen Mandanten erstellst, kannst du die Region wählen, in der die Mand In der Regel solltest du die Region wählen, die deinen Kunden am nächsten ist, um die Latenz zu minimieren und die Leistung zu verbessern. -Logto nutzt das globale Edge-Netzwerk, um die beste Leistung und Verfügbarkeit für deine Anwendungen zu liefern. Das Routing der Anfragen ist optimiert, um sicherzustellen, dass deine Nutzer immer mit der leistungsstärksten Option verbunden sind. +Logto nutzt das globale Edge-Netzwerk, um die beste Leistung und Verfügbarkeit für deine Anwendungen zu bieten. Das Routing der Anfragen ist optimiert, damit deine Nutzer immer mit der leistungsstärksten Option verbunden sind. :::note Du suchst eine andere Region? [Kontaktiere uns](https://logto.io/contact), um: @@ -47,27 +47,32 @@ Du suchst eine andere Region? [Kontaktiere uns](https://logto.io/contact), um: ## Mandantentypen: Dev vs. Prod \{#tenant-types-dev-vs-prod} -Es gibt zwei Arten von Mandanten in Logto Cloud: Entwicklung und Produktion. Mit dieser Unterscheidung kannst du deine Projekte effizienter über verschiedene Umgebungen hinweg verwalten und gleichzeitig den vollen Nutzen von Logto genießen. +Es gibt zwei Typen von Mandanten in Logto Cloud: Entwicklung (Dev) und Produktion (Prod). Mit dieser Mandantendifferenzierung kannst du deine Projekte über verschiedene Umgebungen hinweg effizienter verwalten und gleichzeitig den vollen Nutzen von Logto genießen. Du kannst den Mandantentyp bei der Erstellung auswählen. Wenn du bereit bist, in die Produktion zu gehen, gibt es zwei Optionen: -- **Einen neuen Produktionsmandanten erstellen** +- **Neuen Produktionsmandanten erstellen** Richte einen neuen Produktionsmandanten ein und konfiguriere ihn von Grund auf neu. Dies ist ideal, wenn du Entwicklungs- und Produktionsumgebungen getrennt halten möchtest. - **Deinen aktuellen Dev-Mandanten in Produktion umwandeln** - Wenn du die Konfiguration nicht erneut durchführen oder Benutzer migrieren möchtest, kannst du deinen bestehenden Dev-Mandanten durch ein Abonnement unseres Pro-Plans (ab 16 $ / Monat) in einen kostenpflichtigen Produktionsmandanten umwandeln. - - Alle kostenpflichtigen Funktionen, die du im Dev-Mandanten genutzt hast, werden in den Stripe-Checkout übernommen. - - **Nach der Umwandlung kann der Mandant nicht mehr in eine Entwicklungsumgebung zurückgesetzt werden. Bitte stelle sicher, dass du bereit bist, bevor du fortfährst.** + Wenn du die Konfiguration nicht erneut durchführen oder Benutzer migrieren möchtest, kannst du deinen bestehenden Entwicklungsmandanten auf einen kostenpflichtigen Produktionsmandanten upgraden. + + - **In einen Pro-Plan umwandeln**: Gehe zu Konsole > Mandanteneinstellungen > Einstellungen und klicke dann auf „Umwandeln“, um das Upgrade im Self-Service durchzuführen. Alle kostenpflichtigen Funktionen, die du im Dev-Mandanten genutzt hast, werden in den Stripe-Checkout übernommen. + - **In einen Enterprise-Plan umwandeln**: [Kontaktiere uns](https://logto.io/contact) und wir helfen dir beim Upgrade. + + :::note + Nach der Umwandlung kann der Mandant nicht mehr in eine Dev-Umgebung zurückgesetzt werden; stelle bitte sicher, dass du bereit bist, bevor du fortfährst. + ::: ### Entwicklung \{#development} -Der Entwicklungsmandant (Dev-Mandant) ist in erster Linie für Testzwecke gedacht und sollte nicht in einer Produktionsumgebung verwendet werden. Diese Mandanten ermöglichen den Zugriff auf Premium- und kostenpflichtige Funktionen der kostenpflichtigen Pläne, kostenlos und ohne Abonnement. +Der Entwicklungsmandant (Dev-Mandant) ist in erster Linie für Testzwecke gedacht und sollte nicht in einer Produktionsumgebung verwendet werden. Diese Mandanten ermöglichen den Zugriff auf Premium- und kostenpflichtige Funktionen, die in kostenpflichtigen Plänen enthalten sind – kostenlos und ohne Abonnement. Es gelten jedoch bestimmte Einschränkungen für Entwicklungsmandanten: - Der Dev-Mandant löscht Benutzer und Organisationen automatisch nach über 90 Tagen. -- Während der Anmeldeerfahrung erscheint ein Banner, das darauf hinweist, dass sich der Mandant im Entwicklungsmodus befindet. +- Während der Anmeldeerfahrung erscheint ein Banner, das anzeigt, dass sich der Mandant im Entwicklungsmodus befindet. - Entwicklungsmandanten können Quotenbeschränkungen für bestimmte Funktionen haben. Diese Limits werden auf der jeweiligen Funktionsdetailseite erläutert, falls zutreffend. -- Logto kann die Quotenlimits des Entwicklungsmandanten aktualisieren und wird versuchen, dich im Voraus zu benachrichtigen. +- Logto kann die Quotenlimits für Entwicklungsmandanten aktualisieren und wird versuchen, dich im Voraus zu benachrichtigen. | Funktion | Entitätslimit | | ----------------------------- | -------------- | @@ -97,40 +102,40 @@ Es gelten jedoch bestimmte Einschränkungen für Entwicklungsmandanten: ### Produktion \{#production} -Der Produktionsmandant ist der Ort, an dem Endbenutzer auf die Live-App zugreifen und du möglicherweise ein [kostenpflichtiges Abonnement](https://logto.io/pricing) benötigst. Du kannst den Free-Plan oder Pro-Plan abonnieren, um einen Produktionsmandanten zu erstellen. Wenn du den Free-Plan abonnierst, kannst du maximal 10 Mandanten erstellen. +Der Produktionsmandant ist der Ort, an dem Endbenutzer auf die Live-App zugreifen und du möglicherweise ein [kostenpflichtiges Abonnement](https://logto.io/pricing) benötigst. Du kannst dich für den Free-Plan oder Pro-Plan anmelden, um einen Produktionsmandanten zu erstellen. Wenn du dich für den Free-Plan anmeldest, kannst du maximal 10 Mandanten erstellen. ## MFA aktivieren \{#enable-mfa} -Erhöhe die Sicherheit deines Arbeitsbereichs, indem du Multi-Faktor-Authentifizierung (MFA) für alle Mitglieder in deinem Logto Pro / Enterprise-Mandanten verpflichtend machst. +Erhöhe die Sicherheit deines Arbeitsbereichs, indem du Multi-Faktor-Authentifizierung (MFA) für alle Mitglieder in deinem Logto Pro/Enterprise-Mandanten verpflichtend machst. Da Self-Service noch nicht verfügbar ist, [kontaktiere uns](https://logto.io/contact), um diese Funktion zu aktivieren. ## Enterprise SSO aktivieren \{#enable-enterprise-sso} -Logto Cloud unterstützt die Integration von Enterprise Single Sign-On für kostenpflichtige Mandanten, einschließlich Anbieter wie Google Workspace, Okta, Azure AD und mehr. +Logto Cloud unterstützt Enterprise Single Sign-On-Integration für Enterprise-Plan-Mandanten, einschließlich Anbieter wie Google Workspace, Okta, Azure AD und mehr. -Um zu starten, [kontaktiere uns bitte](https://logto.io/contact). Wir helfen dir bei der schnellen Einrichtung. +Um zu starten, [kontaktiere uns](https://logto.io/contact). Wir helfen dir bei der schnellen Einrichtung. ## Mandanten verlassen \{#leave-tenant} -Ein Admin kann [weitere Mitglieder einladen](/logto-cloud/tenant-member-management) zu diesem Mandanten. +Ein Admin kann [weitere Mitglieder](/logto-cloud/tenant-member-management) zu diesem Mandanten einladen. -Wenn es mindestens einen weiteren **Admin** (Rolle) gibt oder du ein **Kollaborateur** (Rolle) bist, kannst du den Mandanten verlassen. Nach dem Verlassen bleiben alle Ressourcen im Mandanten erhalten, aber du hast keinen Zugriff mehr darauf. +Wenn es mindestens einen weiteren **Admin** (Rolle) gibt oder du ein **Mitarbeiter** (Rolle) bist, kannst du den Mandanten verlassen. Nach dem Verlassen bleiben alle Ressourcen im Mandanten erhalten, aber du hast keinen Zugriff mehr darauf. -Wenn du der letzte Admin bist, musst du einen anderen Kollaborateur zum Admin ernennen, bevor du den Mandanten verlassen kannst. +Wenn du der letzte Admin bist, musst du einen anderen Mitarbeiter zum Admin ernennen, bevor du den Mandanten verlassen kannst. ## Mandanten löschen \{#delete-tenant} -[Admins](/logto-cloud/tenant-member-management#invite-collaborators) können einen Logto-Mandanten löschen. Das Löschen eines Mandanten entfernt dauerhaft alle zugehörigen Benutzerdaten und Konfigurationen. Diese Aktion kann NICHT rückgängig gemacht werden. Logto fordert dich auf, den Mandantennamen einzugeben, um die Löschung zu bestätigen und versehentliche Löschungen zu verhindern. +[Admins](/logto-cloud/tenant-member-management#invite-collaborators) können einen Logto-Mandanten löschen. Das Löschen eines Mandanten entfernt dauerhaft alle zugehörigen Benutzerdaten und Konfigurationen. Diese Aktion kann NICHT rückgängig gemacht werden. Logto wird dich auffordern, den Mandantennamen einzugeben, um die Löschung zu bestätigen und versehentliche Löschungen zu verhindern. -Wenn du Hilfe benötigst, [kontaktiere uns bitte](https://logto.io/contact) per E-Mail. +Wenn du Hilfe benötigst, [kontaktiere uns](https://logto.io/contact) per E-Mail. ## FAQs \{#faqs}
-### Wie kann ich zwischen Logto-Mandanten oder zwischen Cloud und OSS migrieren oder alle Benutzerdaten exportieren? \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} +### Wie migriere ich zwischen Logto-Mandanten oder zwischen Cloud und OSS oder exportiere alle Benutzerdaten? \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} 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 212e7241ead..7768059da60 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 @@ -5,14 +5,14 @@ sidebar_position: 1 # Configuración de cuenta mediante Account API -## ¿Qué es el Account API de Logto? \{#what-is-logto-account-api} +## ¿Qué es Logto Account API? \{#what-is-logto-account-api} -El 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 el Management API. Aquí tienes los aspectos destacados: +El 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 el Management API. Aquí tienes los aspectos más destacados: - Acceso directo: El Account API permite a los usuarios finales acceder y gestionar directamente sus propios perfiles de cuenta sin requerir el relay del 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 llegará pronto. - 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 en el encabezado Authorization como `Bearer `. +- Autorización sin fricciones: ¡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 en el encabezado Authorization como `Bearer `. :::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. @@ -24,7 +24,7 @@ import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...otras opciones - // Añade los alcances adecuados que se ajusten a tus casos de uso. + // Añade los alcances apropiados según 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` @@ -45,16 +45,18 @@ Algunos casos de uso frecuentes se listan a continuación: - Recuperar el perfil de usuario - Actualizar el perfil de usuario - Actualizar la contraseña del usuario -- Actualizar identidades del usuario incluyendo correo electrónico, teléfono y conexiones sociales +- Actualizar las identidades del usuario incluyendo correo electrónico, teléfono y conexiones sociales - Gestionar factores de MFA (verificaciones) -Para conocer más sobre las APIs disponibles, visita [Referencia de Logto Account API](https://openapi.logto.io/group/endpoint-my-account) y [Referencia de Logto Verification API](https://openapi.logto.io/group/endpoint-verifications). +Para obtener más información sobre las APIs disponibles, visita [Referencia de Logto Account API](https://openapi.logto.io/group/endpoint-my-account) y [Referencia de Logto Verification API](https://openapi.logto.io/group/endpoint-verifications). :::note -Próximamente estarán disponibles Account APIs dedicadas para las siguientes configuraciones: MFA, SSO, datos personalizados (usuario) y eliminación de cuenta. Mientras tanto, puedes implementar estas funciones usando las Management APIs de Logto. Consulta [Configuración de cuenta mediante Management API](/end-user-flows/account-settings/by-management-api) para más detalles. +Próximamente estarán disponibles Account APIs dedicadas para las siguientes configuraciones: SSO, datos personalizados (usuario) y eliminación de cuenta. Mientras tanto, puedes implementar estas funciones usando las Management APIs de Logto. Consulta [Configuración de cuenta mediante Management API](/end-user-flows/account-settings/by-management-api) para más detalles. + +Las APIs de gestión de MFA (TOTP y códigos de respaldo) están actualmente en desarrollo y solo disponibles cuando el flag `isDevFeaturesEnabled` está en `true`. La gestión de claves WebAuthn está completamente disponible. ::: -## Cómo habilitar el Account API \{#how-to-enable-account-api} +## Cómo habilitar Account API \{#how-to-enable-account-api} Por defecto, el Account API está deshabilitado. Para habilitarlo, necesitas usar el [Management API](/integrate-logto/interact-with-management-api) para actualizar la configuración global. @@ -89,7 +91,7 @@ Aprende más sobre los detalles de la API en la [Referencia de Logto Management 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 puede usarse para acceder al 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` vacío en la solicitud de concesión de token de acceso a `/oidc/token`. ### Acceder al Account API usando el token de acceso \{#access-account-api-using-access-token} @@ -215,13 +217,25 @@ Después de verificar el código, ahora puedes usar el ID de registro de verific 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`. +### Actualizar la contraseña del usuario \{#update-users-password} + +Para actualizar la contraseña del usuario, puedes usar el endpoint `POST /api/my-account/password`. + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` + ### 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 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 probar la propiedad del correo. Llama al endpoint `POST /api/verifications/verification-code` para solicitar un código de verificación. @@ -232,7 +246,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. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -241,10 +255,10 @@ 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 actualizar el correo electrónico del usuario, establece el `verificationId` en el cuerpo de la solicitud como `newIdentifierVerificationRecordId`. +Después de verificar el código, ahora puedes actualizar el correo electrónico del usuario, estableciendo el `verificationId` en el cuerpo de la solicitud como `newIdentifierVerificationRecordId`. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -267,7 +281,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ Para usar este método, necesitas [configurar el conector SMS](/connectors/sms-connectors/), y asegurarte de que la plantilla `BindNewIdentifier` esté configurada. ::: -Similar a la actualización de correo electrónico, puedes usar el endpoint `PATCH /api/my-account/primary-phone` para actualizar o vincular un nuevo teléfono. Y usar el endpoint `DELETE /api/my-account/primary-phone` para eliminar el teléfono del usuario. +De manera similar a la actualización de correo electrónico, puedes usar el endpoint `PATCH /api/my-account/primary-phone` para actualizar o vincular un nuevo teléfono. Y usar el endpoint `DELETE /api/my-account/primary-phone` para eliminar el teléfono del usuario. ### Vincular una nueva conexión social \{#link-a-new-social-connection} @@ -284,7 +298,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ - `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 usa para prevenir ataques CSRF. -En la respuesta, encontrarás un `verificationRecordId`, guárdalo para usarlo más adelante. +En la respuesta, encontrarás un `verificationRecordId`, guárdalo para su 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` para verificar la conexión social. @@ -317,7 +331,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 WebAuthn \{#link-a-new-webauthn-passkey} :::note Recuerda [habilitar MFA y WebAuthn](/end-user-flows/mfa) primero. @@ -329,11 +343,11 @@ Para usar este método, necesitas habilitar el campo `mfa` en la configuración **Paso 0: Añade el origen de tu app front-end a los orígenes relacionados.** -Una clave de acceso en el navegador está vinculada a un hostname específico (RP ID), y solo el origen del RP ID puede usarse para registrar o verificar una clave de acceso. Sin embargo, tu app front-end que envía la solicitud al Account API no es la misma que la página de inicio de sesión de Logto, así que necesitas añadir el origen de tu app front-end a la lista de orígenes relacionados. Esto permitirá que tu app front-end registre y verifique una clave de acceso bajo otros RP IDs. +Una clave en el navegador está vinculada a un hostname específico (RP ID), y solo el origen del RP ID puede usarse para registrar o verificar una clave. Sin embargo, tu app front-end que envía la solicitud al Account API no es la misma que la página de inicio de sesión de Logto, por lo que necesitas añadir el origen de tu app front-end a la lista de orígenes relacionados. Esto permitirá que tu app front-end registre y verifique una clave bajo otros RP IDs. -Por defecto, Logto establecerá el RP ID al dominio del tenant, por ejemplo, si tu dominio de tenant es `https://example.logto.app`, el RP ID será `example.logto.app`. Si usas un dominio personalizado, el RP ID será el dominio personalizado, por ejemplo, si tu dominio personalizado es `https://auth.example.com`, el RP ID será `auth.example.com`. +Por defecto, Logto establecerá el RP ID en el dominio del tenant, por ejemplo, si tu dominio es `https://example.logto.app`, el RP ID será `example.logto.app`. Si usas un dominio personalizado, el RP ID será el dominio personalizado, por ejemplo, si tu dominio personalizado es `https://auth.example.com`, el RP ID será `auth.example.com`. -Ahora, añade el origen de tu app front-end a los orígenes relacionados, por ejemplo, si el origen de tu app front-end es `https://account.example.com`: +Ahora, añade el origen de tu app front-end a los orígenes relacionados, por ejemplo, si el origen es `https://account.example.com`: ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -344,7 +358,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ Para saber más sobre los orígenes relacionados, consulta la documentación de [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/). -**Paso 1: solicita nuevas opciones de registro.** +**Paso 1: solicitar nuevas opciones de registro.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -352,7 +366,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat -H 'content-type: application/json' ``` -Recibirás una respuesta como: +Obtendrás una respuesta como: ```json { @@ -362,9 +376,9 @@ Recibirás una respuesta como: } ``` -**Paso 2: registra la clave de acceso en el navegador local.** +**Paso 2: registrar la clave en el navegador local.** -Tomando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como ejemplo, puedes usar la función `startRegistration` para registrar la clave de acceso en el navegador local. +Usando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como ejemplo, puedes usar la función `startRegistration` para registrar la clave en el navegador local. ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -376,7 +390,7 @@ const response = await startRegistration({ // Guarda la respuesta para usarla después ``` -**Paso 3: verifica la clave de acceso.** +**Paso 3: verificar la clave.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -388,7 +402,7 @@ 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 4: finalmente, puedes vincular la clave de acceso.** +**Paso 4: finalmente, puedes vincular la clave.** ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -399,12 +413,12 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ``` - `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 del factor MFA, actualmente solo se admite `WebAuthn`. +- `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 clave de acceso WebAuthn existente \{#manage-existing-webauthn-passkey} +### Gestionar clave WebAuthn existente \{#manage-existing-webauthn-passkey} -Para gestionar una clave de acceso WebAuthn existente, puedes usar el endpoint `GET /api/my-account/mfa-verifications` para obtener las claves actuales y otros factores de verificación MFA. +Para gestionar una clave WebAuthn existente, puedes usar el endpoint `GET /api/my-account/mfa-verifications` para obtener las claves actuales y otros factores de verificación MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -427,11 +441,11 @@ El cuerpo de la respuesta sería así: ``` - `id`: el ID de la verificación. -- `type`: el tipo de la verificación, `WebAuthn` para clave de acceso WebAuthn. -- `name`: el nombre de la clave de acceso, campo opcional. -- `agent`: el user agent de la clave de acceso. +- `type`: el tipo de la verificación, `WebAuthn` para clave WebAuthn. +- `name`: el nombre de la clave, campo opcional. +- `agent`: el user agent de la clave. -Actualizar el nombre de la clave de acceso: +Actualizar el nombre de la clave: ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -441,10 +455,160 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Eliminar la clave de acceso: +Eliminar la clave: ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### Vincular un nuevo TOTP \{#link-a-new-totp} + +:::note +Recuerda [habilitar MFA y TOTP](/end-user-flows/mfa) primero. +::: + +:::note +Para usar este método, necesitas habilitar el campo `mfa` en la configuración del centro de cuentas. +::: + +**Paso 1: Generar un secreto TOTP.** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +El cuerpo de la respuesta sería así: + +```json +{ + "secret": "..." +} +``` + +**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). + +El formato URI para el código QR debe ser: + +``` +otpauth://totp/[Emisor]:[Cuenta]?secret=[Secreto]&issuer=[Emisor] +``` + +Ejemplo: + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**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: + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `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. +::: + +### Gestionar códigos de respaldo \{#manage-backup-codes} + +:::note +Recuerda [habilitar MFA y códigos de respaldo](/end-user-flows/mfa) primero. +::: + +:::note +Para usar este método, necesitas habilitar el campo `mfa` en la configuración del centro de cuentas. +::: + +**Paso 1: Generar nuevos códigos de respaldo:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +El cuerpo de la respuesta sería así: + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**Paso 2: Mostrar los códigos de respaldo al usuario:** + +:::important +Antes de vincular los códigos de respaldo a la cuenta del usuario, debes mostrárselos y pedirle que: + +- Descargue o anote estos códigos inmediatamente +- Los guarde en un lugar seguro +- Entienda que cada código solo puede usarse 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). +::: + +**Paso 3: Vincular los códigos de respaldo a la cuenta del usuario:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `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. +- 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. + +::: + +**Ver códigos de respaldo existentes:** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +El cuerpo de la respuesta sería así: + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`: el código de respaldo. +- `usedAt`: la marca de tiempo cuando se usó el código, `null` si aún no se ha usado. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/es/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index f06bd7cfd89..2b28de558c2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -34,9 +34,9 @@ Cuando creas un inquilino, puedes elegir la región donde se almacenarán los da - Australia (Este de Australia) - Japón (Este de Japón) -Normalmente, deberías elegir la región más cercana a tus clientes para minimizar la latencia y mejorar el rendimiento. +Por lo general, debes elegir la región más cercana a tus clientes para minimizar la latencia y mejorar el rendimiento. -Logto aprovecha la red global edge para ofrecer el mejor rendimiento y disponibilidad para tus aplicaciones. El enrutamiento de solicitudes está optimizado para garantizar que tus usuarios siempre estén conectados con la mejor opción disponible. +Logto aprovecha la red global edge para ofrecer el mejor rendimiento y disponibilidad para tus aplicaciones. El enrutamiento de solicitudes está optimizado para garantizar que tus usuarios siempre estén conectados con la opción de mejor rendimiento. :::note ¿Buscas otra región? [Ponte en contacto con nosotros](https://logto.io/contact) para: @@ -47,33 +47,38 @@ Logto aprovecha la red global edge para ofrecer el mejor rendimiento y disponibi ## Tipos de inquilino: Dev vs. Prod \{#tenant-types-dev-vs-prod} -Hay dos tipos de inquilinos en Logto Cloud: desarrollo y producción. Con esta diferenciación, puedes gestionar mejor tus proyectos en diferentes entornos para mayor eficiencia y, al mismo tiempo, disfrutar de todo el valor de Logto. +Hay dos tipos de inquilinos en Logto Cloud: Desarrollo (Dev) y Producción (Prod). Con esta diferenciación de inquilinos, puedes gestionar mejor tus proyectos en diferentes entornos para mayor eficiencia y, al mismo tiempo, disfrutar de todo el valor de Logto. Puedes elegir el tipo de inquilino durante la creación. Cuando estés listo para pasar a producción, hay dos opciones: - **Crear un nuevo inquilino de Producción** Configura un inquilino de producción desde cero. Esto es ideal si deseas mantener separados los entornos de desarrollo y producción. -- **Convertir tu inquilino Dev actual en Producción** - Si prefieres no rehacer la configuración ni migrar usuarios, puedes actualizar tu inquilino de desarrollo existente a un inquilino de producción de pago suscribiéndote a nuestro plan Pro (desde $16/mes). - - Cualquier función de pago que hayas usado en el inquilino Dev se trasladará al checkout de Stripe. - - **Una vez convertido, el inquilino no puede volver a un entorno Dev, por favor confirma que estás listo antes de continuar.** +- **Convertir tu inquilino Dev actual a Producción** + Si prefieres no rehacer la configuración ni migrar usuarios, puedes actualizar tu inquilino de Desarrollo existente a un inquilino de Producción de pago. + + - **Convertir a un plan Pro**: Ve a Consola > Configuración del inquilino > Configuración, luego haz clic en "Convertir" para actualizar por autoservicio. Cualquier función de pago que hayas usado en el inquilino dev se trasladará al checkout de Stripe. + - **Convertir a un plan Enterprise**: [Contáctanos](https://logto.io/contact) y te ayudaremos a completar la actualización. + + :::note + Una vez convertido, el inquilino no puede volver a un entorno Dev; por favor, confirma que estás listo antes de continuar. + ::: ### Desarrollo \{#development} -El inquilino de desarrollo (inquilino Dev) está destinado principalmente a fines de prueba y no debe utilizarse en un entorno de producción. Estos inquilinos permiten el acceso a funciones premium y de pago disponibles en los planes de pago, de forma gratuita y sin necesidad de suscripción. +El inquilino de desarrollo (dev tenant) está destinado principalmente a fines de prueba y no debe utilizarse en un entorno de producción. Estos inquilinos permiten el acceso a funciones premium y de pago disponibles en los planes de pago, de forma gratuita y sin requerir suscripción. Sin embargo, existen ciertas limitaciones que se aplican a los inquilinos de desarrollo: - El inquilino Dev eliminará automáticamente usuarios y organizaciones después de 90 días. -- Aparece un banner durante la experiencia de inicio de sesión, indicando que el inquilino está en modo de desarrollo. +- Aparece un banner durante la experiencia de inicio de sesión, indicando que el inquilino está en modo desarrollo. - Los inquilinos de desarrollo pueden tener límites de cuota en funciones específicas. Estos límites se explican en la página de detalles de la función, si corresponde. -- Logto puede actualizar los límites de cuota del inquilino de desarrollo, e intentaremos notificarte con antelación. +- Logto puede actualizar los límites de cuota del inquilino de desarrollo, y trataremos de notificarte con antelación. | Función | Límite de entidad | | ---------------------------------- | ----------------- | | **Tokens incluidos** | 100k por mes | -| **Aplicaciones** | -| Total de aplicaciones | 100 | +| **Aplicaciones** | | +| Aplicaciones totales | 100 | | Aplicaciones máquina a máquina | 100 | | Aplicaciones de terceros | 100 | | **Recursos de API** | | @@ -103,11 +108,11 @@ El inquilino de producción es donde los usuarios finales acceden a la aplicaci Mejora la seguridad de tu espacio de trabajo exigiendo la Autenticación Multifactor (MFA) para todos los miembros de tu inquilino Logto Pro/Enterprise. -Dado que el autoservicio aún no está disponible, por favor [contáctanos](https://logto.io/contact) para habilitar esta función. +Como el autoservicio aún no está disponible, por favor [contáctanos](https://logto.io/contact) para habilitar esta función. ## Habilitar SSO empresarial \{#enable-enterprise-sso} -Logto Cloud admite la integración de inicio de sesión único empresarial para inquilinos de pago, incluidos proveedores como Google Workspace, Okta, Azure AD y más. +Logto Cloud admite la integración de inicio de sesión único empresarial para inquilinos del Plan Enterprise, incluidos proveedores como Google Workspace, Okta, Azure AD y más. Para comenzar, por favor [contáctanos](https://logto.io/contact). Te ayudaremos a configurarlo rápidamente. @@ -115,11 +120,11 @@ Para comenzar, por favor [contáctanos](https://logto.io/contact). Te ayudaremos Un administrador puede [invitar miembros adicionales](/logto-cloud/tenant-member-management) a este inquilino. -Si hay al menos otro **administrador** (rol), o si eres un **colaborador** (rol), puedes optar por abandonar el inquilino. Después de salir, todos los recursos del inquilino permanecerán, pero ya no tendrás acceso a ellos. +Si hay al menos otro **admin** (rol), o si eres un **colaborador** (rol), puedes optar por abandonar el inquilino. Después de salir, todos los recursos del inquilino permanecerán, pero ya no tendrás acceso a ellos. Si eres el último administrador, debes asignar a otro colaborador como administrador antes de poder salir. -## Eliminar el inquilino \{#delete-tenant} +## Eliminar inquilino \{#delete-tenant} [Los administradores](/logto-cloud/tenant-member-management#invite-collaborators) pueden eliminar un inquilino de Logto. Eliminar un inquilino elimina permanentemente todos los datos de usuario y configuraciones asociadas. Esta acción NO SE PUEDE deshacer. Logto te pedirá que ingreses el nombre del inquilino para confirmar y ayudar a prevenir eliminaciones accidentales. @@ -136,7 +141,7 @@ Si necesitas ayuda, por favor [contáctanos](https://logto.io/contact) por corre Actualmente puedes convertir tu inquilino de **Desarrollo** en un inquilino de **Producción** de pago por ti mismo. [Más información](#tenant-types-dev-vs-prod) -Sin embargo, la migración de autoservicio (todas las configuraciones y datos de usuario) entre Logto Cloud y la versión OSS no está soportada. Si necesitas este servicio, por favor [contacta al equipo de Logto](https://logto.io/contact) para discutir tus opciones. +Sin embargo, la migración por autoservicio (todas las configuraciones y datos de usuario) entre Logto Cloud y la versión OSS no está soportada. Si necesitas este servicio, por favor [contacta al equipo de Logto](https://logto.io/contact) para discutir tus opciones. Si planeas dejar de usar Logto Cloud para un proyecto, Logto puede ayudarte a exportar todos los datos de usuario. Por favor, [ponte en contacto con nosotros](https://logto.io/contact). 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 e3e440cf1b3..167b367518e 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 @@ -10,12 +10,12 @@ sidebar_position: 1 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 : - 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 total sur les paramètres d’accès et peuvent personnaliser chaque champ. -- Autorisation transparente : L’autorisation (Authorization) est plus simple que jamais ! Utilisez simplement `client.getAccessToken()` pour obtenir un jeton opaque d’accès (Jeton d’accès (Access token)) pour OP (Logto), et attachez-le à l’en-tête Authorization sous la forme `Bearer `. +- 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 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 (Authorization) est plus simple que jamais ! Utilisez simplement `client.getAccessToken()` pour obtenir un jeton opaque d’accès (Opaque token) pour OP (Logto), et attachez-le à l’en-tête Authorization sous la forme `Bearer `. :::note -Pour garantir que le jeton d’accès (Jeton d’accès (Access token)) dispose des permissions appropriées, assurez-vous d’avoir correctement configuré les portées (Portées (Scopes)) 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 (Scopes) 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`. @@ -30,7 +30,7 @@ const config: LogtoConfig = { 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 MFA + UserScope.Identities, // Pour les APIs liées à l’identité et à la MFA UserScope.Profile, // Pour gérer le profil utilisateur ], }; @@ -48,17 +48,19 @@ Voici quelques cas d’utilisation fréquents : - 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) -Pour en savoir plus sur les APIs disponibles, consultez la [référence de l’Account API Logto](https://openapi.logto.io/group/endpoint-my-account) et la [référence de la Verification API Logto](https://openapi.logto.io/group/endpoint-verifications). +Pour en savoir plus sur les APIs disponibles, veuillez consulter la [référence de l’Account API Logto](https://openapi.logto.io/group/endpoint-my-account) et la [référence de la Verification API Logto](https://openapi.logto.io/group/endpoint-verifications). :::note -Des Account APIs dédiées pour les paramètres suivants arrivent bientôt : MFA, SSO, données personnalisées (utilisateur) et suppression de compte. En attendant, vous pouvez implémenter ces fonctionnalités via les Management APIs de Logto. Voir [Paramètres du compte via la Management API](/end-user-flows/account-settings/by-management-api) pour plus de détails. +Des Account APIs dédiées pour les paramètres suivants arrivent bientôt : SSO, données personnalisées (utilisateur) et suppression de compte. En attendant, vous pouvez implémenter ces fonctionnalités via les Management APIs de Logto. Voir [Paramètres du compte via la Management API](/end-user-flows/account-settings/by-management-api) pour plus de détails. + +Les APIs de gestion MFA (TOTP et codes de secours) sont actuellement en développement et uniquement disponibles lorsque le flag `isDevFeaturesEnabled` est à `true`. La gestion des passkeys WebAuthn est entièrement disponible. ::: ## Comment activer l’Account API \{#how-to-enable-account-api} Par défaut, l’Account API est désactivée. Pour l’activer, vous devez utiliser la [Management API](/integrate-logto/interact-with-management-api) pour mettre à jour les paramètres globaux. -Le point de terminaison `/api/account-center` peut être utilisé pour récupérer et mettre à jour les paramètres du centre de compte. Vous pouvez l’utiliser pour activer ou désactiver l’Account API et personnaliser les champs. +Le point d’accès API `/api/account-center` peut être utilisé pour récupérer et mettre à jour les paramètres du centre de compte. Vous pouvez l’utiliser pour activer ou désactiver l’Account API et personnaliser les champs. Exemple de requête : @@ -85,15 +87,15 @@ En savoir plus sur les détails de l’API dans la [référence de la Management ## Comment accéder à l’Account API \{#how-to-access-account-api} -### Récupérer un jeton d’accès (Jeton d’accès (Access token)) \{#fetch-an-access-token} +### 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 (Jeton d’accès (Access token)). Ce jeton est un jeton opaque (Jeton opaque (Opaque token)) 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 (Access token). Ce jeton est un jeton opaque (Opaque token) 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` à vide lors de la demande de jeton d’accès (Jeton d’accès (Access token)) à `/oidc/token`. +Si vous n’utilisez pas le SDK officiel, vous devez définir le champ `resource` à vide pour la requête de jeton d’accès vers `/oidc/token`. -### Accéder à l’Account API avec un jeton d’accès (Jeton d’accès (Access token)) \{#access-account-api-using-access-token} +### Accéder à l’Account API avec un jeton d’accès \{#access-account-api-using-access-token} -Vous devez inclure le jeton d’accès (Jeton d’accès (Access token)) 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 au format Bearer (`Bearer YOUR_TOKEN`) lors de l’interaction avec l’Account API. Voici un exemple pour obtenir les informations du compte utilisateur : @@ -128,7 +130,7 @@ Les champs de la réponse peuvent varier selon les paramètres du centre de comp Les informations de base du compte incluent le nom d’utilisateur, le nom, l’avatar et le profil. -Pour mettre à jour le nom d’utilisateur, le nom et l’avatar, vous pouvez utiliser le point de terminaison `PATCH /api/my-account`. +Pour mettre à jour le nom d’utilisateur, le nom et l’avatar, vous pouvez utiliser le point d’accès `PATCH /api/my-account`. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -137,7 +139,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -Pour mettre à jour le profil, vous pouvez utiliser le point de terminaison `PATCH /api/my-account/profile`. +Pour mettre à jour le profil, vous pouvez utiliser le point d’accès `PATCH /api/my-account/profile`. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -148,7 +150,7 @@ 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 (Autorisation (Authorization)) pour les opérations impliquant des identifiants et autres informations sensibles. +Pour des raisons de sécurité, l’Account API requiert une couche supplémentaire d’autorisation (Authorization) pour les opérations impliquant des identifiants et autres informations sensibles. ### Obtenir un identifiant d’enregistrement de vérification \{#get-a-verification-record-id} @@ -179,7 +181,7 @@ 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} :::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 modèle `UserPermissionValidation` est configuré. +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é. ::: Prenons l’e-mail comme exemple, demandez un nouveau code de vérification et obtenez l’identifiant d’enregistrement de vérification : @@ -215,15 +217,27 @@ Après avoir vérifié le code, vous pouvez maintenant utiliser l’identifiant Lors de l’envoi d’une requête pour mettre à jour l’identifiant de l’utilisateur, vous devez inclure l’identifiant 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} + +Pour mettre à jour le mot de passe de l’utilisateur, vous pouvez utiliser le point d’accès `POST /api/my-account/password`. + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` + ### 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 modèle `BindNewIdentifier` est configuré. +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 mettre à jour ou lier un nouvel e-mail, vous devez d’abord prouver la propriété de l’e-mail. -Appelez le point de terminaison `POST /api/verifications/verification-code` pour demander un code de vérification. +Appelez le point d’accès `POST /api/verifications/verification-code` pour demander un code de vérification. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -241,10 +255,10 @@ 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 mettre à jour l’e-mail de l’utilisateur, en définissant le `verificationId` dans le corps de la requête comme `newIdentifierVerificationRecordId`. +Après avoir vérifié le code, vous pouvez maintenant mettre à jour l’e-mail de l’utilisateur, en définissant le `verificationId` dans le corps de la requête sous `newIdentifierVerificationRecordId`. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -253,7 +267,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ ### Supprimer l’e-mail de l’utilisateur \{#remove-the-users-email} -Pour supprimer l’e-mail de l’utilisateur, vous pouvez utiliser le point de terminaison `DELETE /api/my-account/primary-email`. +Pour supprimer l’e-mail de l’utilisateur, vous pouvez utiliser le point d’accès `DELETE /api/my-account/primary-email`. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -264,10 +278,10 @@ 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 modèle `BindNewIdentifier` est configuré. +Pour utiliser cette méthode, vous devez [configurer le connecteur SMS](/connectors/sms-connectors/) et vous assurer que le template `BindNewIdentifier` est configuré. ::: -De la même manière que pour la mise à jour de l’e-mail, vous pouvez utiliser le point de terminaison `PATCH /api/my-account/primary-phone` pour mettre à jour ou lier un nouveau téléphone. Et utiliser le point de terminaison `DELETE /api/my-account/primary-phone` pour supprimer le téléphone de l’utilisateur. +Comme pour la mise à jour de l’e-mail, vous pouvez utiliser le point d’accès `PATCH /api/my-account/primary-phone` pour mettre à jour ou lier un nouveau téléphone. Et utilisez le point d’accès `DELETE /api/my-account/primary-phone` pour supprimer le téléphone de l’utilisateur. ### Lier une nouvelle connexion sociale \{#link-a-new-social-connection} @@ -282,11 +296,11 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ - `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, il s’agit d’une chaîne aléatoire utilisée pour prévenir les attaques CSRF. +- `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 sur le `redirectUri` avec le paramètre `state`. Vous pouvez alors utiliser le point de terminaison `POST /api/verifications/social/verify` pour vérifier la connexion sociale. +Après que l’utilisateur a autorisé l’application, vous recevrez un callback à l’`redirectUri` avec le paramètre `state`. Vous pouvez alors utiliser le point d’accès `POST /api/verifications/social/verify` pour vérifier la connexion sociale. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -295,9 +309,9 @@ 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 du `redirectUri` dans votre page de callback, et les encapsuler en JSON comme valeur du champ `connectorData`. +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`. -Enfin, vous pouvez utiliser le point de terminaison `POST /api/my-account/identities` pour lier la connexion sociale. +Enfin, vous pouvez utiliser le point d’accès `POST /api/my-account/identities` pour lier la connexion sociale. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ @@ -309,7 +323,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ ### Supprimer une connexion sociale \{#remove-a-social-connection} -Pour supprimer une connexion sociale, vous pouvez utiliser le point de terminaison `DELETE /api/my-account/identities`. +Pour supprimer une connexion sociale, vous pouvez utiliser le point d’accès `DELETE /api/my-account/identities`. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -320,7 +334,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto ### Lier une nouvelle passkey WebAuthn \{#link-a-new-webauthn-passkey} :::note -N’oubliez pas [d’activer MFA et WebAuthn](/end-user-flows/mfa) au préalable. +N’oubliez pas d’[activer la MFA et WebAuthn](/end-user-flows/mfa) au préalable. ::: :::note @@ -331,7 +345,7 @@ Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les paramè Une passkey dans le navigateur est liée à un nom d’hôte spécifique (RP ID), et seule l’origine du RP ID peut être utilisée pour enregistrer ou vérifier une passkey. Cependant, votre application front-end qui envoie la requête à l’Account API n’est pas la même que la page de connexion Logto, vous devez donc ajouter l’origine de votre application front-end à la liste des origines associées. Cela permettra à votre application front-end d’enregistrer et de vérifier une passkey sous d’autres RP ID. -Par défaut, Logto définit le RP ID sur le domaine du tenant, par exemple, si votre domaine tenant est `https://example.logto.app`, le RP ID sera `example.logto.app`. Si vous utilisez un domaine personnalisé, le RP ID sera le domaine personnalisé, par exemple, si votre domaine personnalisé est `https://auth.example.com`, le RP ID sera `auth.example.com`. +Par défaut, Logto définit le RP ID sur le domaine du tenant, par exemple, si votre domaine de tenant est `https://example.logto.app`, le RP ID sera `example.logto.app`. Si vous utilisez un domaine personnalisé, le RP ID sera le domaine personnalisé, par exemple, si votre domaine personnalisé est `https://auth.example.com`, le RP ID sera `auth.example.com`. Ajoutons maintenant l’origine de votre application front-end aux origines associées, par exemple, si l’origine de votre application front-end est `https://account.example.com` : @@ -344,7 +358,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ Pour en savoir plus sur les origines associées, veuillez consulter la documentation [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/). -**Étape 1 : demander de nouvelles options d’enregistrement.** +**Étape 1 : Demander de nouvelles options d’enregistrement.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -362,7 +376,7 @@ Vous obtiendrez une réponse comme : } ``` -**Étape 2 : enregistrer la passkey dans le navigateur local.** +**Étape 2 : Enregistrez la passkey 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. @@ -376,7 +390,7 @@ const response = await startRegistration({ // Sauvegardez la réponse pour une utilisation ultérieure ``` -**Étape 3 : vérifier la passkey.** +**Étape 3 : Vérifiez la passkey.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -388,7 +402,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat - `payload` : La réponse du navigateur local à l’étape 2. - `verificationRecordId` : L’identifiant d’enregistrement de vérification retourné par le serveur à l’étape 1. -**Étape 4 : enfin, vous pouvez lier la passkey.** +**Étape 4 : Enfin, vous pouvez lier la passkey.** ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -398,13 +412,13 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}' ``` -- `verification_record_id` : un identifiant d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur, vous pouvez vous référer à la section [Obtenir un identifiant d’enregistrement de vérification](#get-a-verification-record-id) pour plus de détails. +- `verification_record_id` : un identifiant d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur, voir la section [Obtenir un identifiant 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’identifiant d’enregistrement de vérification retourné par le serveur à l’étape 1. ### Gérer une passkey WebAuthn existante \{#manage-existing-webauthn-passkey} -Pour gérer une passkey WebAuthn existante, vous pouvez utiliser le point de terminaison `GET /api/my-account/mfa-verifications` pour obtenir les passkeys actuelles et autres facteurs de vérification MFA. +Pour gérer une passkey WebAuthn existante, vous pouvez utiliser le point d’accès `GET /api/my-account/mfa-verifications` pour obtenir les passkeys actuelles et autres facteurs de vérification MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -448,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### Lier un nouveau TOTP \{#link-a-new-totp} + +:::note +N’oubliez pas d’[activer la MFA et TOTP](/end-user-flows/mfa) au préalable. +::: + +:::note +Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les paramètres du centre de compte. +::: + +**Étape 1 : Générez un secret TOTP.** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +Le corps de la réponse sera similaire à : + +```json +{ + "secret": "..." +} +``` + +**Étape 2 : Affichez 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). + +Le format URI pour le QR code doit être : + +``` +otpauth://totp/[Émetteur]:[Compte]?secret=[Secret]&issuer=[Émetteur] +``` + +Exemple : + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**Étape 3 : Liez 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 : + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id` : un identifiant d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur. Voir la section [Obtenir un identifiant 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. + +:::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. +::: + +### Gérer les codes de secours \{#manage-backup-codes} + +:::note +N’oubliez pas d’[activer la MFA et les codes de secours](/end-user-flows/mfa) au préalable. +::: + +:::note +Pour utiliser cette méthode, vous devez activer le champ `mfa` dans les paramètres du centre de compte. +::: + +**Étape 1 : Générez de nouveaux codes de secours :** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +Le corps de la réponse sera similaire à : + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**Étape 2 : Affichez les codes de secours à l’utilisateur :** + +:::important +Avant de lier les codes de secours au compte utilisateur, vous devez les afficher à l’utilisateur et lui demander 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 + +Vous devez afficher les codes dans un format clair et facile à copier et envisager de proposer une option de téléchargement (par exemple, sous forme de fichier texte ou PDF). +::: + +**Étape 3 : Liez les codes de secours au compte utilisateur :** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id` : un identifiant d’enregistrement de vérification valide, obtenu en vérifiant le facteur existant de l’utilisateur. Voir la section [Obtenir un identifiant 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. + +:::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. + +::: + +**Voir les codes de secours existants :** + +```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 à : + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code` : le code de secours. +- `usedAt` : l’horodatage d’utilisation du code, `null` s’il n’a pas encore été utilisé. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index d8ee2d60962..1646630c0dd 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -21,13 +21,13 @@ Pour un tenant existant, allez dans Console > Paramèt - Voir l'ID du tenant - Mettre à jour le nom du tenant - Voir la [région du tenant](#tenant-region). Cela ne peut pas être modifié après la création. -- Voir le [type de tenant](#tenant-types-dev-vs-prod). Vous pouvez convertir un tenant Dev en tenant Prod si besoin. +- Voir le [type de tenant](#tenant-types-dev-vs-prod). Vous pouvez convertir un tenant Dev en tenant Prod si nécessaire. - [Quitter le tenant](#leave-tenant) - [Supprimer le tenant](#delete-tenant) ## Région du tenant \{#tenant-region} -Lorsque vous créez un tenant, vous pouvez choisir la région où les données du tenant seront stockées. Cela ne peut pas être modifié après la création du tenant. Voici les régions disponibles : +Lorsque vous créez un tenant, vous pouvez choisir la région où les données du tenant sont stockées. Cela ne peut pas être modifié après la création du tenant. Voici les régions disponibles : - Europe (Pays-Bas) - Ouest des États-Unis (Arizona) @@ -45,18 +45,23 @@ Vous cherchez une autre région ? [Contactez-nous](https://logto.io/contact) pou - Vous renseigner sur un déploiement Logto Private Cloud dans l'emplacement de votre choix ::: -## Types de tenant : Dev vs. Prod \{#tenant-types-dev-vs-prod} +## Types de tenants : Dev vs. Prod \{#tenant-types-dev-vs-prod} -Il existe deux types de tenants dans Logto Cloud : développement et production. Grâce à cette différenciation, vous pouvez mieux gérer vos projets sur différents environnements pour plus d'efficacité, tout en profitant pleinement de Logto. +Il existe deux types de tenants dans Logto Cloud : Développement (Dev) et Production (Prod). Grâce à cette différenciation, vous pouvez mieux gérer vos projets sur différents environnements pour plus d'efficacité et, en même temps, profiter pleinement de Logto. Vous pouvez choisir le type de tenant lors de la création. Lorsque vous êtes prêt à passer en production, deux options s'offrent à vous : - **Créer un nouveau tenant Production** - Configurez un tenant de production neuf et paramétrez-le depuis le début. C'est idéal si vous souhaitez séparer les environnements de développement et de production. + Configurez un nouveau tenant de production et paramétrez-le depuis zéro. C'est idéal si vous souhaitez séparer les environnements de développement et de production. - **Convertir votre tenant Dev actuel en Production** - Si vous préférez ne pas refaire la configuration ou migrer les utilisateurs, vous pouvez passer votre tenant dev existant à un tenant de production payant en souscrivant à notre offre Pro (à partir de 16 $ / mois). - - Toutes les fonctionnalités payantes utilisées dans le tenant dev seront reportées lors du paiement Stripe. - - **Une fois converti, le tenant ne peut plus être ramené à un environnement dev, veuillez confirmer que vous êtes prêt avant de continuer.** + Si vous préférez ne pas refaire la configuration ou migrer les utilisateurs, vous pouvez mettre à niveau votre tenant Développement existant vers un tenant Production payant. + + - **Convertir en offre Pro** : Rendez-vous dans Console > Paramètres du tenant > Paramètres, puis cliquez sur "Convertir" pour effectuer la mise à niveau en libre-service. Toutes les fonctionnalités payantes que vous avez utilisées dans le tenant dev seront reportées sur le paiement Stripe. + - **Convertir en offre Enterprise** : [Contactez-nous](https://logto.io/contact) et nous vous aiderons à finaliser la mise à niveau. + + :::note + Une fois converti, le tenant ne peut plus être ramené à un environnement Dev ; veuillez confirmer que vous êtes prêt avant de poursuivre. + ::: ### Développement \{#development} @@ -64,7 +69,7 @@ Le tenant de développement (tenant dev) est principalement destiné aux tests e Cependant, certaines limitations s'appliquent aux tenants de développement : -- Le tenant dev supprimera automatiquement les utilisateurs et organisations de plus de 90 jours. +- Le tenant dev supprimera automatiquement les utilisateurs et organisations après 90 jours. - Une bannière apparaît lors de l'expérience de connexion, indiquant que le tenant est en mode développement. - Les tenants de développement peuvent avoir des limites de quota sur certaines fonctionnalités. Ces limites sont expliquées sur la page de détails de la fonctionnalité, le cas échéant. - Logto peut mettre à jour les limites de quota du tenant de développement, et nous ferons de notre mieux pour vous en informer à l'avance. @@ -74,7 +79,7 @@ Cependant, certaines limitations s'appliquent aux tenants de développement : | **Jetons inclus** | 100k / mois | | **Applications** | | Applications totales | 100 | -| Applications machine à machine | 100 | +| Applications M2M | 100 | | Applications tierces | 100 | | **Ressources API** | | | Nombre de ressources | 100 | @@ -97,23 +102,23 @@ Cependant, certaines limitations s'appliquent aux tenants de développement : ### Production \{#production} -Le tenant de production est celui où les utilisateurs finaux accèdent à l'application en direct et vous pourriez avoir besoin d'[un abonnement payant](https://logto.io/pricing). Vous pouvez souscrire à l'offre Free ou Pro pour créer un tenant de production. Si vous choisissez l'offre Free, vous ne pouvez créer que jusqu'à 10 tenants. +Le tenant de production est celui où les utilisateurs finaux accèdent à l'application en direct et où vous pourriez avoir besoin d'un [abonnement payant](https://logto.io/pricing). Vous pouvez souscrire à l'offre Free ou Pro pour créer un tenant de production. Si vous choisissez l'offre Free, vous ne pouvez créer que jusqu'à 10 tenants. ## Activer MFA \{#enable-mfa} -Renforcez la sécurité de votre espace de travail en exigeant l'authentification multi-facteurs (MFA) pour tous les membres de votre tenant Logto Pro / Enterprise. +Renforcez la sécurité de votre espace de travail en exigeant l’authentification multi-facteurs (MFA) pour tous les membres de votre tenant Logto Pro / Enterprise. -L'auto-service n'étant pas encore disponible, veuillez [nous contacter](https://logto.io/contact) pour activer cette fonctionnalité. +Comme le libre-service n'est pas encore disponible, veuillez [nous contacter](https://logto.io/contact) pour activer cette fonctionnalité. ## Activer le SSO d’entreprise \{#enable-enterprise-sso} -Logto Cloud prend en charge l'intégration de l’authentification unique d’entreprise pour les tenants payants, y compris des fournisseurs comme Google Workspace, Okta, Azure AD, et plus encore. +Logto Cloud prend en charge l'intégration de l’authentification unique d’entreprise (SSO) pour les tenants Enterprise Plan, y compris des fournisseurs comme Google Workspace, Okta, Azure AD, et plus encore. Pour commencer, veuillez [nous contacter](https://logto.io/contact). Nous vous aiderons à le configurer rapidement. ## Quitter le tenant \{#leave-tenant} -Un administrateur peut [inviter d'autres membres](/logto-cloud/tenant-member-management) sur ce tenant. +Un admin peut [inviter d'autres membres](/logto-cloud/tenant-member-management) sur ce tenant. S'il y a au moins un autre **admin** (rôle), ou si vous êtes un **collaborateur** (rôle), vous pouvez choisir de quitter le tenant. Après votre départ, toutes les ressources du tenant resteront, mais vous n'y aurez plus accès. @@ -121,7 +126,7 @@ Si vous êtes le dernier admin, vous devez d'abord nommer un autre collaborateur ## Supprimer le tenant \{#delete-tenant} -Les [admins](/logto-cloud/tenant-member-management#invite-collaborators) peuvent supprimer un tenant Logto. La suppression d'un tenant efface définitivement toutes les données utilisateur et configurations associées. Cette action NE PEUT PAS être annulée. Logto vous demandera de saisir le nom du tenant pour confirmer et éviter toute suppression accidentelle. +Les [admins](/logto-cloud/tenant-member-management#invite-collaborators) peuvent supprimer un tenant Logto. La suppression d'un tenant supprime définitivement toutes les données utilisateur et configurations associées. Cette action NE PEUT PAS être annulée. Logto vous demandera de saisir le nom du tenant pour confirmer et éviter toute suppression accidentelle. Si vous avez besoin d'aide, veuillez [nous contacter](https://logto.io/contact) par e-mail. @@ -130,13 +135,13 @@ Si vous avez besoin d'aide, veuillez [nous contacter](https://logto.io/contact)
-### Comment migrer entre des tenants Logto, entre Cloud et OSS, ou exporter toutes les données utilisateur ? \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} +### Comment migrer entre des tenants Logto ou entre Cloud et OSS, ou exporter toutes les données utilisateur ? \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} -Vous pouvez actuellement convertir vous-même votre tenant **Développement** en tenant **Production** avec un plan payant. [En savoir plus](#tenant-types-dev-vs-prod) +Vous pouvez actuellement convertir vous-même votre tenant **Développement** en tenant **Production** avec une offre payante. [En savoir plus](#tenant-types-dev-vs-prod) -Cependant, la migration en auto-service (toutes les configurations et données utilisateur) entre Logto Cloud et la version OSS n'est pas prise en charge. Si vous avez besoin de ce service, veuillez [contacter l'équipe Logto](https://logto.io/contact) pour discuter de vos options. +Cependant, la migration en libre-service (toutes les configurations et données utilisateur) entre Logto Cloud et la version OSS n'est pas prise en charge. Si vous avez besoin de ce service, veuillez [contacter l'équipe Logto](https://logto.io/contact) pour discuter de vos options. Si vous prévoyez d'arrêter d'utiliser Logto Cloud pour un projet, Logto peut vous aider à exporter toutes les données utilisateur. Veuillez [nous contacter](https://logto.io/contact). 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 b69faf5eae3..bf229f20729 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,36 +1,36 @@ --- -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) のサポートも近日公開予定です。 +- 直接アクセス：Account API により、エンドユーザーは Management API の中継なしで自分のアカウントプロファイルへ直接アクセス・管理できます。 +- ユーザープロファイルとアイデンティティ管理：ユーザーはメール、電話、パスワードなどのアイデンティティ情報の更新やソーシャル接続の管理など、プロファイルやセキュリティ設定を完全に管理できます。MFA や SSO のサポートも近日公開予定です。 - グローバルアクセス制御：管理者はアクセス設定をグローバルに完全管理でき、各フィールドをカスタマイズできます。 - シームレスな認可 (Authorization)：認可 (Authorization) がこれまでになく簡単に！`client.getAccessToken()` を使って OP (Logto) 用の不透明トークン (Opaque token) を取得し、`Authorization` ヘッダーに `Bearer ` として付与するだけです。 :::note -アクセス トークン (Access token) に適切な権限があることを保証するため、Logto 設定で対応するスコープ (Scope) を正しく設定してください。 +アクセス トークン (Access token) に適切な権限 (Permissions) があることを保証するため、Logto 設定で対応するスコープ (Scopes) を正しく設定してください。 -例えば、`POST /api/my-account/primary-email` API には `email` スコープ (Scope) が必要です。`POST /api/my-account/primary-phone` API には `phone` スコープ (Scope) が必要です。 +例えば、`POST /api/my-account/primary-email` API には `email` スコープ (Scope) の設定が必要です。`POST /api/my-account/primary-phone` API には `phone` スコープ (Scope) の設定が必要です。 ```ts import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...他のオプション - // ユースケースに合った適切なスコープ (Scope) を追加してください。 + // ユースケースに合った適切なスコープ (Scopes) を追加してください。 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.Identities, // アイデンティティおよび MFA 関連 API 用 UserScope.Profile, // ユーザープロファイル管理用 ], }; @@ -48,17 +48,19 @@ Logto Account API を使えば、Logto と完全連携したプロフィール - メール・電話・ソーシャル接続などのユーザーアイデンティティの更新 - 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 Reference](https://openapi.logto.io/group/endpoint-my-account) および [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications) をご覧ください。 :::note -以下の設定用の専用 Account API は近日公開予定です：MFA、SSO、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を使ってこれらの機能を実装できます。詳細は [Management API によるアカウント設定](/end-user-flows/account-settings/by-management-api) を参照してください。 +以下の設定用の専用 Account API は近日公開予定です：SSO、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を使ってこれらの機能を実装できます。詳細は [Management API によるアカウント設定](/end-user-flows/account-settings/by-management-api) を参照してください。 + +MFA 管理 API（TOTP およびバックアップコード）は現在開発中で、`isDevFeaturesEnabled` フラグが `true` の場合のみ利用可能です。WebAuthn パスキー管理は完全に利用可能です。 ::: ## Account API を有効化する方法 \{#how-to-enable-account-api} -デフォルトでは、Account API は無効になっています。有効化するには [Management API](/integrate-logto/interact-with-management-api) を使ってグローバル設定を更新する必要があります。 +デフォルトでは、Account API は無効になっています。有効化するには、[Management API](/integrate-logto/interact-with-management-api) を使ってグローバル設定を更新する必要があります。 -API エンドポイント `/api/account-center` でアカウントセンター設定の取得・更新が可能です。これを使って Account API の有効 / 無効やフィールドのカスタマイズができます。 +API エンドポイント `/api/account-center` でアカウントセンター設定の取得・更新ができます。これを使って Account API の有効 / 無効やフィールドのカスタマイズが可能です。 リクエスト例： @@ -76,24 +78,24 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ - `profile`：プロファイルフィールド（サブフィールド含む） - `username`：ユーザー名フィールド - `email`：メールフィールド -- `phone`：電話番号フィールド -- `password`：パスワードフィールド（取得時、ユーザーがパスワードを設定していれば `true`、未設定なら `false` を返します） +- `phone`：電話フィールド +- `password`：パスワードフィールド。取得時、ユーザーがパスワードを設定していれば `true`、未設定なら `false` を返します。 - `social`：ソーシャル接続 - `mfa`：MFA 要素 -API 詳細は [Logto Management API リファレンス](https://openapi.logto.io/group/endpoint-account-center) をご覧ください。 +API の詳細は [Logto Management API Reference](https://openapi.logto.io/group/endpoint-account-center) をご覧ください。 ## Account API へのアクセス方法 \{#how-to-access-account-api} -### アクセストークンの取得 \{#fetch-an-access-token} +### アクセストークン (Access token) の取得 \{#fetch-an-access-token} -アプリケーションで SDK をセットアップした後、`client.getAccessToken()` メソッドでアクセストークン（不透明トークン）を取得できます。このトークンを使って Account API へアクセスできます。 +アプリケーションで SDK をセットアップした後、`client.getAccessToken()` メソッドでアクセストークン (Access token) を取得できます。このトークンは Account API へのアクセスに使える不透明トークン (Opaque token) です。 -公式 SDK を使わない場合は、アクセストークンの発行リクエスト `/oidc/token` で `resource` を空に設定してください。 +公式 SDK を使わない場合は、アクセストークン (Access token) の発行リクエスト `/oidc/token` で `resource` を空に設定してください。 -### アクセストークンを使った Account API へのアクセス \{#access-account-api-using-access-token} +### アクセストークン (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`）でアクセストークン (Access token) を含めてください。 ユーザーアカウント情報を取得する例： @@ -126,7 +128,7 @@ curl https://[tenant-id].logto.app/api/my-account \ ### 基本的なアカウント情報の更新 \{#update-basic-account-information} -基本的なアカウント情報にはユーザー名、名前、アバター、プロファイルが含まれます。 +基本的なアカウント情報には、ユーザー名、名前、アバター、プロファイルが含まれます。 ユーザー名・名前・アバターの更新は `PATCH /api/my-account` エンドポイントを利用します。 @@ -148,17 +150,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## 識別子やその他の機微情報の管理 \{#manage-identifiers-and-other-sensitive-information} -セキュリティ上の理由から、Account API で識別子や機微情報を扱う操作には追加の認可 (Authorization) 層が必要です。 +セキュリティ上の理由から、Account API で識別子やその他の機微情報を操作する場合は追加の認可 (Authorization) 層が必要です。 ### 検証レコード ID の取得 \{#get-a-verification-record-id} まず、検証レコード ID を取得する必要があります。これは識別子の更新時にユーザーの本人確認に使われます。 -検証レコード ID を取得するには、ユーザーのパスワードを検証するか、メールまたは電話に認証コードを送信します。 +検証レコード ID を取得するには、ユーザーのパスワードを検証するか、ユーザーのメールまたは電話に認証コードを送信します。 検証について詳しくは [Account API によるセキュリティ認証](/end-user-flows/security-verification) を参照してください。 -#### ユーザーのパスワードで認証 \{#verify-the-users-password} +#### ユーザーのパスワードで検証 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -176,10 +178,10 @@ 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 を取得します： @@ -200,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 \ @@ -209,19 +211,31 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -コードの認証が完了したら、検証レコード ID を使ってユーザーの識別子を更新できます。 +コードの検証が完了したら、検証レコード ID を使ってユーザーの識別子を更新できます。 -### 検証レコード ID を付与してリクエスト送信 \{#send-request-with-verification-record-id} +### 検証レコード ID を使ってリクエスト送信 \{#send-request-with-verification-record-id} ユーザーの識別子を更新するリクエストを送る際は、リクエストヘッダーの `logto-verification-id` フィールドに検証レコード ID を含めてください。 +### ユーザーパスワードの更新 \{#update-users-password} + +ユーザーパスワードの更新は `POST /api/my-account/password` エンドポイントを利用します。 + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` + ### 新しいメールの更新またはリンク \{#update-or-link-new-email} :::note -この方法を利用するには [メールコネクター](/connectors/email-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を利用するには、[メールコネクター](/connectors/email-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -新しいメールの所有権を証明する必要があります。 +新しいメールの更新またはリンクには、まずメールの所有権を証明する必要があります。 `POST /api/verifications/verification-code` エンドポイントで認証コードをリクエストします。 @@ -232,7 +246,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 \ @@ -241,19 +255,19 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -コード認証後、`newIdentifierVerificationRecordId` としてリクエストボディに `verificationId` を設定してメールを更新できます。 +コードの検証後、`newIdentifierVerificationRecordId` としてリクエストボディに `verificationId` を設定し、ユーザーのメールを更新できます。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}' ``` -### ユーザーのメールを削除 \{#remove-the-users-email} +### ユーザーのメールの削除 \{#remove-the-users-email} -ユーザーのメールを削除するには `DELETE /api/my-account/primary-email` エンドポイントを利用します。 +ユーザーのメールを削除するには、`DELETE /api/my-account/primary-email` エンドポイントを利用します。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -264,10 +278,10 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### 電話番号の管理 \{#manage-phone} :::note -この方法を利用するには [SMS コネクター](/connectors/sms-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を利用するには、[SMS コネクター](/connectors/sms-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -メール更新と同様に、`PATCH /api/my-account/primary-phone` で新しい電話番号の更新やリンクができます。`DELETE /api/my-account/primary-phone` でユーザーの電話番号を削除できます。 +メールの更新と同様に、`PATCH /api/my-account/primary-phone` エンドポイントで新しい電話番号の更新またはリンクができます。`DELETE /api/my-account/primary-phone` エンドポイントでユーザーの電話番号を削除できます。 ### 新しいソーシャル接続のリンク \{#link-a-new-social-connection} @@ -281,12 +295,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`：[ソーシャルコネクター](/connectors/social-connectors/) の ID -- `redirectUri`：ユーザーがアプリケーションを認可した後のリダイレクト先。ここでコールバックを受け取る Web ページをホストしてください。 -- `state`：認可後に返されるランダムな文字列。CSRF 攻撃防止用。 +- `redirectUri`：ユーザーがアプリケーションを認可 (Authorization) した後のリダイレクト先 URI。この URL でコールバックを受け取るページをホストしてください。 +- `state`：ユーザーがアプリケーションを認可 (Authorization) した後に返される state。CSRF 攻撃防止用のランダム文字列です。 -レスポンスで `verificationRecordId` が返されるので、後で使用するために保持してください。 +レスポンスに `verificationRecordId` が含まれるので、後で使用するために保持してください。 -ユーザーがアプリケーションを認可すると、`redirectUri` で `state` パラメータ付きのコールバックを受け取ります。その後、`POST /api/verifications/social/verify` エンドポイントでソーシャル接続を認証します。 +ユーザーがアプリケーションを認可 (Authorization) すると、`redirectUri` で `state` パラメータ付きのコールバックを受け取ります。その後、`POST /api/verifications/social/verify` エンドポイントでソーシャル接続を検証できます。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -295,9 +309,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` はソーシャルコネクターから返されたデータで、コールバックページの `redirectUri` からクエリパラメータを取得し、JSON 形式で `connectorData` フィールドに設定します。 +`connectorData` は、ユーザーがアプリケーションを認可 (Authorization) した後にソーシャルコネクターから返されるデータです。コールバックページで `redirectUri` のクエリパラメータをパースし、JSON 形式で `connectorData` フィールドに渡してください。 -最後に、`POST /api/my-account/identities` エンドポイントでソーシャル接続をリンクします。 +最後に、`POST /api/my-account/identities` エンドポイントでソーシャル接続をリンクできます。 ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ @@ -309,7 +323,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ ### ソーシャル接続の削除 \{#remove-a-social-connection} -ソーシャル接続を削除するには `DELETE /api/my-account/identities` エンドポイントを利用します。 +ソーシャル接続を削除するには、`DELETE /api/my-account/identities` エンドポイントを利用します。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -324,16 +338,16 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto ::: :::note -この方法を利用するには、アカウントセンター設定で `mfa` フィールドを有効にしてください。 +この方法を利用するには、アカウントセンター設定で `mfa` フィールドを有効化してください。 ::: **ステップ 0：フロントエンドアプリのオリジンを関連オリジンに追加** -ブラウザのパスキーは特定のホスト名（RP ID）に紐付き、RP ID のオリジンのみがパスキーの登録・認証に利用できます。フロントエンドアプリが Account API へリクエストする場合、Logto のサインインページとは異なるため、関連オリジンリストにフロントエンドアプリのオリジンを追加する必要があります。これにより、他の RP ID でもパスキーの登録・認証が可能になります。 +ブラウザのパスキーは特定のホスト名（RP ID）に紐づき、RP ID のオリジンのみがパスキーの登録・検証に利用できます。しかし、Account API へリクエストするフロントエンドアプリは Logto のサインインページとは異なるため、フロントエンドアプリのオリジンを関連オリジンリストに追加する必要があります。これにより、他の RP ID でもパスキーの登録・検証が可能になります。 -デフォルトでは、Logto は RP ID をテナントドメインに設定します。例：`https://example.logto.app` なら RP ID は `example.logto.app`。カスタムドメインの場合はそのドメインが RP ID です。 +デフォルトでは、Logto は RP ID をテナントドメインに設定します。たとえば、テナントドメインが `https://example.logto.app` の場合、RP ID は `example.logto.app` です。カスタムドメインを使う場合は、そのドメインが RP ID になります（例：`https://auth.example.com` なら RP ID は `auth.example.com`）。 -例：フロントエンドアプリのオリジンが `https://account.example.com` の場合、関連オリジンに追加します。 +フロントエンドアプリのオリジンが `https://account.example.com` の場合、関連オリジンに追加する例： ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -364,7 +378,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat **ステップ 2：ローカルブラウザでパスキーを登録** -[`@simplewebauthn/browser`](https://simplewebauthn.dev/) を例に、`startRegistration` 関数でローカルブラウザにパスキーを登録します。 +[`@simplewebauthn/browser`](https://simplewebauthn.dev/) を例に、`startRegistration` 関数でローカルブラウザにパスキーを登録できます。 ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -376,7 +390,7 @@ const response = await startRegistration({ // 後で使うために response を保存 ``` -**ステップ 3：パスキーの認証** +**ステップ 3：パスキーの検証** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -398,13 +412,13 @@ 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) を参照。 +- `verification_record_id`：既存要素の検証で発行された有効な検証レコード ID。詳細は [検証レコード ID の取得](#get-a-verification-record-id) セクションを参照。 - `type`：MFA 要素のタイプ。現在は `WebAuthn` のみサポート。 - `newIdentifierVerificationRecordId`：ステップ 1 でサーバーから返された検証レコード ID ### 既存 WebAuthn パスキーの管理 \{#manage-existing-webauthn-passkey} -既存の WebAuthn パスキーを管理するには、`GET /api/my-account/mfa-verifications` エンドポイントで現在のパスキーや他の MFA 要素を取得できます。 +既存の WebAuthn パスキー管理には、`GET /api/my-account/mfa-verifications` エンドポイントで現在のパスキーや他の MFA 要素を取得できます。 ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -426,8 +440,8 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`：認証要素の ID -- `type`：認証要素のタイプ。WebAuthn パスキーの場合は `WebAuthn` +- `id`：検証の ID +- `type`：検証のタイプ。WebAuthn パスキーの場合は `WebAuthn` - `name`：パスキー名（任意） - `agent`：パスキーのユーザーエージェント @@ -448,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### 新しい TOTP のリンク \{#link-a-new-totp} + +:::note +まず [MFA および TOTP を有効化](/end-user-flows/mfa) してください。 +::: + +:::note +この方法を利用するには、アカウントセンター設定で `mfa` フィールドを有効化してください。 +::: + +**ステップ 1：TOTP シークレットの生成** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +レスポンス例： + +```json +{ + "secret": "..." +} +``` + +**ステップ 2：TOTP シークレットをユーザーに表示** + +シークレットを使って QR コードを生成するか、直接ユーザーに表示します。ユーザーはこれを認証アプリ（Google Authenticator、Microsoft Authenticator、Authy など）に追加します。 + +QR コードの URI 形式： + +``` +otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] +``` + +例： + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**ステップ 3：TOTP 要素のバインド** + +ユーザーが認証アプリにシークレットを追加した後、それを検証してアカウントにバインドします： + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`：既存要素の検証で発行された有効な検証レコード ID。詳細は [検証レコード ID の取得](#get-a-verification-record-id) セクションを参照。 +- `type`：`Totp` 固定 +- `secret`：ステップ 1 で生成した TOTP シークレット + +:::note +ユーザーは TOTP 要素を 1 つしか持てません。すでに TOTP 要素がある場合、新たに追加しようとすると 422 エラーになります。 +::: + +### バックアップコードの管理 \{#manage-backup-codes} + +:::note +まず [MFA およびバックアップコードを有効化](/end-user-flows/mfa) してください。 +::: + +:::note +この方法を利用するには、アカウントセンター設定で `mfa` フィールドを有効化してください。 +::: + +**ステップ 1：新しいバックアップコードの生成** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +レスポンス例： + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**ステップ 2：バックアップコードをユーザーに表示** + +:::important +バックアップコードをユーザーアカウントにバインドする前に、必ずユーザーに表示し、以下を伝えてください： + +- すぐにこれらのコードをダウンロードまたは書き留めること +- 安全な場所に保管すること +- 各コードは一度しか使えないこと +- これらのコードは主要な MFA 手段を失った場合の最後の手段であること + +コードはコピーしやすい形式で明確に表示し、ダウンロードオプション（テキストファイルや PDF など）も検討してください。 +::: + +**ステップ 3：バックアップコードをユーザーアカウントにバインド** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`：既存要素の検証で発行された有効な検証レコード ID。詳細は [検証レコード ID の取得](#get-a-verification-record-id) セクションを参照。 +- `type`：`BackupCode` 固定 +- `codes`：前のステップで生成したバックアップコードの配列 + +:::note + +- ユーザーはバックアップコードを 1 セットしか持てません。すべてのコードを使い切った場合は新たに生成・バインドが必要です。 +- バックアップコードだけを MFA 要素とすることはできません。ユーザーは必ず他の MFA 要素（WebAuthn や TOTP など）も有効化している必要があります。 +- 各バックアップコードは一度しか使えません。 + +::: + +**既存のバックアップコードの確認** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +レスポンス例： + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`：バックアップコード +- `usedAt`：コードが使用された日時。未使用の場合は `null` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index 0b1ff49b713..8d3bb4f8840 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -6,7 +6,7 @@ sidebar_position: 2 # テナント設定 -Logto Cloud に新規登録したユーザーは、自動的に無料の **開発 (Development)** (Dev) 環境テナントにオンボーディングされます。このテナントですべての機能を試すことができます。 +Logto Cloud に新規登録したユーザーは、自動的に無料の **開発 (Development)** (Dev) 環境テナントにオンボーディングされます。このテナントで全ての機能を試すことができます。 **本番 (Production)** (Prod) 環境や新しいプロジェクト用に別のテナントを作成したい場合は、画面左上の現在のテナント名をクリックしてください。このメニューでテナントの切り替えや新規作成ができます。 @@ -36,7 +36,7 @@ Logto Cloud に新規登録したユーザーは、自動的に無料の **開 通常は、顧客に最も近いリージョンを選択することで、レイテンシを最小限に抑え、パフォーマンスを向上させることができます。 -Logto はグローバルエッジネットワークを活用し、アプリケーションに最高のパフォーマンスと可用性を提供します。リクエストルーティングは最適化されており、常にユーザーが最適な接続先にアクセスできるようになっています。 +Logto はグローバルエッジネットワークを活用し、アプリケーションに最適なパフォーマンスと可用性を提供します。リクエストルーティングは最適化されており、常にユーザーが最良のパフォーマンスで接続できるようになっています。 :::note 他のリージョンをご希望ですか？ [お問い合わせください](https://logto.io/contact)： @@ -47,16 +47,21 @@ Logto はグローバルエッジネットワークを活用し、アプリケ ## テナントタイプ：Dev と Prod \{#tenant-types-dev-vs-prod} -Logto Cloud には「開発 (Development)」と「本番 (Production)」の 2 種類のテナントがあります。この区分により、異なる環境でプロジェクトを効率的に管理しつつ、Logto の価値を最大限に活用できます。 +Logto Cloud には、開発 (Development, Dev) と本番 (Production, Prod) の 2 種類のテナントがあります。この区分により、異なる環境でプロジェクトを効率的に管理しつつ、Logto の全機能を最大限に活用できます。 テナント作成時にタイプを選択できます。本番運用の準備ができたら、次の 2 つの方法があります： - **新しい本番テナントを作成** 新規の本番テナントをセットアップし、ゼロから構成します。開発環境と本番環境を分離したい場合に最適です。 - **現在の Dev テナントを本番に変換** - 設定のやり直しやユーザー移行を避けたい場合は、既存の Dev テナントを有料の本番テナントにアップグレードできます（Pro プランのご契約が必要、月額 $16 から）。 - - Dev テナントで利用していた有料機能は Stripe チェックアウトに引き継がれます。 - - **一度変換すると、テナントを開発環境に戻すことはできません。準備ができていることを必ずご確認ください。** + 設定のやり直しやユーザーの移行を避けたい場合は、既存の開発テナントを有料の本番テナントにアップグレードできます。 + + - **Pro プランに変換**：コンソール > テナント設定 > 設定 に移動し、「変換」をクリックしてセルフサービスでアップグレードできます。Dev テナントで利用していた有料機能は Stripe チェックアウトに引き継がれます。 + - **エンタープライズプランに変換**：[お問い合わせください](https://logto.io/contact)。アップグレードをサポートします。 + + :::note + 一度変換すると、テナントを Dev 環境に戻すことはできません。準備ができていることを確認してから進めてください。 + ::: ### 開発 (Development) \{#development} @@ -64,16 +69,16 @@ Logto Cloud には「開発 (Development)」と「本番 (Production)」の 2 ただし、開発テナントには以下の制限があります： -- Dev テナントでは 90 日を超えたユーザーおよび組織が自動的に削除されます。 +- Dev テナントは 90 日を超えるユーザーおよび組織を自動的に削除します。 - サインイン体験時に、テナントが開発モードであることを示すバナーが表示されます。 - 開発テナントには特定機能にクォータ制限がある場合があります。該当する場合は機能詳細ページで説明されています。 - Logto は開発テナントのクォータ制限を更新する場合があり、事前に通知するよう努めます。 | 機能 | エンティティ上限 | | ---------------------------------------- | ---------------- | -| **含まれるトークン** | 月間 100,000 | +| **含まれるトークン** | 月あたり 100,000 | | **アプリケーション** | -| アプリケーション総数 | 100 | +| 総アプリケーション数 | 100 | | マシン間通信アプリ | 100 | | サードパーティアプリ | 100 | | **API リソース** | | @@ -92,30 +97,30 @@ Logto Cloud には「開発 (Development)」と「本番 (Production)」の 2 | 組織権限 | 100 | | **開発者・プラットフォーム** | | | Webhook | 10 | -| 監査ログ保持 | 14 日間 | +| 監査ログ保持期間 | 14 日間 | | テナントメンバー | 20 | ### 本番 (Production) \{#production} -本番テナントは、エンドユーザーが実際にアプリを利用する環境です。[有料サブスクリプション](https://logto.io/pricing) が必要な場合があります。Free プランまたは Pro プランに加入して本番テナントを作成できます。Free プランの場合、作成できるテナントは最大 10 個までです。 +本番テナントは、エンドユーザーが実際にアプリを利用する環境であり、[有料サブスクリプション](https://logto.io/pricing) が必要になる場合があります。Free プランまたは Pro プランに加入して本番テナントを作成できます。Free プランの場合、作成できるテナントは最大 10 個までです。 ## MFA 有効化 \{#enable-mfa} -Logto Pro / Enterprise テナントのすべてのメンバーに多要素認証 (MFA) を必須化することで、ワークスペースのセキュリティを強化できます。 +Logto Pro / Enterprise テナントの全メンバーに多要素認証 (MFA) を必須化することで、ワークスペースのセキュリティを強化できます。 -セルフサービスはまだ利用できないため、この機能の有効化は [お問い合わせ](https://logto.io/contact) ください。 +セルフサービスはまだ利用できないため、この機能の有効化をご希望の場合は [お問い合わせください](https://logto.io/contact)。 ## エンタープライズシングルサインオン (SSO) 有効化 \{#enable-enterprise-sso} -Logto Cloud は、有料テナント向けに Google Workspace、Okta、Azure AD などのエンタープライズシングルサインオン (SSO) 統合をサポートしています。 +Logto Cloud は、Enterprise プランテナント向けにエンタープライズシングルサインオン (SSO) 統合をサポートしています。Google Workspace、Okta、Azure AD などのプロバイダーに対応しています。 -導入をご希望の場合は、[お問い合わせ](https://logto.io/contact) ください。迅速にセットアップをサポートします。 +導入をご希望の場合は [お問い合わせください](https://logto.io/contact)。迅速にセットアップをサポートします。 ## テナントから退出 \{#leave-tenant} -管理者はこのテナントに [追加メンバーを招待](/logto-cloud/tenant-member-management) できます。 +管理者は、このテナントに [追加メンバーを招待](/logto-cloud/tenant-member-management) できます。 -**管理者**（ロール）が他に 1 人以上いる場合、または **コラボレーター**（ロール）の場合は、テナントから退出できます。退出後もテナント内のすべてのリソースは残りますが、アクセス権は失われます。 +他に少なくとも 1 人の **管理者**（ロール）がいる場合、または **コラボレーター**（ロール）の場合は、テナントから退出できます。退出後もテナント内の全リソースは残りますが、アクセス権は失われます。 最後の管理者である場合は、退出前に別のコラボレーターを管理者に割り当てる必要があります。 @@ -123,22 +128,22 @@ Logto Cloud は、有料テナント向けに Google Workspace、Okta、Azure AD [管理者](/logto-cloud/tenant-member-management#invite-collaborators) は Logto テナントを削除できます。テナントを削除すると、関連するすべてのユーザーデータと設定が完全に削除されます。この操作は元に戻せません。Logto では、誤削除防止のためテナント名の入力による確認を求めます。 -ご不明な点があれば、[メールでお問い合わせ](https://logto.io/contact) ください。 +ご不明な点があれば、[メールでお問い合わせください](https://logto.io/contact)。 ## よくある質問 \{#faqs}
-### Logto テナント間、Cloud と OSS 間の移行や、すべてのユーザーデータのエクスポート方法は？ \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} +### Logto テナント間や Cloud / OSS 間の移行、または全ユーザーデータのエクスポート方法は？ \{#how-to-migrate-between-logto-tenants-or-between-cloud-and-oss-or-export-all-user-data} -**開発 (Development)** テナントを有料プランの **本番 (Production)** テナントにご自身で変換できます。[詳細はこちら](#tenant-types-dev-vs-prod) +**開発 (Development)** テナントを有料プランの **本番 (Production)** テナントにセルフサービスで変換できます。[詳細はこちら](#tenant-types-dev-vs-prod) -ただし、Logto Cloud と OSS バージョン間での（すべての設定やユーザーデータを含む）セルフサービス移行はサポートされていません。このサービスが必要な場合は、[Logto チームまでご相談](https://logto.io/contact) ください。 +ただし、Logto Cloud と OSS バージョン間での（全設定・ユーザーデータを含む）セルフサービス移行はサポートされていません。このサービスが必要な場合は、[Logto チームまでお問い合わせ](https://logto.io/contact) ください。 -プロジェクトで Logto Cloud の利用を停止する場合、Logto ではすべてのユーザーデータのエクスポートをサポートします。[ご連絡ください](https://logto.io/contact)。 +プロジェクトで Logto Cloud の利用を停止する場合、Logto では全ユーザーデータのエクスポートをサポートします。[ご連絡ください](https://logto.io/contact)。
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 d4ba76e3447..b031fbc047e 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 @@ -7,10 +7,10 @@ sidebar_position: 1 ## 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 지원도 곧 제공될 예정입니다. +- 직접 접근: Account API는 엔드 유저가 Management API의 중계를 거치지 않고 자신의 계정 프로필에 직접 접근하고 관리할 수 있도록 합니다. +- 사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호 등 아이덴티티 정보를 업데이트하고 소셜 연결을 관리하는 등 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원도 곧 제공될 예정입니다. - 글로벌 접근 제어: 관리자는 접근 설정을 전역적으로 완전히 제어할 수 있으며 각 필드를 맞춤 설정할 수 있습니다. - 원활한 인가 (Authorization): 인가 (Authorization)가 그 어느 때보다 쉬워졌습니다! `client.getAccessToken()`을 사용하여 OP (Logto)용 불투명 토큰 (Opaque token)을 얻고, 이를 Authorization 헤더에 `Bearer ` 형식으로 첨부하세요. @@ -23,7 +23,7 @@ Logto Account API는 최종 사용자가 Management API를 거치지 않고 직 import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { - // ...기타 옵션 + // ...other options // 사용 사례에 맞는 적절한 스코프 (Scope)를 추가하세요. scopes: [ UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` API용 @@ -44,14 +44,16 @@ 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)를 방문하세요. :::note -다음 설정을 위한 전용 Account API는 곧 제공될 예정입니다: MFA, SSO, 사용자 정의 데이터, 계정 삭제. 그동안에는 Logto Management API를 사용하여 이러한 기능을 구현할 수 있습니다. 자세한 내용은 [Management API로 계정 설정하기](/end-user-flows/account-settings/by-management-api)를 참고하세요. +다음 설정을 위한 전용 Account API는 곧 제공될 예정입니다: SSO, 사용자 정의 데이터, 계정 삭제. 그동안에는 Logto Management API를 사용하여 이러한 기능을 구현할 수 있습니다. 자세한 내용은 [Management API로 계정 설정하기](/end-user-flows/account-settings/by-management-api)를 참고하세요. + +MFA 관리 API(TOTP 및 백업 코드)는 현재 개발 중이며 `isDevFeaturesEnabled` 플래그가 `true`로 설정된 경우에만 사용할 수 있습니다. WebAuthn 패스키 관리는 완전히 제공됩니다. ::: ## Account API 활성화 방법 \{#how-to-enable-account-api} @@ -77,7 +79,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ - `username`: 사용자명 필드 - `email`: 이메일 필드 - `phone`: 전화번호 필드 -- `password`: 비밀번호 필드 (조회 시, 사용자가 비밀번호를 설정했으면 `true`, 아니면 `false` 반환) +- `password`: 비밀번호 필드 (조회 시 사용자가 비밀번호를 설정했으면 `true`, 아니면 `false` 반환) - `social`: 소셜 연결 - `mfa`: MFA 요소 @@ -89,11 +91,11 @@ API 세부 정보는 [Logto Management API Reference](https://openapi.logto.io/g 애플리케이션에 SDK를 설정한 후, `client.getAccessToken()` 메서드를 사용하여 액세스 토큰 (Access token)을 가져올 수 있습니다. 이 토큰은 Account API에 접근할 수 있는 불투명 토큰 (Opaque token)입니다. -공식 SDK를 사용하지 않는 경우, `/oidc/token`에 대한 액세스 토큰 요청에서 `resource`를 비워야 합니다. +공식 SDK를 사용하지 않는 경우, 액세스 토큰 (Access token) 발급 요청 시 `/oidc/token`의 `resource`를 비워야 합니다. -### 액세스 토큰으로 Account API 접근하기 \{#access-account-api-using-access-token} +### 액세스 토큰 (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`)으로 액세스 토큰 (Access token)을 포함해야 합니다. 사용자 계정 정보를 조회하는 예시: @@ -150,13 +152,13 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ 보안상의 이유로, Account API는 식별자 및 기타 민감 정보와 관련된 작업에 대해 추가적인 인가 (Authorization) 계층을 요구합니다. -### 인증 기록 ID(verification record id) 얻기 \{#get-a-verification-record-id} +### 인증(Verification) 레코드 ID 얻기 \{#get-a-verification-record-id} -먼저, 인증 기록 ID를 얻어야 합니다. 이는 식별자 업데이트 시 사용자의 신원을 검증하는 데 사용됩니다. +먼저 인증(Verification) 레코드 ID를 얻어야 합니다. 이는 식별자 업데이트 시 사용자의 신원을 검증하는 데 사용됩니다. -인증 기록 ID를 얻으려면 사용자의 비밀번호를 검증하거나, 이메일 또는 전화번호로 인증 코드를 전송할 수 있습니다. +인증(Verification) 레코드 ID를 얻으려면 사용자의 비밀번호를 검증하거나, 이메일 또는 전화번호로 인증 코드를 전송할 수 있습니다. -인증 (Verification)에 대해 더 알아보려면 [Account API로 보안 인증](/end-user-flows/security-verification)을 참고하세요. +인증(Verification)에 대해 더 알아보려면 [Account API로 보안 인증](/end-user-flows/security-verification)을 참고하세요. #### 사용자 비밀번호 검증 \{#verify-the-users-password} @@ -176,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` 템플릿이 설정되어 있어야 합니다. ::: -이메일을 예로 들어, 새 인증 코드를 요청하고 인증 기록 ID를 얻으세요: +이메일을 예로 들어, 새 인증 코드를 요청하고 인증(Verification) 레코드 ID를 얻으세요: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -200,7 +202,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -인증 코드를 받은 후, 이를 사용하여 인증 기록의 인증 상태를 업데이트할 수 있습니다. +인증 코드를 받은 후, 이를 사용하여 인증(Verification) 레코드의 인증 상태를 업데이트할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -209,11 +211,23 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -코드 검증이 완료되면, 이제 인증 기록 ID를 사용하여 사용자의 식별자를 업데이트할 수 있습니다. +코드 검증이 완료되면, 이제 인증(Verification) 레코드 ID를 사용하여 사용자의 식별자를 업데이트할 수 있습니다. + +### 인증(Verification) 레코드 ID와 함께 요청 보내기 \{#send-request-with-verification-record-id} + +사용자 식별자를 업데이트하는 요청을 보낼 때, 요청 헤더의 `logto-verification-id` 필드에 인증(Verification) 레코드 ID를 포함해야 합니다. + +### 사용자 비밀번호 업데이트 \{#update-users-password} -### 인증 기록 ID와 함께 요청 보내기 \{#send-request-with-verification-record-id} +사용자 비밀번호를 업데이트하려면 `POST /api/my-account/password` 엔드포인트를 사용하세요. -사용자의 식별자를 업데이트하는 요청을 보낼 때, 요청 헤더의 `logto-verification-id` 필드에 인증 기록 ID를 포함해야 합니다. +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` ### 새 이메일 업데이트 또는 연결 \{#update-or-link-new-email} @@ -221,7 +235,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v 이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 설정되어 있어야 합니다. ::: -새 이메일을 업데이트하거나 연결하려면, 먼저 해당 이메일의 소유권을 증명해야 합니다. +새 이메일을 업데이트하거나 연결하려면 먼저 해당 이메일의 소유권을 증명해야 합니다. `POST /api/verifications/verification-code` 엔드포인트를 호출하여 인증 코드를 요청하세요. @@ -241,19 +255,19 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -코드 검증이 완료되면, 이제 사용자의 이메일을 업데이트할 수 있습니다. 요청 본문에 `verificationId`를 `newIdentifierVerificationRecordId`로 설정하세요. +코드 검증이 완료되면, 이제 사용자의 이메일을 업데이트할 수 있습니다. 요청 본문에 `newIdentifierVerificationRecordId`로 `verificationId`를 설정하세요. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}' ``` -### 사용자의 이메일 삭제 \{#remove-the-users-email} +### 사용자 이메일 삭제 \{#remove-the-users-email} -사용자의 이메일을 삭제하려면 `DELETE /api/my-account/primary-email` 엔드포인트를 사용하세요. +사용자 이메일을 삭제하려면 `DELETE /api/my-account/primary-email` 엔드포인트를 사용하세요. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -267,11 +281,11 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ 이 방법을 사용하려면 [SMS 커넥터](/connectors/sms-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 설정되어 있어야 합니다. ::: -이메일 업데이트와 유사하게, `PATCH /api/my-account/primary-phone` 엔드포인트로 새 전화번호를 업데이트하거나 연결할 수 있습니다. 또한 `DELETE /api/my-account/primary-phone` 엔드포인트로 사용자의 전화번호를 삭제할 수 있습니다. +이메일 업데이트와 유사하게, `PATCH /api/my-account/primary-phone` 엔드포인트로 새 전화번호를 업데이트하거나 연결할 수 있습니다. 그리고 `DELETE /api/my-account/primary-phone` 엔드포인트로 사용자의 전화번호를 삭제할 수 있습니다. ### 새 소셜 연결 추가 \{#link-a-new-social-connection} -새 소셜 연결을 추가하려면 먼저 인증 URL을 요청해야 합니다: +새 소셜 연결을 추가하려면 먼저 인가 (Authorization) URL을 요청해야 합니다: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -281,12 +295,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`를 확인하고, 이후에 사용할 수 있도록 저장하세요. -사용자가 애플리케이션을 인증하면, `redirectUri`로 콜백을 받고 `state` 파라미터를 받게 됩니다. 그런 다음 `POST /api/verifications/social/verify` 엔드포인트로 소셜 연결을 검증할 수 있습니다. +사용자가 애플리케이션을 인가하면, `redirectUri`로 `state` 파라미터와 함께 콜백을 받게 됩니다. 그런 다음 `POST /api/verifications/social/verify` 엔드포인트로 소셜 연결을 검증할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -295,9 +309,9 @@ 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` 엔드포인트를 사용하여 소셜 연결을 추가할 수 있습니다. +마지막으로, `POST /api/my-account/identities` 엔드포인트로 소셜 연결을 추가할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ @@ -317,7 +331,7 @@ 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)를 잊지 마세요. @@ -329,11 +343,11 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto **0단계: 프론트엔드 앱 오리진을 관련 오리진에 추가하세요.** -브라우저의 패스키는 특정 호스트명(RP ID)에 연결되며, 해당 RP ID의 오리진에서만 패스키 등록 또는 검증이 가능합니다. 하지만 Account API에 요청을 보내는 프론트엔드 앱은 Logto의 로그인 페이지와 다르므로, 프론트엔드 앱 오리진을 관련 오리진 목록에 추가해야 합니다. 이를 통해 프론트엔드 앱에서 다른 RP ID로 패스키를 등록 / 검증할 수 있습니다. +브라우저의 패스키는 특정 호스트네임(RP ID)에 연결되며, 해당 RP ID의 오리진에서만 패스키 등록 또는 검증이 가능합니다. 하지만 Account API에 요청을 보내는 프론트엔드 앱은 Logto의 로그인 페이지와 다르기 때문에, 프론트엔드 앱 오리진을 관련 오리진 목록에 추가해야 합니다. 이를 통해 프론트엔드 앱에서 다른 RP ID 하에서 패스키를 등록 및 검증할 수 있습니다. -기본적으로 Logto는 RP ID를 테넌트 도메인으로 설정합니다. 예를 들어, 테넌트 도메인이 `https://example.logto.app`라면 RP ID는 `example.logto.app`입니다. 커스텀 도메인을 사용하는 경우 RP ID는 커스텀 도메인입니다. 예: `https://auth.example.com` → RP ID는 `auth.example.com`. +기본적으로 Logto는 RP ID를 테넌트 도메인으로 설정합니다. 예를 들어, 테넌트 도메인이 `https://example.logto.app`라면 RP ID는 `example.logto.app`입니다. 커스텀 도메인을 사용하는 경우 RP ID는 해당 커스텀 도메인이 됩니다. 예: `https://auth.example.com` → `auth.example.com`. -이제 프론트엔드 앱 오리진이 `https://account.example.com`이라면 관련 오리진에 추가하세요: +이제 프론트엔드 앱 오리진이 `https://account.example.com`이라면, 관련 오리진에 추가하세요: ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -344,7 +358,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ 관련 오리진에 대해 더 알아보려면 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 문서를 참고하세요. -**1단계: 새 등록 옵션 요청** +**1단계: 신규 등록 옵션 요청** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -386,9 +400,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat ``` - `payload`: 2단계에서 로컬 브라우저가 반환한 응답 -- `verificationRecordId`: 1단계에서 서버가 반환한 인증 기록 ID +- `verificationRecordId`: 1단계에서 서버가 반환한 인증(Verification) 레코드 ID -**4단계: 마지막으로 패스키 연결** +**4단계: 패스키 연결** ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -398,20 +412,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`: 사용자의 기존 요소를 검증하여 부여받은 유효한 인증(Verification) 레코드 ID. 자세한 내용은 [인증(Verification) 레코드 ID 얻기](#get-a-verification-record-id) 섹션을 참고하세요. +- `type`: MFA 요소의 타입. 현재는 `WebAuthn`만 지원됩니다. +- `newIdentifierVerificationRecordId`: 1단계에서 서버가 반환한 인증(Verification) 레코드 ID ### 기존 WebAuthn 패스키 관리 \{#manage-existing-webauthn-passkey} -기존 WebAuthn 패스키를 관리하려면 `GET /api/my-account/mfa-verifications` 엔드포인트를 사용하여 현재 패스키 및 기타 MFA 인증 요소를 조회할 수 있습니다. +기존 WebAuthn 패스키를 관리하려면 `GET /api/my-account/mfa-verifications` 엔드포인트로 현재 패스키 및 기타 MFA 인증 요소를 조회할 수 있습니다. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -응답 본문 예시: +응답 예시: ```json [ @@ -426,8 +440,8 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`: 인증의 ID -- `type`: 인증 유형, WebAuthn 패스키의 경우 `WebAuthn` +- `id`: 인증 요소의 ID +- `type`: 인증 요소의 타입 (`WebAuthn`은 WebAuthn 패스키) - `name`: 패스키 이름 (선택 필드) - `agent`: 패스키의 사용자 에이전트 @@ -448,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### 새 TOTP 연결 \{#link-a-new-totp} + +:::note +먼저 [MFA 및 TOTP 활성화](/end-user-flows/mfa)를 잊지 마세요. +::: + +:::note +이 방법을 사용하려면 계정 센터 설정에서 `mfa` 필드를 활성화해야 합니다. +::: + +**1단계: TOTP 시크릿 생성** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +응답 예시: + +```json +{ + "secret": "..." +} +``` + +**2단계: 사용자에게 TOTP 시크릿 표시** + +시크릿을 사용하여 QR 코드를 생성하거나 직접 사용자에게 표시하세요. 사용자는 이를 인증 앱(예: Google Authenticator, Microsoft Authenticator, Authy)에 추가해야 합니다. + +QR 코드의 URI 형식은 다음과 같습니다: + +``` +otpauth://totp/[발급자]:[계정]?secret=[시크릿]&issuer=[발급자] +``` + +예시: + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**3단계: TOTP 요소 바인딩** + +사용자가 인증 앱에 시크릿을 추가한 후, 이를 검증하고 계정에 바인딩해야 합니다: + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`: 사용자의 기존 요소를 검증하여 부여받은 유효한 인증(Verification) 레코드 ID. 자세한 내용은 [인증(Verification) 레코드 ID 얻기](#get-a-verification-record-id) 섹션을 참고하세요. +- `type`: 반드시 `Totp`여야 합니다. +- `secret`: 1단계에서 생성한 TOTP 시크릿 + +:::note +사용자는 한 번에 하나의 TOTP 요소만 가질 수 있습니다. 이미 TOTP 요소가 있으면 추가 시 422 오류가 발생합니다. +::: + +### 백업 코드 관리 \{#manage-backup-codes} + +:::note +먼저 [MFA 및 백업 코드 활성화](/end-user-flows/mfa)를 잊지 마세요. +::: + +:::note +이 방법을 사용하려면 계정 센터 설정에서 `mfa` 필드를 활성화해야 합니다. +::: + +**1단계: 새 백업 코드 생성** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +응답 예시: + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**2단계: 사용자에게 백업 코드 표시** + +:::important +백업 코드를 사용자 계정에 바인딩하기 전에, 반드시 사용자에게 코드를 표시하고 다음을 안내해야 합니다: + +- 즉시 다운로드하거나 적어두기 +- 안전한 장소에 보관하기 +- 각 코드는 한 번만 사용할 수 있음 +- 기본 MFA 수단을 잃어버렸을 때 최후의 수단임을 인지하기 + +코드는 명확하고 복사하기 쉬운 형식으로 표시하고, 다운로드 옵션(예: 텍스트 파일, PDF 등)을 제공하는 것이 좋습니다. +::: + +**3단계: 백업 코드를 사용자 계정에 바인딩** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`: 사용자의 기존 요소를 검증하여 부여받은 유효한 인증(Verification) 레코드 ID. 자세한 내용은 [인증(Verification) 레코드 ID 얻기](#get-a-verification-record-id) 섹션을 참고하세요. +- `type`: 반드시 `BackupCode`여야 합니다. +- `codes`: 이전 단계에서 생성한 백업 코드 배열 + +:::note + +- 사용자는 한 번에 한 세트의 백업 코드만 가질 수 있습니다. 모든 코드를 사용한 경우 새 코드를 생성 및 바인딩해야 합니다. +- 백업 코드는 유일한 MFA 요소가 될 수 없습니다. 사용자는 최소 한 가지 이상의 MFA 요소(WebAuthn 또는 TOTP 등)를 활성화해야 합니다. +- 각 백업 코드는 한 번만 사용할 수 있습니다. + +::: + +**기존 백업 코드 조회** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +응답 예시: + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`: 백업 코드 +- `usedAt`: 코드가 사용된 시각. 아직 사용되지 않았다면 `null` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index 6006178b30d..dcadbcc47e9 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -6,9 +6,9 @@ sidebar_position: 2 # 테넌트 설정 -Logto Cloud에 새로 가입한 사용자는 자동으로 무료 **개발(Development)** (Dev) 환경 테넌트에 온보딩됩니다. 이 테넌트에서 모든 기능을 탐색할 수 있습니다. +Logto Cloud에 새로 가입한 사용자는 자동으로 무료 **개발 (Development, Dev)** 환경 테넌트에 온보딩됩니다. 이 테넌트에서 모든 기능을 탐색할 수 있습니다. -**프로덕션(Production)** (Prod) 환경이나 새로운 프로젝트를 위한 별도의 테넌트를 만들고 싶다면, 상단 바의 왼쪽 상단에 있는 현재 테넌트 이름을 클릭하세요. 이 메뉴에서 테넌트 간 전환 또는 새 테넌트 생성을 할 수 있습니다. +**프로덕션 (Production, Prod)** 환경이나 새로운 프로젝트를 위해 별도의 테넌트를 만들고 싶다면, 상단 바의 왼쪽 상단에 있는 현재 테넌트 이름을 클릭하세요. 이 메뉴에서 테넌트 간 전환 또는 새 테넌트 생성을 할 수 있습니다. "테넌트 생성"을 클릭한 후 다음을 진행하세요: @@ -36,86 +36,91 @@ Logto Cloud에 새로 가입한 사용자는 자동으로 무료 **개발(Develo 일반적으로 고객과 가장 가까운 지역을 선택하여 지연 시간을 최소화하고 성능을 향상시키는 것이 좋습니다. -Logto는 글로벌 엣지 네트워크를 활용하여 애플리케이션에 최고의 성능과 가용성을 제공합니다. 요청 라우팅이 최적화되어 사용자가 항상 최상의 성능을 경험할 수 있도록 연결됩니다. +Logto는 글로벌 엣지 네트워크를 활용하여 애플리케이션에 최고의 성능과 가용성을 제공합니다. 요청 라우팅이 최적화되어 사용자가 항상 최상의 성능을 경험할 수 있도록 합니다. :::note -다른 지역이 필요하신가요? [문의하기](https://logto.io/contact): +다른 지역이 필요하신가요? [문의하기](https://logto.io/contact) 를 통해: - 새로운 퍼블릭 클라우드 지역 요청 - 원하는 위치에 Logto 프라이빗 클라우드 배포 문의 ::: -## 테넌트 유형: 개발(Dev) vs. 프로덕션(Prod) \{#tenant-types-dev-vs-prod} +## 테넌트 유형: Dev vs. Prod \{#tenant-types-dev-vs-prod} -Logto Cloud에는 개발(Development)과 프로덕션(Production) 두 가지 테넌트 유형이 있습니다. 이 구분을 통해 다양한 환경에서 프로젝트를 효율적으로 관리할 수 있으며, 동시에 Logto의 모든 가치를 누릴 수 있습니다. +Logto Cloud에는 두 가지 유형의 테넌트가 있습니다: 개발 (Development, Dev)과 프로덕션 (Production, Prod). 이 테넌트 구분을 통해 다양한 환경에서 프로젝트를 효율적으로 관리할 수 있으며, 동시에 Logto의 모든 가치를 누릴 수 있습니다. 테넌트 생성 시 유형을 선택할 수 있습니다. 프로덕션 환경에서 실제 운영을 시작할 준비가 되면 두 가지 옵션이 있습니다: -- **새 프로덕션 테넌트 생성** +- **새로운 프로덕션 테넌트 생성** 새로운 프로덕션 테넌트를 생성하여 처음부터 설정하세요. 개발 환경과 프로덕션 환경을 분리하고 싶을 때 이상적입니다. - **현재 Dev 테넌트를 프로덕션으로 전환** - 설정을 다시 하거나 사용자를 마이그레이션하지 않으려면, 기존 dev 테넌트를 Pro 요금제(월 $16부터) 구독을 통해 유료 프로덕션 테넌트로 업그레이드할 수 있습니다. - - dev 테넌트에서 사용한 유료 기능은 Stripe 결제에 반영됩니다. - - **한 번 전환하면 테넌트를 dev 환경으로 되돌릴 수 없으니, 준비가 되었는지 꼭 확인하세요.** + 설정을 다시 하거나 사용자를 마이그레이션하지 않으려면, 기존 개발 테넌트를 유료 프로덕션 테넌트로 업그레이드할 수 있습니다. + + - **Pro 플랜으로 전환**: 콘솔 > 테넌트 설정 > 설정로 이동한 후 "전환"을 클릭하여 셀프 서비스로 업그레이드하세요. Dev 테넌트에서 사용한 유료 기능은 Stripe 결제에 그대로 반영됩니다. + - **엔터프라이즈 플랜으로 전환**: [문의하기](https://logto.io/contact) 를 통해 업그레이드를 도와드립니다. + + :::note + 한 번 전환하면 테넌트를 Dev 환경으로 되돌릴 수 없습니다. 준비가 되었는지 꼭 확인 후 진행하세요. + ::: ### 개발(Development) \{#development} -개발 테넌트(dev 테넌트)는 주로 테스트 용도로 사용되며, 프로덕션 환경에서는 사용하지 않아야 합니다. 이 테넌트에서는 유료 요금제에서 제공하는 프리미엄 및 유료 기능을 무료로, 구독 없이 사용할 수 있습니다. +개발 테넌트(Dev 테넌트)는 주로 테스트 용도로 사용되며, 프로덕션 환경에서는 사용하지 않아야 합니다. 이 테넌트에서는 유료 플랜에서 제공하는 프리미엄 및 유료 기능을 무료로, 구독 없이 사용할 수 있습니다. 단, 개발 테넌트에는 다음과 같은 제한이 있습니다: -- dev 테넌트는 90일이 지난 사용자 및 조직을 자동으로 삭제합니다. -- 로그인 경험 중 테넌트가 개발 모드임을 알리는 배너가 표시됩니다. +- Dev 테넌트는 90일이 지난 사용자 및 조직을 자동으로 삭제합니다. +- 로그인 경험 중에 테넌트가 개발 모드임을 알리는 배너가 표시됩니다. - 개발 테넌트는 특정 기능에 쿼터 제한이 있을 수 있습니다. 해당 제한은 기능 상세 페이지에서 확인할 수 있습니다. - Logto는 개발 테넌트의 쿼터 제한을 업데이트할 수 있으며, 사전에 최대한 안내해 드립니다. -| 기능 | 엔티티 제한 | -| -------------------- | ----------- | -| **포함된 토큰** | 월 10만 개 | -| **애플리케이션** | -| 전체 애플리케이션 수 | 100 | -| 기계 간(M2M) 앱 | 100 | -| 서드파티 앱 | 100 | -| **API 리소스** | | -| 리소스 개수 | 100 | -| **사용자 인증** | | -| 소셜 커넥터 | 100 | -| 엔터프라이즈 SSO | 100 | -| **사용자 관리** | | -| 사용자 역할 | 100 | -| 기계 간 역할 | 100 | -| 역할당 권한 | 100 | -| **조직** | | -| 조직 개수 | 5,000 | -| 조직당 사용자 | 5,000 | -| 조직 역할 | 100 | -| 조직 권한 | 100 | -| **개발자 및 플랫폼** | | -| Webhook | 10 | -| 감사 로그 보관 | 14일 | -| 테넌트 멤버 | 20 | +| 기능 | 엔티티 제한 | +| --------------------- | ----------- | +| **포함된 토큰** | 월 10만 개 | +| **애플리케이션** | +| 전체 애플리케이션 수 | 100 | +| 기계 간 애플리케이션 | 100 | +| 서드파티 애플리케이션 | 100 | +| **API 리소스** | | +| 리소스 개수 | 100 | +| **사용자 인증** | | +| 소셜 커넥터 | 100 | +| 엔터프라이즈 SSO | 100 | +| **사용자 관리** | | +| 사용자 역할 | 100 | +| 기계 간 역할 | 100 | +| 역할당 권한 | 100 | +| **조직** | | +| 조직 개수 | 5,000 | +| 조직당 사용자 수 | 5,000 | +| 조직 역할 | 100 | +| 조직 권한 | 100 | +| **개발자 및 플랫폼** | | +| Webhook | 10 | +| 감사 로그 보관 | 14일 | +| 테넌트 멤버 | 20 | ### 프로덕션(Production) \{#production} -프로덕션 테넌트는 최종 사용자가 실제 앱에 접근하는 공간이며, [유료 구독](https://logto.io/pricing)이 필요할 수 있습니다. Free 요금제 또는 Pro 요금제에 가입하여 프로덕션 테넌트를 생성할 수 있습니다. Free 요금제 구독 시 최대 10개의 테넌트만 생성할 수 있습니다. +프로덕션 테넌트는 최종 사용자가 실제 앱에 접근하는 환경이며, [유료 구독](https://logto.io/pricing)이 필요할 수 있습니다. 프로덕션 테넌트를 생성하려면 Free 플랜 또는 Pro 플랜에 가입할 수 있습니다. Free 플랜을 구독하면 최대 10개의 테넌트만 생성할 수 있습니다. ## MFA 활성화 \{#enable-mfa} -Logto Pro/Enterprise 테넌트의 모든 멤버에게 다단계 인증(MFA)을 요구하여 워크스페이스 보안을 강화하세요. +Logto Pro/Enterprise 테넌트의 모든 멤버에게 다단계 인증 (MFA)을 요구하여 워크스페이스 보안을 강화하세요. -셀프 서비스가 아직 제공되지 않으므로, 이 기능 활성화를 원하시면 [문의해 주세요](https://logto.io/contact). +셀프 서비스는 아직 지원되지 않으므로, 이 기능 활성화를 원하시면 [문의하기](https://logto.io/contact) 를 이용해 주세요. ## 엔터프라이즈 SSO 활성화 \{#enable-enterprise-sso} -Logto Cloud는 유료 테넌트에 대해 Google Workspace, Okta, Azure AD 등 다양한 공급자를 포함한 엔터프라이즈 싱글 사인온(SSO) 통합을 지원합니다. +Logto Cloud는 엔터프라이즈 플랜 테넌트에 대해 Google Workspace, Okta, Azure AD 등과 같은 공급자를 포함한 엔터프라이즈 싱글 사인온 (SSO) 통합을 지원합니다. -시작하려면 [문의해 주세요](https://logto.io/contact). 빠르게 설정할 수 있도록 도와드리겠습니다. +시작하려면 [문의하기](https://logto.io/contact) 를 이용해 주세요. 빠르게 설정을 도와드립니다. ## 테넌트 나가기 \{#leave-tenant} 관리자는 이 테넌트에 [추가 멤버를 초대](/logto-cloud/tenant-member-management)할 수 있습니다. -다른 **관리자(역할)**가 최소 한 명 이상 있거나, 본인이 **협업자(역할)**라면 테넌트에서 나갈 수 있습니다. 나간 후에도 테넌트 내 모든 리소스는 그대로 남지만, 더 이상 접근할 수 없습니다. +다른 **관리자(역할)**가 최소 한 명 이상 있거나, 본인이 **협업자(역할)**인 경우 테넌트에서 나갈 수 있습니다. 나간 후에는 테넌트 내 모든 리소스가 그대로 남지만, 더 이상 접근할 수 없습니다. 마지막 관리자인 경우, 나가기 전에 다른 협업자를 관리자로 지정해야 합니다. @@ -134,11 +139,11 @@ Logto Cloud는 유료 테넌트에 대해 Google Workspace, Okta, Azure AD 등 -현재 **개발(Development)** 테넌트를 직접 유료 플랜 **프로덕션(Production)** 테넌트로 전환할 수 있습니다. [자세히 알아보기](#tenant-types-dev-vs-prod) +현재 **개발 (Development)** 테넌트를 유료 플랜 **프로덕션 (Production)** 테넌트로 직접 전환할 수 있습니다. [자세히 알아보기](#tenant-types-dev-vs-prod) -단, Logto Cloud와 OSS 버전 간의 (모든 설정 및 사용자 데이터) 셀프 서비스 마이그레이션은 지원되지 않습니다. 이 서비스가 필요하다면 [Logto 팀에 문의](https://logto.io/contact)하여 옵션을 논의해 주세요. +단, Logto Cloud와 OSS 버전 간의 (모든 설정 및 사용자 데이터) 셀프 서비스 마이그레이션은 지원되지 않습니다. 이 서비스가 필요하다면 [Logto 팀에 문의](https://logto.io/contact)하여 옵션을 논의하세요. -Logto Cloud 사용을 중단할 계획이라면, Logto가 모든 사용자 데이터 내보내기를 도와드릴 수 있습니다. [문의해 주세요](https://logto.io/contact). +Logto Cloud 사용을 중단할 계획이라면, Logto가 모든 사용자 데이터 내보내기를 도와드릴 수 있습니다. [문의하기](https://logto.io/contact) 를 이용해 주세요.
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 042d641826d..19dd5106dea 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: Saiba como usar a Account API para gerenciar o usuário sidebar_position: 1 --- @@ -9,13 +9,13 @@ sidebar_position: 1 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: -- 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. O suporte a MFA e SSO estará disponível em breve. +- 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 da 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 a 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 opaco de acesso para OP (Logto) e anexá-lo ao cabeçalho Authorization como `Bearer `. +- Autorização sem atrito: A autorização está mais fácil do que nunca! Basta usar `client.getAccessToken()` para obter um token opaco de acesso para OP (Logto) e anexá-lo ao cabeçalho Authorization como `Bearer `. :::note -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. +Para garantir que o token de acesso tenha as permissões apropriadas, certifique-se de ter configurado corretamente os escopos correspondentes na 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`, você precisa configurar o escopo `phone`. @@ -24,7 +24,7 @@ import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...outras opções - // Adicione os escopos adequados para seus casos de uso. + // Adicione os escopos adequados para seu caso 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` @@ -51,7 +51,9 @@ Alguns casos de uso frequentes estão listados abaixo: 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). :::note -APIs dedicadas para as seguintes configurações estarão disponíveis em breve: MFA, SSO, dados personalizados (usuário) e exclusão de conta. Enquanto isso, você pode implementar esses recursos usando as Management APIs do Logto. Veja [Configurações de conta pela Management API](/end-user-flows/account-settings/by-management-api) para mais detalhes. +APIs dedicadas de Account para as seguintes configurações estão chegando em breve: SSO, Dados personalizados (usuário) e exclusão de conta. Enquanto isso, você pode implementar esses recursos usando as Management APIs do Logto. Veja [Configurações de conta pela Management API](/end-user-flows/account-settings/by-management-api) para mais detalhes. + +APIs de gerenciamento de MFA (TOTP e códigos de backup) estão atualmente em desenvolvimento e só estão disponíveis quando a flag `isDevFeaturesEnabled` está definida como `true`. O gerenciamento de passkey WebAuthn está totalmente disponível. ::: ## Como habilitar a Account API \{#how-to-enable-account-api} @@ -69,7 +71,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"enabled":true,"fields":{"username":"Edit"}}' ``` -O campo `enabled` é usado para habilitar ou desabilitar a Account API, e o campo `fields` é usado para personalizar os campos, o valor pode ser `Off`, `Edit`, `ReadOnly`. O valor padrão é `Off`. A lista de campos: +O campo `enabled` é usado para habilitar ou desabilitar a Account API, e o campo `fields` é usado para personalizar os campos, o valor pode ser `Off`, `Edit`, `ReadOnly`. O valor padrão é `Off`. Lista de campos: - `name`: O campo nome. - `avatar`: O campo avatar. @@ -77,7 +79,7 @@ O campo `enabled` é usado para habilitar ou desabilitar a Account API, e o camp - `username`: O campo nome de usuário. - `email`: O campo email. - `phone`: O campo telefone. -- `password`: O campo senha; ao obter, retornará `true` se o usuário tiver uma senha definida, caso contrário, `false`. +- `password`: O campo senha; ao obter, retorna `true` se o usuário definiu uma senha, caso contrário `false`. - `social`: Conexões sociais. - `mfa`: Fatores de MFA. @@ -87,7 +89,7 @@ Saiba mais sobre os detalhes da API em [Referência da Logto Management API](htt ### Buscar 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 buscar um token de acesso. Esse 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 para a solicitação de concessão de token de acesso para `/oidc/token`. @@ -111,7 +113,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -O corpo da resposta será semelhante a: +O corpo da resposta será assim: ```json { @@ -152,7 +154,7 @@ Por motivos de segurança, a Account API exige uma camada adicional de autoriza ### Obter um ID de registro de verificação \{#get-a-verification-record-id} -Primeiro, você precisa obter um ID de registro de verificação. Isso pode ser usado para verificar a identidade do usuário ao atualizar identificadores. +Primeiro, você precisa obter um ID de registro de verificação. Ele pode ser usado para verificar a identidade do usuário ao atualizar identificadores. Para obter um ID de registro de verificação, você pode verificar a senha do usuário ou enviar um código de verificação para o email ou telefone do usuário. @@ -167,7 +169,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -O corpo da resposta será semelhante a: +O corpo da resposta será assim: ```json { @@ -179,7 +181,7 @@ O corpo da resposta será semelhante a: #### 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, você precisa [configurar o conector de email](/connectors/email-connectors/) ou [conector 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 SMS](/connectors/sms-connectors/) e garantir que o template `UserPermissionValidation` esteja configurado. ::: Usando email como exemplo, solicite um novo código de verificação e obtenha o ID de registro de verificação: @@ -191,7 +193,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -O corpo da resposta será semelhante a: +O corpo da resposta será assim: ```json { @@ -200,7 +202,7 @@ O corpo da resposta será semelhante a: } ``` -Após 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. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ @@ -211,17 +213,29 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v Após verificar o código, agora você pode usar o ID de registro de verificação para atualizar o identificador do usuário. -### Enviar requisição com ID de registro de verificação \{#send-request-with-verification-record-id} +### Enviar requisição com o ID de registro de verificação \{#send-request-with-verification-record-id} Ao enviar uma requisição para atualizar o identificador do usuário, você precisa incluir o ID de registro de verificação no cabeçalho da requisição com o campo `logto-verification-id`. +### Atualizar a senha do usuário \{#update-users-password} + +Para atualizar a senha do usuário, você pode usar o endpoint `POST /api/my-account/password`. + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` + ### Atualizar ou vincular novo email \{#update-or-link-new-email} :::note Para usar este método, você precisa [configurar o conector de email](/connectors/email-connectors/) e garantir que o template `BindNewIdentifier` esteja configurado. ::: -Para atualizar ou vincular um novo email, primeiro você deve provar a propriedade do email. +Para atualizar ou vincular um novo email, primeiro você deve provar a posse do email. Chame o endpoint `POST /api/verifications/verification-code` para solicitar um código de verificação. @@ -244,7 +258,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v Após verificar o código, agora você pode atualizar o email do usuário, definindo o `verificationId` no corpo da requisição como `newIdentifierVerificationRecordId`. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -295,7 +309,7 @@ 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 um 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 empacotá-los como JSON no campo `connectorData`. Por fim, você pode usar o endpoint `POST /api/my-account/identities` para vincular a conexão social. @@ -317,7 +331,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto -H 'logto-verification-id: ' ``` -### Vincular uma nova chave de acesso WebAuthn \{#link-a-new-webauthn-passkey} +### Vincular uma nova passkey WebAuthn \{#link-a-new-webauthn-passkey} :::note Lembre-se de [habilitar MFA e WebAuthn](/end-user-flows/mfa) primeiro. @@ -329,11 +343,11 @@ Para usar este método, você precisa habilitar o campo `mfa` nas configuraçõe **Passo 0: Adicione a origem do seu app front-end às origens relacionadas.** -Uma chave de acesso no navegador está vinculada a um hostname específico (RP ID), e somente a origem do RP ID pode ser usada para registrar ou verificar uma chave de acesso. No entanto, seu app front-end que está enviando a requisição para a Account API não é o mesmo que a página de login do Logto, então você precisa adicionar a origem do seu app front-end à lista de origens relacionadas. Isso permitirá que seu app front-end registre e verifique uma chave de acesso sob outros RP IDs. +Uma passkey no navegador está vinculada a um hostname específico (RP ID), e somente a origem do RP ID pode ser usada para registrar ou verificar uma passkey. No entanto, seu app front-end que está enviando a requisição para a Account API não é o mesmo da página de login do Logto, então você precisa adicionar a origem do seu app front-end à lista de origens relacionadas. Isso permitirá que seu app front-end registre e verifique uma passkey sob outros RP IDs. -Por padrão, o Logto define o RP ID como o domínio do tenant, por exemplo, se seu domínio for `https://example.logto.app`, o RP ID será `example.logto.app`. Se você estiver usando um domínio personalizado, o RP ID será o domínio personalizado, por exemplo, se seu domínio for `https://auth.example.com`, o RP ID será `auth.example.com`. +Por padrão, o Logto define o RP ID como o domínio do tenant, por exemplo, se seu domínio for `https://example.logto.app`, o RP ID será `example.logto.app`. Se você estiver usando um domínio personalizado, o RP ID será o domínio personalizado, por exemplo, se for `https://auth.example.com`, o RP ID será `auth.example.com`. -Agora, adicione a origem do seu app front-end às origens relacionadas, por exemplo, se a origem do seu app for `https://account.example.com`: +Agora, vamos adicionar a origem do seu app front-end às origens relacionadas, por exemplo, se a origem for `https://account.example.com`: ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -344,7 +358,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ Para saber mais sobre origens relacionadas, consulte a documentação [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/). -**Passo 1: solicitar novas opções de registro.** +**Passo 1: Solicite novas opções de registro.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \ @@ -362,9 +376,9 @@ Você receberá uma resposta como: } ``` -**Passo 2: registrar a chave de acesso no navegador local.** +**Passo 2: Registre a passkey no navegador local.** -Usando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como exemplo, você pode usar a função `startRegistration` para registrar a chave de acesso no navegador local. +Usando [`@simplewebauthn/browser`](https://simplewebauthn.dev/) como exemplo, você pode usar a função `startRegistration` para registrar a passkey no navegador local. ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -376,7 +390,7 @@ const response = await startRegistration({ // Salve a resposta para uso posterior ``` -**Passo 3: verificar a chave de acesso.** +**Passo 3: Verifique a passkey.** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -388,7 +402,7 @@ 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 4: por fim, você pode vincular a chave de acesso.** +**Passo 4: Por fim, você pode vincular a passkey.** ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -402,16 +416,16 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ - `type`: o tipo do fator MFA, atualmente apenas `WebAuthn` é suportado. - `newIdentifierVerificationRecordId`: o ID de registro de verificação retornado pelo servidor no passo 1. -### Gerenciar chave de acesso WebAuthn existente \{#manage-existing-webauthn-passkey} +### Gerenciar passkey WebAuthn existente \{#manage-existing-webauthn-passkey} -Para gerenciar uma chave de acesso WebAuthn existente, você pode usar o endpoint `GET /api/my-account/mfa-verifications` para obter as chaves atuais e outros fatores de verificação MFA. +Para gerenciar uma passkey WebAuthn existente, você pode usar o endpoint `GET /api/my-account/mfa-verifications` para obter as passkeys atuais e outros fatores de verificação MFA. ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -O corpo da resposta será semelhante a: +O corpo da resposta será assim: ```json [ @@ -427,11 +441,11 @@ O corpo da resposta será semelhante a: ``` - `id`: o ID da verificação. -- `type`: o tipo da verificação, `WebAuthn` para chave de acesso WebAuthn. -- `name`: o nome da chave de acesso, campo opcional. -- `agent`: o user agent da chave de acesso. +- `type`: o tipo da verificação, `WebAuthn` para passkey WebAuthn. +- `name`: o nome da passkey, campo opcional. +- `agent`: o user agent da passkey. -Atualizar o nome da chave de acesso: +Atualizar o nome da passkey: ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -441,10 +455,160 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -Excluir a chave de acesso: +Excluir a passkey: ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### Vincular um novo TOTP \{#link-a-new-totp} + +:::note +Lembre-se de [habilitar MFA e TOTP](/end-user-flows/mfa) primeiro. +::: + +:::note +Para usar este método, você precisa habilitar o campo `mfa` nas configurações do centro de contas. +::: + +**Passo 1: Gerar um segredo TOTP.** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +O corpo da resposta será assim: + +```json +{ + "secret": "..." +} +``` + +**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). + +O formato URI para o QR code deve ser: + +``` +otpauth://totp/[Emissor]:[Conta]?secret=[Segredo]&issuer=[Emissor] +``` + +Exemplo: + +``` +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 precisa verificá-lo e vinculá-lo à sua conta: + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --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. +- `type`: deve ser `Totp`. +- `secret`: o segredo TOTP gerado no passo 1. + +:::note +Um usuário só pode ter um fator TOTP por vez. Se o usuário já tiver um fator TOTP, tentar adicionar outro resultará em erro 422. +::: + +### Gerenciar códigos de backup \{#manage-backup-codes} + +:::note +Lembre-se de [habilitar MFA e códigos de backup](/end-user-flows/mfa) primeiro. +::: + +:::note +Para usar este método, você precisa habilitar o campo `mfa` nas configurações do centro de contas. +::: + +**Passo 1: Gerar novos códigos de backup:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +O corpo da resposta será assim: + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**Passo 2: Exibir os códigos de backup para o usuário:** + +:::important +Antes de vincular os códigos de backup à conta do usuário, você deve exibi-los ao usuário e instruí-lo a: + +- Baixar ou anotar esses códigos imediatamente +- Armazená-los em 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 + +Você deve exibir os códigos de forma clara, fácil de copiar e considerar fornecer uma opção de download (por exemplo, como arquivo de texto ou PDF). +::: + +**Passo 3: Vincular códigos de backup à conta do usuário:** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --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. +- `type`: deve ser `BackupCode`. +- `codes`: o array de códigos de backup gerados no passo anterior. + +:::note + +- Um usuário só pode ter 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. +- Cada código de backup só pode ser usado uma vez. + +::: + +**Visualizar códigos de backup existentes:** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +O corpo da resposta será assim: + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`: o código de backup. +- `usedAt`: o timestamp de quando o código foi usado, `null` se ainda não foi usado. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index b243543f57b..35feec18916 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -10,7 +10,7 @@ Novos usuários que se registram no Logto Cloud são automaticamente integrados Se você deseja criar um tenant separado para o ambiente de **Produção** (Prod) ou para um novo projeto, clique no nome do seu tenant atual no canto superior esquerdo da barra superior. Neste menu, você pode alternar entre tenants ou criar um novo. -Clique em "Criar tenant" e então: +Clique em "Criar tenant" e, em seguida: - Nome para o tenant - Selecione uma [região de dados do tenant](#tenant-region) @@ -36,27 +36,32 @@ Ao criar um tenant, você pode escolher a região onde os dados do tenant serão Normalmente, você deve escolher a região mais próxima dos seus clientes para minimizar a latência e melhorar o desempenho. -O Logto utiliza a rede global de edge para oferecer o melhor desempenho e disponibilidade para seus aplicativos. O roteamento de solicitações é otimizado para garantir que seus usuários estejam sempre conectados à opção de melhor desempenho. +O Logto aproveita a rede global de edge para oferecer o melhor desempenho e disponibilidade para seus aplicativos. O roteamento de solicitações é otimizado para garantir que seus usuários estejam sempre conectados à opção de melhor desempenho. :::note Procurando outra região? [Entre em contato conosco](https://logto.io/contact) para: - Solicitar uma nova região de nuvem pública -- Consultar sobre uma implantação Logto Private Cloud no local de sua preferência +- Consultar sobre uma implantação Logto Private Cloud em sua localização preferida ::: ## Tipos de tenant: Dev vs. Prod \{#tenant-types-dev-vs-prod} -Existem dois tipos de tenants no Logto Cloud: desenvolvimento e produção. Com essa diferenciação de tenants, você pode gerenciar melhor seus projetos em diferentes ambientes para maior eficiência e, ao mesmo tempo, aproveitar todo o valor do Logto. +Existem dois tipos de tenants no Logto Cloud: Desenvolvimento (Dev) e Produção (Prod). Com essa diferenciação de tenants, você pode gerenciar melhor seus projetos em diferentes ambientes para maior eficiência e, ao mesmo tempo, aproveitar todo o valor do Logto. Você pode escolher o tipo de tenant durante a criação. Quando estiver pronto para ir para produção, há duas opções: - **Criar um novo tenant de Produção** Configure um tenant de produção do zero. Isso é ideal se você deseja manter os ambientes de desenvolvimento e produção separados. - **Converter seu tenant Dev atual em Produção** - Se preferir não refazer a configuração ou migrar usuários, você pode atualizar seu tenant dev existente para um tenant de produção pago assinando nosso plano Pro (a partir de $16/mês). - - Quaisquer recursos pagos que você utilizou no tenant dev serão transferidos para o checkout do Stripe. - - **Uma vez convertido, o tenant não pode ser revertido para ambiente dev, por favor, confirme que está pronto antes de prosseguir.** + Se preferir não refazer a configuração ou migrar usuários, você pode atualizar seu tenant de Desenvolvimento existente para um tenant de Produção pago. + + - **Converter para o plano Pro**: Vá para Console > Configurações do tenant > Configurações e clique em "Converter" para fazer o upgrade por autoatendimento. Quaisquer recursos pagos que você tenha usado no tenant dev serão transferidos para o checkout do Stripe. + - **Converter para o plano Enterprise**: [Entre em contato conosco](https://logto.io/contact) e ajudaremos você a concluir a atualização. + + :::note + Uma vez convertido, o tenant não pode ser revertido para o ambiente Dev; por favor, confirme que você está pronto antes de prosseguir. + ::: ### Desenvolvimento \{#development} @@ -69,45 +74,45 @@ No entanto, existem algumas limitações que se aplicam aos tenants de desenvolv - Tenants de desenvolvimento podem ter limites de cota em recursos específicos. Esses limites são explicados na página de detalhes do recurso, se aplicável. - O Logto pode atualizar os limites de cota do tenant de desenvolvimento, e tentaremos notificá-lo com antecedência. -| Recurso | Limite de entidade | -| -------------------------------- | ------------------ | -| **Tokens incluídos** | 100k por mês | -| **Aplicativos** | -| Total de aplicativos | 100 | -| Aplicativos máquina para máquina | 100 | -| Aplicativos de terceiros | 100 | -| **Recursos de API** | | -| Contagem de recursos | 100 | -| **Autenticação de usuário** | | -| Conector social | 100 | -| SSO corporativo | 100 | -| **Gerenciamento de usuários** | | -| Papéis de usuário | 100 | -| Papéis máquina para máquina | 100 | -| Permissão por papel | 100 | -| **Organizações** | | -| Contagem de organizações | 5.000 | -| Usuários por organização | 5.000 | -| Papéis da organização | 100 | -| Permissões da organização | 100 | -| **Desenvolvedores e plataforma** | | -| Webhooks | 10 | -| Retenção de log de auditoria | 14 dias | -| Membros do tenant | 20 | +| Recurso | Limite de entidades | +| -------------------------------- | ------------------- | +| **Tokens incluídos** | 100k por mês | +| **Aplicativos** | | +| Total de aplicativos | 100 | +| Aplicativos máquina para máquina | 100 | +| Aplicativos de terceiros | 100 | +| **Recursos de API** | | +| Quantidade de recursos | 100 | +| **Autenticação de usuário** | | +| Conector social | 100 | +| SSO corporativo | 100 | +| **Gerenciamento de usuários** | | +| Papéis de usuário | 100 | +| Papéis máquina para máquina | 100 | +| Permissão por papel | 100 | +| **Organizações** | | +| Quantidade de organizações | 5.000 | +| Usuários por organização | 5.000 | +| Papéis da organização | 100 | +| Permissões da organização | 100 | +| **Desenvolvedores e plataforma** | | +| Webhooks | 10 | +| Retenção de log de auditoria | 14 dias | +| Membros do tenant | 20 | ### Produção \{#production} -O tenant de produção é onde os usuários finais acessam o aplicativo em produção e você pode precisar de uma [assinatura paga](https://logto.io/pricing). Você pode assinar o plano Free ou Pro para criar um tenant de produção. Se você assinar o plano Free, poderá criar até 10 tenants. +O tenant de produção é onde os usuários finais acessam o aplicativo em produção e você pode precisar de uma [assinatura paga](https://logto.io/pricing). Você pode assinar o plano Free ou Pro para criar um tenant de produção. Se você assinar o plano Free, só poderá criar até 10 tenants. ## Ativar MFA \{#enable-mfa} Aumente a segurança do seu workspace exigindo Autenticação Multifatorial (MFA) para todos os membros do seu tenant Logto Pro/Enterprise. -Como o autoatendimento ainda não está disponível, por favor, [entre em contato conosco](https://logto.io/contact) para ativar este recurso. +Como o autoatendimento ainda não está disponível, por favor, [entre em contato conosco](https://logto.io/contact) para ativar esse recurso. ## Ativar SSO corporativo \{#enable-enterprise-sso} -O Logto Cloud suporta integração de Single Sign-On corporativo para tenants pagos, incluindo provedores como Google Workspace, Okta, Azure AD e outros. +O Logto Cloud oferece suporte à integração de autenticação única corporativa (SSO corporativo) para tenants do plano Enterprise, incluindo provedores como Google Workspace, Okta, Azure AD e outros. Para começar, por favor, [entre em contato conosco](https://logto.io/contact). Vamos ajudá-lo a configurar rapidamente. @@ -117,7 +122,7 @@ Um admin pode [convidar membros adicionais](/logto-cloud/tenant-member-managemen Se houver pelo menos outro **admin** (papel), ou se você for um **colaborador** (papel), você pode optar por sair do tenant. Após sair, todos os recursos do tenant permanecerão, mas você não terá mais acesso a eles. -Se você for o último admin, deve atribuir outro colaborador como admin antes de sair. +Se você for o último admin, deverá atribuir outro colaborador como admin antes de sair. ## Excluir tenant \{#delete-tenant} @@ -134,9 +139,9 @@ Se precisar de ajuda, por favor, [entre em contato conosco](https://logto.io/con -Atualmente, você pode converter seu tenant **Desenvolvimento** para um tenant **Produção** com plano pago por conta própria. [Saiba mais](#tenant-types-dev-vs-prod) +Atualmente, você pode converter seu tenant **Desenvolvimento** em um tenant **Produção** de plano pago por conta própria. [Saiba mais](#tenant-types-dev-vs-prod) -No entanto, a migração de autoatendimento (todas as configurações e dados de usuários) entre Logto Cloud e a versão OSS não é suportada. Se precisar desse serviço, por favor, [entre em contato com a equipe Logto](https://logto.io/contact) para discutir suas opções. +No entanto, a migração por autoatendimento (todas as configurações e dados de usuários) entre Logto Cloud e a versão OSS não é suportada. Se precisar desse serviço, por favor, [entre em contato com a equipe Logto](https://logto.io/contact) para discutir suas opções. Se você planeja parar de usar o Logto Cloud para um projeto, o Logto pode ajudá-lo a exportar todos os dados de usuários. Por favor, [fale conosco](https://logto.io/contact). 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 3f0cf3cb492..592bc9a4ac9 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 @@ -9,15 +9,15 @@ sidebar_position: 1 Logto Account API 是一套全面的 API，允许终端用户直接通过 API 访问，无需经过 Management API。主要亮点如下： -- 直接访问：Account API 让终端用户可以直接访问和管理自己的账户资料，无需通过 Management API 中转。 -- 用户资料与身份管理：用户可以完全管理自己的资料和安全设置，包括更新邮箱、手机号、密码等身份信息，以及管理社交连接。MFA 和 SSO 支持即将上线。 +- 直接访问：Account API 让终端用户可以直接访问和管理自己的账户资料，无需中转 Management API。 +- 用户资料与身份管理：用户可以完全管理自己的资料和安全设置，包括更新邮箱、手机号、密码等身份信息，以及管理社交连接。MFA（多因素认证）和 SSO（单点登录）支持即将上线。 - 全局访问控制：管理员拥有对访问设置的完全全局控制，并可自定义每个字段。 -- 无缝授权 (Authorization)：授权 (Authorization) 变得前所未有的简单！只需使用 `client.getAccessToken()` 获取 OP (Logto) 的不透明令牌 (Opaque token)，并将其作为 `Bearer ` 附加到 Authorization 头部即可。 +- 无缝授权 (Authorization)：授权 (Authorization) 变得前所未有的简单！只需使用 `client.getAccessToken()` 获取 OP（Logto） 的不透明令牌 (Opaque token)，并将其作为 `Bearer ` 附加到 Authorization 头部即可。 :::note 为确保访问令牌 (Access token) 具有适当的权限，请确保你已在 Logto 配置中正确配置了相应的权限 (Scopes)。 -例如，对于 `POST /api/my-account/primary-email` API，你需要配置 `email` 权限 (Scope)；对于 `POST /api/my-account/primary-phone` API，你需要配置 `phone` 权限 (Scope)。 +例如，`POST /api/my-account/primary-email` API 需要配置 `email` 权限 (Scope)；`POST /api/my-account/primary-phone` API 需要配置 `phone` 权限 (Scope)。 ```ts import { type LogtoConfig, UserScope } from '@logto/js'; @@ -38,7 +38,7 @@ const config: LogtoConfig = { ::: -通过 Logto Account API，你可以构建一个与 Logto 完全集成的自定义账户管理系统，比如个人资料页面。 +通过 Logto Account API，你可以构建一个与 Logto 完全集成的自定义账户管理系统，如个人资料页。 常见用例如下： @@ -51,14 +51,16 @@ const config: LogtoConfig = { 想了解更多可用 API，请访问 [Logto Account API 参考文档](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 参考文档](https://openapi.logto.io/group/endpoint-verifications)。 :::note -以下设置的专用 Account API 即将上线：MFA、SSO、用户自定义数据、账户删除。在此期间，你可以通过 Logto Management API 实现这些功能。详见 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 +以下设置的专用 Account API 即将上线：SSO、自定义数据（用户）、账户删除。在此期间，你可以使用 Logto Management API 实现这些功能。详见 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 + +MFA 管理 API（TOTP 和备份码）目前正在开发中，仅在 `isDevFeaturesEnabled` 标志设置为 `true` 时可用。WebAuthn 密钥管理已全面开放。 ::: ## 如何启用 Account API \{#how-to-enable-account-api} 默认情况下，Account API 是禁用的。要启用它，你需要使用 [Management API](/integrate-logto/interact-with-management-api) 更新全局设置。 -API 端点 `/api/account-center` 可用于获取和更新账户中心设置。你可以用它来启用或禁用 Account API，并自定义字段。 +API 端点 `/api/account-center` 可用于获取和更新账户中心设置。你可以用它来启用或禁用 Account API 并自定义字段。 请求示例： @@ -156,7 +158,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ 要获取验证记录 ID，可以验证用户密码，或向用户邮箱或手机号发送验证码。 -关于验证的更多信息，请参见 [通过 Account API 进行安全验证](/end-user-flows/security-verification)。 +想了解更多关于验证的信息，请参见 [通过 Account API 进行安全验证](/end-user-flows/security-verification)。 #### 验证用户密码 \{#verify-the-users-password} @@ -179,7 +181,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ #### 通过向用户邮箱或手机号发送验证码进行验证 \{#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： @@ -209,19 +211,31 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -验证码验证通过后，你就可以使用验证记录 ID 更新用户标识符了。 +验证码验证通过后，你就可以使用验证记录 ID 更新用户标识符。 ### 携带验证记录 ID 发送请求 \{#send-request-with-verification-record-id} -在发送更新用户标识符的请求时，需要在请求头中通过 `logto-verification-id` 字段携带验证记录 ID。 +在发送更新用户标识符的请求时，需要在请求头中以 `logto-verification-id` 字段携带验证记录 ID。 + +### 更新用户密码 \{#update-users-password} + +要更新用户密码，可以使用 `POST /api/my-account/password` 端点。 + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` ### 更新或绑定新邮箱 \{#update-or-link-new-email} :::note -使用此方法前，你需要[配置邮箱连接器](/connectors/email-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 +要使用此方法，你需要 [配置邮箱连接器](/connectors/email-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 ::: -要更新或绑定新邮箱，首先需要证明对该邮箱的所有权。 +要更新或绑定新邮箱，首先需要证明邮箱的所有权。 调用 `POST /api/verifications/verification-code` 端点请求验证码。 @@ -232,7 +246,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 \ @@ -241,10 +255,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -验证码验证通过后，你就可以更新用户邮箱，将 `verificationId` 作为 `newIdentifierVerificationRecordId` 放入请求体。 +验证码验证通过后，现在可以更新用户邮箱，将 `verificationId` 作为 `newIdentifierVerificationRecordId` 放入请求体。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -264,10 +278,10 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### 管理手机号 \{#manage-phone} :::note -使用此方法前，你需要[配置短信连接器](/connectors/sms-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 +要使用此方法，你需要 [配置 SMS 连接器](/connectors/sms-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 ::: -与更新邮箱类似，你可以使用 `PATCH /api/my-account/primary-phone` 端点更新或绑定新手机号。使用 `DELETE /api/my-account/primary-phone` 端点移除用户手机号。 +与更新邮箱类似，可以使用 `PATCH /api/my-account/primary-phone` 端点更新或绑定新手机号。使用 `DELETE /api/my-account/primary-phone` 端点移除用户手机号。 ### 绑定新的社交连接 \{#link-a-new-social-connection} @@ -286,7 +300,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ 响应中会有一个 `verificationRecordId`，请妥善保存以备后用。 -用户授权 (Authorization) 应用后，你将在 `redirectUri` 收到带有 `state` 参数的回调。然后可以使用 `POST /api/verifications/social/verify` 端点验证社交连接。 +用户授权 (Authorization) 应用后，你会在 `redirectUri` 收到带有 `state` 参数的回调。然后可以使用 `POST /api/verifications/social/verify` 端点验证社交连接。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -320,20 +334,20 @@ 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 -使用此方法前，你需要在账户中心设置中启用 `mfa` 字段。 +要使用此方法，你需要在账户中心设置中启用 `mfa` 字段。 ::: **第 0 步：将你的前端应用 origin 添加到相关 origin 列表。** -浏览器中的密钥 (Passkey) 绑定到特定主机名（RP ID），只有 RP ID 的 origin 才能注册或验证密钥。但你的前端应用发起请求的 origin 与 Logto 登录页不同，因此需要将前端应用 origin 添加到相关 origin 列表。这样你的前端应用就可以在其他 RP ID 下注册和验证密钥。 +浏览器中的密钥（Passkey）与特定主机名（RP ID）绑定，只有 RP ID 的 origin 才能注册或验证密钥。但你的前端应用请求 Account API 时的 origin 与 Logto 登录页不同，因此需要将前端应用 origin 添加到相关 origin 列表。这样你的前端应用就可以在其他 RP ID 下注册和验证密钥。 -默认情况下，Logto 会将 RP ID 设置为租户域名，例如你的租户域名为 `https://example.logto.app`，RP ID 就是 `example.logto.app`。如果你使用自定义域名，RP ID 就是自定义域名，例如 `https://auth.example.com`，RP ID 就是 `auth.example.com`。 +默认情况下，Logto 会将 RP ID 设置为租户域名，例如租户域名为 `https://example.logto.app`，RP ID 就是 `example.logto.app`。如果你使用自定义域名，RP ID 就是自定义域名，例如 `https://auth.example.com`，RP ID 就是 `auth.example.com`。 -现在，将你的前端应用 origin 添加到相关 origin，例如你的前端应用 origin 是 `https://account.example.com`： +现在，将你的前端应用 origin 添加到相关 origin，例如前端应用 origin 为 `https://account.example.com`： ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -342,7 +356,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}' ``` -关于相关 origin 的更多信息，请参见 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 文档。 +想了解更多相关 origin，请参考 [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) 文档。 **第 1 步：请求新的注册选项。** @@ -385,7 +399,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`：第 2 步本地浏览器返回的 response。 +- `payload`：第 2 步本地浏览器返回的响应。 - `verificationRecordId`：第 1 步服务器返回的验证记录 ID。 **第 4 步：最后，绑定密钥。** @@ -399,7 +413,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ``` - `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 -- `type`：MFA 因子的类型，目前仅支持 `WebAuthn`。 +- `type`：MFA 因子类型，目前仅支持 `WebAuthn`。 - `newIdentifierVerificationRecordId`：第 1 步服务器返回的验证记录 ID。 ### 管理已有 WebAuthn 密钥 \{#manage-existing-webauthn-passkey} @@ -427,7 +441,7 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ``` - `id`：验证因子的 ID。 -- `type`：验证因子的类型，WebAuthn 密钥为 `WebAuthn`。 +- `type`：验证因子类型，WebAuthn 密钥为 `WebAuthn`。 - `name`：密钥名称，可选字段。 - `agent`：密钥的 user agent。 @@ -448,3 +462,153 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{v -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### 绑定新的 TOTP \{#link-a-new-totp} + +:::note +记得先 [启用 MFA 和 TOTP](/end-user-flows/mfa)。 +::: + +:::note +要使用此方法，你需要在账户中心设置中启用 `mfa` 字段。 +::: + +**第 1 步：生成 TOTP 密钥。** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +响应体示例： + +```json +{ + "secret": "..." +} +``` + +**第 2 步：向用户展示 TOTP 密钥。** + +使用该密钥生成二维码或直接展示给用户。用户应将其添加到自己的身份验证器应用（如 Google Authenticator、Microsoft Authenticator 或 Authy）。 + +二维码的 URI 格式为： + +``` +otpauth://totp/[发行者 (Issuer)]:[账户]?secret=[密钥 (Secret)]&issuer=[发行者 (Issuer)] +``` + +示例： + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**第 3 步：绑定 TOTP 因子。** + +用户将密钥添加到身份验证器应用后，需要验证并绑定到账户： + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 +- `type`：必须为 `Totp`。 +- `secret`：第 1 步生成的 TOTP 密钥。 + +:::note +一个用户同一时间只能有一个 TOTP 因子。如果用户已存在 TOTP 因子，再添加会返回 422 错误。 +::: + +### 管理备份码 \{#manage-backup-codes} + +:::note +记得先 [启用 MFA 和备份码](/end-user-flows/mfa)。 +::: + +:::note +要使用此方法，你需要在账户中心设置中启用 `mfa` 字段。 +::: + +**第 1 步：生成新的备份码：** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +响应体示例： + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**第 2 步：向用户展示备份码：** + +:::important +在将备份码绑定到用户账户前，必须向用户展示这些备份码，并提示他们： + +- 立即下载或抄写这些备份码 +- 将其存放在安全的位置 +- 每个备份码只能使用一次 +- 这些备份码是他们丢失主 MFA 方法后最后的救命稻草 + +你应以清晰、易于复制的格式展示这些备份码，并考虑提供下载选项（如文本文件或 PDF）。 +::: + +**第 3 步：将备份码绑定到用户账户：** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`：有效的验证记录 ID，通过验证用户现有因子获得，详见 [获取验证记录 ID](#get-a-verification-record-id)。 +- `type`：必须为 `BackupCode`。 +- `codes`：上一步生成的备份码数组。 + +:::note + +- 一个用户同一时间只能有一组备份码。如果所有备份码都已用完，用户需要重新生成并绑定新备份码。 +- 备份码不能作为唯一的 MFA 因子。用户必须至少启用一个其他 MFA 因子（如 WebAuthn 或 TOTP）。 +- 每个备份码只能使用一次。 + +::: + +**查看已有备份码：** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +响应体示例： + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`：备份码。 +- `usedAt`：该备份码被使用的时间戳，未使用时为 `null`。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index 44ba4ef8f3e..0716c8b5bbd 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -6,9 +6,9 @@ sidebar_position: 2 # 租户设置 -新注册 Logto Cloud 的用户会自动加入一个免费的 **开发 (Development)**（Dev）环境租户。你可以在此租户中探索所有功能。 +新注册 Logto Cloud 的用户会自动加入一个免费的 **开发 (Development)**（Dev）环境租户。你可以在该租户中探索所有功能。 -如果你想为 **生产 (Production)**（Prod）环境或新项目创建一个独立的租户，请点击顶部栏左上角的当前租户名称。在此菜单中，你可以在租户之间切换或创建新租户。 +如果你想为 **生产 (Production)**（Prod）环境或新项目创建独立的租户，请点击顶部栏左上角的当前租户名称。在此菜单中，你可以在不同租户之间切换或创建新租户。 点击“创建租户”，然后： @@ -16,25 +16,25 @@ sidebar_position: 2 - 选择一个 [租户数据区域](#tenant-region) - 选择 [租户类型](#tenant-types-dev-vs-prod)（环境） -对于已有的租户，前往 控制台 > 租户设置 > 设置。在这里，你可以： +对于已有租户，前往 控制台 > 租户设置 > 设置。在这里，你可以： - 查看租户 ID - 更新租户名称 -- 查看 [租户区域](#tenant-region)。此项在创建后无法更改。 +- 查看 [租户区域](#tenant-region)。该项在创建后无法更改。 - 查看 [租户类型](#tenant-types-dev-vs-prod)。如有需要，你可以将 Dev 租户转换为 Prod 租户。 - [离开租户](#leave-tenant) - [删除租户](#delete-tenant) ## 租户区域 \{#tenant-region} -创建租户时，你可以选择租户数据存储的区域。租户创建后无法更改。可选区域如下： +创建租户时，你可以选择租户数据存储的区域。租户创建后无法更改。可用区域如下： - 欧洲（荷兰） - 美国西部（亚利桑那） - 澳大利亚（澳大利亚东部） - 日本（日本东部） -通常，你应选择离你的客户最近的区域，以最小化延迟并提升性能。 +通常，你应选择距离你的客户最近的区域，以最小化延迟并提升性能。 Logto 利用全球边缘网络，为你的应用提供最佳性能和可用性。请求路由经过优化，确保你的用户始终连接到表现最优的节点。 @@ -47,29 +47,34 @@ Logto 利用全球边缘网络，为你的应用提供最佳性能和可用性 ## 租户类型：开发 (Dev) 与生产 (Prod) \{#tenant-types-dev-vs-prod} -Logto Cloud 中有两种租户类型：开发 (Development) 和生产 (Production)。通过区分租户类型，你可以更高效地在不同环境下管理项目，同时充分享受 Logto 的全部价值。 +Logto Cloud 中有两种租户类型：开发 (Development, Dev) 和生产 (Production, Prod)。通过区分租户类型，你可以更高效地在不同环境下管理项目，同时充分享受 Logto 的全部价值。 你可以在创建时选择租户类型。当你准备上线生产环境时，有两种选择： -- **创建新的生产 (Production) 租户** - 新建一个全新的生产租户并从头配置。如果你希望开发环境和生产环境完全隔离，推荐此方式。 -- **将当前 Dev 租户转换为生产 (Production) 租户** - 如果你不想重新配置或迁移用户，可以通过订阅我们的 Pro 计划（起价 $16/月）将现有的开发租户升级为付费生产租户。 - - 你在开发租户中使用的所有付费功能都会在 Stripe 结账时自动带入。 - - **一旦转换，租户无法恢复为开发环境，请确认准备好后再操作。** +- **创建新的生产租户** + 新建一个全新的生产租户并从头配置。如果你希望开发和生产环境完全隔离，这是理想选择。 +- **将当前 Dev 租户转换为生产租户** + 如果你不想重新配置或迁移用户，可以将现有开发租户升级为付费生产租户。 + + - **升级为 Pro 计划**：前往 控制台 > 租户设置 > 设置，点击“转换”即可自助升级。你在 dev 租户中使用的所有付费功能会自动带入 Stripe 结账流程。 + - **升级为企业计划**： [联系我们](https://logto.io/contact)，我们会协助你完成升级。 + + :::note + 转换后，租户无法恢复为 Dev 环境；请确认准备就绪后再操作。 + ::: ### 开发 (Development) \{#development} -开发租户（Dev 租户）主要用于测试目的，不应在生产环境中使用。这些租户可以免费访问付费计划中的高级和付费功能，无需订阅。 +开发租户（dev 租户）主要用于测试目的，不应在生产环境中使用。这些租户可以免费访问付费计划中的高级功能，无需订阅。 -但开发租户有以下限制： +但开发租户有如下限制： - Dev 租户会自动删除 90 天以上的用户和组织。 -- 登录体验过程中会显示横幅，提示租户处于开发模式。 -- 开发租户的某些功能可能有配额限制。如有适用，具体限制会在功能详情页说明。 -- Logto 可能会更新开发租户的配额限制，我们会尽力提前通知你。 +- 登录体验中会显示横幅，提示租户处于开发模式。 +- 开发租户的部分功能可能有配额限制，具体限制会在功能详情页说明（如适用）。 +- Logto 可能会调整开发租户的配额限制，我们会尽量提前通知你。 -| 功能 | 实体限制 | +| 功能 | 实体上限 | | ----------------------------- | ---------- | | **包含令牌** | 每月 10 万 | | **应用程序** | @@ -84,10 +89,10 @@ Logto Cloud 中有两种租户类型：开发 (Development) 和生产 (Productio | **用户管理** | | | 用户角色 | 100 | | 机器对机器角色 | 100 | -| 每个角色的权限 | 100 | +| 每角色权限 | 100 | | **组织 (Organizations)** | | | 组织数量 | 5,000 | -| 每个组织的用户数 | 5,000 | +| 每组织用户数 | 5,000 | | 组织角色 | 100 | | 组织权限 | 100 | | **开发者与平台** | | @@ -97,25 +102,25 @@ Logto Cloud 中有两种租户类型：开发 (Development) 和生产 (Productio ### 生产 (Production) \{#production} -生产租户是终端用户访问线上应用的环境，你可能需要[付费订阅](https://logto.io/pricing)。你可以通过订阅免费计划或 Pro 计划来创建生产租户。如果你订阅免费计划，最多只能创建 10 个租户。 +生产租户是终端用户访问线上应用的环境，你可能需要 [付费订阅](https://logto.io/pricing)。你可以订阅免费计划或 Pro 计划来创建生产租户。如果你订阅免费计划，最多只能创建 10 个租户。 ## 启用 MFA \{#enable-mfa} 通过要求 Logto Pro/Enterprise 租户的所有成员启用多因素认证 (MFA)，提升你的工作区安全性。 -由于暂不支持自助开通，请[联系我们](https://logto.io/contact)以启用此功能。 +由于暂不支持自助开启，请 [联系我们](https://logto.io/contact) 启用此功能。 ## 启用企业单点登录 (SSO) \{#enable-enterprise-sso} -Logto Cloud 支持付费租户集成企业单点登录 (SSO)，包括 Google Workspace、Okta、Azure AD 等提供商。 +Logto Cloud 支持企业计划租户集成企业单点登录 (SSO)，包括 Google Workspace、Okta、Azure AD 等提供商。 -如需开始，请[联系我们](https://logto.io/contact)。我们会协助你快速完成配置。 +如需开始，请 [联系我们](https://logto.io/contact)。我们会协助你快速完成设置。 ## 离开租户 \{#leave-tenant} -管理员可以[邀请其他成员](/logto-cloud/tenant-member-management)加入此租户。 +管理员可以[邀请其他成员](/logto-cloud/tenant-member-management)加入该租户。 -如果还有至少一位其他 **管理员**（角色），或你是 **协作者**（角色），你可以选择离开租户。离开后，租户中的所有资源会保留，但你将无法再访问它们。 +如果至少还有一位其他 **管理员**（角色），或你是 **协作者**（角色），你可以选择离开租户。离开后，租户中的所有资源会保留，但你将无法再访问它们。 如果你是最后一位管理员，必须先将其他协作者设为管理员后才能离开。 @@ -123,7 +128,7 @@ Logto Cloud 支持付费租户集成企业单点登录 (SSO)，包括 Google Wor [管理员](/logto-cloud/tenant-member-management#invite-collaborators)可以删除 Logto 租户。删除租户会永久移除所有相关的用户数据和配置。此操作无法撤销。Logto 会要求你输入租户名称以确认，防止误删。 -如需帮助，请通过邮件[联系我们](https://logto.io/contact)。 +如需帮助，请通过邮件 [联系我们](https://logto.io/contact)。 ## 常见问题 \{#faqs} @@ -136,9 +141,9 @@ Logto Cloud 支持付费租户集成企业单点登录 (SSO)，包括 Google Wor 你目前可以自行将 **开发 (Development)** 租户转换为付费计划的 **生产 (Production)** 租户。[了解更多](#tenant-types-dev-vs-prod) -但 Logto Cloud 与 OSS 版本之间的自助迁移（包括所有配置和用户数据）暂不支持。如需此服务，请[联系 Logto 团队](https://logto.io/contact)讨论你的需求。 +但 Logto Cloud 与 OSS 版本之间的自助迁移（包括所有配置和用户数据）暂不支持。如需此服务，请 [联系 Logto 团队](https://logto.io/contact) 讨论你的方案。 -如果你计划停止在某项目中使用 Logto Cloud，Logto 可以协助你导出所有用户数据。请[联系我们](https://logto.io/contact)。 +如果你计划停止在某项目中使用 Logto Cloud，Logto 可以协助你导出所有用户数据。请 [联系我们](https://logto.io/contact)。
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 4a377183951..43204811f55 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,5 +1,5 @@ --- -description: 學習如何使用 Account API 管理使用者 +description: 瞭解如何使用 Account API 管理使用者 sidebar_position: 1 --- @@ -10,9 +10,9 @@ sidebar_position: 1 Logto Account API 是一組完整的 API，讓終端使用者可以直接透過 API 存取帳號，而無需經過 Management API。重點如下： - 直接存取：Account API 讓終端使用者能直接存取並管理自己的帳號資料，無需透過 Management API 中繼。 -- 使用者資料與身分管理：使用者可完整管理個人資料與安全設定，包括更新身分資訊（如電子郵件、手機、密碼）以及管理社交連結。MFA 與單一登入 (SSO) 支援即將推出。 +- 使用者資料與身分管理：使用者可完整管理個人資料與安全設定，包括更新身分資訊（如電子郵件、手機、密碼）及管理社交連結。MFA 與 SSO 支援即將推出。 - 全域存取控制：管理員可對存取設定進行全域控制，並自訂每個欄位。 -- 無縫授權 (Authorization)：授權 (Authorization) 變得前所未有地簡單！只需使用 `client.getAccessToken()` 取得 Logto 的不透明權杖 (Opaque token)，並以 `Bearer ` 附加於 Authorization 標頭即可。 +- 無縫授權 (Authorization)：授權 (Authorization) 變得前所未有地簡單！只需使用 `client.getAccessToken()` 取得 OP（Logto）用的不透明存取權杖 (Opaque token)，並以 `Bearer ` 附加於 Authorization 標頭即可。 :::note 為確保存取權杖 (Access token) 具備適當權限，請確認你已在 Logto 設定中正確配置對應的權限範圍 (Scopes)。 @@ -24,7 +24,7 @@ import { type LogtoConfig, UserScope } from '@logto/js'; const config: LogtoConfig = { // ...其他選項 - // 根據你的需求新增適當的權限範圍 (Scopes)。 + // 新增符合你需求的權限範圍 (Scopes)。 scopes: [ UserScope.Email, // 用於 `{POST,DELETE} /api/my-account/primary-email` API UserScope.Phone, // 用於 `{POST,DELETE} /api/my-account/primary-phone` API @@ -40,23 +40,25 @@ const config: LogtoConfig = { 透過 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)。 :::note -以下設定專屬的 Account API 即將推出：MFA、單一登入 (SSO)、自訂資料（使用者）、帳號刪除。在此之前，你可以使用 Logto Management API 實作這些功能。詳情請參閱 [透過 Management API 管理帳號設定](/end-user-flows/account-settings/by-management-api)。 +以下設定專屬的 Account API 即將推出：SSO、自訂資料（使用者）、帳號刪除。在此之前，你可以透過 Logto Management API 實作這些功能。詳情請見 [透過 Management API 管理帳號設定](/end-user-flows/account-settings/by-management-api)。 + +MFA 管理 API（TOTP 與備用碼）目前開發中，僅在 `isDevFeaturesEnabled` 設為 `true` 時可用。WebAuthn passkey 管理已全面開放。 ::: ## 如何啟用 Account API \{#how-to-enable-account-api} -預設情況下，Account API 是關閉的。若要啟用，需使用 [Management API](/integrate-logto/interact-with-management-api) 更新全域設定。 +預設情況下，Account API 為停用狀態。若要啟用，需透過 [Management API](/integrate-logto/interact-with-management-api) 更新全域設定。 API 端點 `/api/account-center` 可用於取得與更新帳號中心設定。你可以用它來啟用 / 停用 Account API 並自訂欄位。 @@ -69,19 +71,19 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"enabled":true,"fields":{"username":"Edit"}}' ``` -`enabled` 欄位用於啟用 / 停用 Account API，`fields` 欄位用於自訂欄位，值可為 `Off`、`Edit`、`ReadOnly`，預設為 `Off`。欄位列表如下： +`enabled` 欄位用於啟用或停用 Account API，`fields` 欄位用於自訂欄位，值可為 `Off`、`Edit`、`ReadOnly`，預設為 `Off`。欄位清單如下： - `name`：姓名欄位。 - `avatar`：頭像欄位。 -- `profile`：個人資料欄位，包含其子欄位。 +- `profile`：個人資料欄位（含子欄位）。 - `username`：使用者名稱欄位。 - `email`：電子郵件欄位。 - `phone`：手機欄位。 -- `password`：密碼欄位，查詢時若使用者已設密碼則回傳 `true`，否則為 `false`。 +- `password`：密碼欄位，查詢時若已設密碼則回傳 `true`，否則為 `false`。 - `social`：社交連結。 -- `mfa`：MFA 驗證因素。 +- `mfa`：MFA 因子。 -更多 API 細節請參閱 [Logto Management API Reference](https://openapi.logto.io/group/endpoint-account-center)。 +更多 API 詳情請見 [Logto Management API Reference](https://openapi.logto.io/group/endpoint-account-center)。 ## 如何存取 Account API \{#how-to-access-account-api} @@ -89,11 +91,11 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ 在應用程式中設置 SDK 後，可使用 `client.getAccessToken()` 方法取得存取權杖。此權杖為不透明權杖 (Opaque token)，可用於存取 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 互動時，請將存取權杖以 Bearer 格式（`Bearer YOUR_TOKEN`）放入 HTTP 標頭的 `Authorization` 欄位。 以下為取得使用者帳號資訊的範例： @@ -111,7 +113,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -回應內容如下： +回應內容範例如下： ```json { @@ -154,7 +156,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ 首先，你需要取得驗證紀錄 ID。此 ID 可用於在更新識別資訊時驗證使用者身分。 -取得驗證紀錄 ID 的方式：可驗證使用者密碼，或向使用者電子郵件 / 手機發送驗證碼。 +取得驗證紀錄 ID 的方式：驗證使用者密碼，或向使用者的電子郵件 / 手機發送驗證碼。 更多驗證相關內容，請參閱 [透過 Account API 進行安全驗證](/end-user-flows/security-verification)。 @@ -167,7 +169,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -回應內容如下： +回應內容範例如下： ```json { @@ -176,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/)或[設定簡訊連接器](/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 \ @@ -191,7 +193,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -回應內容如下： +回應內容範例如下： ```json { @@ -213,15 +215,27 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v ### 夾帶驗證紀錄 ID 發送請求 \{#send-request-with-verification-record-id} -更新使用者識別資訊時，需在請求標頭中以 `logto-verification-id` 欄位夾帶驗證紀錄 ID。 +在發送更新使用者識別資訊的請求時，需於請求標頭中以 `logto-verification-id` 欄位夾帶驗證紀錄 ID。 + +### 更新使用者密碼 \{#update-users-password} + +若要更新使用者密碼，可使用 `POST /api/my-account/password` 端點。 + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/password \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"password":"..."}' +``` ### 更新或綁定新電子郵件 \{#update-or-link-new-email} :::note -使用此方法前，需先[設定電子郵件連接器](/connectors/email-connectors/)，並確保已配置 `BindNewIdentifier` 範本。 +使用此方法前，需先 [設定電子郵件連接器](/connectors/email-connectors/)，並確保已配置 `BindNewIdentifier` 範本。 ::: -更新或綁定新電子郵件前，需先證明該電子郵件的所有權。 +要更新或綁定新電子郵件，需先驗證該電子郵件的擁有權。 呼叫 `POST /api/verifications/verification-code` 端點請求驗證碼。 @@ -232,7 +246,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 \ @@ -241,10 +255,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -驗證成功後，即可更新使用者電子郵件，將 `verificationId` 設為請求內容的 `newIdentifierVerificationRecordId`。 +驗證成功後，即可更新使用者電子郵件，於請求內容中將 `verificationId` 設為 `newIdentifierVerificationRecordId`。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ +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' \ @@ -253,7 +267,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ ### 移除使用者電子郵件 \{#remove-the-users-email} -移除使用者電子郵件可使用 `DELETE /api/my-account/primary-email` 端點。 +若要移除使用者電子郵件，可使用 `DELETE /api/my-account/primary-email` 端點。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -264,14 +278,14 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### 管理手機 \{#manage-phone} :::note -使用此方法前，需先[設定簡訊連接器](/connectors/sms-connectors/)，並確保已配置 `BindNewIdentifier` 範本。 +使用此方法前，需先 [設定 SMS 連接器](/connectors/sms-connectors/)，並確保已配置 `BindNewIdentifier` 範本。 ::: 與更新電子郵件類似，可使用 `PATCH /api/my-account/primary-phone` 端點更新或綁定新手機，並用 `DELETE /api/my-account/primary-phone` 端點移除使用者手機。 ### 綁定新社交連結 \{#link-a-new-social-connection} -綁定新社交連結前，需先請求授權網址： +要綁定新社交連結，需先請求授權網址： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -280,13 +294,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`：使用者授權應用程式後的導向網址，你需在此網址架設網頁並接收回呼。 +- `state`：授權後回傳的狀態，用於防止 CSRF 攻擊的隨機字串。 回應中會有 `verificationRecordId`，請妥善保存。 -使用者授權後，你會在 `redirectUri` 收到帶有 `state` 參數的回呼。接著可用 `POST /api/verifications/social/verify` 端點驗證社交連結。 +使用者授權應用程式後，你會在 `redirectUri` 收到帶有 `state` 參數的回呼。接著可用 `POST /api/verifications/social/verify` 端點驗證社交連結。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -295,7 +309,7 @@ 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` 端點綁定社交連結。 @@ -309,7 +323,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ ### 移除社交連結 \{#remove-a-social-connection} -移除社交連結可使用 `DELETE /api/my-account/identities` 端點。 +若要移除社交連結，可使用 `DELETE /api/my-account/identities` 端點。 ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \ @@ -317,10 +331,10 @@ 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 passkey \{#link-a-new-webauthn-passkey} :::note -請先[啟用 MFA 與 WebAuthn](/end-user-flows/mfa)。 +請先 [啟用 MFA 與 WebAuthn](/end-user-flows/mfa)。 ::: :::note @@ -329,11 +343,11 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connecto **步驟 0：將你的前端應用程式來源加入相關來源清單。** -瀏覽器中的 Passkey 綁定於特定主機名稱（RP ID），僅 RP ID 的來源可註冊或驗證 Passkey。然而，你的前端應用程式與 Logto 登入頁面不同，因此需將前端應用程式來源加入相關來源清單，才能在其他 RP ID 下註冊 / 驗證 Passkey。 +瀏覽器中的 passkey 綁定於特定主機名稱（RP ID），僅該 RP ID 的來源可註冊或驗證 passkey。但你的前端應用程式與 Logto 登入頁面來源不同，因此需將前端應用程式來源加入相關來源清單，才能在其他 RP ID 下註冊 / 驗證 passkey。 -預設 Logto 會將 RP ID 設為租戶網域，例如 `https://example.logto.app` 則 RP ID 為 `example.logto.app`。若使用自訂網域，RP ID 則為自訂網域，如 `https://auth.example.com` 則 RP ID 為 `auth.example.com`。 +預設情況下，Logto 會將 RP ID 設為租戶網域，例如 `https://example.logto.app` 則 RP ID 為 `example.logto.app`。若使用自訂網域，RP ID 則為自訂網域，如 `https://auth.example.com` 則 RP ID 為 `auth.example.com`。 -現在，假設你的前端應用程式來源為 `https://account.example.com`，可這樣加入： +現在，假設你的前端應用程式來源為 `https://account.example.com`，請將其加入相關來源： ```bash curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \ @@ -362,9 +376,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat } ``` -**步驟 2：於本地瀏覽器註冊 Passkey。** +**步驟 2：於本地瀏覽器註冊 passkey。** -以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 為例，可用 `startRegistration` 函式於本地瀏覽器註冊 Passkey。 +以 [`@simplewebauthn/browser`](https://simplewebauthn.dev/) 為例，可用 `startRegistration` 函式於本地瀏覽器註冊 passkey。 ```ts import { startRegistration } from '@simplewebauthn/browser'; @@ -373,10 +387,10 @@ import { startRegistration } from '@simplewebauthn/browser'; const response = await startRegistration({ optionsJSON: registrationOptions, // 步驟 1 伺服器回傳資料 }); -// 保存 response 以供後續使用 +// 儲存 response 以供後續使用 ``` -**步驟 3：驗證 Passkey。** +**步驟 3：驗證 passkey。** ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \ @@ -385,10 +399,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat --data-raw '{"payload":"...","verificationRecordId":"..."}' ``` -- `payload`：步驟 2 本地瀏覽器回傳的 response。 +- `payload`：步驟 2 本地瀏覽器回傳的資料。 - `verificationRecordId`：步驟 1 伺服器回傳的驗證紀錄 ID。 -**步驟 4：最後，綁定 Passkey。** +**步驟 4：最後，綁定 passkey。** ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ @@ -398,20 +412,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`。 +- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因子，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 +- `type`：MFA 因子類型，目前僅支援 `WebAuthn`。 - `newIdentifierVerificationRecordId`：步驟 1 伺服器回傳的驗證紀錄 ID。 -### 管理現有 WebAuthn Passkey \{#manage-existing-webauthn-passkey} +### 管理現有 WebAuthn passkey \{#manage-existing-webauthn-passkey} -管理現有 WebAuthn Passkey，可用 `GET /api/my-account/mfa-verifications` 端點取得目前 Passkey 與其他 MFA 驗證因素。 +管理現有 WebAuthn passkey，可用 `GET /api/my-account/mfa-verifications` 端點取得目前 passkey 與其他 MFA 驗證因子。 ```bash curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ -H 'authorization: Bearer ' ``` -回應內容如下： +回應內容範例如下： ```json [ @@ -426,12 +440,12 @@ curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \ ] ``` -- `id`：驗證因素 ID。 -- `type`：驗證因素類型，WebAuthn Passkey 為 `WebAuthn`。 -- `name`：Passkey 名稱，為選填欄位。 -- `agent`：Passkey 的使用者代理資訊。 +- `id`：驗證因子 ID。 +- `type`：驗證因子類型，WebAuthn passkey 為 `WebAuthn`。 +- `name`：passkey 名稱，選填。 +- `agent`：passkey 的 user agent。 -更新 Passkey 名稱： +更新 passkey 名稱： ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \ @@ -441,10 +455,160 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve --data-raw '{"name":"..."}' ``` -刪除 Passkey： +刪除 passkey： ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \ -H 'authorization: Bearer ' \ -H 'logto-verification-id: ' ``` + +### 綁定新 TOTP \{#link-a-new-totp} + +:::note +請先 [啟用 MFA 與 TOTP](/end-user-flows/mfa)。 +::: + +:::note +使用此方法前，需在帳號中心設定中啟用 `mfa` 欄位。 +::: + +**步驟 1：產生 TOTP 密鑰。** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +回應內容範例如下： + +```json +{ + "secret": "..." +} +``` + +**步驟 2：將 TOTP 密鑰顯示給使用者。** + +使用密鑰產生 QR code 或直接顯示給使用者。使用者應將其加入驗證器 App（如 Google Authenticator、Microsoft Authenticator 或 Authy）。 + +QR code 的 URI 格式如下： + +``` +otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer] +``` + +範例： + +``` +otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp +``` + +**步驟 3：綁定 TOTP 因子。** + +使用者將密鑰加入驗證器 App 後，需驗證並綁定至帳號： + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"Totp","secret":"..."}' +``` + +- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因子，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 +- `type`：必須為 `Totp`。 +- `secret`：步驟 1 產生的 TOTP 密鑰。 + +:::note +每位使用者僅能綁定一組 TOTP 因子。若已存在 TOTP 因子，嘗試新增會回傳 422 錯誤。 +::: + +### 管理備用碼 \{#manage-backup-codes} + +:::note +請先 [啟用 MFA 與備用碼](/end-user-flows/mfa)。 +::: + +:::note +使用此方法前，需在帳號中心設定中啟用 `mfa` 欄位。 +::: + +**步驟 1：產生新備用碼：** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \ + -H 'authorization: Bearer ' \ + -H 'content-type: application/json' +``` + +回應內容範例如下： + +```json +{ + "codes": ["...", "...", "..."] +} +``` + +**步驟 2：將備用碼顯示給使用者：** + +:::important +在將備用碼綁定至使用者帳號前，必須顯示給使用者並提醒： + +- 立即下載或抄寫這些備用碼 +- 妥善保存於安全處 +- 每組備用碼僅能使用一次 +- 若失去主要 MFA 方法，這些備用碼是最後救援手段 + +請以清楚、易於複製的格式顯示備用碼，並考慮提供下載選項（如文字檔或 PDF）。 +::: + +**步驟 3：將備用碼綁定至使用者帳號：** + +```bash +curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \ + -H 'authorization: Bearer ' \ + -H 'logto-verification-id: ' \ + -H 'content-type: application/json' \ + --data-raw '{"type":"BackupCode","codes":["...","...","..."]}' +``` + +- `verification_record_id`：有效的驗證紀錄 ID，需先驗證使用者現有因子，詳見 [取得驗證紀錄 ID](#get-a-verification-record-id)。 +- `type`：必須為 `BackupCode`。 +- `codes`：前一步產生的備用碼陣列。 + +:::note + +- 每位使用者僅能有一組備用碼。若全部用完，需重新產生並綁定新備用碼。 +- 備用碼不能是唯一的 MFA 因子。使用者必須至少啟用一種其他 MFA 因子（如 WebAuthn 或 TOTP）。 +- 每組備用碼僅能使用一次。 + +::: + +**查看現有備用碼：** + +```bash +curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \ + -H 'authorization: Bearer ' +``` + +回應內容範例如下： + +```json +{ + "codes": [ + { + "code": "...", + "usedAt": null + }, + { + "code": "...", + "usedAt": "2024-01-15T10:30:00.000Z" + } + ] +} +``` + +- `code`：備用碼。 +- `usedAt`：該備用碼使用時間，若尚未使用則為 `null`。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx index 9b82f3ff874..903b266ec89 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/logto-cloud/tenant-settings.mdx @@ -1,33 +1,33 @@ --- id: tenant-settings -title: 租戶設定 +title: 租戶設定 (Tenant settings) sidebar_position: 2 --- -# 租戶設定 +# 租戶設定 (Tenant settings) -新註冊 Logto Cloud 的使用者會自動加入一個免費的 **開發 (Development, Dev)** 環境租戶。你可以在這個租戶中探索所有功能。 +新註冊 Logto Cloud 的使用者會自動加入一個免費的 **開發 (Development, Dev)** 環境租戶。你可以在此租戶中探索所有功能。 -如果你想為 **生產 (Production, Prod)** 環境或新專案建立獨立租戶，請點擊頂部列左上角的當前租戶名稱。在這個選單中，你可以切換租戶或建立新租戶。 +如果你想為 **生產 (Production, Prod)** 環境或新專案建立獨立租戶，請點擊頂部欄左上角的當前租戶名稱。在此選單中，你可以切換租戶或建立新租戶。 -點擊「建立租戶」，然後： +點擊「建立租戶 (Create tenant)」，然後： - 為租戶命名 -- 選擇 [租戶資料區域](#tenant-region) -- 選擇 [租戶類型](#tenant-types-dev-vs-prod)（環境） +- 選擇 [租戶資料區域 (tenant data region)](#tenant-region) +- 選擇 [租戶類型 (tenant type)](#tenant-types-dev-vs-prod)（環境） 對於現有租戶，請前往 主控台 > 租戶設定 > 設定。在這裡，你可以： - 查看租戶 ID - 更新租戶名稱 -- 查看 [租戶區域](#tenant-region)。此項目建立後無法更改。 -- 查看 [租戶類型](#tenant-types-dev-vs-prod)。如有需要，你可以將 Dev 租戶轉換為 Prod 租戶。 +- 查看 [租戶區域 (tenant region)](#tenant-region)。此項目建立後無法變更。 +- 查看 [租戶類型 (tenant type)](#tenant-types-dev-vs-prod)。如有需要，你可以將 Dev 租戶轉換為 Prod 租戶。 - [離開租戶](#leave-tenant) - [刪除租戶](#delete-tenant) -## 租戶區域 \{#tenant-region} +## 租戶區域 (Tenant region) \{#tenant-region} -建立租戶時，你可以選擇租戶資料儲存的區域。租戶建立後無法更改。可用區域如下： +建立租戶時，你可以選擇租戶資料儲存的區域。租戶建立後無法變更。可用區域如下： - 歐洲（荷蘭） - 美國西部（亞利桑那） @@ -39,35 +39,40 @@ sidebar_position: 2 Logto 利用全球邊緣網路，為你的應用程式提供最佳效能與可用性。請求路由經過最佳化，確保你的使用者始終連接到效能最佳的節點。 :::note -需要其他區域嗎？[聯絡我們](https://logto.io/contact)： +需要其他區域嗎？[聯絡我們](https://logto.io/contact)以： - 申請新的公有雲區域 - 詢問在你偏好的地點部署 Logto 私有雲 (Private Cloud) ::: -## 租戶類型：開發 vs. 生產 \{#tenant-types-dev-vs-prod} +## 租戶類型：開發 (Dev) vs. 生產 (Prod) \{#tenant-types-dev-vs-prod} -Logto Cloud 有兩種租戶類型：開發（Development）與生產（Production）。透過區分租戶類型，你可以更有效率地管理不同環境的專案，同時充分享受 Logto 的完整價值。 +Logto Cloud 有兩種租戶類型：開發 (Development, Dev) 與生產 (Production, Prod)。透過區分租戶類型，你可以更有效率地管理不同環境下的專案，同時充分享受 Logto 的完整價值。 -你可以在建立時選擇租戶類型。當你準備好進入生產環境時，有兩種選擇： +你可以在建立時選擇租戶類型。當你準備好正式上線時，有兩種選擇： -- **建立新的生產租戶** - 從零開始設置全新的生產租戶。適合希望將開發與生產環境完全分離的情境。 -- **將現有 Dev 租戶轉換為生產租戶** - 如果你不想重新設定或遷移使用者，可以透過訂閱 Pro 方案（每月 $16 起）將現有的 dev 租戶升級為付費生產租戶。 - - 你在 dev 租戶中使用過的所有付費功能都會帶入 Stripe 結帳流程。 - - **轉換後，租戶無法再還原為 dev 環境，請確認準備好再進行操作。** +- **建立新的生產租戶 (Production tenant)** + 建立全新的生產租戶並從頭設定。適合希望將開發與生產環境分離的情境。 +- **將現有 Dev 租戶轉換為生產租戶 (Production)** + 若你不想重新設定或遷移使用者，可以將現有開發租戶升級為付費生產租戶。 + + - **轉換為 Pro 方案**：前往 主控台 > 租戶設定 > 設定，點擊「轉換 (Convert)」即可自助升級。你在 dev 租戶中已使用的付費功能將自動帶入 Stripe 結帳頁。 + - **轉換為企業方案 (Enterprise plan)**：[聯絡我們](https://logto.io/contact)，我們將協助你完成升級。 + + :::note + 一旦轉換，租戶無法再回復為 Dev 環境；請確認準備好再進行操作。 + ::: ### 開發 (Development) \{#development} -開發租戶（dev tenant）主要用於測試，不應用於生產環境。這些租戶可免費存取付費方案中的進階功能，且無需訂閱。 +開發租戶（dev tenant）主要用於測試，**不應用於生產環境**。這些租戶可免費存取付費方案中的進階功能，且無需訂閱。 但開發租戶有以下限制： - Dev 租戶會自動刪除 90 天以上的使用者與組織。 - 登入體驗時會顯示橫幅，提示租戶處於開發模式。 - 開發租戶的部分功能可能有配額限制，詳情請參閱功能說明頁。 -- Logto 可能會調整開發租戶的配額限制，並盡力提前通知你。 +- Logto 可能會調整開發租戶的配額限制，並會盡力提前通知你。 | 功能 | 實體上限 | | ------------------------------------------ | ---------- | @@ -82,46 +87,46 @@ Logto Cloud 有兩種租戶類型：開發（Development）與生產（Productio | 社交連接器 (Social connector) | 100 | | 企業級單一登入 (Enterprise SSO) | 100 | | **使用者管理 (User management)** | | -| 使用者角色 (User roles) | 100 | -| 機器對機器角色 (Machine-to-machine roles) | 100 | -| 每個角色的權限 (Permission per role) | 100 | +| 使用者角色 | 100 | +| 機器對機器角色 | 100 | +| 每個角色的權限 | 100 | | **組織 (Organizations)** | | -| 組織數量 (Organization count) | 5,000 | -| 每個組織的使用者 (Users per organization) | 5,000 | -| 組織角色 (Organization roles) | 100 | -| 組織權限 (Organization permissions) | 100 | +| 組織數量 | 5,000 | +| 每個組織的使用者 | 5,000 | +| 組織角色 | 100 | +| 組織權限 | 100 | | **開發者與平台 (Developers and platform)** | | -| Webhook 數量 (Webhooks) | 10 | -| 稽核日誌保留 (Audit log retention) | 14 天 | -| 租戶成員 (Tenant members) | 20 | +| Webhook | 10 | +| 稽核日誌保留 | 14 天 | +| 租戶成員 | 20 | ### 生產 (Production) \{#production} -生產租戶是終端使用者存取正式應用程式的地方，你可能需要[付費訂閱](https://logto.io/pricing)。你可以訂閱 Free 方案或 Pro 方案來建立生產租戶。若訂閱 Free 方案，最多只能建立 10 個租戶。 +生產租戶是終端使用者存取正式應用程式的環境，你可能需要[付費訂閱](https://logto.io/pricing)。你可以訂閱 Free 方案或 Pro 方案來建立生產租戶。若訂閱 Free 方案，最多只能建立 10 個租戶。 -## 啟用 MFA \{#enable-mfa} +## 啟用多重要素驗證 (MFA) \{#enable-mfa} -透過要求所有 Logto Pro / Enterprise 租戶成員啟用多重要素驗證 (MFA, Multi-Factor Authentication)，提升你的工作區安全性。 +透過要求 Logto Pro／Enterprise 租戶的所有成員啟用多重要素驗證 (MFA, Multi-Factor Authentication)，提升你的工作區安全性。 -目前尚未開放自助啟用，請[聯絡我們](https://logto.io/contact)以啟用此功能。 +目前尚未開放自助設定，請[聯絡我們](https://logto.io/contact)以啟用此功能。 ## 啟用企業級單一登入 (Enterprise SSO) \{#enable-enterprise-sso} -Logto Cloud 支援付費租戶整合企業級單一登入 (Enterprise SSO)，包含 Google Workspace、Okta、Azure AD 等供應商。 +Logto Cloud 支援企業方案租戶整合企業級單一登入 (Enterprise SSO)，包含 Google Workspace、Okta、Azure AD 等供應商。 -如需開始設定，請[聯絡我們](https://logto.io/contact)。我們會協助你快速完成設置。 +如需開始設定，請[聯絡我們](https://logto.io/contact)，我們將協助你快速完成。 ## 離開租戶 \{#leave-tenant} 管理員可以[邀請其他成員](/logto-cloud/tenant-member-management)加入此租戶。 -如果還有其他 **管理員 (admin)**（角色），或你是 **協作者 (collaborator)**（角色），你可以選擇離開租戶。離開後，租戶內所有資源仍會保留，但你將無法再存取。 +若至少還有一位 **管理員 (admin)**，或你是 **協作者 (collaborator)**，你可以選擇離開租戶。離開後，租戶內所有資源仍會保留，但你將無法再存取。 如果你是最後一位管理員，必須先將其他協作者指派為管理員後才能離開。 ## 刪除租戶 \{#delete-tenant} -[管理員](/logto-cloud/tenant-member-management#invite-collaborators)可以刪除 Logto 租戶。刪除租戶會永久移除所有相關的使用者資料與設定。此操作**無法復原**。Logto 會要求你輸入租戶名稱以確認，避免誤刪。 +[管理員](/logto-cloud/tenant-member-management#invite-collaborators)可以刪除 Logto 租戶。刪除租戶會永久移除所有相關的使用者資料與設定，**此操作無法復原**。Logto 會要求你輸入租戶名稱以確認，避免誤刪。 如需協助，請透過電子郵件[聯絡我們](https://logto.io/contact)。 @@ -136,7 +141,7 @@ Logto Cloud 支援付費租戶整合企業級單一登入 (Enterprise SSO)，包 你目前可以自行將 **開發 (Development)** 租戶轉換為付費方案的 **生產 (Production)** 租戶。[了解詳情](#tenant-types-dev-vs-prod) -但 Logto Cloud 與 OSS 版本間的自助遷移（所有設定與使用者資料）尚未支援。如需此服務，請[聯絡 Logto 團隊](https://logto.io/contact)討論你的需求。 +但 Logto Cloud 與 OSS 版本間（包含所有設定與使用者資料）的自助遷移尚未支援。如需此服務，請[聯絡 Logto 團隊](https://logto.io/contact)討論你的選項。 如果你計畫停止在某專案中使用 Logto Cloud，Logto 可協助你匯出所有使用者資料。請[聯絡我們](https://logto.io/contact)。 @@ -145,5 +150,5 @@ Logto Cloud 支援付費租戶整合企業級單一登入 (Enterprise SSO)，包 ## 相關資源 \{#related-resources} - 在在地區域與專屬運算資源中保護你的身分 (Identities) + 在在地區域與專屬運算資源中保護你的身分 (identities)