diff --git a/docs/end-user-flows/organization-experience/invite-organization-members.mdx b/docs/end-user-flows/organization-experience/invite-organization-members.mdx index 84226ecadec..ff2eaaaf02b 100644 --- a/docs/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/docs/end-user-flows/organization-experience/invite-organization-members.mdx @@ -80,7 +80,7 @@ If you haven't set up the Logto Management API yet, check out [Interact with Man ::: -### For Cloud and OSS v1.27.0+ users +### For Cloud and OSS v1.27.0+ users \{#for-cloud-and-oss-v1-27-0-users} We can now use the [Magic link (One-time token)](/end-user-flows/one-time-token) feature to handle the invitation flow. @@ -92,7 +92,7 @@ This is the recommended approach, as it will automatically register the invitee Check out the [Magic link (One-time token)](/end-user-flows/one-time-token) page for more details. -### For OSS v1.26.0- users +### For OSS v1.26.0- users \{#for-oss-v1-26-0--users} We've provided a set of invitation-related Management APIs in the organizations feature. With these APIs, you can: 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 0d33bf7c767..775dc442af3 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,5 +1,5 @@ --- -description: Erfahre, wie du die Account API zur Verwaltung von Benutzern nutzt +description: Erfahre, wie du die Account API zur Verwaltung von Benutzern verwendest (Learn how to use the Account API to manage user) sidebar_position: 2 --- @@ -7,33 +7,33 @@ sidebar_position: 2 ## Was ist die Logto Account API \{#what-is-logto-account-api} -Die Logto Account API ist eine umfassende Sammlung von APIs, die den Endbenutzern direkten API-Zugriff ermöglicht, ohne die Management API durchlaufen zu müssen. Hier sind die Highlights: +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 sind die wichtigsten Punkte: -- Direkter Zugriff: Die Account API ermöglicht es Endbenutzern, direkt auf ihr eigenes Konto zuzugreifen und es zu verwalten, ohne die Weiterleitung der 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. MFA und SSO-Unterstützung kommen bald. -- Globale Zugangskontrolle: Der Administrator hat volle, globale Kontrolle über die Zugangseinstellungen und kann jedes Feld anpassen. -- Nahtlose Autorisierung: Die Autorisierung ist einfacher denn je! Verwende einfach `client.getAccessToken()`, um ein opakes Zugangstoken für OP (Logto) zu erhalten, und füge es dem Authorization-Header als `Bearer ` hinzu. +- 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. +- Globale Zugriffskontrolle: Der Administrator hat vollständige, globale Kontrolle über die Zugriffseinstellungen und kann jedes Feld individuell anpassen. +- Nahtlose Autorisierung (Authorization): Die Autorisierung ist so einfach wie nie! 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. -Mit der Logto Account API kannst du ein benutzerdefiniertes Kontoverwaltungssystem wie eine Profilseite erstellen, die vollständig in Logto integriert ist. +Mit der Logto Account API kannst du ein individuelles Kontoverwaltungssystem wie eine Profilseite erstellen, das vollständig in Logto integriert ist. -Einige häufige Verwendungen sind unten aufgeführt: +Einige häufige Anwendungsfälle sind: - Benutzerprofil abrufen - Benutzerprofil aktualisieren - Benutzerpasswort aktualisieren -- Benutzeridentitäten einschließlich E-Mail, Telefon und sozialer Verbindungen aktualisieren +- Benutzeridentitäten einschließlich E-Mail, Telefon und sozialen Verbindungen aktualisieren -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). +Weitere Informationen zu den verfügbaren APIs findest du in der [Logto Account API Referenz](https://openapi.logto.io/group/endpoint-my-account) und der [Logto Verification API Referenz](https://openapi.logto.io/group/endpoint-verifications). :::note -Spezielle Account APIs für die folgenden Einstellungen kommen bald: MFA, SSO, Benutzerdefinierte Daten (Benutzer) und Kontolöschung. In der Zwischenzeit kannst du diese Funktionen mit den Logto Management APIs implementieren. Siehe [Kontoeinstellungen über die Management API](/end-user-flows/account-settings/by-management-api) für weitere Details. +Spezielle Account APIs für die folgenden Einstellungen sind in Kürze verfügbar: MFA, 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. ::: -## Wie man die Account API aktiviert \{#how-to-enable-account-api} +## 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: @@ -44,48 +44,48 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"enabled":true,"fields":{"username":"Edit"}}' ``` -Das `enabled`-Feld wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das `fields`-Feld wird verwendet, um die Felder anzupassen. Der Wert kann `Off`, `Edit`, `ReadOnly` sein. Der Standardwert ist `Off`. Die Liste der Felder: +Das Feld `enabled` wird verwendet, um die Account API zu aktivieren oder zu deaktivieren, und das Feld `fields` dient zur Anpassung der Felder. Der Wert kann `Off`, `Edit`, `ReadOnly` sein. Der Standardwert ist `Off`. Die Liste der Felder: - `name`: Das Namensfeld. - `avatar`: Das Avatar-Feld. - `profile`: Das Profilfeld, einschließlich seiner Unterfelder. -- `username`: Das Benutzernamenfeld. +- `username`: Das Benutzername-Feld. - `email`: Das E-Mail-Feld. - `phone`: Das Telefonfeld. -- `password`: Das Passwortfeld, beim Abrufen wird `true` zurückgegeben, wenn der Benutzer ein Passwort gesetzt hat, andernfalls `false`. +- `password`: Das Passwortfeld; beim Abrufen wird `true` zurückgegeben, wenn der Benutzer ein Passwort gesetzt hat, andernfalls `false`. - `social`: Soziale Verbindungen. -Erfahre mehr über die API-Details in der [Logto Management API Referenz](https://openapi.logto.io/group/endpoint-account-center). +Weitere Details zur API findest du in der [Logto Management API Referenz](https://openapi.logto.io/group/endpoint-account-center). -## Wie man auf die Account API zugreift \{#how-to-access-account-api} +## Wie greife ich auf die Account API zu \{#how-to-access-account-api} -### Ein Zugangstoken abrufen \{#fetch-an-access-token} +### Zugangstoken abrufen \{#fetch-an-access-token} -Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode `client.getAccessToken()` verwenden, um ein Zugangstoken abzurufen. Dieses Token ist ein opakes Token, das zum Zugriff auf die Account API verwendet werden kann. +Nachdem du das SDK in deiner Anwendung eingerichtet hast, kannst du die Methode `client.getAccessToken()` verwenden, um ein Zugangstoken abzurufen. Dieses Token ist ein opaker Token (Opaque token), das für den Zugriff auf die Account API verwendet werden kann. -Wenn du das offizielle SDK nicht verwendest, solltest du das `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 Zugangstoken-Anfrage an `/oidc/token` leer lassen. ### Zugriff auf die Account API mit Zugangstoken \{#access-account-api-using-access-token} -Du solltest das Zugangstoken im `Authorization`-Feld der HTTP-Header mit dem Bearer-Format (`Bearer YOUR_TOKEN`) platzieren, wenn du mit der Account API interagierst. +Du solltest das Zugangstoken im `Authorization`-Feld der HTTP-Header im Bearer-Format (`Bearer YOUR_TOKEN`) angeben, wenn du mit der Account API interagierst. -Ein Beispiel, um die Benutzerkontoinformationen abzurufen: +Ein Beispiel, um die Benutzerkonto-Informationen abzurufen: ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## Verwaltung grundlegender Kontoinformationen \{#manage-basic-account-information} +## Grundlegende Kontoinformationen verwalten \{#manage-basic-account-information} -### Benutzerkontoinformationen abrufen \{#retrieve-user-account-information} +### Benutzerkonto-Informationen abrufen \{#retrieve-user-account-information} ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -Der Antwortkörper könnte so aussehen: +Die Antwort sieht beispielsweise so aus: ```json { @@ -96,13 +96,13 @@ Der Antwortkörper könnte so aussehen: } ``` -Die Antwortfelder können je nach den Einstellungen des Account Centers variieren. +Die Antwortfelder können je nach Account Center-Einstellungen variieren. ### Grundlegende Kontoinformationen aktualisieren \{#update-basic-account-information} -Grundlegende Kontoinformationen umfassen den Benutzernamen, den Namen, das Avatar und das Profil. +Zu den grundlegenden Kontoinformationen gehören Benutzername, Name, Avatar und Profil. -Um Benutzernamen, Namen und Avatar zu aktualisieren, kannst du den Endpunkt `PATCH /api/my-account` verwenden. +Um Benutzername, Name und Avatar zu aktualisieren, kannst du den Endpunkt `PATCH /api/my-account` verwenden. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -120,17 +120,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## Verwaltung von Identifikatoren und anderen sensiblen Informationen \{#manage-identifiers-and-other-sensitive-information} +## Identifikatoren und andere sensible Informationen verwalten \{#manage-identifiers-and-other-sensitive-information} -Aus Sicherheitsgründen erfordert die Account API eine weitere Autorisierungsebene für die Vorgänge, die Identifikatoren und andere sensible Informationen betreffen. +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 erhalten \{#get-a-verification-record-id} +### Eine Verifizierungsdatensatz-ID abrufen \{#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 überprüfen. 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. -#### Das Passwort des Benutzers überprüfen \{#verify-the-users-password} +#### Passwort des Benutzers überprüfen \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -Der Antwortkörper könnte so aussehen: +Die Antwort sieht beispielsweise so aus: ```json { @@ -151,10 +151,10 @@ Der Antwortkörper könnte so aussehen: #### Ü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} :::note -Um diese Methode zu verwenden, musst du den [E-Mail-Connector](/connectors/email-connectors/) oder den [SMS-Connector](/connectors/sms-connectors/) konfigurieren und sicherstellen, dass die `UserPermissionValidation`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/) oder den [SMS-Connector konfigurieren](/connectors/sms-connectors/) und sicherstellen, dass die `UserPermissionValidation`-Vorlage konfiguriert ist. ::: -Nehmen wir E-Mail als Beispiel, fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID: +Am Beispiel E-Mail: Fordere einen neuen Verifizierungscode an und erhalte die Verifizierungsdatensatz-ID: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Der Antwortkörper könnte so aussehen: +Die Antwort sieht beispielsweise so aus: ```json { @@ -175,7 +175,7 @@ Der Antwortkörper könnte so aussehen: Nach Erhalt des Verifizierungscodes kannst du ihn verwenden, um den Verifizierungsstatus des Verifizierungsdatensatzes zu aktualisieren. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' @@ -185,15 +185,15 @@ Nach der Überprüfung des Codes kannst du nun die Verifizierungsdatensatz-ID ve ### Anfrage mit Verifizierungsdatensatz-ID senden \{#send-request-with-verification-record-id} -Beim Senden einer Anfrage zur Aktualisierung des Identifikators des Benutzers musst du die Verifizierungsdatensatz-ID dem Anforderungsheader mit dem `logto-verification-id`-Feld anhängen. +Wenn du eine Anfrage zum Aktualisieren des Benutzeridentifikators sendest, musst du die Verifizierungsdatensatz-ID im Request-Header mit dem Feld `logto-verification-id` anhängen. ### Neue E-Mail aktualisieren oder verknüpfen \{#update-or-link-new-email} :::note -Um diese Methode zu verwenden, musst du den [E-Mail-Connector](/connectors/email-connectors/) konfigurieren und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [E-Mail-Connector konfigurieren](/connectors/email-connectors/) und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. ::: -Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, solltest du zuerst das Eigentum der E-Mail nachweisen. +Um eine neue E-Mail zu aktualisieren oder zu verknüpfen, solltest du zuerst den Besitz der E-Mail nachweisen. Rufe den Endpunkt `POST /api/verifications/verification-code` auf, um einen Verifizierungscode anzufordern. @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Du wirst eine `verificationId` in der Antwort finden und einen Verifizierungscode in der E-Mail erhalten, verwende ihn, um die E-Mail zu verifizieren. +Du findest eine `verificationId` in der Antwort und erhältst einen Verifizierungscode per E-Mail. Verwende diesen, um die E-Mail zu verifizieren. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Nach der Überprüfung des Codes kannst du nun die E-Mail des Benutzers aktualisieren, setze die `verificationId` in den Anforderungskörper 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 \ @@ -223,7 +223,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}' ``` -### Die E-Mail des Benutzers entfernen \{#remove-the-users-email} +### E-Mail des Benutzers entfernen \{#remove-the-users-email} Um die E-Mail des Benutzers zu entfernen, kannst du den Endpunkt `DELETE /api/my-account/primary-email` verwenden. @@ -236,14 +236,14 @@ 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](/connectors/sms-connectors/) konfigurieren und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. +Um diese Methode zu verwenden, musst du den [SMS-Connector konfigurieren](/connectors/sms-connectors/) und sicherstellen, dass die `BindNewIdentifier`-Vorlage konfiguriert ist. ::: -Ähnlich wie bei der Aktualisierung 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. +Ä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. -### Eine neue soziale Verbindung verknüpfen \{#link-a-new-social-connection} +### Neue soziale Verbindung verknüpfen \{#link-a-new-social-connection} -Um eine neue soziale Verbindung zu verknüpfen, solltest du zuerst eine Autorisierungs-URL anfordern: +Um eine neue soziale Verbindung zu verknüpfen, solltest du zunächst eine Autorisierungs-URL anfordern: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`: Die ID des [sozialen Connectors](/connectors/social-connectors/). -- `redirectUri`: Die Umleitungs-URI, nachdem der Benutzer die Anwendung autorisiert hat. Du solltest eine Webseite unter dieser URL hosten und den Callback erfassen. -- `state`: Der Zustand, der nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben wird. Es ist eine zufällige Zeichenfolge, die verwendet wird, um CSRF-Angriffe zu verhindern. +- `connectorId`: Die ID des [Social Connectors](/connectors/social-connectors/). +- `redirectUri`: Die Redirect-URI, zu der der Benutzer nach der Autorisierung der Anwendung weitergeleitet wird. Du solltest eine Webseite unter dieser URL hosten und den Callback abfangen. +- `state`: Der State, der nach der Autorisierung der Anwendung 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 der `redirectUri` mit dem `state`-Parameter. 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 die `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 \ @@ -267,9 +267,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -Die `connectorData` sind die Daten, die vom sozialen Connector nach der Autorisierung der Anwendung durch den Benutzer zurückgegeben werden. Du musst die Abfrageparameter von der `redirectUri` auf deiner Callback-Seite analysieren und als JSON als Wert des `connectorData`-Feldes verpacken. +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. -Schließlich kannst du den Endpunkt `POST /api/my-account/identities` verwenden, um die soziale Verbindung zu verknüpfen. +Abschließend kannst du den Endpunkt `POST /api/my-account/identities` verwenden, um die soziale Verbindung zu verknüpfen. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ @@ -279,7 +279,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ --data-raw '{"newIdentifierVerificationRecordId":"..."}' ``` -### Eine soziale Verbindung entfernen \{#remove-a-social-connection} +### Soziale Verbindung entfernen \{#remove-a-social-connection} Um eine soziale Verbindung zu entfernen, kannst du den Endpunkt `DELETE /api/my-account/identities` verwenden. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index cfdb06e6ac4..03fd1f3effa 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,11 +4,11 @@ sidebar_position: 2 # Organisationsmitglieder einladen -Als Multi-Organisations-Anwendung besteht eine häufige Anforderung darin, Mitglieder zu deiner Organisation einzuladen. In dieser Anleitung führen wir dich durch die Schritte und technischen Details, um diese Funktion in deiner Anwendung zu implementieren. +Als Multi-Organisations-Anwendung ist es eine häufige Anforderung, Mitglieder zu deiner Organisation einzuladen. In dieser Anleitung führen wir dich durch die Schritte und technischen Details, um dieses Feature in deiner Anwendung zu implementieren. ## Ablaufübersicht \{#flow-overview} -Der gesamte Prozess ist im folgenden Diagramm dargestellt: +Der gesamte Prozess wird im folgenden Diagramm dargestellt: ```mermaid sequenceDiagram @@ -23,7 +23,7 @@ sequenceDiagram C ->> C: Einladungslink mit Einladung-ID erstellen C ->> L: Anfordern des Versands der Einladungsemail mit Einladungslink L -->> U: Einladungsemail mit Einladungslink senden - U ->> C: Einladung anklicken und zur Landingpage navigieren,
Einladung annehmen oder ablehnen + U ->> C: Klick auf Einladungslink und Navigation zu deiner Landingpage,
Einladung annehmen oder ablehnen C ->> L: Einladungsstatus mit Management API aktualisieren ``` @@ -33,7 +33,7 @@ Bevor du Mitglieder zu deiner Organisation einlädst, musst du Organisationsroll In dieser Anleitung erstellen wir zwei typische Organisationsrollen: `admin` und `member`. -Die `admin`-Rolle hat vollen Zugriff auf alle Ressourcen der Organisation, während die `member`-Rolle eingeschränkten Zugriff hat. Zum Beispiel kann jede Rolle folgende Berechtigungen haben: +Die `admin`-Rolle hat vollen Zugriff auf alle Ressourcen der Organisation, während die `member`-Rolle eingeschränkten Zugriff hat. Zum Beispiel kann jede Rolle einen Satz von Berechtigungen wie folgt haben: - `admin`-Rolle: - `read:data` – Lesezugriff auf alle Organisationsdatenressourcen. @@ -68,7 +68,7 @@ Der Platzhalter `{{link}}` im E-Mail-Inhalt wird beim Versand der E-Mail durch d :::note -Der integrierte „Logto-E-Mail-Service“ von Logto Cloud unterstützt derzeit nicht den Nutzungstyp `OrganizationInvitation`. Stattdessen musst du deinen eigenen E-Mail-Connector (z. B. Sendgrid) konfigurieren und das `OrganizationInvitation`-Template einrichten. +Der integrierte „Logto E-Mail-Service“ von Logto Cloud unterstützt derzeit nicht den Nutzungstyp `OrganizationInvitation`. Stattdessen musst du deinen eigenen E-Mail-Connector (z. B. Sendgrid) konfigurieren und das `OrganizationInvitation`-Template einrichten. ::: @@ -80,11 +80,25 @@ Falls du die Logto Management API noch nicht eingerichtet hast, sieh dir [Mit Ma ::: -Wir stellen eine Reihe von einladungsbezogenen Management APIs im Organisations-Feature bereit. Mit diesen APIs kannst du: +### Für Cloud- und OSS v1.27.0+ Nutzer \{#for-cloud-and-oss-v1-27-0-users} + +Wir können jetzt das [Magic Link (Einmal-Token)](/end-user-flows/one-time-token) Feature verwenden, um den Einladungsablauf zu handhaben. + +Rufe einfach die Management API auf, um ein Einmal-Token zu erstellen, und erstelle einen Einladungs-Magic-Link mit dem Token und der E-Mail des Eingeladenen. +Füge den Link in den `{{link}}`-Platzhalter im obigen E-Mail-Template ein und sende die E-Mail an den Eingeladenen. +Du kannst einen Link wie `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` anstelle eines Links mit der Einladung-ID erstellen. + +Dies ist der empfohlene Ansatz, da der Eingeladene mit dem Magic Link automatisch registriert wird, falls er noch kein Konto hat. + +Sieh dir die Seite [Magic Link (Einmal-Token)](/end-user-flows/one-time-token) für weitere Details an. + +### Für OSS v1.26.0- Nutzer \{#for-oss-v1-26-0--users} + +Wir haben eine Reihe von einladungsbezogenen Management APIs im Organisations-Feature bereitgestellt. Mit diesen APIs kannst du: - `POST /api/organization-invitations` eine Organisationseinladung mit zugewiesener Organisationsrolle erstellen. - `POST /api/organization-invitations/{id}/message` die Organisationseinladung per E-Mail an den Eingeladenen senden. - Hinweis: Diese API-Payload unterstützt eine `link`-Eigenschaft, du kannst deinen Einladungslink basierend auf der Einladung-ID zusammenstellen. Zum Beispiel: + Hinweis: Diese API-Payload unterstützt eine `link`-Eigenschaft, du kannst deinen Einladungslink basierend auf der Einladung-ID erstellen. Zum Beispiel: ```json { @@ -96,12 +110,12 @@ Wir stellen eine Reihe von einladungsbezogenen Management APIs im Organisations- - `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` alle deine Einladungen oder eine bestimmte Einladung per ID abrufen. Auf deiner Landingpage kannst du diese APIs verwenden, um alle Einladungen oder Details einer Einladung anzuzeigen, die ein Benutzer erhalten hat. -- `PUT /api/organization-invitations/{id}/status` die Einladung durch Aktualisierung des Einladungsstatus annehmen oder ablehnen. +- `PUT /api/organization-invitations/{id}/status` die Einladung annehmen oder ablehnen, indem du den Einladungsstatus aktualisierst. Verwende diese API, um auf die Antwort des Benutzers auf die Einladung zu reagieren. ## Organisation rollenbasierte Zugangskontrolle (RBAC) zur Verwaltung von Benutzerberechtigungen verwenden \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} -Mit den obigen Einstellungen kannst du nun Einladungen per E-Mail versenden und Eingeladene können der Organisation mit der zugewiesenen Rolle beitreten. +Mit den obigen Einstellungen kannst du nun Einladungen per E-Mail versenden, und Eingeladene können der Organisation mit der zugewiesenen Rolle beitreten. Benutzer mit unterschiedlichen Organisationsrollen haben unterschiedliche Berechtigungen (Scopes) in ihren Organisationstokens. Daher sollten sowohl deine Client-App als auch Backend-Services diese Berechtigungen prüfen, um sichtbare Funktionen und erlaubte Aktionen zu bestimmen. @@ -113,7 +127,7 @@ Dieser Abschnitt behandelt fortgeschrittene Themen zur Verwaltung von Organisati Die Verwaltung von Scope-Updates in Organisationstokens umfasst: -### Bestehende Berechtigungen widerrufen \{#revoking-existing-scopes} +### Bestehende Berechtigungen entziehen \{#revoking-existing-scopes} Wenn z. B. ein Admin zu einem Nicht-Admin-Mitglied herabgestuft wird, sollten Berechtigungen vom Benutzer entfernt werden. In diesem Fall kannst du einfach das zwischengespeicherte Organisationstoken löschen und ein neues mit dem Auffrischungstoken abrufen. Die reduzierten Berechtigungen werden sofort im neu ausgestellten Organisationstoken reflektiert. @@ -123,7 +137,7 @@ Dies kann weiter in zwei Szenarien unterteilt werden: #### Neue Berechtigungen gewähren, die bereits im Auth-System definiert sind \{#grant-new-scopes-that-already-defined-in-your-auth-system} -Ähnlich wie beim Widerrufen von Berechtigungen kannst du, wenn die neu gewährte Berechtigung bereits beim Auth-Server registriert ist, einfach ein neues Organisationstoken ausstellen und die neuen Berechtigungen werden sofort reflektiert. +Ähnlich wie beim Entziehen von Berechtigungen kannst du, wenn die neu gewährte Berechtigung bereits beim Auth-Server registriert ist, einfach ein neues Organisationstoken ausstellen, und die neuen Berechtigungen werden sofort reflektiert. #### Neue Berechtigungen gewähren, die neu im Auth-System eingeführt wurden \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} @@ -131,11 +145,11 @@ In diesem Fall musst du einen erneuten Login- oder Zustimmungsprozess auslösen, ### Echtzeit-Berechtigungsprüfung implementieren und Organisationstoken aktualisieren \{#implement-real-time-permission-check-and-update-organization-token} -Logto stellt eine Management API bereit, um die aktuellen Benutzerberechtigungen in der Organisation abzurufen. +Logto stellt eine Management API bereit, um die Echtzeit-Benutzerberechtigungen in der Organisation abzurufen. - `GET /api/organizations/{id}/users/{userId}/scopes` ([API-Referenzen](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -Du kannst dann die Berechtigungen im Organisationstoken des Benutzers mit den aktuellen Berechtigungen vergleichen, um festzustellen, ob der Benutzer befördert oder herabgestuft wurde. +Du kannst dann die Berechtigungen im Organisationstoken des Benutzers mit den Echtzeit-Berechtigungen vergleichen, um festzustellen, ob der Benutzer befördert oder herabgestuft wurde. - Wenn herabgestuft, kannst du einfach das zwischengespeicherte Organisationstoken löschen und das SDK stellt automatisch ein neues mit den aktualisierten Berechtigungen aus. @@ -155,7 +169,7 @@ Du kannst dann die Berechtigungen im Organisationstoken des Benutzers mit den ak const { clearAllTokens, signIn } = useLogto(); ... - // Wenn die abgerufenen Echtzeit-Berechtigungen neue Berechtigungen im Vergleich zum Organisationstoken haben + // Wenn die abgerufenen Echtzeit-Berechtigungen neu zugewiesene Berechtigungen enthalten, die das Organisationstoken nicht hat await clearAllTokens(); signIn({ redirectUri: '', @@ -163,7 +177,7 @@ Du kannst dann die Berechtigungen im Organisationstoken des Benutzers mit den ak }); ``` - Der obige Code löst eine Navigation zum Zustimmungsbildschirm aus und leitet automatisch zurück zu deiner App, mit aktualisierten Berechtigungen im Organisationstoken des Benutzers. + Der obige Code löst eine Seitennavigation zum Zustimmungsbildschirm aus und leitet automatisch zurück zu deiner App, mit aktualisierten Berechtigungen im Organisationstoken des Benutzers. ## Verwandte Ressourcen \{#related-resources} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index de5e1e65932..04e79ed021e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,39 +1,39 @@ --- -description: Aprende a usar la Account API para gestionar usuarios +description: Aprende cómo usar la Account API para gestionar usuarios sidebar_position: 2 --- # Configuración de cuenta mediante Account API -## ¿Qué es Logto Account API? \{#what-is-logto-account-api} +## ¿Qué es la Account API de Logto? \{#what-is-logto-account-api} -La Logto Account API es un conjunto completo de APIs que brinda a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí están los aspectos destacados: +La Account API de Logto es un conjunto completo de APIs que brinda a los usuarios finales acceso directo a la API sin necesidad de pasar por la Management API. Aquí tienes los puntos destacados: -- Acceso directo: La Account API permite a los usuarios finales acceder y gestionar directamente su propio perfil de cuenta sin requerir el uso de la Management API. -- Gestión de perfiles de usuario e identidades: Los usuarios pueden gestionar completamente sus perfiles y configuraciones de seguridad, incluyendo la capacidad de actualizar información de identidad como correo electrónico, teléfono y contraseña, así como gestionar conexiones sociales. El soporte para MFA y SSO llegará pronto. -- Control de acceso global: El administrador tiene control total y global sobre las configuraciones de acceso, pudiendo personalizar cada campo. -- Autorización sin problemas: ¡Autorizar es más fácil que nunca! Simplemente usa `client.getAccessToken()` para obtener un token de acceso opaco para OP (Logto) y adjúntalo al encabezado de Autorización como `Bearer `. +- Acceso directo: La Account API permite a los usuarios finales acceder y gestionar directamente su propio perfil de cuenta sin requerir el uso intermedio de la Management API. +- Gestión de perfil de usuario e identidades: Los usuarios pueden gestionar completamente sus perfiles y configuraciones de seguridad, incluyendo la capacidad de actualizar información de identidad como correo electrónico, teléfono y contraseña, así como gestionar conexiones sociales. El soporte para MFA y SSO llegará pronto. +- Control de acceso global: El administrador tiene control total y global sobre la configuración de acceso, pudiendo personalizar cada campo. +- Autorización fluida: ¡Autorizar nunca fue tan fácil! Simplemente usa `client.getAccessToken()` para obtener un token de acceso opaco para OP (Logto), y adjúntalo en el encabezado Authorization como `Bearer `. -Con la Logto Account API, puedes construir un sistema de gestión de cuentas personalizado como una página de perfil totalmente integrada con Logto. +Con la Account API de Logto, puedes construir un sistema personalizado de gestión de cuentas, como una página de perfil totalmente integrada con Logto. -Algunos usos frecuentes se enumeran a continuación: +Algunos usos frecuentes se listan a continuación: -- Recuperar perfil de usuario -- Actualizar perfil de usuario -- Actualizar contraseña de usuario -- Actualizar identidades de usuario, incluyendo correo electrónico, teléfono y conexiones sociales +- Recuperar el perfil de usuario +- Actualizar el perfil de usuario +- Actualizar la contraseña del usuario +- Actualizar las identidades del usuario, incluyendo correo electrónico, teléfono y conexiones sociales -Para obtener más información sobre las APIs disponibles, visita [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) y [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). +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). :::note -Pronto estarán disponibles APIs dedicadas para las siguientes configuraciones: MFA, SSO, Datos personalizados (usuario) y Eliminación de cuenta. Mientras tanto, puedes implementar estas funciones utilizando las Logto Management APIs. 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: 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. ::: ## Cómo habilitar la Account API \{#how-to-enable-account-api} -Por defecto, la Account API está deshabilitada. Para habilitarla, necesitas usar la [Management API](/integrate-logto/interact-with-management-api) para actualizar las configuraciones globales. +Por defecto, la Account API está deshabilitada. Para habilitarla, necesitas usar la [Management API](/integrate-logto/interact-with-management-api) para actualizar la configuración global. -El endpoint de la API `/api/account-center` se puede usar para recuperar y actualizar las configuraciones del centro de cuentas, puedes usarlo para habilitar o deshabilitar la Account API y personalizar los campos. +El endpoint `/api/account-center` puede usarse para recuperar y actualizar la configuración del centro de cuentas; puedes usarlo para habilitar o deshabilitar la Account API y personalizar los campos. Ejemplo de solicitud: @@ -44,7 +44,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"enabled":true,"fields":{"username":"Edit"}}' ``` -El campo `enabled` se usa para habilitar o deshabilitar la Account API, y el campo `fields` se usa para personalizar los campos, el valor puede ser `Off`, `Edit`, `ReadOnly`. El valor predeterminado es `Off`. La lista de campos: +El campo `enabled` se usa para habilitar o deshabilitar la Account API, y el campo `fields` se usa para personalizar los campos; el valor puede ser `Off`, `Edit`, `ReadOnly`. El valor por defecto es `Off`. Lista de campos: - `name`: El campo de nombre. - `avatar`: El campo de avatar. @@ -52,24 +52,24 @@ El campo `enabled` se usa para habilitar o deshabilitar la Account API, y el cam - `username`: El campo de nombre de usuario. - `email`: El campo de correo electrónico. - `phone`: El campo de teléfono. -- `password`: El campo de contraseña, al obtenerlo, devolverá `true` si el usuario ha establecido una contraseña, de lo contrario `false`. +- `password`: El campo de contraseña; al obtenerlo, devolverá `true` si el usuario ha establecido una contraseña, de lo contrario `false`. - `social`: Conexiones sociales. -Obtén más información sobre los detalles de la API en [Logto Management API Reference](https://openapi.logto.io/group/endpoint-account-center). +Aprende más sobre los detalles de la API en la [Referencia de Logto Management API](https://openapi.logto.io/group/endpoint-account-center). ## Cómo acceder a la Account API \{#how-to-access-account-api} ### Obtener un token de acceso \{#fetch-an-access-token} -Después de configurar el SDK en tu aplicación, puedes usar el método `client.getAccessToken()` para obtener un token de acceso. Este token es un token opaco que se puede usar para acceder a la Account API. +Después de configurar el SDK en tu aplicación, puedes usar el método `client.getAccessToken()` para obtener un token de acceso. Este token es un token opaco que puede usarse para acceder a la Account API. -Si no estás usando el SDK oficial, debes establecer el `resource` en vacío para la solicitud de concesión de token de acceso a `/oidc/token`. +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 a la Account API usando el token de acceso \{#access-account-api-using-access-token} Debes colocar el token de acceso en el campo `Authorization` de los encabezados HTTP con el formato Bearer (`Bearer YOUR_TOKEN`) cuando interactúes con la Account API. -Un ejemplo para obtener la información de la cuenta del usuario: +Un ejemplo para obtener la información de la cuenta de usuario: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -78,14 +78,14 @@ curl https://[tenant-id].logto.app/api/my-account \ ## Gestionar información básica de la cuenta \{#manage-basic-account-information} -### Recuperar información de la cuenta del usuario \{#retrieve-user-account-information} +### Recuperar información de la cuenta de usuario \{#retrieve-user-account-information} ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -El cuerpo de la respuesta sería como: +El cuerpo de la respuesta sería así: ```json { @@ -96,7 +96,7 @@ El cuerpo de la respuesta sería como: } ``` -Los campos de respuesta pueden variar dependiendo de las configuraciones del centro de cuentas. +Los campos de la respuesta pueden variar dependiendo de la configuración del centro de cuentas. ### Actualizar información básica de la cuenta \{#update-basic-account-information} @@ -126,7 +126,7 @@ Por razones de seguridad, la Account API requiere otra capa de autorización par ### Obtener un id de registro de verificación \{#get-a-verification-record-id} -Primero, necesitas obtener un id de registro de verificación, esto se puede usar para verificar la identidad del usuario al actualizar identificadores. +Primero, necesitas obtener un id de registro de verificación; esto puede usarse para verificar la identidad del usuario al actualizar identificadores. Para obtener un id de registro de verificación, puedes verificar la contraseña del usuario o enviar un código de verificación al correo electrónico o teléfono del usuario. @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -El cuerpo de la respuesta sería como: +El cuerpo de la respuesta sería así: ```json { @@ -154,7 +154,7 @@ El cuerpo de la respuesta sería como: Para usar este método, necesitas [configurar el conector de correo electrónico](/connectors/email-connectors/) o [conector de SMS](/connectors/sms-connectors/), y asegurarte de que la plantilla `UserPermissionValidation` esté configurada. ::: -Toma el correo electrónico como ejemplo, solicita un nuevo código de verificación y obtén el id de registro de verificación: +Tomando el correo electrónico como ejemplo, solicita un nuevo código de verificación y obtén el id de registro de verificación: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -El cuerpo de la respuesta sería como: +El cuerpo de la respuesta sería así: ```json { @@ -175,7 +175,7 @@ El cuerpo de la respuesta sería como: Al recibir el código de verificación, puedes usarlo para actualizar el estado de verificación del registro de verificación. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' @@ -185,7 +185,7 @@ Después de verificar el código, ahora puedes usar el id de registro de verific ### Enviar solicitud con id de registro de verificación \{#send-request-with-verification-record-id} -Al enviar una solicitud para actualizar el identificador del usuario, necesitas adjuntar el id de registro de verificación al encabezado de la solicitud con el campo `logto-verification-id`. +Al enviar una solicitud para actualizar el identificador del usuario, necesitas adjuntar el id de registro de verificación en el encabezado de la solicitud con el campo `logto-verification-id`. ### Actualizar o vincular un nuevo correo electrónico \{#update-or-link-new-email} @@ -193,7 +193,7 @@ Al enviar una solicitud para actualizar el identificador del usuario, necesitas 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 electrónico. +Para actualizar o vincular un nuevo correo electrónico, primero debes demostrar la propiedad del correo. Llama al endpoint `POST /api/verifications/verification-code` para solicitar un código de verificación. @@ -204,16 +204,16 @@ 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 electrónico. +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 PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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 \ @@ -239,7 +239,7 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ Para usar este método, necesitas [configurar el conector de 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} @@ -253,10 +253,10 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`: El ID del [conector social](/connectors/social-connectors/). -- `redirectUri`: El 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. +- `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 su uso posterior. +En la respuesta, encontrarás un `verificationRecordId`, guárdalo para usarlo más adelante. 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. @@ -267,7 +267,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -El `connectorData` es el dato devuelto por el conector social después de que el usuario autorice la aplicación, necesitas analizar y obtener los parámetros de consulta del `redirectUri` en tu página de callback, y envolverlos como un JSON como el valor del campo `connectorData`. +El `connectorData` son los datos devueltos por el conector social después de que el usuario autoriza la aplicación; necesitas analizar y obtener los parámetros de consulta del `redirectUri` en tu página de callback y envolverlos como un JSON como valor del campo `connectorData`. Finalmente, puedes usar el endpoint `POST /api/my-account/identities` para vincular la conexión social. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index f562d40e800..5008ef15495 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -29,7 +29,7 @@ sequenceDiagram ## Crear roles de organización \{#create-organization-roles} -Antes de invitar miembros a tu organización, necesitas crear roles de organización. Consulta la [Plantilla de organización](/authorization/organization-template) para aprender más sobre los roles y permisos de organización. +Antes de invitar miembros a tu organización, necesitas crear roles de organización. Consulta la [Plantilla de organización](/authorization/organization-template) para aprender más sobre roles y permisos de organización. En esta guía, vamos a crear dos roles típicos de organización: `admin` y `member`. @@ -51,7 +51,7 @@ Esto se puede hacer fácilmente en la [Consola de Logto](https://cloud.logto.io/ ## Configura tu conector de correo electrónico \{#configure-your-email-connector} -Dado que las invitaciones se envían por correo electrónico, asegúrate de que tu [conector de correo electrónico](/connectors/email-connectors) esté correctamente configurado. Para enviar invitaciones, necesitas configurar un [tipo de uso de plantilla de correo electrónico](/connectors/email-connectors/email-templates#email-template-types) - `OrganizationInvitation`. También puedes incluir variables de organización (por ejemplo, nombre de la organización, logo) y del invitador (por ejemplo, correo electrónico del invitador, nombre) [variables](/connectors/email-connectors/email-templates#email-template-variables) en el contenido, o personalizar [plantillas multilingües](/connectors/email-connectors/email-templates#email-template-localization) según sea necesario. +Dado que las invitaciones se envían por correo electrónico, asegúrate de que tu [conector de correo electrónico](/connectors/email-connectors) esté correctamente configurado. Para enviar invitaciones, necesitas configurar un tipo de uso de [plantilla de correo electrónico](/connectors/email-connectors/email-templates#email-template-types) - `OrganizationInvitation`. También puedes incluir variables de organización (por ejemplo, nombre de la organización, logo) y del invitador (por ejemplo, correo electrónico del invitador, nombre) [variables](/connectors/email-connectors/email-templates#email-template-variables) en el contenido, o personalizar [plantillas multilingües](/connectors/email-connectors/email-templates#email-template-localization) según sea necesario. Un ejemplo de plantilla de correo electrónico para el tipo de uso `OrganizationInvitation` se muestra a continuación: @@ -68,7 +68,7 @@ El marcador `{{link}}` en el contenido del correo será reemplazado por el enlac :::note -El "servicio de correo electrónico de Logto" integrado en Logto Cloud no admite actualmente el tipo de uso `OrganizationInvitation`. En su lugar, necesitas configurar tu propio conector de correo electrónico (por ejemplo, Sendgrid) y establecer la plantilla `OrganizationInvitation`. +El "servicio de correo electrónico de Logto" integrado en Logto Cloud no admite actualmente el tipo de uso `OrganizationInvitation`. En su lugar, debes configurar tu propio conector de correo electrónico (por ejemplo, Sendgrid) y establecer la plantilla `OrganizationInvitation`. ::: @@ -80,11 +80,25 @@ Si aún no has configurado la Logto Management API, consulta [Interactuar con Ma ::: +### Para usuarios de Cloud y OSS v1.27.0+ \{#for-cloud-and-oss-v1-27-0-users} + +Ahora podemos usar la función de [Enlace mágico (Token de un solo uso)](/end-user-flows/one-time-token) para gestionar el flujo de invitación. + +Simplemente llama a la Management API para crear un token de un solo uso y compón un enlace mágico de invitación con el token y el correo electrónico del invitado. +Inserta el enlace en el marcador `{{link}}` de la plantilla de correo anterior y envía el correo al invitado. +Puedes componer un enlace como `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` en lugar de uno que contenga el ID de la invitación. + +Este es el enfoque recomendado, ya que registrará automáticamente al invitado con el enlace mágico si aún no tiene una cuenta. + +Consulta la página de [Enlace mágico (Token de un solo uso)](/end-user-flows/one-time-token) para más detalles. + +### Para usuarios de OSS v1.26.0 o anteriores \{#for-oss-v1-26-0--users} + Hemos proporcionado un conjunto de Management APIs relacionadas con invitaciones en la función de organizaciones. Con estas APIs, puedes: - `POST /api/organization-invitations` crear una invitación de organización con un rol de organización asignado. - `POST /api/organization-invitations/{id}/message` enviar la invitación de organización al invitado por correo electrónico. - Nota: Esta carga útil de la API admite una propiedad `link`, puedes componer tu enlace de invitación en función del ID de la invitación. Por ejemplo: + Nota: Esta API admite una propiedad `link` en el payload, puedes componer tu enlace de invitación basado en el ID de la invitación. Por ejemplo: ```json { @@ -95,11 +109,11 @@ Hemos proporcionado un conjunto de Management APIs relacionadas con invitaciones En consecuencia, necesitas implementar una página de destino cuando tu invitado navegue a través del enlace de invitación hacia tu aplicación. - `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` obtener todas tus invitaciones o una específica por ID. - En tu página de destino, utiliza estas APIs para listar todas las invitaciones o los detalles de una invitación que un usuario ha recibido. + En tu página de destino, usa estas APIs para listar todas las invitaciones o los detalles de una invitación que un usuario ha recibido. - `PUT /api/organization-invitations/{id}/status` aceptar o rechazar la invitación actualizando el estado de la invitación. - Utiliza esta API para gestionar la respuesta del usuario a la invitación. + Usa esta API para gestionar la respuesta del usuario a la invitación. -## Usa control de acceso basado en roles (RBAC) de organización para gestionar permisos de usuario \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +## Usa el control de acceso basado en roles (RBAC) de la organización para gestionar permisos de usuario \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} Con las configuraciones anteriores, ahora puedes enviar invitaciones por correo electrónico, y los invitados pueden unirse a la organización con el rol asignado. @@ -108,26 +122,26 @@ Los usuarios con diferentes roles de organización tendrán diferentes alcances ## Gestiona actualizaciones de alcance en los tokens de organización \{#handle-scope-updates-in-organization-tokens} :::note -Esta sección trata temas avanzados sobre la gestión de plantillas de organización y escenarios de autorización. Si no estás familiarizado con estos conceptos, por favor lee primero [Autorización](/authorization) y [Plantilla de organización](/authorization/organization-template). +Esta sección trata temas avanzados sobre la gestión de plantillas de organización y escenarios de autorización. Si no estás familiarizado con estos conceptos, por favor lee [Autorización](/authorization) y [Plantilla de organización](/authorization/organization-template) primero. ::: Gestionar actualizaciones de alcance en los tokens de organización implica: ### Revocar alcances existentes \{#revoking-existing-scopes} -Por ejemplo, degradar un admin a un miembro no admin debería eliminar alcances del usuario. En tal caso, simplemente puedes limpiar el token de organización en caché y obtener uno nuevo con el refresh token. Los alcances reducidos se reflejarán inmediatamente en el nuevo token de organización emitido. +Por ejemplo, degradar un admin a un miembro no admin debería eliminar alcances del usuario. En tal caso, simplemente puedes limpiar el token de organización en caché y obtener uno nuevo con el token de actualización. Los alcances reducidos se reflejarán inmediatamente en el nuevo token de organización emitido. ### Conceder nuevos alcances \{#granting-new-scopes} Esto se puede dividir en dos escenarios: -#### Conceder nuevos alcances que ya están definidos en tu sistema de autenticación \{#grant-new-scopes-that-already-defined-in-your-auth-system} +#### Conceder nuevos alcances ya definidos en tu sistema de autenticación \{#grant-new-scopes-that-already-defined-in-your-auth-system} -Similar a revocar alcances, si el nuevo alcance concedido ya está registrado en el servidor de autenticación, simplemente puedes emitir un nuevo token de organización, y los nuevos alcances se reflejarán de inmediato. +Similar a revocar alcances, si el nuevo alcance concedido ya está registrado en el servidor de autenticación, simplemente puedes emitir un nuevo token de organización y los nuevos alcances se reflejarán inmediatamente. -#### Conceder nuevos alcances que son recién introducidos en tu sistema de autenticación \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} +#### Conceder nuevos alcances recién introducidos en tu sistema de autenticación \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -En este caso, necesitas desencadenar un proceso de re-login o re-consentimiento para actualizar el token de organización del usuario. Por ejemplo, llamando al método `signIn` en Logto SDK. +En este caso, necesitas activar un proceso de re-inicio de sesión o re-consentimiento para actualizar el token de organización del usuario. Por ejemplo, llamando al método `signIn` en Logto SDK. ### Implementar comprobación de permisos en tiempo real y actualizar el token de organización \{#implement-real-time-permission-check-and-update-organization-token} @@ -143,19 +157,19 @@ Luego puedes comparar los alcances en el token de organización del usuario con const { clearAccessToken } = useLogto(); ... - // Si los alcances en tiempo real obtenidos son menos que los alcances del token de organización + // Si los alcances en tiempo real obtenidos son menores que los alcances del token de organización await clearAccessToken(); ``` - Esto no requiere un proceso de re-login o re-consentimiento. Los nuevos tokens de organización se emitirán automáticamente por el Logto SDK. + Esto no requiere un proceso de re-inicio de sesión o re-consentimiento. Los nuevos tokens de organización se emitirán automáticamente por el Logto SDK. -- Si se introduce un nuevo alcance en tu sistema de autenticación, desencadena un proceso de re-login o re-consentimiento para actualizar el token de organización del usuario. Tomemos como ejemplo el SDK de React: +- Si se introduce un nuevo alcance en tu sistema de autenticación, activa un proceso de re-inicio de sesión o re-consentimiento para actualizar el token de organización del usuario. Tomemos como ejemplo el SDK de React: ```ts const { clearAllTokens, signIn } = useLogto(); ... - // Si los alcances en tiempo real obtenidos incluyen nuevos alcances respecto al token de organización + // Si los alcances en tiempo real obtenidos tienen nuevos alcances asignados respecto a los del token de organización await clearAllTokens(); signIn({ redirectUri: '', @@ -163,7 +177,7 @@ Luego puedes comparar los alcances en el token de organización del usuario con }); ``` - El código anterior desencadenará una navegación a la pantalla de consentimiento y redirigirá automáticamente de vuelta a tu app, con los alcances actualizados en el token de organización del usuario. + El código anterior activará una navegación a la pantalla de consentimiento y redirigirá automáticamente de vuelta a tu app, con los alcances actualizados en el token de organización del usuario. ## Recursos relacionados \{#related-resources} 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 09ca17d3a66..8e02a73cbf0 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,39 +1,39 @@ --- -description: Apprenez à utiliser l'Account API pour gérer les utilisateurs +description: Découvrez comment utiliser l’Account API pour gérer l’utilisateur sidebar_position: 2 --- -# Paramètres de compte par Account API +# Paramètres du compte via l’Account API -## Qu'est-ce que Logto Account API \{#what-is-logto-account-api} +## Qu’est-ce que l’Account API de Logto \{#what-is-logto-account-api} -Le Logto Account API est un ensemble complet d'API qui donne aux utilisateurs finaux un accès direct à l'API sans avoir besoin de passer par le Management API, voici les points forts : +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 directement et de gérer leur propre profil de compte sans nécessiter le relais du Management API. -- Gestion du profil utilisateur et des identités : Les utilisateurs peuvent gérer entièrement leurs profils et paramètres de sécurité, y compris la possibilité de mettre à jour les informations d'identité telles que l'e-mail, le téléphone et le mot de passe, ainsi que de gérer les connexions sociales. Le support pour MFA et SSO arrive bientôt. -- Contrôle d'accès global : L'administrateur a un contrôle total et global sur les paramètres d'accès, peut personnaliser chaque champ. -- Autorisation transparente : L'autorisation est plus facile que jamais ! Utilisez simplement `client.getAccessToken()` pour obtenir un jeton d’accès (Access token) opaque pour OP (Logto), et attachez-le à l'en-tête Authorization comme `Bearer `. +- Accès direct : L’Account API permet aux utilisateurs finaux d’accéder et de gérer directement leur propre profil de compte sans nécessiter le relais de la Management API. +- Gestion du profil utilisateur et des identités : Les utilisateurs peuvent entièrement gérer 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 : L’administrateur dispose d’un contrôle total et global sur les paramètres d’accès, et peut personnaliser chaque champ. +- Autorisation transparente : L’autorisation 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 `. -Avec le Logto Account API, vous pouvez construire un système de gestion de compte personnalisé comme une page de profil entièrement intégrée à Logto. +Avec l’Account API de Logto, vous pouvez construire un système de gestion de compte personnalisé comme une page de profil entièrement intégrée à Logto. -Voici quelques utilisations fréquentes : +Voici quelques usages fréquents : - Récupérer le profil utilisateur - Mettre à jour le profil utilisateur - Mettre à jour le mot de passe utilisateur -- Mettre à jour les identités utilisateur, y compris l'e-mail, le téléphone et les connexions sociales +- Mettre à jour les identifiants utilisateur, y compris l’e-mail, le téléphone et les connexions sociales -Pour en savoir plus sur les API disponibles, veuillez visiter [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) et [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications). +Pour en savoir plus sur les API disponibles, consultez la [Référence de l’Account API de Logto](https://openapi.logto.io/group/endpoint-my-account) et la [Référence de l’API de vérification de 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 en utilisant les Logto Management APIs. Voir [Paramètres de compte par 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 : MFA, SSO, données personnalisées (utilisateur) et suppression de compte. En attendant, vous pouvez implémenter ces fonctionnalités à l’aide des 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. ::: -## Comment activer l'Account API \{#how-to-enable-account-api} +## 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 le [Management API](/integrate-logto/interact-with-management-api) pour mettre à jour les paramètres globaux. +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 `/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 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. Exemple de requête : @@ -44,32 +44,32 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \ --data-raw '{"enabled":true,"fields":{"username":"Edit"}}' ``` -Le champ `enabled` est utilisé pour activer ou désactiver l'Account API, et le champ `fields` est utilisé pour personnaliser les champs, la valeur peut être `Off`, `Edit`, `ReadOnly`. La valeur par défaut est `Off`. La liste des champs : +Le champ `enabled` permet d’activer ou de désactiver l’Account API, et le champ `fields` permet de personnaliser les champs. La valeur peut être `Off`, `Edit`, `ReadOnly`. La valeur par défaut est `Off`. Liste des champs : -- `name` : Le champ du nom. -- `avatar` : Le champ de l'avatar. -- `profile` : Le champ du profil, y compris ses sous-champs. -- `username` : Le champ du nom d'utilisateur. -- `email` : Le champ de l'e-mail. -- `phone` : Le champ du téléphone. -- `password` : Le champ du mot de passe, lors de la récupération, il retournera `true` si l'utilisateur a défini un mot de passe, sinon `false`. +- `name` : Le champ nom. +- `avatar` : Le champ avatar. +- `profile` : Le champ profil, y compris ses sous-champs. +- `username` : Le champ nom d’utilisateur. +- `email` : Le champ e-mail. +- `phone` : Le champ téléphone. +- `password` : Le champ mot de passe ; lors de la récupération, il retournera `true` si l’utilisateur a défini un mot de passe, sinon `false`. - `social` : Connexions sociales. -En savoir plus sur les détails de l'API dans [Logto Management API Reference](https://openapi.logto.io/group/endpoint-account-center). +En savoir plus sur les détails de l’API dans la [Référence de la Management API de Logto](https://openapi.logto.io/group/endpoint-account-center). -## Comment accéder à l'Account API \{#how-to-access-account-api} +## Comment accéder à l’Account API \{#how-to-access-account-api} ### Récupérer un jeton d’accès \{#fetch-an-access-token} -Après avoir configuré le SDK dans votre application, vous pouvez utiliser la méthode `client.getAccessToken()` pour récupérer un jeton d’accès. Ce jeton est un jeton opaque qui peut être utilisé pour accéder à l'Account API. +Après avoir configuré le SDK dans votre application, vous pouvez utiliser la méthode `client.getAccessToken()` pour récupérer un jeton d’accès. Ce jeton est un jeton opaque (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 `resource` à vide pour la requête de jeton d’accès à `/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 en utilisant le jeton d’accès \{#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 placer le jeton d’accès dans le champ `Authorization` des en-têtes HTTP avec le format Bearer (`Bearer YOUR_TOKEN`) lorsque vous interagissez avec l'Account API. +Vous devez placer le jeton d’accès dans le champ `Authorization` des en-têtes HTTP au format Bearer (`Bearer YOUR_TOKEN`) lorsque vous interagissez avec l’Account API. -Un exemple pour obtenir les informations du compte utilisateur : +Exemple pour obtenir les informations du compte utilisateur : ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -85,7 +85,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -Le corps de la réponse serait comme : +Le corps de la réponse sera similaire à : ```json { @@ -96,13 +96,13 @@ Le corps de la réponse serait comme : } ``` -Les champs de la réponse peuvent varier en fonction des paramètres du centre de compte. +Les champs de la réponse peuvent varier selon les paramètres du centre de compte. ### Mettre à jour les informations de base du compte \{#update-basic-account-information} -Les informations de base du compte incluent le nom d'utilisateur, le nom, l'avatar et le profil. +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 de terminaison `PATCH /api/my-account`. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -122,15 +122,15 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Gérer les identifiants et autres informations sensibles \{#manage-identifiers-and-other-sensitive-information} -Pour des raisons de sécurité, l'Account API nécessite une autre couche d'autorisation pour les opérations impliquant des identifiants et d'autres informations sensibles. +Pour des raisons de sécurité, l’Account API nécessite une couche supplémentaire d’autorisation pour les opérations impliquant des identifiants et autres informations sensibles. -### Obtenir un identifiant d'enregistrement de vérification \{#get-a-verification-record-id} +### Obtenir un identifiant d’enregistrement de vérification \{#get-a-verification-record-id} -Tout d'abord, vous devez obtenir un identifiant d'enregistrement de vérification, cela peut être utilisé pour vérifier l'identité de l'utilisateur lors de la mise à jour des identifiants. +Vous devez d’abord obtenir un identifiant d’enregistrement de vérification, qui peut être utilisé pour vérifier l’identité de l’utilisateur lors de la mise à jour des identifiants. -Pour obtenir un identifiant d'enregistrement de vérification, vous pouvez vérifier le mot de passe de l'utilisateur ou envoyer un code de vérification à l'e-mail ou au téléphone de l'utilisateur. +Pour obtenir un identifiant d’enregistrement de vérification, vous pouvez vérifier le mot de passe de l’utilisateur ou envoyer un code de vérification à l’e-mail ou au téléphone de l’utilisateur. -#### Vérifier le mot de passe de l'utilisateur \{#verify-the-users-password} +#### Vérifier le mot de passe de l’utilisateur \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -Le corps de la réponse serait comme : +Le corps de la réponse sera similaire à : ```json { @@ -148,13 +148,13 @@ Le corps de la réponse serait comme : } ``` -#### Vérifier en envoyant un code de vérification à l'e-mail ou au téléphone de l'utilisateur \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### Vérifier en envoyant un code de vérification à l’e-mail ou au téléphone de l’utilisateur \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -Pour utiliser cette méthode, vous devez [configurer le connecteur e-mail](/connectors/email-connectors/) ou [le connecteur SMS](/connectors/sms-connectors/), et vous assurer que le 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 : +Prenons l’e-mail comme exemple, demandez un nouveau code de vérification et obtenez l’identifiant d’enregistrement de vérification : ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Le corps de la réponse serait comme : +Le corps de la réponse sera similaire à : ```json { @@ -172,28 +172,28 @@ Le corps de la réponse serait comme : } ``` -Après avoir reçu le code de vérification, vous pouvez l'utiliser pour mettre à jour le statut de vérification de l'enregistrement de vérification. +Après réception du code de vérification, vous pouvez l’utiliser pour mettre à jour le statut de vérification de l’enregistrement. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Après avoir vérifié le code, vous pouvez maintenant utiliser l'identifiant d'enregistrement de vérification pour mettre à jour l'identifiant de l'utilisateur. +Après avoir vérifié le code, vous pouvez maintenant utiliser l’identifiant d’enregistrement de vérification pour mettre à jour l’identifiant de l’utilisateur. -### Envoyer une requête avec l'identifiant d'enregistrement de vérification \{#send-request-with-verification-record-id} +### Envoyer une requête avec l’identifiant d’enregistrement de vérification \{#send-request-with-verification-record-id} -Lors de l'envoi d'une requête pour mettre à jour l'identifiant de l'utilisateur, vous devez attacher l'identifiant d'enregistrement de vérification à l'en-tête de la requête avec le champ `logto-verification-id`. +Lors de l’envoi d’une requête pour mettre à jour l’identifiant de l’utilisateur, vous devez joindre l’identifiant d’enregistrement de vérification à l’en-tête de la requête avec le champ `logto-verification-id`. ### 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. +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. @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Vous trouverez un `verificationId` dans la réponse, et recevrez un code de vérification dans l'e-mail, utilisez-le pour vérifier l'e-mail. +Vous trouverez un `verificationId` dans la réponse et recevrez un code de vérification par e-mail, utilisez-le pour vérifier l’e-mail. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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, définissez 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 \ @@ -223,9 +223,9 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}' ``` -### Supprimer l'e-mail de l'utilisateur \{#remove-the-users-email} +### Supprimer l’e-mail de l’utilisateur \{#remove-the-users-email} -Pour supprimer l'e-mail de l'utilisateur, vous pouvez utiliser le point de terminaison `DELETE /api/my-account/primary-email`. +Pour supprimer l’e-mail de l’utilisateur, vous pouvez utiliser le point de terminaison `DELETE /api/my-account/primary-email`. ```bash curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ @@ -236,14 +236,14 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Gérer le téléphone \{#manage-phone} :::note -Pour utiliser cette méthode, vous devez [configurer le connecteur SMS](/connectors/sms-connectors/), et vous assurer que le 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é. ::: -Similaire à 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 utilisez le point de terminaison `DELETE /api/my-account/primary-phone` pour supprimer le téléphone de l'utilisateur. +De manière similaire à 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. ### Lier une nouvelle connexion sociale \{#link-a-new-social-connection} -Pour lier une nouvelle connexion sociale, vous devez d'abord demander une URL d'autorisation : +Pour lier une nouvelle connexion sociale, vous devez d’abord demander une URL d’autorisation : ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId` : L'ID du [connecteur social](/connectors/social-connectors/). -- `redirectUri` : L'URI de redirection après que l'utilisateur a autorisé l'application, vous devez héberger une page web à cette URL et capturer le rappel. -- `state` : L'état à retourner après que l'utilisateur a autorisé l'application, c'est une chaîne aléatoire utilisée pour prévenir les attaques CSRF. +- `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. 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 rappel à l'`redirectUri` avec le paramètre `state`. Ensuite, vous pouvez 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 de terminaison `POST /api/verifications/social/verify` pour vérifier la connexion sociale. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -267,7 +267,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -Le `connectorData` est les données retournées par le connecteur social après que l'utilisateur a autorisé l'application, vous devez analyser et obtenir les paramètres de requête de l'`redirectUri` dans votre page de rappel, et les envelopper en JSON comme valeur du champ `connectorData`. +Le `connectorData` correspond aux données retournées 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 l’`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. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index 5c46c959294..cf7b7cb3927 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -23,7 +23,7 @@ sequenceDiagram C ->> C: Composer le lien d'invitation avec l'ID de l'invitation C ->> L: Demander l'envoi de l'e-mail d'invitation avec le lien d'invitation L -->> U: Envoyer l'e-mail d'invitation avec le lien d'invitation - U ->> C: Cliquer sur le lien d'invitation et naviguer vers votre page d'accueil,
accepter ou refuser l'invitation + U ->> C: Cliquer sur le lien d'invitation et naviguer vers votre page d'atterrissage,
accepter ou refuser l'invitation C ->> L: Mettre à jour le statut de l'invitation avec Management API ``` @@ -64,7 +64,7 @@ Un exemple de modèle d'e-mail pour le type d'utilisation `OrganizationInvitatio } ``` -Le placeholder `{{link}}` dans le contenu de l'e-mail sera remplacé par le véritable lien d'invitation lors de l'envoi de l'e-mail. Dans ce guide, supposons qu'il s'agisse de `https://your-app.com/invitation/accept/{your-invitation-id}`. +Le placeholder `{{link}}` dans le contenu de l'e-mail sera remplacé par le lien d'invitation réel lors de l'envoi de l'e-mail. Dans ce guide, supposons qu'il s'agisse de `https://your-app.com/invitation/accept/{your-invitation-id}`. :::note @@ -80,11 +80,25 @@ Si vous n'avez pas encore configuré la Logto Management API, consultez [Interag ::: -Nous avons fourni un ensemble d'APIs Management liées aux invitations dans la fonctionnalité organisations. Avec ces APIs, vous pouvez : +### Pour les utilisateurs Cloud et OSS v1.27.0+ \{#for-cloud-and-oss-v1-27-0-users} + +Nous pouvons désormais utiliser la fonctionnalité [Lien magique (Jeton à usage unique)](/end-user-flows/one-time-token) pour gérer le flux d'invitation. + +Il suffit d'appeler la Management API pour créer un jeton à usage unique, puis de composer un lien magique d'invitation avec le jeton et l'e-mail de l'invité. +Insérez le lien dans le placeholder `{{link}}` du modèle d'e-mail ci-dessus, puis envoyez l'e-mail à l'invité. +Vous pouvez composer un lien du type `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` au lieu de celui contenant l'ID d'invitation. + +C'est l'approche recommandée, car elle enregistrera automatiquement l'invité avec le lien magique s'il n'a pas encore de compte. + +Consultez la page [Lien magique (Jeton à usage unique)](/end-user-flows/one-time-token) pour plus de détails. + +### Pour les utilisateurs OSS v1.26.0 et antérieurs \{#for-oss-v1-26-0--users} + +Nous avons fourni un ensemble d'API de gestion liées aux invitations dans la fonctionnalité organisations. Avec ces API, vous pouvez : - `POST /api/organization-invitations` créer une invitation d'organisation avec un rôle d'organisation attribué. - `POST /api/organization-invitations/{id}/message` envoyer l'invitation d'organisation à l'invité par e-mail. - Remarque : Le payload de cette API prend en charge une propriété `link`, vous pouvez composer votre lien d'invitation à partir de l'ID d'invitation. Par exemple : + Remarque : Le payload de cette API prend en charge une propriété `link`, vous pouvez composer votre lien d'invitation en fonction de l'ID d'invitation. Par exemple : ```json { @@ -92,10 +106,10 @@ Nous avons fourni un ensemble d'APIs Management liées aux invitations dans la f } ``` - En conséquence, vous devez implémenter une page d'accueil lorsque votre invité navigue via le lien d'invitation vers votre application. + En conséquence, vous devez implémenter une page d'atterrissage lorsque votre invité navigue via le lien d'invitation vers votre application. - `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` obtenir toutes vos invitations ou une invitation spécifique par ID. - Sur votre page d'accueil, utilisez ces APIs pour lister toutes les invitations ou les détails d'une invitation reçue par un utilisateur. + Sur votre page d'atterrissage, utilisez ces API pour lister toutes les invitations ou les détails d'une invitation reçue par un utilisateur. - `PUT /api/organization-invitations/{id}/status` accepter ou refuser l'invitation en mettant à jour le statut de l'invitation. Utilisez cette API pour gérer la réponse de l'utilisateur à l'invitation. @@ -108,14 +122,14 @@ Les utilisateurs avec différents rôles d'organisation auront différentes port ## Gérer les mises à jour de portée dans les jetons d’organisation \{#handle-scope-updates-in-organization-tokens} :::note -Cette section aborde des sujets avancés concernant la gestion du modèle d'organisation et les scénarios d'autorisation. Si vous n'êtes pas familier avec ces concepts, veuillez lire [Autorisation](/authorization) et [modèle d'organisation](/authorization/organization-template) en premier. +Cette section aborde des sujets avancés concernant la gestion du modèle d'organisation et les scénarios d'autorisation. Si vous n'êtes pas familier avec ces concepts, veuillez lire [Autorisation](/authorization) et [Modèle d'organisation](/authorization/organization-template) en premier. ::: La gestion des mises à jour de portée dans les jetons d’organisation implique : ### Révoquer des portées existantes \{#revoking-existing-scopes} -Par exemple, rétrograder un admin en membre non-admin doit retirer des portées à l'utilisateur. Dans ce cas, vous pouvez simplement vider le jeton d’organisation mis en cache et en récupérer un nouveau avec le jeton de rafraîchissement. Les portées réduites seront immédiatement reflétées dans le nouveau jeton d’organisation émis. +Par exemple, rétrograder un admin en membre non-admin doit supprimer des portées de l'utilisateur. Dans ce cas, vous pouvez simplement vider le jeton d’organisation mis en cache et en récupérer un nouveau avec le jeton de rafraîchissement. Les portées réduites seront immédiatement reflétées dans le nouveau jeton d’organisation émis. ### Accorder de nouvelles portées \{#granting-new-scopes} @@ -127,15 +141,15 @@ Comme pour la révocation de portées, si la nouvelle portée accordée est déj #### Accorder de nouvelles portées nouvellement introduites dans votre système d’authentification \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -Dans ce cas, vous devez déclencher un processus de reconnexion ou de reconsentement pour mettre à jour le jeton d’organisation de l'utilisateur. Par exemple, en appelant la méthode `signIn` dans le SDK Logto. +Dans ce cas, vous devez déclencher un processus de reconnexion ou de re-consentement pour mettre à jour le jeton d’organisation de l'utilisateur. Par exemple, en appelant la méthode `signIn` dans le SDK Logto. ### Implémenter une vérification des permissions en temps réel et mettre à jour le jeton d’organisation \{#implement-real-time-permission-check-and-update-organization-token} -Logto fournit Management API pour récupérer en temps réel les permissions d’un utilisateur dans l’organisation. +Logto fournit la Management API pour récupérer en temps réel les permissions utilisateur dans l'organisation. - `GET /api/organizations/{id}/users/{userId}/scopes` ([Références API](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -Vous pouvez alors comparer les portées dans le jeton d’organisation de l’utilisateur avec les permissions en temps réel pour déterminer si l’utilisateur a été promu ou rétrogradé. +Vous pouvez alors comparer les portées dans le jeton d’organisation de l'utilisateur avec les permissions en temps réel pour déterminer si l'utilisateur a été promu ou rétrogradé. - Si rétrogradé, vous pouvez simplement vider le jeton d’organisation mis en cache et le SDK émettra automatiquement un nouveau jeton avec les portées mises à jour. @@ -147,9 +161,9 @@ Vous pouvez alors comparer les portées dans le jeton d’organisation de l’ut await clearAccessToken(); ``` - Cela ne nécessite pas de reconnexion ou de reconsentement. De nouveaux jetons d’organisation seront émis automatiquement par le SDK Logto. + Cela ne nécessite pas de reconnexion ou de re-consentement. De nouveaux jetons d’organisation seront émis automatiquement par le SDK Logto. -- Si une nouvelle portée est introduite dans votre système d’authentification, déclenchez un processus de reconnexion ou de reconsentement pour mettre à jour le jeton d’organisation de l’utilisateur. Prenons l’exemple du SDK React : +- Si une nouvelle portée est introduite dans votre système d’authentification, déclenchez un processus de reconnexion ou de re-consentement pour mettre à jour le jeton d’organisation de l'utilisateur. Prenons l'exemple du SDK React : ```ts const { clearAllTokens, signIn } = useLogto(); @@ -163,10 +177,10 @@ Vous pouvez alors comparer les portées dans le jeton d’organisation de l’ut }); ``` - Le code ci-dessus déclenchera une navigation vers l’écran de consentement et un retour automatique vers votre application, avec les portées mises à jour dans le jeton d’organisation de l’utilisateur. + Le code ci-dessus déclenchera une navigation vers l'écran de consentement et un retour automatique vers votre application, avec les portées mises à jour dans le jeton d’organisation de l'utilisateur. ## Ressources associées \{#related-resources} - Comment nous avons implémenté la collaboration utilisateur dans une application multi-tenant + Comment nous avons implémenté la collaboration utilisateur dans une application multi-locataire 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 0a26956a84e..903aa957e86 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 @@ -7,33 +7,33 @@ sidebar_position: 2 ## Logto Account API とは \{#what-is-logto-account-api} -Logto Account API は、エンドユーザーが Management API を経由せずに直接 API にアクセスできる包括的な API セットです。以下がそのハイライトです： +Logto Account API は、エンドユーザーが Management API を経由せずに直接 API アクセスできる包括的な API セットです。主な特徴は以下の通りです： -- 直接アクセス：Account API は、エンドユーザーが自分のアカウントプロファイルに直接アクセスし管理することを可能にし、Management API の中継を必要としません。 -- ユーザープロファイルとアイデンティティ管理：ユーザーは、メール、電話、パスワードなどのアイデンティティ情報の更新やソーシャル接続の管理を含む、プロファイルとセキュリティ設定を完全に管理できます。MFA と SSO のサポートは近日公開予定です。 -- グローバルアクセス制御：管理者はアクセス設定を完全にグローバルに制御でき、各フィールドをカスタマイズできます。 -- シームレスな認可 (Authorization)：認可 (Authorization) はこれまでになく簡単です！`client.getAccessToken()` を使用して OP (Logto) の不透明トークンを取得し、それを `Bearer ` として Authorization ヘッダーに添付します。 +- 直接アクセス：Account API により、エンドユーザーは Management API を介さずに自分のアカウントプロファイルへ直接アクセス・管理できます。 +- ユーザープロファイルとアイデンティティ管理：ユーザーは自分のプロファイルやセキュリティ設定を完全に管理できます。メール、電話、パスワードなどのアイデンティティ情報の更新やソーシャル連携の管理が可能です。多要素認証 (MFA) やシングルサインオン (SSO) のサポートも近日追加予定です。 +- グローバルアクセス制御：管理者はアクセス設定をグローバルに完全管理でき、各フィールドをカスタマイズできます。 +- シームレスな認可 (Authorization)：認可 (Authorization) がこれまでになく簡単に！`client.getAccessToken()` を使って OP (Logto) 用の不透明トークン (Opaque token) を取得し、`Authorization` ヘッダーに `Bearer ` として付与するだけです。 -Logto Account API を使用すると、Logto と完全に統合されたプロファイルページのようなカスタムアカウント管理システムを構築できます。 +Logto Account API を使えば、Logto と完全連携したプロフィールページのようなカスタムアカウント管理システムを構築できます。 -以下に一般的な使用例を示します： +よく使われるユースケース例： - ユーザープロファイルの取得 - ユーザープロファイルの更新 - ユーザーパスワードの更新 -- メール、電話、ソーシャル接続を含むユーザーアイデンティティの更新 +- メール、電話、ソーシャル連携などのユーザーアイデンティティの更新 -利用可能な 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 は近日公開予定です：多要素認証 (MFA)、シングルサインオン (SSO)、カスタムデータ（ユーザー）、アカウント削除。それまでは Logto Management API を使ってこれらの機能を実装できます。詳細は [Management API によるアカウント設定](/end-user-flows/account-settings/by-management-api) をご参照ください。 ::: -## Account API を有効にする方法 \{#how-to-enable-account-api} +## Account API を有効化する方法 \{#how-to-enable-account-api} -デフォルトでは、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 の有効 / 無効やフィールドのカスタマイズができます。 リクエスト例： @@ -44,30 +44,30 @@ 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`: プロファイルフィールドとそのサブフィールド。 -- `username`: ユーザーネームフィールド。 -- `email`: メールフィールド。 -- `phone`: 電話フィールド。 -- `password`: パスワードフィールド。取得時、ユーザーがパスワードを設定している場合は `true`、そうでない場合は `false` を返します。 -- `social`: ソーシャル接続。 +- `name`: 名前フィールド +- `avatar`: アバターフィールド +- `profile`: プロファイルフィールド（サブフィールド含む） +- `username`: ユーザー名フィールド +- `email`: メールフィールド +- `phone`: 電話番号フィールド +- `password`: パスワードフィールド。取得時、ユーザーがパスワードを設定していれば `true`、そうでなければ `false` を返します。 +- `social`: ソーシャル連携 -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} +## Account API へのアクセス方法 \{#how-to-access-account-api} -### アクセストークンを取得する \{#fetch-an-access-token} +### アクセストークンの取得 \{#fetch-an-access-token} -アプリケーションに SDK を設定した後、`client.getAccessToken()` メソッドを使用してアクセストークンを取得できます。このトークンは、不透明トークンであり、Account API にアクセスするために使用できます。 +アプリケーションに SDK をセットアップした後、`client.getAccessToken()` メソッドでアクセストークンを取得できます。このトークンは Account API へのアクセスに使える不透明トークン (Opaque token) です。 -公式 SDK を使用していない場合、`/oidc/token` へのアクセストークングラントリクエストの `resource` を空に設定する必要があります。 +公式 SDK を使わない場合は、アクセストークンの発行リクエスト `/oidc/token` で `resource` を空に設定してください。 -### アクセストークンを使用して Account API にアクセスする \{#access-account-api-using-access-token} +### アクセストークンを使った Account API へのアクセス \{#access-account-api-using-access-token} -Account API とやり取りする際、HTTP ヘッダーの `Authorization` フィールドに Bearer 形式 (`Bearer YOUR_TOKEN`) でアクセストークンを配置する必要があります。 +Account API へリクエストする際は、HTTP ヘッダーの `Authorization` フィールドに Bearer 形式（`Bearer YOUR_TOKEN`）でアクセストークンを付与してください。 ユーザーアカウント情報を取得する例： @@ -76,16 +76,16 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## 基本的なアカウント情報を管理する \{#manage-basic-account-information} +## 基本的なアカウント情報の管理 \{#manage-basic-account-information} -### ユーザーアカウント情報を取得する \{#retrieve-user-account-information} +### ユーザーアカウント情報の取得 \{#retrieve-user-account-information} ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -レスポンスボディは次のようになります： +レスポンス例： ```json { @@ -96,13 +96,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -レスポンスフィールドは、アカウントセンターの設定に応じて異なる場合があります。 +レスポンスフィールドはアカウントセンター設定によって異なる場合があります。 -### 基本的なアカウント情報を更新する \{#update-basic-account-information} +### 基本的なアカウント情報の更新 \{#update-basic-account-information} -基本的なアカウント情報には、ユーザーネーム、名前、アバター、プロファイルが含まれます。 +基本的なアカウント情報にはユーザー名、名前、アバター、プロファイルが含まれます。 -ユーザーネーム、名前、アバターを更新するには、`PATCH /api/my-account` エンドポイントを使用できます。 +ユーザー名、名前、アバターを更新するには `PATCH /api/my-account` エンドポイントを使用します。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -111,7 +111,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -プロファイルを更新するには、`PATCH /api/my-account/profile` エンドポイントを使用できます。 +プロファイルを更新するには `PATCH /api/my-account/profile` エンドポイントを使用します。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -120,17 +120,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 識別子とその他の機密情報を管理する \{#manage-identifiers-and-other-sensitive-information} +## 識別子やその他の機微情報の管理 \{#manage-identifiers-and-other-sensitive-information} -セキュリティ上の理由から、Account API は識別子やその他の機密情報に関わる操作に対して別の認可 (Authorization) レイヤーを要求します。 +セキュリティ上の理由から、Account API で識別子やその他の機微情報を扱う操作には追加の認可 (Authorization) レイヤーが必要です。 -### 検証レコード ID を取得する \{#get-a-verification-record-id} +### 検証レコード ID の取得 \{#get-a-verification-record-id} -まず、検証レコード ID を取得する必要があります。これは識別子を更新する際にユーザーのアイデンティティを確認するために使用されます。 +まず、検証レコード ID を取得する必要があります。これは識別子の更新時にユーザーの本人確認に使われます。 -検証レコード ID を取得するには、ユーザーのパスワードを確認するか、ユーザーのメールまたは電話に検証コードを送信します。 +検証レコード ID を取得するには、ユーザーのパスワードを検証するか、メールまたは電話に認証コードを送信します。 -#### ユーザーのパスワードを確認する \{#verify-the-users-password} +#### ユーザーのパスワードで検証 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -レスポンスボディは次のようになります： +レスポンス例： ```json { @@ -148,13 +148,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### ユーザーのメールまたは電話に検証コードを送信して確認する \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### メールまたは電話に認証コードを送信して検証 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -この方法を使用するには、 [メールコネクター](/connectors/email-connectors/) または [SMS コネクター](/connectors/sms-connectors/) を設定し、`UserPermissionValidation` テンプレートが設定されていることを確認してください。 +この方法を利用するには [メールコネクター](/connectors/email-connectors/) または [SMS コネクター](/connectors/sms-connectors/) を設定し、`UserPermissionValidation` テンプレートが設定されていることを確認してください。 ::: -メールを例にとると、新しい検証コードをリクエストし、検証レコード ID を取得します： +メールを例に、新しい認証コードをリクエストし検証レコード ID を取得します： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -レスポンスボディは次のようになります： +レスポンス例： ```json { @@ -172,30 +172,30 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -検証コードを受け取ったら、それを使用して検証レコードの検証ステータスを更新できます。 +認証コードを受け取ったら、それを使って検証レコードの検証ステータスを更新できます。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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` フィールドをリクエストヘッダーに添付する必要があります。 +ユーザーの識別子を更新するリクエストを送信する際は、リクエストヘッダーの `logto-verification-id` フィールドに検証レコード ID を付与してください。 -### 新しいメールを更新またはリンクする \{#update-or-link-new-email} +### 新しいメールの更新または連携 \{#update-or-link-new-email} :::note -この方法を使用するには、 [メールコネクター](/connectors/email-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を利用するには [メールコネクター](/connectors/email-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -新しいメールを更新またはリンクするには、まずメールの所有権を証明する必要があります。 +新しいメールを更新または連携するには、まずメールの所有権を証明する必要があります。 -`POST /api/verifications/verification-code` エンドポイントを呼び出して検証コードをリクエストします。 +`POST /api/verifications/verification-code` エンドポイントで認証コードをリクエストします。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -レスポンスには `verificationId` が含まれ、メールには検証コードが送信されます。それを使用してメールを確認します。 +レスポンスに `verificationId` が含まれ、メールで認証コードが届きます。それを使ってメールを検証します。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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 \ @@ -223,9 +223,9 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --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 \ @@ -233,17 +233,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 電話を管理する \{#manage-phone} +### 電話番号の管理 \{#manage-phone} :::note -この方法を使用するには、 [SMS コネクター](/connectors/sms-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 +この方法を利用するには [SMS コネクター](/connectors/sms-connectors/) を設定し、`BindNewIdentifier` テンプレートが設定されていることを確認してください。 ::: -メールの更新と同様に、`PATCH /api/my-account/primary-phone` エンドポイントを使用して新しい電話を更新またはリンクできます。また、`DELETE /api/my-account/primary-phone` エンドポイントを使用してユーザーの電話を削除できます。 +メールの更新と同様に、`PATCH /api/my-account/primary-phone` エンドポイントで新しい電話番号の更新または連携ができます。また、`DELETE /api/my-account/primary-phone` エンドポイントでユーザーの電話番号を削除できます。 -### 新しいソーシャル接続をリンクする \{#link-a-new-social-connection} +### 新しいソーシャル連携の追加 \{#link-a-new-social-connection} -新しいソーシャル接続をリンクするには、まず認可 (Authorization) URL をリクエストする必要があります： +新しいソーシャル連携を追加するには、まず認可 (Authorization) URL をリクエストします： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`: [ソーシャルコネクター](/connectors/social-connectors/) の ID。 -- `redirectUri`: ユーザーがアプリケーションを認可 (Authorization) した後のリダイレクト URI。この URL にウェブページをホストし、コールバックをキャプチャする必要があります。 -- `state`: ユーザーがアプリケーションを認可 (Authorization) した後に返される状態。CSRF 攻撃を防ぐために使用されるランダムな文字列です。 +- `connectorId`: [ソーシャルコネクター](/connectors/social-connectors/) の ID +- `redirectUri`: ユーザーがアプリケーションを認可 (Authorization) した後のリダイレクト先 URI。この URL で Web ページをホストし、コールバックを受け取る必要があります。 +- `state`: ユーザーがアプリケーションを認可 (Authorization) した後に返される state。CSRF 攻撃防止のためのランダム文字列です。 -レスポンスには `verificationRecordId` が含まれ、後で使用するために保持します。 +レスポンスに `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 \ @@ -267,9 +267,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData` は、ユーザーがアプリケーションを認可 (Authorization) した後にソーシャルコネクターから返されるデータです。コールバックページで `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 \ @@ -279,9 +279,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ --data-raw '{"newIdentifierVerificationRecordId":"..."}' ``` -### ソーシャル接続を削除する \{#remove-a-social-connection} +### ソーシャル連携の削除 \{#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] \ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index 4f552a83cc9..cd7dfdc93cd 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,7 +4,7 @@ sidebar_position: 2 # 組織メンバーの招待 -マルチ組織アプリケーションでは、よくある要件として組織にメンバーを招待することがあります。このガイドでは、アプリケーションでこの機能を実装するための手順と技術的な詳細を説明します。 +マルチ組織アプリケーションでは、組織にメンバーを招待することが一般的な要件です。このガイドでは、アプリケーションでこの機能を実装するための手順と技術的な詳細を説明します。 ## フロー概要 \{#flow-overview} @@ -19,10 +19,10 @@ sequenceDiagram A ->> C: 招待するメールアドレスとロールを入力 C ->> L: Management API で組織招待を作成 - L -->> C: 招待 ID を返却 + L -->> C: 招待 ID を返す C ->> C: 招待 ID で招待リンクを作成 - C ->> L: 招待リンク付き招待メールの送信をリクエスト - L -->> U: 招待リンク付き招待メールを送信 + C ->> L: 招待リンク付きの招待メール送信をリクエスト + L -->> U: 招待リンク付きの招待メールを送信 U ->> C: 招待リンクをクリックしてランディングページへ遷移、
招待を承諾または拒否 C ->> L: Management API で招待ステータスを更新 ``` @@ -33,25 +33,25 @@ sequenceDiagram このガイドでは、典型的な組織ロールとして `admin` と `member` を作成します。 -`admin` ロールは組織内のすべてのリソースへのフルアクセス権限を持ち、`member` ロールは限定的なアクセス権限を持ちます。例えば、各ロールには次のような権限セットを割り当てることができます： +`admin` ロールは組織内のすべてのリソースへのフルアクセス権を持ち、`member` ロールはアクセスが制限されます。例えば、各ロールには以下のような権限セットを持たせることができます： - `admin` ロール: - `read:data` - 組織のすべてのデータリソースの読み取り権限 - `write:data` - 組織のすべてのデータリソースの書き込み権限 - `delete:data` - 組織のすべてのデータリソースの削除権限 - - `invite:member` - 組織へのメンバー招待権限 - - `manage:member` - 組織内メンバーの管理権限 - - `delete:member` - 組織からメンバーを削除する権限 + - `invite:member` - 組織へのメンバー招待 + - `manage:member` - 組織内メンバーの管理 + - `delete:member` - 組織からメンバーを削除 - `member` ロール: - `read:data` - 組織のすべてのデータリソースの読み取り権限 - `write:data` - 組織のすべてのデータリソースの書き込み権限 - - `invite:member` - 組織へのメンバー招待権限 + - `invite:member` - 組織へのメンバー招待 -これらは [Logto Console](https://cloud.logto.io/) で簡単に設定できます。また、[Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) を使ってプログラム的に組織ロールを作成することも可能です。 +これらは [Logto Console](https://cloud.logto.io/) で簡単に設定できます。また、[Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) を使ってプログラムで組織ロールを作成することも可能です。 ## メールコネクターの設定 \{#configure-your-email-connector} -招待はメールで送信されるため、[メールコネクター](/connectors/email-connectors) が正しく設定されていることを確認してください。招待メールを送信するには、[メールテンプレート](/connectors/email-connectors/email-templates#email-template-types) の使用タイプとして `OrganizationInvitation` を設定する必要があります。メール内容には組織（例：組織名、ロゴ）や招待者（例：招待者のメールアドレス、名前）の [変数](/connectors/email-connectors/email-templates#email-template-variables) を含めたり、[多言語テンプレート](/connectors/email-connectors/email-templates#email-template-localization) をカスタマイズしたりできます。 +招待はメールで送信されるため、[メールコネクター](/connectors/email-connectors) が正しく設定されていることを確認してください。招待を送信するには、[メールテンプレート](/connectors/email-connectors/email-templates#email-template-types) の使用タイプとして `OrganizationInvitation` を設定する必要があります。メール内容には組織（例：組織名、ロゴ）や招待者（例：招待者のメールアドレス、名前）の [変数](/connectors/email-connectors/email-templates#email-template-variables) を含めたり、[多言語テンプレート](/connectors/email-connectors/email-templates#email-template-localization) をカスタマイズすることもできます。 `OrganizationInvitation` 用のサンプルメールテンプレートは以下の通りです： @@ -68,7 +68,7 @@ sequenceDiagram :::note -Logto Cloud の組み込み「Logto email service」は現時点で `OrganizationInvitation` 使用タイプをサポートしていません。代わりに、ご自身のメールコネクター（例：Sendgrid）を設定し、`OrganizationInvitation` テンプレートを用意してください。 +Logto Cloud の組み込み「Logto email service」は現時点で `OrganizationInvitation` 使用タイプをサポートしていません。代わりに、メールコネクター（例：Sendgrid）を設定し、`OrganizationInvitation` テンプレートを用意してください。 ::: @@ -80,11 +80,25 @@ Logto Management API のセットアップがまだの場合は、[Management AP ::: -組織機能には招待関連の Management API が用意されています。これらの API を使って次のことができます： +### Cloud および OSS v1.27.0+ ユーザー向け \{#for-cloud-and-oss-v1-27-0-users} + +[マジックリンク（ワンタイムトークン）](/end-user-flows/one-time-token) 機能を使って招待フローを処理できます。 + +Management API を呼び出してワンタイムトークンを作成し、トークンと招待先メールアドレスでマジックリンクを作成します。 +このリンクを上記メールテンプレートの `{{link}}` プレースホルダーに挿入し、招待者にメールを送信します。 +例えば、`https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` のようなリンクを作成できます（招待 ID を含むものの代わりに）。 + +この方法が推奨されます。なぜなら、招待者がまだアカウントを持っていない場合でも、マジックリンクで自動的に登録されるためです。 + +詳細は [マジックリンク（ワンタイムトークン）](/end-user-flows/one-time-token) ページをご覧ください。 + +### OSS v1.26.0- ユーザー向け \{#for-oss-v1-26-0--users} + +組織機能に招待関連の Management API を用意しています。これらの API で以下が可能です： - `POST /api/organization-invitations` で組織招待を作成し、組織ロールを割り当てる -- `POST /api/organization-invitations/{id}/message` で招待メールを送信する - ※この API のペイロードには `link` プロパティがあり、招待 ID をもとに招待リンクを作成できます。例： +- `POST /api/organization-invitations/{id}/message` で招待メールを送信 + ※この API のペイロードには `link` プロパティがあり、招待 ID を使って招待リンクを作成できます。例： ```json { @@ -92,30 +106,30 @@ Logto Management API のセットアップがまだの場合は、[Management AP } ``` - 招待者が招待リンクからアプリケーションにアクセスした際のランディングページを実装する必要があります。 + 招待者が招待リンクからアプリケーションに遷移した際のランディングページを実装する必要があります。 -- `GET /api/organization-invitations` および `GET /api/organization-invitations/{id}` で全招待または特定の招待情報を取得 - ランディングページでこれらの API を使い、ユーザーが受け取った招待一覧や詳細を表示できます。 -- `PUT /api/organization-invitations/{id}/status` で招待の承諾または拒否を処理 +- `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` で全招待または特定の招待を取得 + ランディングページで、これらの API を使ってユーザーが受け取った招待一覧や詳細を表示できます。 +- `PUT /api/organization-invitations/{id}/status` で招待の承諾または拒否 この API でユーザーの招待への応答を処理します。 ## 組織ロールベースのアクセス制御 (RBAC) でユーザー権限を管理 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} -上記の設定により、メールで招待を送信し、招待されたユーザーは割り当てられたロールで組織に参加できます。 +上記の設定により、メールで招待を送信し、招待者は割り当てられたロールで組織に参加できるようになります。 異なる組織ロールを持つユーザーは、組織トークン内のスコープ（権限）が異なります。そのため、クライアントアプリやバックエンドサービスはこれらのスコープを確認し、表示する機能や許可される操作を判断してください。 ## 組織トークンのスコープ更新を処理する \{#handle-scope-updates-in-organization-tokens} :::note -このセクションは、組織テンプレートや認可 (Authorization) シナリオの高度な内容を含みます。これらの概念に不慣れな場合は、まず [認可 (Authorization)](/authorization) および [組織テンプレート](/authorization/organization-template) をご覧ください。 +このセクションは、組織テンプレートや認可 (Authorization) シナリオの高度な内容を含みます。これらの概念に不慣れな場合は、[認可 (Authorization)](/authorization) および [組織テンプレート](/authorization/organization-template) を先にご覧ください。 ::: 組織トークンのスコープ更新管理には以下が含まれます： ### 既存スコープの取り消し \{#revoking-existing-scopes} -例えば、管理者を一般メンバーに降格する場合、ユーザーからスコープを削除する必要があります。この場合、キャッシュされた組織トークンをクリアし、リフレッシュトークンで新しいトークンを取得するだけで十分です。縮小されたスコープは新しい組織トークンに即時反映されます。 +例えば、管理者を一般メンバーに降格する場合、ユーザーからスコープを削除する必要があります。この場合、キャッシュされた組織トークンをクリアし、リフレッシュトークンで新しいトークンを取得するだけで OK です。縮小されたスコープは新しい組織トークンに即時反映されます。 ### 新しいスコープの付与 \{#granting-new-scopes} @@ -123,9 +137,9 @@ Logto Management API のセットアップがまだの場合は、[Management AP #### 認証システムですでに定義済みの新しいスコープを付与 \{#grant-new-scopes-that-already-defined-in-your-auth-system} -スコープの取り消しと同様に、新たに付与するスコープがすでに認証サーバーに登録されている場合は、新しい組織トークンを発行するだけで新しいスコープが即時反映されます。 +スコープの取り消しと同様に、新たに付与されたスコープが認証サーバーにすでに登録されている場合は、新しい組織トークンを発行するだけで新しいスコープが即時反映されます。 -#### 認証システムに新たに追加されたスコープを付与 \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} +#### 認証システムに新たに導入されたスコープを付与 \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} この場合、ユーザーの組織トークンを更新するために再ログインまたは再同意プロセスをトリガーする必要があります（例：Logto SDK の `signIn` メソッドを呼び出す）。 @@ -135,7 +149,7 @@ Logto は Management API で組織内のユーザー権限をリアルタイム - `GET /api/organizations/{id}/users/{userId}/scopes` ([API リファレンス](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -ユーザーの組織トークン内のスコープとリアルタイム権限を比較し、昇格または降格があったかを判断できます。 +ユーザーの組織トークン内のスコープとリアルタイム権限を比較し、昇格または降格されたかどうかを判断できます。 - 降格された場合は、キャッシュされた組織トークンをクリアするだけで、SDK が自動的に新しいスコープでトークンを発行します。 @@ -143,7 +157,7 @@ Logto は Management API で組織内のユーザー権限をリアルタイム const { clearAccessToken } = useLogto(); ... - // 取得したリアルタイムスコープが組織トークンのスコープより少ない場合 + // 取得したリアルタイムスコープが組織トークンスコープより少ない場合 await clearAccessToken(); ``` @@ -155,7 +169,7 @@ Logto は Management API で組織内のユーザー権限をリアルタイム const { clearAllTokens, signIn } = useLogto(); ... - // 取得したリアルタイムスコープが組織トークンのスコープより多い場合 + // 取得したリアルタイムスコープが組織トークンスコープより新しいスコープを含む場合 await clearAllTokens(); signIn({ redirectUri: '', @@ -163,7 +177,7 @@ Logto は Management API で組織内のユーザー権限をリアルタイム }); ``` - 上記コードは同意画面へのページ遷移をトリガーし、同意後にアプリへ自動リダイレクトされ、ユーザーの組織トークンに更新されたスコープが反映されます。 + 上記コードは同意画面へのページ遷移をトリガーし、ユーザーの組織トークンに更新されたスコープを付与してアプリに自動リダイレクトします。 ## 関連リソース \{#related-resources} 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 5a2a865d3eb..0dac47840db 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -1,18 +1,18 @@ --- -description: 사용자 관리를 위한 Account API 사용 방법을 알아보세요 +description: Account API를 사용하여 사용자를 관리하는 방법을 알아보세요 sidebar_position: 2 --- -# Account API로 계정 설정하기 +# Account API로 계정 설정 관리하기 -## Logto Account API란 무엇인가요 \{#what-is-logto-account-api} +## Logto Account API란? \{#what-is-logto-account-api} -Logto Account API는 최종 사용자가 Management API를 거치지 않고 직접 API에 접근할 수 있는 포괄적인 API 세트입니다. 주요 특징은 다음과 같습니다: +Logto Account API는 최종 사용자가 Management API를 거치지 않고 직접 API에 접근할 수 있도록 해주는 포괄적인 API 세트입니다. 주요 특징은 다음과 같습니다: -- 직접 접근: Account API는 최종 사용자가 자신의 계정 프로필에 직접 접근하고 관리할 수 있도록 하며, Management API의 중계를 필요로 하지 않습니다. -- 사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호와 같은 아이덴티티 정보를 업데이트하고 소셜 연결을 관리할 수 있는 기능을 포함하여 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원은 곧 제공될 예정입니다. -- 글로벌 접근 제어: 관리자는 접근 설정을 전역적으로 완전히 제어할 수 있으며, 각 필드를 사용자 정의할 수 있습니다. -- 원활한 인가 (Authorization): 인가가 그 어느 때보다 쉬워졌습니다! 단순히 `client.getAccessToken()`을 사용하여 OP (Logto)를 위한 불투명 토큰을 얻고, 이를 `Bearer ` 형식으로 Authorization 헤더에 첨부하세요. +- 직접 접근: Account API는 최종 사용자가 Management API의 중계 없이 자신의 계정 프로필에 직접 접근하고 관리할 수 있도록 합니다. +- 사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호 등 아이덴티티 정보를 업데이트하고, 소셜 연결을 관리하는 등 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원도 곧 제공될 예정입니다. +- 글로벌 접근 제어: 관리자는 접근 설정을 전역적으로 완전히 제어할 수 있으며, 각 필드를 맞춤 설정할 수 있습니다. +- 원활한 인가 (Authorization): 인가가 그 어느 때보다 쉬워졌습니다! `client.getAccessToken()`을 사용하여 OP (Logto)용 불투명 토큰 (Opaque token)을 얻고, 이를 Authorization 헤더에 `Bearer ` 형식으로 첨부하세요. Logto Account API를 사용하면 Logto와 완전히 통합된 프로필 페이지와 같은 맞춤형 계정 관리 시스템을 구축할 수 있습니다. @@ -21,19 +21,19 @@ Logto Account API를 사용하면 Logto와 완전히 통합된 프로필 페이 - 사용자 프로필 조회 - 사용자 프로필 업데이트 - 사용자 비밀번호 업데이트 -- 이메일, 전화번호 및 소셜 연결을 포함한 사용자 아이덴티티 업데이트 +- 이메일, 전화번호, 소셜 연결 등 사용자 아이덴티티 업데이트 -사용 가능한 API에 대해 더 알고 싶다면 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 및 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications)를 방문하세요. +사용 가능한 API에 대해 더 알아보려면 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 및 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications)를 방문하세요. :::note -다음 설정을 위한 전용 Account API는 곧 제공될 예정입니다: MFA, SSO, 사용자 정의 데이터, 계정 삭제. 그동안 Logto Management API를 사용하여 이러한 기능을 구현할 수 있습니다. 자세한 내용은 [Management API로 계정 설정하기](/end-user-flows/account-settings/by-management-api)를 참조하세요. +다음 설정을 위한 전용 Account API가 곧 제공될 예정입니다: MFA, SSO, 사용자 커스텀 데이터, 계정 삭제. 그동안에는 Logto Management API를 사용하여 이러한 기능을 구현할 수 있습니다. 자세한 내용은 [Management API로 계정 설정 관리하기](/end-user-flows/account-settings/by-management-api)를 참고하세요. ::: ## 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를 활성화 또는 비활성화하고, 필드를 맞춤 설정할 수 있습니다. 예시 요청: @@ -44,32 +44,32 @@ 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`: 프로필 필드, 하위 필드를 포함. -- `username`: 사용자 이름 필드. -- `email`: 이메일 필드. -- `phone`: 전화번호 필드. -- `password`: 비밀번호 필드, 조회 시 사용자가 비밀번호를 설정한 경우 `true`, 그렇지 않으면 `false`를 반환합니다. -- `social`: 소셜 연결. +- `name`: 이름 필드 +- `avatar`: 아바타 필드 +- `profile`: 프로필 필드 (하위 필드 포함) +- `username`: 사용자명 필드 +- `email`: 이메일 필드 +- `phone`: 전화번호 필드 +- `password`: 비밀번호 필드 (조회 시, 사용자가 비밀번호를 설정했다면 `true`, 아니면 `false` 반환) +- `social`: 소셜 연결 -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} -### 액세스 토큰 가져오기 \{#fetch-an-access-token} +### 액세스 토큰 (Access token) 가져오기 \{#fetch-an-access-token} -애플리케이션에 SDK를 설정한 후, `client.getAccessToken()` 메서드를 사용하여 액세스 토큰을 가져올 수 있습니다. 이 토큰은 Account API에 접근하는 데 사용할 수 있는 불투명 토큰입니다. +애플리케이션에 SDK를 설정한 후, `client.getAccessToken()` 메서드를 사용하여 액세스 토큰을 가져올 수 있습니다. 이 토큰은 Account API에 접근할 수 있는 불투명 토큰 (Opaque token)입니다. -공식 SDK를 사용하지 않는 경우, 액세스 토큰 발급 요청을 `/oidc/token`으로 할 때 `resource`를 비워야 합니다. +공식 SDK를 사용하지 않는 경우, 액세스 토큰 발급 요청 시 `/oidc/token`의 `resource`를 비워야 합니다. -### 액세스 토큰을 사용하여 Account API 접근하기 \{#access-account-api-using-access-token} +### 액세스 토큰으로 Account API 접근하기 \{#access-account-api-using-access-token} -Account API와 상호작용할 때는 HTTP 헤더의 `Authorization` 필드에 Bearer 형식 (`Bearer YOUR_TOKEN`)으로 액세스 토큰을 넣어야 합니다. +Account API와 상호작용할 때는 액세스 토큰을 HTTP 헤더의 `Authorization` 필드에 Bearer 형식(`Bearer YOUR_TOKEN`)으로 넣어야 합니다. -사용자 계정 정보를 얻는 예시: +사용자 계정 정보를 가져오는 예시: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -85,7 +85,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -응답 본문은 다음과 같습니다: +응답 본문 예시: ```json { @@ -96,13 +96,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -응답 필드는 계정 센터 설정에 따라 다를 수 있습니다. +응답 필드는 계정 센터 설정에 따라 달라질 수 있습니다. ### 기본 계정 정보 업데이트 \{#update-basic-account-information} -기본 계정 정보에는 사용자 이름, 이름, 아바타, 프로필이 포함됩니다. +기본 계정 정보에는 사용자명, 이름, 아바타, 프로필이 포함됩니다. -사용자 이름, 이름, 아바타를 업데이트하려면 `PATCH /api/my-account` 엔드포인트를 사용할 수 있습니다. +사용자명, 이름, 아바타를 업데이트하려면 `PATCH /api/my-account` 엔드포인트를 사용하세요. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -111,7 +111,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -프로필을 업데이트하려면 `PATCH /api/my-account/profile` 엔드포인트를 사용할 수 있습니다. +프로필을 업데이트하려면 `PATCH /api/my-account/profile` 엔드포인트를 사용하세요. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -120,17 +120,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 식별자 및 기타 민감한 정보 관리 \{#manage-identifiers-and-other-sensitive-information} +## 식별자 및 기타 민감 정보 관리 \{#manage-identifiers-and-other-sensitive-information} -보안상의 이유로, Account API는 식별자 및 기타 민감한 정보를 포함하는 작업에 대해 추가적인 인가 (Authorization) 계층을 요구합니다. +보안상의 이유로, Account API에서 식별자 및 기타 민감 정보와 관련된 작업에는 추가 인가 (Authorization) 절차가 필요합니다. -### 인증 기록 ID 가져오기 \{#get-a-verification-record-id} +### 인증 기록 ID(verification record id) 얻기 \{#get-a-verification-record-id} -먼저, 인증 기록 ID를 가져와야 하며, 이는 식별자를 업데이트할 때 사용자의 아이덴티티를 확인하는 데 사용됩니다. +먼저 인증 기록 ID를 얻어야 하며, 이는 식별자 업데이트 시 사용자의 신원을 확인하는 데 사용됩니다. -인증 기록 ID를 얻으려면 사용자의 비밀번호를 확인하거나 사용자의 이메일 또는 전화번호로 인증 코드를 보내야 합니다. +인증 기록 ID를 얻으려면 사용자의 비밀번호를 검증하거나, 이메일 또는 전화번호로 인증 코드를 전송할 수 있습니다. -#### 사용자의 비밀번호 확인 \{#verify-the-users-password} +#### 사용자의 비밀번호 검증 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -응답 본문은 다음과 같습니다: +응답 본문 예시: ```json { @@ -148,13 +148,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 사용자의 이메일 또는 전화번호로 인증 코드 보내기 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 이메일 또는 전화번호로 인증 코드 전송하여 검증 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/) 또는 [SMS 커넥터](/connectors/sms-connectors/)를 구성하고, `UserPermissionValidation` 템플릿이 구성되어 있는지 확인해야 합니다. +이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/) 또는 [SMS 커넥터](/connectors/sms-connectors/)를 구성하고, `UserPermissionValidation` 템플릿이 설정되어 있어야 합니다. ::: -이메일을 예로 들어, 새로운 인증 코드를 요청하고 인증 기록 ID를 얻습니다: +이메일을 예로 들어, 새 인증 코드를 요청하고 인증 기록 ID를 받으세요: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -응답 본문은 다음과 같습니다: +응답 본문 예시: ```json { @@ -175,27 +175,27 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ 인증 코드를 받은 후, 이를 사용하여 인증 기록의 인증 상태를 업데이트할 수 있습니다. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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를 첨부해야 합니다. +사용자의 식별자를 업데이트하는 요청을 보낼 때는, 요청 헤더의 `logto-verification-id` 필드에 인증 기록 ID를 첨부해야 합니다. -### 새로운 이메일 업데이트 또는 연결 \{#update-or-link-new-email} +### 새 이메일 업데이트 또는 연결 \{#update-or-link-new-email} :::note -이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 구성되어 있는지 확인해야 합니다. +이 방법을 사용하려면 [이메일 커넥터](/connectors/email-connectors/)를 구성하고, `BindNewIdentifier` 템플릿이 설정되어 있어야 합니다. ::: -새로운 이메일을 업데이트하거나 연결하려면, 먼저 이메일 소유권을 증명해야 합니다. +새 이메일을 업데이트하거나 연결하려면, 먼저 해당 이메일의 소유권을 증명해야 합니다. -`POST /api/verifications/verification-code` 엔드포인트를 호출하여 인증 코드를 요청합니다. +`POST /api/verifications/verification-code` 엔드포인트를 호출하여 인증 코드를 요청하세요. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -응답에서 `verificationId`를 찾고, 이메일로 인증 코드를 받아 이를 사용하여 이메일을 인증합니다. +응답에서 `verificationId`를 확인하고, 이메일로 받은 인증 코드를 사용하여 이메일을 검증하세요. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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 \ @@ -223,9 +223,9 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --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 \ @@ -236,14 +236,14 @@ 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} +### 새 소셜 연결 추가 \{#link-a-new-social-connection} -새로운 소셜 연결을 추가하려면, 먼저 인가 URL을 요청해야 합니다: +새 소셜 연결을 추가하려면, 먼저 인가 (Authorization) URL을 요청해야 합니다: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`: [소셜 커넥터](/connectors/social-connectors/)의 ID. -- `redirectUri`: 사용자가 애플리케이션을 인가한 후 리디렉션되는 URI, 이 URL에 웹 페이지를 호스팅하고 콜백을 캡처해야 합니다. -- `state`: 사용자가 애플리케이션을 인가한 후 반환되는 상태, CSRF 공격을 방지하기 위해 사용되는 임의의 문자열입니다. +- `connectorId`: [소셜 커넥터](/connectors/social-connectors/)의 ID +- `redirectUri`: 사용자가 애플리케이션을 인가한 후 리디렉션되는 URI. 이 URL에 웹 페이지를 호스팅하고 콜백을 수신해야 합니다. +- `state`: 사용자가 애플리케이션을 인가한 후 반환되는 상태 값. CSRF 공격 방지를 위해 사용하는 임의의 문자열입니다. -응답에서 `verificationRecordId`를 찾을 수 있으며, 나중에 사용할 수 있도록 보관하세요. +응답에서 `verificationRecordId`를 확인하고, 이후에 사용할 수 있도록 보관하세요. -사용자가 애플리케이션을 인가한 후, `redirectUri`에서 `state` 매개변수와 함께 콜백을 받게 됩니다. 그런 다음 `POST /api/verifications/social/verify` 엔드포인트를 사용하여 소셜 연결을 확인할 수 있습니다. +사용자가 애플리케이션을 인가하면, `redirectUri`로 `state` 파라미터와 함께 콜백을 받게 됩니다. 그런 다음 `POST /api/verifications/social/verify` 엔드포인트를 사용하여 소셜 연결을 검증할 수 있습니다. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -267,7 +267,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ --data-raw '{"connectorData":"...","verificationRecordId":"..."}' ``` -`connectorData`는 사용자가 애플리케이션을 인가한 후 소셜 커넥터가 반환한 데이터로, 콜백 페이지에서 `redirectUri`의 쿼리 매개변수를 구문 분석하여 `connectorData` 필드의 값으로 JSON으로 래핑해야 합니다. +`connectorData`는 사용자가 애플리케이션을 인가한 후 소셜 커넥터에서 반환된 데이터입니다. 콜백 페이지에서 `redirectUri`의 쿼리 파라미터를 파싱하여 JSON으로 감싸 `connectorData` 필드 값으로 전달해야 합니다. 마지막으로, `POST /api/my-account/identities` 엔드포인트를 사용하여 소셜 연결을 추가할 수 있습니다. @@ -279,9 +279,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ --data-raw '{"newIdentifierVerificationRecordId":"..."}' ``` -### 소셜 연결 제거 \{#remove-a-social-connection} +### 소셜 연결 삭제 \{#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] \ diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index ccdb20f78f1..b1bf352c31f 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,7 +4,7 @@ sidebar_position: 2 # 조직 구성원 초대하기 -다중 조직 애플리케이션에서 흔히 요구되는 기능 중 하나는 조직에 구성원을 초대하는 것입니다. 이 가이드에서는 애플리케이션에서 이 기능을 구현하는 단계와 기술적 세부 사항을 안내합니다. +다중 조직 애플리케이션에서 일반적으로 요구되는 기능 중 하나는 조직에 구성원을 초대하는 것입니다. 이 가이드에서는 애플리케이션에서 이 기능을 구현하는 단계와 기술적 세부 사항을 안내합니다. ## 흐름 개요 \{#flow-overview} @@ -17,7 +17,7 @@ sequenceDiagram Participant C as 귀하의 다중 조직 앱 Participant L as Logto - A ->> C: 초대받을 이메일 및 역할 입력 + A ->> C: 초대받을 이메일과 역할 입력 C ->> L: Management API로 조직 초대 생성 L -->> C: 초대 ID 반환 C ->> C: 초대 ID로 초대 링크 작성 @@ -29,11 +29,11 @@ sequenceDiagram ## 조직 역할 생성하기 \{#create-organization-roles} -조직에 구성원을 초대하기 전에, 조직 역할을 생성해야 합니다. 조직 역할과 권한에 대해 더 알고 싶다면 [조직 템플릿](/authorization/organization-template)을 확인하세요. +구성원을 조직에 초대하기 전에, 조직 역할을 생성해야 합니다. 조직 역할과 권한에 대해 더 알고 싶다면 [조직 템플릿](/authorization/organization-template)을 확인하세요. -이 가이드에서는 `admin`과 `member`라는 두 가지 대표적인 조직 역할을 생성해보겠습니다. +이 가이드에서는 `admin`과 `member`라는 두 가지 일반적인 조직 역할을 생성해보겠습니다. -`admin` 역할은 조직 내 모든 리소스에 대한 전체 접근 권한을 가지며, `member` 역할은 제한된 접근 권한을 가집니다. 예를 들어, 각 역할은 다음과 같은 권한 집합을 가질 수 있습니다: +`admin` 역할은 조직 내 모든 리소스에 대한 전체 접근 권한을 가지며, `member` 역할은 제한된 접근 권한을 가집니다. 예를 들어, 각 역할은 다음과 같은 권한 세트를 가질 수 있습니다: - `admin` 역할: - `read:data` - 모든 조직 데이터 리소스 읽기 권한 @@ -51,7 +51,7 @@ sequenceDiagram ## 이메일 커넥터 구성하기 \{#configure-your-email-connector} -초대장은 이메일을 통해 전송되므로, [이메일 커넥터](/connectors/email-connectors)가 올바르게 구성되어 있는지 확인하세요. 초대장을 보내려면 [이메일 템플릿](/connectors/email-connectors/email-templates#email-template-types) 사용 유형 중 `OrganizationInvitation`을 설정해야 합니다. 또한 조직(예: 조직명, 로고) 및 초대자(예: 초대자 이메일, 이름) [변수](/connectors/email-connectors/email-templates#email-template-variables)를 내용에 포함하거나, 필요에 따라 [다국어 템플릿](/connectors/email-connectors/email-templates#email-template-localization)을 커스터마이즈할 수 있습니다. +초대는 이메일을 통해 전송되므로, [이메일 커넥터](/connectors/email-connectors)가 올바르게 구성되어 있는지 확인하세요. 초대를 보내려면 [이메일 템플릿](/connectors/email-connectors/email-templates#email-template-types) 사용 유형 중 `OrganizationInvitation`을 구성해야 합니다. 이메일 내용에는 조직(예: 조직 이름, 로고) 및 초대자(예: 초대자 이메일, 이름) [변수](/connectors/email-connectors/email-templates#email-template-variables)를 포함하거나, 필요에 따라 [다국어 템플릿](/connectors/email-connectors/email-templates#email-template-localization)을 커스터마이즈할 수 있습니다. `OrganizationInvitation` 사용 유형의 샘플 이메일 템플릿은 아래와 같습니다: @@ -64,7 +64,7 @@ sequenceDiagram } ``` -이메일 내용의 `{{link}}` 플레이스홀더는 이메일 발송 시 실제 초대 링크로 대체됩니다. 이 가이드에서는 `https://your-app.com/invitation/accept/{your-invitation-id}`와 같은 형태라고 가정합니다. +이메일 내용의 `{{link}}` 자리표시는 이메일 전송 시 실제 초대 링크로 대체됩니다. 이 가이드에서는 `https://your-app.com/invitation/accept/{your-invitation-id}`와 같은 링크를 사용한다고 가정합니다. :::note @@ -80,11 +80,25 @@ Logto Cloud의 내장 "Logto email service"는 현재 `OrganizationInvitation` ::: -조직 기능에는 초대 관련 Management API가 제공됩니다. 이 API들을 통해 다음 작업을 할 수 있습니다: +### Cloud 및 OSS v1.27.0+ 사용자 \{#for-cloud-and-oss-v1-27-0-users} -- `POST /api/organization-invitations`로 조직 역할이 할당된 조직 초대 생성 -- `POST /api/organization-invitations/{id}/message`로 초대받는 사람에게 이메일로 조직 초대 전송 - 참고: 이 API의 payload에는 `link` 속성이 지원되므로, 초대 ID를 기반으로 초대 링크를 작성할 수 있습니다. 예시: +이제 [매직 링크 (일회성 토큰)](/end-user-flows/one-time-token) 기능을 사용하여 초대 흐름을 처리할 수 있습니다. + +Management API를 호출하여 일회성 토큰을 생성하고, 해당 토큰과 초대받을 이메일로 초대 매직 링크를 작성하세요. +위 이메일 템플릿의 `{{link}}` 자리에 이 링크를 삽입하여 초대자에게 이메일을 발송하면 됩니다. +초대 ID 대신 `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}`와 같은 링크를 사용할 수 있습니다. + +이 방식은 초대받은 사용자가 아직 계정이 없는 경우에도 매직 링크로 자동 등록되므로 권장됩니다. + +자세한 내용은 [매직 링크 (일회성 토큰)](/end-user-flows/one-time-token) 페이지를 참고하세요. + +### OSS v1.26.0- 사용자 \{#for-oss-v1-26-0--users} + +조직 기능에서 초대 관련 Management API 세트를 제공합니다. 이 API로 다음 작업을 할 수 있습니다: + +- `POST /api/organization-invitations` 조직 역할이 할당된 조직 초대 생성 +- `POST /api/organization-invitations/{id}/message` 초대받을 사람에게 이메일로 조직 초대 전송 + 참고: 이 API의 payload에는 `link` 속성이 있으며, 초대 ID를 기반으로 초대 링크를 작성할 수 있습니다. 예시: ```json { @@ -92,52 +106,52 @@ Logto Cloud의 내장 "Logto email service"는 현재 `OrganizationInvitation` } ``` - 이에 따라, 초대받는 사람이 초대 링크를 통해 애플리케이션에 접근할 때 랜딩 페이지를 구현해야 합니다. + 이에 따라, 초대받은 사용자가 초대 링크를 통해 애플리케이션에 접근할 때 사용할 랜딩 페이지를 구현해야 합니다. -- `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}`로 모든 초대장 또는 특정 초대장(ID 기준) 조회 - 랜딩 페이지에서 이 API들을 사용하여 사용자가 받은 모든 초대장 또는 특정 초대장 정보를 표시할 수 있습니다. -- `PUT /api/organization-invitations/{id}/status`로 초대 상태를 업데이트하여 초대를 수락 또는 거절 - 사용자의 초대 응답을 처리할 때 이 API를 사용하세요. +- `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` 모든 초대 또는 특정 초대(초대 ID 기준) 조회 + 랜딩 페이지에서 이 API를 사용해 사용자가 받은 모든 초대 또는 특정 초대의 상세 정보를 표시할 수 있습니다. +- `PUT /api/organization-invitations/{id}/status` 초대 상태 업데이트로 초대 수락 또는 거절 + 이 API를 사용해 사용자의 초대 응답을 처리하세요. -## 조직 역할 기반 접근 제어(RBAC)로 사용자 권한 관리하기 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +## 조직 역할 기반 접근 제어 (RBAC)로 사용자 권한 관리하기 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} -위의 설정을 마치면, 이메일로 초대장을 보내고 초대받은 사용자가 할당된 역할로 조직에 참여할 수 있습니다. +위 설정을 완료하면 이메일로 초대를 보내고, 초대받은 사용자가 할당된 역할로 조직에 참여할 수 있습니다. -조직 내 서로 다른 역할을 가진 사용자는 조직 토큰에 서로 다른 스코프(권한)를 가지게 됩니다. 따라서 클라이언트 앱과 백엔드 서비스 모두 이 스코프를 확인하여 노출되는 기능과 허용되는 동작을 결정해야 합니다. +서로 다른 조직 역할을 가진 사용자는 조직 토큰 내에서 서로 다른 스코프(권한)를 갖게 됩니다. 따라서 클라이언트 앱과 백엔드 서비스 모두 이 스코프를 확인하여 노출 기능과 허용 작업을 결정해야 합니다. ## 조직 토큰의 스코프 업데이트 처리하기 \{#handle-scope-updates-in-organization-tokens} :::note -이 섹션은 조직 템플릿 및 인가(Authorization) 시나리오에 대한 고급 주제를 다룹니다. 해당 개념에 익숙하지 않다면 먼저 [인가 (Authorization)](/authorization) 및 [조직 템플릿](/authorization/organization-template)을 읽어보세요. +이 섹션은 조직 템플릿 및 인가 시나리오에 대한 고급 주제를 다룹니다. 해당 개념에 익숙하지 않다면 [인가 (Authorization)](/authorization) 및 [조직 템플릿](/authorization/organization-template)을 먼저 읽어보세요. ::: 조직 토큰의 스코프 업데이트 관리는 다음과 같습니다: -### 기존 스코프 취소(Revoking existing scopes) \{#revoking-existing-scopes} +### 기존 스코프 철회하기 \{#revoking-existing-scopes} -예를 들어, 관리자를 일반 멤버로 강등할 경우 사용자에게서 스코프를 제거해야 합니다. 이 경우, 캐시된 조직 토큰을 단순히 삭제하고 리프레시 토큰으로 새 토큰을 받아오면 됩니다. 축소된 스코프는 새로 발급된 조직 토큰에 즉시 반영됩니다. +예를 들어, 관리자를 일반 멤버로 강등하면 해당 사용자의 스코프가 제거되어야 합니다. 이 경우, 캐시된 조직 토큰을 단순히 삭제하고 리프레시 토큰으로 새 토큰을 받아오면 됩니다. 축소된 스코프는 새로 발급된 조직 토큰에 즉시 반영됩니다. -### 새로운 스코프 부여(Granting new scopes) \{#granting-new-scopes} +### 새 스코프 부여하기 \{#granting-new-scopes} 이 경우는 두 가지 시나리오로 나눌 수 있습니다: #### 인증 시스템에 이미 정의된 새 스코프 부여 \{#grant-new-scopes-that-already-defined-in-your-auth-system} -스코프 취소와 유사하게, 새로 부여된 스코프가 이미 인증 서버에 등록되어 있다면, 새 조직 토큰을 발급받기만 하면 새 스코프가 즉시 반영됩니다. +스코프 철회와 유사하게, 새로 부여된 스코프가 이미 인증 서버에 등록되어 있다면, 새 조직 토큰을 발급받기만 하면 새 스코프가 즉시 반영됩니다. #### 인증 시스템에 새로 도입된 스코프 부여 \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의(consent) 과정을 트리거해야 합니다. 예: Logto SDK의 `signIn` 메서드 호출. +이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의 과정을 트리거해야 합니다. 예: Logto SDK의 `signIn` 메서드 호출. -### 실시간 권한 체크 및 조직 토큰 업데이트 구현하기 \{#implement-real-time-permission-check-and-update-organization-token} +### 실시간 권한 확인 및 조직 토큰 업데이트 구현하기 \{#implement-real-time-permission-check-and-update-organization-token} Logto는 조직 내 사용자의 실시간 권한을 조회할 수 있는 Management API를 제공합니다. - `GET /api/organizations/{id}/users/{userId}/scopes` ([API 참조](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -이후 사용자의 조직 토큰 내 스코프와 실시간 권한을 비교하여 승격 또는 강등 여부를 판단할 수 있습니다. +이 API로 사용자의 조직 토큰 내 스코프와 실시간 권한을 비교하여 승격 또는 강등 여부를 판단할 수 있습니다. -- 강등된 경우, 캐시된 조직 토큰을 삭제하면 SDK가 자동으로 스코프가 업데이트된 새 토큰을 발급합니다. +- 강등된 경우, 캐시된 조직 토큰을 삭제하면 SDK가 자동으로 업데이트된 스코프로 새 토큰을 발급합니다. ```ts const { clearAccessToken } = useLogto(); @@ -147,9 +161,9 @@ Logto는 조직 내 사용자의 실시간 권한을 조회할 수 있는 Manage await clearAccessToken(); ``` - 이 과정에는 재로그인 또는 재동의가 필요하지 않습니다. Logto SDK가 자동으로 새 조직 토큰을 발급합니다. + 이 과정에서는 재로그인 또는 재동의가 필요하지 않습니다. Logto SDK가 자동으로 새 조직 토큰을 발급합니다. -- 인증 시스템에 새 스코프가 도입된 경우, 재로그인 또는 재동의 과정을 트리거하여 조직 토큰을 업데이트해야 합니다. React SDK 예시: +- 인증 시스템에 새 스코프가 도입된 경우, 재로그인 또는 재동의 과정을 트리거하여 사용자의 조직 토큰을 업데이트해야 합니다. React SDK 예시: ```ts const { clearAllTokens, signIn } = useLogto(); @@ -163,7 +177,7 @@ Logto는 조직 내 사용자의 실시간 권한을 조회할 수 있는 Manage }); ``` - 위 코드는 동의 화면(consent screen)으로 페이지 이동을 트리거하고, 동의 후 자동으로 앱으로 리디렉션되어 조직 토큰의 스코프가 업데이트됩니다. + 위 코드는 동의 화면으로 페이지 이동을 트리거하고, 사용자의 조직 토큰에 업데이트된 스코프가 반영된 상태로 앱으로 자동 리디렉션됩니다. ## 관련 리소스 \{#related-resources} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx index 55d91502978..588ad338d61 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: Aprenda a usar a Account API para gerenciar usuários +description: Saiba como usar a Account API para gerenciar usuários sidebar_position: 2 --- @@ -7,35 +7,35 @@ sidebar_position: 2 ## O que é a Logto Account API \{#what-is-logto-account-api} -A Logto Account API é um conjunto abrangente de APIs que oferece aos usuários finais acesso direto à API sem a necessidade de passar pela Management API, aqui estão os destaques: +A Logto Account API é um conjunto abrangente de APIs que oferece aos usuários finais acesso direto via API sem a necessidade de passar pela Management API. Aqui estão os destaques: -- Acesso direto: A Account API capacita os usuários finais a acessar e gerenciar diretamente seu próprio perfil de conta sem exigir o uso da Management API. -- Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar completamente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, bem como gerenciar conexões sociais. Suporte para MFA e SSO em breve. +- Acesso direto: A Account API permite que os usuários finais acessem e gerenciem diretamente o próprio perfil de conta sem exigir o repasse pela Management API. +- Gerenciamento de perfil de usuário e identidades: Os usuários podem gerenciar totalmente seus perfis e configurações de segurança, incluindo a capacidade de atualizar informações de identidade como email, telefone e senha, além de gerenciar conexões sociais. Suporte para MFA e SSO em breve. - Controle de acesso global: O administrador tem controle total e global sobre as configurações de acesso, podendo personalizar cada campo. -- Autorização sem complicações: Autorizar é mais fácil do que nunca! Basta usar `client.getAccessToken()` para obter um token de acesso opaco para OP (Logto) e anexá-lo ao cabeçalho de autorização como `Bearer `. +- Autorização sem atrito: Autorizar nunca foi tão fácil! Basta usar `client.getAccessToken()` para obter um token opaco de acesso para OP (Logto) e anexá-lo ao cabeçalho Authorization como `Bearer `. -Com a Logto Account API, você pode construir um sistema de gerenciamento de contas personalizado, como uma página de perfil totalmente integrada com o Logto. +Com a Logto Account API, você pode construir um sistema personalizado de gerenciamento de contas, como uma página de perfil totalmente integrada ao Logto. Alguns usos frequentes estão listados abaixo: -- Recuperar perfil de usuário -- Atualizar perfil de usuário +- Recuperar perfil do usuário +- Atualizar perfil do usuário - Atualizar senha do usuário - Atualizar identidades do usuário, incluindo email, telefone e conexões sociais 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 estão chegando em breve: MFA, SSO, Dados personalizados (usuário) e Exclusão de conta. Enquanto isso, você pode implementar esses recursos usando as Logto Management APIs. Veja [Configurações de conta pela Management API](/end-user-flows/account-settings/by-management-api) para mais detalhes. +APIs dedicadas para as seguintes configurações estão chegando 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. ::: ## Como habilitar a Account API \{#how-to-enable-account-api} -Por padrão, a Account API está desativada. Para habilitá-la, você precisa usar a [Management API](/integrate-logto/interact-with-management-api) para atualizar as configurações globais. +Por padrão, a Account API está desabilitada. Para habilitá-la, você precisa usar a [Management API](/integrate-logto/interact-with-management-api) para atualizar as configurações globais. -O endpoint da API `/api/account-center` pode ser usado para recuperar e atualizar as configurações do centro de contas, você pode usá-lo para habilitar ou desabilitar a Account API e personalizar os campos. +O endpoint `/api/account-center` pode ser usado para recuperar e atualizar as configurações do centro de contas. Você pode usá-lo para habilitar ou desabilitar a Account API e personalizar os campos. -Exemplo de solicitação: +Exemplo de requisição: ```bash curl -X PATCH https://[tenant-id].logto.app/api/account-center \ @@ -44,32 +44,32 @@ 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 de nome. -- `avatar`: O campo de avatar. -- `profile`: O campo de perfil, incluindo seus subcampos. -- `username`: O campo de nome de usuário. -- `email`: O campo de email. -- `phone`: O campo de telefone. -- `password`: O campo de senha, ao obter, retornará `true` se o usuário tiver definido uma senha, caso contrário, `false`. +- `name`: O campo nome. +- `avatar`: O campo avatar. +- `profile`: O campo perfil, incluindo seus subcampos. +- `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 definido uma senha, caso contrário, `false`. - `social`: Conexões sociais. -Saiba mais sobre os detalhes da API na [Referência da Logto Management API](https://openapi.logto.io/group/endpoint-account-center). +Saiba mais sobre os detalhes da API em [Referência da Logto Management API](https://openapi.logto.io/group/endpoint-account-center). ## Como acessar a Account API \{#how-to-access-account-api} -### Obter um token de acesso \{#fetch-an-access-token} +### 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 obter 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`. +Se você não estiver usando o SDK oficial, deve definir o `resource` como vazio na solicitação de concessão de token de acesso para `/oidc/token`. ### Acessar a Account API usando o token de acesso \{#access-account-api-using-access-token} Você deve colocar o token de acesso no campo `Authorization` dos cabeçalhos HTTP com o formato Bearer (`Bearer YOUR_TOKEN`) ao interagir com a Account API. -Um exemplo para obter as informações da conta do usuário: +Exemplo para obter as informações da conta do usuário: ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -85,7 +85,7 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -O corpo da resposta seria assim: +O corpo da resposta será semelhante a: ```json { @@ -96,13 +96,13 @@ O corpo da resposta seria assim: } ``` -Os campos de resposta podem variar dependendo das configurações do centro de contas. +Os campos da resposta podem variar dependendo das configurações do centro de contas. ### Atualizar informações básicas da conta \{#update-basic-account-information} -As informações básicas da conta incluem o nome de usuário, nome, avatar e perfil. +As informações básicas da conta incluem nome de usuário, nome, avatar e perfil. -Para atualizar o nome de usuário, nome e avatar, você pode usar o endpoint `PATCH /api/my-account`. +Para atualizar nome de usuário, nome e avatar, você pode usar o endpoint `PATCH /api/my-account`. ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -122,11 +122,11 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ ## Gerenciar identificadores e outras informações sensíveis \{#manage-identifiers-and-other-sensitive-information} -Por razões de segurança, a Account API requer outra camada de autorização para as operações que envolvem identificadores e outras informações sensíveis. +Por motivos de segurança, a Account API exige uma camada adicional de autorização para operações que envolvem identificadores e outras informações sensíveis. ### 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, que 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. @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -O corpo da resposta seria assim: +O corpo da resposta será semelhante a: ```json { @@ -151,10 +151,10 @@ O corpo da resposta seria assim: #### Verificar enviando um código de verificação para o email ou telefone do usuário \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -Para usar este método, você precisa [configurar o conector de email](/connectors/email-connectors/) ou [conector de SMS](/connectors/sms-connectors/), e certificar-se de que o template `UserPermissionValidation` está configurado. +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. ::: -Tomando o email como exemplo, solicite um novo código de verificação e obtenha o id de registro de verificação: +Usando email como exemplo, solicite um novo código de verificação e obtenha o id de registro de verificação: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -O corpo da resposta seria assim: +O corpo da resposta será semelhante a: ```json { @@ -172,28 +172,28 @@ O corpo da resposta seria assim: } ``` -Após receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro de verificação. +Ao receber o código de verificação, você pode usá-lo para atualizar o status de verificação do registro. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}' ``` -Após verificar o código, você pode agora usar o id de registro de verificação para atualizar o identificador do usuário. +Após verificar o código, você pode usar o id de registro de verificação para atualizar o identificador do usuário. -### Enviar solicitação com id de registro de verificação \{#send-request-with-verification-record-id} +### Enviar requisição com id de registro de verificação \{#send-request-with-verification-record-id} -Ao enviar uma solicitação para atualizar o identificador do usuário, você precisa anexar o id de registro de verificação ao cabeçalho da solicitação com o campo `logto-verification-id`. +Ao enviar uma requisição para atualizar o identificador do usuário, você precisa anexar o id de registro de verificação ao cabeçalho da requisição com o campo `logto-verification-id`. ### 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 certificar-se de que o template `BindNewIdentifier` está configurado. +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, você deve primeiro provar a propriedade do email. +Para atualizar ou vincular um novo email, primeiro você deve provar a propriedade do email. Chame o endpoint `POST /api/verifications/verification-code` para solicitar um código de verificação. @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -Você encontrará um `verificationId` na resposta e receberá um código de verificação no email, use-o para verificar o email. +Você encontrará um `verificationId` na resposta e receberá um código de verificação no email. Use-o para verificar o email. ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}' ``` -Após verificar o código, você pode agora atualizar o email do usuário, defina o `verificationId` no corpo da solicitação como `newIdentifierVerificationRecordId`. +Após verificar o código, 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 \ @@ -236,14 +236,14 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ ### Gerenciar telefone \{#manage-phone} :::note -Para usar este método, você precisa [configurar o conector de SMS](/connectors/sms-connectors/), e certificar-se de que o template `BindNewIdentifier` está configurado. +Para usar este método, você precisa [configurar o conector SMS](/connectors/sms-connectors/) e garantir que o template `BindNewIdentifier` esteja configurado. ::: Semelhante à atualização de email, você pode usar o endpoint `PATCH /api/my-account/primary-phone` para atualizar ou vincular um novo telefone. E usar o endpoint `DELETE /api/my-account/primary-phone` para remover o telefone do usuário. ### Vincular uma nova conexão social \{#link-a-new-social-connection} -Para vincular uma nova conexão social, primeiro você deve solicitar uma URL de autorização: +Para vincular uma nova conexão social, primeiro solicite uma URL de autorização: ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -253,12 +253,12 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ ``` - `connectorId`: O ID do [conector social](/connectors/social-connectors/). -- `redirectUri`: O URI de redirecionamento após o usuário autorizar o aplicativo, você deve hospedar uma página da web neste URL e capturar o callback. -- `state`: O estado a ser retornado após o usuário autorizar o aplicativo, é uma string aleatória usada para prevenir ataques CSRF. +- `redirectUri`: O URI de redirecionamento após o usuário autorizar o aplicativo. Você deve hospedar uma página web neste URL e capturar o callback. +- `state`: O estado a ser retornado após o usuário autorizar o aplicativo. É uma string aleatória usada para prevenir ataques CSRF. -Na resposta, você encontrará um `verificationRecordId`, guarde-o para uso posterior. +Na resposta, você encontrará um `verificationRecordId`. Guarde-o para uso posterior. -Após o usuário autorizar o aplicativo, você receberá um callback no `redirectUri` com o parâmetro `state`. Então você pode usar o endpoint `POST /api/verifications/social/verify` para verificar a conexão social. +Após o usuário autorizar o aplicativo, você receberá um callback no `redirectUri` com o parâmetro `state`. Então, você pode usar o endpoint `POST /api/verifications/social/verify` para verificar a conexão social. ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \ @@ -267,9 +267,9 @@ 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 envolvê-los como um JSON como o valor do 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`. -Finalmente, você pode usar o endpoint `POST /api/my-account/identities` para vincular a conexão social. +Por fim, você pode usar o endpoint `POST /api/my-account/identities` para vincular a conexão social. ```bash curl -X POST https://[tenant-id].logto.app/api/my-account/identities \ diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index 1bfb2ee2ed1..f9a6956eb08 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -20,10 +20,10 @@ sequenceDiagram A ->> C: Inserir e-mail do convidado e papel C ->> L: Criar convite de organização com Management API L -->> C: Retornar ID do convite - C ->> C: Compor link de convite com o ID do convite - C ->> L: Solicitar envio de e-mail de convite com o link de convite - L -->> U: Enviar e-mail de convite com o link de convite - U ->> C: Clicar no link de convite e navegar para sua landing page,
aceitar ou rejeitar o convite + C ->> C: Compor link de convite com ID do convite + C ->> L: Solicitar envio de e-mail de convite com link de convite + L -->> U: Enviar e-mail de convite com link de convite + U ->> C: Clicar no link de convite e navegar para sua landing page,
aceitar ou recusar o convite C ->> L: Atualizar status do convite com Management API ``` @@ -64,7 +64,7 @@ Um exemplo de template de e-mail para o tipo de uso `OrganizationInvitation` é } ``` -O placeholder `{{link}}` no conteúdo do e-mail será substituído pelo link real de convite ao enviar o e-mail. Neste guia, vamos supor que seria `https://your-app.com/invitation/accept/{your-invitation-id}`. +O placeholder `{{link}}` no conteúdo do e-mail será substituído pelo link real do convite ao enviar o e-mail. Neste guia, vamos supor que seria `https://your-app.com/invitation/accept/{your-invitation-id}`. :::note @@ -72,7 +72,7 @@ O "serviço de e-mail Logto" integrado do Logto Cloud não suporta o tipo de uso ::: -## Lidar com convites usando Logto Management API \{#handle-invitations-with-logto-management-api} +## Gerencie convites com Logto Management API \{#handle-invitations-with-logto-management-api} :::note @@ -80,11 +80,25 @@ Se você ainda não configurou o Logto Management API, confira [Interaja com Man ::: -Fornecemos um conjunto de APIs de Management relacionadas a convites no recurso de organizações. Com essas APIs, você pode: +### Para usuários Cloud e OSS v1.27.0+ \{#for-cloud-and-oss-v1-27-0-users} + +Agora podemos usar o recurso [Magic link (Token de uso único)](/end-user-flows/one-time-token) para gerenciar o fluxo de convite. + +Basta chamar o Management API para criar um token de uso único e compor um magic link de convite com o token e o e-mail do convidado. +Insira o link no placeholder `{{link}}` do template de e-mail acima e envie o e-mail para o convidado. +Você pode compor um link como `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` em vez de um contendo o ID do convite. + +Esta é a abordagem recomendada, pois irá registrar automaticamente o convidado com o magic link caso ele ainda não tenha uma conta. + +Confira a página [Magic link (Token de uso único)](/end-user-flows/one-time-token) para mais detalhes. + +### Para usuários OSS v1.26.0- \{#for-oss-v1-26-0--users} + +Fornecemos um conjunto de APIs de convite relacionadas no recurso de organizações. Com essas APIs, você pode: - `POST /api/organization-invitations` criar um convite de organização com um papel de organização atribuído. - `POST /api/organization-invitations/{id}/message` enviar o convite da organização para o convidado por e-mail. - Observação: O payload desta API suporta uma propriedade `link`, você pode compor seu link de convite com base no ID do convite. Por exemplo: + Nota: Este payload da API suporta uma propriedade `link`, você pode compor seu link de convite com base no ID do convite. Por exemplo: ```json { @@ -96,26 +110,26 @@ Fornecemos um conjunto de APIs de Management relacionadas a convites no recurso - `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` obter todos os seus convites ou um específico pelo ID. Em sua landing page, use essas APIs para listar todos os convites ou detalhes de um convite que um usuário recebeu. -- `PUT /api/organization-invitations/{id}/status` aceitar ou rejeitar o convite atualizando o status do convite. +- `PUT /api/organization-invitations/{id}/status` aceitar ou recusar o convite atualizando o status do convite. Use esta API para lidar com a resposta do usuário ao convite. -## Use controle de acesso baseado em papel (RBAC) da organização para gerenciar permissões de usuário \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +## Use controle de acesso baseado em papel (RBAC) da organização para gerenciar permissões de usuários \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} Com as configurações acima, agora você pode enviar convites por e-mail, e os convidados podem ingressar na organização com o papel atribuído. Usuários com diferentes papéis de organização terão diferentes escopos (permissões) em seus tokens de organização. Assim, tanto seu app cliente quanto os serviços de backend devem verificar esses escopos para determinar recursos visíveis e ações permitidas. -## Lidar com atualizações de escopo em tokens de organização \{#handle-scope-updates-in-organization-tokens} +## Gerencie atualizações de escopo em tokens de organização \{#handle-scope-updates-in-organization-tokens} :::note -Esta seção envolve tópicos avançados sobre gerenciamento de template de organização e cenários de autorização. Se você não está familiarizado com esses conceitos, leia primeiro [Autorização](/authorization) e [Template de organização](/authorization/organization-template). +Esta seção envolve tópicos avançados sobre gerenciamento de template de organização e cenários de autorização. Se você não está familiarizado com esses conceitos, leia [Autorização](/authorization) e [Template de organização](/authorization/organization-template) primeiro. ::: Gerenciar atualizações de escopo em tokens de organização envolve: ### Revogar escopos existentes \{#revoking-existing-scopes} -Por exemplo, rebaixar um admin para um membro não-admin deve remover escopos do usuário. Nesse caso, você pode simplesmente limpar o token de organização em cache e buscar um novo com o refresh token. Os escopos reduzidos serão refletidos imediatamente no novo token de organização emitido. +Por exemplo, rebaixar um admin para membro não-admin deve remover escopos do usuário. Nesse caso, basta limpar o token de organização em cache e buscar um novo com o token de atualização. Os escopos reduzidos serão refletidos imediatamente no novo token de organização emitido. ### Conceder novos escopos \{#granting-new-scopes} @@ -123,13 +137,13 @@ Isso pode ser dividido em dois cenários: #### Conceder novos escopos já definidos em seu sistema de autenticação \{#grant-new-scopes-that-already-defined-in-your-auth-system} -Semelhante à revogação de escopos, se o novo escopo concedido já estiver registrado no servidor de autenticação, você pode simplesmente emitir um novo token de organização, e os novos escopos serão refletidos imediatamente. +Semelhante à revogação de escopos, se o novo escopo concedido já estiver registrado no servidor de autenticação, basta emitir um novo token de organização, e os novos escopos serão refletidos imediatamente. #### Conceder novos escopos recém-introduzidos em seu sistema de autenticação \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -Nesse caso, você precisa acionar um processo de novo login ou novo consentimento para atualizar o token de organização do usuário. Por exemplo, chamando o método `signIn` no Logto SDK. +Neste caso, você precisa acionar um processo de novo login ou novo consentimento para atualizar o token de organização do usuário. Por exemplo, chamando o método `signIn` no Logto SDK. -### Implementar verificação de permissão em tempo real e atualizar token de organização \{#implement-real-time-permission-check-and-update-organization-token} +### Implemente verificação de permissão em tempo real e atualize o token de organização \{#implement-real-time-permission-check-and-update-organization-token} O Logto fornece Management API para buscar permissões de usuário em tempo real na organização. @@ -137,7 +151,7 @@ O Logto fornece Management API para buscar permissões de usuário em tempo real Você pode então comparar os escopos no token de organização do usuário com as permissões em tempo real para determinar se o usuário foi promovido ou rebaixado. -- Se rebaixado, você pode simplesmente limpar o token de organização em cache e o SDK emitirá automaticamente um novo com os escopos atualizados. +- Se rebaixado, basta limpar o token de organização em cache e o SDK emitirá automaticamente um novo com os escopos atualizados. ```ts const { clearAccessToken } = useLogto(); @@ -163,7 +177,7 @@ Você pode então comparar os escopos no token de organização do usuário com }); ``` - O código acima acionará uma navegação para a tela de consentimento e redirecionará automaticamente de volta ao seu app, com os escopos atualizados no token de organização do usuário. + O código acima acionará uma navegação para a tela de consentimento e redirecionará automaticamente de volta ao seu app, com escopos atualizados no token de organização do usuário. ## Recursos relacionados \{#related-resources} 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 431441b6ebf..5fa7b890492 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/account-settings/by-account-api.mdx @@ -7,33 +7,33 @@ sidebar_position: 2 ## 什么是 Logto Account API \{#what-is-logto-account-api} -Logto Account API 是一组全面的 API，允许终端用户直接访问 API，而无需通过 Management API，以下是其亮点： +Logto Account API 是一套全面的 API，允许终端用户直接通过 API 访问，无需经过 Management API，主要亮点如下： -- 直接访问：Account API 使终端用户能够直接访问和管理自己的账户资料，而无需中继 Management API。 -- 用户资料和身份管理：用户可以完全管理他们的资料和安全设置，包括更新电子邮件、电话和密码等身份信息，以及管理社交连接。MFA 和 SSO 支持即将推出。 -- 全局访问控制：管理员拥有完全的全局控制权，可以自定义每个字段。 -- 无缝授权：授权比以往更简单！只需使用 `client.getAccessToken()` 获取一个用于 OP (Logto) 的不透明访问令牌，并将其作为 `Bearer ` 附加到 Authorization 头中。 +- 直接访问：Account API 让终端用户可以直接访问和管理自己的账户资料，无需通过 Management API 中转。 +- 用户资料与身份管理：用户可以完全管理自己的资料和安全设置，包括更新邮箱、手机号、密码等身份信息，以及管理社交连接。MFA 和 SSO 支持即将上线。 +- 全局访问控制：管理员拥有对访问设置的完全全局控制，可以自定义每个字段。 +- 无缝授权 (Authorization)：授权 (Authorization) 变得前所未有的简单！只需使用 `client.getAccessToken()` 获取 OP (Logto) 的不透明令牌 (Opaque token)，并将其作为 `Bearer ` 附加到 Authorization 头部即可。 -通过 Logto Account API，你可以构建一个与 Logto 完全集成的自定义账户管理系统，如个人资料页面。 +通过 Logto Account API，你可以构建一个与 Logto 完全集成的自定义账户管理系统，比如个人资料页。 -以下是一些常见的用法： +常见的使用场景包括： -- 检索用户资料 +- 获取用户资料 - 更新用户资料 - 更新用户密码 -- 更新用户身份信息，包括电子邮件、电话和社交连接 +- 更新用户身份信息，包括邮箱、手机号和社交连接 -要了解更多可用的 API，请访问 [Logto Account API 参考](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 参考](https://openapi.logto.io/group/endpoint-verifications)。 +想了解更多可用的 API，请访问 [Logto Account API 参考文档](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API 参考文档](https://openapi.logto.io/group/endpoint-verifications)。 :::note -以下设置的专用 Account API 即将推出：MFA、SSO、自定义数据（用户）和账户删除。同时，你可以使用 Logto Management API 实现这些功能。有关详细信息，请参阅 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 +以下设置的专用 Account API 即将上线：MFA、多因素认证 (MFA)、单点登录 (SSO)、自定义数据（用户）和账户删除。在此期间，你可以通过 Logto Management API 实现这些功能。详见 [通过 Management API 进行账户设置](/end-user-flows/account-settings/by-management-api)。 ::: ## 如何启用 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，并自定义字段。 示例请求： @@ -44,30 +44,30 @@ 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`：名称字段。 +- `name`：姓名字段。 - `avatar`：头像字段。 - `profile`：资料字段，包括其子字段。 - `username`：用户名字段。 -- `email`：电子邮件字段。 -- `phone`：电话字段。 -- `password`：密码字段，获取时，如果用户已设置密码，则返回 `true`，否则返回 `false`。 +- `email`：邮箱字段。 +- `phone`：手机号字段。 +- `password`：密码字段，获取时如果用户已设置密码则返回 `true`，否则为 `false`。 - `social`：社交连接。 -在 [Logto Management API 参考](https://openapi.logto.io/group/endpoint-account-center) 中了解更多 API 详细信息。 +更多 API 详情请参见 [Logto Management API 参考文档](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)。该令牌是不透明令牌 (Opaque token)，可用于访问 Account API。 -如果你没有使用官方 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 交互时，应将访问令牌 (Access token) 以 Bearer 格式（`Bearer YOUR_TOKEN`）放在 HTTP 头部的 `Authorization` 字段中。 获取用户账户信息的示例： @@ -76,16 +76,16 @@ curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -## 管理基本账户信息 \{#manage-basic-account-information} +## 管理基础账户信息 \{#manage-basic-account-information} -### 检索用户账户信息 \{#retrieve-user-account-information} +### 获取用户账户信息 \{#retrieve-user-account-information} ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -响应体如下： +响应体示例： ```json { @@ -96,13 +96,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -响应字段可能会根据账户中心设置而有所不同。 +响应字段可能会根据账户中心设置有所不同。 -### 更新基本账户信息 \{#update-basic-account-information} +### 更新基础账户信息 \{#update-basic-account-information} -基本账户信息包括用户名、名称、头像和资料。 +基础账户信息包括用户名、姓名、头像和资料。 -要更新用户名、名称和头像，你可以使用 `PATCH /api/my-account` 端点。 +要更新用户名、姓名和头像，可以使用 `PATCH /api/my-account` 端点。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -111,7 +111,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -要更新资料，你可以使用 `PATCH /api/my-account/profile` 端点。 +要更新资料，可以使用 `PATCH /api/my-account/profile` 端点。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -120,17 +120,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 管理标识符和其他敏感信息 \{#manage-identifiers-and-other-sensitive-information} +## 管理标识符及其他敏感信息 \{#manage-identifiers-and-other-sensitive-information} -出于安全原因，Account API 需要对涉及标识符和其他敏感信息的操作进行另一层授权。 +出于安全考虑，Account API 对涉及标识符及其他敏感信息的操作需要额外一层授权 (Authorization)。 ### 获取验证记录 ID \{#get-a-verification-record-id} -首先，你需要获取一个验证记录 ID，这可以用于在更新标识符时验证用户的身份。 +首先，你需要获取一个验证记录 ID，用于在更新标识符时验证用户身份。 -要获取验证记录 ID，你可以验证用户的密码或向用户的电子邮件或电话发送验证码。 +获取验证记录 ID 的方式包括验证用户密码或向用户邮箱 / 手机发送验证码。 -#### 验证用户的密码 \{#verify-the-users-password} +#### 验证用户密码 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -响应体如下： +响应体示例： ```json { @@ -148,13 +148,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 通过向用户的电子邮件或电话发送验证码进行验证 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 通过向用户邮箱 / 手机发送验证码进行验证 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -要使用此方法，你需要 [配置电子邮件连接器](/connectors/email-connectors/) 或 [SMS 连接器](/connectors/sms-connectors/)，并确保配置了 `UserPermissionValidation` 模板。 +使用此方法前，你需要 [配置邮箱连接器](/connectors/email-connectors/) 或 [配置短信连接器](/connectors/sms-connectors/)，并确保已配置 `UserPermissionValidation` 模板。 ::: -以电子邮件为例，请求一个新的验证码并获取验证记录 ID： +以邮箱为例，请求新的验证码并获取验证记录 ID： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -响应体如下： +响应体示例： ```json { @@ -172,28 +172,28 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -收到验证码后，你可以使用它来更新验证记录的验证状态。 +收到验证码后，你可以用它来更新验证记录的验证状态。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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} -在发送请求以更新用户的标识符时，你需要将验证记录 ID 附加到请求头中的 `logto-verification-id` 字段。 +在发送更新用户标识符的请求时，需要在请求头中通过 `logto-verification-id` 字段附带验证记录 ID。 -### 更新或链接新电子邮件 \{#update-or-link-new-email} +### 更新或绑定新邮箱 \{#update-or-link-new-email} :::note -要使用此方法，你需要 [配置电子邮件连接器](/connectors/email-connectors/)，并确保配置了 `BindNewIdentifier` 模板。 +使用此方法前，你需要 [配置邮箱连接器](/connectors/email-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 ::: -要更新或链接新电子邮件，你应首先证明对电子邮件的所有权。 +要更新或绑定新邮箱，首先需要证明对该邮箱的所有权。 调用 `POST /api/verifications/verification-code` 端点请求验证码。 @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -你将在响应中找到一个 `verificationId`，并在电子邮件中收到验证码，使用它来验证电子邮件。 +你会在响应中获得 `verificationId`，并在邮箱中收到验证码，使用它验证邮箱。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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 \ @@ -223,9 +223,9 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --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 \ @@ -233,17 +233,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 管理电话 \{#manage-phone} +### 管理手机号 \{#manage-phone} :::note -要使用此方法，你需要 [配置 SMS 连接器](/connectors/sms-connectors/)，并确保配置了 `BindNewIdentifier` 模板。 +使用此方法前，你需要 [配置短信连接器](/connectors/sms-connectors/)，并确保已配置 `BindNewIdentifier` 模板。 ::: -类似于更新电子邮件，你可以使用 `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} +### 绑定新的社交连接 \{#link-a-new-social-connection} -要链接新的社交连接，首先你应该请求一个授权 URL： +要绑定新的社交连接，首先需要请求授权 (Authorization) URL： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`：[社交连接器](/connectors/social-connectors/)的 ID。 -- `redirectUri`：用户授权应用程序后的重定向 URI，你应该在此 URL 上托管一个网页并捕获回调。 -- `state`：用户授权应用程序后返回的状态，它是一个用于防止 CSRF 攻击的随机字符串。 +- `connectorId`： [社交连接器](/connectors/social-connectors/) 的 ID。 +- `redirectUri`：用户授权 (Authorization) 应用后跳转的 URI，你需要在此地址托管网页并捕获回调。 +- `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 \ @@ -267,9 +267,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 \ @@ -281,7 +281,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] \ diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index ba4eb3497a1..c4a4614a9d8 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,7 +4,7 @@ sidebar_position: 2 # 邀请组织成员 -作为一个多组织应用，一个常见需求是邀请成员加入你的组织。在本指南中，我们将带你了解在应用中实现此功能的步骤和技术细节。 +作为一个多组织应用，一个常见需求是邀请成员加入你的组织。本指南将带你了解在你的应用中实现此功能的步骤和技术细节。 ## 流程概览 \{#flow-overview} @@ -17,12 +17,12 @@ sequenceDiagram Participant C as 你的多组织应用 Participant L as Logto - A ->> C: 输入被邀请者邮箱和角色 + A ->> C: 输入被邀请人邮箱和角色 C ->> L: 使用 Management API 创建组织邀请 L -->> C: 返回邀请 ID C ->> C: 组合带有邀请 ID 的邀请链接 - C ->> L: 请求发送包含邀请链接的邀请邮件 - L -->> U: 发送包含邀请链接的邀请邮件 + C ->> L: 请求发送带有邀请链接的邀请邮件 + L -->> U: 发送带有邀请链接的邀请邮件 U ->> C: 点击邀请链接并跳转到你的落地页，
接受或拒绝邀请 C ->> L: 使用 Management API 更新邀请状态 ``` @@ -40,20 +40,20 @@ sequenceDiagram - `write:data` - 写入所有组织数据资源的权限。 - `delete:data` - 删除所有组织数据资源的权限。 - `invite:member` - 邀请成员加入组织。 - - `manage:member` - 管理组织成员。 + - `manage:member` - 管理组织内成员。 - `delete:member` - 移除组织成员。 - `member` 角色： - `read:data` - 读取所有组织数据资源的权限。 - `write:data` - 写入所有组织数据资源的权限。 - `invite:member` - 邀请成员加入组织。 -你可以在 [Logto 控制台](https://cloud.logto.io/) 轻松完成上述操作。你也可以使用 [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) 以编程方式创建组织角色。 +你可以在 [Logto 控制台](https://cloud.logto.io/) 轻松完成这些操作。你也可以使用 [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) 以编程方式创建组织角色。 ## 配置你的邮件连接器 \{#configure-your-email-connector} 由于邀请是通过邮件发送的，请确保你的 [邮件连接器](/connectors/email-connectors) 已正确配置。要发送邀请，你需要配置一个 [邮件模板](/connectors/email-connectors/email-templates#email-template-types) 用法类型 - `OrganizationInvitation`。你还可以在内容中包含组织（如组织名称、Logo）和邀请人（如邀请人邮箱、姓名）[变量](/connectors/email-connectors/email-templates#email-template-variables)，或根据需要自定义 [多语言模板](/connectors/email-connectors/email-templates#email-template-localization)。 -下面是一个 `OrganizationInvitation` 用法类型的邮件模板示例： +以下是 `OrganizationInvitation` 用法类型的邮件模板示例： ```json { @@ -64,7 +64,7 @@ sequenceDiagram } ``` -邮件内容中的 `{{link}}` 占位符会在发送邮件时被实际的邀请链接替换。在本指南中，假设它为 `https://your-app.com/invitation/accept/{your-invitation-id}`。 +邮件内容中的 `{{link}}` 占位符在发送邮件时会被实际的邀请链接替换。在本指南中，假设它为 `https://your-app.com/invitation/accept/{your-invitation-id}`。 :::note @@ -76,14 +76,28 @@ Logto Cloud 内置的“Logto 邮件服务”目前不支持 `OrganizationInvita :::note -如果你还没有设置 Logto Management API，请参考 [与 Management API 交互](/integrate-logto/interact-with-management-api) 获取详细信息。 +如果你还没有设置 Logto Management API，请查看 [与 Management API 交互](/integrate-logto/interact-with-management-api) 获取详情。 ::: +### 针对 Cloud 和 OSS v1.27.0+ 用户 \{#for-cloud-and-oss-v1-27-0-users} + +我们现在可以使用 [魔法链接（一次性令牌）](/end-user-flows/one-time-token) 功能来处理邀请流程。 + +只需调用 Management API 创建一次性令牌，并用该令牌和被邀请人邮箱组合一个邀请魔法链接。 +将该链接插入到上述邮件模板的 `{{link}}` 占位符中，并发送邮件给被邀请人。 +你可以组合一个类似 `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` 的链接，而不是包含邀请 ID 的链接。 + +这是推荐方式，因为如果被邀请人还没有账户，魔法链接会自动为其注册。 + +详细信息请查看 [魔法链接（一次性令牌）](/end-user-flows/one-time-token) 页面。 + +### 针对 OSS v1.26.0- 用户 \{#for-oss-v1-26-0--users} + 我们在组织功能中提供了一组与邀请相关的 Management API。通过这些 API，你可以： - `POST /api/organization-invitations` 创建带有指定组织角色的组织邀请。 -- `POST /api/organization-invitations/{id}/message` 通过邮件向被邀请者发送组织邀请。 +- `POST /api/organization-invitations/{id}/message` 通过邮件将组织邀请发送给被邀请人。 注意：此 API 的 payload 支持 `link` 属性，你可以基于邀请 ID 组合你的邀请链接。例如： ```json @@ -92,70 +106,70 @@ Logto Cloud 内置的“Logto 邮件服务”目前不支持 `OrganizationInvita } ``` - 相应地，你需要实现一个落地页，当被邀请者通过邀请链接跳转到你的应用时进行处理。 + 相应地，你需要实现一个落地页，当被邀请人通过邀请链接跳转到你的应用时进行处理。 -- `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` 获取你所有的邀请或根据 ID 获取特定邀请。 - 在你的落地页上，使用这些 API 列出用户收到的所有邀请或某个邀请的详细信息。 -- `PUT /api/organization-invitations/{id}/status` 通过更新邀请状态来接受或拒绝邀请。 +- `GET /api/organization-invitations` & `GET /api/organization-invitations/{id}` 获取你所有的邀请或通过 ID 获取某个邀请。 + 在你的落地页上，使用这些 API 列出用户收到的所有邀请或某个邀请的详情。 +- `PUT /api/organization-invitations/{id}/status` 通过更新邀请状态接受或拒绝邀请。 使用此 API 处理用户对邀请的响应。 ## 使用基于组织角色的访问控制 (RBAC) 管理用户权限 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} -通过上述设置，你现在可以通过邮件发送邀请，被邀请者可以以分配的角色加入组织。 +通过上述配置，你现在可以通过邮件发送邀请，被邀请人可以以分配的角色加入组织。 -拥有不同组织角色的用户将在其组织令牌 (Organization token) 中拥有不同的权限 (Scopes)。因此，你的客户端应用和后端服务都应检查这些权限 (Scopes) 以确定可见功能和允许的操作。 +拥有不同组织角色的用户将在其组织令牌中拥有不同的权限（scopes）。因此，你的客户端应用和后端服务都应检查这些权限，以决定可见功能和允许的操作。 -## 处理组织令牌 (Organization token) 中的权限 (Scope) 更新 \{#handle-scope-updates-in-organization-tokens} +## 处理组织令牌中的权限（scope）更新 \{#handle-scope-updates-in-organization-tokens} :::note 本节涉及组织模板和授权 (Authorization) 场景的高级主题。如果你不熟悉这些概念，请先阅读 [授权 (Authorization)](/authorization) 和 [组织模板](/authorization/organization-template)。 ::: -管理组织令牌 (Organization token) 中权限 (Scope) 的更新包括： +管理组织令牌中的权限（scope）更新包括： -### 撤销已有权限 (Revoking existing scopes) \{#revoking-existing-scopes} +### 撤销已有权限 \{#revoking-existing-scopes} -例如，将管理员降级为非管理员成员时，应移除该用户的权限 (Scopes)。此时，你只需清除缓存的组织令牌 (Organization token)，并使用刷新令牌 (Refresh token) 获取新的组织令牌 (Organization token)。收缩后的权限 (Scopes) 会立即反映在新签发的组织令牌 (Organization token) 中。 +例如，将管理员降级为普通成员时，应移除该用户的权限。在这种情况下，你只需清除缓存的组织令牌，并使用刷新令牌获取新的组织令牌。收缩后的权限会立即反映在新签发的组织令牌中。 -### 授予新权限 (Granting new scopes) \{#granting-new-scopes} +### 授予新权限 \{#granting-new-scopes} -这又可以细分为两种场景： +这又可以分为两种场景： -#### 授予已在认证系统中定义的新权限 (Grant new scopes that already defined in your auth system) \{#grant-new-scopes-that-already-defined-in-your-auth-system} +#### 授予已在认证系统中定义的新权限 \{#grant-new-scopes-that-already-defined-in-your-auth-system} -与撤销权限 (Scopes) 类似，如果新授予的权限 (Scope) 已在认证服务器注册，你只需签发新的组织令牌 (Organization token)，新权限 (Scopes) 会立即生效。 +与撤销权限类似，如果新授予的权限已在认证服务器注册，你只需签发新的组织令牌，新权限会立即生效。 -#### 授予认证系统中新引入的权限 (Grant new scopes that are newly introduced your auth system) \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} +#### 授予认证系统中新引入的权限 \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -此时，你需要触发重新登录或重新授权流程，以更新用户的组织令牌 (Organization token)。例如，调用 Logto SDK 中的 `signIn` 方法。 +此时，你需要触发重新登录或重新授权流程以更新用户的组织令牌。例如，调用 Logto SDK 的 `signIn` 方法。 -### 实现实时权限检查并更新组织令牌 (Organization token) \{#implement-real-time-permission-check-and-update-organization-token} +### 实现实时权限检查并更新组织令牌 \{#implement-real-time-permission-check-and-update-organization-token} -Logto 提供了 Management API 用于获取用户在组织中的实时权限 (Permissions)。 +Logto 提供 Management API 用于获取用户在组织中的实时权限。 - `GET /api/organizations/{id}/users/{userId}/scopes` ([API 参考](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -你可以将用户组织令牌 (Organization token) 中的权限 (Scopes) 与实时权限 (Permissions) 进行对比，以判断用户是否被提升或降级。 +你可以将用户组织令牌中的权限与实时权限进行对比，以判断用户是否被提升或降级。 -- 如果被降级，你只需清除缓存的组织令牌 (Organization token)，SDK 会自动签发带有更新权限 (Scopes) 的新令牌 (Organization token)。 +- 如果被降级，你只需清除缓存的组织令牌，SDK 会自动签发带有更新权限的新令牌。 ```ts const { clearAccessToken } = useLogto(); ... - // 如果获取到的实时权限 (Scopes) 少于组织令牌 (Organization token) 中的权限 (Scopes) + // 如果实时获取的权限比组织令牌中的权限少 await clearAccessToken(); ``` - 这不需要重新登录或重新授权流程。Logto SDK 会自动签发新的组织令牌 (Organization token)。 + 这不需要重新登录或重新授权流程。Logto SDK 会自动签发新的组织令牌。 -- 如果你的认证系统中引入了新的权限 (Scope)，则需触发重新登录或重新授权流程以更新用户的组织令牌 (Organization token)。以 React SDK 为例： +- 如果你的认证系统中引入了新权限，触发重新登录或重新授权流程以更新用户的组织令牌。以 React SDK 为例： ```ts const { clearAllTokens, signIn } = useLogto(); ... - // 如果获取到的实时权限 (Scopes) 比组织令牌 (Organization token) 中的权限 (Scopes) 多 + // 如果实时获取的权限比组织令牌中的权限多 await clearAllTokens(); signIn({ redirectUri: '', @@ -163,7 +177,7 @@ Logto 提供了 Management API 用于获取用户在组织中的实时权限 (Pe }); ``` - 上述代码会触发页面跳转到用户授权页面 (Consent screen)，并自动重定向回你的应用，用户组织令牌 (Organization token) 中的权限 (Scopes) 会被更新。 + 上述代码会触发页面跳转到用户授权页面，并自动重定向回你的应用，用户组织令牌中的权限也会更新。 ## 相关资源 \{#related-resources} 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 1f37c924ecc..28b1fcb2113 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 @@ -3,37 +3,37 @@ description: 瞭解如何使用 Account API 管理使用者 sidebar_position: 2 --- -# 使用 Account API 設定帳戶 +# 透過 Account API 管理帳戶設定 ## 什麼是 Logto Account API \{#what-is-logto-account-api} -Logto Account API 是一組完整的 API，讓終端使用者可以直接存取 API，而不需要透過 Management API，以下是重點： +Logto Account API 是一套完整的 API，讓終端使用者可以直接透過 API 存取帳戶，而無需經過 Management API，重點如下： -- 直接存取：Account API 讓終端使用者可以直接存取並管理自己的帳戶資料，而不需要透過 Management API。 -- 使用者資料和身分管理：使用者可以完全管理自己的資料和安全設定，包括更新電子郵件、電話和密碼等身分資訊，以及管理社交連結。MFA 和 SSO 支援即將推出。 -- 全域存取控制：管理員擁有完整的全域控制權，可以自訂每個欄位。 -- 無縫授權：授權比以往更簡單！只需使用 `client.getAccessToken()` 獲取 Logto 的不透明存取權杖，並將其作為 `Bearer ` 附加到 Authorization 標頭。 +- 直接存取：Account API 讓終端使用者可以直接存取並管理自己的帳戶資料，無需透過 Management API 中繼。 +- 使用者資料與身分管理：使用者可完整管理個人資料與安全設定，包括更新電子郵件、手機、密碼等身分資訊，以及管理社交連結。MFA 與 SSO 支援即將推出。 +- 全域存取控制：管理員可對存取設定進行完整、全域的控制，並可自訂每個欄位。 +- 無縫授權 (Seamless authorization)：授權變得前所未有地簡單！只需使用 `client.getAccessToken()` 取得 Logto 的不透明權杖 (Opaque token)，並以 `Bearer ` 附加於 Authorization 標頭即可。 -使用 Logto Account API，你可以建立一個自訂的帳戶管理系統，如與 Logto 完全整合的個人資料頁面。 +透過 Logto Account API，你可以打造與 Logto 完整整合的自訂帳戶管理系統，例如個人資料頁面。 -以下列出一些常見的使用方式： +常見的使用情境如下： - 取得使用者資料 - 更新使用者資料 - 更新使用者密碼 -- 更新使用者身分，包括電子郵件、電話和社交連結 +- 更新使用者身分資訊（包含電子郵件、手機、社交連結） -要瞭解更多可用的 API，請造訪 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 和 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications)。 +想瞭解更多可用 API，請參閱 [Logto Account API Reference](https://openapi.logto.io/group/endpoint-my-account) 與 [Logto Verification API Reference](https://openapi.logto.io/group/endpoint-verifications)。 :::note -以下設定的專用 Account API 即將推出：MFA、SSO、自訂資料（使用者）和帳戶刪除。與此同時，你可以使用 Logto Management API 實現這些功能。詳情請參閱 [使用 Management API 設定帳戶](/end-user-flows/account-settings/by-management-api)。 +以下設定專用的 Account API 即將推出：MFA、多重要素驗證 (MFA)、單一登入 (SSO)、自訂資料（使用者）、帳戶刪除。在此之前，你可以透過 Logto Management API 實作這些功能。詳情請參閱 [透過 Management API 管理帳戶設定](/end-user-flows/account-settings/by-management-api)。 ::: ## 如何啟用 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，並自訂欄位。 範例請求： @@ -44,32 +44,32 @@ 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`：名稱欄位。 +- `name`：姓名欄位。 - `avatar`：頭像欄位。 -- `profile`：資料欄位，包括其子欄位。 +- `profile`：個人資料欄位，包含其子欄位。 - `username`：使用者名稱欄位。 - `email`：電子郵件欄位。 -- `phone`：電話欄位。 -- `password`：密碼欄位，當取得時，如果使用者已設置密碼，則返回 `true`，否則返回 `false`。 +- `phone`：手機欄位。 +- `password`：密碼欄位，查詢時若使用者已設密碼則回傳 `true`，否則為 `false`。 - `social`：社交連結。 -瞭解更多 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} -### 獲取存取權杖 \{#fetch-an-access-token} +### 取得存取權杖 (Access token) \{#fetch-an-access-token} -在應用程式中設置 SDK 後，你可以使用 `client.getAccessToken()` 方法獲取存取權杖。此權杖是不透明權杖，可用於存取 Account API。 +在應用程式中設定好 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 互動時，應將存取權杖放在 HTTP 標頭的 `Authorization` 欄位中，格式為 Bearer (`Bearer YOUR_TOKEN`)。 +與 Account API 互動時，請將存取權杖放在 HTTP 標頭的 `Authorization` 欄位，格式為 Bearer (`Bearer YOUR_TOKEN`)。 -以下是獲取使用者帳戶資訊的範例： +以下為取得使用者帳戶資訊的範例： ```bash curl https://[tenant-id].logto.app/api/my-account \ @@ -78,14 +78,14 @@ curl https://[tenant-id].logto.app/api/my-account \ ## 管理基本帳戶資訊 \{#manage-basic-account-information} -### 獲取使用者帳戶資訊 \{#retrieve-user-account-information} +### 取得使用者帳戶資訊 \{#retrieve-user-account-information} ```bash curl https://[tenant-id].logto.app/api/my-account \ -H 'authorization: Bearer ' ``` -回應主體可能如下： +回應內容範例如下： ```json { @@ -96,13 +96,13 @@ curl https://[tenant-id].logto.app/api/my-account \ } ``` -回應欄位可能會根據帳戶中心設定而有所不同。 +回應欄位會依帳戶中心設定而有所不同。 ### 更新基本帳戶資訊 \{#update-basic-account-information} -基本帳戶資訊包括使用者名稱、名稱、頭像和資料。 +基本帳戶資訊包含使用者名稱、姓名、頭像與個人資料。 -要更新使用者名稱、名稱和頭像，可以使用 `PATCH /api/my-account` 端點。 +若要更新使用者名稱、姓名、頭像，可使用 `PATCH /api/my-account` 端點。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account \ @@ -111,7 +111,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \ --data-raw '{"username":"...","name":"...","avatar":"..."}' ``` -要更新資料，可以使用 `PATCH /api/my-account/profile` 端點。 +若要更新個人資料，可使用 `PATCH /api/my-account/profile` 端點。 ```bash curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ @@ -120,17 +120,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \ --data-raw '{"familyName":"...","givenName":"..."}' ``` -## 管理識別符和其他敏感資訊 \{#manage-identifiers-and-other-sensitive-information} +## 管理識別資訊與其他敏感資料 \{#manage-identifiers-and-other-sensitive-information} -出於安全考量，Account API 需要對涉及識別符和其他敏感資訊的操作進行額外的授權。 +出於安全考量，Account API 在涉及識別資訊與其他敏感操作時，需額外授權。 -### 獲取驗證記錄 ID \{#get-a-verification-record-id} +### 取得驗證記錄 ID \{#get-a-verification-record-id} -首先，你需要獲取驗證記錄 ID，這可用於在更新識別符時驗證使用者的身分。 +首先需取得驗證記錄 ID，該 ID 可用於更新識別資訊時驗證使用者身分。 -要獲取驗證記錄 ID，你可以驗證使用者的密碼或向使用者的電子郵件或電話發送驗證碼。 +取得驗證記錄 ID 的方式：驗證使用者密碼，或向使用者電子郵件 / 手機發送驗證碼。 -#### 驗證使用者的密碼 \{#verify-the-users-password} +#### 驗證使用者密碼 \{#verify-the-users-password} ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/password \ @@ -139,7 +139,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ --data-raw '{"password":"..."}' ``` -回應主體可能如下： +回應內容範例如下： ```json { @@ -148,13 +148,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/password \ } ``` -#### 通過向使用者的電子郵件或電話發送驗證碼進行驗證 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} +#### 透過發送驗證碼至電子郵件或手機驗證 \{#verify-by-sending-a-verification-code-to-the-users-email-or-phone} :::note -要使用此方法，你需要 [配置電子郵件連接器](/connectors/email-connectors/) 或 [SMS 連接器](/connectors/sms-connectors/)，並確保配置了 `UserPermissionValidation` 模板。 +使用此方法前，需先[設定電子郵件連接器](/connectors/email-connectors/)或[設定簡訊連接器](/connectors/sms-connectors/)，並確保已設定 `UserPermissionValidation` 範本。 ::: -以電子郵件為例，請求新的驗證碼並獲取驗證記錄 ID： +以電子郵件為例，請求新驗證碼並取得驗證記錄 ID： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -163,7 +163,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -回應主體可能如下： +回應內容範例如下： ```json { @@ -172,30 +172,30 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ } ``` -收到驗證碼後，你可以使用它來更新驗證記錄的驗證狀態。 +收到驗證碼後，可用於更新驗證記錄的驗證狀態。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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} -在發送請求以更新使用者的識別符時，你需要將驗證記錄 ID 附加到請求標頭的 `logto-verification-id` 欄位。 +在發送更新使用者識別資訊的請求時，需將驗證記錄 ID 夾帶於請求標頭的 `logto-verification-id` 欄位。 -### 更新或連結新電子郵件 \{#update-or-link-new-email} +### 更新或綁定新電子郵件 \{#update-or-link-new-email} :::note -要使用此方法，你需要 [配置電子郵件連接器](/connectors/email-connectors/)，並確保配置了 `BindNewIdentifier` 模板。 +使用此方法前，需先[設定電子郵件連接器](/connectors/email-connectors/)，並確保已設定 `BindNewIdentifier` 範本。 ::: -要更新或連結新電子郵件，你應首先證明對該電子郵件的擁有權。 +更新或綁定新電子郵件前，需先驗證該電子郵件的擁有權。 -調用 `POST /api/verifications/verification-code` 端點以請求驗證碼。 +呼叫 `POST /api/verifications/verification-code` 端點請求驗證碼。 ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ @@ -204,16 +204,16 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \ --data-raw '{"identifier":{"type":"email","value":"..."}}' ``` -你會在回應中找到 `verificationId`，並在電子郵件中收到驗證碼，使用它來驗證電子郵件。 +回應中會有 `verificationId`，並會收到驗證碼，請用於驗證電子郵件。 ```bash -curl -X PATCH https://[tenant-id].logto.app/api/verifications/verification-code/verify \ +curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \ -H 'authorization: Bearer ' \ -H 'content-type: application/json' \ --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 \ @@ -223,9 +223,9 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/primary-email \ --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 \ @@ -233,17 +233,17 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \ -H 'logto-verification-id: ' ``` -### 管理電話 \{#manage-phone} +### 管理手機 \{#manage-phone} :::note -要使用此方法，你需要 [配置 SMS 連接器](/connectors/sms-connectors/)，並確保配置了 `BindNewIdentifier` 模板。 +使用此方法前，需先[設定簡訊連接器](/connectors/sms-connectors/)，並確保已設定 `BindNewIdentifier` 範本。 ::: -類似於更新電子郵件，你可以使用 `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} +### 綁定新社交連結 \{#link-a-new-social-connection} -要連結新的社交連結，首先你應請求授權 URL： +綁定新社交連結時，需先請求授權網址： ```bash curl -X POST https://[tenant-id].logto.app/api/verifications/social \ @@ -252,13 +252,13 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \ --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}' ``` -- `connectorId`：[社交連接器](/connectors/social-connectors/)的 ID。 -- `redirectUri`：使用者授權應用程式後的重定向 URI，你應在此 URL 上託管一個網頁並捕獲回調。 -- `state`：使用者授權應用程式後返回的狀態，它是一個用於防止 CSRF 攻擊的隨機字串。 +- `connectorId`：對應 [社交連接器](/connectors/social-connectors/) 的 ID。 +- `redirectUri`：使用者授權應用程式後的導向網址，你需在此網址架設網頁並接收回呼。 +- `state`：授權後回傳的狀態，用於防止 CSRF 攻擊的隨機字串。 -在回應中，你會找到一個 `verificationRecordId`，請保留以備後用。 +回應中會有 `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 \ @@ -267,9 +267,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 \ @@ -281,7 +281,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] \ diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index 1c848c0de9d..18d473d034e 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,7 +4,7 @@ sidebar_position: 2 # 邀請組織 (Organization) 成員 -作為多組織 (multi-organization) 應用程式，一個常見需求是邀請成員加入你的組織 (Organization)。本指南將帶你瞭解在應用程式中實作此功能的步驟與技術細節。 +作為多組織應用程式，一個常見需求是邀請成員加入你的組織。本文將帶你了解在應用程式中實作此功能的步驟與技術細節。 ## 流程概覽 \{#flow-overview} @@ -17,43 +17,43 @@ sequenceDiagram Participant C as 你的多組織應用程式 (Your multi-organization app) Participant L as Logto - A ->> C: 輸入被邀請者電子郵件與角色 (Input invitee email and role) + A ->> C: 輸入受邀者電子郵件與角色 (Input invitee email and role) C ->> L: 透過 Management API 建立組織邀請 (Create organization invitation with Management API) L -->> C: 回傳邀請 ID (Return invitation ID) C ->> C: 組合帶有邀請 ID 的邀請連結 (Compose invitation link with invitation ID) C ->> L: 請求發送帶有邀請連結的邀請郵件 (Request sending invitation email with invitation link) L -->> U: 發送帶有邀請連結的邀請郵件 (Send invitation email with invitation link) - U ->> C: 點擊邀請連結並導向你的著陸頁，
接受或拒絕邀請 (Click invitation link and navigate to your landing page,
accept or reject the invitation) + U ->> C: 點擊邀請連結並導向你的著陸頁，接受或拒絕邀請 (Click invitation link and navigate to your landing page,
accept or reject the invitation) C ->> L: 透過 Management API 更新邀請狀態 (Update invitation status with Management API) ``` ## 建立組織角色 \{#create-organization-roles} -在邀請成員加入組織 (Organization) 前，你需要先建立組織角色。請參閱 [組織範本 (Organization template)](/authorization/organization-template) 以瞭解更多關於組織角色與權限的資訊。 +在邀請成員加入組織前，你需要先建立組織角色。請參閱 [組織範本 (Organization template)](/authorization/organization-template) 以瞭解更多關於組織角色與權限的資訊。 -本指南將建立兩個典型的組織角色：`admin` 與 `member`。 +本指南將建立兩個典型的組織角色：`admin` 和 `member`。 `admin` 角色擁有組織內所有資源的完整存取權限，而 `member` 角色則有較有限的權限。例如，每個角色可擁有如下權限： - `admin` 角色： - - `read:data` - 讀取所有組織資料資源的權限。 - - `write:data` - 寫入所有組織資料資源的權限。 - - `delete:data` - 刪除所有組織資料資源的權限。 - - `invite:member` - 邀請成員加入組織的權限。 - - `manage:member` - 管理組織成員的權限。 - - `delete:member` - 移除組織成員的權限。 + - `read:data` - 讀取所有組織資料資源。 + - `write:data` - 寫入所有組織資料資源。 + - `delete:data` - 刪除所有組織資料資源。 + - `invite:member` - 邀請成員加入組織。 + - `manage:member` - 管理組織成員。 + - `delete:member` - 移除組織成員。 - `member` 角色： - - `read:data` - 讀取所有組織資料資源的權限。 - - `write:data` - 寫入所有組織資料資源的權限。 - - `invite:member` - 邀請成員加入組織的權限。 + - `read:data` - 讀取所有組織資料資源。 + - `write:data` - 寫入所有組織資料資源。 + - `invite:member` - 邀請成員加入組織。 -你可以在 [Logto Console](https://cloud.logto.io/) 輕鬆完成這些設定，也可以透過 [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) 以程式方式建立組織角色。 +這些操作可在 [Logto Console](https://cloud.logto.io/) 輕鬆完成。你也可以透過 [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) 程式化建立組織角色。 ## 設定你的電子郵件連接器 (Connector) \{#configure-your-email-connector} -由於邀請是透過電子郵件發送，請確保你的 [電子郵件連接器 (email connector)](/connectors/email-connectors) 已正確設定。要發送邀請，你需要設定一個 [電子郵件範本 (email template)](/connectors/email-connectors/email-templates#email-template-types) 使用類型 - `OrganizationInvitation`。你也可以在內容中加入組織（如組織名稱、Logo）與邀請者（如邀請者電子郵件、名稱）[變數 (variables)](/connectors/email-connectors/email-templates#email-template-variables)，或依需求自訂 [多語言範本 (multi-language templates)](/connectors/email-connectors/email-templates#email-template-localization)。 +由於邀請是透過電子郵件發送，請確保你的 [電子郵件連接器](/connectors/email-connectors) 已正確設定。要發送邀請，需設定 [電子郵件範本](/connectors/email-connectors/email-templates#email-template-types)用途類型為 `OrganizationInvitation`。你也可以在內容中加入組織（如組織名稱、Logo）與邀請人（如邀請人電子郵件、姓名）[變數](/connectors/email-connectors/email-templates#email-template-variables)，或依需求自訂 [多語言範本](/connectors/email-connectors/email-templates#email-template-localization)。 -以下為 `OrganizationInvitation` 使用類型的電子郵件範本範例： +以下為 `OrganizationInvitation` 用途類型的範本範例： ```json { @@ -64,11 +64,11 @@ sequenceDiagram } ``` -電子郵件內容中的 `{{link}}` 佔位符會在發送郵件時替換為實際的邀請連結。本指南假設該連結為 `https://your-app.com/invitation/accept/{your-invitation-id}`。 +郵件內容中的 `{{link}}` 佔位符會在發送郵件時替換為實際邀請連結。本指南假設連結為 `https://your-app.com/invitation/accept/{your-invitation-id}`。 :::note -Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationInvitation` 使用類型。你需要自行設定電子郵件連接器（如 Sendgrid）並設置 `OrganizationInvitation` 範本。 +Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationInvitation` 用途類型。你需自行設定電子郵件連接器（如 Sendgrid）並設置 `OrganizationInvitation` 範本。 ::: @@ -76,15 +76,29 @@ Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationIn :::note -如果你尚未設定 Logto Management API，請參閱 [與 Management API 互動](/integrate-logto/interact-with-management-api) 以瞭解詳情。 +若尚未設定 Logto Management API，請參閱 [與 Management API 互動](/integrate-logto/interact-with-management-api) 以取得詳細資訊。 ::: -我們在組織 (Organization) 功能中提供了一組與邀請相關的 Management API。你可以透過這些 API： +### 適用於 Cloud 與 OSS v1.27.0+ 用戶 \{#for-cloud-and-oss-v1-27-0-users} -- `POST /api/organization-invitations` 建立帶有指定組織角色的組織邀請。 -- `POST /api/organization-invitations/{id}/message` 透過電子郵件將組織邀請發送給被邀請者。 - 注意：此 API 載荷支援 `link` 屬性，你可以根據邀請 ID 組合你的邀請連結。例如： +你可以使用 [魔術連結（一次性權杖, One-time token）](/end-user-flows/one-time-token) 功能來處理邀請流程。 + +只需呼叫 Management API 建立一次性權杖，並以該權杖與受邀者電子郵件組合邀請魔術連結。 +將此連結插入上述郵件範本的 `{{link}}` 佔位符，並發送郵件給受邀者。 +你可以組合如 `https://your-app.com/landing-page?token={your-one-time-token}&email={invitee-email}` 的連結，而非包含邀請 ID 的連結。 + +這是推薦做法，因為若受邀者尚未有帳號，魔術連結會自動註冊帳號。 + +詳情請參閱 [魔術連結（一次性權杖, One-time token）](/end-user-flows/one-time-token) 頁面。 + +### 適用於 OSS v1.26.0- 用戶 \{#for-oss-v1-26-0--users} + +我們在組織功能中提供了一組邀請相關的 Management API。你可以： + +- `POST /api/organization-invitations` 以指定組織角色建立組織邀請。 +- `POST /api/organization-invitations/{id}/message` 透過電子郵件將組織邀請發送給受邀者。 + 注意：此 API 載荷支援 `link` 屬性，你可依邀請 ID 組合邀請連結。例如： ```json { @@ -92,50 +106,50 @@ Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationIn } ``` - 相對應地，你需要實作一個著陸頁，讓被邀請者點擊邀請連結後導向你的應用程式。 + 相對應地，你需要實作一個著陸頁，讓受邀者點擊邀請連結時導向你的應用程式。 -- `GET /api/organization-invitations` 及 `GET /api/organization-invitations/{id}` 取得所有邀請或依 ID 取得特定邀請。 - 在你的著陸頁上，可使用這些 API 列出所有邀請或顯示使用者收到的邀請詳情。 -- `PUT /api/organization-invitations/{id}/status` 透過更新邀請狀態來接受或拒絕邀請。 +- `GET /api/organization-invitations` 及 `GET /api/organization-invitations/{id}` 取得所有邀請或指定 ID 的邀請。 + 在著陸頁中，可用這些 API 列出所有邀請或使用者收到的邀請詳情。 +- `PUT /api/organization-invitations/{id}/status` 透過更新邀請狀態接受或拒絕邀請。 使用此 API 處理使用者對邀請的回應。 -## 使用組織角色型存取控制 (RBAC) 管理使用者權限 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +## 使用組織角色型存取控制 (RBAC, Role-based Access Control) 管理使用者權限 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} -完成上述設定後，你即可透過電子郵件發送邀請，被邀請者可依指定角色加入組織 (Organization)。 +完成上述設定後，你即可透過電子郵件發送邀請，受邀者可依分配角色加入組織。 -擁有不同組織角色的使用者，其組織權杖 (Organization token) 中會有不同的權限範圍 (Scopes)。因此，你的前端應用程式與後端服務都應檢查這些權限範圍，以決定可見功能與允許操作。 +擁有不同組織角色的使用者，其組織權杖 (Organization token) 會有不同的權限範圍 (Scopes)。因此，無論是前端應用程式還是後端服務，都應檢查這些權限範圍以決定可見功能與允許操作。 ## 處理組織權杖 (Organization token) 權限範圍 (Scope) 更新 \{#handle-scope-updates-in-organization-tokens} :::note -本節涉及組織範本 (Organization template) 與授權 (Authorization) 進階議題。若你尚未熟悉這些概念，請先閱讀 [授權 (Authorization)](/authorization) 與 [組織範本 (Organization template)](/authorization/organization-template)。 +本節涉及組織範本與授權 (Authorization) 情境的進階主題。若你尚未熟悉這些概念，請先閱讀 [授權 (Authorization)](/authorization) 與 [組織範本 (Organization template)](/authorization/organization-template)。 ::: -管理組織權杖 (Organization token) 權限範圍 (Scope) 更新包含： +管理組織權杖權限範圍更新包含： ### 撤銷現有權限範圍 \{#revoking-existing-scopes} -例如，將 admin 降級為非 admin 成員時，應移除其權限範圍。此時，你只需清除快取的組織權杖，並使用重新整理權杖 (Refresh token) 取得新權杖。縮減後的權限範圍會立即反映於新簽發的組織權杖中。 +例如，將管理員降級為非管理員成員時，應移除其權限範圍。此時，只需清除快取的組織權杖並用重新整理權杖 (Refresh token) 取得新權杖，縮減後的權限範圍會立即反映於新簽發的組織權杖中。 ### 賦予新權限範圍 \{#granting-new-scopes} -此情境可再細分為兩種： +可再細分為兩種情境： #### 賦予已在驗證系統中定義的新權限範圍 \{#grant-new-scopes-that-already-defined-in-your-auth-system} -與撤銷權限範圍類似，若新賦予的權限範圍已在驗證伺服器註冊，只需簽發新組織權杖即可，新的權限範圍會立即反映。 +與撤銷權限範圍類似，若新賦予的權限範圍已在驗證伺服器註冊，只需簽發新組織權杖即可立即反映新權限範圍。 #### 賦予驗證系統中新引入的權限範圍 \{#grant-new-scopes-that-are-newly-introduced-your-auth-system} -此時，你需要觸發重新登入或重新授權流程，以更新使用者的組織權杖。例如，呼叫 Logto SDK 的 `signIn` 方法。 +此時需觸發重新登入或重新授權流程以更新使用者的組織權杖。例如，呼叫 Logto SDK 的 `signIn` 方法。 ### 實作即時權限檢查並更新組織權杖 \{#implement-real-time-permission-check-and-update-organization-token} -Logto 提供 Management API 以查詢組織中使用者的即時權限： +Logto 提供 Management API 以查詢組織中使用者的即時權限。 - `GET /api/organizations/{id}/users/{userId}/scopes` ([API 參考文件](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -你可以將使用者組織權杖中的權限範圍與即時權限進行比對，以判斷使用者是否被升級或降級。 +你可以將使用者組織權杖中的權限範圍與即時權限比對，以判斷使用者是否被升級或降級。 - 若被降級，只需清除快取的組織權杖，SDK 會自動簽發帶有更新權限範圍的新權杖。 @@ -149,7 +163,7 @@ Logto 提供 Management API 以查詢組織中使用者的即時權限： 此操作不需重新登入或重新授權。Logto SDK 會自動簽發新組織權杖。 -- 若驗證系統中引入新權限範圍，則需觸發重新登入或重新授權流程以更新使用者的組織權杖。以 React SDK 為例： +- 若驗證系統中引入新權限範圍，需觸發重新登入或重新授權流程以更新使用者的組織權杖。以 React SDK 為例： ```ts const { clearAllTokens, signIn } = useLogto(); @@ -163,7 +177,7 @@ Logto 提供 Management API 以查詢組織中使用者的即時權限： }); ``` - 上述程式碼會觸發頁面導向使用者授權頁面 (Consent screen)，並自動導回你的應用程式，且使用者的組織權杖已帶有更新後的權限範圍。 + 上述程式碼會觸發頁面導向使用者授權頁面 (Consent screen)，並自動導回你的應用程式，且組織權杖中的權限範圍已更新。 ## 相關資源 \{#related-resources}