diff --git a/docs/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/docs/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index 80e695b0274..04b5ce31260 100644 --- a/docs/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/docs/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -80,7 +80,7 @@ The implementation is the same as the previous section. Always provide the organ For details on protecting organization‑level API permissions, see the [full guide](/authorization/organization-level-api-resources). -### Using global RBAC +### Using global RBAC \{#using-global-rbac} In this case, you can use the Logto Management API to implement system-level access control. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 7ce89726b4a..dab7249b00f 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,11 +4,11 @@ sidebar_position: 3 # Organisation erstellen -Stell dir vor, du entwickelst eine [Multi-Tenant-App](https://auth.wiki/multi-tenancy) (z. B. eine Multi-Tenant-SaaS-App), die viele Kunden bedient und jedem Kunden einen eigenen Mandanten zuweist. +Stell dir vor, du baust eine [Multi-Tenant-App](https://auth.wiki/multi-tenancy) (z. B. eine Multi-Tenant-SaaS-App), die viele Kunden bedient, wobei jeder Kunde einen eigenen Tenant besitzt. Organisationen werden typischerweise erstellt, wenn: -1. Neue Kunden sich registrieren und sowohl ein Konto als auch einen Mandanten für ihr Unternehmen anlegen. +1. Neue Kunden sich registrieren und sowohl ein Konto als auch einen Tenant für ihr Unternehmen erstellen. 2. Bestehende Benutzer innerhalb der App eine neue Organisation erstellen können. Neues Konto erstellt Organisation @@ -21,28 +21,31 @@ Organisationen werden typischerweise erstellt, wenn: Es gibt zwei Möglichkeiten, Organisationen für deine App zu erstellen. -### Über die Logto Console erstellen \{#create-via-logto-console} +### Erstellung über Logto Console \{#create-via-logto-console} Erstelle Organisationen manuell in der Logto Console UI. Gehe zu Console > Organizations, um Organisationen zu erstellen, Mitglieder und Rollen zuzuweisen und die Anmeldeerfahrung der Organisation anzupassen. -Erstelle eine [Organisationstemplate](/authorization/organization-template), um ähnliche Organisationen, die die gleichen Rollen und Berechtigungen teilen, stapelweise zu erstellen. +Erstelle eine [Organisation-Vorlage](/authorization/organization-template), um ähnliche Organisationen, die die gleichen Rollen und Berechtigungen teilen, im Batch zu erstellen. -### Über die Logto Management API erstellen \{#create-via-logto-management-api} +### Erstellung über Logto Management API \{#create-via-logto-management-api} -Die Console eignet sich hervorragend für die manuelle Einrichtung, aber die meisten Apps ermöglichen es Endbenutzern, sich selbst zu bedienen – Organisationen direkt in deiner App zu erstellen und zu verwalten. Um dies zu ermöglichen, implementiere diese Funktionen mit der Logto Management API. +Die Console ist großartig für die manuelle Einrichtung, aber die meisten Apps ermöglichen es Endbenutzern, sich selbst zu bedienen – Organisationen direkt in deiner App zu erstellen und zu verwalten. Um dies zu ermöglichen, implementiere diese Funktionen mit der Logto Management API. :::note -Wenn du neu bei der Logto Management API bist, lies zuerst diese Seiten: +Wenn du neu bei der Logto Management API bist oder die grundlegende Einführung zur Nutzung der Logto Management API für die Organisationserfahrung noch nicht gelesen hast, lies zuerst diese: + + Richte deinen App-Service mit der Logto Management API ein + Management API -Mit Management API interagieren +Interaktion mit der Management API ::: -Angenommen, dein Backend ist über den Maschine-zu-Maschine (M2M) Mechanismus mit der Logto Management API verbunden und du hast ein M2M-Zugangstoken erhalten. +Angenommen, dein Backend ist über den Maschine-zu-Maschine (M2M)-Mechanismus mit der Logto Management API verbunden und du hast ein M2M-Zugangstoken erhalten. -Erstelle eine Organisation mit der Management API ([API-Referenz](https://openapi.logto.io/operation/operation-createorganization)): +Erstelle eine Organisation mit der Management API ([API-Referenzen](https://openapi.logto.io/operation/operation-createorganization)): ```bash curl \ @@ -70,6 +73,6 @@ Verpacke diese Aufrufe in deiner eigenen API-Schicht. Wenn Benutzer in deiner Ap ## Organisationstoken in Benutzeranfragen validieren \{#validating-organization-token-in-user-request} -In deiner App müssen Benutzer, wenn sie Aktionen im Kontext einer Organisation ausführen, ein Organisationstoken anstelle eines regulären Zugangstokens verwenden. Das Organisationstoken ist ein [JWT](https://auth.wiki/jwt), das Organisationsberechtigungen enthält. Wie bei jedem [Zugangstoken (Access token)](https://auth.wiki/access-token) kannst du die Ansprüche (Claims) dekodieren und den "scope"-Anspruch überprüfen, um Berechtigungen durchzusetzen. +In deiner App müssen Benutzer, wenn sie Aktionen im Kontext einer Organisation ausführen, ein Organisationstoken anstelle eines regulären Zugangstokens verwenden. Das Organisationstoken ist ein [JWT](https://auth.wiki/jwt), das Organisationsberechtigungen enthält. Wie jedes [Zugangstoken (Access token)](https://auth.wiki/access-token) kannst du die Ansprüche (Claims) dekodieren und den "scope"-Anspruch überprüfen, um Berechtigungen durchzusetzen. Siehe Autorisierung (Authorization) für weitere Informationen zu Autorisierungsszenarien und wie du Organisationstokens validierst. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index 93b934d92a6..6ad2ce1583f 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -8,15 +8,15 @@ sidebar_position: 4 Dies wird üblicherweise auf der Benutzerprofilseite verwendet, auf der Benutzer ihre Organisationsinformationen anzeigen müssen. -Organisation Benutzerinfo +Organisations-Benutzerinfo ## Wie wird es implementiert \{#how-to-implement-it} Es gibt zwei Möglichkeiten, Benutzerinformationen innerhalb einer Organisation abzurufen. -### 1. Den ID-Token dekodieren \{#1-decode-the-id-token} +### ID-Token entschlüsseln \{#decode-the-id-token} -Der ID-Token (ID token) ist ein standardisierter JWT, der Benutzerprofilinformationen und organisationsbezogene Ansprüche (Claims) enthält. Rufe die SDK-Methode `decodeIdToken()` auf, um ein JSON-Objekt wie dieses zu erhalten: +Das ID-Token (ID token) ist ein standardisiertes JWT, das Benutzerprofilinformationen und organisationsbezogene Ansprüche (Claims) enthält. Rufe die SDK-Methode `decodeIdToken()` auf, um ein JSON-Objekt wie dieses zu erhalten: ```json { @@ -42,8 +42,8 @@ Der ID-Token (ID token) ist ein standardisierter JWT, der Benutzerprofilinformat } ``` -Der ID-Token (ID token) wird jedoch nur während der Authentifizierung ausgestellt und kann veraltet sein, wenn sich das Benutzerprofil danach ändert. -Für die aktuellsten Informationen verwende die zweite Methode unten oder rufe `clearAllTokens()` auf und starte einen Authentifizierungsfluss neu, um einen frischen ID-Token (ID token) zu erhalten. +Das ID-Token (ID token) wird jedoch nur während der Authentifizierung ausgegeben und kann veraltet sein, wenn sich das Benutzerprofil danach ändert. +Für die aktuellsten Informationen verwende die zweite Methode unten oder rufe `clearAllTokens()` auf und starte einen Authentifizierungsablauf neu, um ein frisches ID-Token (ID token) zu erhalten. ```ts await logtoClient.clearAllTokens(); @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -Wenn die Sitzung noch gültig ist, wird der `signIn`-Aufruf ohne erneute Eingabe von Zugangsdaten zurück zu deiner App umleiten. Aus Sicht des Benutzers wird die App einfach aktualisiert und ein neuer ID-Token (ID token) wird im Hintergrund ausgestellt. +Wenn die Sitzung noch gültig ist, leitet der `signIn`-Aufruf ohne erneute Eingabe von Zugangsdaten zurück zu deiner App. Aus Sicht des Benutzers wird die App einfach aktualisiert und im Hintergrund ein neues ID-Token (ID token) ausgegeben. -### 2. Benutzerinformationen vom `/oidc/me`-Endpunkt abrufen \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### Benutzerinformationen vom `/oidc/me`-Endpunkt abrufen \{#fetch-user-info-from-the-oidc-me-endpoint} Du kannst auch `/oidc/me` anfragen, um Benutzerinformationen in Echtzeit im Organisationskontext zu erhalten. Rufe dazu die SDK-Methode `fetchUserInfo()` auf. 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 c95503edab5..d1b71857800 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,7 +4,7 @@ sidebar_position: 6 # Organisationsmitglieder einladen -In Multi-Organisations-Anwendungen ist es eine häufige Anforderung, Mitglieder zu einer Organisation einzuladen. Diese Anleitung führt durch die Schritte und technischen Details zur Implementierung dieser Funktion. +In Multi-Tenancy-Anwendungen ist es eine häufige Anforderung, Mitglieder zu einer Organisation einzuladen. Diese Anleitung führt durch die Schritte und technischen Details zur Implementierung dieser Funktion. ## Ablaufübersicht \{#flow-overview} @@ -17,21 +17,21 @@ sequenceDiagram Participant C as Deine Multi-Organisations-App Participant L as Logto - A ->> C: Eingabe der E-Mail-Adresse und Rolle des Eingeladenen + A ->> C: E-Mail und Rolle des Eingeladenen eingeben C ->> L: Organisationseinladung mit Management API erstellen - L -->> C: Rückgabe der Einladungs-ID - C ->> C: Einladungslink mit Einladungs-ID erstellen + L -->> C: Einladung-ID zurückgeben + C ->> C: Einladungslink mit Einladung-ID erstellen C ->> L: Anfordern des Versands der Einladungsemail mit Einladungslink - L -->> U: Versand der Einladungsemail mit Einladungslink - U ->> C: Klick auf den Einladungslink und Weiterleitung zu deiner Landingpage,
Einladung annehmen oder ablehnen - C ->> L: Aktualisierung des Einladungsstatus mit Management API + L -->> U: Einladungsemail mit Einladungslink senden + U ->> C: Klick auf Einladungslink und Weiterleitung zu deiner Landingpage,
Einladung annehmen oder ablehnen + C ->> L: Einladungsstatus mit Management API aktualisieren ``` ## Organisationsrollen erstellen \{#create-organization-roles} Bevor Mitglieder eingeladen werden, erstelle Organisationsrollen. Siehe die [Organisationstemplate](/authorization/organization-template), um mehr über Rollen und Berechtigungen zu erfahren. -In dieser Anleitung erstellen wir weiterhin zwei typische Organisationsrollen: `admin` und `member`. +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: @@ -82,15 +82,20 @@ Falls du die Logto Management API noch nicht eingerichtet hast, siehe [Mit Manag ### Organisationseinladung mit Logto Management API erstellen \{#create-an-organization-invitation-with-logto-management-api} -Es gibt eine Reihe von einladungsbezogenen Management APIs im Organisations-Feature. Mit diesen APIs kannst du: +Im Organisations-Feature gibt es eine Reihe von einladungsbezogenen Management APIs. Mit diesen APIs kannst du: - `POST /api/organization-invitations`: Eine Organisationseinladung mit zugewiesener Organisationsrolle erstellen. - `POST /api/one-time-tokens`: Ein Einmal-Token für den Eingeladenen erstellen, um sich zu authentifizieren, wenn er die Einladung annimmt. [Mehr erfahren](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message`: Die Organisationseinladung per E-Mail an den Eingeladenen senden. - Hinweis: Die Nutzlast unterstützt eine `link`-Eigenschaft, sodass du deinen eigenen Einladungslink basierend auf der Einladungs-ID erstellen kannst. Zum Beispiel: - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +Das Payload unterstützt eine `link`-Eigenschaft, sodass du deinen eigenen Einladungslink basierend auf der Einladung-ID erstellen kannst. Zum Beispiel: + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 59571c201b7..30693a531b0 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -6,9 +6,11 @@ sidebar_position: 7 ## Wo wird es verwendet \{#where-to-use-it} -Die Organisationsliste erscheint typischerweise während des Benutzer-Onboarding-Flows. Zum Beispiel, wenn ein Administrator dich einlädt, einem Arbeitsbereich beizutreten. +Die Organisationsliste und der Beitrittsprozess erscheinen in der Regel während des Benutzer-Onboardings. +Zum Beispiel, wenn ein Administrator jemanden zu einem Arbeitsbereich einlädt, der Benutzer jedoch die E-Mail-Einladung überspringt und sich direkt in der App anmeldet oder registriert. -Aus Produktsicht kann sie an zwei Hauptstellen erscheinen: +In deinem Produkt möchtest du möglicherweise Einstiegspunkte für diesen Ablauf hinzufügen. +Er kann an zwei Hauptstellen erscheinen: - Der **Organisationsfinder** während der Anmeldung oder Registrierung @@ -24,12 +26,12 @@ Aus Produktsicht kann sie an zwei Hauptstellen erscheinen: alt="Organisation innerhalb der App beitreten" /> -## Die Logto Management API verwenden, um Benutzern das Beitreten zu einer Organisation zu ermöglichen \{#use-the-logto-management-api-to-let-users-join-an-organization} +## Verwende die Logto Management API, um Benutzern den Beitritt zu einer Organisation zu ermöglichen \{#use-the-logto-management-api-to-let-users-join-an-organization} Im vorherigen Abschnitt haben wir das Erstellen und Versenden von Organisationseinladungen mit der Logto Management API behandelt. Als Nächstes implementierst du eine Landingpage, die den Einladungslink verarbeitet, wenn Eingeladene in deiner Anwendung ankommen. -- `GET /api/organization-invitations` und `GET /api/organization-invitations/{id}`: Hole alle Einladungen oder eine bestimmte Einladung per ID. +- `GET /api/organization-invitations` und `GET /api/organization-invitations/{id}`: Alle Einladungen oder eine bestimmte Einladung per ID abrufen. Verwende diese APIs auf deiner Landingpage, um alle Einladungen aufzulisten oder die Details einer bestimmten Einladung anzuzeigen, die der Benutzer erhalten hat. -- `PUT /api/organization-invitations/{id}/status`: Akzeptiere oder lehne die Einladung ab, indem du ihren Status aktualisierst. - Verwende diese API, um auf die Antwort des Benutzers zu reagieren. +- `PUT /api/organization-invitations/{id}/status`: Die Einladung annehmen oder ablehnen, indem der Status aktualisiert wird. + Verwende diese API, um die Antwort des Benutzers zu verarbeiten. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 4090b27ca6c..c0eeecb27c9 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,47 +2,54 @@ sidebar_position: 8 --- -# Berechtigungs- und Ressourcenverwaltung +# Umgang mit Berechtigungsaktualisierungen in Organisationstokens -Verwende die Organisation als Ressource und wende eine Organisationstemplate an, um sie zu schützen. Zum Beispiel hat jede Organisation innerhalb eines Mandanten ihre eigenen Dokumente. Nur Benutzer mit den richtigen Rollen können diese Dokumente bearbeiten oder löschen. +Mit der obigen Einrichtung kannst du Einladungen per E-Mail versenden, und Eingeladene können der Organisation mit der zugewiesenen Rolle beitreten. -Siehe [Organisationsberechtigungen](/authorization/organization-permissions) für Details. +Benutzer mit unterschiedlichen Organisationsrollen haben unterschiedliche Berechtigungen (Scopes) in ihren Organisationstokens. Sowohl deine Client-App als auch Backend-Services sollten diese Berechtigungen prüfen, um sichtbare Funktionen und erlaubte Aktionen zu bestimmen. -## Verwende organisationsbasierte rollenbasierte Zugangskontrolle (RBAC), um Benutzerberechtigungen zu verwalten \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +Wie bereits erwähnt, dient die Organisationstemplate als zentrale Zugangskontrollschicht zum Schutz von [Organisationsberechtigungen](/authorization/organization-permissions) oder [organisationsbezogenen APIs](/authorization/organization-level-api-resources). Überprüfe unbedingt die Autorisierungsabschnitte und wähle das Autorisierungsmodell, das am besten zu deinem Produkt passt. -Mit der obigen Einrichtung kannst du Einladungen per E-Mail versenden, und Eingeladene können der Organisation mit der zugewiesenen Rolle beitreten. +:::note -Benutzer mit unterschiedlichen Organisationsrollen haben unterschiedliche Berechtigungen (Scopes) in ihren Organisationstokens. Sowohl deine Client-App als auch Backend-Services sollten diese Berechtigungen prüfen, um sichtbare Funktionen und erlaubte Aktionen zu bestimmen. + + Organisation (Nicht-API) Berechtigungen schützen + + + Organisationsebene API-Ressourcen schützen + -## Umgang mit Berechtigungsaktualisierungen in Organisationstokens \{#handle-scope-updates-in-organization-tokens} +::: + +Dieses Kapitel konzentriert sich auf das **Berechtigungsmanagement** und Best Practices für den **Umgang mit Berechtigungsänderungen und Berechtigungen** in Logto Organisationstokens. -Dieser Abschnitt behandelt fortgeschrittene Themen zur Verwaltung des Organisationstemplates und Autorisierungsszenarien. Wenn du mit diesen Konzepten nicht vertraut bist, lies zuerst [Autorisierung](/authorization) und [Organisationstemplate](/authorization/organization-template). +## Umgang mit Berechtigungsaktualisierungen in Organisationstokens \{#handle-scope-updates-in-organization-tokens} -Die Verwaltung von Berechtigungsaktualisierungen in Organisationstokens umfasst: +Das Verwalten von Berechtigungsaktualisierungen in Organisationstokens umfasst: -### Vorhandene Berechtigungen widerrufen \{#revoke-existing-scopes} +### Bestehende Berechtigungen widerrufen \{#revoke-existing-scopes} -Zum Beispiel sollte das Herabstufen eines Admins zu einem Nicht-Admin-Mitglied Berechtigungen vom Benutzer entfernen. In solchen Fällen lösche das zwischengespeicherte Organisationstoken und hole ein neues mit einem Auffrischungstoken. Die reduzierten Berechtigungen werden sofort im neu ausgestellten Organisationstoken widergespiegelt. +Wenn beispielsweise ein Admin zu einem Nicht-Admin-Mitglied herabgestuft wird, sollten Berechtigungen vom Benutzer entfernt werden. In solchen Fällen lösche das zwischengespeicherte Organisationstoken und fordere mit einem Auffrischungstoken ein neues an. Die reduzierten Berechtigungen werden sofort im neu ausgestellten Organisationstoken widergespiegelt. ### Neue Berechtigungen gewähren \{#grant-new-scopes} -Dies kann in zwei Szenarien unterteilt werden: +Dies lässt sich in zwei Szenarien unterteilen: #### Neue Berechtigungen gewähren, die bereits in deinem Auth-System definiert sind \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -Ähnlich wie beim Widerrufen von Berechtigungen: Wenn die neu gewährte Berechtigung bereits beim Auth-Server registriert ist, stelle ein neues Organisationstoken aus und die neuen Berechtigungen werden sofort widergespiegelt. +Ähnlich wie beim Widerrufen von Berechtigungen: Wenn die neu gewährte Berechtigung bereits beim Auth-Server registriert ist, stelle ein neues Organisationstoken aus und die neuen Berechtigungen werden sofort übernommen. -#### Neue Berechtigungen gewähren, die neu in dein Auth-System eingeführt wurden \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### Neue Berechtigungen gewähren, die neu in deinem Auth-System eingeführt wurden \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} In diesem Fall löse einen erneuten Anmelde- oder Zustimmungsprozess aus, um das Organisationstoken des Benutzers zu aktualisieren. Rufe zum Beispiel die `signIn`-Methode im Logto SDK auf. ## Berechtigungen in Echtzeit prüfen und das Organisationstoken aktualisieren \{#check-permissions-in-real-time-and-update-the-organization-token} -Logto stellt eine Management API bereit, um die aktuellen Benutzerberechtigungen in der Organisation in Echtzeit abzurufen. +Logto stellt eine Management API bereit, um die aktuellen Benutzerberechtigungen in der Organisation abzurufen. - `GET /api/organizations/{id}/users/{userId}/scopes` ([API-Referenzen](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -Vergleiche die Berechtigungen im Organisationstoken des Benutzers mit den Echtzeit-Berechtigungen, um festzustellen, ob der Benutzer befördert oder herabgestuft wurde. +Vergleiche die Berechtigungen im Organisationstoken des Benutzers mit den aktuellen Berechtigungen, um festzustellen, ob der Benutzer befördert oder herabgestuft wurde. - Wenn herabgestuft, lösche das zwischengespeicherte Organisationstoken und das SDK stellt automatisch ein neues mit den aktualisierten Berechtigungen aus. @@ -50,20 +57,20 @@ Vergleiche die Berechtigungen im Organisationstoken des Benutzers mit den Echtze const { clearAccessToken } = useLogto(); ... - // Wenn die abgerufenen Echtzeit-Berechtigungen weniger Berechtigungen haben als die Organisationstoken-Berechtigungen + // Wenn die abgerufenen Echtzeit-Berechtigungen weniger Berechtigungen enthalten als das Organisationstoken await clearAccessToken(); ``` Dies erfordert keinen erneuten Anmelde- oder Zustimmungsprozess. Neue Organisationstokens werden automatisch vom Logto SDK ausgestellt. -- Wenn eine neue Berechtigung in dein Auth-System eingeführt wird, löse einen erneuten Anmelde- oder Zustimmungsprozess aus, um das Organisationstoken des Benutzers zu aktualisieren. Zum Beispiel mit dem React SDK: +- Wenn eine neue Berechtigung in deinem Auth-System eingeführt wird, löse einen erneuten Anmelde- oder Zustimmungsprozess aus, um das Organisationstoken des Benutzers zu aktualisieren. Zum Beispiel mit dem React SDK: ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // Wenn die abgerufenen Echtzeit-Berechtigungen neu zugewiesene Berechtigungen haben als die Organisationstoken-Berechtigungen + // Wenn die abgerufenen Echtzeit-Berechtigungen neu zugewiesene Berechtigungen enthalten, die das Organisationstoken noch nicht hat await clearAllTokens(); signIn({ redirectUri: '', diff --git a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index 6dc62d718cc..101c7cb3df1 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,23 +4,24 @@ sidebar_position: 2 # Richte deinen App-Service mit der Logto Management API ein -Nutze die Logto **Management API**, um benutzerdefinierte **Organisationsabläufe** in deiner App zu erstellen. Nachfolgend findest du die grundlegenden Einrichtungsschritte für die Integration der Management API. Wenn du bereits vertraut bist, kannst du direkt zum [Tutorial](/integrate-logto/interact-with-management-api) springen. +Logto bietet eine leistungsstarke Management API, mit der du deinen eigenen Organisations-Flow innerhalb deiner App erstellen und anpassen kannst. +Zu verstehen, wie sie funktioniert, ist entscheidend für die Gestaltung deines individuellen Setups. Nachfolgend findest du die grundlegenden Schritte und eine Übersicht zur Integration der Management API, um deine Organisationserfahrung umzusetzen. -Sobald du mit der Einrichtung vertraut bist, kannst du zusätzliche APIs erkunden, um die restlichen Abläufe an deine Geschäftsanforderungen anzupassen. +Wenn du die Grundlagen bereits kennst, kannst du direkt zum [Tutorial](/integrate-logto/interact-with-management-api) springen. Sobald du mit dem Setup vertraut bist, kannst du zusätzliche APIs erkunden, um die restlichen Abläufe an deine Geschäftsanforderungen anzupassen. -## Aufbau einer Maschine-zu-Maschine-Verbindung \{#establish-a-machine-to-machine-connection} +## Etabliere eine Maschine-zu-Maschine-Verbindung \{#establish-a-machine-to-machine-connection} -Logto verwendet **Maschine‑zu‑Maschine (M2M) Authentifizierung**, um deinen Backend-Service sicher mit dem Logto Management API-Endpunkt zu verbinden. +Logto verwendet **Maschine‑zu‑Maschine (M2M) Authentifizierung** (Machine-to-machine (M2M) authentication), um deinen Backend-Service sicher mit dem Logto Management API-Endpunkt zu verbinden. Dein Backend-Service kann dann die Management API nutzen, um organisationsbezogene Aufgaben wie **Organisationen erstellen**, **Mitglieder hinzufügen oder entfernen** und mehr zu erledigen. -Dies umfasst: +Das beinhaltet: -1. **Erstelle eine Maschine-zu-Maschine (M2M) App** in der Logto Console. +1. **Erstelle eine Maschine-zu-Maschine (M2M) App** in der Logto-Konsole. -M2M-App-Details +M2M app details -2. **Erhalte ein M2M Zugangstoken** von Logto. [Mehr erfahren](/integrate-logto/interact-with-management-api#fetch-an-access-token). -3. **Rufe Logto Management APIs** von deinem Backend-Service auf. Zum Beispiel, um alle Organisationen aufzulisten: +2. **Erhalte ein M2M Zugangstoken** (access token) von Logto. [Mehr erfahren](/integrate-logto/interact-with-management-api#fetch-an-access-token). +3. **Rufe Logto Management APIs** von deinem Backend-Service aus auf. Zum Beispiel, um alle Organisationen aufzulisten: ```bash curl \ @@ -31,17 +32,17 @@ curl \ ## Schütze deinen App-Server \{#protect-your-app-server} -Da Endbenutzer bestimmte Organisationsoperationen selbstständig durchführen können, füge eine Autorisierungsschicht zwischen dem Endbenutzer und deinem App-Server hinzu. Der Server sollte jede Anfrage vermitteln, das organisationsbezogene Token des Benutzers und die erforderlichen Berechtigungen validieren und erst dann ein serverseitig gehaltenes M2M-Zertifikat verwenden, um die Management API aufzurufen. +Da Endbenutzer bestimmte Organisationsaktionen selbst durchführen können, ist es wichtig, eine Autorisierungsschicht zwischen dem Endbenutzer und deinem App-Server einzufügen. Du kannst diese Schicht global oder auf Organisationsebene anwenden, abhängig davon, welche Logto Management API-Endpunkte du verwendest und wie die API deines Produkts strukturiert ist. Der Server sollte jede Anfrage vermitteln, das organisationsbezogene Token des Benutzers und die erforderlichen Berechtigungen (scopes) validieren und erst dann mit einem serverseitig gehaltenen M2M-Zugang die Management API aufrufen. -Wenn ein Benutzer ein Organisationstoken präsentiert, um eine Aktion anzufordern (zum Beispiel das Erstellen einer Organisation), validiert der Server zuerst die Berechtigungen im Token. Wenn das Token die notwendige Berechtigung wie `org:create` enthält, autorisiere die Anfrage und rufe die Logto Management API über den M2M-Flow auf, um die Organisation zu erstellen. +Wenn ein Benutzer ein Organisationstoken (organization token) vorlegt, um eine Aktion anzufordern (zum Beispiel das Erstellen einer Organisation), validiert der Server zuerst die Berechtigungen (scopes) im Token. Wenn das Token die erforderliche Berechtigung wie `org:create` enthält, autorisiere die Anfrage und rufe die Logto Management API über den M2M-Flow auf, um die Organisation zu erstellen. -Enthält das Token nicht die erforderlichen Berechtigungen, gib einen 403 Forbidden zurück und überspringe die M2M-Logik. So wird sichergestellt, dass Benutzer ohne entsprechende Privilegien keine Organisationen erstellen können. +Enthält das Token nicht die erforderlichen Berechtigungen, gib einen 403 Forbidden zurück und überspringe die M2M-Logik. So wird sichergestellt, dass Benutzer ohne die entsprechenden Privilegien keine Organisationen erstellen können. Nachfolgend findest du gängige Autorisierungsmuster. ### Verwendung von Organisationsberechtigungen \{#using-organization-permissions} -Stelle zunächst sicher, dass du Organisationsberechtigungen und Rollen in deiner Organisationstemplate im [vorherigen Abschnitt](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) definiert hast. +Stelle zunächst sicher, dass du Organisationsberechtigungen (organization permissions) und Rollen (roles) in deiner Organisationstemplate im [vorherigen Abschnitt](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) definiert hast. Stelle dann sicher, dass `UserScope.Organizations` (Wert: `urn:logto:organization`) in der Logto-Konfiguration enthalten ist. Am Beispiel des React SDK: @@ -53,7 +54,7 @@ const config = { endpoint: 'https://.logto.app/', // Dein Logto-Endpunkt appId: '40fmibayagoo00lj26coc', // Deine App-ID resources: [ - 'https://my.company.com/api', // Dein globaler API-Ressourcen-Identifier + 'https://my.company.com/api', // Dein globaler API-Ressourcen-Identifikator ], scopes: [ UserScope.Email, @@ -61,20 +62,30 @@ const config = { UserScope.CustomData, UserScope.Identities, // highlight-start - UserScope.Organizations, // Organisationstoken anfordern + UserScope.Organizations, // Fordere ein Organisationstoken an // highlight-end ], }; ``` -Dies stellt sicher, dass beim Aufruf von `getOrganizationToken(organizationId)` das Client-SDK ein Organisationstoken anfordert, das die dem Benutzer zugewiesenen Organisationsberechtigungen enthält. Dein Backend-Service kann dann das Token validieren und nach diesen Berechtigungen nachfolgende Anfragen autorisieren. +So wird sichergestellt, dass beim Aufruf von `getOrganizationToken(organizationId)` das Client-SDK ein Organisationstoken anfordert, das die dem Benutzer zugewiesenen Organisationsberechtigungen enthält. Dein Backend-Service kann dann das Token validieren und nach diesen Berechtigungen nachfolgende Anfragen autorisieren. -Details zum Schutz von organisationsbezogenen (nicht-API) Berechtigungen findest du im [vollständigen Leitfaden](/authorization/organization-permissions). +Details zum Schutz von organisationsbezogenen (nicht-API-)Berechtigungen findest du im [vollständigen Leitfaden](/authorization/organization-permissions). -### Kombination von organisationsbezogenen Berechtigungen und API-Berechtigungen \{#mixing-organization-level-permissions-and-api-level-permissions} +### Verwendung von API-Ebene-Berechtigungen \{#using-api-level-permissions} -Dies gilt, wenn deine API-Ressourcen und Berechtigungen global registriert sind, aber Rollen auf Organisationsebene definiert werden (du kannst API-Berechtigungen zu Organisationsrollen im Organisationstemplate zuweisen). +Dies gilt, wenn deine API-Ressourcen und Berechtigungen global registriert sind, aber Rollen auf Organisationsebene definiert werden (du kannst API-Ebene-Berechtigungen zu Organisationsrollen im Organisationstemplate zuweisen). -Die Implementierung ist identisch mit dem vorherigen Abschnitt. Gib immer die Organisations-ID an und rufe `getOrganizationToken(organizationId)` auf, um ein Organisationstoken zu erhalten; andernfalls werden Organisationsberechtigungen nicht enthalten sein. +Die Implementierung ist identisch mit dem vorherigen Abschnitt. Gib immer die Organisations-ID an und rufe `getOrganizationToken(organizationId)` auf, um ein Organisationstoken zu erhalten; andernfalls werden keine Organisationsberechtigungen enthalten sein. Details zum Schutz von organisationsbezogenen API-Berechtigungen findest du im [vollständigen Leitfaden](/authorization/organization-level-api-resources). + +### Verwendung von globalem RBAC \{#using-global-rbac} + +In diesem Fall kannst du die Logto Management API nutzen, um systemweite Zugangskontrolle zu implementieren. + +In einer Multi-Tenant-Umgebung ist ein gängiges Muster die Einführung einer Superuser- oder Superadmin-Rolle. Wenn du beispielsweise eine SaaS-Plattform mit Logto aufbaust, möchtest du vielleicht einen Superuser, der alle Kundenorganisationen direkt in deiner eigenen App verwalten kann, ohne sich in der Logto-Konsole anmelden zu müssen. + +Dieser Superuser kann höherstufige Aktionen durchführen, wie das Erstellen oder Löschen von Organisationen in großen Mengen, die systemweite Berechtigungen über den Kontext einer einzelnen Organisation hinaus erfordern. Um dies zu ermöglichen, registriere eine API-Ressource in Logto, nutze die Logto Management API und verwalte diese Berechtigungen mit globalem RBAC. + +Weitere Details zur Integration und Verwaltung der Zugangskontrolle für RBAC findest du im [vollständigen Leitfaden](/authorization/global-api-resources). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index ddf76a1c29b..3ddcbd8ec76 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -26,18 +26,21 @@ Crea una [plantilla de organización](/authorization/organization-template) para ### Crear a través de Logto Management API \{#create-via-logto-management-api} -La Console es ideal para la configuración manual, pero la mayoría de las aplicaciones permiten a los usuarios finales autogestionarse: crear y administrar organizaciones directamente en tu aplicación. Para ello, implementa estas funciones con la Logto Management API. +La consola es ideal para la configuración manual, pero la mayoría de las aplicaciones permiten a los usuarios finales autogestionarse: crear y administrar organizaciones directamente en tu aplicación. Para ello, implementa estas funciones con la Logto Management API. :::note -Si eres nuevo en la Logto Management API, lee esto primero: +Si eres nuevo en la Logto Management API o no has leído la introducción básica sobre el uso de la Logto Management API para la experiencia de organización, lee esto primero: + + Configura tu servicio de aplicación con la Logto Management API + Management API -Interact with Management API +Interactúa con Management API ::: -Supón que tu backend está conectado a la Logto Management API mediante el mecanismo máquina a máquina (M2M), y has obtenido un token de acceso M2M. +Supón que tu backend está conectado a la Logto Management API mediante el mecanismo máquina a máquina (M2M), y que has obtenido un token de acceso M2M. Crea una organización con la Management API ([referencias de API](https://openapi.logto.io/operation/operation-createorganization)): diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index b6eefbca3b6..e43bbf0cbd8 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -12,9 +12,9 @@ Esto se utiliza normalmente en la página de perfil de usuario donde los usuario ## Cómo implementarlo \{#how-to-implement-it} -Hay dos formas de obtener la información del usuario dentro de una organización. +Hay dos formas de obtener información del usuario dentro de una organización. -### 1. Decodificar el token de ID (ID token) \{#1-decode-the-id-token} +### Decodificar el token de ID \{#decode-the-id-token} El token de ID (ID token) es un JWT estándar que contiene información del perfil del usuario y reclamos relacionados con la organización. Llama al método del SDK `decodeIdToken()` para obtener un objeto JSON como este: @@ -43,7 +43,7 @@ El token de ID (ID token) es un JWT estándar que contiene información del perf ``` Sin embargo, el token de ID (ID token) solo se emite durante la autenticación y puede quedar desactualizado si el perfil del usuario cambia después. -Para obtener la información más actualizada, utiliza el segundo enfoque a continuación, o llama a `clearAllTokens()` y reinicia un flujo de autenticación para obtener un nuevo token de ID (ID token). +Para obtener la información más actualizada, utiliza el segundo enfoque a continuación, o llama a `clearAllTokens()` y reinicia un flujo de autenticación para obtener un nuevo token de ID. ```ts await logtoClient.clearAllTokens(); @@ -55,6 +55,6 @@ logtoClient.signIn({ Si la sesión sigue siendo válida, la llamada a `signIn` redirigirá de vuelta a tu aplicación sin requerir credenciales. Desde la perspectiva del usuario, la aplicación simplemente se actualiza y se emite un nuevo token de ID (ID token) en segundo plano. -### 2. Obtener información del usuario desde el endpoint `/oidc/me` \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### Obtener información del usuario desde el endpoint `/oidc/me` \{#fetch-user-info-from-the-oidc-me-endpoint} También puedes solicitar `/oidc/me` para obtener información del usuario en tiempo real en el contexto de la organización. Llama al método del SDK `fetchUserInfo()`. 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 cd721f82704..dc0655bf27d 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 @@ -4,7 +4,7 @@ sidebar_position: 6 # Invitar miembros a la organización -En aplicaciones multi‑organización, un requisito común es invitar miembros a una organización. Esta guía recorre los pasos y detalles técnicos para implementar esta funcionalidad. +En aplicaciones multi‑tenant, un requisito común es invitar miembros a una organización. Esta guía te muestra los pasos y detalles técnicos para implementar esta funcionalidad. ## Descripción general del flujo \{#flow-overview} @@ -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 actualmente no admite el tipo de uso `OrganizationInvitation`. Configura tu propio conector de correo electrónico (por ejemplo, SendGrid) y configura la plantilla `OrganizationInvitation` en su lugar. +El “servicio de correo electrónico de Logto” incorporado en Logto Cloud actualmente no admite el tipo de uso `OrganizationInvitation`. Configura tu propio conector de correo electrónico (por ejemplo, SendGrid) y configura la plantilla `OrganizationInvitation` en su lugar. ::: @@ -82,15 +82,20 @@ Si aún no has configurado la Logto Management API, consulta [Interactuar con Ma ### Crear una invitación de organización con Logto Management API \{#create-an-organization-invitation-with-logto-management-api} -Hay un conjunto de Management APIs relacionadas con invitaciones en la funcionalidad de organizaciones. Con estas APIs, puedes: +Existe un conjunto de Management APIs relacionadas con invitaciones en la funcionalidad 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/one-time-tokens`: Crear un token de un solo uso para que el invitado se autentique cuando acepte la invitación. [Aprende más](/end-user-flows/one-time-token) -- `POST /api/organization-invitations/{id}/message`: Enviar la invitación de organización al invitado por correo electrónico. - Nota: El payload admite una propiedad `link` para que puedas componer tu propio enlace de invitación basado en el ID de la invitación. Por ejemplo: - - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +- `POST /api/organization-invitations/{id}/message`: Enviar la invitación de la organización al invitado por correo electrónico. + +:::note + +El payload admite una propiedad `link` para que puedas componer tu propio enlace de invitación basado en el ID de la invitación. Por ejemplo: + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 19ca7d65e30..a830fb3b220 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -4,11 +4,13 @@ sidebar_position: 7 # Unirse a la organización -## Dónde se utiliza \{#where-to-use-it} +## Dónde usarlo \{#where-to-use-it} -La lista de organizaciones suele aparecer durante el flujo de incorporación de usuarios. Por ejemplo, cuando un administrador te invita a un espacio de trabajo. +La lista de organizaciones y el flujo para unirse suelen aparecer durante la incorporación de usuarios. +Por ejemplo, cuando un administrador invita a alguien a un espacio de trabajo, pero el usuario omite la invitación por correo electrónico e inicia sesión o se registra directamente en la aplicación. -Desde la perspectiva del producto, puede aparecer en dos lugares principales: +En tu producto, puedes querer añadir puntos de entrada para este flujo. +Puede aparecer en dos lugares principales: - El **buscador de organizaciones** durante el inicio de sesión o registro @@ -32,4 +34,4 @@ A continuación, implementa una página de destino que maneje el enlace de invit - `GET /api/organization-invitations` y `GET /api/organization-invitations/{id}`: Obtén todas las invitaciones o una específica por ID. En tu página de destino, utiliza estas APIs para listar todas las invitaciones o mostrar los detalles de una invitación específica que el usuario haya recibido. - `PUT /api/organization-invitations/{id}/status`: Acepta o rechaza la invitación actualizando su estado. - Utiliza esta API para manejar la respuesta del usuario. + Usa esta API para manejar la respuesta del usuario. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 5bf3a586147..7d7b38d06e1 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,41 +2,46 @@ sidebar_position: 8 --- -# Gestión de permisos y recursos +# Gestionar actualizaciones de alcances en los tokens de organización -Utiliza la organización como un recurso y aplica una plantilla de organización para protegerlo. Por ejemplo, cada organización tiene sus propios documentos dentro de un inquilino. Solo los usuarios con los roles adecuados pueden editar o eliminar esos documentos. +Con la configuración anterior, puedes enviar invitaciones por correo electrónico, y los invitados pueden unirse a la organización con el rol asignado. -Consulta [Permisos de organización](/authorization/organization-permissions) para más detalles. +Los usuarios con diferentes roles de organización tendrán diferentes alcances (permisos) en sus tokens de organización. Tanto tu aplicación cliente como los servicios backend deben comprobar estos alcances para determinar las funciones visibles y las acciones permitidas. -## Usa el control de acceso basado en roles (RBAC) de la organización para gestionar los permisos de los usuarios \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +Como se mencionó anteriormente, la plantilla de organización sirve como una capa clave de control de acceso para proteger [permisos de organización](/authorization/organization-permissions) o [APIs a nivel de organización](/authorization/organization-level-api-resources). Asegúrate de revisar las secciones de autorización y elegir el modelo de autorización que mejor se adapte a tu producto. -Con la configuración anterior, puedes enviar invitaciones por correo electrónico, y los invitados pueden unirse a la organización con el rol asignado. +:::note -Los usuarios con diferentes roles de organización tendrán diferentes alcances (permisos) en sus tokens de organización. Tanto tu aplicación cliente como los servicios backend deben comprobar estos alcances para determinar las funciones visibles y las acciones permitidas. +Proteger permisos de organización (no API) + + Proteger recursos de API a nivel de organización + + +::: -## Gestiona las actualizaciones de alcance en los tokens de organización \{#handle-scope-updates-in-organization-tokens} +Este capítulo se centra en la **gestión de permisos** y las mejores prácticas para **gestionar cambios de alcances y permisos** en los tokens de organización de Logto. -Esta sección cubre temas avanzados sobre la gestión de la plantilla de organización y escenarios de autorización. Si no estás familiarizado con estos conceptos, lee primero [Autorización (Authorization)](/authorization) y [Plantilla de organización](/authorization/organization-template). +## Gestionar actualizaciones de alcances en los tokens de organización \{#handle-scope-updates-in-organization-tokens} -Gestionar las actualizaciones de alcance en los tokens de organización implica: +Gestionar actualizaciones de alcances en los tokens de organización implica: ### Revocar alcances existentes \{#revoke-existing-scopes} -Por ejemplo, degradar a un administrador a un miembro no administrador debería eliminar los alcances del usuario. En tales casos, borra el token de organización en caché y obtén uno nuevo con un token de actualización. Los alcances reducidos se reflejarán inmediatamente en el nuevo token de organización emitido. +Por ejemplo, degradar a un administrador a un miembro no administrador debe eliminar los alcances del usuario. En tales casos, borra el token de organización en caché y obtén uno nuevo con un token de actualización. Los alcances reducidos se reflejarán inmediatamente en el nuevo token de organización emitido. -### Conceder nuevos alcances \{#grant-new-scopes} +### Otorgar nuevos alcances \{#grant-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-are-already-defined-in-your-auth-system} +#### Otorgar nuevos alcances que ya están definidos en tu sistema de autenticación \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -Similar a la revocación de alcances, si el nuevo alcance concedido ya está registrado en el servidor de autenticación, emite un nuevo token de organización y los nuevos alcances se reflejarán inmediatamente. +Similar a la revocación de alcances, si el nuevo alcance otorgado ya está registrado en el servidor de autenticación, emite un nuevo token de organización y los nuevos alcances se reflejarán inmediatamente. -#### Conceder nuevos alcances que se introducen por primera vez en tu sistema de autenticación \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### Otorgar nuevos alcances que se introducen por primera vez en tu sistema de autenticación \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} En este caso, activa un proceso de re‑inicio de sesión o re‑consentimiento para actualizar el token de organización del usuario. Por ejemplo, llama al método `signIn` en el SDK de Logto. -## Comprueba los permisos en tiempo real y actualiza el token de organización \{#check-permissions-in-real-time-and-update-the-organization-token} +## Comprobar permisos en tiempo real y actualizar el token de organización \{#check-permissions-in-real-time-and-update-the-organization-token} Logto proporciona una Management API para obtener los permisos de usuario en tiempo real en la organización. @@ -55,7 +60,7 @@ Compara los alcances en el token de organización del usuario con los permisos e ``` - Esto no requiere un proceso de re‑inicio de sesión ni de re‑consentimiento. Los nuevos tokens de organización se emitirán automáticamente por el SDK de Logto. + Esto no requiere un proceso de re‑inicio de sesión ni de re‑consentimiento. Los nuevos tokens de organización serán emitidos automáticamente por el SDK de Logto. - 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. Por ejemplo, con el SDK de React: @@ -63,7 +68,7 @@ Compara los alcances en el token de organización del usuario con los permisos e const { clearAllTokens, signIn } = useLogto(); ... - // Si los alcances obtenidos en tiempo real tienen nuevos alcances asignados que los del token de organización + // Si los alcances obtenidos en tiempo real incluyen nuevos alcances asignados que el token de organización no tiene await clearAllTokens(); signIn({ redirectUri: '', diff --git a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index 5b166ff15f2..e03caabc3c9 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -2,22 +2,23 @@ sidebar_position: 2 --- -# Configura el servicio de tu aplicación con la Management API de Logto +# Configura tu servicio de aplicación con la Management API de Logto -Utiliza la **Management API** de Logto para construir flujos personalizados de **organización** en tu aplicación. A continuación se muestran los pasos básicos para integrar la Management API. Si ya estás familiarizado, puedes saltar directamente al [tutorial](/integrate-logto/interact-with-management-api). +Logto ofrece una potente Management API que te permite crear y personalizar tu propio flujo de organización dentro de tu aplicación. +Comprender cómo funciona es clave para diseñar tu configuración personalizada. A continuación se presentan los pasos básicos y el esquema para integrar la Management API e implementar tu experiencia de organización. -Una vez que te familiarices con la configuración, puedes explorar APIs adicionales para adaptar el resto de los flujos a las necesidades de tu negocio. +Si ya conoces lo básico, puedes saltar directamente al [tutorial](/integrate-logto/interact-with-management-api). Una vez que estés familiarizado con la configuración, puedes explorar APIs adicionales para adaptar el resto de los flujos a las necesidades de tu negocio. ## Establece una conexión máquina a máquina \{#establish-a-machine-to-machine-connection} Logto utiliza la **autenticación máquina a máquina (M2M)** para conectar de forma segura tu servicio backend con el endpoint de la Management API de Logto. -Tu servicio backend puede entonces utilizar la Management API para manejar tareas relacionadas con la organización, como **crear organizaciones**, **agregar o eliminar miembros**, y más. +Tu servicio backend puede entonces usar la Management API para manejar tareas relacionadas con organizaciones como **crear organizaciones**, **agregar o eliminar miembros**, y más. Esto implica: 1. **Crear una aplicación Máquina a Máquina (M2M)** en la Consola de Logto. -Detalles de la aplicación M2M +Detalles de la app M2M 2. **Adquirir un token de acceso M2M** de Logto. [Aprende más](/integrate-logto/interact-with-management-api#fetch-an-access-token). 3. **Llamar a las Management APIs de Logto** desde tu servicio backend. Por ejemplo, listar todas las organizaciones: @@ -29,9 +30,9 @@ curl \ -H "Content-Type: application/json" ``` -## Protege el servidor de tu aplicación \{#protect-your-app-server} +## Protege tu servidor de aplicaciones \{#protect-your-app-server} -Debido a que los usuarios finales pueden realizar ciertas operaciones de organización por sí mismos, añade una capa de autorización entre el usuario final y el servidor de tu aplicación. El servidor debe mediar cada solicitud, validar el token de organización del usuario y los alcances requeridos, y solo entonces utilizar una credencial M2M mantenida en el servidor para invocar la Management API. +Dado que los usuarios finales pueden realizar ciertas acciones de organización por sí mismos, es importante añadir una capa de autorización entre el usuario final y tu servidor de aplicaciones. Puedes aplicar esta capa globalmente o a nivel de organización, dependiendo de qué endpoints de la Management API de Logto utilices y cómo esté estructurada la API de tu producto. El servidor debe mediar cada solicitud, validar el token de organización del usuario y los alcances requeridos, y solo entonces usar una credencial M2M mantenida en el servidor para invocar la Management API. Cuando un usuario presenta un token de organización para solicitar una acción (por ejemplo, crear una organización), el servidor primero valida los alcances en el token. Si el token incluye el alcance necesario, como `org:create`, autoriza la solicitud y llama a la Management API de Logto mediante el flujo M2M para crear la organización. @@ -43,7 +44,7 @@ A continuación se muestran patrones comunes de autorización. Primero, asegúrate de haber definido permisos y roles de organización en tu plantilla de organización en [la sección anterior](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations). -Luego, asegúrate de que `UserScope.Organizations` (valor: `urn:logto:organization`) esté incluido en la configuración de Logto. Toma como ejemplo el SDK de React: +Luego, asegúrate de que `UserScope.Organizations` (valor: `urn:logto:organization`) esté incluido en la configuración de Logto. Tomando el SDK de React como ejemplo: ```jsx // src/App.js @@ -69,12 +70,22 @@ const config = { Esto asegura que al llamar a `getOrganizationToken(organizationId)`, el SDK del cliente solicite un token de organización que contenga los permisos de organización asignados al usuario. Tu servicio backend puede entonces validar el token y autorizar solicitudes posteriores basándose en estos permisos. -Para más detalles sobre cómo proteger permisos a nivel de organización (no de API), consulta la [guía completa](/authorization/organization-permissions). +Para detalles sobre cómo proteger permisos de organización (no de API), consulta la [guía completa](/authorization/organization-permissions). -### Mezclando permisos a nivel de organización y permisos a nivel de API \{#mixing-organization-level-permissions-and-api-level-permissions} +### Usando permisos a nivel de API \{#using-api-level-permissions} -Esto aplica cuando tus recursos y permisos de API están registrados globalmente, pero los roles se definen a nivel de organización (puedes asignar permisos de API a roles de organización en la plantilla de organización). +Esto aplica cuando tus recursos de API y permisos están registrados globalmente, pero los roles se definen a nivel de organización (puedes asignar permisos a nivel de API a roles de organización en la plantilla de organización). La implementación es la misma que en la sección anterior. Siempre proporciona el ID de la organización y llama a `getOrganizationToken(organizationId)` para obtener un token de organización; de lo contrario, los permisos de organización no se incluirán. -Para más detalles sobre cómo proteger permisos de API a nivel de organización, consulta la [guía completa](/authorization/organization-level-api-resources). +Para detalles sobre cómo proteger permisos de API a nivel de organización, consulta la [guía completa](/authorization/organization-level-api-resources). + +### Usando RBAC global \{#using-global-rbac} + +En este caso, puedes usar la Management API de Logto para implementar el control de acceso a nivel de sistema. + +En un entorno multi-tenant, un patrón común es tener un rol de superusuario o super admin. Por ejemplo, si estás construyendo una plataforma SaaS con Logto, podrías querer un superusuario que pueda gestionar todas las organizaciones de clientes directamente dentro de tu propia aplicación, sin necesidad de iniciar sesión en la Consola de Logto. + +Este superusuario puede realizar acciones de alto nivel, como crear o eliminar organizaciones en masa, que requieren permisos a nivel de sistema más allá del contexto de cualquier organización individual. Para habilitar esto, registra un recurso de API en Logto mientras aprovechas la Management API de Logto y usa RBAC global para gestionar estos permisos. + +Para más detalles sobre cómo integrar y gestionar el control de acceso para RBAC, consulta la [guía completa](/authorization/global-api-resources). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 25d69fd3f7f..a70f0c3b0b6 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,7 +4,7 @@ sidebar_position: 3 # Créer une organisation -Imaginez que vous construisez une [application multi-locataire](https://auth.wiki/multi-tenancy) (par exemple, une application SaaS multi-locataire) qui dessert de nombreux clients, et chaque client possède un locataire dédié. +Imaginez que vous construisez une [application multi-locataire](https://auth.wiki/multi-tenancy) (par exemple, une application SaaS multi-locataire) qui sert de nombreux clients, et chaque client possède un locataire dédié. Les organisations sont généralement créées lorsque : @@ -29,20 +29,23 @@ Créez un [modèle d'organisation](/authorization/organization-template) pour cr ### Créer via l’API de gestion Logto \{#create-via-logto-management-api} -La Console est idéale pour la configuration manuelle, mais la plupart des applications permettent aux utilisateurs finaux d'être autonomes—créer et gérer des organisations directement dans votre application. Pour cela, implémentez ces fonctionnalités avec la Management API Logto. +La console est idéale pour la configuration manuelle, mais la plupart des applications permettent aux utilisateurs finaux de s’auto-gérer—créer et gérer des organisations directement dans votre application. Pour cela, implémentez ces fonctionnalités avec l’API de gestion Logto. :::note -Si vous débutez avec la Management API Logto, lisez d'abord ceci : +Si vous débutez avec l’API de gestion Logto ou si vous n’avez pas lu l’introduction de base à l’utilisation de l’API de gestion Logto pour l’expérience organisationnelle, lisez d’abord ceci : + + Configurez votre service d’application avec l’API de gestion Logto + Management API -Interagir avec la Management API +Interagir avec Management API ::: -Supposons que votre backend soit connecté à la Management API Logto via le mécanisme machine à machine (M2M), et que vous ayez obtenu un jeton d’accès M2M. +Supposons que votre backend soit connecté à l’API de gestion Logto via le mécanisme machine à machine (M2M), et que vous ayez obtenu un jeton d’accès M2M. -Créez une organisation avec la Management API ([Références API](https://openapi.logto.io/operation/operation-createorganization)) : +Créez une organisation avec Management API ([références API](https://openapi.logto.io/operation/operation-createorganization)) : ```bash curl \ @@ -52,7 +55,7 @@ curl \ -d '{"tenantId":"string","name":"string","description":"string","customData":{},"isMfaRequired":false,"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"createdAt":1234567890}' ``` -Ajoutez ensuite l'utilisateur en tant que membre de l'organisation ([Référence API](https://openapi.logto.io/operation/operation-addorganizationusers)) : +Ajoutez ensuite l’utilisateur en tant que membre de l’organisation ([référence API](https://openapi.logto.io/operation/operation-addorganizationusers)) : ```bash curl \ @@ -62,14 +65,14 @@ curl \ -d '{"userIds":["string"]}' ``` -Vous pouvez également attribuer des rôles d'organisation spécifiques à l'utilisateur ([Référence API](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)). +Vous pouvez éventuellement attribuer des rôles d’organisation spécifiques à l’utilisateur ([référence API](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)). Consultez les [spécifications complètes de l’API](https://openapi.logto.io/group/endpoint-organizations) pour plus de détails. -Encapsulez ces appels dans votre propre couche API. Lorsque les utilisateurs effectuent l'action "créer une organisation" dans votre application, validez la requête en vérifiant leurs permissions, puis appelez la Management API Logto pour finaliser l'opération. +Encapsulez ces appels dans votre propre couche API. Lorsque les utilisateurs effectuent l’action “créer une organisation” dans votre application, validez la requête en vérifiant leurs permissions, puis appelez l’API de gestion Logto pour finaliser l’opération. ## Valider le jeton d’organisation dans les requêtes utilisateur \{#validating-organization-token-in-user-request} -Dans votre application, lorsque les utilisateurs effectuent des actions dans le contexte d'une organisation, ils doivent utiliser un jeton d’organisation au lieu d’un jeton d’accès classique. Le jeton d’organisation est un [JWT](https://auth.wiki/jwt) qui contient les permissions de l’organisation. Comme tout [jeton d’accès](https://auth.wiki/access-token), vous pouvez décoder les revendications et vérifier la revendication "scope" pour appliquer les permissions. +Dans votre application, lorsque les utilisateurs effectuent des actions dans le contexte d’une organisation, ils doivent utiliser un jeton d’organisation au lieu d’un jeton d’accès classique. Le jeton d’organisation est un [JWT](https://auth.wiki/jwt) qui contient les permissions d’organisation. Comme tout [jeton d’accès](https://auth.wiki/access-token), vous pouvez décoder les revendications et vérifier la revendication "scope" pour appliquer les permissions. Voir Autorisation (Authorization) pour plus d’informations sur les scénarios d’autorisation et la validation des jetons d’organisation. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index c6554bef521..8d9de5470a2 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -6,7 +6,7 @@ sidebar_position: 4 ## Où l'utiliser \{#where-to-use-it} -Ceci est généralement utilisé dans la page de profil utilisateur où les utilisateurs doivent afficher les informations de leur organisation. +Ceci est généralement utilisé sur la page de profil utilisateur où les utilisateurs doivent afficher les informations de leur organisation. Informations utilisateur de l'organisation @@ -14,7 +14,7 @@ Ceci est généralement utilisé dans la page de profil utilisateur où les util Il existe deux façons d'obtenir les informations utilisateur au sein d'une organisation. -### 1. Décoder le jeton d’identifiant (ID token) \{#1-decode-the-id-token} +### Décoder le jeton d’identifiant (ID token) \{#decode-the-id-token} Le jeton d’identifiant (ID token) est un JWT standard qui contient les informations de profil utilisateur et les revendications liées à l’organisation. Appelez la méthode SDK `decodeIdToken()` pour obtenir un objet JSON comme celui-ci : @@ -43,7 +43,7 @@ Le jeton d’identifiant (ID token) est un JWT standard qui contient les informa ``` Cependant, le jeton d’identifiant (ID token) n’est émis que lors de l’authentification et peut devenir obsolète si le profil utilisateur change par la suite. -Pour obtenir les informations les plus à jour, utilisez la seconde méthode ci-dessous, ou appelez `clearAllTokens()` et réinitialisez un flux d’authentification pour obtenir un nouveau jeton d’identifiant (ID token). +Pour obtenir les informations les plus à jour, utilisez la seconde approche ci-dessous, ou appelez `clearAllTokens()` et réinitialisez un flux d’authentification pour obtenir un nouveau jeton d’identifiant (ID token). ```ts await logtoClient.clearAllTokens(); @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -Si la session est toujours valide, l’appel à `signIn` redirigera vers votre application sans demander d’identifiants. Du point de vue de l’utilisateur, l’application se rafraîchit simplement et un nouveau jeton d’identifiant (ID token) est émis en arrière-plan. +Si la session est toujours valide, l’appel à `signIn` redirigera vers votre application sans demander de nouvelles informations d’identification. Du point de vue de l’utilisateur, l’application se rafraîchit simplement et un nouveau jeton d’identifiant (ID token) est émis en arrière-plan. -### 2. Récupérer les informations utilisateur depuis l’endpoint `/oidc/me` \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### Récupérer les informations utilisateur depuis l’endpoint `/oidc/me` \{#fetch-user-info-from-the-oidc-me-endpoint} -Vous pouvez également faire une requête vers `/oidc/me` pour obtenir en temps réel les informations utilisateur dans le contexte de l’organisation. Appelez la méthode SDK `fetchUserInfo()`. +Vous pouvez également interroger `/oidc/me` pour obtenir en temps réel les informations utilisateur dans le contexte de l’organisation. Appelez la méthode SDK `fetchUserInfo()`. 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 80803051fc6..9f1042794d4 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 @@ -4,7 +4,7 @@ sidebar_position: 6 # Inviter des membres à une organisation -Dans les applications multi-organisations, il est courant de devoir inviter des membres dans une organisation. Ce guide détaille les étapes et les aspects techniques pour mettre en œuvre cette fonctionnalité. +Dans les applications multi‑tenantes, il est courant de devoir inviter des membres dans une organisation. Ce guide détaille les étapes et les aspects techniques pour mettre en œuvre cette fonctionnalité. ## Vue d’ensemble du flux \{#flow-overview} @@ -14,7 +14,7 @@ Le processus global est illustré dans le diagramme ci-dessous : sequenceDiagram Participant U as Utilisateur final Participant A as Administrateur d’organisation - Participant C as Votre application multi-organisation + Participant C as Votre application multi‑organisation Participant L as Logto A ->> C: Saisir l’e-mail de l’invité et le rôle @@ -23,13 +23,13 @@ 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 accéder à votre page d’atterrissage,
accepter ou refuser l’invitation + U ->> C: Cliquer sur le lien d’invitation et accéder à votre page d’accueil,
accepter ou refuser l’invitation C ->> L: Mettre à jour le statut de l’invitation avec Management API ``` ## Créer des rôles d’organisation \{#create-organization-roles} -Avant d’inviter des membres, créez des rôles d’organisation. Consultez le [modèle d’organisation](/authorization/organization-template) pour en savoir plus sur les rôles et les permissions (Permissions). +Avant d’inviter des membres, créez des rôles d’organisation. Consultez le [modèle d’organisation](/authorization/organization-template) pour en savoir plus sur les rôles et les permissions. Dans ce guide, créons deux rôles d’organisation typiques : `admin` et `member`. @@ -51,7 +51,7 @@ Cela peut être fait facilement dans la [Console Logto](https://cloud.logto.io/) ## Configurer votre connecteur e-mail \{#configure-your-email-connector} -Puisque les invitations sont envoyées par e-mail, assurez-vous que votre [connecteur e-mail](/connectors/email-connectors) est correctement configuré. Pour envoyer des invitations, configurez un [modèle d’e-mail](/connectors/email-connectors/email-templates#email-template-types) avec le type d’utilisation `OrganizationInvitation`. Vous pouvez inclure des variables d’organisation (par exemple, nom, logo) et d’invitant (par exemple, e-mail, nom) [variables](/connectors/email-connectors/email-templates#email-template-variables) dans le contenu, et personnaliser les [modèles localisés](/connectors/email-connectors/email-templates#email-template-localization) selon vos besoins. +Puisque les invitations sont envoyées par e-mail, assurez-vous que votre [connecteur e-mail](/connectors/email-connectors) est correctement configuré. Pour envoyer des invitations, configurez un [modèle d’e-mail](/connectors/email-connectors/email-templates#email-template-types) avec le type d’utilisation `OrganizationInvitation`. Vous pouvez inclure des [variables](/connectors/email-connectors/email-templates#email-template-variables) d’organisation (par exemple, nom, logo) et d’invitant (par exemple, e-mail, nom) dans le contenu, et personnaliser les [modèles localisés](/connectors/email-connectors/email-templates#email-template-localization) selon vos besoins. Un exemple de modèle d’e-mail pour le type d’utilisation `OrganizationInvitation` est présenté ci-dessous : @@ -64,7 +64,7 @@ Un exemple de modèle d’e-mail pour le type d’utilisation `OrganizationInvit } ``` -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. +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. :::note @@ -87,10 +87,15 @@ Il existe un ensemble d’API Management liées aux invitations dans la fonction - `POST /api/organization-invitations` : Créer une invitation d’organisation avec un rôle d’organisation attribué. - `POST /api/one-time-tokens` : Créer un jeton à usage unique pour que l’invité puisse s’authentifier lors de l’acceptation de l’invitation. [En savoir plus](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message` : Envoyer l’invitation d’organisation à l’invité par e-mail. - Remarque : La charge utile prend en charge une propriété `link` afin que vous puissiez composer votre propre lien d’invitation basé sur l’ID de l’invitation. Par exemple : - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +La charge utile prend en charge une propriété `link` afin que vous puissiez composer votre propre lien d’invitation basé sur l’ID de l’invitation. Par exemple : + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 45b3a27caa4..0201c81fa95 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -6,9 +6,11 @@ sidebar_position: 7 ## Où l’utiliser \{#where-to-use-it} -La liste des organisations apparaît généralement lors du parcours d’intégration utilisateur. Par exemple, lorsqu’un administrateur vous invite à rejoindre un espace de travail. +La liste des organisations et le parcours de rejoindre une organisation apparaissent généralement lors de l’onboarding utilisateur. +Par exemple, lorsqu’un administrateur invite quelqu’un dans un espace de travail, mais que l’utilisateur ignore l’invitation par e-mail et se connecte ou s’inscrit directement dans l’application. -D’un point de vue produit, elle peut apparaître à deux endroits principaux : +Dans votre produit, vous pouvez ajouter des points d’entrée pour ce parcours. +Cela peut apparaître à deux endroits principaux : - Le **sélecteur d’organisation** lors de la connexion ou de l’inscription @@ -17,19 +19,19 @@ D’un point de vue produit, elle peut apparaître à deux endroits principaux : alt="Rejoindre une organisation lors de la connexion ou de l’inscription" /> -- Le **changeur d’organisation** au sein de l’application +- Le **changeur d’organisation** dans l’application Rejoindre une organisation dans l’application -## Utiliser le Management API Logto pour permettre aux utilisateurs de rejoindre une organisation \{#use-the-logto-management-api-to-let-users-join-an-organization} +## Utiliser l’API de gestion Logto pour permettre aux utilisateurs de rejoindre une organisation \{#use-the-logto-management-api-to-let-users-join-an-organization} -Dans la section précédente, nous avons abordé la création et l’envoi d’invitations à une organisation à l’aide du Management API Logto. -Ensuite, implémentez une page d’atterrissage qui gère le lien d’invitation lorsque les invités arrivent sur votre application. +Dans la section précédente, nous avons vu comment créer et envoyer des invitations à une organisation en utilisant l’API de gestion Logto. +Ensuite, implémentez une page d’atterrissage qui gère le lien d’invitation lorsque les invités arrivent dans votre application. -- `GET /api/organization-invitations` et `GET /api/organization-invitations/{id}` : Obtenez toutes les invitations ou une invitation spécifique par ID. +- `GET /api/organization-invitations` et `GET /api/organization-invitations/{id}` : Récupérez toutes les invitations ou une invitation spécifique par ID. Sur votre page d’atterrissage, utilisez ces API pour lister toutes les invitations ou afficher les détails d’une invitation spécifique reçue par l’utilisateur. - `PUT /api/organization-invitations/{id}/status` : Acceptez ou refusez l’invitation en mettant à jour son statut. Utilisez cette API pour gérer la réponse de l’utilisateur. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 1fdc7920a80..bce6b28b683 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,27 +2,34 @@ sidebar_position: 8 --- -# Gestion des permissions et des ressources +# Gérer les mises à jour de portée dans les jetons d’organisation -Utilisez l'organisation comme ressource et appliquez un modèle d'organisation pour la protéger. Par exemple, chaque organisation possède ses propres documents au sein d'un tenant. Seuls les utilisateurs ayant les bons rôles peuvent modifier ou supprimer ces documents. +Avec la configuration ci-dessus, vous pouvez envoyer des invitations par e-mail, et les invités peuvent rejoindre l’organisation avec le rôle attribué. -Voir [Permissions d’organisation](/authorization/organization-permissions) pour plus de détails. +Les utilisateurs ayant différents rôles d’organisation auront différentes portées (permissions) dans leurs jetons d’organisation. Votre application cliente et vos services backend doivent vérifier ces portées pour déterminer les fonctionnalités visibles et les actions autorisées. -## Utiliser le contrôle d’accès basé sur les rôles (RBAC) d’organisation pour gérer les permissions des utilisateurs \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +Comme mentionné précédemment, le modèle d’organisation sert de couche clé de contrôle d’accès pour protéger les [permissions d’organisation](/authorization/organization-permissions) ou les [API de niveau organisation](/authorization/organization-level-api-resources). Veillez à consulter les sections sur l’autorisation et à choisir le modèle d’autorisation le mieux adapté à votre produit. -Avec la configuration ci-dessus, vous pouvez envoyer des invitations par e-mail, et les invités peuvent rejoindre l'organisation avec le rôle attribué. +:::note -Les utilisateurs ayant des rôles différents dans l'organisation auront différentes portées (permissions) dans leurs jetons d’organisation. Votre application cliente et vos services backend doivent vérifier ces portées pour déterminer les fonctionnalités visibles et les actions autorisées. + + Protéger les permissions d’organisation (non-API) + + + Protéger les ressources API de niveau organisation + -## Gérer les mises à jour de portée dans les jetons d’organisation \{#handle-scope-updates-in-organization-tokens} +::: + +Ce chapitre se concentre sur la **gestion des permissions** et les bonnes pratiques pour **gérer les changements de portée et de permissions** dans les jetons d’organisation Logto. -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, lisez d'abord [Autorisation](/authorization) et [Modèle d’organisation](/authorization/organization-template). +## Gérer les mises à jour de portée dans les jetons d’organisation \{#handle-scope-updates-in-organization-tokens} La gestion des mises à jour de portée dans les jetons d’organisation implique : -### Révoquer des portées existantes \{#revoke-existing-scopes} +### Révoquer les portées existantes \{#revoke-existing-scopes} -Par exemple, rétrograder un administrateur en membre non-administrateur doit supprimer des portées à l'utilisateur. Dans ce cas, effacez le jeton d’organisation mis en cache et récupérez-en un nouveau avec un 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 administrateur en membre non-administrateur doit retirer des portées à l’utilisateur. Dans ce cas, effacez le jeton d’organisation mis en cache et récupérez-en un nouveau avec un 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 \{#grant-new-scopes} @@ -30,11 +37,11 @@ Cela peut être divisé en deux scénarios : #### Accorder de nouvelles portées déjà définies dans votre système d’authentification \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -De manière similaire à la révocation de portées, si la nouvelle portée accordée est déjà enregistrée auprès du serveur d’authentification, émettez un nouveau jeton d’organisation et les nouvelles portées seront immédiatement reflétées. +Comme pour la révocation de portées, si la nouvelle portée accordée est déjà enregistrée auprès du serveur d’authentification, émettez un nouveau jeton d’organisation et les nouvelles portées seront immédiatement reflétées. #### Accorder de nouvelles portées nouvellement introduites dans votre système d’authentification \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} -Dans ce cas, déclenchez un processus de reconnexion ou de reconsentement pour mettre à jour le jeton d’organisation de l’utilisateur. Par exemple, appelez la méthode `signIn` dans le SDK Logto. +Dans ce cas, déclenchez un processus de reconnexion ou de re-consentement pour mettre à jour le jeton d’organisation de l’utilisateur. Par exemple, appelez la méthode `signIn` dans le SDK Logto. ## Vérifier les permissions en temps réel et mettre à jour le jeton d’organisation \{#check-permissions-in-real-time-and-update-the-organization-token} @@ -44,7 +51,7 @@ Logto fournit une Management API pour récupérer en temps réel les permissions Comparez 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é, effacez le jeton d’organisation mis en cache et le SDK émettra automatiquement un nouveau jeton avec les portées mises à jour. +- Si l’utilisateur est rétrogradé, effacez le jeton d’organisation mis en cache et le SDK émettra automatiquement un nouveau jeton avec les portées mises à jour. ```tsx const { clearAccessToken } = useLogto(); @@ -55,15 +62,15 @@ Comparez les portées dans le jeton d’organisation de l’utilisateur avec les ``` - Cela ne nécessite pas de processus de reconnexion ou de reconsentement. De nouveaux jetons d’organisation seront émis automatiquement par le SDK Logto. + Cela ne nécessite pas de reconnexion ni 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. Par exemple, avec le 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. Par exemple, avec le SDK React : ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // Si les portées récupérées en temps réel comportent de nouvelles portées attribuées par rapport à celles du jeton d’organisation + // Si les portées récupérées en temps réel comportent de nouvelles portées attribuées par rapport au jeton d’organisation await clearAllTokens(); signIn({ redirectUri: '', diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index f3cfa31aa9d..445561d88b8 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,18 +4,19 @@ sidebar_position: 2 # Configurez votre service d’application avec l’API de gestion Logto -Utilisez l’**API de gestion (Management API)** Logto pour créer des **flux d’organisation** personnalisés dans votre application. Voici les étapes de base pour intégrer l’API de gestion. Si vous êtes déjà familier, vous pouvez passer directement au [tutoriel](/integrate-logto/interact-with-management-api). +Logto propose une puissante API de gestion (Management API) qui vous permet de créer et de personnaliser votre propre parcours d’organisation au sein de votre application. +Comprendre son fonctionnement est essentiel pour concevoir votre configuration personnalisée. Voici les étapes de base et un aperçu pour intégrer l’API de gestion afin de mettre en œuvre votre expérience d’organisation. -Une fois que vous maîtrisez la configuration, vous pouvez explorer d’autres API pour adapter le reste des flux à vos besoins métier. +Si vous connaissez déjà les bases, vous pouvez passer directement au [tutoriel](/integrate-logto/interact-with-management-api). Une fois que vous êtes à l’aise avec la configuration, vous pouvez explorer des API supplémentaires pour adapter le reste des parcours à vos besoins métier. ## Établir une connexion machine à machine \{#establish-a-machine-to-machine-connection} -Logto utilise l’**authentification machine à machine (M2M)** pour connecter en toute sécurité votre service backend au point de terminaison de l’API de gestion Logto. -Votre service backend peut alors utiliser l’API de gestion pour gérer les tâches liées aux organisations telles que **créer des organisations**, **ajouter ou supprimer des membres**, et plus encore. +Logto utilise **l’authentification machine à machine (M2M) (Machine-to-machine authentication)** pour connecter en toute sécurité votre service backend au point de terminaison de l’API de gestion Logto. +Votre service backend peut alors utiliser l’API de gestion pour gérer des tâches liées à l’organisation telles que **la création d’organisations**, **l’ajout ou la suppression de membres**, et plus encore. Cela implique : -1. **Créer une application Machine à Machine (M2M)** dans la console Logto. +1. **Créer une application Machine-to-Machine (M2M)** dans la Console Logto. Détails de l’application M2M @@ -31,13 +32,14 @@ curl \ ## Protégez votre serveur d’application \{#protect-your-app-server} -Parce que les utilisateurs finaux peuvent effectuer certaines opérations d’organisation en libre-service, ajoutez une couche d’autorisation entre l’utilisateur final et votre serveur d’application. Le serveur doit intercepter chaque requête, valider le jeton d’organisation de l’utilisateur et les portées requises, puis seulement utiliser un identifiant M2M détenu côté serveur pour invoquer l’API de gestion. +Puisque les utilisateurs finaux peuvent effectuer certaines actions sur l’organisation par eux-mêmes, il est important d’ajouter une couche d’autorisation (Authorization) entre l’utilisateur final et votre serveur d’application.\ +Vous pouvez appliquer cette couche globalement ou au niveau de l’organisation, selon les points de terminaison de l’API de gestion Logto que vous utilisez et la structure de l’API de votre produit. Le serveur doit intercepter chaque requête, valider le jeton d’organisation de l’utilisateur et les portées requises, puis seulement utiliser un identifiant M2M détenu côté serveur pour invoquer l’API de gestion. Lorsqu’un utilisateur présente un jeton d’organisation pour demander une action (par exemple, créer une organisation), le serveur valide d’abord les portées dans le jeton. Si le jeton inclut la portée nécessaire, telle que `org:create`, autorisez la requête et appelez l’API de gestion Logto via le flux M2M pour créer l’organisation. -Si le jeton ne contient pas les portées requises, retournez un 403 Forbidden et ignorez la logique M2M. Cela garantit que les utilisateurs sans les privilèges appropriés ne peuvent pas créer d’organisations. +Si le jeton ne contient pas les portées requises, retournez une erreur 403 Forbidden et ignorez la logique M2M. Cela garantit que les utilisateurs sans les privilèges appropriés ne peuvent pas créer d’organisations. -Voici des schémas courants d’autorisation. +Voici des schémas d’autorisation courants. ### Utilisation des permissions d’organisation \{#using-organization-permissions} @@ -51,9 +53,9 @@ import { UserScope } from '@logto/react'; const config = { endpoint: 'https://.logto.app/', // Votre point de terminaison Logto - appId: '40fmibayagoo00lj26coc', // L’identifiant de votre application + appId: '40fmibayagoo00lj26coc', // Votre identifiant d’application resources: [ - 'https://my.company.com/api', // L’identifiant global de votre ressource API + 'https://my.company.com/api', // Identifiant global de la ressource API ], scopes: [ UserScope.Email, @@ -69,12 +71,22 @@ const config = { Cela garantit que lors de l’appel à `getOrganizationToken(organizationId)`, le SDK client demande un jeton d’organisation contenant les permissions d’organisation attribuées à l’utilisateur. Votre service backend peut alors valider le jeton et autoriser les requêtes suivantes en fonction de ces permissions. -Pour plus de détails sur la protection des permissions au niveau organisation (hors API), consultez le [guide complet](/authorization/organization-permissions). +Pour plus de détails sur la protection des permissions d’organisation (hors API), consultez le [guide complet](/authorization/organization-permissions). -### Combiner permissions au niveau organisation et permissions au niveau API \{#mixing-organization-level-permissions-and-api-level-permissions} +### Utilisation des permissions au niveau de l’API \{#using-api-level-permissions} -Cela s’applique lorsque vos ressources API et permissions sont enregistrées globalement, mais que les rôles sont définis au niveau de l’organisation (vous pouvez attribuer des permissions au niveau API aux rôles d’organisation dans le modèle d’organisation). +Cela s’applique lorsque vos ressources API et permissions sont enregistrées globalement, mais que les rôles sont définis au niveau de l’organisation (vous pouvez attribuer des permissions API à des rôles d’organisation dans le modèle d’organisation). La mise en œuvre est la même que dans la section précédente. Fournissez toujours l’identifiant de l’organisation et appelez `getOrganizationToken(organizationId)` pour obtenir un jeton d’organisation ; sinon, les permissions d’organisation ne seront pas incluses. -Pour plus de détails sur la protection des permissions API au niveau organisation, consultez le [guide complet](/authorization/organization-level-api-resources). +Pour plus de détails sur la protection des permissions API au niveau de l’organisation, consultez le [guide complet](/authorization/organization-level-api-resources). + +### Utilisation du RBAC global \{#using-global-rbac} + +Dans ce cas, vous pouvez utiliser l’API de gestion Logto pour mettre en œuvre un contrôle d’accès au niveau du système. + +Dans un environnement multi-locataires, un schéma courant consiste à avoir un superutilisateur ou un rôle de super administrateur. Par exemple, si vous construisez une plateforme SaaS avec Logto, vous pouvez souhaiter qu’un superutilisateur puisse gérer toutes les organisations clientes directement depuis votre propre application, sans avoir à se connecter à la Console Logto. + +Ce superutilisateur peut effectuer des actions de niveau supérieur, telles que la création ou la suppression d’organisations en masse, nécessitant des permissions globales dépassant le contexte d’une seule organisation. Pour cela, enregistrez une ressource API dans Logto tout en exploitant l’API de gestion Logto et utilisez le RBAC global pour gérer ces permissions. + +Pour plus de détails sur l’intégration et la gestion du contrôle d’accès pour le RBAC, consultez le [guide complet](/authorization/global-api-resources). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 0a3d1cea1c9..c932c226771 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,11 +4,11 @@ sidebar_position: 3 # 組織の作成 -[マルチテナントアプリ](https://auth.wiki/multi-tenancy)（例：マルチテナント SaaS アプリ）を構築していると仮定します。このアプリは多くの顧客にサービスを提供し、それぞれの顧客が専用のテナントを所有しています。 +[マルチテナントアプリ](https://auth.wiki/multi-tenancy)（例：マルチテナント SaaS アプリ）を構築していると想像してください。このアプリは多くの顧客にサービスを提供し、それぞれの顧客が専用のテナントを所有します。 組織 (Organization) は通常、次のタイミングで作成されます： -1. 新しい顧客がサインアップし、自分のビジネス用のアカウントとテナントを作成する場合。 +1. 新しい顧客がサインアップし、自社用のアカウントとテナントを作成する場合。 2. 既存ユーザーがアプリ内から新しい組織 (Organization) を作成する場合。 新規アカウントが組織を作成 @@ -18,27 +18,30 @@ sidebar_position: 3 アプリで組織 (Organization) を作成する方法は 2 つあります。 -### Logto Console から作成 \{#create-via-logto-console} +### Logto コンソールから作成 \{#create-via-logto-console} -Logto Console の UI で手動で組織 (Organization) を作成します。Console > 組織 (Organizations) +Logto コンソール UI で手動で組織 (Organization) を作成します。コンソール > 組織 (Organizations) に移動し、組織 (Organization) の作成、メンバーやロールの割り当て、組織 (Organization) のサインイン体験のカスタマイズができます。 [組織テンプレート](/authorization/organization-template) を作成して、同じロールや権限を共有する類似の組織 (Organization) を一括作成できます。 ### Logto Management API から作成 \{#create-via-logto-management-api} -Console は手動設定に便利ですが、多くのアプリではエンドユーザーがセルフサービスで組織 (Organization) を直接作成・管理できるようにします。その場合は、Logto Management API を使ってこれらの機能を実装します。 +コンソールは手動設定に便利ですが、多くのアプリではエンドユーザーがセルフサービスで組織 (Organization) を作成・管理できるようにします。そのためには、Logto Management API を使ってこれらの機能を実装します。 :::note -Logto Management API を初めて利用する場合は、まずこちらをお読みください： +Logto Management API を初めて利用する場合や、組織体験のための Logto Management API の基本的な使い方をまだ読んでいない場合は、まず以下をお読みください： + + Logto Management API でアプリサービスをセットアップする + Management API Management API との連携 ::: -バックエンドがマシン間通信 (M2M) メカニズムを通じて Logto Management API に接続されており、M2M アクセストークンを取得していると仮定します。 +バックエンドがマシン間通信 (M2M) メカニズムを通じて Logto Management API に接続されており、M2M アクセストークン (アクセス トークン) を取得済みであると仮定します。 Management API で組織 (Organization) を作成します（[API リファレンス](https://openapi.logto.io/operation/operation-createorganization)）： @@ -60,14 +63,14 @@ curl \ -d '{"userIds":["string"]}' ``` -必要に応じて、特定の組織 (Organization) ロールをユーザーに割り当てることもできます（[API リファレンス](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)）。 +必要に応じて、特定の組織ロール (ロール) をユーザーに割り当てることもできます（[API リファレンス](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)）。 詳細は [API 仕様全体](https://openapi.logto.io/group/endpoint-organizations) をご確認ください。 -これらの呼び出しを独自の API レイヤーでラップしましょう。ユーザーがアプリで「組織 (Organization) を作成」アクションを実行した際、権限をチェックしてリクエストを検証し、その後 Logto Management API を呼び出して処理を完了させます。 +これらの呼び出しを独自の API レイヤーでラップしましょう。ユーザーがアプリで「組織 (Organization) を作成」アクションを実行した際、権限を確認してリクエストを検証し、その後 Logto Management API を呼び出して処理を完了させます。 -## ユーザーリクエストで組織トークン (Organization token) を検証する \{#validating-organization-token-in-user-request} +## ユーザーリクエストで組織トークン (組織トークン) を検証する \{#validating-organization-token-in-user-request} -アプリ内でユーザーが組織 (Organization) のコンテキストで操作を行う場合、通常のアクセス トークン (Access token) ではなく、組織トークン (Organization token) を使用する必要があります。組織トークン (Organization token) は、組織 (Organization) の権限を含む [JWT](https://auth.wiki/jwt) です。[アクセス トークン (Access token)](https://auth.wiki/access-token) と同様に、クレーム (Claims) をデコードし、「scope」クレーム (Claim) を検証して権限を強制できます。 +アプリ内でユーザーが組織 (Organization) のコンテキストで操作を行う場合、通常のアクセス トークンではなく組織トークン (組織トークン) を使用する必要があります。組織トークン (組織トークン) は、組織の権限 (権限) を含む [JWT](https://auth.wiki/jwt) です。任意の [アクセス トークン](https://auth.wiki/access-token) と同様に、クレーム (クレーム) をデコードし、「スコープ (スコープ)」クレームを検証して権限 (権限) を強制できます。 -認可 (Authorization) シナリオや組織トークン (Organization token) の検証方法については、認可 (Authorization) を参照してください。 +認可 (Authorization) シナリオや組織トークン (組織トークン) の検証方法については、認可 (Authorization) を参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index e334742e0da..32fed627cd9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -14,9 +14,9 @@ sidebar_position: 4 組織内でユーザー情報を取得する方法は 2 つあります。 -### 1. ID トークン (ID token) をデコードする \{#1-decode-the-id-token} +### ID トークン (ID token) をデコードする \{#decode-the-id-token} -ID トークン (ID token) は、ユーザープロフィール情報や組織に関連するクレーム (Claims) を含む標準的な JWT です。SDK の `decodeIdToken()` メソッドを呼び出すことで、次のような JSON オブジェクトを取得できます： +ID トークン (ID token) は、ユーザープロフィール情報や組織に関連するクレーム (Claims) を含む標準的な JWT です。SDK の `decodeIdToken()` メソッドを呼び出すと、次のような JSON オブジェクトが取得できます： ```json { @@ -43,7 +43,7 @@ ID トークン (ID token) は、ユーザープロフィール情報や組織 ``` ただし、ID トークン (ID token) は認証 (Authentication) 時にのみ発行されるため、その後ユーザープロフィールが変更された場合は古くなる可能性があります。 -最新の情報が必要な場合は、以下の 2 番目の方法を利用するか、`clearAllTokens()` を呼び出して認証 (Authentication) フローを再実行し、新しい ID トークン (ID token) を取得してください。 +最新の情報が必要な場合は、下記の 2 番目の方法を利用するか、`clearAllTokens()` を呼び出して認証 (Authentication) フローを再実行し、新しい ID トークン (ID token) を取得してください。 ```ts await logtoClient.clearAllTokens(); @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -セッションがまだ有効な場合、`signIn` の呼び出しは認証情報の入力なしでアプリにリダイレクトされます。ユーザーから見ると、アプリが単にリフレッシュされ、裏側で新しい ID トークン (ID token) が発行されます。 +セッションが有効な場合、`signIn` の呼び出しは認証情報の入力を求めずにアプリへリダイレクトします。ユーザーから見ると、アプリが単にリフレッシュされ、裏側で新しい ID トークン (ID token) が発行されます。 -### 2. `/oidc/me` エンドポイントからユーザー情報を取得する \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### `/oidc/me` エンドポイントからユーザー情報を取得する \{#fetch-user-info-from-the-oidc-me-endpoint} -また、`/oidc/me` にリクエストを送ることで、組織コンテキストでリアルタイムのユーザー情報を取得できます。SDK の `fetchUserInfo()` メソッドを呼び出してください。 +また、`/oidc/me` にリクエストすることで、組織コンテキストでリアルタイムのユーザー情報を取得できます。SDK の `fetchUserInfo()` メソッドを呼び出してください。 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 a9e70fef606..74ef550cbe6 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: 6 # 組織メンバーの招待 -マルチ組織アプリケーションでは、よくある要件として組織へのメンバー招待があります。このガイドでは、その機能を実装するための手順と技術的な詳細を説明します。 +マルチテナンシーアプリケーションでは、組織にメンバーを招待することが一般的な要件です。このガイドでは、その機能を実装するための手順と技術的な詳細を説明します。 ## フロー概要 \{#flow-overview} @@ -19,46 +19,46 @@ sequenceDiagram A ->> C: 招待するメールアドレスとロールを入力 C ->> L: Management API で組織招待を作成 - L -->> C: 招待 ID を返す + L -->> C: 招待 ID を返却 C ->> C: 招待 ID で招待リンクを作成 C ->> L: 招待リンク付きの招待メール送信をリクエスト L -->> U: 招待リンク付きの招待メールを送信 - U ->> C: 招待リンクをクリックしランディングページへ遷移、
招待を承諾または拒否 + U ->> C: 招待リンクをクリックしてランディングページへ遷移、
招待を承諾または拒否 C ->> L: Management API で招待ステータスを更新 ``` ## 組織ロールの作成 \{#create-organization-roles} -メンバーを招待する前に、組織ロールを作成します。ロールと権限について詳しくは [組織テンプレート](/authorization/organization-template) を参照してください。 +メンバーを招待する前に、組織ロールを作成します。ロールと権限については [組織テンプレート](/authorization/organization-template) を参照してください。 -このガイドでは、典型的な組織ロールとして `admin` と `member` の 2 つを作成します。 +このガイドでは、典型的な組織ロールである `admin` と `member` を作成します。 -`admin` ロールは組織内のすべてのリソースへのフルアクセス権を持ち、`member` ロールは限定的なアクセス権を持ちます。例： +`admin` ロールは組織内のすべてのリソースへのフルアクセス権を持ち、`member` ロールは限定的なアクセス権を持ちます。例えば： - `admin` ロール: - `read:data` - 組織のすべてのデータリソースの読み取り権限 - `write:data` - 組織のすべてのデータリソースの書き込み権限 - `delete:data` - 組織のすべてのデータリソースの削除権限 - `invite:member` - 組織へのメンバー招待権限 - - `manage:member` - 組織内メンバーの管理権限 - - `delete: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) が正しく設定されていることを確認してください。招待を送信するには、使用タイプが `OrganizationInvitation` の [メールテンプレート](/connectors/email-connectors/email-templates#email-template-types) を設定します。組織（例：名前、ロゴ）や招待者（例：メールアドレス、名前）の [変数](/connectors/email-connectors/email-templates#email-template-variables) を本文に含めることができ、必要に応じて [ローカライズされたテンプレート](/connectors/email-connectors/email-templates#email-template-localization) もカスタマイズできます。 +招待はメールで送信されるため、[メールコネクター](/connectors/email-connectors) が正しく設定されていることを確認してください。招待メールを送信するには、使用タイプが `OrganizationInvitation` の [メールテンプレート](/connectors/email-connectors/email-templates#email-template-types) を設定します。組織（例：名前、ロゴ）や招待者（例：メールアドレス、名前）の [変数](/connectors/email-connectors/email-templates#email-template-variables) を内容に含めることができ、必要に応じて [ローカライズされたテンプレート](/connectors/email-connectors/email-templates#email-template-localization) もカスタマイズできます。 `OrganizationInvitation` 用のサンプルメールテンプレートは以下の通りです： ```json { "subject": "Welcome to my organization", - "content": "

この リンク から {{organization.name}} に参加してください。

", + "content": "

Join {{organization.name}} by this link.

", "usageType": "OrganizationInvitation", "type": "text/html" } @@ -68,7 +68,7 @@ sequenceDiagram :::note -Logto Cloud の組み込み「Logto メールサービス」は現在 `OrganizationInvitation` 使用タイプをサポートしていません。独自のメールコネクター（例：SendGrid）を設定し、`OrganizationInvitation` テンプレートを用意してください。 +Logto Cloud の組み込み「Logto email service」では、現在 `OrganizationInvitation` 使用タイプはサポートされていません。独自のメールコネクター（例：SendGrid）を設定し、`OrganizationInvitation` テンプレートを用意してください。 ::: @@ -82,15 +82,20 @@ Logto Management API のセットアップがまだの場合は、[Management AP ### Logto Management API で組織招待を作成する \{#create-an-organization-invitation-with-logto-management-api} -組織機能には招待関連の Management API が用意されています。これらの API で次のことが可能です： +組織機能には招待関連の Management API が用意されています。これらの API で次のことができます： -- `POST /api/organization-invitations`: 割り当てた組織ロールで組織招待を作成 +- `POST /api/organization-invitations`: 組織ロールを割り当てて組織招待を作成 - `POST /api/one-time-tokens`: 招待を承諾する際に招待者が認証するためのワンタイムトークンを作成 [詳細はこちら](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message`: 組織招待をメールで招待者に送信 - 注意：ペイロードは `link` プロパティをサポートしているため、招待 ID をもとに独自の招待リンクを作成できます。例： - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +ペイロードは `link` プロパティをサポートしているため、招待 ID をもとに独自の招待リンクを作成できます。例： + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 3437f5c492f..a77e36ba55d 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -2,31 +2,33 @@ sidebar_position: 7 --- -# 組織への参加 +# 組織 (Organization) への参加 ## 利用シーン \{#where-to-use-it} -組織リストは、通常ユーザーのオンボーディングフロー中に表示されます。例えば、管理者からワークスペースへの招待を受けた場合などです。 +組織 (Organization) 一覧や参加フローは、通常ユーザーのオンボーディング時に表示されます。 +例えば、管理者が誰かをワークスペースに招待したものの、そのユーザーがメール招待をスキップしてアプリで直接サインインまたはサインアップした場合などです。 -プロダクトの観点では、主に次の 2 つの場所で表示されます： +プロダクト内で、このフローへの導線を追加したい場合があります。 +主に次の 2 つの場所で表示できます： -- サインインまたはサインアップ時の **組織ファインダー** +- サインインまたはサインアップ時の **組織 (Organization) ファインダー** サインインまたはサインアップ時に組織へ参加 -- アプリケーション内の **組織スイッチャー** +- アプリケーション内の **組織 (Organization) スイッチャー** -アプリ内で組織へ参加 +アプリ内で組織 (Organization) へ参加 -## Logto Management API を使ってユーザーが組織に参加できるようにする \{#use-the-logto-management-api-to-let-users-join-an-organization} +## Logto Management API を使ってユーザーが組織 (Organization) に参加できるようにする \{#use-the-logto-management-api-to-let-users-join-an-organization} -前のセクションでは、Logto Management API を使って組織の招待を作成し送信する方法を説明しました。 -次に、招待されたユーザーがアプリケーションにアクセスした際に、招待リンクを処理するランディングページを実装します。 +前のセクションでは、Logto Management API を使って組織 (Organization) 招待を作成し送信する方法を説明しました。 +次に、招待されたユーザーがアプリケーションに到着した際に招待リンクを処理するランディングページを実装します。 - `GET /api/organization-invitations` および `GET /api/organization-invitations/{id}`：すべての招待、または ID で特定の招待を取得します。 - ランディングページでこれらの API を利用し、ユーザーが受け取ったすべての招待を一覧表示したり、特定の招待の詳細を表示したりします。 + ランディングページでこれらの API を使い、ユーザーが受け取ったすべての招待を一覧表示したり、特定の招待の詳細を表示したりします。 - `PUT /api/organization-invitations/{id}/status`：ステータスを更新して招待を承諾または拒否します。 この API を使ってユーザーの応答を処理します。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 7d4d4734e10..0c5c6b36a20 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,68 +2,71 @@ sidebar_position: 8 --- -# 権限 (Permission) とリソース管理 +# 組織トークンにおけるスコープの更新を扱う -組織 (Organization) をリソースとして使用し、組織テンプレートを適用して保護します。例えば、各組織 (Organization) はテナント内に独自のドキュメントを持ちます。適切なロール (Role) を持つユーザーのみが、それらのドキュメントを編集または削除できます。 +上記のセットアップにより、メールで招待を送信し、招待されたユーザーは割り当てられたロールで組織に参加できます。 -詳細は [組織の権限 (Organization permissions)](/authorization/organization-permissions) を参照してください。 +異なる組織ロールを持つユーザーは、組織トークン内で異なるスコープ（権限）を持ちます。クライアントアプリとバックエンドサービスの両方で、これらのスコープを確認し、表示する機能や許可されるアクションを判断してください。 -## 組織ロールベースのアクセス制御 (RBAC) でユーザー権限を管理する \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +前述の通り、組織テンプレートは [組織権限](/authorization/organization-permissions) や [組織レベル API リソース](/authorization/organization-level-api-resources) を保護するための主要なアクセス制御レイヤーとして機能します。認可 (Authorization) セクションを必ず確認し、製品に最適な認可 (Authorization) モデルを選択してください。 -上記の設定により、メールで招待を送信でき、招待されたユーザーは割り当てられたロール (Role) で組織 (Organization) に参加できます。 +:::note -異なる組織ロール (Role) を持つユーザーは、組織トークン (Organization token) 内で異なるスコープ (Scope)（権限 (Permission)）を持ちます。クライアントアプリとバックエンドサービスの両方で、これらのスコープ (Scope) を確認し、表示する機能や許可された操作を判断してください。 +組織（非 API）権限を保護する +組織レベル API リソースを保護する -## 組織トークン (Organization token) のスコープ (Scope) 更新を処理する \{#handle-scope-updates-in-organization-tokens} +::: -このセクションでは、組織テンプレートや認可 (Authorization) シナリオの管理に関する高度なトピックを扱います。これらの概念に慣れていない場合は、まず [認可 (Authorization)](/authorization) および [組織テンプレート (Organization template)](/authorization/organization-template) をお読みください。 +この章では、Logto 組織トークンにおける **権限管理** および **スコープ変更と権限の扱い** のベストプラクティスに焦点を当てます。 -組織トークン (Organization token) のスコープ (Scope) 更新の管理には、次の内容が含まれます： +## 組織トークンにおけるスコープの更新を扱う \{#handle-scope-updates-in-organization-tokens} -### 既存のスコープ (Scope) を取り消す \{#revoke-existing-scopes} +組織トークンにおけるスコープの更新管理には、次の内容が含まれます： -例えば、管理者 (admin) を非管理者メンバーに降格する場合、ユーザーからスコープ (Scope) を削除する必要があります。このような場合は、キャッシュされた組織トークン (Organization token) をクリアし、リフレッシュトークン (Refresh token) で新しいトークンを取得してください。減少したスコープ (Scope) は新しく発行された組織トークン (Organization token) に即座に反映されます。 +### 既存のスコープを取り消す \{#revoke-existing-scopes} -### 新しいスコープ (Scope) を付与する \{#grant-new-scopes} +例えば、管理者を非管理者メンバーに降格する場合、ユーザーからスコープを削除する必要があります。この場合、キャッシュされた組織トークンをクリアし、リフレッシュトークンで新しいトークンを取得してください。減少したスコープは新たに発行された組織トークンに即時反映されます。 + +### 新しいスコープを付与する \{#grant-new-scopes} これは 2 つのシナリオに分けられます： -#### 認証システムですでに定義されている新しいスコープ (Scope) を付与する \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} +#### 認証システムですでに定義されている新しいスコープを付与する場合 \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -スコープ (Scope) の取り消しと同様に、新たに付与されたスコープ (Scope) がすでに認証サーバーに登録されている場合、新しい組織トークン (Organization token) を発行すれば、新しいスコープ (Scope) が即座に反映されます。 +スコープの取り消しと同様に、新たに付与されたスコープがすでに認証サーバーに登録されている場合、新しい組織トークンを発行すれば新しいスコープが即時反映されます。 -#### 認証システムに新たに導入されたスコープ (Scope) を付与する \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### 認証システムに新たに導入されたスコープを付与する場合 \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} -この場合、ユーザーの組織トークン (Organization token) を更新するために再ログインまたは再同意プロセスをトリガーしてください。例えば、Logto SDK の `signIn` メソッドを呼び出します。 +この場合、再ログインまたは再同意プロセスをトリガーしてユーザーの組織トークンを更新します。例えば、Logto SDK の `signIn` メソッドを呼び出します。 -## 権限 (Permission) をリアルタイムで確認し、組織トークン (Organization token) を更新する \{#check-permissions-in-real-time-and-update-the-organization-token} +## 権限をリアルタイムで確認し、組織トークンを更新する \{#check-permissions-in-real-time-and-update-the-organization-token} -Logto は、組織 (Organization) 内のユーザー権限 (Permission) をリアルタイムで取得するための Management API を提供しています。 +Logto は、組織内のユーザー権限をリアルタイムで取得するための Management API を提供しています。 - `GET /api/organizations/{id}/users/{userId}/scopes` （[API リファレンス](https://openapi.logto.io/operation/operation-listorganizationuserscopes)） -ユーザーの組織トークン (Organization token) 内のスコープ (Scope) とリアルタイムの権限 (Permission) を比較し、ユーザーが昇格または降格されたかどうかを判断します。 +ユーザーの組織トークン内のスコープとリアルタイム権限を比較し、ユーザーが昇格または降格されたかどうかを判断します。 -- 降格された場合、キャッシュされた組織トークン (Organization token) をクリアすると、SDK が自動的に更新されたスコープ (Scope) で新しいトークンを発行します。 +- 降格された場合、キャッシュされた組織トークンをクリアすると、SDK が自動的に更新されたスコープで新しいトークンを発行します。 ```tsx const { clearAccessToken } = useLogto(); ... - // 取得したリアルタイムスコープ (Scope) が組織トークン (Organization token) のスコープ (Scope) より少ない場合 + // 取得したリアルタイムスコープが組織トークンのスコープより少ない場合 await clearAccessToken(); ``` - この操作には再ログインや再同意プロセスは不要です。新しい組織トークン (Organization token) は Logto SDK により自動的に発行されます。 + この操作には再ログインや再同意プロセスは不要です。Logto SDK により新しい組織トークンが自動的に発行されます。 -- 認証システムに新しいスコープ (Scope) が導入された場合、再ログインまたは再同意プロセスをトリガーしてユーザーの組織トークン (Organization token) を更新してください。例えば、React SDK では： +- 認証システムに新しいスコープが導入された場合、再ログインまたは再同意プロセスをトリガーしてユーザーの組織トークンを更新します。例えば、React SDK では： ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // 取得したリアルタイムスコープ (Scope) に新たに割り当てられたスコープ (Scope) がある場合 + // 取得したリアルタイムスコープが組織トークンのスコープより新たに割り当てられている場合 await clearAllTokens(); signIn({ redirectUri: '', @@ -72,4 +75,4 @@ Logto は、組織 (Organization) 内のユーザー権限 (Permission) をリ ``` - 上記のコードは同意画面 (Consent screen) への遷移をトリガーし、ユーザーの組織トークン (Organization token) に更新されたスコープ (Scope) を付与してアプリに自動リダイレクトします。 + 上記のコードは同意画面への遷移をトリガーし、ユーザーの組織トークンに更新されたスコープを付与した状態でアプリに自動リダイレクトします。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index d335b0da589..3ce410fdf6a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,23 +4,24 @@ sidebar_position: 2 # Logto Management API でアプリサービスをセットアップする -Logto の **Management API** を利用して、アプリ内でカスタムの **組織フロー** を構築できます。以下は Management API を統合するための基本的なセットアップ手順です。すでにご存知の場合は、[チュートリアル](/integrate-logto/interact-with-management-api) へ進んでください。 +Logto では、強力な Management API を提供しており、アプリ内で独自の組織フローを作成・カスタマイズできます。 +その仕組みを理解することは、カスタムセットアップを設計する上で重要です。以下は、Management API を統合して組織体験を実装するための基本的なステップと概要です。 -セットアップに慣れたら、他の API も活用して、ビジネスニーズに合わせたフローを構築できます。 +基本をすでに理解している場合は、[チュートリアル](/integrate-logto/interact-with-management-api) へ進んでください。セットアップに慣れたら、他の API も活用してビジネスニーズに合わせてフローを調整できます。 -## マシン間通信 (M2M) 接続の確立 \{#establish-a-machine-to-machine-connection} +## マシン間通信接続の確立 \{#establish-a-machine-to-machine-connection} -Logto では、**マシン間通信 (M2M) 認証 (Authentication)** を利用して、バックエンドサービスと Logto Management API エンドポイントを安全に接続します。 -バックエンドサービスは Management API を使って、**組織の作成**、**メンバーの追加や削除** など、組織関連のタスクを処理できます。 +Logto は、**マシン間通信 (M2M) 認証 (Authentication)** を使用して、バックエンドサービスと Logto Management API エンドポイントを安全に接続します。 +バックエンドサービスは、Management API を利用して **組織の作成**、**メンバーの追加や削除** など、組織関連のタスクを処理できます。 -この手順は以下の通りです： +この流れは次の通りです： 1. Logto コンソールで **マシン間通信 (M2M) アプリ** を作成します。 M2M アプリの詳細 2. Logto から **M2M アクセス トークン (Access token)** を取得します。[詳細はこちら](/integrate-logto/interact-with-management-api#fetch-an-access-token)。 -3. バックエンドサービスから Logto Management API を呼び出します。例えば、すべての組織を一覧表示する場合： +3. バックエンドサービスから **Logto Management API** を呼び出します。例えば、すべての組織を一覧表示する場合： ```bash curl \ @@ -31,17 +32,18 @@ curl \ ## アプリサーバーの保護 \{#protect-your-app-server} -エンドユーザーが一部の組織操作をセルフサービスで実行できるため、エンドユーザーとアプリサーバーの間に認可 (Authorization) レイヤーを追加してください。サーバーはすべてのリクエストを仲介し、ユーザーの組織トークン (Organization token) と必要なスコープ (Scope) を検証したうえで、サーバーが保持する M2M 資格情報を使って Management API を呼び出すべきです。 +エンドユーザーが自身で組織に関する操作を行える場合があるため、エンドユーザーとアプリサーバーの間に認可 (Authorization) レイヤーを追加することが重要です。 +このレイヤーは、利用する Logto Management API エンドポイントやプロダクトの API 構成に応じて、グローバルまたは組織単位で適用できます。サーバーはすべてのリクエストを仲介し、ユーザーの組織トークン (Organization token) と必要なスコープ (Scope) を検証した上で、サーバーが保持する M2M 資格情報を使って Management API を呼び出すべきです。 ユーザーが組織トークン (Organization token) を提示してアクション（例：組織の作成）をリクエストした場合、サーバーはまずトークン内のスコープ (Scope) を検証します。トークンに `org:create` など必要なスコープ (Scope) が含まれていれば、リクエストを認可 (Authorization) し、M2M フロー経由で Logto Management API を呼び出して組織を作成します。 -必要なスコープ (Scope) が含まれていない場合は、403 Forbidden を返し、M2M ロジックをスキップします。これにより、適切な権限を持たないユーザーが組織を作成できないようにします。 +必要なスコープ (Scope) がトークンに含まれていない場合は、403 Forbidden を返し、M2M ロジックをスキップします。これにより、適切な権限を持たないユーザーが組織を作成できないようにします。 以下は一般的な認可 (Authorization) パターンです。 ### 組織権限の利用 \{#using-organization-permissions} -まず、[前のセクション](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) で組織権限とロールを組織テンプレートに定義していることを確認してください。 +まず、[前のセクション](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) で組織権限とロール (Role) を組織テンプレートに定義していることを確認してください。 次に、Logto 設定に `UserScope.Organizations`（値：`urn:logto:organization`）が含まれていることを確認します。React SDK の例： @@ -67,14 +69,24 @@ const config = { }; ``` -これにより、`getOrganizationToken(organizationId)` を呼び出す際、クライアント SDK はユーザーに割り当てられた組織権限を含む組織トークン (Organization token) をリクエストします。バックエンドサービスはこのトークンを検証し、権限に基づいて後続のリクエストを認可 (Authorization) できます。 +これにより、`getOrganizationToken(organizationId)` を呼び出す際、クライアント SDK はユーザーに割り当てられた組織権限を含む組織トークン (Organization token) をリクエストします。バックエンドサービスはこのトークンを検証し、これらの権限に基づいて後続のリクエストを認可 (Authorization) できます。 組織レベル（非 API）権限の保護については、[完全ガイド](/authorization/organization-permissions) を参照してください。 -### 組織レベル権限と API レベル権限の混在 \{#mixing-organization-level-permissions-and-api-level-permissions} +### API レベル権限の利用 \{#using-api-level-permissions} -API リソースと権限がグローバルに登録されているが、ロールは組織レベルで定義されている場合（API レベルの権限を組織テンプレート内の組織ロールに割り当て可能）、このパターンが該当します。 +API リソースと権限がグローバルに登録されているが、ロール (Role) は組織単位で定義されている場合に適用されます（API レベル権限を組織テンプレート内の組織ロール (Role) に割り当て可能）。 実装方法は前述のセクションと同じです。常に組織 ID を指定し、`getOrganizationToken(organizationId)` を呼び出して組織トークン (Organization token) を取得してください。そうしないと、組織権限が含まれません。 -組織レベル API 権限の保護については、[完全ガイド](/authorization/organization-level-api-resources) を参照してください。 +組織レベルの API 権限の保護については、[完全ガイド](/authorization/organization-level-api-resources) を参照してください。 + +### グローバル RBAC の利用 \{#using-global-rbac} + +この場合、Logto Management API を使ってシステムレベルのアクセス制御を実装できます。 + +マルチテナント環境では、スーパーユーザーやスーパー管理者ロール (Role) を持つパターンが一般的です。例えば、Logto で SaaS プラットフォームを構築する場合、Logto コンソールにログインせずに自社アプリ内で全クライアント組織を直接管理できるスーパーユーザーが必要になることがあります。 + +このスーパーユーザーは、単一の組織コンテキストを超えたシステム全体の権限が必要な、組織の一括作成や削除などの高度な操作を実行できます。これを実現するには、Logto で API リソースを登録し、Logto Management API を活用しつつ、グローバル RBAC でこれらの権限を管理します。 + +RBAC のアクセス制御統合と管理の詳細については、[完全ガイド](/authorization/global-api-resources) を参照してください。 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 7e96248a848..d9ba598aab8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,34 +4,37 @@ sidebar_position: 3 # 조직 생성 -여러 고객을 대상으로 하는 [멀티 테넌트 앱](https://auth.wiki/multi-tenancy) (예: 멀티 테넌트 SaaS 앱)을 구축한다고 상상해 보세요. 각 고객은 전용 테넌트를 소유하게 됩니다. +여러 고객에게 서비스를 제공하며 각 고객이 전용 테넌트를 소유하는 [멀티 테넌트 앱](https://auth.wiki/multi-tenancy) (예: 멀티 테넌트 SaaS 앱)을 구축한다고 상상해 보세요. 조직은 일반적으로 다음과 같은 경우에 생성됩니다: 1. 신규 고객이 가입하여 비즈니스를 위한 계정과 테넌트를 모두 생성할 때 2. 기존 사용자가 앱 내에서 새로운 조직을 생성할 때 -신규 계정이 조직을 생성함 +새 계정이 조직을 생성함 기존 사용자가 조직을 생성함 -## 조직 생성 구현 \{#implement-organization-creation} +## 조직 생성 구현하기 \{#implement-organization-creation} 앱에서 조직을 생성하는 방법은 두 가지가 있습니다. ### Logto Console을 통한 생성 \{#create-via-logto-console} -Logto Console UI에서 조직을 수동으로 생성할 수 있습니다. Console > 조직로 이동하여 조직을 생성하고, 구성원 및 역할을 할당하며, 조직 로그인 경험을 맞춤 설정하세요. +Logto Console UI에서 조직을 수동으로 생성할 수 있습니다. Console > 조직로 이동하여 조직을 생성하고, 구성원과 역할을 할당하며, 조직 로그인 경험을 맞춤화하세요. 동일한 역할과 권한을 공유하는 유사한 조직을 일괄 생성하려면 [조직 템플릿](/authorization/organization-template)을 만드세요. ### Logto Management API를 통한 생성 \{#create-via-logto-management-api} -Console은 수동 설정에 적합하지만, 대부분의 앱은 최종 사용자가 직접 조직을 생성하고 관리할 수 있도록 지원합니다. 이를 위해 Logto Management API로 해당 기능을 구현하세요. +콘솔은 수동 설정에 적합하지만, 대부분의 앱은 최종 사용자가 직접 조직을 생성 및 관리할 수 있도록 지원합니다. 이를 위해 Logto Management API로 해당 기능을 구현하세요. :::note -Logto Management API가 처음이라면 다음을 먼저 읽어보세요: +Logto Management API가 처음이거나, 조직 경험을 위한 Logto Management API 사용 기본 소개를 읽지 않았다면 먼저 아래를 참고하세요: + + Logto Management API로 앱 서비스를 설정하세요 + Management API Management API와 상호작용하기 @@ -59,14 +62,14 @@ curl \ -d '{"userIds":["string"]}' ``` -선택적으로, 사용자에게 특정 조직 역할을 할당할 수 있습니다 ([API 참조](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)). +필요하다면, 특정 조직 역할을 사용자에게 할당할 수도 있습니다 ([API 참조](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)). 자세한 내용은 [전체 API 명세](https://openapi.logto.io/group/endpoint-organizations)를 확인하세요. -이 호출들을 자체 API 레이어로 감싸세요. 사용자가 앱에서 “조직 생성” 작업을 수행할 때, 권한을 확인하여 요청을 검증한 후 Logto Management API를 호출하여 작업을 완료하세요. +이 호출들을 자체 API 레이어로 감싸세요. 사용자가 앱에서 “조직 생성” 작업을 수행할 때, 권한을 확인하여 요청을 검증한 후 Logto Management API를 호출해 작업을 완료하세요. ## 사용자 요청에서 조직 토큰 검증하기 \{#validating-organization-token-in-user-request} -앱에서 사용자가 조직의 컨텍스트에서 작업을 수행할 때는 일반 액세스 토큰 대신 조직 토큰을 사용해야 합니다. 조직 토큰은 조직 권한을 포함하는 [JWT](https://auth.wiki/jwt)입니다. 모든 [액세스 토큰](https://auth.wiki/access-token)과 마찬가지로, 클레임을 디코드하고 "scope" 클레임을 검증하여 권한을 적용할 수 있습니다. +앱에서 사용자가 조직 컨텍스트 내에서 작업을 수행할 때는 일반 액세스 토큰 대신 조직 토큰을 사용해야 합니다. 조직 토큰은 조직 권한이 포함된 [JWT](https://auth.wiki/jwt)입니다. 모든 [액세스 토큰](https://auth.wiki/access-token)과 마찬가지로, 클레임을 디코딩하고 "scope" 클레임을 검증하여 권한을 적용할 수 있습니다. 인가 (Authorization) 시나리오 및 조직 토큰 검증 방법에 대한 자세한 내용은 인가 (Authorization)를 참고하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index 9704eaaf3cd..53f098e66ee 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -4,19 +4,19 @@ sidebar_position: 4 # 조직 내에서 사용자 정보 가져오기 -## 사용 시점 \{#where-to-use-it} +## 사용처 \{#where-to-use-it} -이 기능은 일반적으로 사용자가 자신의 조직 정보를 보여주어야 하는 사용자 프로필 페이지에서 사용됩니다. +이 기능은 일반적으로 사용자의 조직 정보를 보여주어야 하는 사용자 프로필 페이지에서 사용됩니다. 조직 사용자 정보 ## 구현 방법 \{#how-to-implement-it} -조직 내에서 사용자 정보를 얻는 방법은 두 가지가 있습니다. +조직 내에서 사용자 정보를 가져오는 방법은 두 가지가 있습니다. -### 1. ID 토큰(ID token) 디코딩 \{#1-decode-the-id-token} +### ID 토큰(ID token) 디코딩하기 \{#decode-the-id-token} -ID 토큰(ID token)은 사용자 프로필 정보와 조직 관련 클레임(Claim)을 포함하는 표준 JWT입니다. SDK 메서드 `decodeIdToken()`을 호출하면 다음과 같은 JSON 객체를 얻을 수 있습니다: +ID 토큰(ID token)은 사용자 프로필 정보와 조직 관련 클레임(Claim)을 포함하는 표준 JWT입니다. SDK의 `decodeIdToken()` 메서드를 호출하면 다음과 같은 JSON 객체를 얻을 수 있습니다: ```json { @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -세션이 여전히 유효하다면, `signIn` 호출은 자격 증명 입력 없이 앱으로 다시 리디렉션됩니다. 사용자의 입장에서는 앱이 단순히 새로고침되고, 백그라운드에서 새로운 ID 토큰(ID token)이 발급됩니다. +세션이 여전히 유효하다면, `signIn` 호출은 자격 증명 입력 없이 앱으로 다시 리디렉션됩니다. 사용자 입장에서는 앱이 단순히 새로고침되고, 백그라운드에서 새로운 ID 토큰(ID token)이 발급됩니다. -### 2. `/oidc/me` 엔드포인트에서 사용자 정보 가져오기 \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### `/oidc/me` 엔드포인트에서 사용자 정보 가져오기 \{#fetch-user-info-from-the-oidc-me-endpoint} -조직 컨텍스트에서 실시간 사용자 정보를 얻으려면 `/oidc/me`에 요청할 수도 있습니다. SDK 메서드 `fetchUserInfo()`를 호출하세요. +조직 컨텍스트에서 실시간 사용자 정보를 얻으려면 `/oidc/me`에 요청할 수도 있습니다. SDK의 `fetchUserInfo()` 메서드를 호출하세요. 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 cd8b66eebb5..4ea41a75574 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 @@ -2,13 +2,13 @@ sidebar_position: 6 --- -# 조직 구성원 초대 +# 조직 구성원 초대하기 -다중 조직 애플리케이션에서는 조직에 구성원을 초대하는 것이 일반적인 요구 사항입니다. 이 가이드에서는 이 기능을 구현하는 단계와 기술적인 세부 사항을 안내합니다. +다중 테넌시 애플리케이션에서는 조직에 구성원을 초대하는 것이 일반적인 요구 사항입니다. 이 가이드에서는 이 기능을 구현하는 단계와 기술적 세부 사항을 안내합니다. ## 흐름 개요 \{#flow-overview} -전체 프로세스는 아래 다이어그램에 나타나 있습니다: +전체 프로세스는 아래 다이어그램과 같이 설명됩니다: ```mermaid sequenceDiagram @@ -17,19 +17,19 @@ sequenceDiagram Participant C as 귀하의 다중 조직 앱 Participant L as Logto - A ->> C: 초대받을 이메일과 역할 입력 + A ->> C: 초대받을 이메일 및 역할 입력 C ->> L: Management API로 조직 초대 생성 L -->> C: 초대 ID 반환 - C ->> C: 초대 ID로 초대 링크 작성 + C ->> C: 초대 ID로 초대 링크 생성 C ->> L: 초대 링크로 초대 이메일 발송 요청 L -->> U: 초대 링크가 포함된 초대 이메일 발송 U ->> C: 초대 링크 클릭 후 랜딩 페이지로 이동,
초대 수락 또는 거절 C ->> L: Management API로 초대 상태 업데이트 ``` -## 조직 역할 생성 \{#create-organization-roles} +## 조직 역할 생성하기 \{#create-organization-roles} -구성원을 초대하기 전에 조직 역할을 생성하세요. 역할과 권한에 대해 더 알고 싶다면 [조직 템플릿](/authorization/organization-template)을 참고하세요. +구성원을 초대하기 전에 조직 역할을 생성해야 합니다. 역할과 권한에 대해 더 알고 싶다면 [조직 템플릿](/authorization/organization-template)을 참고하세요. 이 가이드에서는 `admin`과 `member`라는 두 가지 대표적인 조직 역할을 생성해보겠습니다. @@ -49,7 +49,7 @@ sequenceDiagram 이 작업은 [Logto Console](https://cloud.logto.io/)에서 쉽게 할 수 있습니다. 또한 [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole)를 사용하여 프로그래밍 방식으로 조직 역할을 생성할 수도 있습니다. -## 이메일 커넥터 구성 \{#configure-your-email-connector} +## 이메일 커넥터 구성하기 \{#configure-your-email-connector} 초대는 이메일을 통해 전송되므로, [이메일 커넥터](/connectors/email-connectors)가 올바르게 구성되어 있는지 확인하세요. 초대를 보내려면, 사용 유형이 `OrganizationInvitation`인 [이메일 템플릿](/connectors/email-connectors/email-templates#email-template-types)을 구성해야 합니다. 조직(예: 이름, 로고) 및 초대자(예: 이메일, 이름) [변수](/connectors/email-connectors/email-templates#email-template-variables)를 내용에 포함할 수 있으며, 필요에 따라 [로컬라이즈된 템플릿](/connectors/email-connectors/email-templates#email-template-localization)도 커스터마이즈할 수 있습니다. @@ -72,7 +72,7 @@ Logto Cloud의 내장 “Logto 이메일 서비스”는 현재 `OrganizationInv ::: -## Logto Management API로 초대 처리 \{#handle-invitations-with-logto-management-api} +## Logto Management API로 초대 처리하기 \{#handle-invitations-with-logto-management-api} :::note @@ -80,17 +80,22 @@ Logto Cloud의 내장 “Logto 이메일 서비스”는 현재 `OrganizationInv ::: -### Logto Management API로 조직 초대 생성 \{#create-an-organization-invitation-with-logto-management-api} +### Logto Management API로 조직 초대 생성하기 \{#create-an-organization-invitation-with-logto-management-api} 조직 기능에는 초대 관련 Management API가 있습니다. 이 API들을 통해 다음을 할 수 있습니다: - `POST /api/organization-invitations`: 조직 역할이 할당된 조직 초대 생성 -- `POST /api/one-time-tokens`: 초대 수락 시 인증을 위한 일회용 토큰 생성. [자세히 알아보기](/end-user-flows/one-time-token) -- `POST /api/organization-invitations/{id}/message`: 초대받는 사람에게 이메일로 조직 초대 전송 - 참고: 페이로드는 `link` 속성을 지원하므로, 초대 ID를 기반으로 직접 초대 링크를 작성할 수 있습니다. 예시: - - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +- `POST /api/one-time-tokens`: 초대 수락 시 인증을 위한 일회성 토큰 생성 [자세히 알아보기](/end-user-flows/one-time-token) +- `POST /api/organization-invitations/{id}/message`: 초대받는 사람에게 이메일로 조직 초대 전송 + +:::note + +페이로드는 `link` 속성을 지원하므로, 초대 ID를 기반으로 직접 초대 링크를 만들 수 있습니다. 예시: + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 17a3656e2a0..bcd205a60cf 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -4,13 +4,15 @@ sidebar_position: 7 # 조직에 가입하기 -## 사용 위치 \{#where-to-use-it} +## 어디에 사용하나요 \{#where-to-use-it} -조직 목록은 일반적으로 사용자 온보딩 플로우 중에 나타납니다. 예를 들어, 관리자가 워크스페이스에 초대할 때 볼 수 있습니다. +조직 목록과 가입 플로우는 일반적으로 사용자 온보딩 과정에서 나타납니다. +예를 들어, 관리자가 누군가를 워크스페이스에 초대했지만, 사용자가 이메일 초대를 건너뛰고 앱에서 직접 로그인 또는 회원가입을 하는 경우입니다. -제품 관점에서, 다음 두 가지 주요 위치에 표시될 수 있습니다: +제품 내에서 이 플로우로 진입할 수 있는 진입점을 추가할 수 있습니다. +주요 위치는 두 가지입니다: -- 로그인 또는 회원가입 중의 **조직 찾기** +- 로그인 또는 회원가입 중에 표시되는 **조직 찾기** 조직 (비 API) 권한 보호 +조직 수준 API 리소스 보호 -## 조직 토큰의 스코프 업데이트 처리 \{#handle-scope-updates-in-organization-tokens} +::: -이 섹션에서는 조직 템플릿 및 인가 (Authorization) 시나리오에 대한 고급 주제를 다룹니다. 이러한 개념에 익숙하지 않다면 먼저 [인가 (Authorization)](/authorization) 및 [조직 템플릿](/authorization/organization-template)을 읽어보세요. +이 챕터에서는 Logto 조직 토큰에서 **권한 관리** 및 **스코프 변경과 권한 처리**에 대한 모범 사례에 중점을 둡니다. -조직 토큰의 스코프 업데이트 관리는 다음과 같습니다: +## 조직 토큰에서 스코프 업데이트 처리하기 \{#handle-scope-updates-in-organization-tokens} -### 기존 스코프 취소 \{#revoke-existing-scopes} +조직 토큰에서 스코프 업데이트를 관리하는 방법은 다음과 같습니다: -예를 들어, 관리자를 일반 멤버로 강등하면 해당 사용자의 스코프가 제거되어야 합니다. 이 경우, 캐시된 조직 토큰을 삭제하고 리프레시 토큰으로 새 토큰을 받아오세요. 축소된 스코프는 새로 발급된 조직 토큰에 즉시 반영됩니다. +### 기존 스코프 해제하기 \{#revoke-existing-scopes} -### 새로운 스코프 부여 \{#grant-new-scopes} +예를 들어, 관리자를 일반 멤버로 강등하는 경우 해당 사용자의 스코프를 제거해야 합니다. 이럴 때는 캐시된 조직 토큰을 삭제하고 리프레시 토큰으로 새 토큰을 받아오세요. 축소된 스코프는 새로 발급된 조직 토큰에 즉시 반영됩니다. + +### 새로운 스코프 부여하기 \{#grant-new-scopes} 이 경우는 두 가지 시나리오로 나눌 수 있습니다: -#### 인증 시스템에 이미 정의된 새로운 스코프 부여 \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} +#### 인증 시스템에 이미 정의된 새로운 스코프 부여하기 \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -스코프 취소와 유사하게, 새로 부여된 스코프가 이미 인증 서버에 등록되어 있다면 새 조직 토큰을 발급하면 새로운 스코프가 즉시 반영됩니다. +스코프 해제와 유사하게, 새로 부여된 스코프가 이미 인증 서버에 등록되어 있다면, 새 조직 토큰을 발급하면 새로운 스코프가 즉시 반영됩니다. -#### 인증 시스템에 새로 도입된 스코프 부여 \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### 인증 시스템에 새로 도입된 스코프 부여하기 \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} -이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의 프로세스를 트리거해야 합니다. 예를 들어, Logto SDK의 `signIn` 메서드를 호출하세요. +이 경우, 사용자의 조직 토큰을 업데이트하기 위해 재로그인 또는 재동의 과정을 트리거해야 합니다. 예를 들어, Logto SDK의 `signIn` 메서드를 호출하세요. -## 실시간으로 권한 확인 및 조직 토큰 업데이트 \{#check-permissions-in-real-time-and-update-the-organization-token} +## 실시간 권한 확인 및 조직 토큰 업데이트 \{#check-permissions-in-real-time-and-update-the-organization-token} Logto는 조직 내에서 실시간 사용자 권한을 가져올 수 있는 Management API를 제공합니다. @@ -55,9 +58,9 @@ Logto는 조직 내에서 실시간 사용자 권한을 가져올 수 있는 Man ``` - 이 과정에서는 재로그인 또는 재동의 프로세스가 필요하지 않습니다. Logto SDK가 자동으로 새 조직 토큰을 발급합니다. + 이 과정에서는 재로그인 또는 재동의 과정이 필요하지 않습니다. Logto SDK가 자동으로 새 조직 토큰을 발급합니다. -- 인증 시스템에 새로운 스코프가 도입된 경우, 재로그인 또는 재동의 프로세스를 트리거하여 사용자의 조직 토큰을 업데이트해야 합니다. 예를 들어, React SDK에서는 다음과 같이 할 수 있습니다: +- 인증 시스템에 새로운 스코프가 도입된 경우, 재로그인 또는 재동의 과정을 트리거하여 사용자의 조직 토큰을 업데이트해야 합니다. 예를 들어, React SDK에서는 다음과 같이 할 수 있습니다: ```tsx const { clearAllTokens, signIn } = useLogto(); @@ -72,4 +75,4 @@ Logto는 조직 내에서 실시간 사용자 권한을 가져올 수 있는 Man ``` - 위 코드는 동의 화면으로 이동을 트리거하고, 사용자의 조직 토큰에 업데이트된 스코프와 함께 앱으로 자동 리디렉션됩니다. + 위 코드는 동의 화면으로 이동을 트리거하며, 사용자의 조직 토큰에 업데이트된 스코프가 반영된 상태로 앱으로 자동 리디렉션됩니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index c610070776b..b62ef133158 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,14 +4,13 @@ sidebar_position: 2 # Logto Management API로 앱 서비스 설정하기 -Logto **Management API**를 사용하여 앱에서 맞춤형 **조직 플로우**를 구축할 수 있습니다. 아래는 Management API 통합을 위한 기본 설정 단계입니다. 이미 익숙하다면 [튜토리얼](/integrate-logto/interact-with-management-api)로 바로 넘어가도 됩니다. +Logto는 강력한 Management API를 제공하여, 앱 내에서 자체 조직 플로우를 생성하고 맞춤화할 수 있습니다. 이 API의 작동 방식을 이해하는 것은 맞춤형 설정을 설계하는 데 핵심적입니다. 아래는 Management API를 통합하여 조직 경험을 구현하는 기본 단계와 개요입니다. -설정에 익숙해지면, 추가 API를 탐색하여 나머지 플로우를 비즈니스 요구에 맞게 맞춤화할 수 있습니다. +기본 사항을 이미 알고 있다면 [튜토리얼](/integrate-logto/interact-with-management-api)로 바로 넘어가도 됩니다. 설정에 익숙해진 후에는 추가 API를 탐색하여 나머지 플로우를 비즈니스 요구에 맞게 조정할 수 있습니다. -## 기계 간 (M2M) 연결 설정하기 \{#establish-a-machine-to-machine-connection} +## 기계 간 연결(M2M) 설정하기 \{#establish-a-machine-to-machine-connection} -Logto는 **기계 간 (M2M) 인증 (Authentication)**을 사용하여 백엔드 서비스를 Logto Management API 엔드포인트에 안전하게 연결합니다. -이후 백엔드 서비스는 Management API를 사용하여 **조직 생성**, **멤버 추가 또는 제거** 등 조직 관련 작업을 처리할 수 있습니다. +Logto는 **기계 간 (M2M) 인증 (Authentication)**을 사용하여 백엔드 서비스를 Logto Management API 엔드포인트에 안전하게 연결합니다. 백엔드 서비스는 Management API를 사용하여 **조직 생성**, **멤버 추가 또는 제거** 등 조직 관련 작업을 처리할 수 있습니다. 이 과정은 다음과 같습니다: @@ -31,19 +30,19 @@ curl \ ## 앱 서버 보호하기 \{#protect-your-app-server} -최종 사용자가 일부 조직 작업을 셀프 서비스로 수행할 수 있으므로, 최종 사용자와 앱 서버 사이에 인가 (Authorization) 계층을 추가하세요. 서버는 모든 요청을 중재하고, 사용자의 조직 토큰 (Organization token)과 필요한 스코프 (Scope)를 검증한 후에만 서버에 저장된 M2M 자격 증명을 사용하여 Management API를 호출해야 합니다. +최종 사용자가 직접 일부 조직 작업을 수행할 수 있으므로, 최종 사용자와 앱 서버 사이에 인가 (Authorization) 계층을 추가하는 것이 중요합니다. 이 계층은 사용하는 Logto Management API 엔드포인트와 제품의 API 구조에 따라 전역 또는 조직 단위로 적용할 수 있습니다. 서버는 모든 요청을 중재하고, 사용자의 조직 토큰 (Organization token)과 필요한 스코프 (Scope)를 검증한 후에만 서버에 저장된 M2M 자격 증명을 사용하여 Management API를 호출해야 합니다. -사용자가 조직 토큰 (Organization token)을 제시하여 작업(예: 조직 생성)을 요청하면, 서버는 먼저 토큰의 스코프 (Scope)를 검증합니다. 토큰에 `org:create`와 같은 필요한 스코프가 포함되어 있으면 요청을 인가 (Authorize)하고, M2M 플로우를 통해 Logto Management API를 호출하여 조직을 생성합니다. +사용자가 조직 토큰 (Organization token)을 제시하여 작업(예: 조직 생성)을 요청하면, 서버는 먼저 토큰의 스코프 (Scope)를 검증합니다. 토큰에 `org:create`와 같은 필요한 스코프가 포함되어 있다면 요청을 인가 (Authorize)하고, M2M 플로우를 통해 Logto Management API를 호출하여 조직을 생성합니다. -토큰에 필요한 스코프가 없으면 403 Forbidden을 반환하고 M2M 로직을 건너뜁니다. 이를 통해 적절한 권한이 없는 사용자가 조직을 생성하지 못하도록 보장할 수 있습니다. +토큰에 필요한 스코프가 없다면 403 Forbidden을 반환하고 M2M 로직을 건너뜁니다. 이를 통해 적절한 권한이 없는 사용자가 조직을 생성하지 못하도록 보장할 수 있습니다. 아래는 일반적인 인가 (Authorization) 패턴입니다. -### 조직 권한 (Permission) 사용하기 \{#using-organization-permissions} +### 조직 권한 사용하기 \{#using-organization-permissions} -먼저, [이전 섹션](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations)에서 조직 권한 (Permission)과 역할 (Role)을 조직 템플릿에 정의했는지 확인하세요. +먼저, [이전 섹션](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations)에서 조직 권한과 역할을 조직 템플릿에 정의했는지 확인하세요. -그런 다음, Logto 설정에 `UserScope.Organizations` (값: `urn:logto:organization`)이 포함되어 있는지 확인하세요. React SDK를 예로 들면: +그런 다음, Logto 설정에 `UserScope.Organizations` (값: `urn:logto:organization`)이 포함되어 있는지 확인하세요. React SDK 예시는 다음과 같습니다: ```jsx // src/App.js @@ -67,14 +66,24 @@ const config = { }; ``` -이렇게 하면 `getOrganizationToken(organizationId)`를 호출할 때, 클라이언트 SDK가 사용자에게 할당된 조직 권한 (Permission)이 포함된 조직 토큰 (Organization token)을 요청하게 됩니다. 이후 백엔드 서비스는 이 토큰을 검증하고, 해당 권한에 따라 후속 요청을 인가 (Authorize)할 수 있습니다. +이렇게 하면 `getOrganizationToken(organizationId)`를 호출할 때, 클라이언트 SDK가 사용자에게 할당된 조직 권한이 포함된 조직 토큰 (Organization token)을 요청하게 됩니다. 백엔드 서비스는 이 토큰을 검증하고, 해당 권한에 따라 후속 요청을 인가 (Authorize)할 수 있습니다. -조직 수준(비 API) 권한 보호에 대한 자세한 내용은 [전체 가이드](/authorization/organization-permissions)를 참고하세요. +조직 단위(비 API) 권한 보호에 대한 자세한 내용은 [전체 가이드](/authorization/organization-permissions)를 참고하세요. -### 조직 수준 권한과 API 수준 권한 혼합 사용하기 \{#mixing-organization-level-permissions-and-api-level-permissions} +### API 단위 권한 사용하기 \{#using-api-level-permissions} -API 리소스와 권한이 글로벌로 등록되어 있지만, 역할 (Role)이 조직 수준에서 정의된 경우에 해당합니다(조직 템플릿에서 조직 역할에 API 수준 권한을 할당할 수 있습니다). +API 리소스와 권한이 전역적으로 등록되어 있지만, 역할은 조직 단위로 정의된 경우에 해당합니다(조직 템플릿에서 조직 역할에 API 단위 권한을 할당할 수 있습니다). -구현 방식은 이전 섹션과 동일합니다. 항상 조직 ID를 제공하고 `getOrganizationToken(organizationId)`를 호출하여 조직 토큰 (Organization token)을 받아야 합니다. 그렇지 않으면 조직 권한이 포함되지 않습니다. +구현 방식은 이전 섹션과 동일합니다. 항상 조직 ID를 제공하고 `getOrganizationToken(organizationId)`를 호출하여 조직 토큰 (Organization token)을 받아야 하며, 그렇지 않으면 조직 권한이 포함되지 않습니다. -조직 수준 API 권한 보호에 대한 자세한 내용은 [전체 가이드](/authorization/organization-level-api-resources)를 참고하세요. +조직 단위 API 권한 보호에 대한 자세한 내용은 [전체 가이드](/authorization/organization-level-api-resources)를 참고하세요. + +### 글로벌 RBAC 사용하기 \{#using-global-rbac} + +이 경우, Logto Management API를 사용하여 시스템 수준 접근 제어를 구현할 수 있습니다. + +멀티 테넌트 환경에서는 슈퍼유저 또는 슈퍼 관리자 역할을 두는 것이 일반적입니다. 예를 들어, Logto로 SaaS 플랫폼을 구축하는 경우, Logto 콘솔에 로그인하지 않고도 자체 앱 내에서 모든 클라이언트 조직을 직접 관리할 수 있는 슈퍼유저가 필요할 수 있습니다. + +이 슈퍼유저는 단일 조직 범위를 넘어서는 시스템 전체 권한이 필요한 대량 조직 생성 또는 삭제와 같은 상위 작업을 수행할 수 있습니다. 이를 위해 Logto에 API 리소스를 등록하고, Logto Management API를 활용하며, 글로벌 RBAC로 이러한 권한을 관리하세요. + +RBAC의 접근 제어 통합 및 관리에 대한 자세한 내용은 [전체 가이드](/authorization/global-api-resources)를 참고하세요. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index b12bf88195f..d0758546997 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -20,20 +20,23 @@ Existem duas maneiras de criar organizações para seu aplicativo. ### Criar via Logto Console \{#create-via-logto-console} -Crie organizações manualmente na interface do Logto Console. Vá para Console > Organizações para criar organizações, atribuir membros e papéis, e personalizar a experiência de login da organização. +Crie organizações manualmente na interface do Logto Console. Vá para Console > Organizações (Organizations) para criar organizações, atribuir membros e papéis, e personalizar a experiência de login da organização. Crie um [modelo de organização](/authorization/organization-template) para criar em lote organizações semelhantes que compartilham os mesmos papéis e permissões. ### Criar via Logto Management API \{#create-via-logto-management-api} -O Console é ótimo para configuração manual, mas a maioria dos aplicativos permite que os usuários finais se autoatendam—criem e gerenciem organizações diretamente em seu aplicativo. Para isso, implemente esses recursos com o Logto Management API. +O console é ótimo para configuração manual, mas a maioria dos aplicativos permite que os usuários finais se autoatendam—criem e gerenciem organizações diretamente no seu aplicativo. Para isso, implemente esses recursos com o Logto Management API. :::note -Se você é novo no Logto Management API, leia isto primeiro: +Se você é novo no Logto Management API ou ainda não leu a introdução básica sobre o uso do Logto Management API para experiência de organização, leia estes primeiro: + + Configure seu serviço de aplicativo com o Logto Management API + Management API -Interagir com Management API +Interaja com o Management API ::: @@ -69,4 +72,4 @@ Envolva essas chamadas em sua própria camada de API. Quando os usuários realiz No seu aplicativo, quando os usuários realizam ações no contexto de uma organização, eles devem usar um token de organização em vez de um token de acesso comum. O token de organização é um [JWT](https://auth.wiki/jwt) que contém permissões da organização. Assim como qualquer [token de acesso](https://auth.wiki/access-token), você pode decodificar as reivindicações e verificar a reivindicação "scope" para aplicar permissões. -Veja Autorização (Authorization) para saber mais sobre cenários de autorização e como validar tokens de organização. +Veja Autorização (Authorization) para mais sobre cenários de autorização e como validar tokens de organização. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index beae493c546..e187d934dac 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -6,7 +6,7 @@ sidebar_position: 4 ## Onde usar \{#where-to-use-it} -Isso geralmente é usado na página de perfil do usuário, onde os usuários precisam exibir suas informações da organização. +Isso geralmente é utilizado na página de perfil do usuário, onde é necessário exibir as informações da organização. Informações do usuário da organização @@ -14,7 +14,7 @@ Isso geralmente é usado na página de perfil do usuário, onde os usuários pre Existem duas maneiras de obter informações do usuário dentro de uma organização. -### 1. Decodificar o token de ID (ID token) \{#1-decode-the-id-token} +### Decodificar o token de ID (ID token) \{#decode-the-id-token} O token de ID (ID token) é um JWT padrão que contém informações do perfil do usuário e reivindicações relacionadas à organização. Chame o método do SDK `decodeIdToken()` para obter um objeto JSON como este: @@ -42,8 +42,8 @@ O token de ID (ID token) é um JWT padrão que contém informações do perfil d } ``` -No entanto, o token de ID (ID token) é emitido apenas durante a autenticação e pode ficar desatualizado se o perfil do usuário for alterado posteriormente. -Para obter as informações mais atualizadas, use a segunda abordagem abaixo ou chame `clearAllTokens()` e reinicie um fluxo de autenticação para obter um novo token de ID. +No entanto, o token de ID (ID token) só é emitido durante a autenticação e pode ficar desatualizado se o perfil do usuário for alterado posteriormente. +Para obter as informações mais atualizadas, utilize a segunda abordagem abaixo ou chame `clearAllTokens()` e reinicie um fluxo de autenticação para obter um novo token de ID. ```ts await logtoClient.clearAllTokens(); @@ -55,6 +55,6 @@ logtoClient.signIn({ Se a sessão ainda for válida, a chamada `signIn` irá redirecionar de volta para seu aplicativo sem exigir credenciais. Do ponto de vista do usuário, o aplicativo simplesmente é atualizado e um novo token de ID é emitido nos bastidores. -### 2. Buscar informações do usuário no endpoint `/oidc/me` \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### Buscar informações do usuário no endpoint `/oidc/me` \{#fetch-user-info-from-the-oidc-me-endpoint} -Você também pode requisitar `/oidc/me` para obter informações em tempo real do usuário no contexto da organização. Chame o método do SDK `fetchUserInfo()`. +Você também pode requisitar `/oidc/me` para obter informações do usuário em tempo real no contexto da organização. Chame o método do SDK `fetchUserInfo()`. 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 773288c042a..99f12034191 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 @@ -4,7 +4,7 @@ sidebar_position: 6 # Convidar membros da organização -Em aplicativos com múltiplas organizações, um requisito comum é convidar membros para uma organização. Este guia apresenta as etapas e detalhes técnicos para implementar esse recurso. +Em aplicativos multi-inquilinos, um requisito comum é convidar membros para uma organização. Este guia apresenta as etapas e detalhes técnicos para implementar esse recurso. ## Visão geral do fluxo \{#flow-overview} @@ -47,11 +47,11 @@ O papel `admin` tem acesso total a todos os recursos da organização, enquanto - `write:data` - Acesso de escrita a todos os recursos de dados da organização. - `invite:member` - Convidar membros para a organização. -Isso pode ser feito facilmente no [Logto Console](https://cloud.logto.io/). Você também pode usar o [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) para criar papéis da organização programaticamente. +Isso pode ser feito facilmente no [Logto Console](https://cloud.logto.io/). Você também pode usar o [Logto Management API](https://openapi.logto.io/operation/operation-createorganizationrole) para criar papéis de organização programaticamente. ## Configure seu conector de e-mail \{#configure-your-email-connector} -Como os convites são enviados por e-mail, certifique-se de que seu [conector de e-mail](/connectors/email-connectors) está devidamente configurado. Para enviar convites, configure um [template de e-mail](/connectors/email-connectors/email-templates#email-template-types) com o tipo de uso `OrganizationInvitation`. Você pode incluir variáveis da organização (por exemplo, nome, logo) e do convidador (por exemplo, e-mail, nome) [variáveis](/connectors/email-connectors/email-templates#email-template-variables) no conteúdo, e personalizar [templates localizados](/connectors/email-connectors/email-templates#email-template-localization) conforme necessário. +Como os convites são enviados por e-mail, certifique-se de que seu [conector de e-mail](/connectors/email-connectors) está devidamente configurado. Para enviar convites, configure um [template de e-mail](/connectors/email-connectors/email-templates#email-template-types) com o tipo de uso `OrganizationInvitation`. Você pode incluir variáveis de organização (por exemplo, nome, logo) e do convidador (por exemplo, e-mail, nome) [variáveis](/connectors/email-connectors/email-templates#email-template-variables) no conteúdo, e personalizar [templates localizados](/connectors/email-connectors/email-templates#email-template-localization) conforme necessário. Um exemplo de template de e-mail para o tipo de uso `OrganizationInvitation` é mostrado abaixo: @@ -72,7 +72,7 @@ O “serviço de e-mail Logto” integrado do Logto Cloud atualmente não suport ::: -## Gerencie convites com Logto Management API \{#handle-invitations-with-logto-management-api} +## Gerenciar convites com Logto Management API \{#handle-invitations-with-logto-management-api} :::note @@ -87,10 +87,15 @@ Há um conjunto de APIs de convite no recurso de organizações. Com essas APIs, - `POST /api/organization-invitations`: Criar um convite de organização com um papel de organização atribuído. - `POST /api/one-time-tokens`: Criar um token de uso único para o convidado autenticar ao aceitar o convite. [Saiba mais](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message`: Enviar o convite da organização para o convidado por e-mail. - Observação: O payload suporta uma propriedade `link` para que você possa compor seu próprio link de convite com base no ID do convite. Por exemplo: - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +O payload suporta uma propriedade `link` para que você possa compor seu próprio link de convite com base no ID do convite. Por exemplo: + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 22166e2ae81..acf25b19ced 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -6,27 +6,32 @@ sidebar_position: 7 ## Onde usar \{#where-to-use-it} -A lista de organizações normalmente aparece durante o fluxo de onboarding do usuário. Por exemplo, quando um administrador convida você para participar de um workspace. +A lista de organizações e o fluxo de entrada geralmente aparecem durante o onboarding do usuário. +Por exemplo, quando um administrador convida alguém para um workspace, mas o usuário ignora o convite por e-mail e faz login ou cadastro diretamente no aplicativo. -Do ponto de vista do produto, ela pode aparecer em dois lugares principais: +No seu produto, você pode querer adicionar pontos de entrada para esse fluxo. +Ele pode aparecer em dois locais principais: -- O **localizador de organização** durante o login ou cadastro +- O **localizador de organizações** durante o login ou cadastro Entrar na organização durante o login ou cadastro -- O **seletor de organização** dentro do aplicativo +- O **seletor de organizações** dentro do aplicativo -Entrar na organização dentro do app +Entrar na organização dentro do aplicativo -## Use a Management API do Logto para permitir que usuários entrem em uma organização \{#use-the-logto-management-api-to-let-users-join-an-organization} +## Use a Logto Management API para permitir que usuários entrem em uma organização \{#use-the-logto-management-api-to-let-users-join-an-organization} -Na seção anterior, abordamos a criação e o envio de convites para organizações usando a Management API do Logto. -Em seguida, implemente uma página de destino que trate o link de convite quando os convidados chegarem ao seu aplicativo. +Na seção anterior, abordamos a criação e o envio de convites para organizações usando a Logto Management API. +A seguir, implemente uma página de destino que trata o link de convite quando os convidados chegam ao seu aplicativo. - `GET /api/organization-invitations` e `GET /api/organization-invitations/{id}`: Obtenha todos os convites ou um específico pelo ID. Na sua página de destino, use essas APIs para listar todos os convites ou mostrar os detalhes de um convite específico que o usuário recebeu. - `PUT /api/organization-invitations/{id}/status`: Aceite ou rejeite o convite atualizando seu status. - Use esta API para tratar a resposta do usuário. + Use esta API para lidar com a resposta do usuário. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index ddc5547ab64..8042b870ba9 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,21 +2,28 @@ sidebar_position: 8 --- -# Gerenciamento de permissões e recursos +# Lidar com atualizações de escopo em tokens de organização -Use a organização como um recurso e aplique um modelo de organização para protegê-la. Por exemplo, cada organização possui seus próprios documentos dentro de um tenant. Apenas usuários com os papéis corretos podem editar ou excluir esses documentos. +Com a configuração acima, você pode enviar convites por e-mail, e os convidados podem ingressar na organização com o papel atribuído. -Veja [Permissões de organização](/authorization/organization-permissions) para detalhes. +Usuários com diferentes papéis na organização terão diferentes escopos (permissões) em seus tokens de organização. Tanto seu aplicativo cliente quanto os serviços de backend devem verificar esses escopos para determinar os recursos visíveis e as ações permitidas. -## Use o 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} +Como mencionado anteriormente, o template de organização serve como uma camada-chave de controle de acesso para proteger [permissões da organização](/authorization/organization-permissions) ou [APIs em nível de organização](/authorization/organization-level-api-resources). Certifique-se de revisar as seções de autorização e escolher o modelo de autorização que melhor se adapta ao seu produto. -Com a configuração acima, você pode enviar convites por e-mail, e os convidados podem ingressar na organização com o papel atribuído. +:::note + + + Proteger permissões da organização (não-API) + + + Proteger recursos de API em nível de organização + -Usuários com diferentes papéis na organização terão diferentes escopos (permissões) em seus tokens de organização. Tanto seu aplicativo cliente quanto os serviços de backend devem verificar esses escopos para determinar funcionalidades visíveis e ações permitidas. +::: -## Lide com atualizações de escopo em tokens de organização \{#handle-scope-updates-in-organization-tokens} +Este capítulo foca em **gestão de permissões** e melhores práticas para **lidar com mudanças de escopo e permissões** em tokens de organização do Logto. -Esta seção aborda tópicos avançados sobre o gerenciamento do modelo de organização e cenários de autorização. Se você não estiver familiarizado com esses conceitos, leia [Autorização (Authorization)](/authorization) e [Modelo de organização](/authorization/organization-template) primeiro. +## Lidar com atualizações de escopo em tokens de organização \{#handle-scope-updates-in-organization-tokens} Gerenciar atualizações de escopo em tokens de organização envolve: @@ -32,13 +39,13 @@ Isso pode ser dividido em dois cenários: Semelhante à revogação de escopos, se o novo escopo concedido já estiver registrado no servidor de autenticação, emita um novo token de organização e os novos escopos serão refletidos imediatamente. -#### Conceder novos escopos que estão sendo introduzidos agora no seu sistema de autenticação \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### Conceder novos escopos recém-introduzidos no seu sistema de autenticação \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} Nesse caso, acione um processo de novo login ou novo consentimento para atualizar o token de organização do usuário. Por exemplo, chame o método `signIn` no SDK do Logto. ## Verifique permissões em tempo real e atualize o token de organização \{#check-permissions-in-real-time-and-update-the-organization-token} -O Logto fornece uma Management API para buscar permissões de usuário em tempo real na organização. +O Logto fornece uma Management API para buscar permissões do usuário em tempo real na organização. - `GET /api/organizations/{id}/users/{userId}/scopes` ([Referências da API](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) @@ -50,20 +57,20 @@ Compare os escopos no token de organização do usuário com as permissões em t const { clearAccessToken } = useLogto(); ... - // Se os escopos buscados em tempo real forem menores que os escopos do token de organização + // Se os escopos em tempo real buscados forem menores que os escopos do token de organização await clearAccessToken(); ``` - Isso não requer um novo login ou processo de consentimento. Novos tokens de organização serão emitidos automaticamente pelo SDK do Logto. + Isso não requer um novo login ou processo de novo consentimento. Novos tokens de organização serão emitidos automaticamente pelo SDK do Logto. -- Se um novo escopo for introduzido no seu sistema de autenticação, acione um novo login ou processo de consentimento para atualizar o token de organização do usuário. Por exemplo, com o React SDK: +- Se um novo escopo for introduzido no seu sistema de autenticação, acione um processo de novo login ou novo consentimento para atualizar o token de organização do usuário. Por exemplo, com o React SDK: ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // Se os escopos buscados em tempo real tiverem escopos recém-atribuídos em relação aos escopos do token de organização + // Se os escopos em tempo real buscados tiverem escopos recém-atribuídos em relação aos escopos do token de organização await clearAllTokens(); signIn({ redirectUri: '', diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index ed918d650a7..8f9dec38e2b 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,20 +4,21 @@ sidebar_position: 2 # Configure seu serviço de aplicativo com a Management API do Logto -Use a **Management API** do Logto para construir fluxos personalizados de **organização (organization flows)** em seu aplicativo. Abaixo estão as etapas básicas de configuração para integrar a Management API. Se você já estiver familiarizado, pode pular direto para o [tutorial](/integrate-logto/interact-with-management-api). +O Logto oferece uma poderosa Management API que permite criar e personalizar seu próprio fluxo de organização dentro do seu aplicativo. +Compreender como ela funciona é fundamental para projetar sua configuração personalizada. Abaixo estão os passos básicos e um resumo para integrar a Management API e implementar sua experiência de organização. -Depois de se familiarizar com a configuração, você pode explorar APIs adicionais para adaptar o restante dos fluxos às necessidades do seu negócio. +Se você já conhece o básico, pode pular direto para o [tutorial](/integrate-logto/interact-with-management-api). Depois de se familiarizar com a configuração, você pode explorar APIs adicionais para adaptar o restante dos fluxos às necessidades do seu negócio. ## Estabeleça uma conexão máquina para máquina \{#establish-a-machine-to-machine-connection} O Logto utiliza **autenticação máquina para máquina (M2M)** para conectar com segurança seu serviço backend ao endpoint da Management API do Logto. -Seu serviço backend pode então usar a Management API para lidar com tarefas relacionadas à organização, como **criar organizações (organizations)**, **adicionar ou remover membros**, e muito mais. +Seu serviço backend pode então usar a Management API para lidar com tarefas relacionadas à organização, como **criar organizações**, **adicionar ou remover membros**, e muito mais. Isso envolve: 1. **Criar um aplicativo Máquina para Máquina (M2M)** no Logto Console. -Detalhes do app M2M +Detalhes do aplicativo M2M 2. **Obter um token de acesso M2M** do Logto. [Saiba mais](/integrate-logto/interact-with-management-api#fetch-an-access-token). 3. **Chamar as Management APIs do Logto** a partir do seu serviço backend. Por exemplo, listar todas as organizações: @@ -31,9 +32,9 @@ curl \ ## Proteja seu servidor de aplicativo \{#protect-your-app-server} -Como os usuários finais podem realizar certas operações de organização de forma self-service, adicione uma camada de autorização entre o usuário final e seu servidor de aplicativo. O servidor deve mediar cada solicitação, validar o token de organização do usuário e os escopos necessários, e só então usar uma credencial M2M mantida no servidor para invocar a Management API. +Como os usuários finais podem realizar certas ações de organização por conta própria, é importante adicionar uma camada de autorização entre o usuário final e seu servidor de aplicativo. Você pode aplicar essa camada globalmente ou no nível da organização, dependendo de quais endpoints da Management API do Logto você utiliza e de como a API do seu produto está estruturada. O servidor deve intermediar cada solicitação, validar o token com escopo de organização do usuário e os escopos necessários, e só então usar uma credencial M2M mantida no servidor para invocar a Management API. -Quando um usuário apresenta um token de organização para solicitar uma ação (por exemplo, criar uma organização), o servidor primeiro valida os escopos no token. Se o token incluir o escopo necessário, como `org:create`, autorize a solicitação e chame a Management API do Logto via o fluxo M2M para criar a organização. +Quando um usuário apresenta um token de organização para solicitar uma ação (por exemplo, criar uma organização), o servidor primeiro valida os escopos no token. Se o token incluir o escopo necessário, como `org:create`, autorize a solicitação e chame a Management API do Logto via fluxo M2M para criar a organização. Se o token não contiver os escopos necessários, retorne um 403 Forbidden e ignore a lógica M2M. Isso garante que usuários sem os privilégios apropriados não possam criar organizações. @@ -43,7 +44,7 @@ Abaixo estão padrões comuns de autorização. Primeiro, certifique-se de que você definiu permissões e papéis de organização em seu template de organização na [seção anterior](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations). -Depois, garanta que `UserScope.Organizations` (valor: `urn:logto:organization`) esteja incluído na configuração do Logto. Veja o SDK React como exemplo: +Depois, garanta que `UserScope.Organizations` (valor: `urn:logto:organization`) esteja incluído na configuração do Logto. Tomando o SDK React como exemplo: ```jsx // src/App.js @@ -53,7 +54,7 @@ const config = { endpoint: 'https://.logto.app/', // Seu endpoint Logto appId: '40fmibayagoo00lj26coc', // Seu app id resources: [ - 'https://my.company.com/api', // Seu identificador global de recurso de API + 'https://my.company.com/api', // Identificador global do recurso de API ], scopes: [ UserScope.Email, @@ -67,14 +68,24 @@ const config = { }; ``` -Isso garante que, ao chamar `getOrganizationToken(organizationId)`, o SDK cliente solicita um token de organização que contém as permissões de organização atribuídas ao usuário. Seu serviço backend pode então validar o token e autorizar as solicitações subsequentes com base nessas permissões. +Isso garante que, ao chamar `getOrganizationToken(organizationId)`, o SDK do cliente solicite um token de organização que contenha as permissões de organização atribuídas ao usuário. Seu serviço backend pode então validar o token e autorizar solicitações subsequentes com base nessas permissões. Para detalhes sobre como proteger permissões de organização (não relacionadas à API), veja o [guia completo](/authorization/organization-permissions). -### Misturando permissões de nível de organização e permissões de nível de API \{#mixing-organization-level-permissions-and-api-level-permissions} +### Usando permissões no nível da API \{#using-api-level-permissions} -Isso se aplica quando seus recursos e permissões de API são registrados globalmente, mas os papéis são definidos no nível da organização (você pode atribuir permissões de nível de API a papéis de organização no template da organização). +Isso se aplica quando seus recursos de API e permissões são registrados globalmente, mas os papéis são definidos no nível da organização (você pode atribuir permissões de API a papéis de organização no template de organização). -A implementação é a mesma da seção anterior. Sempre forneça o ID da organização e chame `getOrganizationToken(organizationId)` para buscar um token de organização; caso contrário, as permissões de organização não serão incluídas. +A implementação é a mesma da seção anterior. Sempre forneça o ID da organização e chame `getOrganizationToken(organizationId)` para obter um token de organização; caso contrário, as permissões de organização não serão incluídas. -Para detalhes sobre como proteger permissões de API de nível de organização, veja o [guia completo](/authorization/organization-level-api-resources). +Para detalhes sobre como proteger permissões de API no nível da organização, veja o [guia completo](/authorization/organization-level-api-resources). + +### Usando RBAC global \{#using-global-rbac} + +Neste caso, você pode usar a Management API do Logto para implementar o controle de acesso em nível de sistema. + +Em um ambiente multi-tenant, um padrão comum é ter um papel de superusuário ou super admin. Por exemplo, se você está construindo uma plataforma SaaS com Logto, pode querer um superusuário que possa gerenciar todas as organizações de clientes diretamente dentro do seu próprio aplicativo, sem precisar acessar o Logto Console. + +Esse superusuário pode realizar ações de nível superior, como criar ou excluir organizações em massa, que exigem permissões amplas de sistema além de qualquer contexto de organização individual. Para habilitar isso, registre um recurso de API no Logto enquanto utiliza a Management API do Logto e use o RBAC global para gerenciar essas permissões. + +Para mais detalhes sobre integração e gerenciamento de controle de acesso para RBAC, veja o [guia completo](/authorization/global-api-resources). diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 332c5af54bf..e987682b4e1 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,42 +4,45 @@ sidebar_position: 3 # สร้างองค์กร -ลองจินตนาการว่าคุณกำลังสร้าง [แอปหลายผู้เช่า (multi-tenant app)](https://auth.wiki/multi-tenancy) (เช่น แอป SaaS หลายผู้เช่า) ที่ให้บริการลูกค้าหลายราย โดยแต่ละรายจะมีผู้เช่า (tenant) ของตนเอง +ลองจินตนาการว่าคุณกำลังสร้าง [แอปหลายผู้เช่า (multi-tenant app)](https://auth.wiki/multi-tenancy) (เช่น แอป SaaS หลายผู้เช่า) ที่ให้บริการลูกค้าหลายราย และแต่ละรายมี tenant ของตนเอง -โดยปกติแล้ว องค์กรจะถูกสร้างขึ้นเมื่อ: +โดยปกติจะมีการสร้างองค์กรเมื่อ: -1. ลูกค้าใหม่สมัครใช้งานและสร้างทั้งบัญชีและผู้เช่าสำหรับธุรกิจของตน -2. ผู้ใช้ที่มีอยู่แล้วสามารถสร้างองค์กรใหม่จากภายในแอป +1. ลูกค้าใหม่ลงทะเบียนและสร้างทั้งบัญชีและ tenant สำหรับธุรกิจของตน +2. ผู้ใช้ที่มีอยู่สามารถสร้างองค์กรใหม่จากภายในแอป บัญชีใหม่สร้างองค์กร ผู้ใช้ที่มีอยู่สร้างองค์กร -## การสร้างองค์กรในแอป \{#implement-organization-creation} +## การสร้างองค์กรในแอปของคุณ \{#implement-organization-creation} มีสองวิธีในการสร้างองค์กรสำหรับแอปของคุณ ### สร้างผ่าน Logto Console \{#create-via-logto-console} -สร้างองค์กรด้วยตนเองผ่าน UI ของ Logto Console ไปที่ Console > Organizations เพื่อสร้างองค์กร กำหนดสมาชิกและบทบาท และปรับแต่งประสบการณ์การลงชื่อเข้าใช้องค์กร +สร้างองค์กรด้วยตนเองผ่าน UI ของ Logto Console ไปที่ Console > Organizations เพื่อสร้างองค์กร กำหนดสมาชิกและบทบาท และปรับแต่งประสบการณ์การลงชื่อเข้าใช้ขององค์กร -สร้าง [แม่แบบองค์กร (organization template)](/authorization/organization-template) เพื่อสร้างองค์กรที่มีบทบาทและสิทธิ์เหมือนกันแบบกลุ่ม +สร้าง [เทมเพลตองค์กร](/authorization/organization-template) เพื่อสร้างองค์กรที่มีบทบาทและสิทธิ์เหมือนกันแบบกลุ่ม ### สร้างผ่าน Logto Management API \{#create-via-logto-management-api} -Console เหมาะสำหรับการตั้งค่าด้วยตนเอง แต่แอปส่วนใหญ่จะให้ผู้ใช้ปลายทางสร้างและจัดการองค์กรได้เองโดยตรงในแอปของคุณ หากต้องการเช่นนั้น ให้พัฒนาฟีเจอร์เหล่านี้ด้วย Logto Management API +Console เหมาะสำหรับการตั้งค่าด้วยตนเอง แต่แอปส่วนใหญ่จะให้ผู้ใช้ปลายทางสร้างและจัดการองค์กรได้เองโดยตรงในแอปของคุณ หากต้องการทำเช่นนั้น ให้พัฒนาฟีเจอร์เหล่านี้ด้วย Logto Management API :::note -หากคุณยังใหม่กับ Logto Management API โปรดอ่านสิ่งเหล่านี้ก่อน: +หากคุณยังใหม่กับ Logto Management API หรือยังไม่ได้อ่านบทนำพื้นฐานเกี่ยวกับการใช้ Logto Management API สำหรับประสบการณ์องค์กร โปรดอ่านสิ่งเหล่านี้ก่อน: + + ตั้งค่าบริการแอปของคุณกับ Logto Management API + Management API -Interact with Management API +โต้ตอบกับ Management API ::: -สมมติว่า backend ของคุณเชื่อมต่อกับ Logto Management API ผ่านกลไก machine‑to‑machine (M2M) และคุณได้รับ M2M access token แล้ว +สมมติว่า backend ของคุณเชื่อมต่อกับ Logto Management API ผ่านกลไก machine‑to‑machine (M2M) และคุณได้รับโทเค็นการเข้าถึง M2M แล้ว -สร้างองค์กรด้วย Management API ([API references](https://openapi.logto.io/operation/operation-createorganization)): +สร้างองค์กรด้วย Management API ([API อ้างอิง](https://openapi.logto.io/operation/operation-createorganization)): ```bash curl \ @@ -49,7 +52,7 @@ curl \ -d '{"tenantId":"string","name":"string","description":"string","customData":{},"isMfaRequired":false,"branding":{"logoUrl":"string","darkLogoUrl":"string","favicon":"string","darkFavicon":"string"},"createdAt":1234567890}' ``` -จากนั้นเพิ่มผู้ใช้เป็นสมาชิกขององค์กร ([API reference](https://openapi.logto.io/operation/operation-addorganizationusers)): +จากนั้นเพิ่มผู้ใช้เป็นสมาชิกขององค์กร ([API อ้างอิง](https://openapi.logto.io/operation/operation-addorganizationusers)): ```bash curl \ @@ -59,14 +62,14 @@ curl \ -d '{"userIds":["string"]}' ``` -หากต้องการ สามารถกำหนดบทบาทองค์กรเฉพาะให้กับผู้ใช้ ([API reference](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)) +หากต้องการ สามารถกำหนดบทบาทองค์กรเฉพาะให้กับผู้ใช้ ([API อ้างอิง](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)) -ดู [API specs ฉบับเต็ม](https://openapi.logto.io/group/endpoint-organizations) สำหรับรายละเอียดเพิ่มเติม +ดู [สเปก API ฉบับเต็ม](https://openapi.logto.io/group/endpoint-organizations) สำหรับรายละเอียดเพิ่มเติม -ห่อคำสั่งเหล่านี้ไว้ในเลเยอร์ API ของคุณเอง เมื่อผู้ใช้ดำเนินการ “สร้างองค์กร” ในแอปของคุณ ให้ตรวจสอบคำขอโดยเช็คสิทธิ์ของพวกเขา จากนั้นเรียก Logto Management API เพื่อดำเนินการให้เสร็จสมบูรณ์ +ห่อคำสั่งเหล่านี้ไว้ในเลเยอร์ API ของคุณเอง เมื่อผู้ใช้ดำเนินการ “สร้างองค์กร” ในแอปของคุณ ให้ตรวจสอบคำขอโดยเช็คสิทธิ์ของพวกเขา แล้วเรียก Logto Management API เพื่อดำเนินการให้เสร็จสมบูรณ์ ## ตรวจสอบโทเค็นองค์กรในคำขอของผู้ใช้ \{#validating-organization-token-in-user-request} -ในแอปของคุณ เมื่อผู้ใช้ดำเนินการต่าง ๆ ในบริบทขององค์กร พวกเขาต้องใช้โทเค็นองค์กร (organization token) แทนโทเค็นการเข้าถึง (access token) ปกติ โทเค็นองค์กรคือ [JWT](https://auth.wiki/jwt) ที่มีสิทธิ์ขององค์กร เช่นเดียวกับ [โทเค็นการเข้าถึง (access token)](https://auth.wiki/access-token) คุณสามารถถอดรหัสการอ้างสิทธิ์ (claims) และตรวจสอบการอ้างสิทธิ์ "scope" เพื่อบังคับใช้สิทธิ์ได้ +ในแอปของคุณ เมื่อผู้ใช้ดำเนินการในบริบทขององค์กร พวกเขาต้องใช้โทเค็นองค์กรแทนโทเค็นการเข้าถึงปกติ โทเค็นองค์กรคือ [JWT](https://auth.wiki/jwt) ที่มีสิทธิ์ขององค์กร เช่นเดียวกับ [โทเค็นการเข้าถึง (access token)](https://auth.wiki/access-token) คุณสามารถถอดรหัสการอ้างสิทธิ์ (claims) และตรวจสอบการอ้างสิทธิ์ "scope" เพื่อบังคับใช้สิทธิ์ ดู การอนุญาต (Authorization) สำหรับสถานการณ์การอนุญาตและวิธีตรวจสอบโทเค็นองค์กร diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index c20f6b1f239..81fc9755887 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -4,7 +4,7 @@ sidebar_position: 4 # รับข้อมูลผู้ใช้ภายในองค์กร -## ใช้เมื่อใด \{#where-to-use-it} +## ใช้งานเมื่อใด \{#where-to-use-it} โดยปกติจะใช้ในหน้าข้อมูลโปรไฟล์ผู้ใช้ ซึ่งผู้ใช้ต้องการแสดงข้อมูลขององค์กรที่ตนเองสังกัด @@ -12,11 +12,11 @@ sidebar_position: 4 ## วิธีการนำไปใช้ \{#how-to-implement-it} -มี 2 วิธีในการรับข้อมูลผู้ใช้ภายในองค์กร +มีสองวิธีในการรับข้อมูลผู้ใช้ภายในองค์กร -### 1. ถอดรหัสโทเค็น ID (ID token) \{#1-decode-the-id-token} +### ถอดรหัสโทเค็น ID (Decode the ID token) \{#decode-the-id-token} -โทเค็น ID (ID token) เป็น JWT มาตรฐานที่มีข้อมูลโปรไฟล์ผู้ใช้และการอ้างสิทธิ์ (claims) ที่เกี่ยวข้องกับองค์กร เรียกใช้เมธอด SDK `decodeIdToken()` เพื่อรับอ็อบเจ็กต์ JSON ดังนี้: +โทเค็น ID (ID token) เป็น JWT มาตรฐานที่มีข้อมูลโปรไฟล์ผู้ใช้และการอ้างสิทธิ์ (claims) ที่เกี่ยวข้องกับองค์กร เรียกใช้เมธอด SDK `decodeIdToken()` เพื่อรับอ็อบเจกต์ JSON ดังนี้: ```json { @@ -42,7 +42,7 @@ sidebar_position: 4 } ``` -อย่างไรก็ตาม โทเค็น ID จะถูกออกให้เฉพาะระหว่างการยืนยันตัวตน (Authentication) เท่านั้น และอาจล้าสมัยหากโปรไฟล์ผู้ใช้มีการเปลี่ยนแปลงในภายหลัง +อย่างไรก็ตาม โทเค็น ID จะถูกออกให้เฉพาะระหว่างการยืนยันตัวตนเท่านั้น และอาจล้าสมัยหากโปรไฟล์ผู้ใช้มีการเปลี่ยนแปลงในภายหลัง หากต้องการข้อมูลล่าสุดที่สุด ให้ใช้วิธีที่สองด้านล่าง หรือเรียก `clearAllTokens()` และเริ่มกระบวนการยืนยันตัวตนใหม่เพื่อรับโทเค็น ID ที่สดใหม่ ```ts @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -หากเซสชันยังคงใช้งานได้ การเรียก `signIn` จะเปลี่ยนเส้นทางกลับไปยังแอปของคุณโดยไม่ต้องกรอกข้อมูลรับรองใหม่ สำหรับผู้ใช้ แอปจะเพียงแค่รีเฟรชและมีการออกโทเค็น ID ใหม่เบื้องหลัง +หากเซสชันยังคงใช้งานได้ การเรียก `signIn` จะเปลี่ยนเส้นทางกลับไปยังแอปของคุณโดยไม่ต้องกรอกข้อมูลรับรองใหม่ สำหรับผู้ใช้แล้ว แอปจะรีเฟรชและมีการออกโทเค็น ID ใหม่โดยอัตโนมัติ -### 2. ดึงข้อมูลผู้ใช้จาก endpoint `/oidc/me` \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### ดึงข้อมูลผู้ใช้จาก endpoint `/oidc/me` \{#fetch-user-info-from-the-oidc-me-endpoint} -คุณยังสามารถร้องขอ `/oidc/me` เพื่อรับข้อมูลผู้ใช้แบบเรียลไทม์ในบริบทขององค์กร เรียกใช้เมธอด SDK `fetchUserInfo()` +คุณยังสามารถร้องขอ `/oidc/me` เพื่อรับข้อมูลผู้ใช้แบบเรียลไทม์ในบริบทขององค์กรได้ เรียกใช้เมธอด SDK `fetchUserInfo()` diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx index 4e8ebdc4f0a..cf444adb00d 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/invite-organization-members.mdx @@ -4,7 +4,7 @@ sidebar_position: 6 # เชิญสมาชิกองค์กร -ในแอปพลิเคชันที่รองรับหลายองค์กร ความต้องการทั่วไปคือการเชิญสมาชิกเข้าสู่องค์กร คู่มือนี้จะแนะนำขั้นตอนและรายละเอียดทางเทคนิคในการนำฟีเจอร์นี้ไปใช้ +ในแอปพลิเคชันแบบหลายผู้เช่า (multi-tenancy) ความต้องการที่พบบ่อยคือการเชิญสมาชิกเข้าสู่องค์กร คู่มือนี้จะแนะนำขั้นตอนและรายละเอียดทางเทคนิคในการนำฟีเจอร์นี้ไปใช้ ## ภาพรวมของขั้นตอน \{#flow-overview} @@ -19,21 +19,21 @@ sequenceDiagram A ->> C: กรอกอีเมลและบทบาทของผู้รับเชิญ C ->> L: สร้างคำเชิญองค์กรด้วย Management API - L -->> C: ส่งคืนรหัสคำเชิญ - C ->> C: สร้างลิงก์คำเชิญโดยใช้รหัสคำเชิญ - C ->> L: ขอให้ส่งอีเมลคำเชิญพร้อมลิงก์คำเชิญ - L -->> U: ส่งอีเมลคำเชิญพร้อมลิงก์คำเชิญ - U ->> C: คลิกลิงก์คำเชิญและไปยังหน้าแลนดิ้งของคุณ,
ยอมรับหรือปฏิเสธคำเชิญ + L -->> C: ส่งคืน invitation ID + C ->> C: สร้างลิงก์เชิญด้วย invitation ID + C ->> L: ขอให้ส่งอีเมลเชิญพร้อมลิงก์เชิญ + L -->> U: ส่งอีเมลเชิญพร้อมลิงก์เชิญ + U ->> C: คลิกลิงก์เชิญและไปยังหน้า landing page ของคุณ,
ยอมรับหรือปฏิเสธคำเชิญ C ->> L: อัปเดตสถานะคำเชิญด้วย Management API ``` ## สร้างบทบาทองค์กร \{#create-organization-roles} -ก่อนเชิญสมาชิก ให้สร้างบทบาทองค์กร ดู [เทมเพลตองค์กร](/authorization/organization-template) เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับบทบาทและสิทธิ์ +ก่อนเชิญสมาชิก ให้สร้างบทบาทองค์กร ดู [organization template](/authorization/organization-template) เพื่อเรียนรู้เพิ่มเติมเกี่ยวกับบทบาทและสิทธิ์ (permissions) -ในคู่มือนี้ เราจะสร้างบทบาทองค์กรทั่วไป 2 แบบ: `admin` และ `member` +ในคู่มือนี้ เราจะสร้างบทบาทองค์กรทั่วไปสองแบบ: `admin` และ `member` -บทบาท `admin` มีสิทธิ์เข้าถึงทรัพยากรทั้งหมดในองค์กร ส่วนบทบาท `member` จะมีสิทธิ์จำกัด ตัวอย่างเช่น: +บทบาท `admin` มีสิทธิ์เข้าถึงทรัพยากรทั้งหมดในองค์กร ส่วนบทบาท `member` มีสิทธิ์จำกัด ตัวอย่างเช่น: - บทบาท `admin`: - `read:data` - อ่านข้อมูลทรัพยากรทั้งหมดขององค์กร @@ -51,24 +51,24 @@ 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) ของคุณถูกตั้งค่าอย่างถูกต้อง ในการส่งคำเชิญ ให้ตั้งค่า [email template](/connectors/email-connectors/email-templates#email-template-types) โดยใช้ `usageType` เป็น `OrganizationInvitation` คุณสามารถใส่ตัวแปรองค์กร (เช่น ชื่อ, โลโก้) และผู้เชิญ (เช่น อีเมล, ชื่อ) [ตัวแปร](/connectors/email-connectors/email-templates#email-template-variables) ในเนื้อหา และปรับแต่ง [เทมเพลตภาษาท้องถิ่น](/connectors/email-connectors/email-templates#email-template-localization) ได้ตามต้องการ -ตัวอย่างเทมเพลตอีเมลสำหรับประเภทการใช้งาน `OrganizationInvitation` แสดงด้านล่าง: +ตัวอย่าง email template สำหรับ `OrganizationInvitation` มีดังนี้: ```json { "subject": "ยินดีต้อนรับสู่องค์กรของฉัน", - "content": "

เข้าร่วม {{organization.name}} ได้โดยคลิก ลิงก์นี้.

", + "content": "

เข้าร่วม {{organization.name}} ได้ที่ ลิงก์นี้.

", "usageType": "OrganizationInvitation", "type": "text/html" } ``` -ตัวแปร `{{link}}` ในเนื้อหาอีเมลจะถูกแทนที่ด้วยลิงก์คำเชิญจริงเมื่อส่งอีเมล +ตัวแปร `{{link}}` ในเนื้อหาอีเมลจะถูกแทนที่ด้วยลิงก์เชิญจริงเมื่อส่งอีเมล :::note -บริการ “Logto email service” ที่มากับ Logto Cloud ยังไม่รองรับประเภทการใช้งาน `OrganizationInvitation` กรุณาตั้งค่าตัวเชื่อมต่ออีเมลของคุณเอง (เช่น SendGrid) และตั้งค่าเทมเพลต `OrganizationInvitation` แทน +บริการ “Logto email service” ที่มาพร้อม Logto Cloud ยังไม่รองรับ `OrganizationInvitation` ในขณะนี้ กรุณาตั้งค่าตัวเชื่อมต่ออีเมลของคุณเอง (เช่น SendGrid) และตั้งค่าเทมเพลต `OrganizationInvitation` แทน ::: @@ -76,7 +76,7 @@ sequenceDiagram :::note -หากคุณยังไม่ได้ตั้งค่า Logto Management API โปรดดู [โต้ตอบกับ Management API](/integrate-logto/interact-with-management-api) สำหรับรายละเอียด +หากคุณยังไม่ได้ตั้งค่า Logto Management API ดูรายละเอียดที่ [โต้ตอบกับ Management API](/integrate-logto/interact-with-management-api) ::: @@ -87,10 +87,15 @@ sequenceDiagram - `POST /api/organization-invitations`: สร้างคำเชิญองค์กรพร้อมกำหนดบทบาทองค์กร - `POST /api/one-time-tokens`: สร้างโทเค็นใช้ครั้งเดียวสำหรับผู้รับเชิญเพื่อยืนยันตัวตนเมื่อยอมรับคำเชิญ [เรียนรู้เพิ่มเติม](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message`: ส่งคำเชิญองค์กรไปยังผู้รับเชิญทางอีเมล - หมายเหตุ: payload รองรับ property `link` เพื่อให้คุณสามารถสร้างลิงก์คำเชิญเองโดยอิงจากรหัสคำเชิญ ตัวอย่างเช่น: - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +payload รองรับ property `link` เพื่อให้คุณสร้างลิงก์เชิญเองโดยอิงจาก invitation ID ตัวอย่างเช่น: + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index 7b61f9b4541..3402c325bb4 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -6,27 +6,29 @@ sidebar_position: 7 ## ใช้งานที่ไหน \{#where-to-use-it} -รายการองค์กร (organization list) มักจะแสดงในระหว่างขั้นตอนการเริ่มต้นใช้งานของผู้ใช้ (user onboarding flow) ตัวอย่างเช่น เมื่อผู้ดูแลระบบเชิญคุณเข้าร่วม workspace +รายการองค์กรและขั้นตอนการเข้าร่วมมักจะปรากฏในระหว่างการเริ่มต้นใช้งานของผู้ใช้ (onboarding) +ตัวอย่างเช่น เมื่อผู้ดูแลระบบเชิญใครบางคนเข้าสู่ workspace แต่ผู้ใช้ข้ามอีเมลเชิญและเข้าสู่ระบบหรือสมัครสมาชิกในแอปโดยตรง -ในมุมมองของผลิตภัณฑ์ สามารถแสดงได้ใน 2 ตำแหน่งหลัก: +ในผลิตภัณฑ์ของคุณ คุณอาจต้องการเพิ่มจุดเข้าใช้งานสำหรับขั้นตอนนี้ +โดยสามารถแสดงได้ในสองตำแหน่งหลัก: -- **ตัวค้นหาองค์กร (organization finder)** ระหว่างการลงชื่อเข้าใช้ หรือสมัครสมาชิก +- **ตัวค้นหาองค์กร** ระหว่างการลงชื่อเข้าใช้หรือสมัครสมาชิก เข้าร่วมองค์กรระหว่างการลงชื่อเข้าใช้ หรือสมัครสมาชิก -- **ตัวสลับองค์กร (organization switcher)** ภายในแอปพลิเคชัน +- **ตัวสลับองค์กร** ภายในแอปพลิเคชัน เข้าร่วมองค์กรภายในแอป ## ใช้ Logto Management API เพื่อให้ผู้ใช้เข้าร่วมองค์กร \{#use-the-logto-management-api-to-let-users-join-an-organization} -ในหัวข้อก่อนหน้า เราได้กล่าวถึงการสร้างและส่งคำเชิญเข้าร่วมองค์กรโดยใช้ Logto Management API -ถัดไป ให้คุณสร้างหน้า landing page เพื่อจัดการลิงก์คำเชิญเมื่อผู้ถูกเชิญเข้ามายังแอปของคุณ +ในหัวข้อก่อนหน้า เราได้กล่าวถึงการสร้างและส่งคำเชิญองค์กรโดยใช้ Logto Management API +ถัดไป ให้คุณสร้างหน้า landing page เพื่อจัดการลิงก์คำเชิญเมื่อผู้รับเชิญมาถึงแอปพลิเคชันของคุณ -- `GET /api/organization-invitations` และ `GET /api/organization-invitations/{id}`: ดึงคำเชิญทั้งหมด หรือระบุด้วย ID - ในหน้า landing page ของคุณ ใช้ API เหล่านี้เพื่อแสดงรายการคำเชิญทั้งหมด หรือแสดงรายละเอียดของคำเชิญที่ผู้ใช้ได้รับ +- `GET /api/organization-invitations` และ `GET /api/organization-invitations/{id}`: ดึงคำเชิญทั้งหมดหรือเฉพาะรายการตาม ID + ในหน้า landing page ของคุณ ให้ใช้ API เหล่านี้เพื่อแสดงรายการคำเชิญทั้งหมดหรือแสดงรายละเอียดของคำเชิญที่ผู้ใช้ได้รับ - `PUT /api/organization-invitations/{id}/status`: ยอมรับหรือปฏิเสธคำเชิญโดยอัปเดตสถานะ ใช้ API นี้เพื่อจัดการการตอบรับของผู้ใช้ diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 14d4d6d31f5..4df6fda11f4 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,37 +2,40 @@ sidebar_position: 8 --- -# การจัดการสิทธิ์ (Permission) และทรัพยากร (Resource) +# จัดการการอัปเดตขอบเขต (scope) ในโทเค็นองค์กร (Organization token) -ใช้องค์กรเป็นทรัพยากรและนำเทมเพลตองค์กรไปใช้เพื่อปกป้องมัน ตัวอย่างเช่น แต่ละองค์กรมีเอกสารของตนเองภายในผู้เช่า (tenant) เฉพาะผู้ใช้ที่มีบทบาท (Role) ที่เหมาะสมเท่านั้นที่สามารถแก้ไขหรือ ลบเอกสารเหล่านั้นได้ +ด้วยการตั้งค่าข้างต้น คุณสามารถส่งคำเชิญผ่านอีเมล และผู้ที่ได้รับเชิญสามารถเข้าร่วมองค์กรพร้อมบทบาทที่กำหนดไว้ -ดูรายละเอียดที่ [สิทธิ์ขององค์กร (Organization permissions)](/authorization/organization-permissions) +ผู้ใช้ที่มีบทบาทองค์กรต่างกันจะมีขอบเขต (สิทธิ์) ที่แตกต่างกันในโทเค็นองค์กรของตน ทั้งแอปฝั่งไคลเอนต์และบริการฝั่งแบ็กเอนด์ของคุณควรตรวจสอบขอบเขตเหล่านี้เพื่อกำหนดฟีเจอร์ที่มองเห็นได้และการกระทำที่อนุญาต -## ใช้การควบคุมการเข้าถึงตามบทบาทขององค์กร (RBAC) เพื่อจัดการสิทธิ์ของผู้ใช้ \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +ดังที่กล่าวไว้ก่อนหน้านี้ เทมเพลตองค์กรทำหน้าที่เป็นชั้นควบคุมการเข้าถึงที่สำคัญเพื่อปกป้อง [สิทธิ์ขององค์กร](/authorization/organization-permissions) หรือ [API ระดับองค์กร](/authorization/organization-level-api-resources) อย่าลืมทบทวนหัวข้อการอนุญาตและเลือกโมเดลการอนุญาตที่เหมาะสมกับผลิตภัณฑ์ของคุณมากที่สุด -ด้วยการตั้งค่าข้างต้น คุณสามารถส่งคำเชิญผ่านอีเมล และผู้ที่ได้รับเชิญสามารถเข้าร่วมองค์กรพร้อมบทบาทที่กำหนดไว้ +:::note + +ปกป้องสิทธิ์ขององค์กร (ที่ไม่ใช่ API) +ปกป้อง API ระดับองค์กร -ผู้ใช้ที่มีบทบาทองค์กรต่างกันจะมีขอบเขต (Scopes / Permissions) ที่แตกต่างกันในโทเค็นองค์กรของตน ทั้งแอปฝั่งไคลเอนต์และบริการฝั่งแบ็กเอนด์ของคุณควรตรวจสอบขอบเขตเหล่านี้เพื่อกำหนดฟีเจอร์ที่มองเห็นได้และการกระทำที่อนุญาต +::: -## จัดการการอัปเดตขอบเขต (Scope) ในโทเค็นองค์กร \{#handle-scope-updates-in-organization-tokens} +บทนี้เน้นที่ **การจัดการสิทธิ์ (permission management)** และแนวปฏิบัติที่ดีที่สุดสำหรับ **การจัดการการเปลี่ยนแปลงขอบเขตและสิทธิ์** ในโทเค็นองค์กรของ Logto -ส่วนนี้ครอบคลุมหัวข้อขั้นสูงเกี่ยวกับการจัดการเทมเพลตองค์กรและสถานการณ์การอนุญาต (Authorization) หากคุณยังไม่คุ้นเคยกับแนวคิดเหล่านี้ โปรดอ่าน [การอนุญาต (Authorization)](/authorization) และ [เทมเพลตองค์กร (Organization template)](/authorization/organization-template) ก่อน +## จัดการการอัปเดตขอบเขตในโทเค็นองค์กร \{#handle-scope-updates-in-organization-tokens} การจัดการการอัปเดตขอบเขตในโทเค็นองค์กรประกอบด้วย: ### เพิกถอนขอบเขตที่มีอยู่ \{#revoke-existing-scopes} -ตัวอย่างเช่น การลดระดับแอดมินเป็นสมาชิกทั่วไปควรลบขอบเขตออกจากผู้ใช้ ในกรณีนี้ ให้ล้างแคชโทเค็นองค์กรและดึงโทเค็นใหม่ด้วยโทเค็นรีเฟรช ขอบเขตที่ลดลงจะสะท้อนทันทีในโทเค็นองค์กรที่ออกใหม่ +ตัวอย่างเช่น การลดระดับแอดมินให้เป็นสมาชิกทั่วไปควรลบขอบเขตออกจากผู้ใช้ ในกรณีนี้ ให้ล้างโทเค็นองค์กรที่แคชไว้และดึงโทเค็นใหม่ด้วยโทเค็นรีเฟรช ขอบเขตที่ลดลงจะสะท้อนในโทเค็นองค์กรที่ออกใหม่ทันที ### ให้ขอบเขตใหม่ \{#grant-new-scopes} สามารถแบ่งออกเป็นสองกรณี: -#### ให้ขอบเขตใหม่ที่มีอยู่แล้วในระบบยืนยันตัวตนของคุณ \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} +#### ให้ขอบเขตใหม่ที่มีการกำหนดไว้แล้วในระบบ auth ของคุณ \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -คล้ายกับการเพิกถอนขอบเขต หากขอบเขตที่ให้ใหม่ได้ถูกลงทะเบียนไว้กับเซิร์ฟเวอร์ยืนยันตัวตนแล้ว ให้ออกโทเค็นองค์กรใหม่และขอบเขตใหม่จะสะท้อนทันที +คล้ายกับการเพิกถอนขอบเขต หากขอบเขตที่ให้ใหม่ได้ลงทะเบียนไว้กับ auth server แล้ว ให้ออกโทเค็นองค์กรใหม่และขอบเขตใหม่จะสะท้อนทันที -#### ให้ขอบเขตใหม่ที่เพิ่งเพิ่มเข้ามาในระบบยืนยันตัวตนของคุณ \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### ให้ขอบเขตใหม่ที่เพิ่งเพิ่มเข้ามาในระบบ auth ของคุณ \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} ในกรณีนี้ ให้เรียกกระบวนการเข้าสู่ระบบใหม่หรือขอความยินยอมใหม่ (re-consent) เพื่ออัปเดตโทเค็นองค์กรของผู้ใช้ เช่น เรียกใช้เมธอด `signIn` ใน Logto SDK @@ -44,26 +47,26 @@ Logto มี Management API สำหรับดึงสิทธิ์ขอ เปรียบเทียบขอบเขตในโทเค็นองค์กรของผู้ใช้กับสิทธิ์แบบเรียลไทม์เพื่อดูว่าผู้ใช้ถูกเลื่อนขั้นหรือลดขั้นหรือไม่ -- หากถูกลดขั้น ให้ล้างแคชโทเค็นองค์กร และ SDK จะออกโทเค็นใหม่พร้อมขอบเขตที่อัปเดตโดยอัตโนมัติ +- หากถูกลดขั้น ให้ล้างโทเค็นองค์กรที่แคชไว้ และ SDK จะออกโทเค็นใหม่ที่มีขอบเขตอัปเดตให้อัตโนมัติ ```tsx const { clearAccessToken } = useLogto(); ... - // หากขอบเขตที่ดึงแบบเรียลไทม์มีน้อยกว่าขอบเขตในโทเค็นองค์กร + // หากขอบเขตแบบเรียลไทม์ที่ดึงมา มีจำนวนน้อยกว่าขอบเขตในโทเค็นองค์กร await clearAccessToken(); ``` - กรณีนี้ไม่ต้องเข้าสู่ระบบใหม่หรือขอความยินยอมใหม่ โทเค็นองค์กรใหม่จะถูกออกโดยอัตโนมัติผ่าน Logto SDK + กรณีนี้ไม่จำเป็นต้องเข้าสู่ระบบใหม่หรือขอความยินยอมใหม่ โทเค็นองค์กรใหม่จะถูกออกให้อัตโนมัติโดย Logto SDK -- หากมีขอบเขตใหม่ถูกเพิ่มเข้ามาในระบบยืนยันตัวตนของคุณ ให้เรียกกระบวนการเข้าสู่ระบบใหม่หรือขอความยินยอมใหม่เพื่ออัปเดตโทเค็นองค์กรของผู้ใช้ เช่น ด้วย React SDK: +- หากมีการเพิ่มขอบเขตใหม่ในระบบ auth ของคุณ ให้เรียกกระบวนการเข้าสู่ระบบใหม่หรือขอความยินยอมใหม่เพื่ออัปเดตโทเค็นองค์กรของผู้ใช้ เช่น ด้วย React SDK: ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // หากขอบเขตที่ดึงแบบเรียลไทม์มีขอบเขตใหม่มากกว่าขอบเขตในโทเค็นองค์กร + // หากขอบเขตแบบเรียลไทม์ที่ดึงมา มีขอบเขตใหม่มากกว่าขอบเขตในโทเค็นองค์กร await clearAllTokens(); signIn({ redirectUri: '', diff --git a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index f2f62cbb4a5..f68bb3cecb0 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,14 +4,15 @@ sidebar_position: 2 # ตั้งค่าบริการแอปของคุณด้วย Logto Management API -ใช้ **Management API** ของ Logto เพื่อสร้าง **ประสบการณ์องค์กร (organization flows)** แบบกำหนดเองในแอปของคุณ ด้านล่างนี้คือขั้นตอนพื้นฐานสำหรับการเชื่อมต่อ Management API หากคุณคุ้นเคยอยู่แล้ว สามารถข้ามไปที่ [บทแนะนำ](/integrate-logto/interact-with-management-api) ได้เลย +Logto มี Management API ที่ทรงพลัง ช่วยให้คุณสร้างและปรับแต่งประสบการณ์องค์กรของคุณเองภายในแอป +การเข้าใจวิธีการทำงานเป็นกุญแจสำคัญในการออกแบบการตั้งค่าที่กำหนดเองของคุณ ด้านล่างนี้คือขั้นตอนพื้นฐานและโครงร่างสำหรับการผสาน Management API เพื่อสร้างประสบการณ์องค์กรของคุณ -เมื่อคุณเข้าใจขั้นตอนการตั้งค่าแล้ว คุณสามารถสำรวจ API อื่น ๆ เพื่อปรับแต่ง flow ที่เหลือให้เหมาะกับความต้องการทางธุรกิจของคุณ +หากคุณทราบพื้นฐานแล้ว สามารถข้ามไปที่ [คู่มือ](/integrate-logto/interact-with-management-api) ได้เลย เมื่อคุณคุ้นเคยกับการตั้งค่าแล้ว คุณสามารถสำรวจ API อื่น ๆ เพื่อปรับแต่ง flow ที่เหลือให้เหมาะกับความต้องการทางธุรกิจของคุณ -## สร้างการเชื่อมต่อเครื่องต่อเครื่อง \{#establish-a-machine-to-machine-connection} +## สร้างการเชื่อมต่อเครื่องต่อเครื่อง (Machine-to-machine) \{#establish-a-machine-to-machine-connection} -Logto ใช้ **การยืนยันตัวตนระหว่างเครื่อง (Machine-to-machine; M2M)** เพื่อเชื่อมต่อบริการ backend ของคุณกับ Management API endpoint ของ Logto อย่างปลอดภัย -บริการ backend ของคุณจะสามารถใช้ Management API เพื่อจัดการงานที่เกี่ยวข้องกับองค์กร เช่น **สร้างองค์กร**, **เพิ่มหรือลบสมาชิก** และอื่น ๆ +Logto ใช้ **การยืนยันตัวตนระหว่างเครื่อง (Machine‑to‑machine; M2M)** เพื่อเชื่อมต่อบริการ backend ของคุณกับ Logto Management API endpoint อย่างปลอดภัย +จากนั้นบริการ backend ของคุณสามารถใช้ Management API เพื่อจัดการงานที่เกี่ยวข้องกับองค์กร เช่น **สร้างองค์กร**, **เพิ่มหรือลบสมาชิก** และอื่น ๆ ขั้นตอนประกอบด้วย: @@ -19,8 +20,8 @@ Logto ใช้ **การยืนยันตัวตนระหว่า รายละเอียดแอป M2M -2. **ขอรับโทเค็นการเข้าถึง M2M (M2M access token)** จาก Logto [เรียนรู้เพิ่มเติม](/integrate-logto/interact-with-management-api#fetch-an-access-token) -3. **เรียกใช้ Logto Management API** จากบริการ backend ของคุณ ตัวอย่างเช่น แสดงรายการองค์กรทั้งหมด: +2. **ขอรับ M2M access token** จาก Logto [เรียนรู้เพิ่มเติม](/integrate-logto/interact-with-management-api#fetch-an-access-token) +3. **เรียกใช้ Logto Management APIs** จากบริการ backend ของคุณ ตัวอย่างเช่น แสดงรายการองค์กรทั้งหมด: ```bash curl \ @@ -31,19 +32,19 @@ curl \ ## ปกป้องเซิร์ฟเวอร์แอปของคุณ \{#protect-your-app-server} -เนื่องจากผู้ใช้ปลายทางสามารถดำเนินการบางอย่างเกี่ยวกับองค์กรได้ด้วยตนเอง ควรเพิ่มเลเยอร์การอนุญาต (authorization layer) ระหว่างผู้ใช้กับเซิร์ฟเวอร์แอปของคุณ เซิร์ฟเวอร์ควรเป็นตัวกลางสำหรับทุกคำขอ ตรวจสอบโทเค็นองค์กรของผู้ใช้และขอบเขต (scopes) ที่จำเป็น และใช้ข้อมูลรับรอง M2M ที่เก็บไว้ในเซิร์ฟเวอร์เพื่อเรียก Management API เท่านั้น +เนื่องจากผู้ใช้ปลายทางสามารถดำเนินการบางอย่างเกี่ยวกับองค์กรได้ด้วยตนเอง จึงควรเพิ่มชั้นการอนุญาต (Authorization) ระหว่างผู้ใช้ปลายทางกับเซิร์ฟเวอร์แอปของคุณ\คุณสามารถใช้ชั้นนี้ในระดับ global หรือระดับองค์กร ขึ้นอยู่กับว่าใช้ Logto Management API endpoint ใดและโครงสร้าง API ของผลิตภัณฑ์ของคุณเป็นอย่างไร เซิร์ฟเวอร์ควรเป็นตัวกลางในทุกคำขอ ตรวจสอบโทเค็นองค์กรของผู้ใช้และขอบเขตที่ต้องการ และใช้ข้อมูลประจำตัว M2M ที่เซิร์ฟเวอร์ถืออยู่เพื่อเรียก Management API เท่านั้น -เมื่อผู้ใช้ส่งโทเค็นองค์กรเพื่อขอดำเนินการ (เช่น สร้างองค์กร) เซิร์ฟเวอร์จะตรวจสอบขอบเขตในโทเค็นก่อน หากโทเค็นมีขอบเขตที่จำเป็น เช่น `org:create` ให้อนุญาตคำขอและเรียก Logto Management API ผ่าน flow M2M เพื่อสร้างองค์กร +เมื่อผู้ใช้ส่ง organization token เพื่อขอดำเนินการ (เช่น สร้างองค์กร) เซิร์ฟเวอร์จะตรวจสอบขอบเขตในโทเค็นก่อน หากโทเค็นมีขอบเขตที่จำเป็น เช่น `org:create` ให้อนุญาตคำขอและเรียก Logto Management API ผ่าน flow M2M เพื่อสร้างองค์กร -หากโทเค็นไม่มีขอบเขตที่จำเป็น ให้ส่งกลับ 403 Forbidden และข้ามตรรกะ M2M เพื่อให้แน่ใจว่าผู้ใช้ที่ไม่มีสิทธิ์จะไม่สามารถสร้างองค์กรได้ +หากโทเค็นไม่มีขอบเขตที่ต้องการ ให้ส่งกลับ 403 Forbidden และข้ามตรรกะ M2M เพื่อให้แน่ใจว่าผู้ใช้ที่ไม่มีสิทธิ์จะไม่สามารถสร้างองค์กรได้ ด้านล่างนี้คือลักษณะการอนุญาตที่พบบ่อย -### การใช้สิทธิ์ขององค์กร \{#using-organization-permissions} +### การใช้สิทธิ์ขององค์กร (Organization permissions) \{#using-organization-permissions} -ก่อนอื่น ตรวจสอบให้แน่ใจว่าคุณได้กำหนดสิทธิ์ (permissions) และบทบาท (roles) ขององค์กรไว้ในเทมเพลตองค์กรของคุณใน [หัวข้อก่อนหน้า](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) +ก่อนอื่น ตรวจสอบให้แน่ใจว่าคุณได้กำหนดสิทธิ์และบทบาทขององค์กรไว้ในเทมเพลตองค์กรใน [หัวข้อก่อนหน้า](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) -จากนั้น ตรวจสอบให้แน่ใจว่า `UserScope.Organizations` (ค่า: `urn:logto:organization`) ถูกเพิ่มไว้ใน config ของ Logto ยกตัวอย่าง React SDK: +จากนั้น ตรวจสอบให้แน่ใจว่า `UserScope.Organizations` (ค่า: `urn:logto:organization`) ถูกเพิ่มใน config ของ Logto ยกตัวอย่าง React SDK: ```jsx // src/App.js @@ -53,7 +54,7 @@ const config = { endpoint: 'https://.logto.app/', // Logto endpoint ของคุณ appId: '40fmibayagoo00lj26coc', // app id ของคุณ resources: [ - 'https://my.company.com/api', // ตัวระบุทรัพยากร API ระดับโกลบอลของคุณ + 'https://my.company.com/api', // ตัวระบุทรัพยากร API ระดับ global ของคุณ ], scopes: [ UserScope.Email, @@ -61,20 +62,30 @@ const config = { UserScope.CustomData, UserScope.Identities, // highlight-start - UserScope.Organizations, // ขอรับโทเค็นองค์กร + UserScope.Organizations, // ขอ organization token // highlight-end ], }; ``` -สิ่งนี้จะทำให้เมื่อเรียก `getOrganizationToken(organizationId)` ตัว client SDK จะขอโทเค็นองค์กรที่มีสิทธิ์ขององค์กรที่กำหนดให้กับผู้ใช้ บริการ backend ของคุณสามารถตรวจสอบโทเค็นและอนุญาตคำขอถัดไปตามสิทธิ์เหล่านี้ +สิ่งนี้จะทำให้เมื่อเรียก `getOrganizationToken(organizationId)` client SDK จะขอ organization token ที่มีสิทธิ์ขององค์กรที่กำหนดให้กับผู้ใช้ บริการ backend ของคุณสามารถตรวจสอบโทเค็นและอนุญาตคำขอถัดไปตามสิทธิ์เหล่านี้ สำหรับรายละเอียดเกี่ยวกับการปกป้องสิทธิ์ระดับองค์กร (ที่ไม่ใช่ API) ดู [คู่มือฉบับเต็ม](/authorization/organization-permissions) -### ผสมผสานสิทธิ์ระดับองค์กรและสิทธิ์ระดับ API \{#mixing-organization-level-permissions-and-api-level-permissions} +### การใช้สิทธิ์ระดับ API (API-level permissions) \{#using-api-level-permissions} -กรณีนี้ใช้เมื่อทรัพยากร API และสิทธิ์ของคุณถูกลงทะเบียนในระดับโกลบอล แต่บทบาทถูกกำหนดในระดับองค์กร (คุณสามารถกำหนดสิทธิ์ระดับ API ให้กับบทบาทขององค์กรในเทมเพลตองค์กรได้) +กรณีนี้ใช้เมื่อทรัพยากร API และสิทธิ์ของคุณถูกลงทะเบียนในระดับ global แต่บทบาทถูกกำหนดในระดับองค์กร (คุณสามารถกำหนดสิทธิ์ระดับ API ให้กับบทบาทองค์กรในเทมเพลตองค์กรได้) -การใช้งานเหมือนกับหัวข้อก่อนหน้าเสมอ ให้ระบุ organization ID และเรียก `getOrganizationToken(organizationId)` เพื่อขอโทเค็นองค์กร มิฉะนั้นสิทธิ์ขององค์กรจะไม่ถูกรวมอยู่ด้วย +การใช้งานเหมือนกับหัวข้อก่อนหน้าเสมอ ให้ระบุ organization ID และเรียก `getOrganizationToken(organizationId)` เพื่อดึง organization token มิฉะนั้นสิทธิ์ขององค์กรจะไม่ถูกรวมอยู่ด้วย สำหรับรายละเอียดเกี่ยวกับการปกป้องสิทธิ์ API ระดับองค์กร ดู [คู่มือฉบับเต็ม](/authorization/organization-level-api-resources) + +### การใช้ RBAC ระดับ global \{#using-global-rbac} + +ในกรณีนี้ คุณสามารถใช้ Logto Management API เพื่อสร้างการควบคุมการเข้าถึงระดับระบบ + +ในสภาพแวดล้อมแบบหลายผู้เช่า (multi-tenant) รูปแบบที่พบบ่อยคือมี superuser หรือ super admin ตัวอย่างเช่น หากคุณกำลังสร้างแพลตฟอร์ม SaaS ด้วย Logto คุณอาจต้องการ superuser ที่สามารถจัดการองค์กรลูกค้าทั้งหมดได้โดยตรงในแอปของคุณเอง โดยไม่ต้องเข้าสู่ระบบ Logto Console + +superuser นี้สามารถดำเนินการระดับสูง เช่น สร้างหรือลบองค์กรจำนวนมาก ซึ่งต้องใช้สิทธิ์ระดับระบบที่กว้างกว่าขอบเขตขององค์กรใด ๆ เพื่อเปิดใช้งานสิ่งนี้ ให้ลงทะเบียนทรัพยากร API ใน Logto พร้อมใช้ Logto Management API และใช้ RBAC ระดับ global เพื่อจัดการสิทธิ์เหล่านี้ + +สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการผสานและจัดการการควบคุมการเข้าถึงสำหรับ RBAC ดู [คู่มือฉบับเต็ม](/authorization/global-api-resources) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 67f1efab47c..ea2f602b011 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,7 +4,7 @@ sidebar_position: 3 # 创建组织 (Organization) -假设你正在构建一个[多租户应用](https://auth.wiki/multi-tenancy)（例如，多租户 SaaS 应用），为许多客户服务，每个客户拥有一个专属租户。 +假设你正在构建一个[多租户应用](https://auth.wiki/multi-tenancy)（例如，多租户 SaaS 应用），为许多客户提供服务，每个客户拥有一个专属租户。 通常在以下情况下会创建组织 (Organization)： @@ -16,28 +16,31 @@ sidebar_position: 3 ## 实现组织 (Organization) 创建 \{#implement-organization-creation} -为你的应用创建组织 (Organization) 有两种方式。 +有两种方式为你的应用创建组织 (Organization)。 -### 通过 Logto Console 创建 \{#create-via-logto-console} +### 通过 Logto 控制台创建 \{#create-via-logto-console} -在 Logto Console UI 中手动创建组织 (Organization)。前往 控制台 > 组织 (Organizations) 创建组织 (Organization)、分配成员和角色，并自定义组织登录体验。 +在 Logto 控制台 UI 中手动创建组织 (Organization)。前往 控制台 > 组织 (Organizations) 创建组织 (Organization)、分配成员和角色，并自定义组织登录体验。 创建一个[组织模板](/authorization/organization-template)，批量创建具有相同角色和权限的类似组织 (Organization)。 ### 通过 Logto Management API 创建 \{#create-via-logto-management-api} -控制台适合手动设置，但大多数应用允许终端用户自助——直接在你的应用中创建和管理组织 (Organization)。要实现这一点，请使用 Logto Management API 实现相关功能。 +控制台适合手动设置，但大多数应用允许终端用户自助——直接在你的应用中创建和管理组织 (Organization)。要实现这一点，请使用 Logto Management API 实现这些功能。 :::note -如果你是第一次接触 Logto Management API，请先阅读： +如果你是 Logto Management API 新手，或者还没有阅读过使用 Logto Management API 实现组织 (Organization) 体验的基础介绍，请先阅读以下内容： + + 使用 Logto Management API 设置你的应用服务 + Management API 与 Management API 交互 ::: -假设你的后端通过机器对机器 (M2M) 机制连接到 Logto Management API，并已获取 M2M 访问令牌 (Access token)。 +假设你的后端已通过机器对机器 (M2M) 机制连接到 Logto Management API，并且你已经获得了 M2M 访问令牌 (Access token)。 使用 Management API 创建组织 (Organization)（[API 参考](https://openapi.logto.io/operation/operation-createorganization)）： @@ -59,14 +62,14 @@ curl \ -d '{"userIds":["string"]}' ``` -你还可以为用户分配特定的组织 (Organization) 角色（[API 参考](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)）。 +可选地，为用户分配特定的组织 (Organization) 角色（[API 参考](https://openapi.logto.io/operation/operation-assignorganizationrolestousers)）。 -查看[完整 API 规范](https://openapi.logto.io/group/endpoint-organizations)获取更多细节。 +查看[完整 API 规范](https://openapi.logto.io/group/endpoint-organizations)以获取更多细节。 -将这些调用封装在你自己的 API 层。当用户在你的应用中执行“创建组织 (Organization)”操作时，先校验其权限，然后调用 Logto Management API 完成操作。 +将这些调用封装在你自己的 API 层中。当用户在你的应用中执行“创建组织 (Organization)”操作时，通过检查其权限来验证请求，然后调用 Logto Management API 完成操作。 -## 校验用户请求中的组织令牌 (Organization token) \{#validating-organization-token-in-user-request} +## 验证用户请求中的组织令牌 (Organization token) \{#validating-organization-token-in-user-request} -在你的应用中，当用户在组织 (Organization) 上下文中执行操作时，必须使用组织令牌 (Organization token)，而不是普通访问令牌 (Access token)。组织令牌 (Organization token) 是一个 [JWT](https://auth.wiki/jwt)，其中包含组织权限。与任何[访问令牌 (Access token)](https://auth.wiki/access-token)一样，你可以解码声明 (Claims) 并校验 "scope" 声明 (Claim) 以执行权限控制。 +在你的应用中，当用户在组织 (Organization) 上下文中执行操作时，必须使用组织令牌 (Organization token)，而不是普通访问令牌 (Access token)。组织令牌 (Organization token) 是一个 [JWT](https://auth.wiki/jwt)，其中包含组织 (Organization) 权限。与任何[访问令牌 (Access token)](https://auth.wiki/access-token)一样，你可以解码声明 (Claims) 并验证 "scope" 声明 (Claim) 以强制执行权限。 -更多授权 (Authorization) 场景及如何校验组织令牌 (Organization token)，请参见 授权 (Authorization)。 +更多关于授权 (Authorization) 场景和如何验证组织令牌 (Organization token)，请参见 授权 (Authorization)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index 1dc333a2a45..e74f505eb25 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -6,17 +6,17 @@ sidebar_position: 4 ## 使用场景 \{#where-to-use-it} -这通常用于用户个人资料页面，需要展示用户的组织信息。 +这通常用于用户资料页面，需要展示用户的组织 (Organization) 信息。 -组织用户信息 +组织 (Organization) 用户信息 -## 实现方法 \{#how-to-implement-it} +## 如何实现 \{#how-to-implement-it} -有两种方式可以获取组织内的用户信息。 +有两种方式可以获取组织 (Organization) 内的用户信息。 -### 1. 解码 ID 令牌 (ID token) \{#1-decode-the-id-token} +### 解码 ID 令牌 (ID token) \{#decode-the-id-token} -ID 令牌 (ID token) 是一个标准的 JWT，其中包含用户资料信息和与组织相关的声明 (Claims)。调用 SDK 方法 `decodeIdToken()` 可以获得如下的 JSON 对象： +ID 令牌 (ID token) 是一个标准的 JWT，其中包含用户资料信息和与组织 (Organization) 相关的声明 (Claims)。调用 SDK 方法 `decodeIdToken()` 可以获得如下的 JSON 对象： ```json { @@ -42,8 +42,8 @@ ID 令牌 (ID token) 是一个标准的 JWT，其中包含用户资料信息和 } ``` -但是，ID 令牌 (ID token) 只会在认证 (Authentication) 期间签发，如果用户资料之后发生更改，令牌可能会变得过时。 -如需获取最新信息，请使用下面的第二种方式，或者调用 `clearAllTokens()` 并重新发起认证 (Authentication) 流程以获取新的 ID 令牌 (ID token)。 +但是，ID 令牌 (ID token) 只会在认证 (Authentication) 期间签发，如果用户资料之后发生更改，可能会变得过时。 +如需获取最新信息，请使用下面的第二种方式，或调用 `clearAllTokens()` 并重新发起认证 (Authentication) 流程以获取新的 ID 令牌 (ID token)。 ```ts await logtoClient.clearAllTokens(); @@ -55,6 +55,6 @@ logtoClient.signIn({ 如果会话仍然有效，`signIn` 调用会在无需输入凭据的情况下重定向回你的应用。从用户的角度来看，应用只是刷新了一下，后台会自动签发新的 ID 令牌 (ID token)。 -### 2. 从 `/oidc/me` 端点获取用户信息 \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### 从 `/oidc/me` 端点获取用户信息 \{#fetch-user-info-from-the-oidc-me-endpoint} -你也可以请求 `/oidc/me`，以在组织上下文中获取实时的用户信息。调用 SDK 方法 `fetchUserInfo()` 即可。 +你也可以请求 `/oidc/me`，以在组织 (Organization) 上下文中获取实时的用户信息。调用 SDK 方法 `fetchUserInfo()`。 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 648bbf19386..77e61834647 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: 6 # 邀请组织成员 -在多组织应用中，一个常见需求是邀请成员加入组织。本指南将介绍实现此功能的步骤和技术细节。 +在多租户应用程序中，一个常见需求是邀请成员加入组织。本指南将介绍实现此功能的步骤和技术细节。 ## 流程概览 \{#flow-overview} @@ -20,7 +20,7 @@ sequenceDiagram A ->> C: 输入被邀请者邮箱和角色 C ->> L: 使用 Management API 创建组织邀请 L -->> C: 返回邀请 ID - C ->> C: 组合带有邀请 ID 的邀请链接 + C ->> C: 通过邀请 ID 生成邀请链接 C ->> L: 请求发送包含邀请链接的邀请邮件 L -->> U: 发送包含邀请链接的邀请邮件 U ->> C: 点击邀请链接并跳转到你的落地页，
接受或拒绝邀请 @@ -40,14 +40,14 @@ sequenceDiagram - `write:data` - 写入所有组织数据资源的权限。 - `delete:data` - 删除所有组织数据资源的权限。 - `invite:member` - 邀请成员加入组织。 - - `manage:member` - 管理组织成员。 + - `manage:member` - 管理组织内成员。 - `delete:member` - 移除组织成员。 - `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) 以编程方式创建组织角色。 ## 配置你的邮件连接器 \{#configure-your-email-connector} @@ -76,7 +76,7 @@ Logto Cloud 内置的 “Logto email service” 目前不支持 `OrganizationInv :::note -如果你还没有设置 Logto Management API，请参见 [与 Management API 交互](/integrate-logto/interact-with-management-api) 获取详细信息。 +如果你还没有配置 Logto Management API，请参见 [与 Management API 交互](/integrate-logto/interact-with-management-api) 获取详细信息。 ::: @@ -85,12 +85,17 @@ Logto Cloud 内置的 “Logto email service” 目前不支持 `OrganizationInv 在组织功能中有一组与邀请相关的 Management API。通过这些 API，你可以： - `POST /api/organization-invitations`：创建带有指定组织角色的组织邀请。 -- `POST /api/one-time-tokens`：为被邀请者创建一次性令牌，用于其接受邀请时认证 (Authentication)。[了解更多](/end-user-flows/one-time-token) -- `POST /api/organization-invitations/{id}/message`：通过邮件将组织邀请发送给被邀请者。 - 注意：请求体支持 `link` 属性，因此你可以基于邀请 ID 组合自己的邀请链接。例如： - - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +- `POST /api/one-time-tokens`：为被邀请人在接受邀请时认证 (Authentication) 创建一次性令牌。[了解更多](/end-user-flows/one-time-token) +- `POST /api/organization-invitations/{id}/message`：通过邮件将组织邀请发送给被邀请人。 + +:::note + +请求体支持 `link` 属性，因此你可以基于邀请 ID 自定义自己的邀请链接。例如： + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index dc21f1583e5..39af43b11fc 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -6,9 +6,11 @@ sidebar_position: 7 ## 使用场景 \{#where-to-use-it} -组织 (Organization) 列表通常出现在用户入职流程中。例如，当管理员邀请你加入某个工作区时。 +组织 (Organization) 列表和加入流程通常出现在用户入职（onboarding）期间。 +例如，当管理员邀请某人加入工作区，但该用户跳过了邮件邀请，直接在应用中登录或注册时。 -从产品角度来看，它主要会出现在两个地方： +在你的产品中，你可能希望为此流程添加入口。 +它主要可以出现在两个地方： - 登录或注册时的 **组织 (Organization) 查找器** @@ -24,9 +26,9 @@ sidebar_position: 7 ## 使用 Logto Management API 让用户加入组织 (Organization) \{#use-the-logto-management-api-to-let-users-join-an-organization} 在上一节中，我们介绍了如何使用 Logto Management API 创建并发送组织 (Organization) 邀请。 -接下来，实现一个落地页，用于在被邀请人访问你的应用时处理邀请链接。 +接下来，实现一个落地页，用于处理受邀者到达应用时的邀请链接。 - `GET /api/organization-invitations` 和 `GET /api/organization-invitations/{id}`：获取所有邀请或通过 ID 获取特定邀请。 在你的落地页上，使用这些 API 列出所有邀请，或展示用户收到的特定邀请详情。 -- `PUT /api/organization-invitations/{id}/status`：通过更新状态来接受或拒绝邀请。 +- `PUT /api/organization-invitations/{id}/status`：通过更新状态接受或拒绝邀请。 使用此 API 处理用户的响应。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 256e71c2320..d28d6b0bfaf 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,49 +2,56 @@ sidebar_position: 8 --- -# 权限 (Permission) 与资源管理 +# 处理组织令牌 (Organization token) 中的权限 (Scope) 更新 -将组织 (Organization) 作为资源，并应用组织模板来保护它。例如，每个组织 (Organization) 在租户内都有自己的文档。只有拥有正确角色 (Role) 的用户才能编辑或删除这些文档。 +通过上述设置，你可以通过电子邮件发送邀请，受邀者可以以分配的角色加入组织 (Organization)。 -详见 [组织权限 (Organization permissions)](/authorization/organization-permissions)。 +拥有不同组织 (Organization) 角色的用户将在其组织令牌 (Organization token) 中拥有不同的权限 (Scopes)。你的客户端应用和后端服务都应检查这些权限 (Scopes)，以确定可见功能和允许的操作。 -## 使用组织基于角色的访问控制 (RBAC) 管理用户权限 (Permissions) \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +如前所述，组织模板是保护[组织权限 (Organization permissions)](/authorization/organization-permissions)或[组织级 API 资源 (Organization-level APIs)](/authorization/organization-level-api-resources)的关键访问控制层。请务必查阅授权 (Authorization) 相关章节，并选择最适合你产品的授权 (Authorization) 模型。 -通过上述设置，你可以通过电子邮件发送邀请，受邀者可以以分配的角色 (Role) 加入组织 (Organization)。 +:::note -拥有不同组织角色 (Role) 的用户将在其组织令牌 (Organization token) 中拥有不同的权限 (Scopes)。你的客户端应用和后端服务都应检查这些权限 (Scopes) 以确定可见功能和允许的操作。 + + 保护组织（非 API）权限 (Organization permissions) + + + 保护组织级 API 资源 (Organization-level API resources) + -## 处理组织令牌 (Organization token) 中权限 (Scopes) 的更新 \{#handle-scope-updates-in-organization-tokens} +::: -本节涵盖关于管理组织模板和授权 (Authorization) 场景的高级主题。如果你不熟悉这些概念，请先阅读 [授权 (Authorization)](/authorization) 和 [组织模板 (Organization template)](/authorization/organization-template)。 +本章重点介绍 **权限 (Permission) 管理** 以及在 Logto 组织令牌 (Organization token) 中**处理权限 (Scope) 变更和权限 (Permission) 的最佳实践**。 -管理组织令牌 (Organization token) 中权限 (Scopes) 的更新包括： +## 处理组织令牌 (Organization token) 中的权限 (Scope) 更新 \{#handle-scope-updates-in-organization-tokens} -### 撤销现有权限 (Scopes) \{#revoke-existing-scopes} +管理组织令牌 (Organization token) 中的权限 (Scope) 更新包括： -例如，将管理员降级为非管理员成员时，应从该用户移除权限 (Scopes)。在这种情况下，清除缓存的组织令牌 (Organization token)，并使用刷新令牌 (Refresh token) 获取新的组织令牌 (Organization token)。减少后的权限 (Scopes) 会立即反映在新签发的组织令牌 (Organization token) 中。 +### 撤销已有权限 (Revoke existing scopes) \{#revoke-existing-scopes} -### 授予新权限 (Scopes) \{#grant-new-scopes} +例如，将管理员降级为非管理员成员时，应移除该用户的权限 (Scopes)。此时，清除缓存的组织令牌 (Organization token)，并使用刷新令牌 (Refresh token) 获取新的组织令牌 (Organization token)。新签发的组织令牌 (Organization token) 会立即反映减少后的权限 (Scopes)。 + +### 授予新权限 (Grant new scopes) \{#grant-new-scopes} 这可以分为两种情况： -#### 授予已在认证 (Authentication) 系统中定义的新权限 (Scopes) \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} +#### 授予已在认证 (Authentication) 系统中定义的新权限 (Grant new scopes that are already defined in your auth system) \{#grant-new-scopes-that-are-already-defined-in-your-auth-system} -与撤销权限 (Scopes) 类似，如果新授予的权限 (Scope) 已在认证 (Authentication) 服务器注册，签发新的组织令牌 (Organization token)，新权限 (Scopes) 会立即生效。 +与撤销权限 (Scopes) 类似，如果新授予的权限 (Scope) 已在认证 (Authentication) 服务器注册，签发新的组织令牌 (Organization token) 后，新权限 (Scopes) 会立即生效。 -#### 授予认证 (Authentication) 系统中新引入的权限 (Scopes) \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### 授予认证 (Authentication) 系统中新引入的新权限 (Grant new scopes that are newly introduced into your auth system) \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} -在这种情况下，触发重新登录或重新授权流程以更新用户的组织令牌 (Organization token)。例如，调用 Logto SDK 中的 `signIn` 方法。 +此时，需要触发重新登录或重新授权流程，以更新用户的组织令牌 (Organization token)。例如，调用 Logto SDK 中的 `signIn` 方法。 -## 实时检查权限 (Permissions) 并更新组织令牌 (Organization token) \{#check-permissions-in-real-time-and-update-the-organization-token} +## 实时检查权限 (Permission) 并更新组织令牌 (Organization token) \{#check-permissions-in-real-time-and-update-the-organization-token} -Logto 提供了 Management API 用于获取组织 (Organization) 内用户的实时权限 (Permissions)。 +Logto 提供了 Management API 用于获取组织 (Organization) 中用户的实时权限 (Permission)。 - `GET /api/organizations/{id}/users/{userId}/scopes` ([API 参考](https://openapi.logto.io/operation/operation-listorganizationuserscopes)) -将用户组织令牌 (Organization token) 中的权限 (Scopes) 与实时权限 (Permissions) 进行比较，以判断用户是否被提升或降级。 +将用户组织令牌 (Organization token) 中的权限 (Scopes) 与实时权限 (Permission) 进行对比，以判断用户是否被提升或降级。 -- 如果被降级，清除缓存的组织令牌 (Organization token)，SDK 会自动签发带有更新权限 (Scopes) 的新令牌 (Token)。 +- 如果被降级，清除缓存的组织令牌 (Organization token)，SDK 会自动签发包含更新权限 (Scopes) 的新组织令牌 (Organization token)。 ```tsx const { clearAccessToken } = useLogto(); @@ -57,7 +64,7 @@ Logto 提供了 Management API 用于获取组织 (Organization) 内用户的实 这不需要重新登录或重新授权流程。Logto SDK 会自动签发新的组织令牌 (Organization token)。 -- 如果在认证 (Authentication) 系统中引入了新的权限 (Scope)，则需触发重新登录或重新授权流程以更新用户的组织令牌 (Organization token)。例如，使用 React SDK： +- 如果你的认证 (Authentication) 系统中引入了新的权限 (Scope)，则需要触发重新登录或重新授权流程，以更新用户的组织令牌 (Organization token)。例如，使用 React SDK： ```tsx const { clearAllTokens, signIn } = useLogto(); @@ -72,4 +79,4 @@ Logto 提供了 Management API 用于获取组织 (Organization) 内用户的实 ``` - 上述代码会触发跳转到用户授权页面 (Consent screen)，并在用户组织令牌 (Organization token) 中带有更新后的权限 (Scopes) 自动重定向回你的应用。 + 上述代码会触发跳转到用户授权页面 (Consent screen)，并在用户组织令牌 (Organization token) 权限 (Scopes) 更新后自动重定向回你的应用。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index 4aeaa1753aa..fe77e1667cc 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,14 +4,15 @@ sidebar_position: 2 # 使用 Logto Management API 配置你的应用服务 -使用 Logto **Management API** 在你的应用中构建自定义的**组织 (Organization) 流程**。下面是集成 Management API 的基础设置步骤。如果你已经熟悉这些内容，可以直接跳转到[教程](/integrate-logto/interact-with-management-api)。 +Logto 提供了强大的 Management API，让你可以在应用内创建并自定义自己的组织 (Organization) 流程。 +理解其工作原理是设计自定义方案的关键。以下是集成 Management API 以实现组织 (Organization) 体验的基本步骤和概要。 -熟悉设置流程后，你可以探索更多 API，以便根据业务需求定制其余流程。 +如果你已经了解基础知识，可以直接跳转到[教程](/integrate-logto/interact-with-management-api)。熟悉设置后，你还可以探索更多 API，以根据业务需求定制其余流程。 -## 建立机器对机器 (Machine-to-machine) 连接 \{#establish-a-machine-to-machine-connection} +## 建立机器对机器 (Machine-to-Machine) 连接 \{#establish-a-machine-to-machine-connection} Logto 使用**机器对机器 (M2M) 认证 (Authentication)**，安全地将你的后端服务连接到 Logto Management API 端点。 -你的后端服务随后可以使用 Management API 处理与组织 (Organization) 相关的任务，例如**创建组织 (Organization)**、**添加或移除成员**等。 +你的后端服务随后可以使用 Management API 处理与组织 (Organization) 相关的任务，如**创建组织 (Organization)**、**添加或移除成员**等。 具体步骤如下： @@ -31,17 +32,17 @@ curl \ ## 保护你的应用服务器 \{#protect-your-app-server} -由于终端用户可以自助执行某些组织 (Organization) 操作，请在终端用户和你的应用服务器之间添加授权 (Authorization) 层。服务器应拦截每个请求，验证用户的组织令牌 (Organization token) 及所需权限 (Scopes)，只有在验证通过后，才使用服务器持有的 M2M 凭证调用 Management API。 +由于终端用户可以自行执行某些组织 (Organization) 操作，因此在终端用户与应用服务器之间添加授权 (Authorization) 层非常重要。你可以根据所用的 Logto Management API 端点以及产品 API 的结构，将此层应用于全局或组织 (Organization) 级别。服务器应拦截每个请求，验证用户的组织令牌 (Organization token) 及所需权限 (Scopes)，然后仅使用服务器持有的 M2M 凭证调用 Management API。 -当用户提交组织令牌 (Organization token) 请求某个操作（例如创建组织 (Organization)）时，服务器首先验证令牌中的权限 (Scopes)。如果令牌包含必要的权限 (Scope)，如 `org:create`，则授权 (Authorization) 请求，并通过 M2M 流程调用 Logto Management API 创建组织 (Organization)。 +当用户提交组织令牌 (Organization token) 请求某个操作（例如创建组织 (Organization)）时，服务器首先验证令牌中的权限 (Scopes)。如果令牌包含所需权限 (Scope)，如 `org:create`，则授权 (Authorization) 请求，并通过 M2M 流程调用 Logto Management API 创建组织 (Organization)。 -如果令牌不包含所需权限 (Scopes)，则返回 403 Forbidden 并跳过 M2M 逻辑。这确保了没有相应权限的用户无法创建组织 (Organizations)。 +如果令牌不包含所需权限 (Scopes)，则返回 403 Forbidden 并跳过 M2M 逻辑。这确保了没有相应权限的用户无法创建组织 (Organization)。 以下是常见的授权 (Authorization) 模式。 ### 使用组织 (Organization) 权限 (Permissions) \{#using-organization-permissions} -首先，确保你已在[上一节](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations)的组织 (Organization) 模板中定义了组织权限 (Permissions) 和角色 (Roles)。 +首先，确保你已在[上一节](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations)的组织 (Organization) 模板中定义了组织 (Organization) 权限 (Permissions) 和角色 (Roles)。 然后，确保在 Logto 配置中包含了 `UserScope.Organizations`（值：`urn:logto:organization`）。以 React SDK 为例： @@ -67,14 +68,24 @@ const config = { }; ``` -这样可以确保在调用 `getOrganizationToken(organizationId)` 时，客户端 SDK 会请求包含分配给用户的组织权限 (Permissions) 的组织令牌 (Organization token)。你的后端服务随后可以验证该令牌，并根据这些权限 (Permissions) 授权 (Authorization) 后续请求。 +这样，当调用 `getOrganizationToken(organizationId)` 时，客户端 SDK 会请求包含分配给用户的组织 (Organization) 权限 (Permissions) 的组织令牌 (Organization token)。你的后端服务随后可以验证该令牌，并根据这些权限 (Permissions) 授权 (Authorization) 后续请求。 关于保护组织级（非 API）权限 (Permissions) 的详细信息，请参阅[完整指南](/authorization/organization-permissions)。 -### 混合组织级权限 (Permissions) 与 API 级权限 (Permissions) \{#mixing-organization-level-permissions-and-api-level-permissions} +### 使用 API 级权限 (Permissions) \{#using-api-level-permissions} -当你的 API 资源 (API resources) 和权限 (Permissions) 是全局注册的，但角色 (Roles) 在组织 (Organization) 级别定义时适用（你可以在组织模板中将 API 级权限 (Permissions) 分配给组织角色 (Roles)）。 +当你的 API 资源和权限 (Permissions) 在全局注册，但角色 (Roles) 在组织 (Organization) 级别定义时适用（你可以在组织 (Organization) 模板中将 API 级权限 (Permissions) 分配给组织 (Organization) 角色 (Roles)）。 -实现方式与上一节相同。始终提供组织 ID 并调用 `getOrganizationToken(organizationId)` 获取组织令牌 (Organization token)；否则，组织权限 (Permissions) 不会被包含。 +实现方式与上一节相同。始终提供组织 (Organization) ID 并调用 `getOrganizationToken(organizationId)` 获取组织令牌 (Organization token)；否则不会包含组织 (Organization) 权限 (Permissions)。 关于保护组织级 API 权限 (Permissions) 的详细信息，请参阅[完整指南](/authorization/organization-level-api-resources)。 + +### 使用全局 RBAC \{#using-global-rbac} + +在这种情况下，你可以使用 Logto Management API 实现系统级访问控制。 + +在多租户环境下，常见模式是拥有超级用户或超级管理员角色。例如，如果你正在使用 Logto 构建 SaaS 平台，可能希望有一个超级用户可以直接在你的应用内管理所有客户组织 (Organizations)，而无需登录 Logto 控制台。 + +该超级用户可以执行更高层级的操作，如批量创建或删除组织 (Organizations)，这些操作需要超越任何单一组织 (Organization) 上下文的系统级权限。为此，在 Logto 中注册一个 API 资源，同时利用 Logto Management API，并使用全局 RBAC 管理这些权限 (Permissions)。 + +有关集成和管理 RBAC 访问控制的更多细节，请参阅[完整指南](/authorization/global-api-resources)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx index 1124b81db71..de8a0ef7f70 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/create-organization.mdx @@ -4,9 +4,9 @@ sidebar_position: 3 # 建立組織 (Organization) -假設你正在打造一個[多租戶應用程式](https://auth.wiki/multi-tenancy)（例如多租戶 SaaS 應用程式），服務眾多客戶，每個客戶都擁有專屬的租戶。 +想像你正在打造一個[多租戶應用程式](https://auth.wiki/multi-tenancy)（例如多租戶 SaaS 應用），服務眾多客戶，每個客戶都擁有專屬的租戶。 -通常會在以下情境建立組織 (Organization)： +組織 (Organization) 通常在以下情境下建立： 1. 新客戶註冊時，同時為其企業建立帳號與租戶。 2. 現有使用者可在應用程式內建立新組織。 @@ -20,30 +20,33 @@ sidebar_position: 3 alt="現有使用者建立組織 (Existing user creates organization)" /> -## 實作組織建立功能 \{#implement-organization-creation} +## 實作組織建立流程 \{#implement-organization-creation} -你可以透過兩種方式為應用程式建立組織。 +你可以用兩種方式為應用程式建立組織。 ### 透過 Logto Console 建立 \{#create-via-logto-console} -可在 Logto Console UI 手動建立組織。前往 Console > Organizations 建立組織、指派成員與角色，並自訂組織登入體驗。 +在 Logto Console UI 中手動建立組織。前往 Console > Organizations 建立組織、指派成員與角色，並自訂組織登入體驗。 -建立[組織範本 (Organization template)](/authorization/organization-template)，可批次建立擁有相同角色與權限的組織。 +建立 [組織範本 (Organization template)](/authorization/organization-template) 以批次建立擁有相同角色與權限的組織。 ### 透過 Logto Management API 建立 \{#create-via-logto-management-api} -Console 適合手動設置，但大多數應用程式會讓終端使用者自助操作——直接在你的應用程式中建立與管理組織。你可以透過 Logto Management API 實作這些功能。 +Console 適合手動設置，但大多數應用程式會讓終端使用者自助操作——直接在你的應用中建立與管理組織。要實現這些功能，請使用 Logto Management API。 :::note -如果你是第一次接觸 Logto Management API，請先閱讀： +如果你是第一次接觸 Logto Management API，或尚未閱讀如何用 Logto Management API 實現組織體驗的基礎介紹，請先閱讀： + + 使用 Logto Management API 設定你的應用服務 + Management API -Interact with Management API +與 Management API 互動 ::: -假設你的後端已透過機器對機器 (M2M, Machine-to-Machine) 機制連接 Logto Management API，並取得了 M2M 存取權杖 (Access token)。 +假設你的後端已透過機器對機器 (M2M, Machine-to-Machine) 機制連接 Logto Management API，並取得 M2M 存取權杖 (Access token)。 使用 Management API 建立組織（[API 參考文件](https://openapi.logto.io/operation/operation-createorganization)）： @@ -69,10 +72,10 @@ curl \ 更多細節請參閱 [完整 API 規格](https://openapi.logto.io/group/endpoint-organizations)。 -建議將這些呼叫包裝在你自己的 API 層。當使用者在你的應用程式執行「建立組織」動作時，先檢查其權限，再呼叫 Logto Management API 完成操作。 +建議將這些呼叫包裝在你自己的 API 層。當使用者在你的應用中執行「建立組織」動作時，先檢查其權限，再呼叫 Logto Management API 完成操作。 ## 驗證使用者請求中的組織權杖 (Organization token) \{#validating-organization-token-in-user-request} -在你的應用程式中，當使用者於組織情境下執行操作時，必須使用組織權杖 (Organization token)，而非一般存取權杖 (Access token)。組織權杖是一個 [JWT](https://auth.wiki/jwt)，內含組織權限。就像任何 [存取權杖 (Access token)](https://auth.wiki/access-token) 一樣，你可以解碼宣告 (Claims) 並驗證 "scope" 宣告以強制執行權限。 +在你的應用中，當使用者在組織情境下執行操作時，必須使用組織權杖 (Organization token)，而非一般存取權杖 (Access token)。組織權杖是一個 [JWT](https://auth.wiki/jwt)，內含組織權限。與任何 [存取權杖 (Access token)](https://auth.wiki/access-token) 一樣，你可以解碼宣告 (Claims) 並驗證 "scope" 宣告以強制執行權限。 更多授權 (Authorization) 情境與組織權杖驗證方式，請參閱 授權 (Authorization)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx index 266d7ca12ca..1520174e05f 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/get-user-info.mdx @@ -14,7 +14,7 @@ sidebar_position: 4 有兩種方式可以取得組織內的使用者資訊。 -### 1. 解碼 ID 權杖 (ID token) \{#1-decode-the-id-token} +### 解碼 ID 權杖 (ID token) \{#decode-the-id-token} ID 權杖 (ID token) 是一個標準的 JWT，內含使用者個人資料資訊與組織相關宣告 (claims)。呼叫 SDK 方法 `decodeIdToken()` 可取得如下的 JSON 物件： @@ -42,8 +42,8 @@ ID 權杖 (ID token) 是一個標準的 JWT，內含使用者個人資料資訊 } ``` -但請注意，ID 權杖 (ID token) 僅在驗證 (Authentication) 時簽發，若使用者個人資料後續有變更，權杖內容可能會過時。 -若需取得最新資訊，請使用下方第二種方式，或呼叫 `clearAllTokens()` 並重新啟動驗證流程以獲取新的 ID 權杖 (ID token)。 +但請注意，ID 權杖 (ID token) 僅於驗證 (Authentication) 時簽發，若使用者個人資料後續有變更，權杖內容可能會過時。 +若需取得最新資訊，請參考下方第二種方式，或呼叫 `clearAllTokens()` 並重新啟動驗證流程以取得新的 ID 權杖 (ID token)。 ```ts await logtoClient.clearAllTokens(); @@ -53,8 +53,8 @@ logtoClient.signIn({ }); ``` -如果會話仍然有效，`signIn` 呼叫會直接導回你的應用程式，無需再次輸入憑證。對使用者而言，應用程式僅會刷新畫面，並在背景取得新的 ID 權杖 (ID token)。 +如果會話仍有效，`signIn` 呼叫會直接導回你的應用程式，無需再次輸入憑證。對使用者來說，應用程式僅會刷新畫面，並於背景自動取得新的 ID 權杖 (ID token)。 -### 2. 從 `/oidc/me` 端點取得使用者資訊 \{#2-fetch-user-info-from-the-oidc-me-endpoint} +### 從 `/oidc/me` 端點取得使用者資訊 \{#fetch-user-info-from-the-oidc-me-endpoint} -你也可以請求 `/oidc/me` 以即時取得組織情境下的使用者資訊。呼叫 SDK 方法 `fetchUserInfo()` 即可。 +你也可以請求 `/oidc/me`，以組織情境下即時取得使用者資訊。請呼叫 SDK 方法 `fetchUserInfo()`。 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 31938e099d2..b36d1b03420 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: 6 # 邀請組織成員 -在多組織應用程式中，常見需求之一是邀請成員加入組織。本指南將帶你了解實作此功能的步驟與技術細節。 +在多租戶（multi-tenancy）應用程式中，常見需求之一是邀請成員加入組織。本指南將帶你瞭解實作此功能的步驟與技術細節。 ## 流程總覽 \{#flow-overview} @@ -29,9 +29,9 @@ sequenceDiagram ## 建立組織角色 \{#create-organization-roles} -在邀請成員之前，請先建立組織角色。詳情請參閱 [組織範本 (organization template)](/authorization/organization-template) 以瞭解角色與權限。 +在邀請成員之前，請先建立組織角色。參閱 [組織範本](/authorization/organization-template) 以深入瞭解角色與權限。 -本指南將建立兩個典型的組織角色：`admin` 和 `member`。 +本指南將建立兩個典型的組織角色：`admin` 與 `member`。 `admin` 角色擁有組織內所有資源的完整存取權限，而 `member` 角色則有較有限的權限。例如： @@ -47,13 +47,13 @@ sequenceDiagram - `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) 以程式方式建立組織角色。 ## 設定你的電子郵件連接器 \{#configure-your-email-connector} -由於邀請是透過電子郵件發送，請確保你的 [電子郵件連接器 (email connector)](/connectors/email-connectors) 已正確設定。若要發送邀請，請設定一個 `OrganizationInvitation` 用途類型的 [電子郵件範本 (email template)](/connectors/email-connectors/email-templates#email-template-types)。你可以在內容中加入組織（如名稱、Logo）與邀請人（如電子郵件、名稱）[變數 (variables)](/connectors/email-connectors/email-templates#email-template-variables)，並根據需求自訂 [在地化範本 (localized templates)](/connectors/email-connectors/email-templates#email-template-localization)。 +由於邀請是透過電子郵件發送，請確保你的 [電子郵件連接器](/connectors/email-connectors) 已正確設定。若要發送邀請，請設定一個使用類型為 `OrganizationInvitation` 的 [電子郵件範本](/connectors/email-connectors/email-templates#email-template-types)。你可以在內容中加入組織（如名稱、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}}` 佔位符會在郵件發送時自動替換為實際邀請連結。 +電子郵件內容中的 `{{link}}` 佔位符會在郵件發送時自動替換為實際的邀請連結。 :::note -Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationInvitation` 用途類型。請改用你自己的電子郵件連接器（如 SendGrid），並設定 `OrganizationInvitation` 範本。 +Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationInvitation` 使用類型。請改為設定你自己的電子郵件連接器（如 SendGrid），並設置 `OrganizationInvitation` 範本。 ::: @@ -76,21 +76,26 @@ Logto Cloud 內建的「Logto email service」目前尚不支援 `OrganizationIn :::note -如果你尚未設定 Logto Management API，請參閱 [與 Management API 互動 (Interact with Management API)](/integrate-logto/interact-with-management-api) 以取得詳細說明。 +如果你尚未設定 Logto Management API，請參閱 [與 Management API 互動](/integrate-logto/interact-with-management-api) 以瞭解詳情。 ::: ### 使用 Logto Management API 建立組織邀請 \{#create-an-organization-invitation-with-logto-management-api} -在組織功能中有一組與邀請相關的 Management API。你可以透過這些 API： +組織功能中提供了一組與邀請相關的 Management API。你可以透過這些 API： - `POST /api/organization-invitations`：建立帶有指定組織角色的組織邀請。 - `POST /api/one-time-tokens`：為受邀者建立一次性權杖，供其接受邀請時驗證身分。[進一步瞭解](/end-user-flows/one-time-token) - `POST /api/organization-invitations/{id}/message`：透過電子郵件將組織邀請發送給受邀者。 - 注意：請求內容支援 `link` 屬性，你可以根據邀請 ID 組合自己的邀請連結。例如： - ```json - { - "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" - } - ``` +:::note + +請求內容支援 `link` 屬性，因此你可以根據邀請 ID 組合自訂邀請連結。例如： + +::: + +```json +{ + "link": "https://your-app.com/invitation/join?id=your-invitation-id&token=your-one-time-token&email=invitee-email" +} +``` diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx index e26afa2752c..ea371663763 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/join-the-organization.mdx @@ -4,11 +4,13 @@ sidebar_position: 7 # 加入組織 (Organization) -## 使用場景 \{#where-to-use-it} +## 適用場景 \{#where-to-use-it} -組織清單通常出現在使用者導入流程中。例如，當管理員邀請你加入某個工作區時。 +組織清單與加入流程通常出現在使用者導入（onboarding）階段。 +例如，當管理員邀請某人加入工作區，但該使用者跳過電子郵件邀請，直接在應用程式中登入或註冊時。 -從產品角度來看，這個功能主要會出現在兩個地方： +你可以在產品中為此流程新增入口點。 +常見出現位置有兩個： - 登入或註冊時的 **組織搜尋器 (organization finder)** @@ -27,9 +29,9 @@ sidebar_position: 7 ## 使用 Logto Management API 讓使用者加入組織 (Organization) \{#use-the-logto-management-api-to-let-users-join-an-organization} 在前一節中，我們介紹了如何使用 Logto Management API 建立並發送組織邀請。 -接下來，實作一個著陸頁，當受邀者點擊邀請連結進入你的應用程式時進行處理。 +接下來，實作一個登陸頁面，當受邀者點擊邀請連結進入你的應用程式時進行處理。 -- `GET /api/organization-invitations` 與 `GET /api/organization-invitations/{id}`：取得所有邀請或依 ID 取得特定邀請。 - 在你的著陸頁上，使用這些 API 來列出所有邀請，或顯示使用者收到的特定邀請詳情。 +- `GET /api/organization-invitations` 與 `GET /api/organization-invitations/{id}`：取得所有邀請或依 ID 查詢特定邀請。 + 在你的登陸頁面上，使用這些 API 列出所有邀請，或顯示使用者收到的特定邀請詳情。 - `PUT /api/organization-invitations/{id}/status`：透過更新邀請狀態來接受或拒絕邀請。 使用此 API 處理使用者的回應。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx index 47a516180eb..4d09b6967c1 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/permission-and-resource-management.mdx @@ -2,29 +2,36 @@ sidebar_position: 8 --- -# 權限與資源管理 +# 處理組織權杖 (Organization token) 的權限範圍 (Scope) 更新 -將組織 (Organization) 作為資源，並套用組織範本 (Organization template) 來保護它。例如，每個組織在租戶內都有自己的文件，只有擁有正確角色 (Role) 的使用者才能編輯或刪除這些文件。 +完成上述設定後，你可以透過電子郵件發送邀請，受邀者將以指定角色加入組織 (Organization)。 -詳情請參閱 [組織權限 (Organization permissions)](/authorization/organization-permissions)。 +擁有不同組織角色的使用者，其組織權杖 (Organization token) 中會有不同的權限範圍 (Scopes / Permissions)。你的前端應用程式與後端服務都應檢查這些權限範圍，以決定可見功能與允許操作。 -## 使用組織角色型存取控制 (RBAC, Role-based Access Control) 管理使用者權限 \{#use-organization-role-based-access-control-rbac-to-manage-user-permissions} +如前所述，組織範本 (Organization template) 是保護[組織權限 (Organization permissions)](/authorization/organization-permissions)或[組織層級 API](/authorization/organization-level-api-resources)的重要存取控制層。請務必檢閱授權 (Authorization) 章節，並選擇最適合你產品的授權模型。 -完成上述設定後，你可以透過電子郵件發送邀請，受邀者將以指定角色加入組織。 +:::note -擁有不同組織角色的使用者，在其組織權杖 (Organization token) 中會有不同的權限範圍 (Scopes)。你的前端應用程式與後端服務都應檢查這些權限範圍，以決定可見功能與允許操作。 + + 保護組織（非 API）權限 (Organization permissions) + + + 保護組織層級 API 資源 (Organization-level API resources) + -## 處理組織權杖 (Organization token) 權限範圍 (Scope) 更新 \{#handle-scope-updates-in-organization-tokens} +::: + +本章重點說明 **權限管理** 以及在 Logto 組織權杖 (Organization token) 中**處理權限範圍 (Scope) 變更與權限**的最佳實踐。 -本節涵蓋管理組織範本 (Organization template) 與授權 (Authorization) 情境的進階主題。若你尚未熟悉這些概念，請先閱讀 [授權 (Authorization)](/authorization) 與 [組織範本 (Organization template)](/authorization/organization-template)。 +## 處理組織權杖 (Organization token) 權限範圍 (Scope) 更新 \{#handle-scope-updates-in-organization-tokens} -管理組織權杖權限範圍更新包含： +管理組織權杖 (Organization token) 權限範圍 (Scope) 更新包含： -### 撤銷現有權限範圍 (Scopes) \{#revoke-existing-scopes} +### 撤銷現有權限範圍 (Revoke existing scopes) \{#revoke-existing-scopes} -例如，將管理員降級為非管理員成員時，應移除該使用者的權限範圍。此時，請清除快取的組織權杖，並使用重新整理權杖 (Refresh token) 取得新權杖。新發行的組織權杖會立即反映權限範圍的減少。 +例如，將管理員降級為一般成員時，應移除該使用者的權限範圍 (Scopes)。此時，請清除快取的組織權杖 (Organization token)，並使用重新整理權杖 (Refresh token) 取得新權杖。新發行的組織權杖會立即反映權限範圍的減少。 -### 賦予新權限範圍 (Scopes) \{#grant-new-scopes} +### 賦予新權限範圍 (Grant new scopes) \{#grant-new-scopes} 可分為兩種情境： @@ -32,17 +39,17 @@ sidebar_position: 8 與撤銷權限範圍類似，若新賦予的權限範圍已在驗證伺服器註冊，發行新組織權杖即可立即反映新權限範圍。 -#### 賦予驗證系統中新引入的權限範圍 \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} +#### 賦予剛新增至驗證系統的新權限範圍 \{#grant-new-scopes-that-are-newly-introduced-into-your-auth-system} -此時需觸發重新登入或重新同意流程，以更新使用者的組織權杖。例如，呼叫 Logto SDK 的 `signIn` 方法。 +此時，需觸發重新登入或重新授權（consent）流程，以更新使用者的組織權杖。例如，呼叫 Logto SDK 的 `signIn` 方法。 -## 即時檢查權限並更新組織權杖 \{#check-permissions-in-real-time-and-update-the-organization-token} +## 即時檢查權限並更新組織權杖 (Organization token) \{#check-permissions-in-real-time-and-update-the-organization-token} -Logto 提供 Management API 以即時查詢使用者在組織中的權限。 +Logto 提供 Management API 以查詢組織中使用者的即時權限： - `GET /api/organizations/{id}/users/{userId}/scopes`（[API 參考文件](https://openapi.logto.io/operation/operation-listorganizationuserscopes)） -比較使用者組織權杖中的權限範圍與即時權限，以判斷使用者是否被升級或降級。 +將使用者組織權杖中的權限範圍與即時權限比對，以判斷使用者是否被升級或降級。 - 若被降級，請清除快取的組織權杖，SDK 會自動發行包含更新權限範圍的新權杖。 @@ -55,15 +62,15 @@ Logto 提供 Management API 以即時查詢使用者在組織中的權限。 ``` - 此操作不需重新登入或重新同意流程。Logto SDK 會自動發行新組織權杖。 + 此操作不需重新登入或重新授權。Logto SDK 會自動發行新的組織權杖。 -- 若驗證系統中引入了新權限範圍，需觸發重新登入或重新同意流程以更新使用者的組織權杖。例如，使用 React SDK： +- 若驗證系統中新增了新的權限範圍，則需觸發重新登入或重新授權流程以更新使用者的組織權杖。例如，使用 React SDK： ```tsx const { clearAllTokens, signIn } = useLogto(); ... - // 若即時查詢的權限範圍多於組織權杖中的權限範圍 + // 若即時查詢的權限範圍有新分配的權限範圍 await clearAllTokens(); signIn({ redirectUri: '', @@ -72,4 +79,4 @@ Logto 提供 Management API 以即時查詢使用者在組織中的權限。 ``` - 上述程式碼會導向使用者授權頁面 (Consent screen)，並於同意後自動導回你的應用程式，組織權杖中的權限範圍也會隨之更新。 + 上述程式碼會導向使用者授權頁面 (Consent screen)，並於授權後自動導回應用程式，且組織權杖中的權限範圍已更新。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx index 9cb4f3c1d44..ba9eaf19fbe 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/end-user-flows/organization-experience/setup-app-service-with-management-api.mdx @@ -4,14 +4,15 @@ sidebar_position: 2 # 使用 Logto Management API 設定你的應用服務 -利用 Logto **Management API**，你可以在應用程式中打造自訂的 **組織 (Organization) 流程**。以下是整合 Management API 的基本設定步驟。如果你已經熟悉這些內容，可以直接前往 [教學](/integrate-logto/interact-with-management-api)。 +Logto 提供強大的 Management API，讓你能在應用程式內建立並自訂專屬的組織 (Organization) 流程。 +理解其運作方式是設計自訂流程的關鍵。以下為整合 Management API 以實現組織使用體驗的基本步驟與概要。 -熟悉設定後，你可以探索更多 API，根據業務需求調整其餘流程。 +如果你已熟悉基礎內容，可直接前往 [教學](/integrate-logto/interact-with-management-api)。熟悉設定後，還能探索更多 API，根據業務需求調整其餘流程。 ## 建立機器對機器連線 \{#establish-a-machine-to-machine-connection} -Logto 採用 **機器對機器 (M2M, Machine-to-Machine) 驗證 (Authentication)**，安全地將你的後端服務連接至 Logto Management API 端點。 -你的後端服務即可透過 Management API 處理與組織 (Organization) 相關的任務，例如 **建立組織 (Organization)**、**新增或移除成員**等。 +Logto 使用 **機器對機器 (M2M, Machine-to-Machine) 驗證 (Authentication)**，安全地將你的後端服務連接至 Logto Management API 端點。 +你的後端服務即可透過 Management API 處理組織相關任務，例如**建立組織**、**新增或移除成員**等。 步驟如下： @@ -20,7 +21,7 @@ Logto 採用 **機器對機器 (M2M, Machine-to-Machine) 驗證 (Authentication) M2M app details 2. 從 Logto **取得 M2M 存取權杖 (Access token)**。[進一步了解](/integrate-logto/interact-with-management-api#fetch-an-access-token)。 -3. 從你的後端服務 **呼叫 Logto Management API**。例如，列出所有組織 (Organizations)： +3. 從你的後端服務 **呼叫 Logto Management API**。例如，列出所有組織： ```bash curl \ @@ -31,17 +32,17 @@ curl \ ## 保護你的應用伺服器 \{#protect-your-app-server} -由於終端使用者可自行執行部分組織 (Organization) 操作，建議在終端使用者與應用伺服器之間加入授權 (Authorization) 層。伺服器應攔截每個請求，驗證使用者的組織權杖 (Organization token) 及所需權限範圍 (Scopes)，僅在通過驗證後，才以伺服器持有的 M2M 憑證呼叫 Management API。 +由於終端使用者可自行執行部分組織操作，因此在終端使用者與應用伺服器之間加入授權 (Authorization) 層至關重要。你可以根據所使用的 Logto Management API 端點及產品 API 架構，選擇全域或組織層級套用此授權層。伺服器應攔截每個請求，驗證使用者的組織權杖 (Organization token) 及所需權限範圍 (Scopes)，僅在通過驗證後，才以伺服器持有的 M2M 憑證呼叫 Management API。 -當使用者提交組織權杖 (Organization token) 請求操作（例如建立組織 (Organization)）時，伺服器會先驗證權杖中的權限範圍 (Scopes)。若權杖包含必要的權限範圍（如 `org:create`），則授權 (Authorize) 請求並透過 M2M 流程呼叫 Logto Management API 建立組織 (Organization)。 +當使用者提交組織權杖請求操作（例如建立組織）時，伺服器會先驗證權杖中的權限範圍 (Scopes)。若權杖包含必要權限範圍（如 `org:create`），則授權請求並透過 M2M 流程呼叫 Logto Management API 建立組織。 -若權杖未包含所需權限範圍，則回傳 403 Forbidden，並略過 M2M 邏輯。這可確保未具備適當權限的使用者無法建立組織 (Organization)。 +若權杖未包含所需權限範圍，則回傳 403 Forbidden 並略過 M2M 邏輯。如此可確保未具備適當權限的使用者無法建立組織。 -以下是常見的授權 (Authorization) 模式。 +以下為常見授權 (Authorization) 模式。 ### 使用組織權限 (Organization permissions) \{#using-organization-permissions} -首先，請確保你已在 [前一節](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations) 的組織 (Organization) 範本中定義組織權限 (Organization permissions) 與角色 (Roles)。 +首先，請確保你已在[前一節](/end-user-flows/organization-experience/organization-management#define-access-control-within-organizations)的組織範本中定義組織權限與角色。 接著，確認 Logto 設定中已包含 `UserScope.Organizations`（值：`urn:logto:organization`）。以 React SDK 為例： @@ -53,7 +54,7 @@ const config = { endpoint: 'https://.logto.app/', // 你的 Logto 端點 appId: '40fmibayagoo00lj26coc', // 你的 app id resources: [ - 'https://my.company.com/api', // 你的全域 API 資源 (API resource) 識別符 + 'https://my.company.com/api', // 你的全域 API 資源識別符 ], scopes: [ UserScope.Email, @@ -67,14 +68,24 @@ const config = { }; ``` -這樣當呼叫 `getOrganizationToken(organizationId)` 時，client SDK 會請求包含指派給使用者之組織權限 (Organization permissions) 的組織權杖 (Organization token)。你的後端服務即可驗證該權杖，並根據這些權限授權 (Authorize) 後續請求。 +這可確保當呼叫 `getOrganizationToken(organizationId)` 時，client SDK 會請求包含分配給使用者之組織權限的組織權杖。你的後端服務即可驗證該權杖，並根據這些權限授權後續請求。 -關於保護組織層級（非 API）權限的詳細說明，請參閱 [完整指南](/authorization/organization-permissions)。 +關於保護組織層級（非 API）權限，詳見[完整指南](/authorization/organization-permissions)。 -### 混合組織層級權限與 API 層級權限 \{#mixing-organization-level-permissions-and-api-level-permissions} +### 使用 API 層級權限 (API-level permissions) \{#using-api-level-permissions} -當你的 API 資源 (API resources) 與權限 (Permissions) 是全域註冊，但角色 (Roles) 則在組織 (Organization) 層級定義時適用（你可以在組織範本中將 API 層級權限指派給組織角色）。 +當你的 API 資源與權限為全域註冊，但角色於組織層級定義時（你可在組織範本中將 API 層級權限指派給組織角色），適用此模式。 -實作方式與前述相同。務必提供組織 ID 並呼叫 `getOrganizationToken(organizationId)` 以取得組織權杖 (Organization token)；否則，組織權限 (Organization permissions) 不會被包含。 +實作方式與前述相同。務必提供組織 ID 並呼叫 `getOrganizationToken(organizationId)` 以取得組織權杖，否則不會包含組織權限。 -關於保護組織層級 API 權限的詳細說明，請參閱 [完整指南](/authorization/organization-level-api-resources)。 +關於保護組織層級 API 權限，詳見[完整指南](/authorization/organization-level-api-resources)。 + +### 使用全域 RBAC (Global RBAC) \{#using-global-rbac} + +此情境下，你可利用 Logto Management API 實作系統層級存取控制。 + +在多租戶環境中，常見模式是設有超級使用者或超級管理員角色。例如，若你以 Logto 建立 SaaS 平台，可能希望有一位超級使用者能直接在自家應用內管理所有客戶組織，無需登入 Logto Console。 + +此超級使用者可執行更高層級操作，如批次建立或刪除組織，這些操作需超越單一組織範疇的系統權限。為實現此目標，請在 Logto 註冊 API 資源，並結合 Logto Management API，利用全域 RBAC 管理這些權限。 + +關於 RBAC 整合與存取控制管理，詳見[完整指南](/authorization/global-api-resources)。