From 00794343cf69da2fc84b914445d7cdff553571c2 Mon Sep 17 00:00:00 2001 From: gao-sun <14722250+gao-sun@users.noreply.github.com> Date: Wed, 10 Dec 2025 08:59:18 +0000 Subject: [PATCH 1/2] chore: update translations and generated content --- .../_handle-user-permission-change.mdx | 6 +- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 45 +++---- .../organization-level-api-resources.mdx | 69 +++++----- .../organization-permissions.mdx | 61 ++++----- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 67 +++++----- .../organization-level-api-resources.mdx | 57 +++++---- .../organization-permissions.mdx | 39 +++--- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 51 ++++---- .../organization-level-api-resources.mdx | 55 ++++---- .../organization-permissions.mdx | 51 ++++---- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 105 ++++++++------- .../organization-level-api-resources.mdx | 120 +++++++++--------- .../organization-permissions.mdx | 115 +++++++++-------- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 75 ++++++----- .../organization-level-api-resources.mdx | 103 +++++++-------- .../organization-permissions.mdx | 65 +++++----- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 59 ++++----- .../organization-level-api-resources.mdx | 37 +++--- .../organization-permissions.mdx | 81 ++++++------ .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 109 ++++++++-------- .../organization-level-api-resources.mdx | 99 ++++++++------- .../organization-permissions.mdx | 63 ++++----- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 107 ++++++++-------- .../organization-level-api-resources.mdx | 95 +++++++------- .../organization-permissions.mdx | 71 ++++++----- .../_handle-user-permission-change.mdx | 31 +++++ .../authorization/global-api-resources.mdx | 93 +++++++------- .../organization-level-api-resources.mdx | 113 +++++++++-------- .../organization-permissions.mdx | 61 ++++----- 37 files changed, 1330 insertions(+), 1021 deletions(-) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx diff --git a/docs/authorization/fragments/_handle-user-permission-change.mdx b/docs/authorization/fragments/_handle-user-permission-change.mdx index edfd75b5dfd..fe0a6fc5769 100644 --- a/docs/authorization/fragments/_handle-user-permission-change.mdx +++ b/docs/authorization/fragments/_handle-user-permission-change.mdx @@ -8,7 +8,7 @@ Even if a user gains new permissions, the token issued later can only contain a To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow. ::: -#### Downscoped permissions +#### Downscoped permissions \{#downscoped-permissions} When a user loses permissions: @@ -18,13 +18,13 @@ When a user loses permissions: If you need faster reactions, implement your own signal that tells clients to refresh their tokens. -#### Enlarged permissions +#### Enlarged permissions \{#enlarged-permissions} {props.type === "global" &&

For global API resources, when a user gains permissions, enlarged permissions will NOT show up through refresh. The client must perform a new OAuth authorization flow to obtain a token that includes the new scopes. This can happen silently if the user has an active Logto session.

} {props.type === "organization" &&

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

} -#### Recommendations +#### Recommendations \{#recommendations} - Validate scopes in your API on every call. - Keep token expiration short. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/de/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..77afffd0f5c --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### Optional: Benutzerberechtigungsänderungen behandeln \{#optional-handle-user-permission-change} + +Benutzerberechtigungen können sich jederzeit ändern. Da Logto JWTs für rollenbasierte Zugangskontrolle (RBAC) ausstellt, erscheinen Berechtigungsänderungen nur in neu ausgestellten Tokens und ändern niemals bestehende JWTs. + +:::info Berechtigungs-Subset-Regel +Ein Zugangstoken (Access token) kann nur Berechtigungen (Scopes) enthalten, die im ursprünglichen OAuth-Autorisierungsablauf angefordert wurden. +Selbst wenn ein Benutzer neue Berechtigungen erhält, kann das später ausgestellte Token nur eine Teilmenge der ursprünglich angeforderten Berechtigungen enthalten. +Um auf neu gewährte Berechtigungen zuzugreifen, die nicht Teil der ursprünglichen Anfrage waren, muss der Client einen neuen Autorisierungsablauf durchführen. +::: + +#### Reduzierte Berechtigungen \{#downscoped-permissions} + +Wenn ein Benutzer Berechtigungen verliert: + +- Neu ausgestellte Tokens spiegeln die reduzierten Berechtigungen sofort wider. +- Bestehende JWTs behalten die alten Berechtigungen, bis sie ablaufen. +- Deine API sollte immer die Berechtigungen validieren und sich auf kurze Token-Laufzeiten verlassen. + +Wenn du schnellere Reaktionen benötigst, implementiere ein eigenes Signal, das den Clients mitteilt, ihre Tokens zu aktualisieren. + +#### Erweiterte Berechtigungen \{#enlarged-permissions} + +{props.type === "global" &&

Für globale API-Ressourcen werden erweiterte Berechtigungen, wenn ein Benutzer neue Berechtigungen erhält, NICHT durch Aktualisierung (Refresh) sichtbar. Der Client muss einen neuen OAuth-Autorisierungsablauf durchführen, um ein Token zu erhalten, das die neuen Berechtigungen enthält. Dies kann still erfolgen, wenn der Benutzer eine aktive Logto-Sitzung hat.

} + +{props.type === "organization" &&

Für Organisationstokens werden erweiterte Berechtigungen, wenn ein Benutzer neue Berechtigungen erhält, bei der nächsten Ausstellung (Refresh oder Token-Anfrage) sichtbar. Ein neues Token ist weiterhin erforderlich, aber eine vollständige erneute Authentifizierung ist nicht nötig, es sei denn, die neuen Berechtigungen überschreiten die ursprünglich angeforderte Menge.

} + +#### Empfehlungen \{#recommendations} + +- Validiere die Berechtigungen bei jedem API-Aufruf. +- Halte die Token-Gültigkeit kurz. +- Füge optionale Benachrichtigungen hinzu, wenn du eine sofortige Verbreitung von Berechtigungsänderungen benötigst. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/de/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 132b4e78e30..465cc508a19 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -30,8 +31,8 @@ Logto ermöglicht es dir, diese APIs mit OAuth 2.1 in Kombination mit flexibler, ## So funktioniert es in Logto \{#how-it-works-in-logto} - **API-Ressourcen und Berechtigungen werden global registriert:** Jede API, die du schützen möchtest, wird mit einem eindeutigen Ressourcenindikator (URI) und einem Satz von Berechtigungen (Scopes) definiert, die den Zugriff steuern. -- **Der Zugriff wird durch globale Rollen gesteuert:** Du kannst Berechtigungen Rollen zuweisen, die dann Benutzern oder Clients zugeordnet werden. -- **Getrennt von organisationsbezogenen Berechtigungen:** Globale API-Ressourcen haben keinen Organisationskontext. Sie können jedoch zusammen mit Organisationsrollen verwendet werden, um bei Bedarf eine zusätzliche Kontextebene bereitzustellen. Um organisationsbezogene APIs zu schützen, siehe [Organisationsbezogene API-Ressourcen schützen](/authorization/organization-level-api-resources). +- **Der Zugriff wird durch globale Rollen gesteuert:** Du kannst Berechtigungen Rollen zuweisen, die dann Benutzern oder Clients zugewiesen werden. +- **Getrennt von organisationsbezogenen Berechtigungen:** Globale API-Ressourcen haben keinen Organisationskontext. Sie können jedoch in Verbindung mit Organisationsrollen verwendet werden, um bei Bedarf eine zusätzliche Kontextebene bereitzustellen. Um organisationsbezogene APIs zu schützen, siehe [Organisationsbezogene API-Ressourcen schützen](/authorization/organization-level-api-resources). Globale API-Ressourcen RBAC @@ -50,7 +51,7 @@ Logto modelliert API-Ressourcen gemäß [RFC 8707: Resource Indicators for OAuth **Wichtige Punkte** - Ressourcenindikatoren müssen absolute URIs sein (z. B. `https://api.example.com`) -- Kein Fragmentbestandteil; vermeide nach Möglichkeit Query-Strings. +- Kein Fragmentbestandteil; vermeide nach Möglichkeit die Verwendung von Query-Strings. - Ressourcenindikatoren ermöglichen zielgruppenbeschränkte Tokens und unterstützen Multi-API-Architekturen. **Beispiel** @@ -60,9 +61,9 @@ Logto modelliert API-Ressourcen gemäß [RFC 8707: Resource Indicators for OAuth ### Autorisierungsfluss: Authentifizierung und Absicherung deiner API \{#authorization-flow-authenticating-and-securing-your-api} -Der folgende Ablauf gilt sowohl für interaktive Benutzer-Authentifizierung (Browser/App) als auch für Backend-Maschine-zu-Maschine (M2M)-Szenarien. +Der folgende Ablauf gilt sowohl für interaktive Benutzer-Authentifizierung (Browser / App) als auch für Backend-Maschine-zu-Maschine (M2M)-Szenarien. -Beachte, dass der Ablauf nicht alle Details zu erforderlichen Parametern oder Headern enthält, sondern sich auf die wichtigsten Schritte konzentriert. Lies weiter, um zu sehen, wie der Ablauf in der Praxis funktioniert. +Beachte, dass der Ablauf nicht alle erforderlichen Parameter oder Header im Detail enthält, sondern sich auf die wichtigsten Schritte konzentriert. Lies weiter, um zu sehen, wie der Ablauf in der Praxis funktioniert. ```mermaid sequenceDiagram @@ -96,13 +97,13 @@ sequenceDiagram end ``` -_Benutzer-Authentifizierung = Browser/App. M2M = Backend-Dienst oder Skript mit Client-Credentials._ +_Benutzer-Authentifizierung = Browser / App. M2M = Backend-Dienst oder Skript mit Client-Credentials._ :::note Der `resource`-Parameter muss exakt mit dem in Logto registrierten API-Identifier (Ressourcenindikator) übereinstimmen. ::: -## Implementierungsschritte \{#implementation-steps} +## Umsetzungsschritte \{#implementation-steps} ### Registriere deine API-Ressourcen \{#register-your-api-resources} @@ -139,23 +140,23 @@ Details zu jedem SDK findest du in den [Schnellstarts](/quick-starts). -Beim Konfigurieren deines OAuth 2.0-Clients oder beim Initialisieren des Authorization Code Flows stelle sicher, dass du den `resource`-Parameter und die gewünschten Scopes in der Autorisierungsanfrage einfügst. +Beim Konfigurieren deines OAuth 2.0-Clients oder beim Initialisieren des Authorization Code Flows stelle sicher, dass du den `resource`-Parameter und die gewünschten Scopes in der Autorisierungsanfrage einschließt. -Einige Bibliotheken unterstützen den `resource`-Parameter nicht nativ, erlauben aber in der Regel das Hinzufügen zusätzlicher Parameter zur Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. +Einige Bibliotheken unterstützen den `resource`-Parameter nicht nativ, erlauben aber in der Regel das Übergeben zusätzlicher Parameter in der Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. Hier ein nicht-normatives Beispiel für die Autorisierungsanfrage mit den Parametern `resource` und `scope`: -Nach erfolgreicher Authentifizierung erhältst du einen Authorization Code. Tausche diesen Code gegen ein Zugangstoken, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst und den `resource`-Parameter im Anfragekörper angibst. +Nach erfolgreicher Authentifizierung erhältst du einen Authorization Code. Tausche diesen Code gegen ein Zugangstoken aus, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst und den `resource`-Parameter im Request-Body einschließt. -Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ authorization_code: +Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ Authorization Code: -Du kannst auch den Grant-Typ `refresh_token` verwenden, um ohne Benutzerinteraktion ein neues Zugangstoken zu erhalten, solange der `resource`-Parameter in der Anfrage enthalten ist. +Du kannst auch den Grant-Typ `refresh_token` verwenden, um ein neues Zugangstoken ohne Benutzerinteraktion zu erhalten, solange der `resource`-Parameter in der Anfrage enthalten ist. -Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ refresh_token: +Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ Auffrischungstoken: @@ -171,7 +172,7 @@ Es gibt zwei wichtige Parameter, die in der Anfrage enthalten sein müssen: - `resource`: Die URI des Ressourcenindikators der API, auf die du zugreifen möchtest (z. B. `https://api.yourapp.com`). - `scope`: Die Berechtigungen, die du für die API anfordern möchtest (z. B. `read:products write:products`). -Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ client_credentials: +Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ Client-Credentials: ## Best Practices und Sicherheitstipps \{#best-practices-and-security-tips} - **Berechtigungen geschäftsorientiert halten:** Verwende klare Namen, die echten Aktionen entsprechen. -- **Token-Ablauf kurz halten:** Reduziert das Risiko bei Token-Leakage. +- **Token-Ablauf kurz halten:** Reduziert das Risiko bei einem Token-Leak. - **Vergebene Scopes begrenzen:** Gib Tokens nur die Berechtigungen, die sie tatsächlich benötigen. - **Zielgruppenbeschränkung nutzen:** Überprüfe immer den `aud`-Anspruch, um Missbrauch zu verhindern. @@ -227,9 +224,9 @@ Lege eine Standard-API-Ressource in der Logto-Konsole fest. Tokens verwenden die Überprüfe die folgenden häufigen Probleme: -- **Token-Signatur**: Stelle sicher, dass dein Backend die korrekten JWKs von Logto abruft +- **Token-Signatur**: Stelle sicher, dass dein Backend die richtigen JWKs von Logto abruft - **Token-Ablauf**: Stelle sicher, dass das Token nicht abgelaufen ist (`exp`-Anspruch) -- **Zielgruppe**: Prüfe, ob der `aud`-Anspruch mit deinem registrierten API-Ressourcenindikator übereinstimmt +- **Zielgruppe**: Prüfe, dass der `aud`-Anspruch mit deinem registrierten API-Ressourcenindikator übereinstimmt - **Erforderliche Scopes**: Stelle sicher, dass das Token die notwendigen Berechtigungen im `scope`-Anspruch enthält @@ -270,12 +267,12 @@ scopes: ["read:elections", "write:elections"] Das funktioniert **NICHT**: ```swift -scopes: ["read", "write"] // ❌ Stimmt nicht mit den Berechtigungsnamen überein +scopes: ["read", "write"] // ❌ Entspricht nicht den Berechtigungsnamen ``` -## Weiterführende Literatur \{#further-reading} +## Weiterführende Informationen \{#further-reading} Zugangstokens validieren diff --git a/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index e85609d4fb0..b9e39f14520 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -16,28 +17,28 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md export const resource = 'https://api.your-app.com/organizations'; -Kombiniere API-Ressourcen mit der Organisationstemplate, um den Zugriff auf APIs und Daten innerhalb jeder Organisation zu beschränken und so eine Mandantenisolation in deinem SaaS sicherzustellen. +Kombiniere API-Ressourcen mit der Organisationstemplate, um den Zugriff auf APIs und Daten innerhalb jeder Organisation einzuschränken und so eine Mandantenisolation in deinem SaaS zu gewährleisten. ## Was sind API-Ressourcen auf Organisationsebene? \{#what-are-organization-level-api-resources} API-Ressourcen auf Organisationsebene sind Endpunkte oder Dienste in deiner Anwendung, die **auf eine bestimmte Organisation beschränkt** sind. Diese APIs erzwingen Autorisierung und Zugriff basierend auf dem Organisationskontext – so wird sichergestellt, dass Benutzer oder Clients nur auf Daten und Aktionen zugreifen, die für ihre Organisation relevant sind. -**Anwendungsfälle umfassen** +**Anwendungsfälle sind unter anderem** - APIs zur Verwaltung von Organisationsmitgliedern, Rollen oder Einstellungen (z. B. `/organizations/{organizationId}/members`) -- Organisationsbezogene Dashboards, Analysen oder Berichte +- Organisationsspezifische Dashboards, Analysen oder Berichte - Abrechnungs-, Abonnement- oder Audit-Endpunkte, die an eine Organisation gebunden sind - Jede API, bei der Aktionen und Daten pro Mandant isoliert sind Logto ermöglicht es dir, diese Organisations-APIs mit OAuth 2.1 und rollenbasierter Zugangskontrolle (RBAC) abzusichern und unterstützt dabei Multi-Tenant-SaaS-Architekturen. -Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der [Organisationstemplate](/authorization/organization-template) definiert sind. Jede Organisation verwendet die gleiche Vorlage, was ein konsistentes Berechtigungsmodell über alle Organisationen hinweg gewährleistet. +Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der [Organisationstemplate](/authorization/organization-template) definiert sind. Jede Organisation verwendet die gleiche Vorlage, was ein konsistentes Berechtigungsmodell für alle Organisationen gewährleistet. ## So funktioniert es in Logto \{#how-it-works-in-logto} -- **API-Ressourcen und Berechtigungen werden global registriert:** Jede API-Ressource wird mit einem eindeutigen Ressourcenindikator (URI) und einem Satz von Berechtigungen (Scopes) in Logto definiert. +- **API-Ressourcen und Berechtigungen werden global registriert:** Jede API-Ressource wird mit einem eindeutigen Ressourcenindikator (URI) und einer Reihe von Berechtigungen (Scopes) in Logto definiert. - **Rollen auf Organisationsebene:** Organisationsrollen werden in der Organisationstemplate definiert. API-Ressourcenberechtigungen (Scopes) werden den Organisationsrollen zugewiesen, die dann Benutzern oder Clients **innerhalb jeder Organisation** zugewiesen werden. -- **Kontextbewusste Autorisierung:** Wenn ein Client ein Zugangstoken mit sowohl einer API-Ressource als auch einer `organization_id` anfordert, stellt Logto ein Token aus, das sowohl den Organisationskontext als auch die API-Zielgruppe enthält. Die Berechtigungen (Scopes) des Tokens werden durch die Organisationsrollen des Benutzers für die angegebene Organisation bestimmt. +- **Kontextbezogene Autorisierung:** Wenn ein Client ein Zugangstoken sowohl mit einer API-Ressource als auch einer `organization_id` anfordert, stellt Logto ein Token aus, das sowohl den Organisationskontext als auch die API-Zielgruppe enthält. Die Berechtigungen (Scopes) des Tokens werden durch die Organisationsrollen des Benutzers für die angegebene Organisation bestimmt. - **Trennung von globalen Ressourcen:** API-Ressourcen können mit oder ohne Organisationskontext aufgerufen werden. Organisation RBAC wird nur angewendet, wenn eine `organization_id` in der Anfrage enthalten ist. Für APIs, die für alle Benutzer freigegeben sind, siehe [Globale API-Ressourcen schützen](/authorization/global-api-resources). Organisationsebene API-Ressourcen RBAC @@ -54,7 +55,7 @@ Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der - Wenn du ein Zugangstoken **ohne** eine `organization_id` anforderst, werden nur globale Rollen / Berechtigungen berücksichtigt. - Wenn du ein Zugangstoken **mit** einer `organization_id` anforderst, bewertet Logto die Organisationsrollen des Benutzers und deren zugehörige Berechtigungen für diese Organisation. -- Das resultierende JWT enthält sowohl die API-Zielgruppe (`aud` Anspruch) als auch den Organisationskontext (`organization_id` Anspruch), wobei die Scopes auf diejenigen gefiltert werden, die durch die Organisationsrollen des Benutzers gewährt werden. +- Das resultierende JWT enthält sowohl die API-Zielgruppe (`aud` Anspruch) als auch den Organisationskontext (`organization_id` Anspruch), wobei die Scopes auf die durch die Organisationsrollen des Benutzers gewährten Berechtigungen gefiltert werden. ### Autorisierungsablauf: Authentifizierung und Absicherung von APIs mit Organisationskontext \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} @@ -92,7 +93,7 @@ sequenceDiagram _Benutzer-Authentifizierung = Browser / App. M2M = Backend-Service oder Skript mit Client-Credentials + Organisationskontext._ -## Implementierungsschritte \{#implementation-steps} +## Umsetzungsschritte \{#implementation-steps} ### Registriere deine API-Ressource \{#register-your-api-resource} @@ -111,16 +112,16 @@ Für vollständige Konfigurationsschritte siehe [Organisationsrollen verwenden]( ### Organisationstokens für API-Ressourcen erhalten \{#obtain-organization-tokens-for-api-resources} -Dein Client / deine App sollte ein Token mit sowohl `resource` als auch `organization_id` anfordern, um auf APIs auf Organisationsebene zuzugreifen. Logto stellt Organisationstokens als [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) aus. Du kannst diese entweder über den [Auffrischungstoken-Flow](https://auth.wiki/refresh-token) oder den [Client-Credentials-Flow](https://auth.wiki/client-credentials-flow) erhalten. +Dein Client / deine App sollte ein Token sowohl mit `resource` als auch mit `organization_id` anfordern, um auf APIs auf Organisationsebene zuzugreifen. Logto stellt Organisationstokens als [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) aus. Du kannst diese entweder über den [Auffrischungstoken-Flow](https://auth.wiki/refresh-token) oder den [Client-Credentials-Flow](https://auth.wiki/client-credentials-flow) erhalten. #### Auffrischungstoken-Flow \{#refresh-token-flow} -Fast alle offiziellen Logto SDKs unterstützen das Abrufen von Organisationstokens über den Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann ebenfalls verwendet werden, um diesen Flow zu implementieren. +Fast alle offiziellen Logto SDKs unterstützen das Abrufen von Organisationstokens mit dem Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann ebenfalls verwendet werden, um diesen Flow zu implementieren. -Beim Initialisieren des Logto SDK füge `urn:logto:scope:organizations` und die gewünschten Organisationsberechtigungen (Scopes) zum `scopes`-Parameter hinzu. +Beim Initialisieren des Logto SDK füge `urn:logto:scope:organizations` und die gewünschten Organisationsberechtigungen (Scopes) zum Parameter `scopes` hinzu. Einige Logto SDKs haben einen vordefinierten Scope für Organisationen, wie z. B. `UserScope.Organizations` in JavaScript SDKs. @@ -128,17 +129,17 @@ Einige Logto SDKs haben einen vordefinierten Scope für Organisationen, wie z. B Beim Aufruf von `getAccessToken()` gib sowohl die API-Ressource (`resource`) als auch die Organisations-ID (`organizationId`) an, um ein Organisationstoken zu erhalten. -Für Details zu jedem SDK siehe [Quick starts](/quick-starts). +Für Details zu jedem SDK siehe [Schnellstarts](/quick-starts). - + Beim Konfigurieren deines OAuth 2.0 Clients oder beim Initialisieren des Authorization-Code-Flows stelle sicher, dass du folgende Parameter einschließt: -- `resource`: Setze dies auf den in Logto registrierten API-Ressourcenbezeichner (z. B. `https://api.your-app.com/organizations`). +- `resource`: Setze dies auf den in Logto registrierten API-Ressourcen-Identifier (z. B. `https://api.your-app.com/organizations`). - `scope`: Füge den vordefinierten Organisationsscope (`urn:logto:scope:organizations`), `offline_access` (um Auffrischungstokens zu erhalten) und alle spezifischen API-Berechtigungen hinzu, die du benötigst (z. B. `manage:members view:analytics`). -Einige Bibliotheken unterstützen den `resource`-Parameter nicht nativ, erlauben aber in der Regel das Übergeben zusätzlicher Parameter in der Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. +Einige Bibliotheken unterstützen den Parameter `resource` nicht nativ, erlauben aber in der Regel das Übergeben zusätzlicher Parameter in der Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. Hier ist ein nicht-normatives Beispiel, wie die Autorisierungsanfrage aussehen könnte: @@ -147,7 +148,7 @@ Hier ist ein nicht-normatives Beispiel, wie die Autorisierungsanfrage aussehen k scope="urn:logto:scope:organizations invite:member manage:billing" /> -Sobald der Benutzer authentifiziert ist, erhältst du einen Authorization-Code. Verwende diesen Code, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. +Sobald der Benutzer authentifiziert ist, erhältst du einen Autorisierungscode. Verwende diesen Code, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. Hier ist ein nicht-normatives Beispiel für die Token-Anfrage: @@ -159,11 +160,11 @@ Du erhältst ein Auffrischungstoken, das verwendet werden kann, um Organisations -Verwende schließlich das Auffrischungstoken, um ein Organisationstoken zu erhalten, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. Denke daran, Folgendes einzuschließen: +Verwende abschließend das Auffrischungstoken, um ein Organisationstoken zu erhalten, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. Denke daran, Folgendes einzuschließen: -- Den `resource`-Parameter, gesetzt auf den API-Ressourcenbezeichner (z. B. `https://api.yourapp.com/org`). -- Den `organization_id`-Parameter, gesetzt auf die gewünschte Organisations-ID. -- (Optional) Den `scope`-Parameter, um die benötigten Berechtigungen weiter einzuschränken (z. B. `manage:members view:reports`). +- Den Parameter `resource`, gesetzt auf den API-Ressourcen-Identifier (z. B. `https://api.yourapp.com/org`). +- Den Parameter `organization_id`, gesetzt auf die gewünschte Organisations-ID. +- (Optional) Den Parameter `scope`, um die benötigten Berechtigungen weiter einzuschränken (z. B. `manage:members view:reports`). Hier ist ein nicht-normatives Beispiel, wie die Token-Anfrage aussehen könnte: @@ -182,11 +183,11 @@ Für Maschine-zu-Maschine (M2M)-Szenarien kannst du den Client-Credentials-Flow Hier sind die wichtigsten Parameter, die in der Anfrage enthalten sein sollten: -- `resource`: Der API-Ressourcenbezeichner (z. B. `https://api.yourapp.com/org`). +- `resource`: Der API-Ressourcen-Identifier (z. B. `https://api.yourapp.com/org`). - `organization_id`: Die ID der Organisation, für die du das Token möchtest. -- `scope`: Die API-Ressourcenberechtigungen auf Organisationsebene, die du anfordern möchtest (z. B. `invite:member`, `manage:billing`). +- `scope`: Die gewünschten API-Ressourcenberechtigungen auf Organisationsebene (z. B. `invite:member`, `manage:billing`). -Hier ist ein nicht-normatives Beispiel für die Token-Anfrage mit dem Client-Credentials-Grant-Typ: +Hier ist ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Type Client-Credentials: + ## Best Practices und Sicherheitstipps \{#best-practices-and-security-tips} -- **Validiere immer den Organisationskontext:** Vertraue nicht nur dem Token; prüfe den `organization_id`-Anspruch bei jedem organisationsbezogenen API-Aufruf. -- **Verwende Zielgruppenbeschränkungen:** Prüfe immer den `aud`-Anspruch, um sicherzustellen, dass das Token für die beabsichtigte Organisation bestimmt ist. -- **Halte Berechtigungen geschäftsgetrieben:** Verwende klare Namen, die echten Aktionen entsprechen; gewähre nur das, was für jede Organisationsrolle benötigt wird. -- **Trenne API- und Nicht-API-Berechtigungen**, wo möglich (aber beide können in einer Rolle enthalten sein). +- **Validiere immer den Organisationskontext:** Vertraue nicht nur auf das Token; prüfe den `organization_id` Anspruch bei jedem organisationsbezogenen API-Aufruf. +- **Verwende Zielgruppenbeschränkungen:** Prüfe immer den `aud` Anspruch, um sicherzustellen, dass das Token für die beabsichtigte Organisation bestimmt ist. +- **Halte Berechtigungen geschäftsorientiert:** Verwende klare Namen, die echten Aktionen entsprechen; gewähre nur das, was für jede Organisationsrolle benötigt wird. +- **Trenne API- und Nicht-API-Berechtigungen**, wo möglich (beides kann aber in einer Rolle enthalten sein). - **Halte Token-Lebensdauern kurz:** Reduziert das Risiko, falls ein Token kompromittiert wird. -- **Überprüfe regelmäßig deine Organisationstemplate:** Aktualisiere Rollen und Berechtigungen, während sich dein Produkt weiterentwickelt. +- **Überprüfe regelmäßig deine Organisationstemplate:** Aktualisiere Rollen und Berechtigungen, wenn sich dein Produkt weiterentwickelt. ## FAQs \{#faqs} @@ -235,7 +238,7 @@ Es werden nur globale Rollen / Berechtigungen ausgewertet. Organisation RBAC wir
-### Kann ich Organisations- und Nicht-Organisationsberechtigungen in einer Rolle mischen? \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} +### Kann ich Organisations- und Nicht-Organisationsberechtigungen in einer einzigen Rolle mischen? \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index f1232d42b92..9dccac883e2 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -18,20 +19,20 @@ Verwende die Organisation-Vorlage, um organisationsweite Rollen und Berechtigung ## Was sind Organisation (Nicht-API) Berechtigungen? \{#what-are-organization-non-api-permissions} -Organisationsberechtigungen (Nicht-API) steuern, was Benutzer **im Kontext einer Organisation** tun können, werden aber **nicht auf API-Ebene durchgesetzt**. Stattdessen regeln sie den Zugriff auf App-Funktionen, UI-Elemente, Workflows oder Geschäftsaktionen und nicht auf Backend-APIs. +Organisationsberechtigungen (Nicht-API) steuern, was Benutzer **im Kontext einer Organisation** tun können, werden aber **nicht auf API-Ebene durchgesetzt**. Stattdessen regeln sie den Zugriff auf App-Funktionen, UI-Elemente, Workflows oder Geschäftsaktionen, nicht auf Backend-APIs. **Anwendungsfälle sind unter anderem** -- Mitglieder innerhalb einer Organisation einladen oder verwalten -- Organisationsrollen zuweisen oder ändern -- Abrechnung, Einstellungen oder administrative Funktionen für eine Organisation verwalten +- Einladen oder Verwalten von Mitgliedern innerhalb einer Organisation +- Zuweisen oder Ändern von Organisationsrollen +- Verwaltung von Abrechnung, Einstellungen oder administrativen Funktionen für eine Organisation - Zugriff auf Dashboards, Analysen oder interne Tools, die keine API-Endpunkte haben Logto ermöglicht es dir, diese Organisationsberechtigungen mit OAuth 2.1 und rollenbasierter Zugangskontrolle (RBAC) abzusichern und unterstützt dabei Multi-Tenant-SaaS-Architekturen. -Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der [Organisation-Vorlage](/authorization/organization-template) definiert sind. Jede Organisation verwendet die gleiche Vorlage, was ein konsistentes Berechtigungsmodell über alle Organisationen hinweg sicherstellt. +Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der [Organisation-Vorlage](/authorization/organization-template) definiert sind. Jede Organisation verwendet die gleiche Vorlage, was ein konsistentes Berechtigungsmodell für alle Organisationen sicherstellt. -## So funktioniert es in Logto \{#how-it-works-in-logto} +## Wie funktioniert es in Logto \{#how-it-works-in-logto} - **Organisationsebene RBAC:** Rollen und Berechtigungen werden in der Organisation-Vorlage definiert. Wenn ein Benutzer einer Organisation beitritt, werden ihm eine oder mehrere Rollen zugewiesen, die bestimmte Berechtigungen gewähren. - **Nicht-API-Durchsetzung:** Berechtigungen werden in der UI deiner App, im Workflow oder in der Backend-Logik geprüft und durchgesetzt, nicht zwingend durch ein API-Gateway. @@ -50,7 +51,7 @@ Diese Berechtigungen werden über **Organisationsrollen** verwaltet, die in der 1. **Definiere Organisationsberechtigungen** in Logto unter der Organisation-Vorlage. 2. **Erstelle Organisationsrollen**, die die notwendigen Berechtigungen für deine organisationsspezifischen Aktionen bündeln. 3. **Weise Rollen** Benutzern oder Clients innerhalb jeder Organisation zu. -4. **Erhalte ein Organisationstoken (JWT)** für die aktuelle Organisation entweder über das Auffrischungstoken oder den Client-Credentials-Flow. +4. **Erhalte ein Organisationstoken (JWT)** für die aktuelle Organisation, entweder über das Auffrischungstoken oder den Client-Credentials-Flow. 5. **Validiere Zugangstokens** in der UI oder im Backend deiner App, um Organisationsberechtigungen durchzusetzen. ### Autorisierungsablauf: Authentifizierung und Absicherung von Organisationsberechtigungen \{#authorization-flow-authenticating-and-securing-organization-permissions} @@ -71,9 +72,9 @@ sequenceDiagram Logto->>Client: Leitet zurück mit `authorization_code` Client->>Logto: POST /oidc/token mit `grant_type=authorization_code` Logto->>Client: Gibt Auffrischungstoken zurück - Client->>Logto: POST /oidc/token mit `grant_type=refresh_token` + Organisationsparameter + Client->>Logto: POST /oidc/token mit `grant_type=refresh_token` + Organisationsparametern else M2M-Client-Authentifizierung - Client->>Logto: POST /oidc/token mit `grant_type=client_credentials` + Organisationsparameter + Client->>Logto: POST /oidc/token mit `grant_type=client_credentials` + Organisationsparametern end Logto->>Client: Gibt Organisationstoken (JWT) zurück @@ -89,7 +90,7 @@ sequenceDiagram _Benutzer-Authentifizierung = Browser/App. M2M = Backend-Service oder Skript mit Client-Credentials + Organisationskontext._ -## Implementierungsschritte \{#implementation-steps} +## Umsetzungsschritte \{#implementation-steps} ### Organisationsberechtigungen registrieren \{#register-organization-permissions} @@ -112,12 +113,12 @@ Dein Client/App sollte ein Organisationstoken (Nicht-API) erhalten, um auf Organ #### Auffrischungstoken-Flow \{#refresh-token-flow} -Fast alle offiziellen Logto SDKs unterstützen das Abrufen von Organisationstokens über den Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Client-Bibliothek kann ebenfalls verwendet werden, um diesen Flow zu implementieren. +Fast alle offiziellen Logto SDKs unterstützen das Erhalten von Organisationstokens über den Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann ebenfalls für diesen Flow verwendet werden. -Beim Initialisieren des Logto SDK füge `urn:logto:scope:organizations` und die gewünschten Organisationsberechtigungen (Berechtigungen) zum `scopes`-Parameter hinzu. +Beim Initialisieren des Logto SDK füge `urn:logto:scope:organizations` und die gewünschten Organisationsberechtigungen (Scopes) zum `scopes`-Parameter hinzu. Einige Logto SDKs haben einen vordefinierten Scope für Organisationen, wie `UserScope.Organizations` in JavaScript SDKs. @@ -125,19 +126,19 @@ Einige Logto SDKs haben einen vordefinierten Scope für Organisationen, wie `Use Verwende `getOrganizationToken` oder eine ähnliche Methode (wie `getAccessToken` mit einer Organisations-ID), um ein Organisationstoken für eine bestimmte Organisation anzufordern. -Für Details zu jedem SDK siehe [Quick starts](/quick-starts). +Für Details zu jedem SDK siehe [Quick Starts](/quick-starts). - + -Beim Konfigurieren deines OAuth 2.0 Clients oder beim Initialisieren des Authorization-Code-Flows stelle sicher, dass du folgende Parameter einfügst: +Beim Konfigurieren deines OAuth 2.0 Clients oder beim Initialisieren des Authorization-Code-Flows stelle sicher, dass du folgende Parameter einschließt: - `resource`: Setze auf `urn:logto:resource:organizations`, um anzugeben, dass du ein Organisationstoken möchtest. -- `scope`: Füge den vordefinierten Organisation-Scope (`urn:logto:scope:organizations`), `offline_access` (um Auffrischungstokens zu erhalten) und alle spezifischen Organisationsberechtigungen hinzu, die du benötigst (z. B. `invite:member`, `manage:billing`). +- `scope`: Füge den vordefinierten Organisationsscope (`urn:logto:scope:organizations`), `offline_access` (um Auffrischungstokens zu erhalten) und alle spezifischen Organisationsberechtigungen hinzu, die du benötigst (z. B. `invite:member`, `manage:billing`). -Einige Bibliotheken unterstützen den `resource`-Parameter nicht nativ, erlauben aber in der Regel das Übergeben zusätzlicher Parameter in der Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. +Einige Bibliotheken unterstützen den `resource`-Parameter nicht nativ, erlauben aber meist das Übergeben zusätzlicher Parameter in der Autorisierungsanfrage. Prüfe die Dokumentation deiner Bibliothek für Details. -Hier ist ein nicht-normatives Beispiel, wie die Autorisierungsanfrage aussehen könnte: +Hier ein nicht-normatives Beispiel, wie die Autorisierungsanfrage aussehen könnte: @@ -156,12 +157,12 @@ Du erhältst ein Auffrischungstoken, das verwendet werden kann, um Organisations -Verwende schließlich das Auffrischungstoken, um ein Organisationstoken zu erhalten, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. Denke daran, Folgendes einzuschließen: +Verwende abschließend das Auffrischungstoken, um ein Organisationstoken zu erhalten, indem du eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt stellst. Denke daran, Folgendes einzuschließen: - Den `organization_id`-Parameter, gesetzt auf die gewünschte Organisations-ID. - (Optional) Den `scope`-Parameter, um die benötigten Berechtigungen weiter einzuschränken (z. B. `manage:members view:reports`). -Hier ist ein nicht-normatives Beispiel, wie die Token-Anfrage aussehen könnte: +Hier ein nicht-normatives Beispiel, wie die Token-Anfrage aussehen könnte: @@ -170,14 +171,14 @@ Hier ist ein nicht-normatives Beispiel, wie die Token-Anfrage aussehen könnte: #### Client-Credentials-Flow \{#client-credentials-flow} -Für Maschine-zu-Maschine (M2M)-Szenarien kannst du den Client-Credentials-Flow verwenden, um ein Zugangstoken für Organisationsberechtigungen zu erhalten. Durch eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt mit Organisationsparametern kannst du ein Organisationstoken mit deiner Client-ID und deinem Secret anfordern. +Für Maschine-zu-Maschine (M2M) Szenarien kannst du den Client-Credentials-Flow verwenden, um ein Zugangstoken für Organisationsberechtigungen zu erhalten. Durch eine POST-Anfrage an Logtos `/oidc/token`-Endpunkt mit Organisationsparametern kannst du ein Organisationstoken mit deiner Client-ID und deinem Secret anfordern. -Hier sind die wichtigsten Parameter, die in der Anfrage enthalten sein sollten: +Hier sind die wichtigsten Parameter, die du in die Anfrage aufnehmen solltest: - `organization_id`: Die ID der Organisation, für die du das Token möchtest. - `scope`: Die Organisationsberechtigungen, die du anfordern möchtest (z. B. `invite:member`, `manage:billing`). -Hier ist ein nicht-normatives Beispiel für die Token-Anfrage mit dem Client-Credentials-Grant-Typ: +Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Client-Credentials-Grant-Typ: + ## Best Practices und Sicherheitstipps \{#best-practices-and-security-tips} -- **Verlasse dich niemals ausschließlich auf die UI-Durchsetzung:** Prüfe Berechtigungen für kritische Aktionen immer auch im Backend. +- **Verlasse dich niemals nur auf die UI-Durchsetzung:** Prüfe Berechtigungen für kritische Aktionen immer auch im Backend. - **Verwende Zielgruppenbeschränkungen:** Prüfe immer den `aud`-Anspruch, um sicherzustellen, dass das Token für die beabsichtigte Organisation ist. - **Halte Berechtigungen geschäftsgetrieben:** Verwende klare Namen, die echten Aktionen entsprechen; gewähre nur das, was für jede Organisationsrolle benötigt wird. -- **Trenne API- und Nicht-API-Berechtigungen**, wo möglich (beide können aber in einer Rolle enthalten sein). -- **Überprüfe die Organisation-Vorlage regelmäßig**, während sich dein Produkt weiterentwickelt. +- **Trenne API- und Nicht-API-Berechtigungen** wo möglich (beide können aber in einer Rolle enthalten sein). +- **Überprüfe die Organisation-Vorlage regelmäßig**, wenn sich dein Produkt weiterentwickelt. ## FAQs \{#faqs} diff --git a/i18n/es/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/es/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..ccb019ac9f8 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### Opcional: Manejar el cambio de permisos de usuario \{#optional-handle-user-permission-change} + +Los permisos de usuario pueden cambiar en cualquier momento. Debido a que Logto emite JWTs para RBAC, las actualizaciones de permisos solo aparecen en los tokens emitidos recientemente y nunca modifican los JWTs existentes. + +:::info Regla de subconjunto de alcances (Scope subset rule) +Un token de acceso solo puede incluir alcances que fueron solicitados en el flujo de autorización OAuth original. +Incluso si un usuario obtiene nuevos permisos, el token emitido posteriormente solo puede contener un subconjunto de los alcances solicitados originalmente. +Para acceder a los nuevos alcances concedidos que no formaban parte de la solicitud inicial, el cliente debe ejecutar un nuevo flujo de autorización. +::: + +#### Permisos reducidos (Downscoped permissions) \{#downscoped-permissions} + +Cuando un usuario pierde permisos: + +- Los tokens emitidos recientemente reflejan inmediatamente los alcances reducidos. +- Los JWTs existentes mantienen los antiguos alcances hasta que expiran. +- Tu API siempre debe validar los alcances y depender de tiempos de vida de token cortos. + +Si necesitas reacciones más rápidas, implementa tu propia señal que indique a los clientes que refresquen sus tokens. + +#### Permisos ampliados (Enlarged permissions) \{#enlarged-permissions} + +{props.type === "global" &&

Para recursos de API globales, cuando un usuario obtiene permisos, los permisos ampliados NO aparecerán mediante refresh. El cliente debe realizar un nuevo flujo de autorización OAuth para obtener un token que incluya los nuevos alcances. Esto puede suceder de forma silenciosa si el usuario tiene una sesión activa en Logto.

} + +{props.type === "organization" &&

Para tokens de organización, cuando un usuario obtiene permisos, los permisos ampliados aparecerán en la próxima emisión (refresh o solicitud de token). Aún se requiere un nuevo token, pero no es necesario un re-autenticación completa a menos que los nuevos alcances excedan el conjunto de la solicitud original.

} + +#### Recomendaciones \{#recommendations} + +- Valida los alcances en tu API en cada llamada. +- Mantén la expiración de los tokens corta. +- Añade notificaciones opcionales si necesitas una propagación inmediata de los cambios de permisos. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/es/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 115aab101d0..52aafbceb77 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,20 +6,21 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; -# Protege recursos globales de API +# Protege recursos de API globales export const resource = 'https://api.your-app.com'; -Protege las APIs de todo el producto utilizando el control de acceso basado en roles (RBAC) en Logto. Asigna roles y permisos globales para controlar el acceso de todos los usuarios y clientes en tu aplicación. +Protege las API de todo el producto utilizando el control de acceso basado en roles (RBAC) en Logto. Asigna roles y permisos globales para controlar el acceso de todos los usuarios y clientes en tu aplicación. -## ¿Qué son los recursos globales de API? \{#what-are-global-api-resources} +## ¿Qué son los recursos de API globales? \{#what-are-global-api-resources} -Los recursos globales de API son endpoints o servicios en tu aplicación que son accesibles para todos los usuarios, sin importar la organización o el inquilino. Normalmente, estos son APIs públicos, servicios centrales del producto o cualquier endpoint que no esté limitado a una organización específica. +Los recursos de API globales son endpoints o servicios en tu aplicación que son accesibles para todos los usuarios, sin importar la organización o el inquilino. Normalmente, estos son APIs públicos, servicios centrales del producto o cualquier endpoint que no esté limitado a una organización específica. -**Casos de uso incluyen** +**Los casos de uso incluyen** - APIs públicas o endpoints compartidos entre toda tu base de usuarios. - Microservicios que no están ligados a la multi-tenencia. @@ -31,9 +32,9 @@ Logto te permite asegurar estas APIs usando OAuth 2.1, combinado con un control - **Los recursos de API y permisos se registran globalmente:** Cada API que deseas proteger se define con un indicador de recurso único (URI) y un conjunto de permisos (alcances) que controlan el acceso. - **El acceso se controla mediante roles globales:** Puedes asignar permisos a roles, que luego se asignan a usuarios o clientes. -- **Separado de los permisos a nivel de organización:** Los recursos globales de API no tienen contexto de organización. Sin embargo, pueden usarse junto con roles de organización para proporcionar una capa adicional de contexto si es necesario. Para proteger APIs a nivel de organización, consulta [Proteger recursos de API a nivel de organización](/authorization/organization-level-api-resources). +- **Separado de los permisos a nivel de organización:** Los recursos de API globales no tienen contexto de organización. Sin embargo, pueden usarse junto con roles de organización para proporcionar una capa adicional de contexto si es necesario. Para proteger APIs a nivel de organización, consulta [Proteger recursos de API a nivel de organización](/authorization/organization-level-api-resources). -Recursos globales de API RBAC +Recursos de API globales RBAC ### Resumen de la implementación \{#implementation-overview} @@ -45,7 +46,7 @@ Logto te permite asegurar estas APIs usando OAuth 2.1, combinado con un control ### Entendiendo los indicadores de recurso \{#understanding-resource-indicators} -Logto modela los recursos de API según [RFC 8707: Indicadores de recurso para OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html). Un **indicador de recurso** es un URI que identifica de manera única la API o servicio objetivo solicitado. +Logto modela los recursos de API según [RFC 8707: Indicadores de recurso para OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html). Un **indicador de recurso** es un URI que identifica de forma única la API o servicio objetivo solicitado. **Puntos clave** @@ -89,9 +90,9 @@ sequenceDiagram Cliente->>API: Solicitud con token Bearer API->>API: Valida token de acceso - alt Token válido + alt El token es válido API->>Cliente: Devuelve datos del recurso protegido - else Token inválido + else El token no es válido API->>Cliente: 401 No autorizado end ``` @@ -109,7 +110,7 @@ El parámetro `resource` debe coincidir exactamente con el identificador de API 1. Ve a Consola → Recursos de API. 2. Crea un nuevo recurso de API (por ejemplo, `https://api.yourapp.com/org`) y define sus permisos (alcances). -Para ver todos los pasos de configuración, consulta [Definir recursos de API con permisos](/authorization/role-based-access-control#define-api-resources-with-permissions). +Para ver los pasos completos de configuración, consulta [Definir recursos de API con permisos](/authorization/role-based-access-control#define-api-resources-with-permissions). ### Configura roles globales \{#set-up-global-roles} @@ -117,22 +118,22 @@ Para ver todos los pasos de configuración, consulta [Definir recursos de API co 2. Crea roles que se correspondan con los permisos de tu API (por ejemplo, `read:products`, `write:products`). 3. Asigna estos roles a los usuarios o clientes que necesiten acceso a la API. -Para ver todos los pasos de configuración, consulta [Usar roles globales](/authorization/role-based-access-control#configure-global-roles). +Para ver los pasos completos de configuración, consulta [Usar roles globales](/authorization/role-based-access-control#configure-global-roles). -### Obtén tokens de acceso para recursos globales de API \{#obtain-access-tokens-for-global-api-resources} +### Obtén tokens de acceso para recursos de API globales \{#obtain-access-tokens-for-global-api-resources} -Antes de acceder a un recurso global de API, tu cliente debe obtener un token de acceso. Logto emite [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) como tokens de acceso para recursos globales de API. Esto normalmente se realiza usando el [flujo de código de autorización OAuth 2.0](https://auth.wiki/authorization-code-flow), [flujo de refresh token](https://auth.wiki/refresh-token), o el [flujo de client credentials](https://auth.wiki/client-credentials-flow). +Antes de acceder a un recurso de API global, tu cliente debe obtener un token de acceso. Logto emite [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) como tokens de acceso para recursos de API globales. Esto normalmente se realiza usando el [flujo de código de autorización OAuth 2.0](https://auth.wiki/authorization-code-flow), [flujo de refresh token](https://auth.wiki/refresh-token) o el [flujo de client credentials](https://auth.wiki/client-credentials-flow). #### Flujo de código de autorización o refresh token \{#authorization-code-or-refresh-token-flow} -Todos los SDK oficiales de Logto admiten la obtención de tokens de acceso para recursos globales de API usando el flujo de refresh token de forma predeterminada. También se puede usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. +Todos los SDK oficiales de Logto admiten la obtención de tokens de acceso para recursos de API globales usando el flujo de refresh token de forma predeterminada. También puedes usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. -Al inicializar el cliente de Logto, agrega el indicador de recurso al parámetro `resources` (array), luego agrega los permisos deseados (alcances) al parámetro `scopes`. +Al inicializar el cliente Logto, añade el indicador de recurso al parámetro `resources` (array), luego añade los permisos deseados (alcances) al parámetro `scopes`. -Una vez que el usuario esté autenticado, pasa el indicador de recurso en el parámetro `resource` o un parámetro de nombre similar al solicitar el token de acceso (por ejemplo, llamando a `getAccessToken()`). +Una vez que el usuario esté autenticado, pasa el indicador de recurso en el parámetro `resource` o en un parámetro de nombre similar al solicitar el token de acceso (por ejemplo, llamando a `getAccessToken()`). Para detalles sobre cada SDK, consulta los [Inicios rápidos](/quick-starts). @@ -141,7 +142,7 @@ Para detalles sobre cada SDK, consulta los [Inicios rápidos](/quick-starts). Al configurar tu cliente OAuth 2.0 o inicializar el flujo de código de autorización, asegúrate de incluir el parámetro `resource` y los alcances deseados en la solicitud de autorización. -Algunas bibliotecas pueden no admitir el parámetro `resource` de forma nativa, pero normalmente permiten pasar parámetros adicionales en la solicitud de autorización. Consulta la documentación de tu biblioteca para más detalles. +Algunas bibliotecas pueden no soportar el parámetro `resource` de forma nativa, pero normalmente permiten pasar parámetros adicionales en la solicitud de autorización. Consulta la documentación de tu biblioteca para más detalles. Aquí tienes un ejemplo no normativo de la solicitud de autorización con los parámetros `resource` y `scope`: @@ -149,13 +150,13 @@ Aquí tienes un ejemplo no normativo de la solicitud de autorización con los pa Una vez que el usuario esté autenticado, recibirás un authorization code. Intercambia este código por un token de acceso haciendo una solicitud POST al endpoint `/oidc/token` de Logto, incluyendo el parámetro `resource` en el cuerpo de la solicitud. -Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant type authorization_code: +Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant type authorization code: También puedes usar el grant type `refresh_token` para obtener un nuevo token de acceso sin interacción del usuario, siempre que el parámetro `resource` esté incluido en la solicitud. -Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant type refresh_token: +Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant type refresh token: @@ -164,7 +165,7 @@ Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant ty #### Flujo de client credentials \{#client-credentials-flow} -Para escenarios máquina a máquina (M2M), puedes usar el flujo de client credentials para obtener un token de acceso para tu recurso global de API. Haciendo una solicitud POST al endpoint `/oidc/token` de Logto, puedes solicitar un token de acceso usando tu client ID y secret. +Para escenarios máquina a máquina (M2M), puedes usar el flujo de client credentials para obtener un token de acceso para tu recurso de API global. Haciendo una solicitud POST al endpoint `/oidc/token` de Logto, puedes solicitar un token de acceso usando tu client ID y secret. Hay dos parámetros clave que debes incluir en la solicitud: @@ -182,21 +183,17 @@ Aquí tienes un ejemplo no normativo de la solicitud de token usando el grant ty Los JWT emitidos por Logto contienen reclamos que tu API puede usar para hacer cumplir la autorización. -Cuando tu API reciba una solicitud con un token de acceso emitido por Logto, debes: +Cuando tu API recibe una solicitud con un token de acceso emitido por Logto, debes: - Verificar la firma del token (usando los JWKs de Logto). -- Confirmar que el token no haya expirado (reclamo `exp`). -- Comprobar que el `iss` (emisor) coincida con tu endpoint de Logto. -- Asegurarte de que el `aud` (audiencia) coincida con el identificador de recurso de API que registraste (por ejemplo, `https://api.yourapp.com`). +- Confirmar que el token no ha expirado (reclamo `exp`). +- Comprobar que el `iss` (emisor) coincide con tu endpoint de Logto. +- Asegurarte de que el `aud` (audiencia) coincide con el identificador del recurso de API que registraste (por ejemplo, `https://api.yourapp.com`). - Separar el reclamo `scope` (separado por espacios) y comprobar los permisos requeridos. Para guías paso a paso y específicas por lenguaje, consulta [Cómo validar tokens de acceso](/authorization/validate-access-tokens). -### Opcional: Manejar cambios de permisos de usuario \{#optional-handle-user-permission-change} - -:::info -👷 Trabajo en progreso. 🚧 -::: + ## Mejores prácticas y consejos de seguridad \{#best-practices-and-security-tips} @@ -210,7 +207,7 @@ Para guías paso a paso y específicas por lenguaje, consulta [Cómo validar tok
-### ¿Qué pasa si mi cliente no admite el parámetro resource? \{#what-if-my-client-doesn-t-support-the-resource-parameter} +### ¿Qué pasa si mi cliente no soporta el parámetro resource? \{#what-if-my-client-doesn-t-support-the-resource-parameter} @@ -227,9 +224,9 @@ Configura un recurso de API predeterminado en la Consola de Logto. Los tokens te Verifica los siguientes problemas comunes: -- **Firma del token**: Asegúrate de que tu backend esté obteniendo los JWKs correctos de Logto -- **Expiración del token**: Verifica que el token no haya expirado (reclamo `exp`) -- **Audiencia**: Confirma que el reclamo `aud` coincida con el indicador de recurso de API registrado +- **Firma del token**: Asegúrate de que tu backend obtiene los JWKs correctos de Logto +- **Expiración del token**: Asegúrate de que el token no haya expirado (reclamo `exp`) +- **Audiencia**: Confirma que el reclamo `aud` coincide con el indicador de recurso de API registrado - **Alcances requeridos**: Verifica que el token contenga los permisos necesarios en el reclamo `scope`
@@ -281,5 +278,5 @@ scopes: ["read", "write"] // ❌ No coincide con los nombres de permisos RBAC en la práctica: Implementando autorización segura para tu aplicación -Personalización de reclamos de token +Personalización de reclamos de tokens RFC 8707: Indicadores de recurso diff --git a/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 8b1851286b1..ce551ff4585 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,30 +6,31 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; import InspectOrganizationClaim from './fragments/_inspect-organization-claim.md'; import OrganizationTokenWarning from './fragments/_organization-token-warning.md'; -# Protege recursos de API a nivel de organización +# Protege los recursos de API a nivel de organización export const resource = 'https://api.your-app.com/organizations'; -Combina recursos de API con la plantilla de organización para restringir el acceso a las APIs y datos dentro de cada organización, asegurando el aislamiento a nivel de inquilino en tu SaaS. +Combina los recursos de API con la plantilla de organización para restringir el acceso a las APIs y datos dentro de cada organización, asegurando el aislamiento a nivel de inquilino en tu SaaS. ## ¿Qué son los recursos de API a nivel de organización? \{#what-are-organization-level-api-resources} -Los recursos de API a nivel de organización son endpoints o servicios en tu aplicación que están **limitados a una organización específica**. Estas APIs aplican autorización y acceso basados en el contexto de la organización, asegurando que los usuarios o clientes solo accedan a datos y acciones relevantes para su organización. +Los recursos de API a nivel de organización son endpoints o servicios en tu aplicación que están **asociados a una organización específica**. Estas APIs aplican autorización y acceso basados en el contexto de la organización, asegurando que los usuarios o clientes solo accedan a datos y acciones relevantes para su organización. -**Los casos de uso incluyen** +**Casos de uso incluyen** - APIs para gestionar miembros, roles o configuraciones de la organización (por ejemplo, `/organizations/{organizationId}/members`) -- Paneles, analíticas o informes limitados a la organización +- Paneles, analíticas o reportes asociados a la organización - Endpoints de facturación, suscripción o auditoría vinculados a una organización - Cualquier API donde las acciones y los datos estén aislados por inquilino -Logto te permite asegurar estas APIs de organización usando OAuth 2.1 y control de acceso basado en roles (RBAC), mientras soporta arquitecturas SaaS multi-inquilino. +Logto te permite asegurar estas APIs de organización usando OAuth 2.1 y RBAC, mientras soporta arquitecturas SaaS multi-inquilino. Estos permisos se gestionan a través de **roles de organización** definidos en la [plantilla de organización](/authorization/organization-template). Cada organización utiliza la misma plantilla, asegurando un modelo de permisos consistente en todas las organizaciones. @@ -38,7 +39,7 @@ Estos permisos se gestionan a través de **roles de organización** definidos en - **Los recursos de API y permisos se registran globalmente:** Cada recurso de API se define con un indicador de recurso único (URI) y un conjunto de permisos (alcances) en Logto. - **Roles a nivel de organización:** Los roles de organización se definen en la plantilla de organización. Los permisos de recursos de API (alcances) se asignan a los roles de organización, que luego se asignan a usuarios o clientes **dentro de cada organización**. - **Autorización consciente del contexto:** Cuando un cliente solicita un token de acceso con un recurso de API y un `organization_id`, Logto emite un token que incluye tanto el contexto de la organización como la audiencia de la API. Los permisos (alcances) del token se determinan por los roles de organización del usuario para la organización especificada. -- **Separación de recursos globales:** Los recursos de API pueden ser accedidos con o sin contexto de organización. El RBAC de organización solo se aplica si se incluye un `organization_id` en la solicitud. Para APIs compartidas entre todos los usuarios, consulta [Protege recursos de API globales](/authorization/global-api-resources). +- **Separación de recursos globales:** Los recursos de API pueden ser accedidos con o sin contexto de organización. El RBAC de organización solo se aplica si se incluye un `organization_id` en la solicitud. Para APIs compartidas entre todos los usuarios, consulta [Proteger recursos de API globales](/authorization/global-api-resources). >API: Solicitud con token Bearer API->>API: Valida el token, verifica contexto de organización y permisos - alt Token válido + alt El token es válido API->>Cliente: Devuelve datos de la organización - else Token inválido + else El token no es válido API->>Cliente: 401 No autorizado end ``` @@ -103,15 +104,15 @@ _Autenticación de usuario = navegador/app. M2M = servicio backend o script usan 1. Ve a Consola → Recursos de API. 2. Crea un nuevo recurso de API (por ejemplo, `https://api.yourapp.com/org`) y define sus permisos (alcances). -Para ver los pasos completos de configuración, consulta [Definir recursos de API con permisos](/authorization/role-based-access-control#define-api-resources-with-permissions). +Para los pasos completos de configuración, consulta [Definir recursos de API con permisos](/authorization/role-based-access-control#define-api-resources-with-permissions). -### Configura roles de organización \{#set-up-organization-roles} +### Configura los roles de organización \{#set-up-organization-roles} 1. Ve a Consola → Plantilla de organización → Roles de organización. 2. Crea roles de organización (por ejemplo, `admin`, `member`) y asigna permisos de API a cada rol. 3. Asigna roles a usuarios o clientes dentro de cada organización. Si aún no son miembros, invítalos o agrégalos primero. -Para ver los pasos completos de configuración, consulta [Usar roles de organización](/authorization/role-based-access-control#configure-organization-roles). +Para los pasos completos de configuración, consulta [Usar roles de organización](/authorization/role-based-access-control#configure-organization-roles). ### Obtén tokens de organización para recursos de API \{#obtain-organization-tokens-for-api-resources} @@ -119,12 +120,12 @@ Tu cliente/app debe solicitar un token con ambos parámetros, `resource` y `orga #### Flujo de token de actualización \{#refresh-token-flow} -Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de token de actualización de forma nativa. También se puede usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. +Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de token de actualización de forma nativa. También puedes usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. -Al inicializar el Logto SDK, añade el alcance `urn:logto:scope:organizations` y los permisos de organización deseados (alcances) al parámetro `scopes`. +Al inicializar el SDK de Logto, añade `urn:logto:scope:organizations` y los permisos de organización deseados (alcances) al parámetro `scopes`. Algunos SDK de Logto tienen un alcance predefinido para organizaciones, como `UserScope.Organizations` en los SDK de JavaScript. @@ -132,7 +133,7 @@ Algunos SDK de Logto tienen un alcance predefinido para organizaciones, como `Us Al llamar a `getAccessToken()`, especifica tanto el recurso de API (`resource`) como el ID de la organización (`organizationId`) para obtener un token de organización. -Para detalles sobre cada SDK, consulta [Guías rápidas](/quick-starts). +Para detalles sobre cada SDK, consulta [Inicios rápidos](/quick-starts). @@ -140,7 +141,7 @@ Para detalles sobre cada SDK, consulta [Guías rápidas](/quick-starts). Al configurar tu cliente OAuth 2.0 o inicializar el flujo de código de autorización, asegúrate de incluir los siguientes parámetros: - `resource`: Establece el identificador del recurso de API registrado en Logto (por ejemplo, `https://api.your-app.com/organizations`). -- `scope`: Incluye el alcance predefinido de organización (`urn:logto:scope:organizations`), `offline_access` (para obtener tokens de actualización) y cualquier permiso específico de API que necesites (por ejemplo, `manage:members view:analytics`). +- `scope`: Incluye el alcance predefinido de organización (`urn:logto:scope:organizations`), `offline_access` (para obtener tokens de actualización) y cualquier permiso de API específico que necesites (por ejemplo, `manage:members view:analytics`). Algunas bibliotecas pueden no soportar el parámetro `resource` de forma nativa, pero normalmente permiten pasar parámetros adicionales en la solicitud de autorización. Consulta la documentación de tu biblioteca para más detalles. @@ -200,26 +201,28 @@ Aquí tienes un ejemplo no normativo de la solicitud de token usando el tipo de ### Valida los tokens de organización \{#validate-organization-tokens} -Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu API puede usar para aplicar el control de acceso a nivel de organización. +Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu API puede usar para aplicar control de acceso a nivel de organización. Cuando tu app reciba un token de organización, deberías: - Verificar la firma del token (usando los JWKs de Logto). -- Confirmar que el token no esté expirado (reclamo `exp`). +- Confirmar que el token no esté expirado (`exp` claim). - Comprobar que el `iss` (emisor) coincida con tu endpoint de Logto. - Asegurarte de que el `aud` (audiencia) coincida con el identificador del recurso de API que registraste (por ejemplo, `https://api.yourapp.com/org`). -- Validar el reclamo `organization_id` para asegurar que el token esté limitado a la organización correcta. +- Validar el reclamo `organization_id` para asegurar que el token esté asociado a la organización correcta. - Separar el reclamo `scope` (separado por espacios) y comprobar los permisos requeridos. -- Si la ruta de tu API incluye el ID de la organización (por ejemplo, `/organizations/{organizationId}/members`), asegúrate de que el reclamo `organization_id` coincida con el parámetro de la ruta. +- Si tu ruta de API incluye el ID de la organización (por ejemplo, `/organizations/{organizationId}/members`), asegúrate de que el reclamo `organization_id` coincida con el parámetro de la ruta. Para guías paso a paso y específicas por lenguaje, consulta [Cómo validar tokens de acceso](/authorization/validate-access-tokens). + + ## Mejores prácticas y consejos de seguridad \{#best-practices-and-security-tips} -- **Valida siempre el contexto de la organización:** No confíes solo en el token; revisa el reclamo `organization_id` en cada llamada a una API limitada por organización. -- **Usa restricciones de audiencia:** Revisa siempre el reclamo `aud` para asegurar que el token sea para la organización prevista. +- **Valida siempre el contexto de organización:** No confíes solo en el token; verifica el reclamo `organization_id` en cada llamada a una API asociada a organización. +- **Usa restricciones de audiencia:** Comprueba siempre el reclamo `aud` para asegurar que el token es para la organización prevista. - **Mantén los permisos orientados al negocio:** Usa nombres claros que correspondan a acciones reales; otorga solo lo necesario para cada rol de organización. -- **Separa permisos de API y no-API** donde sea posible (pero ambos pueden estar en un solo rol). +- **Separa permisos de API y no-API** cuando sea posible (pero ambos pueden estar en un solo rol). - **Mantén los tiempos de vida de los tokens cortos:** Reduce el riesgo si un token se filtra. - **Revisa regularmente tu plantilla de organización:** Actualiza roles y permisos a medida que tu producto evoluciona. @@ -243,14 +246,14 @@ Solo se evaluarán los roles/permisos globales. No se aplicará el RBAC de organ -No, los permisos de organización (incluidos los permisos de API a nivel de organización) se definen por la plantilla de organización y no pueden mezclarse con permisos globales de API. Sin embargo, puedes crear roles que incluyan tanto permisos de organización como permisos de API a nivel de organización. +No, los permisos de organización (incluidos los permisos de API a nivel de organización) se definen por la plantilla de organización y no pueden mezclarse con permisos de API globales. Sin embargo, puedes crear roles que incluyan tanto permisos de organización como permisos de API a nivel de organización.
## Más información \{#further-reading} Cómo validar tokens de acceso -Personalización de reclamos de tokens +Personalización de reclamos de token Caso de uso: Construir una aplicación SaaS multi-inquilino diff --git a/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index efd147efbbd..a3c50bfa256 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,27 +15,27 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # Protege los permisos de organización (no API) -Utiliza la plantilla de organización para gestionar y aplicar roles y permisos a nivel de organización en Logto, controlando el acceso a funciones y flujos dentro de una organización. +Utiliza la plantilla de organización para gestionar y aplicar roles y permisos a nivel de organización en Logto, controlando el acceso a funciones y flujos dentro de la aplicación en el contexto de una organización. ## ¿Qué son los permisos de organización (no API)? \{#what-are-organization-non-api-permissions} Los permisos de organización (no API) controlan lo que los usuarios pueden hacer **dentro del contexto de una organización**, pero no se **aplican a nivel de API**. En cambio, gobiernan el acceso a funciones de la aplicación, elementos de la interfaz, flujos de trabajo o acciones de negocio, en lugar de APIs de backend. -**Casos de uso incluyen** +**Los casos de uso incluyen** - Invitar o gestionar miembros dentro de una organización - Asignar o cambiar roles de organización - Gestionar la facturación, configuraciones o funciones administrativas de una organización - Acceso a paneles, analíticas o herramientas internas que no tienen endpoints de API -Logto te permite asegurar estos permisos de organización usando OAuth 2.1 y control de acceso basado en roles (RBAC), mientras soporta arquitecturas SaaS multi-tenant. +Logto te permite proteger estos permisos de organización usando OAuth 2.1 y control de acceso basado en roles (RBAC), mientras soporta arquitecturas SaaS multi-tenant. Estos permisos se gestionan a través de **roles de organización** definidos en la [plantilla de organización](/authorization/organization-template). Cada organización utiliza la misma plantilla, asegurando un modelo de permisos consistente en todas las organizaciones. ## Cómo funciona en Logto \{#how-it-works-in-logto} - **RBAC a nivel de organización:** Los roles y permisos se definen en la plantilla de organización. Cuando un usuario se une a una organización, se le asignan uno o más roles, otorgando permisos específicos. -- **Aplicación no API:** Los permisos se verifican y aplican en la interfaz de tu app, flujo de trabajo o lógica de backend, no necesariamente por un gateway de API. +- **Aplicación no API:** Los permisos se verifican y aplican en la interfaz de tu aplicación, flujo de trabajo o lógica de backend, no necesariamente por un gateway de API. - **Separación de la protección de API:** Los permisos de organización (no API) son distintos de los permisos de recursos de API. Puedes combinar ambos para escenarios avanzados.
@@ -50,8 +51,8 @@ Estos permisos se gestionan a través de **roles de organización** definidos en 1. **Define los permisos de organización** en Logto bajo la plantilla de organización. 2. **Crea roles de organización** que agrupen los permisos necesarios para tus acciones específicas de organización. 3. **Asigna roles** a usuarios o clientes dentro de cada organización. -4. **Obtén un token de organización (JWT)** para la organización actual usando el refresh token o el flujo de client credentials. -5. **Valida los tokens de acceso** en la interfaz o backend de tu app para aplicar los permisos de organización. +4. **Obtén un token de organización (JWT)** para la organización actual usando el flujo de refresh token o client credentials. +5. **Valida los tokens de acceso** en la interfaz o backend de tu aplicación para aplicar los permisos de organización. ### Flujo de autorización: autenticando y asegurando permisos de organización \{#authorization-flow-authenticating-and-securing-organization-permissions} @@ -87,7 +88,7 @@ sequenceDiagram end ``` -_Autenticación de usuario = navegador/app. M2M = servicio de backend o script usando client credentials + contexto de organización._ +_Autenticación de usuario = navegador/aplicación. M2M = servicio de backend o script usando client credentials + contexto de organización._ ## Pasos de implementación \{#implementation-steps} @@ -108,11 +109,11 @@ Para ver los pasos completos de configuración, consulta [Usar roles de organiza ### Obtén tokens de organización (no API) \{#obtain-organization-tokens-non-api} -Tu cliente/app debe obtener un token de organización (no API) para acceder a los permisos de organización. Logto emite tokens de organización como [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Puedes obtenerlos usando el [refresh token flow](https://auth.wiki/refresh-token) o el [client credentials flow](https://auth.wiki/client-credentials-flow). +Tu cliente/aplicación debe obtener un token de organización (no API) para acceder a los permisos de organización. Logto emite tokens de organización como [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Puedes obtenerlos usando el [flujo de refresh token](https://auth.wiki/refresh-token) o el [flujo de client credentials](https://auth.wiki/client-credentials-flow). #### Flujo de refresh token \{#refresh-token-flow} -Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de refresh token de forma nativa. También puedes usar una librería estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. +Casi todos los SDK oficiales de Logto admiten la obtención de tokens de organización usando el flujo de refresh token de forma nativa. También se puede usar una biblioteca estándar de cliente OAuth 2.0 / OIDC para implementar este flujo. @@ -133,9 +134,9 @@ Para detalles sobre cada SDK, consulta [Guías rápidas](/quick-starts). Al configurar tu cliente OAuth 2.0 o inicializar el flujo de código de autorización, asegúrate de incluir los siguientes parámetros: - `resource`: Establece en `urn:logto:resource:organizations` para indicar que deseas un token de organización. -- `scope`: Incluye el alcance predefinido de organización (`urn:logto:scope:organizations`), `offline_access` (para obtener refresh tokens) y cualquier permiso específico de organización que necesites (por ejemplo, `invite:member`, `manage:billing`). +- `scope`: Incluye el alcance predefinido de organización (`urn:logto:scope:organizations`), `offline_access` (para obtener refresh tokens) y cualquier permiso de organización específico que necesites (por ejemplo, `invite:member`, `manage:billing`). -Algunas librerías pueden no soportar el parámetro `resource` de forma nativa, pero normalmente permiten pasar parámetros adicionales en la solicitud de autorización. Consulta la documentación de tu librería para más detalles. +Algunas bibliotecas pueden no soportar el parámetro `resource` de forma nativa, pero normalmente permiten pasar parámetros adicionales en la solicitud de autorización. Consulta la documentación de tu biblioteca para más detalles. Aquí tienes un ejemplo no normativo de cómo podría verse la solicitud de autorización: @@ -158,7 +159,7 @@ Recibirás un refresh token que puede usarse para obtener tokens de organizació Finalmente, usa el refresh token para obtener un token de organización haciendo una solicitud POST al endpoint `/oidc/token` de Logto. Recuerda incluir: -- El parámetro `organization_id` establecido al ID de la organización deseada. +- El parámetro `organization_id` establecido en el ID de la organización deseada. - (Opcional) El parámetro `scope` para reducir aún más los permisos que necesitas (por ejemplo, `manage:members view:reports`). Aquí tienes un ejemplo no normativo de cómo podría verse la solicitud de token: @@ -172,7 +173,7 @@ Aquí tienes un ejemplo no normativo de cómo podría verse la solicitud de toke Para escenarios máquina a máquina (M2M), puedes usar el flujo de client credentials para obtener un token de acceso para permisos de organización. Haciendo una solicitud POST al endpoint `/oidc/token` de Logto con parámetros de organización, puedes solicitar un token de organización usando tu client ID y secret. -Estos son los parámetros clave a incluir en la solicitud: +Estos son los parámetros clave que debes incluir en la solicitud: - `organization_id`: El ID de la organización para la que deseas el token. - `scope`: Los permisos de organización que deseas solicitar (por ejemplo, `invite:member`, `manage:billing`). @@ -184,11 +185,11 @@ Aquí tienes un ejemplo no normativo de la solicitud de token usando el tipo de scope="invite:member manage:billing" /> -### Valida los tokens de organización \{#validate-organization-tokens} +### Valida tokens de organización \{#validate-organization-tokens} -Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu app/interfaz/backend puede usar para aplicar el control de acceso a nivel de organización. +Los tokens de organización emitidos por Logto (JWTs) contienen reclamos que tu aplicación/interfaz/backend puede usar para aplicar el control de acceso a nivel de organización. -Cuando tu app reciba un token de organización, deberías: +Cuando tu aplicación reciba un token de organización, deberías: - Verificar la firma del token (usando los JWKs de Logto). - Confirmar que el token no ha expirado (reclamo `exp`). @@ -198,11 +199,13 @@ Cuando tu app reciba un token de organización, deberías: Para guías paso a paso y específicas por lenguaje, consulta [Cómo validar tokens de acceso](/authorization/validate-access-tokens). + + ## Mejores prácticas y consejos de seguridad \{#best-practices-and-security-tips} - **Nunca confíes solo en la aplicación en la interfaz:** Siempre valida los permisos en el backend para acciones críticas. - **Usa restricciones de audiencia:** Comprueba siempre el reclamo `aud` para asegurarte de que el token es para la organización prevista. -- **Mantén los permisos orientados al negocio:** Usa nombres claros que correspondan a acciones reales; concede solo lo necesario para cada rol de organización. +- **Mantén los permisos orientados al negocio:** Usa nombres claros que correspondan a acciones reales; otorga solo lo necesario para cada rol de organización. - **Separa permisos de API y no API** cuando sea posible (pero ambos pueden estar en un solo rol). - **Revisa la plantilla de organización regularmente** a medida que evoluciona tu producto. @@ -233,7 +236,7 @@ Verifica los permisos no API tanto en la interfaz (para limitar funciones) como ## Más información \{#further-reading} Cómo validar tokens de acceso -Personalización de reclamos de tokens +Personalización de reclamos en tokens Caso de uso: Construir una aplicación SaaS multi-tenant diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..7e91a3295d5 --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### Optionnel : Gérer le changement de permission utilisateur \{#optional-handle-user-permission-change} + +Les permissions des utilisateurs peuvent changer à tout moment. Comme Logto émet des JWT pour le contrôle d’accès basé sur les rôles (RBAC), les mises à jour de permissions n’apparaissent que dans les nouveaux jetons émis, et ne modifient jamais les JWT existants. + +:::info Règle de sous-ensemble de portée (Scope subset rule) +Un jeton d’accès (Access token) ne peut inclure que les portées (Scopes) qui ont été demandées lors du flux d’autorisation OAuth initial. +Même si un utilisateur obtient de nouvelles permissions (Permissions), le jeton émis par la suite ne peut contenir qu’un sous-ensemble des portées demandées à l’origine. +Pour accéder à de nouvelles portées accordées qui ne faisaient pas partie de la demande initiale, le client doit lancer un nouveau flux d’autorisation. +::: + +#### Permissions réduites (Downscoped permissions) \{#downscoped-permissions} + +Lorsqu’un utilisateur perd des permissions : + +- Les nouveaux jetons émis reflètent immédiatement les portées réduites. +- Les JWT existants conservent les anciennes portées jusqu’à leur expiration. +- Votre API doit toujours valider les portées et s’appuyer sur des durées de vie de jeton courtes. + +Si vous avez besoin d’une réaction plus rapide, implémentez votre propre signal pour demander aux clients d’actualiser leurs jetons. + +#### Permissions élargies (Enlarged permissions) \{#enlarged-permissions} + +{props.type === "global" &&

Pour les ressources API globales, lorsqu’un utilisateur obtient de nouvelles permissions, les permissions élargies n’apparaîtront PAS lors d’un rafraîchissement. Le client doit effectuer un nouveau flux d’autorisation OAuth pour obtenir un jeton incluant les nouvelles portées. Cela peut se faire silencieusement si l’utilisateur a une session Logto active.

} + +{props.type === "organization" &&

Pour les jetons d’organisation, lorsqu’un utilisateur obtient de nouvelles permissions, les permissions élargies apparaîtront lors de la prochaine émission (rafraîchissement ou demande de jeton). Un nouveau jeton est toujours requis, mais une ré-authentification complète n’est pas nécessaire sauf si les nouvelles portées dépassent l’ensemble de la demande initiale.

} + +#### Recommandations \{#recommendations} + +- Validez les portées dans votre API à chaque appel. +- Gardez une expiration de jeton courte. +- Ajoutez des notifications optionnelles si vous avez besoin d’une propagation immédiate des changements de permissions. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 5f3a364ac82..882b1ef99e5 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -13,11 +14,11 @@ import Tabs from '@theme/Tabs'; export const resource = 'https://api.your-app.com'; -Protégez les API à l’échelle du produit en utilisant le contrôle d’accès basé sur les rôles (RBAC) dans Logto. Attribuez des rôles et des permissions globaux pour contrôler l’accès de tous les utilisateurs et clients à travers votre application. +Protégez les API à l’échelle du produit en utilisant le contrôle d’accès basé sur les rôles (RBAC) dans Logto. Attribuez des rôles et des permissions globales pour contrôler l’accès de tous les utilisateurs et clients à travers votre application. ## Qu’est-ce qu’une ressource API globale ? \{#what-are-global-api-resources} -Les ressources API globales sont des points de terminaison ou des services dans votre application accessibles à tous les utilisateurs, quel que soit l’organisation ou le locataire. Il s’agit généralement d’API publiques, de services cœur du produit ou de tout point de terminaison qui n’est pas limité à une organisation spécifique. +Les ressources API globales sont des points de terminaison ou des services dans votre application accessibles à tous les utilisateurs, quel que soit l’organisation ou le locataire. Il s’agit généralement d’API publiques, de services principaux du produit ou de tout point de terminaison qui n’est pas limité à une organisation spécifique. **Cas d’utilisation courants** @@ -29,9 +30,9 @@ Logto vous permet de sécuriser ces API en utilisant OAuth 2.1, combiné à un c ## Fonctionnement dans Logto \{#how-it-works-in-logto} -- **Les ressources API et permissions sont enregistrées globalement :** Chaque API que vous souhaitez protéger est définie avec un indicateur de ressource unique (URI) et un ensemble de permissions (portées) qui contrôlent l’accès. +- **Les ressources API et les permissions sont enregistrées globalement :** Chaque API que vous souhaitez protéger est définie avec un indicateur de ressource unique (URI) et un ensemble de permissions (portées) qui contrôlent l’accès. - **L’accès est contrôlé par des rôles globaux :** Vous pouvez attribuer des permissions à des rôles, qui sont ensuite attribués à des utilisateurs ou des clients. -- **Séparé des permissions au niveau de l’organisation :** Les ressources API globales n’ont pas de contexte d’organisation. Cependant, elles peuvent être utilisées en combinaison avec des rôles d’organisation pour fournir une couche de contexte supplémentaire si nécessaire. Pour protéger les API au niveau de l’organisation, voir [Protéger les ressources API au niveau de l’organisation](/authorization/organization-level-api-resources). +- **Séparé des permissions au niveau de l’organisation :** Les ressources API globales n’ont pas de contexte d’organisation. Cependant, elles peuvent être utilisées en combinaison avec des rôles d’organisation pour fournir une couche de contexte supplémentaire si nécessaire. Pour protéger des API au niveau de l’organisation, voir [Protéger les ressources API au niveau de l’organisation](/authorization/organization-level-api-resources). Ressources API globales RBAC @@ -39,7 +40,7 @@ Logto vous permet de sécuriser ces API en utilisant OAuth 2.1, combiné à un c 1. **Enregistrez votre ressource API** et définissez ses permissions dans Logto. 2. **Définissez des rôles** avec les permissions nécessaires pour accéder à l’API. -3. **Attribuez les rôles** aux utilisateurs ou clients. +3. **Attribuez les rôles** aux utilisateurs ou aux clients. 4. **Utilisez les flux d’autorisation OAuth 2.0** pour obtenir des jetons d’accès pour l’API (le paramètre resource doit correspondre à l’identifiant API enregistré). 5. **Validez les jetons d’accès** dans votre API pour appliquer les permissions. @@ -62,7 +63,7 @@ Logto modélise les ressources API selon [RFC 8707 : Indicateurs de ressource po Le flux ci-dessous s’applique à la fois à l’authentification interactive de l’utilisateur (navigateur / application) et aux scénarios backend machine à machine (M2M). -Veuillez noter que ce flux ne détaille pas tous les paramètres ou en-têtes requis, mais se concentre sur les étapes clés. Continuez la lecture pour voir comment ce flux fonctionne en pratique. +Veuillez noter que ce flux ne détaille pas tous les paramètres ou en-têtes requis, mais se concentre sur les étapes clés. Continuez à lire pour voir comment ce flux fonctionne en pratique. ```mermaid sequenceDiagram @@ -74,9 +75,9 @@ sequenceDiagram Client->>Logto: GET /oidc/auth Logto->>Logto: Redirige l’utilisateur vers la page de connexion Logto->>Client: Redirige avec `authorization_code` - alt Utilise le grant authorization_code + alt Utiliser le flux authorization_code Client->>Logto: POST /oidc/token avec `grant_type=authorization_code`
et paramètre `resource` - else Utilise le grant refresh_token + else Utiliser le flux refresh_token Client->>Logto: POST /oidc/token avec `grant_type=authorization_code` Logto->>Client: Retourne un jeton de rafraîchissement Client->>Logto: POST /oidc/token avec `grant_type=refresh_token`
et paramètre `resource` @@ -111,21 +112,21 @@ Le paramètre `resource` doit correspondre exactement à l’identifiant API (in Pour toutes les étapes de configuration, voir [Définir des ressources API avec des permissions](/authorization/role-based-access-control#define-api-resources-with-permissions). -### Configurez des rôles globaux \{#set-up-global-roles} +### Configurez les rôles globaux \{#set-up-global-roles} 1. Allez dans Console → Rôles. 2. Créez des rôles correspondant à vos permissions API (par exemple, `read:products`, `write:products`). 3. Attribuez ces rôles aux utilisateurs ou clients qui ont besoin d’accéder à l’API. -Pour toutes les étapes de configuration, voir [Utiliser des rôles globaux](/authorization/role-based-access-control#configure-global-roles). +Pour toutes les étapes de configuration, voir [Utiliser les rôles globaux](/authorization/role-based-access-control#configure-global-roles). ### Obtenez des jetons d’accès pour les ressources API globales \{#obtain-access-tokens-for-global-api-resources} -Avant d’accéder à une ressource API globale, votre client doit obtenir un jeton d’accès. Logto émet des [JSON Web Tokens (JWT)](https://auth.wiki/jwt) comme jetons d’accès pour les ressources API globales. Cela se fait généralement via le [flux d’autorisation code OAuth 2.0](https://auth.wiki/authorization-code-flow), le [flux de jeton de rafraîchissement](https://auth.wiki/refresh-token), ou le [flux client credentials](https://auth.wiki/client-credentials-flow). +Avant d’accéder à une ressource API globale, votre client doit obtenir un jeton d’accès. Logto émet des [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) comme jetons d’accès pour les ressources API globales. Cela se fait généralement via le [flux d’autorisation code OAuth 2.0](https://auth.wiki/authorization-code-flow), le [flux de jeton de rafraîchissement](https://auth.wiki/refresh-token), ou le [flux client credentials](https://auth.wiki/client-credentials-flow). #### Flux authorization code ou refresh token \{#authorization-code-or-refresh-token-flow} -Tous les SDK officiels Logto prennent en charge l’obtention de jetons d’accès pour les ressources API globales via le flux de jeton de rafraîchissement par défaut. Une bibliothèque cliente OAuth 2.0 / OIDC standard peut également être utilisée pour implémenter ce flux. +Tous les SDK officiels Logto prennent en charge l’obtention de jetons d’accès pour les ressources API globales via le flux refresh token par défaut. Une bibliothèque cliente OAuth 2.0 / OIDC standard peut également être utilisée pour implémenter ce flux. @@ -149,13 +150,13 @@ Voici un exemple non normatif de requête d’autorisation avec les paramètres Une fois l’utilisateur authentifié, vous recevrez un code d’autorisation. Échangez ce code contre un jeton d’accès en effectuant une requête POST vers le point de terminaison `/oidc/token` de Logto, en incluant le paramètre `resource` dans le corps de la requête. -Voici un exemple non normatif de requête de jeton utilisant le type de grant authorization_code : +Voici un exemple non normatif de requête de jeton utilisant le type de flux authorization code : -Vous pouvez également utiliser le type de grant `refresh_token` pour obtenir un nouveau jeton d’accès sans interaction utilisateur, tant que le paramètre `resource` est inclus dans la requête. +Vous pouvez également utiliser le type de flux `refresh_token` pour obtenir un nouveau jeton d’accès sans interaction utilisateur, tant que le paramètre `resource` est inclus dans la requête. -Voici un exemple non normatif de requête de jeton utilisant le type de grant refresh_token : +Voici un exemple non normatif de requête de jeton utilisant le type de flux refresh token : @@ -171,7 +172,7 @@ Deux paramètres clés doivent être inclus dans la requête : - `resource` : L’URI indicateur de ressource de l’API à laquelle vous souhaitez accéder (par exemple, `https://api.yourapp.com`). - `scope` : Les permissions que vous souhaitez demander pour l’API (par exemple, `read:products write:products`). -Voici un exemple non normatif de requête de jeton utilisant le type de grant client credentials : +Voici un exemple non normatif de requête de jeton utilisant le type de flux client credentials : ## Bonnes pratiques et conseils de sécurité \{#best-practices-and-security-tips} @@ -227,10 +224,10 @@ Définissez une ressource API par défaut dans la Console Logto. Les jetons util Vérifiez les problèmes courants suivants : -- **Signature du jeton** : Vérifiez que votre backend récupère les bons JWKs depuis Logto -- **Expiration du jeton** : Assurez-vous que le jeton n’a pas expiré (revendication `exp`) -- **Audience** : Vérifiez que la revendication `aud` correspond à l’indicateur de ressource API enregistré -- **Portées requises** : Vérifiez que le jeton contient les permissions nécessaires dans la revendication `scope` +- **Signature du jeton :** Vérifiez que votre backend récupère les bons JWKs depuis Logto +- **Expiration du jeton :** Assurez-vous que le jeton n’a pas expiré (revendication `exp`) +- **Audience :** Vérifiez que la revendication `aud` correspond à l’indicateur de ressource API enregistré +- **Portées requises :** Vérifiez que le jeton contient les permissions nécessaires dans la revendication `scope` @@ -248,11 +245,11 @@ Utilisez un [jeton d’accès personnel](/user-management/personal-access-token)
-### Puis-je utiliser des préfixes de scope ou des versions abrégées lors de la demande de permissions ? \{#can-i-use-scope-prefixes-or-shortened-versions} +### Puis-je utiliser des préfixes de portée ou des versions abrégées lors de la demande de permissions ? \{#can-i-use-scope-prefixes-or-shortened-versions} -Non. Les noms de scope doivent **correspondre exactement** aux noms de permissions définis dans votre ressource API. Les préfixes et versions abrégées ne fonctionnent pas comme des jokers. +Non. Les noms de portées doivent **correspondre exactement** aux noms de permissions définis dans votre ressource API. Les préfixes et versions abrégées ne fonctionnent pas comme des jokers. **Exemple :** diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 30113945731..63952bf2143 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -20,18 +21,18 @@ Combinez les ressources API avec le modèle d’organisation pour restreindre l ## Que sont les ressources API au niveau de l’organisation ? \{#what-are-organization-level-api-resources} -Les ressources API au niveau de l’organisation sont des points de terminaison ou des services dans votre application qui sont **limités à une organisation spécifique**. Ces API appliquent l’autorisation et l’accès en fonction du contexte organisationnel, garantissant que les utilisateurs ou clients n’accèdent qu’aux données et actions pertinentes pour leur organisation. +Les ressources API au niveau de l’organisation sont des points de terminaison ou des services dans votre application qui sont **rattachés à une organisation spécifique**. Ces API appliquent l’autorisation et l’accès en fonction du contexte organisationnel, garantissant que les utilisateurs ou clients n’accèdent qu’aux données et actions pertinentes pour leur organisation. **Exemples d’utilisation** - API pour gérer les membres, rôles ou paramètres d’une organisation (par exemple, `/organizations/{organizationId}/members`) -- Tableaux de bord, analyses ou rapports limités à l’organisation +- Tableaux de bord, analyses ou rapports spécifiques à l’organisation - Points de terminaison de facturation, d’abonnement ou d’audit liés à une organisation - Toute API où les actions et les données sont isolées par locataire Logto vous permet de sécuriser ces API d’organisation en utilisant OAuth 2.1 et le contrôle d’accès basé sur les rôles (RBAC), tout en prenant en charge les architectures SaaS multi-locataires. -Ces permissions sont gérées via les **rôles d’organisation** définis dans le [modèle d’organisation](/authorization/organization-template). Chaque organisation utilise le même modèle, garantissant un modèle de permission cohérent pour toutes les organisations. +Ces permissions sont gérées via les **rôles d’organisation** définis dans le [modèle d’organisation](/authorization/organization-template). Chaque organisation utilise le même modèle, garantissant un modèle de permissions cohérent pour toutes les organisations. ## Fonctionnement dans Logto \{#how-it-works-in-logto} @@ -46,11 +47,11 @@ Ces permissions sont gérées via les **rôles d’organisation** définis dans style={{ maxWidth: '100%' }} /> -### Vue d’ensemble de la mise en œuvre \{#implementation-overview} +### Vue d’ensemble de l’implémentation \{#implementation-overview} 1. **Enregistrez votre ressource API** et définissez ses permissions (portées) dans Logto. 2. **Définissez les rôles d’organisation** dans le modèle d’organisation et attribuez les permissions API pertinentes. -3. **Attribuez des rôles** aux utilisateurs ou clients au sein de chaque organisation. +3. **Attribuez les rôles** aux utilisateurs ou clients au sein de chaque organisation. 4. **Demandez un jeton d’accès** pour l’API avec un `organization_id` pour inclure le contexte organisationnel. 5. **Validez les jetons d’accès** dans votre API, en appliquant à la fois le contexte organisationnel et les permissions. @@ -60,11 +61,11 @@ Ces permissions sont gérées via les **rôles d’organisation** définis dans - Si vous demandez un jeton d’accès **avec** un `organization_id`, Logto évalue les rôles d’organisation de l’utilisateur et leurs permissions associées pour cette organisation. - Le JWT résultant contiendra à la fois l’audience API (`aud` revendication) et le contexte organisationnel (`organization_id` revendication), avec des portées filtrées selon celles accordées par les rôles d’organisation de l’utilisateur. -### Flux d’autorisation : authentifier et sécuriser les API avec le contexte organisationnel \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} +### Flux d’autorisation : authentification et sécurisation des API avec contexte organisationnel \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} Le flux suivant montre comment un client (web, mobile ou backend) obtient et utilise des jetons d’organisation pour accéder aux ressources API au niveau de l’organisation. -Veuillez noter que ce flux ne détaille pas tous les paramètres ou en-têtes requis, mais se concentre sur les étapes clés. Continuez à lire pour voir comment le flux fonctionne en pratique. +Veuillez noter que ce flux ne détaille pas tous les paramètres ou en-têtes requis, mais se concentre sur les étapes clés. Continuez la lecture pour voir comment ce flux fonctionne en pratique. ```mermaid sequenceDiagram @@ -77,13 +78,13 @@ sequenceDiagram Logto->>Logto: Redirige l’utilisateur vers la page de connexion Logto->>Client: Redirige avec `authorization_code` Client->>Logto: POST /oidc/token avec `grant_type=authorization_code` - Logto->>Client: Retourne le jeton de rafraîchissement + Logto->>Client: Retourne un jeton de rafraîchissement Client->>Logto: POST /oidc/token avec `grant_type=refresh_token`
+ resource + organization_id - else Authentification client machine à machine (M2M) + else Authentification machine à machine (M2M) Client->>Logto: POST /oidc/token avec `grant_type=client_credentials`
+ resource + organization_id end - Logto->>Client: Retourne le jeton d’accès (JWT) + Logto->>Client: Retourne un jeton d’accès (JWT) Client->>API: Requête avec jeton Bearer API->>API: Valide le jeton, vérifie le contexte organisationnel et les permissions @@ -96,26 +97,26 @@ sequenceDiagram _Authentification utilisateur = navigateur / application. M2M = service backend ou script utilisant les identifiants client + contexte organisationnel._ -## Étapes de mise en œuvre \{#implementation-steps} +## Étapes d’implémentation \{#implementation-steps} ### Enregistrez votre ressource API \{#register-your-api-resource} -1. Allez dans Console → Ressources API. +1. Accédez à Console → Ressources API. 2. Créez une nouvelle ressource API (par exemple, `https://api.yourapp.com/org`) et définissez ses permissions (portées). Pour les étapes complètes de configuration, voir [Définir des ressources API avec des permissions](/authorization/role-based-access-control#define-api-resources-with-permissions). ### Configurez les rôles d’organisation \{#set-up-organization-roles} -1. Allez dans Console → Modèle d’organisation → Rôles d’organisation. -2. Créez des rôles d’organisation (par exemple, `admin`, `member`) et attribuez des permissions API à chaque rôle. -3. Attribuez des rôles aux utilisateurs ou clients au sein de chaque organisation. S’ils ne sont pas encore membres, invitez-les ou ajoutez-les d’abord. +1. Accédez à Console → Modèle d’organisation → Rôles d’organisation. +2. Créez des rôles d’organisation (par exemple, `admin`, `member`) et attribuez les permissions API à chaque rôle. +3. Attribuez les rôles aux utilisateurs ou clients au sein de chaque organisation. S’ils ne sont pas encore membres, invitez-les ou ajoutez-les d’abord. Pour les étapes complètes de configuration, voir [Utiliser les rôles d’organisation](/authorization/role-based-access-control#configure-organization-roles). ### Obtenez des jetons d’organisation pour les ressources API \{#obtain-organization-tokens-for-api-resources} -Votre client / application doit demander un jeton avec à la fois `resource` et `organization_id` pour accéder aux API au niveau de l’organisation. Logto émet des jetons d’organisation sous forme de [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Vous pouvez les obtenir en utilisant soit le [flux de jeton de rafraîchissement](https://auth.wiki/refresh-token), soit le [flux client credentials](https://auth.wiki/client-credentials-flow). +Votre client / application doit demander un jeton avec à la fois `resource` et `organization_id` pour accéder aux API au niveau de l’organisation. Logto émet des jetons d’organisation sous forme de [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Vous pouvez les obtenir en utilisant soit le [flux de jeton de rafraîchissement](https://auth.wiki/refresh-token) soit le [flux client credentials](https://auth.wiki/client-credentials-flow). #### Flux de jeton de rafraîchissement \{#refresh-token-flow} @@ -130,19 +131,19 @@ Certains SDK Logto disposent d’une portée prédéfinie pour les organisations -Lors de l’appel de `getAccessToken()`, spécifiez à la fois la ressource API (`resource`) et l’ID de l’organisation (`organizationId`) pour obtenir un jeton d’organisation. +Lors de l’appel à `getAccessToken()`, spécifiez à la fois la ressource API (`resource`) et l’ID de l’organisation (`organizationId`) pour obtenir un jeton d’organisation. Pour plus de détails sur chaque SDK, voir [Démarrages rapides](/quick-starts). - + -Lors de la configuration de votre client OAuth 2.0 ou de l’initialisation du flux d’autorisation par code, assurez-vous d’inclure les paramètres suivants : +Lors de la configuration de votre client OAuth 2.0 ou de l’initialisation du flux d’autorisation, assurez-vous d’inclure les paramètres suivants : - `resource` : Défini sur l’identifiant de la ressource API enregistrée dans Logto (par exemple, `https://api.your-app.com/organizations`). - `scope` : Incluez la portée prédéfinie d’organisation (`urn:logto:scope:organizations`), `offline_access` (pour obtenir des jetons de rafraîchissement), et toutes les permissions API spécifiques dont vous avez besoin (par exemple, `manage:members view:analytics`). -Certaines bibliothèques peuvent ne pas prendre en charge nativement le paramètre `resource`, mais permettent généralement de passer des paramètres supplémentaires dans la requête d’autorisation. Consultez la documentation de votre bibliothèque pour plus de détails. +Certaines bibliothèques ne prennent pas en charge le paramètre `resource` nativement, mais permettent généralement de passer des paramètres supplémentaires dans la requête d’autorisation. Consultez la documentation de votre bibliothèque pour plus de détails. Voici un exemple non normatif de requête d’autorisation : @@ -167,7 +168,7 @@ Enfin, utilisez le jeton de rafraîchissement pour obtenir un jeton d’organisa - Le paramètre `resource` défini sur l’identifiant de la ressource API (par exemple, `https://api.yourapp.com/org`). - Le paramètre `organization_id` défini sur l’ID de l’organisation souhaitée. -- (Optionnel) Le paramètre `scope` pour restreindre davantage les permissions dont vous avez besoin (par exemple, `manage:members view:reports`). +- (Optionnel) Le paramètre `scope` pour restreindre davantage les permissions nécessaires (par exemple, `manage:members view:reports`). Voici un exemple non normatif de requête de jeton : @@ -206,19 +207,21 @@ Lorsque votre application reçoit un jeton d’organisation, vous devez : - Vérifier la signature du jeton (en utilisant les JWKs de Logto). - Confirmer que le jeton n’est pas expiré (`exp` revendication). -- Vérifier que le `iss` (émetteur) correspond à votre point de terminaison Logto. -- S’assurer que le `aud` (audience) correspond à l’identifiant de la ressource API que vous avez enregistrée (par exemple, `https://api.yourapp.com/org`). -- Valider la revendication `organization_id` pour s’assurer que le jeton est limité à la bonne organisation. +- Vérifier que l’`iss` (émetteur) correspond à votre point de terminaison Logto. +- S’assurer que l’`aud` (audience) correspond à l’identifiant de la ressource API que vous avez enregistrée (par exemple, `https://api.yourapp.com/org`). +- Valider la revendication `organization_id` pour s’assurer que le jeton est rattaché à la bonne organisation. - Séparer la revendication `scope` (séparée par des espaces) et vérifier les permissions requises. - Si le chemin de votre API inclut l’ID de l’organisation (par exemple, `/organizations/{organizationId}/members`), assurez-vous que la revendication `organization_id` correspond au paramètre du chemin. Pour des guides étape par étape et spécifiques à chaque langage, voir [Comment valider les jetons d’accès](/authorization/validate-access-tokens). + + ## Bonnes pratiques et conseils de sécurité \{#best-practices-and-security-tips} -- **Validez toujours le contexte organisationnel :** Ne vous fiez pas uniquement au jeton ; vérifiez la revendication `organization_id` pour chaque appel d’API limité à l’organisation. +- **Validez toujours le contexte organisationnel :** Ne vous fiez pas uniquement au jeton ; vérifiez la revendication `organization_id` pour chaque appel d’API rattaché à une organisation. - **Utilisez les restrictions d’audience :** Vérifiez toujours la revendication `aud` pour vous assurer que le jeton est destiné à la bonne organisation. -- **Gardez les permissions orientées métier :** Utilisez des noms clairs correspondant à de vraies actions ; n’accordez que ce qui est nécessaire pour chaque rôle d’organisation. +- **Gardez les permissions orientées métier :** Utilisez des noms clairs correspondant à des actions réelles ; n’accordez que ce qui est nécessaire pour chaque rôle d’organisation. - **Séparez les permissions API et non-API** lorsque c’est possible (mais les deux peuvent être dans un même rôle). - **Gardez la durée de vie des jetons courte :** Réduit le risque en cas de fuite d’un jeton. - **Révisez régulièrement votre modèle d’organisation :** Mettez à jour les rôles et permissions au fur et à mesure de l’évolution de votre produit. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 4f29772cfe6..271d01e3d64 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -18,24 +19,24 @@ Utilisez le modèle d’organisation pour gérer et appliquer les rôles et perm ## Que sont les permissions d’organisation (hors API) ? \{#what-are-organization-non-api-permissions} -Les permissions d’organisation (hors API) contrôlent ce que les utilisateurs peuvent faire **dans le contexte d’une organisation**, mais ne sont **pas appliquées au niveau de l’API**. Elles régissent l’accès aux fonctionnalités de l’application, aux éléments d’interface, aux flux de travail ou aux actions métier, plutôt qu’aux API backend. +Les permissions d’organisation (hors API) contrôlent ce que les utilisateurs peuvent faire **dans le contexte d’une organisation**, mais ne sont **pas appliquées au niveau de l’API**. Elles régissent plutôt l’accès aux fonctionnalités de l’application, aux éléments d’interface, aux flux de travail ou aux actions métier, plutôt qu’aux API backend. -**Cas d’usage typiques** +**Cas d’usage courants** - Inviter ou gérer des membres au sein d’une organisation - Attribuer ou modifier des rôles d’organisation - Gérer la facturation, les paramètres ou les fonctions administratives d’une organisation -- Accès à des tableaux de bord, des analyses ou des outils internes sans points de terminaison API +- Accès à des tableaux de bord, des analyses ou des outils internes sans point d’accès API -Logto vous permet de sécuriser ces permissions d’organisation à l’aide d’OAuth 2.1 et du contrôle d’accès basé sur les rôles (RBAC), tout en prenant en charge les architectures SaaS multi-locataires. +Logto vous permet de sécuriser ces permissions d’organisation en utilisant OAuth 2.1 et le contrôle d’accès basé sur les rôles (RBAC), tout en prenant en charge les architectures SaaS multi-locataires. Ces permissions sont gérées via les **rôles d’organisation** définis dans le [modèle d’organisation](/authorization/organization-template). Chaque organisation utilise le même modèle, garantissant une cohérence du modèle de permissions entre toutes les organisations. ## Fonctionnement dans Logto \{#how-it-works-in-logto} -- **Contrôle d’accès basé sur les rôles au niveau organisation** : Les rôles et permissions sont définis dans le modèle d’organisation. Lorsqu’un utilisateur rejoint une organisation, un ou plusieurs rôles lui sont attribués, lui accordant des permissions spécifiques. -- **Application hors API** : Les permissions sont vérifiées et appliquées dans l’interface de votre application, les flux de travail ou la logique backend, pas nécessairement par une passerelle API. -- **Séparation de la protection API** : Les permissions d’organisation (hors API) sont distinctes des permissions des ressources API. Vous pouvez combiner les deux pour des scénarios avancés. +- **Contrôle d’accès basé sur les rôles au niveau de l’organisation (RBAC) :** Les rôles et permissions sont définis dans le modèle d’organisation. Lorsqu’un utilisateur rejoint une organisation, il se voit attribuer un ou plusieurs rôles, lui accordant des permissions spécifiques. +- **Application hors API :** Les permissions sont vérifiées et appliquées dans l’interface de votre application, les flux de travail ou la logique backend, pas nécessairement par une passerelle API. +- **Séparation de la protection API :** Les permissions d’organisation (hors API) sont distinctes des permissions des ressources API. Vous pouvez combiner les deux pour des scénarios avancés.
>Client: Retourne le jeton d’organisation (JWT) - Client->>App: Requête avec jeton Bearer - App->>App: Valide le jeton d’organisation, vérifie le contexte et les permissions d’organisation + Client->>App: Requête avec Bearer token + App->>App: Valide le jeton d’organisation, vérifie le contexte d’organisation et les permissions alt Jeton valide App->>Client: Autorise les actions/données spécifiques à l’organisation @@ -96,7 +97,7 @@ _Authentification utilisateur = navigateur/application. M2M = service backend ou 1. Rendez-vous sur Console → Modèle d’organisation → Permissions d’organisation. 2. Définissez les permissions d’organisation nécessaires (ex : `invite:member`, `manage:billing`, `view:analytics`). -Pour la configuration complète, voir [Définir les permissions d’organisation](/authorization/role-based-access-control#define-organization-permissions). +Pour toutes les étapes de configuration, voir [Définir les permissions d’organisation](/authorization/role-based-access-control#define-organization-permissions). ### Configurer les rôles d’organisation \{#set-up-organization-roles} @@ -104,7 +105,7 @@ Pour la configuration complète, voir [Définir les permissions d’organisation 2. Créez des rôles regroupant les permissions d’organisation définies précédemment (ex : `admin`, `member`, `billing`). 3. Attribuez ces rôles aux utilisateurs ou clients dans chaque organisation. -Pour la configuration complète, voir [Utiliser les rôles d’organisation](/authorization/role-based-access-control#configure-organization-roles). +Pour toutes les étapes de configuration, voir [Utiliser les rôles d’organisation](/authorization/role-based-access-control#configure-organization-roles). ### Obtenir des jetons d’organisation (hors API) \{#obtain-organization-tokens-non-api} @@ -133,9 +134,9 @@ Pour plus de détails sur chaque SDK, voir [Démarrages rapides](/quick-starts). Lors de la configuration de votre client OAuth 2.0 ou de l’initialisation du flux d’autorisation, assurez-vous d’inclure les paramètres suivants : - `resource` : Définir sur `urn:logto:resource:organizations` pour indiquer que vous souhaitez un jeton d’organisation. -- `scope` : Inclure la portée prédéfinie d’organisation (`urn:logto:scope:organizations`), `offline_access` (pour obtenir des jetons de rafraîchissement) et toute permission d’organisation spécifique nécessaire (ex : `invite:member`, `manage:billing`). +- `scope` : Inclure la portée prédéfinie d’organisation (`urn:logto:scope:organizations`), `offline_access` (pour obtenir des jetons de rafraîchissement), et toute permission d’organisation spécifique requise (ex : `invite:member`, `manage:billing`). -Certaines bibliothèques ne prennent pas en charge le paramètre `resource` nativement, mais permettent généralement de passer des paramètres supplémentaires dans la requête d’autorisation. Consultez la documentation de votre bibliothèque pour plus de détails. +Certaines bibliothèques ne prennent pas en charge nativement le paramètre `resource`, mais permettent généralement de passer des paramètres supplémentaires dans la requête d’autorisation. Consultez la documentation de votre bibliothèque pour plus de détails. Voici un exemple non normatif de requête d’autorisation : @@ -144,7 +145,7 @@ Voici un exemple non normatif de requête d’autorisation : resource="urn:logto:resource:organizations" /> -Une fois l’utilisateur authentifié, vous recevrez un code d’autorisation. Utilisez ce code en effectuant une requête POST vers le point de terminaison `/oidc/token` de Logto. +Une fois l’utilisateur authentifié, vous recevrez un code d’autorisation. Utilisez ce code en effectuant une requête POST vers l’endpoint `/oidc/token` de Logto. Voici un exemple non normatif de requête de jeton : @@ -156,7 +157,7 @@ Vous recevrez un jeton de rafraîchissement qui pourra être utilisé pour obten -Enfin, utilisez le jeton de rafraîchissement pour obtenir un jeton d’organisation en effectuant une requête POST vers le point de terminaison `/oidc/token` de Logto. N’oubliez pas d’inclure : +Enfin, utilisez le jeton de rafraîchissement pour obtenir un jeton d’organisation en effectuant une requête POST vers l’endpoint `/oidc/token` de Logto. N’oubliez pas d’inclure : - Le paramètre `organization_id` défini sur l’ID de l’organisation souhaitée. - (Optionnel) Le paramètre `scope` pour restreindre davantage les permissions nécessaires (ex : `manage:members view:reports`). @@ -170,7 +171,7 @@ Voici un exemple non normatif de requête de jeton : #### Flux client credentials \{#client-credentials-flow} -Pour les scénarios machine à machine (M2M), vous pouvez utiliser le flux client credentials pour obtenir un jeton d’accès aux permissions d’organisation. En effectuant une requête POST vers le point de terminaison `/oidc/token` de Logto avec les paramètres d’organisation, vous pouvez demander un jeton d’organisation à l’aide de votre client ID et secret. +Pour les scénarios machine à machine (M2M), vous pouvez utiliser le flux client credentials pour obtenir un jeton d’accès aux permissions d’organisation. En effectuant une requête POST vers l’endpoint `/oidc/token` de Logto avec les paramètres d’organisation, vous pouvez demander un jeton d’organisation en utilisant votre client ID et secret. Voici les paramètres clés à inclure dans la requête : @@ -186,23 +187,25 @@ Voici un exemple non normatif de requête de jeton utilisant le type de flux cli ### Valider les jetons d’organisation \{#validate-organization-tokens} -Les jetons d’organisation émis par Logto (JWTs) contiennent des revendications que votre application / interface / backend peut utiliser pour appliquer le contrôle d’accès au niveau organisation. +Les jetons d’organisation émis par Logto (JWTs) contiennent des revendications que votre application/interface/backend peut utiliser pour appliquer le contrôle d’accès au niveau de l’organisation. Lorsque votre application reçoit un jeton d’organisation, vous devez : - Vérifier la signature du jeton (en utilisant les JWKs de Logto). - Confirmer que le jeton n’est pas expiré (revendication `exp`). -- Vérifier que l’`iss` (émetteur) correspond à votre point de terminaison Logto. +- Vérifier que l’`iss` (émetteur) correspond à votre endpoint Logto. - S’assurer que l’`aud` (audience) correspond à l’identifiant formaté de l’organisation (ex : `urn:logto:organization:{organization_id}`). - Découper la revendication `scope` (séparée par des espaces) et vérifier les permissions requises. Pour des guides détaillés et spécifiques à chaque langage, voir [Comment valider les jetons d’accès](/authorization/validate-access-tokens). + + ## Bonnes pratiques et conseils de sécurité \{#best-practices-and-security-tips} -- **Ne vous fiez jamais uniquement à l’interface** : Validez toujours les permissions côté backend pour les actions critiques. -- **Utilisez les restrictions d’audience** : Vérifiez toujours la revendication `aud` pour vous assurer que le jeton est destiné à la bonne organisation. -- **Gardez les permissions orientées métier** : Utilisez des noms clairs correspondant à de vraies actions ; n’accordez que ce qui est nécessaire pour chaque rôle d’organisation. +- **Ne vous fiez jamais uniquement à l’interface pour l’application des permissions :** Validez toujours les permissions côté backend pour les actions critiques. +- **Utilisez les restrictions d’audience :** Vérifiez toujours la revendication `aud` pour vous assurer que le jeton est destiné à la bonne organisation. +- **Gardez les permissions orientées métier :** Utilisez des noms clairs correspondant à des actions réelles ; n’accordez que ce qui est nécessaire pour chaque rôle d’organisation. - **Séparez les permissions API et hors API** autant que possible (mais les deux peuvent être dans un même rôle). - **Révisez régulièrement le modèle d’organisation** à mesure que votre produit évolue. @@ -215,7 +218,7 @@ Pour des guides détaillés et spécifiques à chaque langage, voir [Comment val -Non, les permissions d’organisation (y compris les permissions API au niveau organisation) sont définies par le modèle d’organisation et ne peuvent pas être mélangées avec des permissions API globales. Cependant, vous pouvez créer des rôles incluant à la fois des permissions d’organisation et des permissions API au niveau organisation. +Non, les permissions d’organisation (y compris les permissions API au niveau de l’organisation) sont définies par le modèle d’organisation et ne peuvent pas être mélangées avec les permissions API globales. Cependant, vous pouvez créer des rôles incluant à la fois des permissions d’organisation et des permissions API au niveau de l’organisation.
@@ -226,14 +229,14 @@ Non, les permissions d’organisation (y compris les permissions API au niveau o -Vérifiez les permissions hors API à la fois dans l’interface (pour le contrôle d’accès aux fonctionnalités) et dans votre logique côté serveur pour les actions sensibles. +Vérifiez les permissions hors API à la fois dans l’interface (pour le contrôle d’accès aux fonctionnalités) et dans votre logique serveur pour les actions sensibles. ## Pour aller plus loin \{#further-reading} Comment valider les jetons d’accès -Personnaliser les revendications de jeton +Personnalisation des revendications de jeton Cas d’usage : Construire une application SaaS multi-locataires diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..2839e6dbe64 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### オプション: ユーザー権限の変更への対応 \{#optional-handle-user-permission-change} + +ユーザーの権限はいつでも変更される可能性があります。Logto は RBAC のために JWT を発行しているため、権限の更新は新たに発行されたトークンにのみ反映され、既存の JWT が変更されることはありません。 + +:::info スコープ (Scope) サブセットルール +アクセス トークン (Access token) には、元の OAuth 認可 (Authorization) フローでリクエストされたスコープ (Scope) のみが含まれます。 +ユーザーが新しい権限を獲得しても、後で発行されるトークンには、元のリクエストで要求されたスコープ (Scope) のサブセットしか含めることができません。 +初回リクエストに含まれていなかった新しいスコープ (Scope) へアクセスするには、クライアントは新しい認可 (Authorization) フローを実行する必要があります。 +::: + +#### 権限の縮小（ダウンスコープ） \{#downscoped-permissions} + +ユーザーが権限を失った場合： + +- 新たに発行されたトークンは、即座に縮小されたスコープ (Scope) を反映します。 +- 既存の JWT は、有効期限が切れるまで古いスコープ (Scope) を保持します。 +- API では常にスコープ (Scope) を検証し、短いトークン有効期間に依存してください。 + +より迅速な対応が必要な場合は、クライアントにトークンのリフレッシュを促す独自のシグナルを実装してください。 + +#### 権限の拡大（アップスコープ） \{#enlarged-permissions} + +{props.type === "global" &&

グローバル API リソースの場合、ユーザーが権限を獲得しても、リフレッシュによって拡大した権限は反映されません。新しいスコープ (Scope) を含むトークンを取得するには、クライアントは新しい OAuth 認可 (Authorization) フローを実行する必要があります。ユーザーがアクティブな Logto セッションを持っていれば、これはサイレントに行われる場合があります。

} + +{props.type === "organization" &&

組織トークンの場合、ユーザーが権限を獲得すると、次回の発行（リフレッシュまたはトークンリクエスト）で拡大した権限が反映されます。新しいトークンは必要ですが、新しいスコープ (Scope) が元のリクエストセットを超えない限り、完全な再認証は不要です。

} + +#### 推奨事項 \{#recommendations} + +- API では毎回スコープ (Scope) を検証してください。 +- トークンの有効期限は短く設定してください。 +- 即時の権限変更伝播が必要な場合は、オプションで通知機能を追加してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 5fde7cd9e9a..59e128f2bf6 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -29,9 +30,9 @@ Logto では、OAuth 2.1 と柔軟なロールベースのアクセス制御を ## Logto での仕組み \{#how-it-works-in-logto} -- **API リソースと権限はグローバルに登録される：** 保護したい各 API は、一意のリソースインジケーター（URI）とアクセスを制御する権限（スコープ）のセットで定義されます。 -- **アクセスはグローバルロールで制御：** 権限をロールに割り当て、それをユーザーやクライアントに割り当てます。 -- **組織レベルの権限とは分離：** グローバル API リソースには組織の文脈がありません。ただし、必要に応じて組織ロールと組み合わせて追加の文脈を提供することも可能です。組織レベルの API を保護するには、[組織レベルの API リソースの保護](/authorization/organization-level-api-resources) を参照してください。 +- **API リソースと権限はグローバルに登録されます：** 保護したい各 API は、一意のリソースインジケーター（URI）とアクセスを制御する権限（スコープ）のセットで定義します。 +- **アクセスはグローバルロールで制御：** 権限をロールに割り当て、そのロールをユーザーやクライアントに割り当てます。 +- **組織レベルの権限とは分離：** グローバル API リソースには組織のコンテキストがありません。ただし、必要に応じて組織ロールと組み合わせて追加のコンテキストを提供することも可能です。組織レベルの API を保護するには、[組織レベルの API リソースの保護](/authorization/organization-level-api-resources) を参照してください。 グローバル API リソース RBAC @@ -40,7 +41,7 @@ Logto では、OAuth 2.1 と柔軟なロールベースのアクセス制御を 1. **API リソースを登録**し、Logto でその権限を定義します。 2. **API へのアクセスに必要な権限を持つロールを定義**します。 3. **ロールをユーザーやクライアントに割り当て**ます。 -4. **OAuth 2.0 認可フローを使用して** API 用のアクセス トークンを取得します（resource パラメーターは登録した API 識別子と一致させる必要があります）。 +4. **OAuth 2.0 認可フロー**を使用して API 用のアクセス トークンを取得します（resource パラメーターは登録した API 識別子と一致する必要があります）。 5. **API でアクセス トークンを検証**し、権限を強制します。 ### リソースインジケーターの理解 \{#understanding-resource-indicators} @@ -50,7 +51,7 @@ Logto は [RFC 8707: OAuth 2.0 のリソースインジケーター](https://www **ポイント** - リソースインジケーターは絶対 URI でなければなりません（例： `https://api.example.com`） -- フラグメントコンポーネントは不可。可能な限りクエリストリングの使用も避けてください。 +- フラグメントコンポーネントは不可。可能な限りクエリ文字列の使用も避けてください。 - リソースインジケーターにより、オーディエンス制限付きトークンやマルチ API アーキテクチャのサポートが可能になります。 **例** @@ -60,46 +61,46 @@ Logto は [RFC 8707: OAuth 2.0 のリソースインジケーター](https://www ### 認可フロー：API の認証と保護 \{#authorization-flow-authenticating-and-securing-your-api} -以下のフローは、インタラクティブなユーザー認証（ブラウザ / アプリ）とバックエンドのマシン間通信 (M2M) シナリオの両方に適用されます。 +以下のフローは、インタラクティブなユーザー認証（ブラウザ / アプリ）とバックエンドのマシン間通信 (M2M) の両方に適用されます。 -このフローは必要なパラメーターやヘッダーの詳細をすべて網羅しているわけではなく、主要なステップに焦点を当てています。実際のフローの動作については、引き続きお読みください。 +このフローは必要なパラメーターやヘッダーの詳細をすべて網羅しているわけではなく、主要なステップに焦点を当てています。実際の動作例はこの後で紹介します。 ```mermaid sequenceDiagram - participant Client + participant クライアント participant Logto participant API as API リソース alt ユーザー認証 - Client->>Logto: GET /oidc/auth + クライアント->>Logto: GET /oidc/auth Logto->>Logto: ユーザーをサインインページにリダイレクト - Logto->>Client: `authorization_code` でリダイレクトバック + Logto->>クライアント: `authorization_code` でリダイレクトバック alt authorization_code グラントを使用 - Client->>Logto: POST /oidc/token （`grant_type=authorization_code`
および `resource` パラメーター付き） + クライアント->>Logto: POST /oidc/token （`grant_type=authorization_code`
および `resource` パラメーター付き） else refresh_token グラントを使用 - Client->>Logto: POST /oidc/token （`grant_type=authorization_code`） - Logto->>Client: リフレッシュ トークンを返す - Client->>Logto: POST /oidc/token （`grant_type=refresh_token`
および `resource` パラメーター付き） + クライアント->>Logto: POST /oidc/token （`grant_type=authorization_code`） + Logto->>クライアント: リフレッシュ トークンを返す + クライアント->>Logto: POST /oidc/token （`grant_type=refresh_token`
および `resource` パラメーター付き） end else マシン間通信 (M2M) クライアント認証 - Client->>Logto: POST /oidc/token （`grant_type=client_credentials`
および `resource` パラメーター付き） + クライアント->>Logto: POST /oidc/token （`grant_type=client_credentials`
および `resource` パラメーター付き） end - Logto->>Client: アクセス トークン（JSON Web Token）を返す - Client->>API: Bearer トークンでリクエスト + Logto->>クライアント: アクセス トークン（JSON Web Token）を返す + クライアント->>API: Bearer トークンでリクエスト API->>API: アクセス トークンを検証 alt トークンが有効 - API->>Client: 保護されたリソースデータを返す + API->>クライアント: 保護されたリソースデータを返す else トークンが無効 - API->>Client: 401 Unauthorized + API->>クライアント: 401 Unauthorized end ``` -_ユーザー認証 = ブラウザ / アプリ。M2M = クライアント認証を使うバックエンドサービスやスクリプト。_ +_ユーザー認証 = ブラウザ / アプリ。M2M = クライアント認証情報を使うバックエンドサービスやスクリプト。_ :::note -`resource` パラメーターは、Logto で登録した API 識別子（リソースインジケーター）と完全に一致している必要があります。 +`resource` パラメーターは、Logto で登録した API 識別子（リソースインジケーター）と完全に一致する必要があります。 ::: ## 実装手順 \{#implementation-steps} @@ -121,57 +122,57 @@ _ユーザー認証 = ブラウザ / アプリ。M2M = クライアント認証 ### グローバル API リソース用のアクセス トークンの取得 \{#obtain-access-tokens-for-global-api-resources} -グローバル API リソースにアクセスする前に、クライアントはアクセス トークンを取得する必要があります。Logto はグローバル API リソース用の [JSON Web Token (JWT)](https://auth.wiki/jwt) をアクセス トークンとして発行します。これは通常、[OAuth 2.0 認可コードフロー](https://auth.wiki/authorization-code-flow)、[リフレッシュ トークンフロー](https://auth.wiki/refresh-token)、または [クライアント認証フロー](https://auth.wiki/client-credentials-flow) を使用して行われます。 +グローバル API リソースへアクセスする前に、クライアントはアクセス トークンを取得する必要があります。Logto はグローバル API リソース用の [JSON Web Token (JWT)](https://auth.wiki/jwt) をアクセス トークンとして発行します。これは通常、[OAuth 2.0 認可コードフロー](https://auth.wiki/authorization-code-flow)、[リフレッシュ トークンフロー](https://auth.wiki/refresh-token)、または [クライアント認証情報フロー](https://auth.wiki/client-credentials-flow) で行います。 #### 認可コードまたはリフレッシュ トークンフロー \{#authorization-code-or-refresh-token-flow} -Logto 公式 SDK はすべて、リフレッシュ トークンフローを利用したグローバル API リソース用のアクセス トークン取得をサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 +Logto 公式 SDK はすべて、リフレッシュ トークンフローを使ったグローバル API リソース用のアクセス トークン取得をサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 -Logto クライアントの初期化時に、`resources` パラメーター（配列）にリソースインジケーターを追加し、`scopes` パラメーターに必要な権限（スコープ）を追加します。 +Logto クライアント初期化時に、`resources` パラメーター（配列）にリソースインジケーターを追加し、`scopes` パラメーターに必要な権限（スコープ）を追加します。 -ユーザーが認証された後、`getAccessToken()` などでアクセス トークンをリクエストする際に、`resource` パラメーターまたは同様のパラメーターでリソースインジケーターを渡します。 +ユーザーが認証 (Authentication) されたら、`getAccessToken()` などでアクセス トークンをリクエストする際に `resource` パラメーター（または同等のパラメーター）にリソースインジケーターを渡します。 各 SDK の詳細は [クイックスタート](/quick-starts) を参照してください。 -OAuth 2.0 クライアントの設定や認可コードフローの初期化時に、`resource` パラメーターと必要なスコープを認可リクエストに含めてください。 +OAuth 2.0 クライアントの設定や認可コードフロー初期化時に、`resource` パラメーターと必要なスコープを認可リクエストに含めてください。 -一部のライブラリは `resource` パラメーターをネイティブにサポートしていませんが、通常は追加パラメーターとして認可リクエストに渡すことができます。詳細はご利用のライブラリのドキュメントを確認してください。 +一部のライブラリは `resource` パラメーターをネイティブにサポートしていませんが、通常は追加パラメーターとして認可リクエストに渡すことができます。詳細はライブラリのドキュメントを確認してください。 -`resource` および `scope` パラメーターを含む認可リクエストの非公式例を示します： +`resource` および `scope` パラメーターを含む認可リクエストの非公式例： -ユーザーが認証されると、認可コードを受け取ります。このコードを Logto の `/oidc/token` エンドポイントに POST し、リクエストボディに `resource` パラメーターを含めてアクセス トークンと交換します。 +ユーザーが認証 (Authentication) されると、認可コードが返されます。このコードを Logto の `/oidc/token` エンドポイントに POST し、リクエストボディに `resource` パラメーターを含めてアクセス トークンと交換します。 -認可コードグラントタイプを使ったトークンリクエストの非公式例： +認可コードグラントタイプでのトークンリクエストの非公式例： また、`refresh_token` グラントタイプを使えば、ユーザー操作なしで新しいアクセス トークンを取得できます（リクエストに `resource` パラメーターを含める必要があります）。 -リフレッシュ トークングラントタイプを使ったトークンリクエストの非公式例： +リフレッシュ トークングラントタイプでのトークンリクエストの非公式例： -#### クライアント認証フロー \{#client-credentials-flow} +#### クライアント認証情報フロー \{#client-credentials-flow} -マシン間通信 (M2M) シナリオでは、クライアント認証フローを使ってグローバル API リソース用のアクセス トークンを取得できます。Logto の `/oidc/token` エンドポイントに POST リクエストを送り、クライアント ID とシークレットを使ってアクセス トークンをリクエストします。 +マシン間通信 (M2M) シナリオでは、クライアント認証情報フローを使ってグローバル API リソース用のアクセス トークンを取得できます。Logto の `/oidc/token` エンドポイントに POST リクエストを送り、クライアント ID とシークレットを使ってアクセス トークンをリクエストします。 -リクエストに含めるべき主なパラメーターは 2 つです： +リクエストに含める主なパラメーターは 2 つです： - `resource`: アクセスしたい API のリソースインジケーター URI（例： `https://api.yourapp.com`） -- `scope`: API にリクエストしたい権限（例： `read:products write:products`） +- `scope`: API に対してリクエストしたい権限（例： `read:products write:products`） -クライアント認証グラントタイプを使ったトークンリクエストの非公式例： +クライアント認証情報グラントタイプでのトークンリクエストの非公式例： ## ベストプラクティスとセキュリティのヒント \{#best-practices-and-security-tips} -- **権限はビジネス主導で設計：** 実際のアクションに対応する分かりやすい名前を使いましょう。 -- **トークンの有効期限は短く：** トークンが漏洩した場合のリスクを低減します。 -- **付与するスコープは最小限に：** トークンには本当に必要な権限だけを与えましょう。 -- **オーディエンス制限を活用：** `aud` クレームを必ず検証し、不正利用を防ぎましょう。 +- **権限はビジネスに即したものに：** 実際のアクションに対応する明確な名前を使いましょう。 +- **トークン有効期限は短く：** トークンが漏洩した場合のリスクを減らせます。 +- **付与するスコープは最小限に：** 実際に必要な権限だけをトークンに与えましょう。 +- **オーディエンス制限を利用：** `aud` クレームを必ず検証し、不正利用を防ぎましょう。 ## よくある質問 \{#faqs} @@ -214,21 +211,21 @@ API が Logto 発行のアクセス トークンを受け取った場合、次 -Logto コンソールでデフォルトの API リソースを設定してください。トークンリクエストで resource パラメーターが指定されていない場合、このオーディエンスがデフォルトになります。 +Logto コンソールでデフォルトの API リソースを設定してください。トークンリクエストで resource パラメーターが指定されていない場合、このオーディエンスがデフォルトで使用されます。
-### API から 401 Unauthorized が返される理由は？ \{#why-do-i-get-401-unauthorized-from-my-api} +### API から 401 Unauthorized が返されるのはなぜ？ \{#why-do-i-get-401-unauthorized-from-my-api} 次の一般的な問題を確認してください： - **トークン署名**：バックエンドが Logto から正しい JWKs を取得しているか確認 -- **トークンの有効期限**：トークンが有効期限切れでないか（`exp` クレーム） +- **トークン有効期限**：トークンが期限切れでないか（`exp` クレーム） - **オーディエンス**：`aud` クレームが登録した API リソースインジケーターと一致しているか - **必要なスコープ**：トークンの `scope` クレームに必要な権限が含まれているか @@ -279,7 +276,7 @@ scopes: ["read", "write"] // ❌ 権限名と一致しません アクセス トークンの検証方法 - RBAC 実践：アプリケーションの安全な認可 (Authorization) 実装 + 実践 RBAC：アプリケーションの安全な認可 (Authorization) 実装 トークンクレームのカスタマイズ RFC 8707: リソースインジケーター diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 60e611cdf99..5de04d98b6b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -20,14 +21,14 @@ API リソースと組織テンプレートを組み合わせることで、各 ## 組織レベルの API リソースとは？ \{#what-are-organization-level-api-resources} -組織レベルの API リソースとは、**特定の組織にスコープされた**アプリケーション内のエンドポイントやサービスです。これらの API は組織コンテキストに基づいて認可 (Authorization) とアクセスを強制し、ユーザーやクライアントが自分の組織に関連するデータや操作のみを利用できるようにします。 +組織レベルの API リソースとは、**特定の組織にスコープされた**アプリケーション内のエンドポイントやサービスです。これらの API は組織コンテキストに基づいて認可 (Authorization) とアクセスを強制し、ユーザーやクライアントが自分の組織に関連するデータや操作のみにアクセスできるようにします。 -**主なユースケース例** +**ユースケース例** -- 組織メンバー、ロール、設定を管理する API（例： `/organizations/{organizationId}/members` ） +- 組織メンバー、ロール、設定を管理する API（例： `/organizations/{organizationId}/members`） - 組織単位のダッシュボード、分析、レポート - 組織に紐づく請求、サブスクリプション、監査用エンドポイント -- アクションやデータがテナントごとに分離されるすべての API +- アクションやデータがテナントごとに分離されるあらゆる API Logto は、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利用して、これらの組織 API をセキュアに保護し、マルチテナント SaaS アーキテクチャをサポートします。 @@ -35,9 +36,9 @@ Logto は、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利 ## Logto での仕組み \{#how-it-works-in-logto} -- **API リソースと権限はグローバルに登録される：** 各 API リソースは一意のリソースインジケーター（URI）と権限（スコープ）のセットで Logto に定義されます。 -- **組織レベルのロール：** 組織ロールは組織テンプレートで定義されます。API リソースの権限（スコープ）は組織ロールに割り当てられ、各組織内のユーザーやクライアントに付与されます。 -- **コンテキスト認識型認可 (Authorization)：** クライアントが API リソースと `organization_id` の両方を指定してアクセストークンをリクエストすると、Logto は組織コンテキストと API オーディエンスの両方を含むトークンを発行します。トークンの権限（スコープ）は、指定した組織におけるユーザーの組織ロールによって決定されます。 +- **API リソースと権限はグローバルに登録される：** 各 API リソースは Logto で一意のリソースインジケーター（URI）と権限（スコープ）のセットとして定義されます。 +- **組織レベルのロール：** 組織ロールは組織テンプレートで定義されます。API リソースの権限（スコープ）は組織ロールに割り当てられ、各組織内のユーザーやクライアントに割り当てられます。 +- **コンテキスト認識型の認可 (Authorization)：** クライアントが API リソースと `organization_id` の両方を指定してアクセストークンをリクエストすると、Logto は組織コンテキストと API オーディエンスの両方を含むトークンを発行します。トークンの権限（スコープ）は、指定された組織に対するユーザーの組織ロールによって決定されます。 - **グローバルリソースとの分離：** API リソースは組織コンテキストの有無にかかわらずアクセスできます。組織 RBAC はリクエストに `organization_id` が含まれる場合のみ適用されます。すべてのユーザーで共有される API については [グローバル API リソースの保護](/authorization/global-api-resources) を参照してください。 組織レベルの API リソース RBAC @@ -45,16 +46,16 @@ Logto は、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利 ### 実装概要 \{#implementation-overview} 1. **API リソースを登録**し、Logto でその権限（スコープ）を定義します。 -2. **組織ロールを定義**し、関連する API 権限を割り当てます。 -3. **各組織内でユーザーやクライアントにロールを割り当て**ます。 -4. **API 用のアクセストークンを `organization_id` 付きでリクエスト**し、組織コンテキストを含めます。 -5. **API でアクセストークンを検証**し、組織コンテキストと権限の両方を強制します。 +2. **組織ロールを組織テンプレートで定義**し、関連する API 権限を割り当てます。 +3. **各組織内でユーザーやクライアントにロールを割り当てます。** +4. **`organization_id` を指定して API 用のアクセストークンをリクエストし、組織コンテキストを含めます。** +5. **API でアクセストークンを検証し、組織コンテキストと権限の両方を強制します。** -### Logto における組織 RBAC の適用方法 \{#how-logto-applies-organization-rbac} +### Logto による組織 RBAC の適用方法 \{#how-logto-applies-organization-rbac} - `organization_id` **なし**でアクセストークンをリクエストした場合、グローバルロール／権限のみが考慮されます。 - `organization_id` **あり**でアクセストークンをリクエストした場合、Logto はユーザーの組織ロールとその組織に紐づく権限を評価します。 -- 発行される JWT には API オーディエンス（`aud` クレーム）と組織コンテキスト（`organization_id` クレーム）の両方が含まれ、スコープはユーザーの組織ロールで許可されたものに絞り込まれます。 +- 発行される JWT には、API オーディエンス（`aud` クレーム）と組織コンテキスト（`organization_id` クレーム）の両方が含まれ、スコープはユーザーの組織ロールで許可されたものに絞り込まれます。 ### 認可 (Authorization) フロー：組織コンテキスト付きで API を認証・保護する \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} @@ -73,18 +74,18 @@ sequenceDiagram Logto->>Logto: ユーザーをサインインページへリダイレクト Logto->>Client: `authorization_code` でリダイレクトバック Client->>Logto: POST /oidc/token （`grant_type=authorization_code`） - Logto->>Client: リフレッシュ トークンを返却 + Logto->>Client: リフレッシュ トークンを返す Client->>Logto: POST /oidc/token （`grant_type=refresh_token`
+ resource + organization_id） else マシン間通信 (M2M) クライアント認証 (Authentication) Client->>Logto: POST /oidc/token （`grant_type=client_credentials`
+ resource + organization_id） end - Logto->>Client: アクセス トークン (JWT) を返却 + Logto->>Client: アクセス トークン（JWT）を返す Client->>API: Bearer トークンでリクエスト - API->>API: トークン検証、組織コンテキストと権限を確認 + API->>API: トークンを検証し、組織コンテキストと権限を確認 alt トークンが有効 - API->>Client: 組織データを返却 + API->>Client: 組織データを返す else トークンが無効 API->>Client: 401 Unauthorized end @@ -96,15 +97,16 @@ _ユーザー認証 (Authentication) = ブラウザ／アプリ。M2M = クラ ### API リソースを登録する \{#register-your-api-resource} -1. コンソール → API リソース へ移動します。 -2. 新しい API リソース（例： `https://api.yourapp.com/org` ）を作成し、その権限（スコープ）を定義します。 +1. コンソール → API リソース に移動します。 +2. 新しい API リソース（例： `https://api.yourapp.com/org`）を作成し、その権限（スコープ）を定義します。 詳細な設定手順は [API リソースと権限の定義](/authorization/role-based-access-control#define-api-resources-with-permissions) を参照してください。 ### 組織ロールを設定する \{#set-up-organization-roles} -{/* eslint-disable-next-line prettier/prettier */} -1. コンソール → 組織テンプレート → 組織ロール へ移動します。 +1. + コンソール → 組織テンプレート → 組織ロール + に移動します。 2. 組織ロール（例： `admin`、`member`）を作成し、各ロールに API 権限を割り当てます。 3. 各組織内でユーザーやクライアントにロールを割り当てます。まだメンバーでない場合は、招待または追加してください。 @@ -112,18 +114,18 @@ _ユーザー認証 (Authentication) = ブラウザ／アプリ。M2M = クラ ### API リソース用の組織トークンを取得する \{#obtain-organization-tokens-for-api-resources} -クライアント／アプリは `resource` と `organization_id` の両方を指定してトークンをリクエストし、組織レベルの API へアクセスします。Logto は組織トークンを [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式で発行します。これは [リフレッシュ トークンフロー](https://auth.wiki/refresh-token) または [クライアント認証情報フロー](https://auth.wiki/client-credentials-flow) のいずれかで取得できます。 +クライアント／アプリは、`resource` と `organization_id` の両方を指定してトークンをリクエストすることで、組織レベルの API にアクセスできます。Logto はこれらを [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式の組織トークンとして発行します。[リフレッシュ トークンフロー](https://auth.wiki/refresh-token) または [クライアント認証情報フロー](https://auth.wiki/client-credentials-flow) のいずれかで取得できます。 #### リフレッシュ トークンフロー \{#refresh-token-flow} -ほとんどの Logto 公式 SDK はリフレッシュ トークンフローによる組織トークン取得を標準サポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 +ほとんどの Logto 公式 SDK は、リフレッシュ トークンフローによる組織トークンの取得を標準でサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 -Logto SDK 初期化時に、`urn:logto:scope:organizations` および必要な組織権限（スコープ）を `scopes` パラメーターに追加します。 +Logto SDK の初期化時に、`urn:logto:scope:organizations` および必要な組織権限（スコープ）を `scopes` パラメーターに追加します。 -一部の Logto SDK には組織用のプリセットスコープ（例： JavaScript SDK の `UserScope.Organizations` ）があります。 +一部の Logto SDK には、`UserScope.Organizations` など組織用の事前定義スコープがあります。 @@ -134,39 +136,39 @@ Logto SDK 初期化時に、`urn:logto:scope:organizations` および必要な -OAuth 2.0 クライアントの設定や認可コードフローの初期化時、以下のパラメーターを必ず含めてください： +OAuth 2.0 クライアントの設定や認可コードフローの初期化時に、以下のパラメーターを含めてください： -- `resource`: Logto に登録した API リソース識別子（例： `https://api.your-app.com/organizations` ）を指定。 -- `scope`: プリセットの組織スコープ（`urn:logto:scope:organizations`）、`offline_access`（リフレッシュ トークン取得用）、および必要な API 権限（例： `manage:members view:analytics` ）を含める。 +- `resource`: Logto で登録した API リソース識別子（例： `https://api.your-app.com/organizations`）。 +- `scope`: 事前定義の組織スコープ（`urn:logto:scope:organizations`）、`offline_access`（リフレッシュ トークン取得用）、および必要な API 権限（例： `manage:members view:analytics`）。 -一部のライブラリは `resource` パラメーターを標準サポートしていませんが、通常は認可リクエストで追加パラメーターを渡せます。詳細はライブラリのドキュメントを確認してください。 +一部のライブラリは `resource` パラメーターを標準サポートしていませんが、多くの場合、認可リクエストで追加パラメーターを渡せます。詳細はライブラリのドキュメントを確認してください。 -認可リクエスト例（非規範的）： +認可リクエストの非公式例： -ユーザー認証 (Authentication) 後、認可コードが返却されます。このコードを使い、Logto の `/oidc/token` エンドポイントへ POST リクエストします。 +ユーザーが認証 (Authentication) されると、認可コードが返されます。このコードを使って Logto の `/oidc/token` エンドポイントに POST リクエストします。 -トークンリクエスト例（非規範的）： +トークンリクエストの非公式例： -リフレッシュ トークンが返却され、これを使って組織トークンを取得できます。 +リフレッシュ トークンが返され、これを使って組織トークンを取得できます。 -最後に、リフレッシュ トークンを使い Logto の `/oidc/token` エンドポイントへ POST リクエストし、組織トークンを取得します。以下を必ず含めてください： +最後に、リフレッシュ トークンを使って Logto の `/oidc/token` エンドポイントに POST リクエストし、組織トークンを取得します。以下を必ず含めてください： -- `resource` パラメーター（例： `https://api.yourapp.com/org` ）。 -- `organization_id` パラメーター（対象の組織 ID）。 -- （任意）`scope` パラメーター（例： `manage:members view:reports` など、必要な権限をさらに絞り込む）。 +- `resource` パラメーター：API リソース識別子（例： `https://api.yourapp.com/org`）。 +- `organization_id` パラメーター：対象の組織 ID。 +- （オプション）`scope` パラメーター：必要な権限をさらに絞り込む場合（例： `manage:members view:reports`）。 -トークンリクエスト例（非規範的）： +トークンリクエストの非公式例： ## ベストプラクティスとセキュリティのヒント \{#best-practices-and-security-tips} -- **常に組織コンテキストを検証する：** トークンだけを信用せず、すべての組織スコープ API 呼び出しで `organization_id` クレームを確認してください。 +- **常に組織コンテキストを検証する：** トークンだけを信用せず、組織スコープ API 呼び出しごとに `organization_id` クレームを確認してください。 - **オーディエンス制限を利用する：** `aud` クレームを必ず確認し、トークンが意図した組織用であることを保証してください。 -- **権限はビジネス主導で設計：** 実際のアクションに対応する明確な名前を使い、各組織ロールに必要なものだけを付与してください。 -- **API 権限と非 API 権限は可能な限り分離**（ただし両方を 1 つのロールに含めることも可能）。 -- **トークンの有効期間は短く保つ：** 万一漏洩した場合のリスクを低減します。 +- **権限はビジネス主導で設計する：** 実際のアクションに対応する明確な名前を使い、各組織ロールに必要なものだけを付与してください。 +- **API 権限と非 API 権限は可能な限り分離する**（ただし両方を 1 つのロールに含めることも可能）。 +- **トークンの有効期間は短く保つ：** 万が一漏洩した場合のリスクを低減します。 - **組織テンプレートを定期的に見直す：** 製品の進化に合わせてロールや権限を更新してください。 ## よくある質問 \{#faqs} @@ -229,7 +233,7 @@ Logto が発行する組織トークン（JWT）には、API で組織レベル -グローバルロール／権限のみが評価され、組織 RBAC は適用されません。 +グローバルロール／権限のみが評価されます。組織 RBAC は適用されません。
@@ -240,7 +244,7 @@ Logto が発行する組織トークン（JWT）には、API で組織レベル -いいえ、組織権限（組織レベルの API 権限を含む）は組織テンプレートで定義されており、グローバル API 権限と混在できません。ただし、組織権限と組織レベルの API 権限を両方含むロールは作成できます。 +いいえ、組織権限（組織レベルの API 権限を含む）は組織テンプレートで定義されており、グローバル API 権限と混在できません。ただし、組織権限と組織レベルの API 権限を含むロールは作成できます。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index e6a12b97920..8dc963015d1 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,28 +15,28 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # 組織（非 API）権限の保護 -Logto の組織テンプレートを利用して、組織レベルのロールと権限を管理・適用し、組織コンテキスト内でアプリ内機能やワークフローへのアクセスを制御できます。 +Logto の組織テンプレートを利用して、組織レベルのロールと権限を管理・適用し、組織コンテキスト内でのアプリ機能やワークフローへのアクセスを制御できます。 ## 組織（非 API）権限とは？ \{#what-are-organization-non-api-permissions} -組織権限（非 API）は、**組織コンテキスト内**でユーザーが何をできるかを制御しますが、**API レベルで強制されるものではありません**。代わりに、アプリの機能、UI 要素、ワークフロー、またはビジネスアクションへのアクセスを管理し、バックエンド API ではなくフロントや業務ロジックで適用されます。 +組織権限（非 API）は、**組織コンテキスト内**でユーザーが何をできるかを制御しますが、**API レベルでは強制されません**。代わりに、バックエンド API ではなく、アプリの機能、UI 要素、ワークフロー、ビジネスアクションへのアクセスを管理します。 **ユースケース例** -- 組織内でメンバーを招待・管理する +- 組織内でのメンバー招待や管理 - 組織ロールの割り当てや変更 - 組織の請求、設定、管理機能の管理 - API エンドポイントを持たないダッシュボード、分析、内部ツールへのアクセス -Logto では、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を活用し、マルチテナント SaaS アーキテクチャをサポートしながら、これらの組織権限を安全に管理できます。 +Logto では、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を利用して、これらの組織権限をセキュアに管理でき、マルチテナント SaaS アーキテクチャにも対応しています。 -これらの権限は [組織テンプレート](/authorization/organization-template) で定義された**組織ロール**を通じて管理されます。すべての組織が同じテンプレートを使用するため、全組織で一貫した権限モデルが保証されます。 +これらの権限は [組織テンプレート](/authorization/organization-template) で定義された**組織ロール**を通じて管理されます。すべての組織が同じテンプレートを利用するため、全組織で一貫した権限モデルが保証されます。 ## Logto での仕組み \{#how-it-works-in-logto} -- **組織レベルの RBAC**：ロールと権限は組織テンプレートで定義します。ユーザーが組織に参加すると、1 つ以上のロールが割り当てられ、特定の権限が付与されます。 +- **組織レベルの RBAC**：ロールと権限は組織テンプレートで定義されます。ユーザーが組織に参加すると、1 つ以上のロールが割り当てられ、特定の権限が付与されます。 - **非 API 強制**：権限はアプリの UI、ワークフロー、またはバックエンドロジックでチェック・適用され、必ずしも API ゲートウェイで強制されるわけではありません。 -- **API 保護との分離**：組織（非 API）権限は API リソース権限とは別物です。両者を組み合わせて高度なシナリオにも対応できます。 +- **API 保護との分離**：組織（非 API）権限は API リソース権限とは別物です。高度なシナリオでは両方を組み合わせて利用できます。
組織権限 RBAC @@ -46,33 +47,33 @@ Logto では、OAuth 2.1 とロールベースのアクセス制御 (RBAC) を 1. Logto の組織テンプレートで**組織権限を定義**します。 2. 組織固有のアクションに必要な権限をまとめた**組織ロールを作成**します。 3. 各組織内のユーザーやクライアントに**ロールを割り当て**ます。 -4. リフレッシュトークンまたはクライアントクレデンシャルフローを使って、現在の組織の**組織トークン（JWT）を取得**します。 -5. アプリの UI やバックエンドで**アクセス トークン**を検証し、組織権限を強制します。 +4. **リフレッシュトークンまたはクライアントクレデンシャルフロー**を使って、現在の組織の組織トークン（JWT）を取得します。 +5. アプリの UI やバックエンドで**アクセストークンを検証**し、組織権限を強制します。 ### 認可フロー：組織権限の認証と保護 \{#authorization-flow-authenticating-and-securing-organization-permissions} 以下のフローは、クライアント（Web、モバイル、バックエンド）が非 API 権限の強制のために組織トークンを取得・利用する流れを示しています。 -このフローは必要なパラメーターやヘッダーの詳細をすべて網羅しているわけではなく、主要なステップに焦点を当てています。実際の動作例はこの後の説明を参照してください。 +このフローは必要なパラメータやヘッダーの詳細を網羅しているわけではなく、主要なステップに焦点を当てています。実際の動作例はこの後の説明を参照してください。 ```mermaid sequenceDiagram - participant Client - participant Logto + participant Client as クライアント + participant Logto as Logto participant App as アプリ/UI/バックエンド alt ユーザー認証 Client->>Logto: GET /oidc/auth - Logto->>Logto: ユーザーをサインインページへリダイレクト + Logto->>Logto: サインインページへリダイレクト Logto->>Client: `authorization_code` でリダイレクトバック Client->>Logto: `grant_type=authorization_code` で POST /oidc/token - Logto->>Client: リフレッシュ トークンを返却 - Client->>Logto: `grant_type=refresh_token` + 組織パラメーターで POST /oidc/token + Logto->>Client: リフレッシュトークンを返却 + Client->>Logto: `grant_type=refresh_token` + 組織パラメータで POST /oidc/token else M2M クライアント認証 - Client->>Logto: `grant_type=client_credentials` + 組織パラメーターで POST /oidc/token + Client->>Logto: `grant_type=client_credentials` + 組織パラメータで POST /oidc/token end - Logto->>Client: 組織トークン (JWT) を返却 + Logto->>Client: 組織トークン（JWT）を返却 Client->>App: Bearer トークンでリクエスト App->>App: 組織トークンを検証し、組織コンテキストと権限をチェック @@ -89,51 +90,53 @@ _ユーザー認証 = ブラウザ/アプリ。M2M = クライアントクレデ ### 組織権限の登録 \{#register-organization-permissions} -{/* eslint-disable-next-line prettier/prettier */} -1. コンソール → 組織テンプレート → 組織権限 にアクセスします。 -2. 必要な組織権限を定義します（例：`invite:member`, `manage:billing`, `view:analytics` など）。 +1. + コンソール → 組織テンプレート → 組織権限 + にアクセスします。 +2. 必要な組織権限を定義します（例：`invite:member`、`manage:billing`、`view:analytics` など）。 詳細な設定手順は [組織権限の定義](/authorization/role-based-access-control#define-organization-permissions) を参照してください。 ### 組織ロールの設定 \{#set-up-organization-roles} -{/* eslint-disable-next-line prettier/prettier */} -1. コンソール → 組織テンプレート → 組織ロール にアクセスします。 -2. 先ほど定義した組織権限をまとめたロールを作成します（例：`admin`, `member`, `billing` など）。 +1. + コンソール → 組織テンプレート → 組織ロール + にアクセスします。 +2. 先ほど定義した組織権限をまとめたロールを作成します（例：`admin`、`member`、`billing` など）。 3. これらのロールを各組織内のユーザーやクライアントに割り当てます。 詳細な設定手順は [組織ロールの利用](/authorization/role-based-access-control#configure-organization-roles) を参照してください。 ### 組織トークン（非 API）の取得 \{#obtain-organization-tokens-non-api} -クライアント/アプリは、組織権限へアクセスするために組織トークン（非 API）を取得する必要があります。Logto は組織トークンを [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式で発行します。[リフレッシュ トークンフロー](https://auth.wiki/refresh-token) または [クライアントクレデンシャルフロー](https://auth.wiki/client-credentials-flow) のいずれかで取得できます。 +クライアント/アプリは、組織権限へアクセスするために組織トークン（非 API）を取得する必要があります。Logto は [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式で組織トークンを発行します。[リフレッシュトークンフロー](https://auth.wiki/refresh-token) または [クライアントクレデンシャルフロー](https://auth.wiki/client-credentials-flow) のいずれかで取得できます。 -#### リフレッシュ トークンフロー \{#refresh-token-flow} +#### リフレッシュトークンフロー \{#refresh-token-flow} -ほぼすべての Logto 公式 SDK は、リフレッシュ トークンフローによる組織トークンの取得を標準でサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 +ほぼすべての Logto 公式 SDK は、リフレッシュトークンフローによる組織トークンの取得を標準でサポートしています。標準的な OAuth 2.0 / OIDC クライアントライブラリでもこのフローを実装できます。 -Logto SDK の初期化時に、`urn:logto:scope:organizations` および必要な組織権限（スコープ）を `scopes` パラメーターに追加します。 +Logto SDK を初期化する際、`scopes` パラメータに `urn:logto:scope:organizations` および必要な組織権限（スコープ）を追加します。 -一部の Logto SDK には、`UserScope.Organizations` のような組織用の事前定義スコープがあります（JavaScript SDK など）。 +一部の Logto SDK には、`UserScope.Organizations` など組織用の事前定義スコープがあります。 -`getOrganizationToken` または（組織 ID を指定した）`getAccessToken` などのメソッドで、特定の組織の組織トークンをリクエストします。 +特定の組織の組織トークンをリクエストするには、`getOrganizationToken` または `getAccessToken`（組織 ID 指定）などのメソッドを利用します。 各 SDK の詳細は [クイックスタート](/quick-starts) を参照してください。 - + -OAuth 2.0 クライアントの設定や認可コードフローの初期化時に、以下のパラメーターを含めてください： +OAuth 2.0 クライアントの設定や認可コードフローの初期化時に、以下のパラメータを含めてください： -- `resource`: `urn:logto:resource:organizations` を指定し、組織トークンを要求することを示します。 -- `scope`: 事前定義された組織スコープ（`urn:logto:scope:organizations`）、`offline_access`（リフレッシュ トークン取得用）、および必要な組織権限（例：`invite:member`, `manage:billing` など）を含めます。 +- `resource`：`urn:logto:resource:organizations` を指定し、組織トークンを要求することを示します。 +- `scope`：事前定義の組織スコープ（`urn:logto:scope:organizations`）、`offline_access`（リフレッシュトークン取得用）、および必要な組織権限（例：`invite:member`、`manage:billing` など）を含めます。 -一部のライブラリは `resource` パラメーターを標準サポートしていませんが、多くの場合認可リクエストで追加パラメーターを渡せます。詳細はライブラリのドキュメントを確認してください。 +一部のライブラリは `resource` パラメータをネイティブにサポートしていませんが、通常は認可リクエストで追加パラメータを渡せます。詳細はライブラリのドキュメントを確認してください。 認可リクエストの非公式例： @@ -142,7 +145,7 @@ OAuth 2.0 クライアントの設定や認可コードフローの初期化時 resource="urn:logto:resource:organizations" /> -ユーザーが認証されると、認可コードが返却されます。このコードを使い、Logto の `/oidc/token` エンドポイントへ POST リクエストを送ります。 +ユーザーが認証されると、認可コードが返却されます。このコードを使って Logto の `/oidc/token` エンドポイントに POST リクエストを送信します。 トークンリクエストの非公式例： @@ -150,14 +153,14 @@ OAuth 2.0 クライアントの設定や認可コードフローの初期化時 -リフレッシュ トークンが返却され、組織トークンの取得に利用できます。 +リフレッシュトークンが返却され、組織トークンの取得に利用できます。 -最後に、リフレッシュ トークンを使って Logto の `/oidc/token` エンドポイントへ POST リクエストし、組織トークンを取得します。以下を含めてください： +最後に、リフレッシュトークンを使って Logto の `/oidc/token` エンドポイントに POST リクエストを送り、組織トークンを取得します。以下を含めることを忘れずに： -- `organization_id` パラメーターに希望する組織 ID を指定 -- （オプション）`scope` パラメーターで必要な権限をさらに絞り込む（例：`manage:members view:reports` など） +- `organization_id` パラメータに希望する組織 ID を指定 +- （オプション）`scope` パラメータで必要な権限をさらに絞り込む（例：`manage:members view:reports` など） トークンリクエストの非公式例： @@ -168,14 +171,14 @@ OAuth 2.0 クライアントの設定や認可コードフローの初期化時 #### クライアントクレデンシャルフロー \{#client-credentials-flow} -マシン間通信 (M2M) シナリオでは、クライアントクレデンシャルフローを使って組織権限用のアクセス トークンを取得できます。Logto の `/oidc/token` エンドポイントへ組織パラメーター付きで POST リクエストし、クライアント ID とシークレットで組織トークンをリクエストします。 +マシン間通信 (M2M) シナリオでは、クライアントクレデンシャルフローを利用して組織権限用のアクセストークンを取得できます。Logto の `/oidc/token` エンドポイントに組織パラメータを含めて POST リクエストを送信し、クライアント ID とシークレットで組織トークンをリクエストします。 -リクエストに含める主なパラメーター： +リクエストに含める主なパラメータ： -- `organization_id`: トークンを取得したい組織の ID -- `scope`: 要求したい組織権限（例：`invite:member`, `manage:billing` など） +- `organization_id`：トークンを取得したい組織の ID +- `scope`：リクエストしたい組織権限（例：`invite:member`、`manage:billing` など） -クライアントクレデンシャルグラントタイプでのトークンリクエスト非公式例： +クライアントクレデンシャルグラントタイプによるトークンリクエストの非公式例： ## ベストプラクティスとセキュリティのヒント \{#best-practices-and-security-tips} - **UI のみの強制に頼らない**：重要なアクションは必ずバックエンドでも権限を検証してください。 -- **オーディエンス制限を利用**：`aud` クレームを必ずチェックし、トークンが意図した組織用であることを確認してください。 +- **オーディエンス制限を利用**：`aud` クレームを必ず確認し、トークンが意図した組織用であることを保証してください。 - **ビジネス主導の権限設計**：実際のアクションに対応する明確な名前を使い、各組織ロールに必要なものだけを付与してください。 -- **API 権限と非 API 権限は可能な限り分離**（ただし 1 つのロールに両方含めることも可能） -- **プロダクトの進化に合わせて組織テンプレートを定期的に見直す** +- **API 権限と非 API 権限は可能な限り分離**（ただし両方を 1 つのロールに含めることも可能）。 +- **プロダクトの進化に合わせて組織テンプレートを定期的に見直す**。 ## よくある質問 \{#faqs} @@ -224,13 +229,13 @@ Logto が発行する組織トークン（JWT）には、アプリ/UI/バック -非 API 権限は、UI（機能制御用）とサーバーサイドロジック（機密アクション用）の両方でチェックしてください。 +非 API 権限は、UI（機能制御用）とサーバーサイドロジック（重要なアクション用）の両方でチェックしてください。 ## さらに読む \{#further-reading} -アクセス トークンの検証方法 +アクセストークンの検証方法 トークンクレームのカスタマイズ ユースケース：マルチテナント SaaS アプリケーションの構築 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..bec60e14ca6 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### 선택 사항: 사용자 권한 변경 처리 \{#optional-handle-user-permission-change} + +사용자 권한은 언제든지 변경될 수 있습니다. Logto는 RBAC를 위해 JWT를 발급하므로, 권한 업데이트는 새로 발급된 토큰에만 반영되며 기존 JWT는 절대 수정되지 않습니다. + +:::info 스코프 (Scope) 하위 집합 규칙 +액세스 토큰 (Access token)은 원래 OAuth 인가 (Authorization) 플로우에서 요청된 스코프 (Scope)만 포함할 수 있습니다. +사용자가 새로운 권한을 얻더라도, 이후에 발급된 토큰은 원래 요청된 스코프의 하위 집합만 포함할 수 있습니다. +초기 요청에 포함되지 않은 새로 부여된 스코프에 접근하려면, 클라이언트는 새로운 인가 (Authorization) 플로우를 실행해야 합니다. +::: + +#### 축소된 권한 (Downscoped permissions) \{#downscoped-permissions} + +사용자가 권한을 잃었을 때: + +- 새로 발급된 토큰은 즉시 축소된 스코프를 반영합니다. +- 기존 JWT는 만료될 때까지 이전 스코프를 유지합니다. +- API에서는 항상 스코프를 검증하고, 짧은 토큰 수명을 사용하는 것이 좋습니다. + +더 빠른 반응이 필요하다면, 클라이언트에게 토큰을 새로고침하라는 신호를 직접 구현하세요. + +#### 확장된 권한 (Enlarged permissions) \{#enlarged-permissions} + +{props.type === "global" &&

글로벌 API 리소스의 경우, 사용자가 권한을 얻으면 확장된 권한은 새로고침을 통해 나타나지 않습니다. 클라이언트는 새로운 OAuth 인가 (Authorization) 플로우를 수행해야 새로운 스코프가 포함된 토큰을 받을 수 있습니다. 사용자가 활성 Logto 세션을 가지고 있다면 이 과정은 자동으로(조용히) 진행될 수 있습니다.

} + +{props.type === "organization" &&

조직 토큰의 경우, 사용자가 권한을 얻으면 확장된 권한은 다음 발급(새로고침 또는 토큰 요청) 시 반영됩니다. 새로운 토큰이 필요하지만, 새로운 스코프가 원래 요청 범위를 초과하지 않는 한 전체 재인증은 필요하지 않습니다.

} + +#### 권장 사항 \{#recommendations} + +- API 호출마다 스코프를 검증하세요. +- 토큰 만료 시간을 짧게 유지하세요. +- 즉각적인 권한 변경 전파가 필요하다면, 선택적으로 알림 기능을 추가하세요. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 722be432aeb..0c38ebd15d3 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -17,12 +18,12 @@ Logto에서 역할 기반 접근 제어 (RBAC)를 사용하여 제품 전체의 ## 글로벌 API 리소스란 무엇인가요? \{#what-are-global-api-resources} -글로벌 API 리소스는 조직 또는 테넌트와 상관없이 모든 사용자가 접근할 수 있는 애플리케이션 내 엔드포인트 또는 서비스입니다. 일반적으로 공개 API, 핵심 제품 서비스, 또는 특정 조직에 한정되지 않은 엔드포인트가 이에 해당합니다. +글로벌 API 리소스는 조직이나 테넌트와 상관없이 모든 사용자가 접근할 수 있는 애플리케이션 내 엔드포인트 또는 서비스입니다. 일반적으로 공개 API, 핵심 제품 서비스, 또는 특정 조직에 한정되지 않은 엔드포인트가 이에 해당합니다. **사용 사례 예시** -- 사용자 기반 전체에 공유되는 공개 API 또는 엔드포인트 -- 다중 테넌시와 연결되지 않은 마이크로서비스 +- 사용자 전체에 공유되는 공개 API 또는 엔드포인트 +- 다중 테넌시에 묶이지 않은 마이크로서비스 - 모든 고객이 사용하는 핵심 애플리케이션 API (예: `/api/users`, `/api/products`) Logto는 OAuth 2.1과 유연한 역할 기반 접근 제어를 결합하여 이러한 API를 안전하게 보호할 수 있도록 지원합니다. @@ -37,11 +38,11 @@ Logto는 OAuth 2.1과 유연한 역할 기반 접근 제어를 결합하여 이 ### 구현 개요 \{#implementation-overview} -1. **API 리소스를 등록**하고 Logto에서 해당 권한을 정의합니다. -2. **API 접근에 필요한 권한을 가진 역할을 정의**합니다. -3. **역할을 사용자 또는 클라이언트에 할당**합니다. -4. **OAuth 2.0 인가 플로우**를 사용하여 API용 액세스 토큰을 획득합니다 (resource 파라미터는 등록된 API 식별자와 일치해야 합니다). -5. **API에서 액세스 토큰을 검증**하여 권한을 적용합니다. +1. **API 리소스를 등록**하고 Logto에서 해당 권한을 정의하세요. +2. **API 접근에 필요한 권한을 가진 역할을 정의**하세요. +3. **역할을 사용자 또는 클라이언트에 할당**하세요. +4. **OAuth 2.0 인가 플로우**를 사용하여 API에 대한 액세스 토큰을 획득하세요 (resource 파라미터는 등록된 API 식별자와 일치해야 합니다). +5. **API에서 액세스 토큰을 검증**하여 권한을 적용하세요. ### 리소스 지표 이해하기 \{#understanding-resource-indicators} @@ -62,21 +63,21 @@ Logto는 [RFC 8707: OAuth 2.0을 위한 리소스 지표](https://www.rfc-editor 아래 플로우는 상호작용 사용자 인증 (브라우저/앱)과 백엔드 기계 간 (M2M) 시나리오 모두에 적용됩니다. -이 플로우는 필수 파라미터나 헤더에 대한 모든 세부사항을 포함하지 않으며, 주요 단계에 초점을 맞추고 있습니다. 실제 동작 방식은 아래 내용을 계속 읽어보세요. +이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 주요 단계에 초점을 맞추고 있습니다. 실제 동작 방식은 아래 내용을 계속 읽어보세요. ```mermaid sequenceDiagram - participant Client as 클라이언트 - participant Logto as Logto + participant Client + participant Logto participant API as API 리소스 alt 사용자 인증 Client->>Logto: GET /oidc/auth Logto->>Logto: 사용자를 로그인 페이지로 리디렉션 Logto->>Client: `authorization_code`와 함께 다시 리디렉션 - alt authorization_code 그랜트 사용 + alt authorization_code grant 사용 Client->>Logto: POST /oidc/token, `grant_type=authorization_code`
및 `resource` 파라미터 포함 - else refresh_token 그랜트 사용 + else refresh_token grant 사용 Client->>Logto: POST /oidc/token, `grant_type=authorization_code` Logto->>Client: 리프레시 토큰 반환 Client->>Logto: POST /oidc/token, `grant_type=refresh_token`
및 `resource` 파라미터 포함 @@ -92,7 +93,7 @@ sequenceDiagram alt 토큰이 유효함 API->>Client: 보호된 리소스 데이터 반환 else 토큰이 유효하지 않음 - API->>Client: 401 인가되지 않음 + API->>Client: 401 Unauthorized end ``` @@ -106,16 +107,16 @@ _사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명을 사 ### API 리소스 등록하기 \{#register-your-api-resources} -1. 콘솔 → API 리소스로 이동합니다. -2. 새 API 리소스 (예: `https://api.yourapp.com/org`)를 생성하고, 해당 권한(스코프)을 정의합니다. +1. 콘솔 → API 리소스로 이동하세요. +2. 새 API 리소스 (예: `https://api.yourapp.com/org`)를 생성하고, 해당 권한(스코프)을 정의하세요. 전체 설정 단계는 [권한과 함께 API 리소스 정의하기](/authorization/role-based-access-control#define-api-resources-with-permissions)를 참고하세요. ### 글로벌 역할 설정하기 \{#set-up-global-roles} -1. 콘솔 → 역할로 이동합니다. -2. API 권한에 매핑되는 역할을 생성합니다 (예: `read:products`, `write:products`). -3. 이 역할을 API 접근이 필요한 사용자 또는 클라이언트에 할당합니다. +1. 콘솔 → 역할로 이동하세요. +2. API 권한에 매핑되는 역할을 생성하세요 (예: `read:products`, `write:products`). +3. 이 역할을 API 접근이 필요한 사용자 또는 클라이언트에 할당하세요. 전체 설정 단계는 [글로벌 역할 사용하기](/authorization/role-based-access-control#configure-global-roles)를 참고하세요. @@ -139,23 +140,23 @@ Logto 클라이언트 초기화 시, `resources` 파라미터(배열)에 리소 -OAuth 2.0 클라이언트 구성 또는 인가 코드 플로우 초기화 시, 인가 요청에 `resource` 파라미터와 원하는 스코프를 반드시 포함하세요. +OAuth 2.0 클라이언트 설정 또는 인가 코드 플로우 초기화 시, 인가 요청에 `resource` 파라미터와 원하는 스코프를 반드시 포함하세요. -일부 라이브러리는 `resource` 파라미터를 기본 지원하지 않을 수 있지만, 일반적으로 인가 요청에 추가 파라미터를 전달할 수 있습니다. 자세한 내용은 사용 중인 라이브러리의 문서를 참고하세요. +일부 라이브러리는 `resource` 파라미터를 기본 지원하지 않을 수 있지만, 일반적으로 인가 요청에 추가 파라미터를 전달할 수 있습니다. 자세한 내용은 사용하는 라이브러리의 문서를 참고하세요. -다음은 `resource` 및 `scope` 파라미터가 포함된 인가 요청의 비표준 예시입니다: +다음은 `resource` 및 `scope` 파라미터가 포함된 인가 요청의 비공식 예시입니다: 사용자가 인증되면, 인가 코드를 받게 됩니다. 이 코드를 Logto의 `/oidc/token` 엔드포인트에 POST 요청하여 액세스 토큰으로 교환하세요. 이때 요청 본문에 `resource` 파라미터를 포함해야 합니다. -다음은 authorization_code 그랜트 타입을 사용하는 토큰 요청의 비표준 예시입니다: +다음은 authorization code grant 타입을 사용하는 토큰 요청의 비공식 예시입니다: -사용자 상호작용 없이 새로운 액세스 토큰을 얻으려면, `refresh_token` 그랜트 타입을 사용할 수 있습니다. 이때도 요청에 `resource` 파라미터를 포함해야 합니다. +사용자 상호작용 없이 새로운 액세스 토큰을 얻으려면, `refresh_token` grant 타입을 사용할 수 있습니다. 이때도 `resource` 파라미터를 요청에 포함해야 합니다. -다음은 refresh_token 그랜트 타입을 사용하는 토큰 요청의 비표준 예시입니다: +다음은 refresh token grant 타입을 사용하는 토큰 요청의 비공식 예시입니다: @@ -164,14 +165,14 @@ OAuth 2.0 클라이언트 구성 또는 인가 코드 플로우 초기화 시, #### 클라이언트 자격 증명 플로우 \{#client-credentials-flow} -기계 간 (M2M) 시나리오에서는 클라이언트 자격 증명 플로우를 사용하여 글로벌 API 리소스용 액세스 토큰을 획득할 수 있습니다. Logto의 `/oidc/token` 엔드포인트에 POST 요청을 보내면, 클라이언트 ID와 시크릿을 사용하여 액세스 토큰을 요청할 수 있습니다. +기계 간 (M2M) 시나리오에서는 클라이언트 자격 증명 플로우를 사용하여 글로벌 API 리소스용 액세스 토큰을 획득할 수 있습니다. Logto의 `/oidc/token` 엔드포인트에 POST 요청을 보내 클라이언트 ID와 시크릿으로 액세스 토큰을 요청하세요. 요청에 반드시 포함해야 할 주요 파라미터는 다음과 같습니다: - `resource`: 접근하려는 API의 리소스 지표 URI (예: `https://api.yourapp.com`) - `scope`: API에 요청할 권한 (예: `read:products write:products`) -다음은 클라이언트 자격 증명 그랜트 타입을 사용하는 토큰 요청의 비표준 예시입니다: +다음은 클라이언트 자격 증명 grant 타입을 사용하는 토큰 요청의 비공식 예시입니다: ## 모범 사례 및 보안 팁 \{#best-practices-and-security-tips} - **권한은 비즈니스 중심으로 유지하세요:** 실제 동작에 매핑되는 명확한 이름을 사용하세요. -- **토큰 만료는 짧게 유지하세요:** 토큰이 유출될 경우 위험을 줄일 수 있습니다. +- **토큰 만료 시간을 짧게 유지하세요:** 토큰이 유출될 경우 위험을 줄일 수 있습니다. - **부여하는 스코프를 제한하세요:** 토큰에 실제로 필요한 권한만 부여하세요. -- **대상 제한 사용:** 오용 방지를 위해 항상 `aud` 클레임을 검증하세요. +- **대상 제한 사용:** `aud` 클레임을 항상 검증하여 오용을 방지하세요. ## 자주 묻는 질문 \{#faqs} @@ -214,7 +211,7 @@ API가 Logto 발급 액세스 토큰이 포함된 요청을 받으면 다음을 -Logto 콘솔에서 기본 API 리소스를 설정하세요. 토큰 요청에 resource 파라미터가 지정되지 않으면 이 audience가 기본값으로 사용됩니다. +Logto 콘솔에서 기본 API 리소스를 설정하세요. 토큰 요청에 resource 파라미터가 지정되지 않은 경우, 해당 audience가 기본값으로 사용됩니다. @@ -275,7 +272,7 @@ scopes: ["read", "write"] // ❌ 권한 이름과 일치하지 않음 -## 추가 자료 \{#further-reading} +## 추가 참고 자료 \{#further-reading} 액세스 토큰 검증 방법 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 6e859b63059..b2f3f35d4f8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -20,47 +21,47 @@ API 리소스와 조직 템플릿을 결합하여 각 조직 내에서 API 및 ## 조직 수준 API 리소스란? \{#what-are-organization-level-api-resources} -조직 수준 API 리소스는 애플리케이션 내에서 **특정 조직에 범위가 지정된** 엔드포인트 또는 서비스입니다. 이러한 API는 조직 컨텍스트에 따라 인가 (Authorization) 및 접근을 강제하여, 사용자 또는 클라이언트가 자신의 조직과 관련된 데이터 및 작업만 접근하도록 보장합니다. +조직 수준 API 리소스는 **특정 조직에 범위가 지정된** 애플리케이션의 엔드포인트 또는 서비스입니다. 이러한 API는 조직 컨텍스트에 따라 인가 (Authorization)와 접근을 강제하여, 사용자 또는 클라이언트가 자신의 조직과 관련된 데이터 및 작업만 접근할 수 있도록 보장합니다. **사용 사례 예시** - 조직 구성원, 역할 또는 설정을 관리하는 API (예: `/organizations/{organizationId}/members`) - 조직 범위의 대시보드, 분석, 리포트 - 조직에 연결된 결제, 구독, 감사 엔드포인트 -- 작업 및 데이터가 테넌트별로 분리되는 모든 API +- 테넌트별로 작업과 데이터가 분리되어야 하는 모든 API -Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 사용하여 이러한 조직 API를 보호할 수 있도록 하며, 멀티 테넌트 SaaS 아키텍처를 지원합니다. +Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 활용하여 이러한 조직 API를 안전하게 보호하며, 멀티 테넌트 SaaS 아키텍처를 지원합니다. -이러한 권한은 [조직 템플릿](/authorization/organization-template)에 정의된 **조직 역할**을 통해 관리됩니다. 모든 조직은 동일한 템플릿을 사용하므로, 모든 조직에서 일관된 권한 모델이 보장됩니다. +이러한 권한은 [조직 템플릿](/authorization/organization-template)에 정의된 **조직 역할**을 통해 관리됩니다. 모든 조직은 동일한 템플릿을 사용하므로, 모든 조직에 일관된 권한 모델이 적용됩니다. ## Logto에서의 동작 방식 \{#how-it-works-in-logto} -- **API 리소스와 권한은 전역적으로 등록됩니다:** 각 API 리소스는 Logto에서 고유한 리소스 지표 (URI)와 권한(스코프) 집합으로 정의됩니다. -- **조직 수준의 역할:** 조직 역할은 조직 템플릿에서 정의됩니다. API 리소스 권한(스코프)은 조직 역할에 할당되며, 각 조직 내의 사용자 또는 클라이언트에 할당됩니다. +- **API 리소스와 권한은 전역적으로 등록됨:** 각 API 리소스는 Logto에서 고유한 리소스 지표 (URI)와 권한(스코프) 집합으로 정의됩니다. +- **조직 수준의 역할:** 조직 역할은 조직 템플릿에서 정의됩니다. API 리소스 권한(스코프)은 조직 역할에 할당되고, 각 조직 내의 사용자 또는 클라이언트에 할당됩니다. - **컨텍스트 인식 인가:** 클라이언트가 API 리소스와 `organization_id`를 함께 포함하여 액세스 토큰을 요청하면, Logto는 조직 컨텍스트와 API 대상이 모두 포함된 토큰을 발급합니다. 토큰의 권한(스코프)은 지정된 조직에 대한 사용자의 조직 역할에 따라 결정됩니다. -- **글로벌 리소스와의 분리:** API 리소스는 조직 컨텍스트와 함께 또는 없이 접근할 수 있습니다. 조직 RBAC는 요청에 `organization_id`가 포함된 경우에만 적용됩니다. 모든 사용자가 공유하는 API에 대해서는 [글로벌 API 리소스 보호하기](/authorization/global-api-resources)를 참고하세요. +- **전역 리소스와의 분리:** API 리소스는 조직 컨텍스트와 함께 또는 없이 접근할 수 있습니다. 조직 RBAC는 요청에 `organization_id`가 포함된 경우에만 적용됩니다. 모든 사용자에게 공유되는 API의 경우 [전역 API 리소스 보호하기](/authorization/global-api-resources)를 참고하세요. 조직 수준 API 리소스 RBAC ### 구현 개요 \{#implementation-overview} -1. **API 리소스를 등록**하고 Logto에서 권한(스코프)을 정의하세요. +1. **API 리소스를 등록**하고, Logto에서 해당 권한(스코프)을 정의하세요. 2. **조직 역할을 정의**하고, 관련 API 권한을 할당하세요. 3. **각 조직 내에서 사용자 또는 클라이언트에 역할을 할당**하세요. -4. **API에 대한 액세스 토큰을 `organization_id`와 함께 요청**하여 조직 컨텍스트를 포함하세요. +4. **API에 대한 액세스 토큰을 요청**할 때 `organization_id`를 포함하여 조직 컨텍스트를 추가하세요. 5. **API에서 액세스 토큰을 검증**하여 조직 컨텍스트와 권한을 모두 강제하세요. -### Logto가 조직 RBAC를 적용하는 방식 \{#how-logto-applies-organization-rbac} +### Logto의 조직 RBAC 적용 방식 \{#how-logto-applies-organization-rbac} -- `organization_id` **없이** 액세스 토큰을 요청하면, 글로벌 역할/권한만 고려됩니다. -- `organization_id` **와 함께** 액세스 토큰을 요청하면, Logto는 해당 조직에 대한 사용자의 조직 역할 및 관련 권한을 평가합니다. -- 결과 JWT에는 API 대상 (`aud` 클레임)과 조직 컨텍스트 (`organization_id` 클레임)가 모두 포함되며, 스코프는 사용자의 조직 역할에 의해 부여된 권한으로 필터링됩니다. +- `organization_id` 없이 액세스 토큰을 요청하면, 전역 역할/권한만 고려됩니다. +- `organization_id`와 함께 액세스 토큰을 요청하면, Logto는 해당 조직에 대한 사용자의 조직 역할과 연결된 권한을 평가합니다. +- 결과 JWT에는 API 대상(`aud` 클레임)과 조직 컨텍스트(`organization_id` 클레임)가 모두 포함되며, 스코프는 사용자의 조직 역할에 의해 부여된 권한으로 필터링됩니다. -### 인가 흐름: 조직 컨텍스트로 API 인증 및 보호하기 \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} +### 인가 플로우: 조직 컨텍스트로 API 인증 및 보호하기 \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} -다음 흐름은 클라이언트(웹, 모바일, 백엔드)가 조직 토큰을 획득하고 조직 수준 API 리소스에 접근하는 방법을 보여줍니다. +다음 플로우는 클라이언트(웹, 모바일, 백엔드)가 조직 토큰을 획득하고, 조직 수준 API 리소스에 접근하는 과정을 보여줍니다. -이 흐름은 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 주요 단계에 초점을 맞추고 있습니다. 실제 흐름이 어떻게 동작하는지 계속 읽어보세요. +이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 핵심 단계에 초점을 맞추고 있습니다. 실제 동작 방식을 계속 읽어보세요. ```mermaid sequenceDiagram @@ -71,35 +72,35 @@ sequenceDiagram alt 사용자 인증 Client->>Logto: GET /oidc/auth Logto->>Logto: 사용자를 로그인 페이지로 리디렉션 - Logto->>Client: `authorization_code`로 다시 리디렉션 - Client->>Logto: POST /oidc/token, `grant_type=authorization_code` + Logto->>Client: `authorization_code`와 함께 다시 리디렉션 + Client->>Logto: POST /oidc/token (`grant_type=authorization_code`) Logto->>Client: 리프레시 토큰 반환 - Client->>Logto: POST /oidc/token, `grant_type=refresh_token`
+ resource + organization_id + Client->>Logto: POST /oidc/token (`grant_type=refresh_token`
+ resource + organization_id) else 기계 간 (M2M) 클라이언트 인증 - Client->>Logto: POST /oidc/token, `grant_type=client_credentials`
+ resource + organization_id + Client->>Logto: POST /oidc/token (`grant_type=client_credentials`
+ resource + organization_id) end - Logto->>Client: 액세스 토큰 (JWT) 반환 + Logto->>Client: 액세스 토큰(JWT) 반환 Client->>API: Bearer 토큰으로 요청 API->>API: 토큰 검증, 조직 컨텍스트 및 권한 확인 alt 토큰이 유효함 API->>Client: 조직 데이터 반환 else 토큰이 유효하지 않음 - API->>Client: 401 Unauthorized + API->>Client: 401 인가되지 않음 end ``` -_사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명 + 조직 컨텍스트를 사용하는 백엔드 서비스 또는 스크립트._ +_사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격증명 + 조직 컨텍스트를 사용하는 백엔드 서비스 또는 스크립트._ ## 구현 단계 \{#implementation-steps} ### API 리소스 등록하기 \{#register-your-api-resource} 1. 콘솔 → API 리소스로 이동하세요. -2. 새 API 리소스(예: `https://api.yourapp.com/org`)를 생성하고 권한(스코프)을 정의하세요. +2. 새 API 리소스(예: `https://api.yourapp.com/org`)를 생성하고, 해당 권한(스코프)을 정의하세요. -전체 설정 단계는 [권한과 함께 API 리소스 정의하기](/authorization/role-based-access-control#define-api-resources-with-permissions)를 참고하세요. +전체 설정 방법은 [권한과 함께 API 리소스 정의하기](/authorization/role-based-access-control#define-api-resources-with-permissions)를 참고하세요. ### 조직 역할 설정하기 \{#set-up-organization-roles} @@ -107,14 +108,14 @@ _사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명 + 조 콘솔 → 조직 템플릿 → 조직 역할 로 이동하세요. -2. 조직 역할(예: `admin`, `member`)을 생성하고 각 역할에 API 권한을 할당하세요. -3. 각 조직 내에서 사용자 또는 클라이언트에 역할을 할당하세요. 아직 멤버가 아니라면 먼저 초대하거나 추가하세요. +2. 조직 역할(예: `admin`, `member`)을 생성하고, 각 역할에 API 권한을 할당하세요. +3. 각 조직 내에서 사용자 또는 클라이언트에 역할을 할당하세요. 아직 멤버가 아니라면 초대하거나 먼저 추가하세요. -전체 설정 단계는 [조직 역할 사용하기](/authorization/role-based-access-control#configure-organization-roles)를 참고하세요. +전체 설정 방법은 [조직 역할 사용하기](/authorization/role-based-access-control#configure-organization-roles)를 참고하세요. ### API 리소스를 위한 조직 토큰 획득하기 \{#obtain-organization-tokens-for-api-resources} -클라이언트/앱은 조직 수준 API에 접근하기 위해 `resource`와 `organization_id`를 모두 포함하여 토큰을 요청해야 합니다. Logto는 조직 토큰을 [JSON Web Token (JWT)](https://auth.wiki/jwt) 형태로 발급합니다. [리프레시 토큰 플로우](https://auth.wiki/refresh-token) 또는 [클라이언트 자격 증명 플로우](https://auth.wiki/client-credentials-flow)를 사용할 수 있습니다. +클라이언트/앱은 조직 수준 API에 접근하기 위해 `resource`와 `organization_id`를 모두 포함하여 토큰을 요청해야 합니다. Logto는 조직 토큰을 [JSON Web Token (JWT)](https://auth.wiki/jwt) 형태로 발급합니다. [리프레시 토큰 플로우](https://auth.wiki/refresh-token) 또는 [클라이언트 자격증명 플로우](https://auth.wiki/client-credentials-flow)를 사용할 수 있습니다. #### 리프레시 토큰 플로우 \{#refresh-token-flow} @@ -123,9 +124,9 @@ _사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명 + 조 -Logto SDK를 초기화할 때, `urn:logto:scope:organizations`와 원하는 조직 권한(스코프)을 `scopes` 파라미터에 추가하세요. +Logto SDK를 초기화할 때, `scopes` 파라미터에 `urn:logto:scope:organizations`와 원하는 조직 권한(스코프)을 추가하세요. -일부 Logto SDK에는 조직을 위한 미리 정의된 스코프가 있습니다. 예를 들어 JavaScript SDK의 `UserScope.Organizations` 등입니다. +일부 Logto SDK에는 조직용 미리 정의된 스코프가 있습니다. 예를 들어 JavaScript SDK에서는 `UserScope.Organizations`가 있습니다. @@ -136,14 +137,14 @@ Logto SDK를 초기화할 때, `urn:logto:scope:organizations`와 원하는 조 -OAuth 2.0 클라이언트를 구성하거나 인증 코드 플로우를 초기화할 때, 다음 파라미터를 포함해야 합니다: +OAuth 2.0 클라이언트를 구성하거나 인가 코드 플로우를 초기화할 때, 다음 파라미터를 포함해야 합니다: - `resource`: Logto에 등록된 API 리소스 식별자(예: `https://api.your-app.com/organizations`). - `scope`: 미리 정의된 조직 스코프(`urn:logto:scope:organizations`), `offline_access`(리프레시 토큰 획득용), 그리고 필요한 API 권한(예: `manage:members view:analytics`)을 포함하세요. -일부 라이브러리는 `resource` 파라미터를 기본적으로 지원하지 않을 수 있지만, 보통 인가 요청에 추가 파라미터를 전달할 수 있습니다. 자세한 내용은 라이브러리 문서를 참고하세요. +일부 라이브러리는 `resource` 파라미터를 기본적으로 지원하지 않을 수 있지만, 일반적으로 인가 요청에 추가 파라미터를 전달할 수 있습니다. 자세한 내용은 라이브러리 문서를 참고하세요. -다음은 인가 요청의 비공식 예시입니다: +다음은 인가 요청 예시입니다: @@ -162,13 +163,13 @@ OAuth 2.0 클라이언트를 구성하거나 인증 코드 플로우를 초기 -마지막으로, 리프레시 토큰을 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 하여 조직 토큰을 획득하세요. 다음을 반드시 포함하세요: +마지막으로, 리프레시 토큰을 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 통해 조직 토큰을 획득하세요. 다음을 반드시 포함하세요: -- `resource` 파라미터: API 리소스 식별자(예: `https://api.yourapp.com/org`). -- `organization_id` 파라미터: 원하는 조직 ID. -- (선택) `scope` 파라미터: 필요한 권한만큼 스코프를 축소(예: `manage:members view:reports`). +- `resource` 파라미터: API 리소스 식별자(예: `https://api.yourapp.com/org`) +- `organization_id` 파라미터: 원하는 조직 ID +- (선택) `scope` 파라미터: 필요한 권한만 추가로 지정(예: `manage:members view:reports`) -다음은 토큰 요청의 비공식 예시입니다: +다음은 토큰 요청 예시입니다: -#### 클라이언트 자격 증명 플로우 \{#client-credentials-flow} +#### 클라이언트 자격증명 플로우 \{#client-credentials-flow} -기계 간 (M2M) 시나리오에서는 클라이언트 자격 증명 플로우를 사용하여 조직 수준 API 리소스 권한에 대한 액세스 토큰을 획득할 수 있습니다. Logto의 `/oidc/token` 엔드포인트에 조직 파라미터와 함께 POST 요청을 하여, 클라이언트 ID와 시크릿으로 조직 토큰을 요청하세요. +기계 간 (M2M) 시나리오에서는 클라이언트 자격증명 플로우를 사용하여 조직 수준 API 리소스 권한에 대한 액세스 토큰을 획득할 수 있습니다. Logto의 `/oidc/token` 엔드포인트에 조직 파라미터와 함께 POST 요청을 보내면, 클라이언트 ID와 시크릿으로 조직 토큰을 요청할 수 있습니다. 요청에 포함해야 할 주요 파라미터는 다음과 같습니다: -- `resource`: API 리소스 식별자(예: `https://api.yourapp.com/org`). -- `organization_id`: 토큰을 받고자 하는 조직의 ID. -- `scope`: 요청하려는 조직 수준 API 리소스 권한(예: `invite:member`, `manage:billing`). +- `resource`: API 리소스 식별자(예: `https://api.yourapp.com/org`) +- `organization_id`: 토큰을 받고자 하는 조직의 ID +- `scope`: 요청할 조직 수준 API 리소스 권한(예: `invite:member`, `manage:billing`) -다음은 클라이언트 자격 증명 grant 타입을 사용하는 토큰 요청의 비공식 예시입니다: +다음은 클라이언트 자격증명 grant 타입을 사용하는 토큰 요청 예시입니다: + ## 모범 사례 및 보안 팁 \{#best-practices-and-security-tips} - **항상 조직 컨텍스트를 검증하세요:** 토큰만 신뢰하지 말고, 조직 범위 API 호출마다 `organization_id` 클레임을 확인하세요. - **대상 제한 사용:** 항상 `aud` 클레임을 확인하여 토큰이 의도한 조직용인지 확인하세요. -- **권한은 비즈니스 중심으로:** 실제 작업에 매핑되는 명확한 이름을 사용하고, 각 조직 역할에 필요한 권한만 부여하세요. -- **API 및 비 API 권한을 분리**하세요(가능하다면, 단일 역할에 모두 포함할 수 있습니다). +- **비즈니스 중심의 권한 유지:** 실제 동작에 매핑되는 명확한 이름을 사용하고, 각 조직 역할에 필요한 권한만 부여하세요. +- **API와 비 API 권한을 분리**하세요(가능하다면, 단일 역할에 모두 포함할 수도 있습니다). - **토큰 수명은 짧게 유지:** 토큰이 유출될 경우 위험을 줄입니다. - **조직 템플릿을 정기적으로 검토:** 제품이 발전함에 따라 역할과 권한을 업데이트하세요. @@ -231,7 +234,7 @@ Logto가 발급한 조직 토큰(JWT)에는 API가 조직 수준 접근 제어 -글로벌 역할/권한만 평가됩니다. 조직 RBAC는 적용되지 않습니다. +전역 역할/권한만 평가됩니다. 조직 RBAC는 적용되지 않습니다. @@ -242,7 +245,7 @@ Logto가 발급한 조직 토큰(JWT)에는 API가 조직 수준 접근 제어 -아니요, 조직 권한(조직 수준 API 권한 포함)은 조직 템플릿에 의해 정의되며 글로벌 API 권한과 혼합할 수 없습니다. 그러나 조직 권한과 조직 수준 API 권한을 모두 포함하는 역할을 생성할 수 있습니다. +아니요, 조직 권한(조직 수준 API 권한 포함)은 조직 템플릿에 의해 정의되며, 전역 API 권한과 혼합할 수 없습니다. 하지만, 조직 권한과 조직 수준 API 권한을 모두 포함하는 역할을 생성할 수는 있습니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 52ac78e21e6..0f4d15a42c4 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,20 +15,20 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # 조직 (비 API) 권한 보호 -조직 템플릿을 사용하여 Logto에서 조직 수준의 역할과 권한을 관리하고 적용하세요. 이를 통해 조직 컨텍스트 내에서 인앱 기능 및 워크플로우에 대한 접근을 제어할 수 있습니다. +조직 템플릿을 사용하여 Logto에서 조직 수준의 역할 및 권한을 관리하고 적용하세요. 이를 통해 조직 컨텍스트 내에서 앱 기능 및 워크플로우에 대한 접근을 제어할 수 있습니다. ## 조직 (비 API) 권한이란? \{#what-are-organization-non-api-permissions} -조직 권한(비 API)은 **조직 컨텍스트 내**에서 사용자가 무엇을 할 수 있는지 제어하지만, **API 수준에서 강제 적용되지는 않습니다**. 대신, 백엔드 API가 아닌 앱 기능, UI 요소, 워크플로우 또는 비즈니스 액션에 대한 접근을 관리합니다. +조직 권한(비 API)은 사용자가 **조직 컨텍스트 내에서** 무엇을 할 수 있는지를 제어하지만, **API 수준에서 강제 적용되지는 않습니다**. 대신, 백엔드 API가 아닌 앱 기능, UI 요소, 워크플로우 또는 비즈니스 액션에 대한 접근을 관리합니다. -**사용 예시** +**사용 사례 예시** - 조직 내에서 멤버 초대 또는 관리 - 조직 역할 할당 또는 변경 - 조직의 결제, 설정, 관리 기능 관리 - API 엔드포인트가 없는 대시보드, 분석, 내부 도구 접근 -Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 사용하여 이러한 조직 권한을 안전하게 보호할 수 있으며, 다중 테넌트 SaaS 아키텍처도 지원합니다. +Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 사용하여 이러한 조직 권한을 안전하게 보호할 수 있도록 하며, 멀티 테넌트 SaaS 아키텍처도 지원합니다. 이러한 권한은 [조직 템플릿](/authorization/organization-template)에 정의된 **조직 역할**을 통해 관리됩니다. 모든 조직은 동일한 템플릿을 사용하므로, 모든 조직에서 일관된 권한 모델을 보장합니다. @@ -35,7 +36,7 @@ Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 사용하여 이러 - **조직 수준 RBAC:** 역할과 권한은 조직 템플릿에서 정의됩니다. 사용자가 조직에 가입하면 하나 이상의 역할이 할당되어 특정 권한을 부여받습니다. - **비 API 강제 적용:** 권한은 앱의 UI, 워크플로우 또는 백엔드 로직에서 확인 및 적용되며, 반드시 API 게이트웨이에서만 적용되는 것은 아닙니다. -- **API 보호와의 분리:** 조직(비 API) 권한은 API 리소스 권한과 구분됩니다. 두 가지를 조합하여 고급 시나리오를 구현할 수 있습니다. +- **API 보호와 분리:** 조직(비 API) 권한은 API 리소스 권한과 구분됩니다. 고급 시나리오에서는 둘을 조합할 수 있습니다.
조직 권한 RBAC @@ -45,34 +46,34 @@ Logto는 OAuth 2.1 및 역할 기반 접근 제어 (RBAC)를 사용하여 이러 1. Logto의 조직 템플릿에서 **조직 권한을 정의**합니다. 2. 조직별 액션에 필요한 권한을 묶은 **조직 역할을 생성**합니다. -3. 각 조직 내 사용자 또는 클라이언트에 **역할을 할당**합니다. +3. 각 조직 내에서 사용자 또는 클라이언트에 **역할을 할당**합니다. 4. **리프레시 토큰 또는 클라이언트 자격 증명 플로우**를 사용하여 현재 조직에 대한 **조직 토큰 (JWT)**을 획득합니다. 5. 앱의 UI 또는 백엔드에서 **액세스 토큰을 검증**하여 조직 권한을 적용합니다. ### 인가 플로우: 조직 권한 인증 및 보호 \{#authorization-flow-authenticating-and-securing-organization-permissions} -다음 플로우는 클라이언트(웹, 모바일, 백엔드)가 비 API 권한 적용을 위해 조직 토큰을 획득하고 사용하는 과정을 보여줍니다. +다음 플로우는 클라이언트(웹, 모바일, 백엔드)가 조직 토큰을 획득하고 비 API 권한 적용에 사용하는 과정을 보여줍니다. -이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 주요 단계에 초점을 맞추고 있습니다. 실제 동작 방식은 아래 내용을 계속 읽어보세요. +이 플로우는 필수 파라미터나 헤더에 대한 모든 세부 정보를 포함하지 않으며, 주요 단계에 초점을 맞춥니다. 실제 동작 방식은 아래 설명을 참고하세요. ```mermaid sequenceDiagram - participant Client as 클라이언트 - participant Logto as Logto + participant Client + participant Logto participant App as 앱/UI/백엔드 alt 사용자 인증 Client->>Logto: GET /oidc/auth Logto->>Logto: 사용자를 로그인 페이지로 리디렉션 - Logto->>Client: `authorization_code`와 함께 다시 리디렉션 - Client->>Logto: `grant_type=authorization_code`로 POST /oidc/token + Logto->>Client: `authorization_code`로 다시 리디렉션 + Client->>Logto: POST /oidc/token, `grant_type=authorization_code` Logto->>Client: 리프레시 토큰 반환 - Client->>Logto: `grant_type=refresh_token` + 조직 파라미터로 POST /oidc/token + Client->>Logto: POST /oidc/token, `grant_type=refresh_token` + 조직 파라미터 else M2M 클라이언트 인증 - Client->>Logto: `grant_type=client_credentials` + 조직 파라미터로 POST /oidc/token + Client->>Logto: POST /oidc/token, `grant_type=client_credentials` + 조직 파라미터 end - Logto->>Client: 조직 토큰 (JWT) 반환 + Logto->>Client: 조직 토큰(JWT) 반환 Client->>App: Bearer 토큰으로 요청 App->>App: 조직 토큰 검증, 조직 컨텍스트 및 권한 확인 @@ -104,13 +105,13 @@ _사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명 + 조 로 이동하세요. 2. 앞서 정의한 조직 권한을 묶은 역할을 생성하세요 (예: `admin`, `member`, `billing`). -3. 각 조직 내 사용자 또는 클라이언트에 이러한 역할을 할당하세요. +3. 각 조직 내에서 사용자 또는 클라이언트에 이 역할을 할당하세요. 전체 설정 단계는 [조직 역할 사용하기](/authorization/role-based-access-control#configure-organization-roles)를 참고하세요. ### 조직 토큰(비 API) 획득 \{#obtain-organization-tokens-non-api} -클라이언트/앱은 조직 권한에 접근하기 위해 조직 토큰(비 API)을 획득해야 합니다. Logto는 조직 토큰을 [JSON Web Token (JWT)](https://auth.wiki/jwt) 형태로 발급합니다. [리프레시 토큰 플로우](https://auth.wiki/refresh-token) 또는 [클라이언트 자격 증명 플로우](https://auth.wiki/client-credentials-flow)를 통해 획득할 수 있습니다. +클라이언트/앱은 조직 권한에 접근하기 위해 조직 토큰(비 API)을 획득해야 합니다. Logto는 조직 토큰을 [JSON Web Token (JWT)](https://auth.wiki/jwt) 형태로 발급합니다. [리프레시 토큰 플로우](https://auth.wiki/refresh-token) 또는 [클라이언트 자격 증명 플로우](https://auth.wiki/client-credentials-flow)를 사용할 수 있습니다. #### 리프레시 토큰 플로우 \{#refresh-token-flow} @@ -119,7 +120,7 @@ _사용자 인증 = 브라우저/앱. M2M = 클라이언트 자격 증명 + 조 -Logto SDK를 초기화할 때, `scopes` 파라미터에 `urn:logto:scope:organizations`와 원하는 조직 권한(스코프)을 추가하세요. +Logto SDK를 초기화할 때, `scopes` 파라미터에 `urn:logto:scope:organizations` 및 원하는 조직 권한(스코프)을 추가하세요. 일부 Logto SDK에는 조직용 미리 정의된 스코프가 있습니다. 예를 들어 JavaScript SDK의 `UserScope.Organizations` 등입니다. @@ -132,21 +133,21 @@ Logto SDK를 초기화할 때, `scopes` 파라미터에 `urn:logto:scope:organiz -OAuth 2.0 클라이언트 설정 또는 인증 코드 플로우 초기화 시, 다음 파라미터를 반드시 포함하세요: +OAuth 2.0 클라이언트 설정 또는 인증 코드 플로우 초기화 시 다음 파라미터를 포함해야 합니다: -- `resource`: 조직 토큰을 요청하려면 `urn:logto:resource:organizations`로 설정 -- `scope`: 미리 정의된 조직 스코프(`urn:logto:scope:organizations`), `offline_access`(리프레시 토큰 획득용), 그리고 필요한 조직 권한(예: `invite:member`, `manage:billing`) 포함 +- `resource`: 조직 토큰을 요청하려면 `urn:logto:resource:organizations`로 설정하세요. +- `scope`: 미리 정의된 조직 스코프(`urn:logto:scope:organizations`), `offline_access`(리프레시 토큰 획득용), 그리고 필요한 조직 권한(예: `invite:member`, `manage:billing`)을 포함하세요. 일부 라이브러리는 `resource` 파라미터를 기본 지원하지 않을 수 있지만, 보통 인증 요청에 추가 파라미터를 전달할 수 있습니다. 자세한 내용은 라이브러리 문서를 참고하세요. -다음은 인가 요청 예시입니다: +다음은 인증 요청 예시입니다: -사용자가 인증되면 인가 코드를 받게 됩니다. 이 코드를 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 하세요. +사용자가 인증되면 인증 코드를 받게 됩니다. 이 코드를 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 하세요. 다음은 토큰 요청 예시입니다: @@ -158,7 +159,7 @@ OAuth 2.0 클라이언트 설정 또는 인증 코드 플로우 초기화 시, -마지막으로, 리프레시 토큰을 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 통해 조직 토큰을 획득하세요. 다음을 반드시 포함해야 합니다: +마지막으로, 리프레시 토큰을 사용하여 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 보내 조직 토큰을 획득하세요. 다음을 포함해야 합니다: - 원하는 조직 ID로 설정된 `organization_id` 파라미터 - (선택) 필요한 권한만 요청하려면 `scope` 파라미터(예: `manage:members view:reports`) @@ -172,14 +173,14 @@ OAuth 2.0 클라이언트 설정 또는 인증 코드 플로우 초기화 시, #### 클라이언트 자격 증명 플로우 \{#client-credentials-flow} -기계 간 (M2M) 시나리오에서는 클라이언트 자격 증명 플로우를 사용하여 조직 권한용 액세스 토큰을 획득할 수 있습니다. 조직 파라미터와 함께 Logto의 `/oidc/token` 엔드포인트에 POST 요청을 보내면, 클라이언트 ID와 시크릿으로 조직 토큰을 요청할 수 있습니다. +기계 간 (M2M) 시나리오에서는 클라이언트 자격 증명 플로우를 사용하여 조직 권한용 액세스 토큰을 획득할 수 있습니다. Logto의 `/oidc/token` 엔드포인트에 조직 파라미터와 함께 POST 요청을 보내면, 클라이언트 ID와 시크릿으로 조직 토큰을 요청할 수 있습니다. -요청에 포함해야 할 주요 파라미터: +요청에 포함해야 할 주요 파라미터는 다음과 같습니다: -- `organization_id`: 토큰을 요청할 조직의 ID +- `organization_id`: 토큰을 발급받을 조직의 ID - `scope`: 요청할 조직 권한(예: `invite:member`, `manage:billing`) -다음은 클라이언트 자격 증명 grant type을 사용하는 토큰 요청 예시입니다: +다음은 클라이언트 자격 증명 grant 타입을 사용하는 토큰 요청 예시입니다: + ## 모범 사례 및 보안 팁 \{#best-practices-and-security-tips} - **UI 강제 적용만으로는 충분하지 않습니다:** 중요한 액션은 반드시 백엔드에서 권한을 검증하세요. -- **대상 제한 사용:** 항상 `aud` 클레임을 확인하여 토큰이 의도한 조직용인지 확인하세요. +- **대상 제한 사용:** 항상 `aud` 클레임을 확인하여 토큰이 의도한 조직용인지 검증하세요. - **비즈니스 중심 권한 사용:** 실제 액션에 매핑되는 명확한 이름을 사용하고, 각 조직 역할에 필요한 권한만 부여하세요. - **API와 비 API 권한을 분리**하세요(단, 둘 다 하나의 역할에 포함될 수 있음). - **제품이 발전함에 따라 조직 템플릿을 정기적으로 검토**하세요. @@ -213,11 +216,11 @@ Logto가 발급한 조직 토큰(JWT)에는 앱/UI/백엔드에서 조직 수준
-### 하나의 역할에 조직 및 비조직 권한을 혼합할 수 있나요? \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} +### 하나의 역할에 조직 권한과 비조직 권한을 혼합할 수 있나요? \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} -아니요, 조직 권한(조직 수준 API 권한 포함)은 조직 템플릿에서 정의되며, 글로벌 API 권한과 혼합할 수 없습니다. 하지만 조직 권한과 조직 수준 API 권한을 모두 포함하는 역할은 생성할 수 있습니다. +아니요, 조직 권한(조직 수준 API 권한 포함)은 조직 템플릿에 의해 정의되며 글로벌 API 권한과 혼합할 수 없습니다. 하지만, 조직 권한과 조직 수준 API 권한을 모두 포함하는 역할은 만들 수 있습니다.
diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..b9b4a05c576 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### Opcional: lidar com alteração de permissões do usuário \{#optional-handle-user-permission-change} + +As permissões dos usuários podem mudar a qualquer momento. Como o Logto emite JWTs para RBAC, as atualizações de permissões só aparecem em tokens recém-emitidos e nunca modificam JWTs existentes. + +:::info Regra de subconjunto de escopo +Um token de acesso (Access token) só pode incluir escopos (Scopes) que foram solicitados no fluxo de autorização OAuth original. +Mesmo que um usuário obtenha novas permissões (Permissions), o token emitido posteriormente só pode conter um subconjunto dos escopos originalmente solicitados. +Para acessar escopos recém-concedidos que não faziam parte da solicitação inicial, o cliente deve executar um novo fluxo de autorização. +::: + +#### Permissões reduzidas \{#downscoped-permissions} + +Quando um usuário perde permissões: + +- Tokens recém-emitidos refletem imediatamente os escopos reduzidos. +- JWTs existentes mantêm os escopos antigos até expirarem. +- Sua API deve sempre validar os escopos e depender de tempos de vida curtos para os tokens. + +Se você precisar de reações mais rápidas, implemente seu próprio sinal para informar aos clientes que eles devem atualizar seus tokens. + +#### Permissões ampliadas \{#enlarged-permissions} + +{props.type === "global" &&

Para recursos de API globais, quando um usuário ganha permissões, as permissões ampliadas NÃO aparecerão através do refresh. O cliente deve realizar um novo fluxo de autorização OAuth para obter um token que inclua os novos escopos. Isso pode acontecer silenciosamente se o usuário tiver uma sessão Logto ativa.

} + +{props.type === "organization" &&

Para tokens de organização, quando um usuário ganha permissões, as permissões ampliadas aparecerão na próxima emissão (refresh ou solicitação de token). Ainda é necessário um novo token, mas não é preciso uma reautenticação completa, a menos que os novos escopos excedam o conjunto solicitado originalmente.

} + +#### Recomendações \{#recommendations} + +- Valide os escopos em sua API em todas as chamadas. +- Mantenha a expiração dos tokens curta. +- Adicione notificações opcionais se precisar de propagação imediata de alterações de permissões. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 912556f027a..d2141e8c602 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -13,7 +14,7 @@ import Tabs from '@theme/Tabs'; export const resource = 'https://api.your-app.com'; -Proteja APIs de todo o produto usando controle de acesso baseado em papel (RBAC) no Logto. Atribua papéis globais e permissões para controlar o acesso de todos os usuários e clientes em seu aplicativo. +Proteja APIs de todo o produto usando controle de acesso baseado em papel (RBAC) no Logto. Atribua papéis globais e permissões para controlar o acesso de todos os usuários e clientes em todo o seu aplicativo. ## O que são recursos globais de API? \{#what-are-global-api-resources} @@ -22,14 +23,14 @@ Recursos globais de API são endpoints ou serviços em seu aplicativo que são a **Casos de uso incluem** - APIs públicas ou endpoints compartilhados entre sua base de usuários. -- Microsserviços que não estão atrelados à multi-tenância. +- Microsserviços que não estão ligados à multi-tenancy. - APIs centrais do aplicativo (por exemplo, `/api/users`, `/api/products`) usadas por todos os clientes. O Logto permite proteger essas APIs usando OAuth 2.1, combinado com controle de acesso flexível baseado em papel. ## Como funciona no Logto \{#how-it-works-in-logto} -- **Recursos de API e permissões são registrados globalmente:** Cada API que você deseja proteger é definida com um indicador de recurso único (URI) e um conjunto de permissões (escopos) que controlam o acesso. +- **Recursos de API e permissões são registrados globalmente:** Cada API que você deseja proteger é definida com um indicador de recurso único (URI) com um conjunto de permissões (escopos) que controlam o acesso. - **O acesso é controlado por papéis globais:** Você pode atribuir permissões a papéis, que então são atribuídos a usuários ou clientes. - **Separado das permissões em nível de organização:** Recursos globais de API não têm contexto de organização. No entanto, podem ser usados em conjunto com papéis de organização para fornecer uma camada adicional de contexto, se necessário. Para proteger APIs em nível de organização, veja [Proteger recursos de API em nível de organização](/authorization/organization-level-api-resources). @@ -45,7 +46,7 @@ O Logto permite proteger essas APIs usando OAuth 2.1, combinado com controle de ### Entendendo indicadores de recurso \{#understanding-resource-indicators} -O Logto modela recursos de API de acordo com [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html). Um **indicador de recurso** é um URI que identifica de forma única a API ou serviço de destino solicitado. +O Logto modela recursos de API de acordo com [RFC 8707: Indicadores de Recurso para OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html). Um **indicador de recurso** é um URI que identifica exclusivamente a API ou serviço de destino solicitado. **Pontos-chave** @@ -60,7 +61,7 @@ O Logto modela recursos de API de acordo com [RFC 8707: Indicadores de Recurso p ### Fluxo de autorização: autenticando e protegendo sua API \{#authorization-flow-authenticating-and-securing-your-api} -O fluxo abaixo se aplica tanto à autenticação interativa do usuário (navegador / aplicativo) quanto a cenários backend máquina para máquina (M2M). +O fluxo abaixo se aplica tanto à autenticação interativa do usuário (navegador/app) quanto a cenários backend máquina para máquina (M2M). Observe que o fluxo não inclui detalhes exaustivos sobre os parâmetros ou cabeçalhos necessários, mas foca nas etapas principais envolvidas. Continue lendo para ver como o fluxo funciona na prática. @@ -86,7 +87,7 @@ sequenceDiagram end Logto->>Cliente: Retorna token de acesso (JSON Web Token) - Cliente->>Recurso de API: Requisição com token Bearer + Cliente->>Recurso de API: Requisição com Bearer token Recurso de API->>Recurso de API: Valida token de acesso alt Token é válido @@ -96,7 +97,7 @@ sequenceDiagram end ``` -_Autenticação do usuário = navegador / aplicativo. M2M = serviço backend ou script usando credenciais do cliente._ +_Autenticação do usuário = navegador/app. M2M = serviço backend ou script usando credenciais de cliente._ :::note O parâmetro `resource` deve corresponder exatamente ao identificador da API (indicador de recurso) que você registrou no Logto. @@ -106,22 +107,22 @@ O parâmetro `resource` deve corresponder exatamente ao identificador da API (in ### Registre seus recursos de API \{#register-your-api-resources} -1. Acesse Console → Recursos de API. +1. Vá para Console → Recursos de API. 2. Crie um novo recurso de API (por exemplo, `https://api.yourapp.com/org`) e defina suas permissões (escopos). Para etapas completas de configuração, veja [Definir recursos de API com permissões](/authorization/role-based-access-control#define-api-resources-with-permissions). ### Configure papéis globais \{#set-up-global-roles} -1. Acesse Console → Papéis. +1. Vá para Console → Papéis. 2. Crie papéis que correspondam às permissões da sua API (por exemplo, `read:products`, `write:products`). -3. Atribua esses papéis a usuários ou clientes que precisam acessar a API. +3. Atribua esses papéis a usuários ou clientes que precisam de acesso à API. Para etapas completas de configuração, veja [Usar papéis globais](/authorization/role-based-access-control#configure-global-roles). ### Obtenha tokens de acesso para recursos globais de API \{#obtain-access-tokens-for-global-api-resources} -Antes de acessar um recurso global de API, seu cliente deve obter um token de acesso. O Logto emite [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) como tokens de acesso para recursos globais de API. Isso normalmente é feito usando o [fluxo de código de autorização OAuth 2.0](https://auth.wiki/authorization-code-flow), [fluxo de refresh token](https://auth.wiki/refresh-token) ou o [fluxo de credenciais do cliente](https://auth.wiki/client-credentials-flow). +Antes de acessar um recurso global de API, seu cliente deve obter um token de acesso. O Logto emite [JSON Web Tokens (JWTs)](https://auth.wiki/jwt) como tokens de acesso para recursos globais de API. Isso normalmente é feito usando o [fluxo de código de autorização OAuth 2.0](https://auth.wiki/authorization-code-flow), [fluxo de refresh token](https://auth.wiki/refresh-token) ou o [fluxo de client credentials](https://auth.wiki/client-credentials-flow). #### Fluxo de código de autorização ou refresh token \{#authorization-code-or-refresh-token-flow} @@ -132,46 +133,46 @@ Todos os SDKs oficiais do Logto suportam a obtenção de tokens de acesso para r Ao inicializar o cliente Logto, adicione o indicador de recurso ao parâmetro `resources` (array), depois adicione as permissões desejadas (escopos) ao parâmetro `scopes`. -Uma vez que o usuário esteja autenticado, passe o indicador de recurso no parâmetro `resource` ou parâmetro de nome similar ao solicitar o token de acesso (por exemplo, ao chamar `getAccessToken()`). +Uma vez que o usuário esteja autenticado, passe o indicador de recurso no parâmetro `resource` ou parâmetro de nome semelhante ao solicitar o token de acesso (por exemplo, ao chamar `getAccessToken()`). Para detalhes sobre cada SDK, veja os [Comece rápido](/quick-starts). - + Ao configurar seu cliente OAuth 2.0 ou inicializar o fluxo de código de autorização, certifique-se de incluir o parâmetro `resource` e os escopos desejados na solicitação de autorização. -Algumas bibliotecas podem não suportar o parâmetro `resource` nativamente, mas geralmente permitem passar parâmetros adicionais na solicitação de autorização. Consulte a documentação da sua biblioteca para detalhes. +Algumas bibliotecas podem não suportar o parâmetro `resource` nativamente, mas geralmente permitem passar parâmetros adicionais na solicitação de autorização. Verifique a documentação da sua biblioteca para detalhes. Aqui está um exemplo não normativo da solicitação de autorização com os parâmetros `resource` e `scope`: -Uma vez que o usuário esteja autenticado, você receberá um código de autorização. Troque esse código por um token de acesso fazendo uma requisição POST para o endpoint `/oidc/token` do Logto, incluindo o parâmetro `resource` no corpo da requisição. +Uma vez que o usuário esteja autenticado, você receberá um authorization code. Troque esse código por um token de acesso fazendo uma requisição POST para o endpoint `/oidc/token` do Logto, incluindo o parâmetro `resource` no corpo da requisição. -Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão authorization_code: +Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão authorization code: -Você também pode usar o tipo de concessão `refresh_token` para obter um novo token de acesso sem interação do usuário, desde que o parâmetro `resource` esteja incluído na requisição. +Você também pode usar o tipo de concessão `refresh_token` para obter um novo token de acesso sem interação do usuário, desde que o parâmetro `resource` seja incluído na requisição. -Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão refresh_token: +Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão refresh token: -#### Fluxo de credenciais do cliente \{#client-credentials-flow} +#### Fluxo de client credentials \{#client-credentials-flow} -Para cenários máquina para máquina (M2M), você pode usar o fluxo de credenciais do cliente para obter um token de acesso para seu recurso global de API. Fazendo uma requisição POST para o endpoint `/oidc/token` do Logto, você pode solicitar um token de acesso usando seu client ID e secret. +Para cenários máquina para máquina (M2M), você pode usar o fluxo de client credentials para obter um token de acesso para seu recurso global de API. Fazendo uma requisição POST para o endpoint `/oidc/token` do Logto, você pode solicitar um token de acesso usando seu client ID e secret. Há dois parâmetros principais a serem incluídos na requisição: - `resource`: O URI do indicador de recurso da API que você deseja acessar (por exemplo, `https://api.yourapp.com`). - `scope`: As permissões que você deseja solicitar para a API (por exemplo, `read:products write:products`). -Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão client_credentials: +Aqui está um exemplo não normativo da solicitação de token usando o tipo de concessão client credentials: -:::info -👷 Trabalho em andamento. 🚧 -::: - -## Boas práticas e dicas de segurança \{#best-practices-and-security-tips} +## Melhores práticas e dicas de segurança \{#best-practices-and-security-tips} - **Mantenha as permissões orientadas ao negócio:** Use nomes claros que correspondam a ações reais. - **Mantenha a expiração do token curta:** Reduz o risco caso um token seja vazado. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index cc313d00866..d6662807cfd 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -16,7 +17,7 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md export const resource = 'https://api.your-app.com/organizations'; -Combine recursos de API com o template de organização para restringir o acesso a APIs e dados dentro de cada organização, garantindo isolamento em nível de locatário em seu SaaS. +Combine recursos de API com o template de organização para restringir o acesso a APIs e dados dentro de cada organização, garantindo isolamento em nível de locatário no seu SaaS. ## O que são recursos de API em nível de organização? \{#what-are-organization-level-api-resources} @@ -29,16 +30,16 @@ Recursos de API em nível de organização são endpoints ou serviços em seu ap - Endpoints de cobrança, assinatura ou auditoria vinculados a uma organização - Qualquer API onde ações e dados são isolados por locatário -O Logto permite proteger essas APIs de organização usando OAuth 2.1 e RBAC, enquanto oferece suporte a arquiteturas SaaS multi-locatário. +O Logto permite proteger essas APIs de organização usando OAuth 2.1 e RBAC, enquanto oferece suporte a arquiteturas SaaS multi-inquilino. -Essas permissões são gerenciadas por meio de **papéis da organização** definidos no [template de organização](/authorization/organization-template). Cada organização usa o mesmo template, garantindo um modelo de permissões consistente em todas as organizações. +Essas permissões são gerenciadas por meio de **papéis da organização (organization roles)** definidos no [template de organização](/authorization/organization-template). Cada organização usa o mesmo template, garantindo um modelo de permissões consistente em todas as organizações. ## Como funciona no Logto \{#how-it-works-in-logto} -- **Recursos de API e permissões são registrados globalmente:** Cada recurso de API é definido com um indicador de recurso (URI) exclusivo e um conjunto de permissões (escopos) no Logto. -- **Papéis em nível de organização:** Papéis de organização são definidos no template de organização. Permissões de recursos de API (escopos) são atribuídas a papéis da organização, que então são atribuídos a usuários ou clientes **dentro de cada organização**. +- **Recursos de API e permissões são registrados globalmente:** Cada recurso de API é definido com um indicador de recurso único (URI) e um conjunto de permissões (escopos) no Logto. +- **Papéis em nível de organização:** Papéis da organização são definidos no template de organização. Permissões de recursos de API (escopos) são atribuídas a papéis da organização, que então são atribuídos a usuários ou clientes **dentro de cada organização**. - **Autorização sensível ao contexto:** Quando um cliente solicita um token de acesso com um recurso de API e um `organization_id`, o Logto emite um token que inclui tanto o contexto da organização quanto o público da API. As permissões (escopos) do token são determinadas pelos papéis da organização do usuário para a organização especificada. -- **Separação de recursos globais:** Recursos de API podem ser acessados com ou sem contexto de organização. O RBAC da organização só é aplicado se um `organization_id` for incluído na solicitação. Para APIs compartilhadas entre todos os usuários, veja [Proteger recursos de API globais](/authorization/global-api-resources). +- **Separação de recursos globais:** Recursos de API podem ser acessados com ou sem contexto de organização. O RBAC da organização só é aplicado se um `organization_id` for incluído na solicitação. Para APIs compartilhadas entre todos os usuários, veja [Proteger recursos globais de API](/authorization/global-api-resources). Console → Template de organização → Papéis da organização. -2. Crie papéis de organização (por exemplo, `admin`, `member`) e atribua permissões de API a cada papel. +2. Crie papéis da organização (por exemplo, `admin`, `member`) e atribua permissões de API a cada papel. 3. Atribua papéis a usuários ou clientes dentro de cada organização. Se ainda não forem membros, convide-os ou adicione-os primeiro. -Para etapas completas de configuração, veja [Usar papéis de organização](/authorization/role-based-access-control#configure-organization-roles). +Para etapas completas de configuração, veja [Usar papéis da organização](/authorization/role-based-access-control#configure-organization-roles). ### Obtenha tokens de organização para recursos de API \{#obtain-organization-tokens-for-api-resources} @@ -119,12 +120,12 @@ Seu cliente/app deve solicitar um token com `resource` e `organization_id` para #### Fluxo de token de atualização \{#refresh-token-flow} -Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de token de atualização nativamente. Uma biblioteca padrão de cliente OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo. +Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de token de atualização nativamente. Uma biblioteca padrão OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo. -Ao inicializar o Logto SDK, adicione o `urn:logto:scope:organizations` e as permissões de organização desejadas (escopos) ao parâmetro `scopes`. +Ao inicializar o Logto SDK, adicione `urn:logto:scope:organizations` e as permissões de organização desejadas (escopos) ao parâmetro `scopes`. Alguns SDKs do Logto possuem um escopo predefinido para organizações, como `UserScope.Organizations` em SDKs JavaScript. @@ -207,19 +208,21 @@ Quando seu app receber um token de organização, você deve: - Verificar a assinatura do token (usando os JWKs do Logto). - Confirmar que o token não está expirado (`exp` claim). - Verificar se o `iss` (emissor) corresponde ao seu endpoint Logto. -- Garantir que o `aud` (público) corresponda ao identificador do recurso de API que você registrou (por exemplo, `https://api.yourapp.com/org`). +- Garantir que o `aud` (público) corresponde ao identificador do recurso de API registrado (por exemplo, `https://api.yourapp.com/org`). - Validar a reivindicação `organization_id` para garantir que o token está restrito à organização correta. - Dividir a reivindicação `scope` (separada por espaço) e verificar as permissões necessárias. - Se o caminho da sua API incluir o ID da organização (por exemplo, `/organizations/{organizationId}/members`), garantir que a reivindicação `organization_id` corresponda ao parâmetro do caminho. Para guias passo a passo e específicos de linguagem, veja [Como validar tokens de acesso](/authorization/validate-access-tokens). + + ## Boas práticas e dicas de segurança \{#best-practices-and-security-tips} - **Sempre valide o contexto da organização:** Não confie apenas no token; verifique a reivindicação `organization_id` para cada chamada de API restrita à organização. - **Use restrições de público:** Sempre verifique a reivindicação `aud` para garantir que o token é para a organização pretendida. - **Mantenha as permissões orientadas ao negócio:** Use nomes claros que correspondam a ações reais; conceda apenas o necessário para cada papel da organização. -- **Separe permissões de API e não-API** sempre que possível (mas ambas podem estar em um único papel). +- **Separe permissões de API e não-API** quando possível (mas ambas podem estar em um único papel). - **Mantenha a vida útil dos tokens curta:** Reduz o risco caso um token seja vazado. - **Revise regularmente seu template de organização:** Atualize papéis e permissões conforme seu produto evolui. @@ -243,7 +246,7 @@ Apenas papéis/permissões globais serão avaliados. O RBAC da organização nã -Não, permissões de organização (incluindo permissões de API em nível de organização) são definidas pelo template de organização e não podem ser misturadas com permissões globais de API. No entanto, você pode criar papéis que incluam permissões de organização e permissões de API em nível de organização. +Não, permissões de organização (incluindo permissões de API em nível de organização) são definidas pelo template de organização e não podem ser misturadas com permissões globais de API. No entanto, você pode criar papéis que incluam tanto permissões de organização quanto permissões de API em nível de organização. @@ -252,6 +255,6 @@ Não, permissões de organização (incluindo permissões de API em nível de or Como validar tokens de acesso Personalizando reivindicações de token - Caso de uso: Construa um aplicativo SaaS multi-locatário + Caso de uso: Construa um aplicativo SaaS multi-inquilino RFC 8707: Indicadores de recurso diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 24ff7e66c72..ac718502ceb 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,11 +15,11 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # Proteger permissões de organização (não-API) -Use o template de organização para gerenciar e aplicar papéis e permissões em nível de organização no Logto, controlando o acesso a funcionalidades e fluxos dentro do contexto de uma organização. +Use o template de organização para gerenciar e aplicar papéis e permissões em nível de organização no Logto, controlando o acesso a recursos e fluxos dentro do contexto de uma organização. ## O que são permissões de organização (não-API)? \{#what-are-organization-non-api-permissions} -As permissões de organização (não-API) controlam o que os usuários podem fazer **dentro do contexto de uma organização**, mas não são **aplicadas no nível da API**. Em vez disso, elas governam o acesso a funcionalidades do aplicativo, elementos da interface, fluxos de trabalho ou ações de negócio, e não a APIs de backend. +As permissões de organização (não-API) controlam o que os usuários podem fazer **dentro do contexto de uma organização**, mas não são **aplicadas no nível da API**. Em vez disso, elas governam o acesso a recursos do aplicativo, elementos da interface, fluxos ou ações de negócio, e não a APIs de backend. **Casos de uso incluem** @@ -29,7 +30,7 @@ As permissões de organização (não-API) controlam o que os usuários podem fa O Logto permite proteger essas permissões de organização usando OAuth 2.1 e RBAC, além de suportar arquiteturas SaaS multi-tenant. -Essas permissões são gerenciadas através de **papéis de organização** definidos no [template de organização](/authorization/organization-template). Todas as organizações usam o mesmo template, garantindo um modelo de permissões consistente entre todas as organizações. +Essas permissões são gerenciadas por meio de **papéis de organização** definidos no [template de organização](/authorization/organization-template). Todas as organizações usam o mesmo template, garantindo um modelo de permissões consistente em todas as organizações. ## Como funciona no Logto \{#how-it-works-in-logto} @@ -47,49 +48,49 @@ Essas permissões são gerenciadas através de **papéis de organização** defi ### Visão geral da implementação \{#implementation-overview} -1. **Defina as permissões de organização** no Logto, dentro do template de organização. +1. **Defina permissões de organização** no Logto, no template de organização. 2. **Crie papéis de organização** que agrupem as permissões necessárias para ações específicas da organização. 3. **Atribua papéis** a usuários ou clientes dentro de cada organização. -4. **Obtenha um token de organização (JWT)** para a organização atual usando o fluxo de token de atualização ou client credentials. +4. **Obtenha um token de organização (JWT)** para a organização atual usando o refresh token ou o fluxo de client credentials. 5. **Valide os tokens de acesso** na interface ou backend do seu app para aplicar as permissões de organização. ### Fluxo de autorização: autenticando e protegendo permissões de organização \{#authorization-flow-authenticating-and-securing-organization-permissions} -O fluxo a seguir mostra como um cliente (web, mobile ou backend) obtém e utiliza tokens de organização para aplicação de permissões não-API. +O fluxo a seguir mostra como um cliente (web, mobile ou backend) obtém e usa tokens de organização para aplicação de permissões não-API. -Observe que o fluxo não inclui detalhes exaustivos sobre os parâmetros ou cabeçalhos necessários, mas foca nos passos principais. Continue lendo para ver como o fluxo funciona na prática. +Observe que o fluxo não inclui detalhes exaustivos sobre parâmetros ou cabeçalhos necessários, mas foca nos passos principais. Continue lendo para ver como o fluxo funciona na prática. ```mermaid sequenceDiagram - participant Client + participant Cliente participant Logto participant App as App/UI/backend alt Autenticação do usuário - Client->>Logto: GET /oidc/auth + Cliente->>Logto: GET /oidc/auth Logto->>Logto: Redireciona usuário para página de login - Logto->>Client: Redireciona de volta com `authorization_code` - Client->>Logto: POST /oidc/token com `grant_type=authorization_code` - Logto->>Client: Retorna token de atualização - Client->>Logto: POST /oidc/token com `grant_type=refresh_token` + parâmetros de organização + Logto->>Cliente: Redireciona de volta com `authorization_code` + Cliente->>Logto: POST /oidc/token com `grant_type=authorization_code` + Logto->>Cliente: Retorna refresh token + Cliente->>Logto: POST /oidc/token com `grant_type=refresh_token` + parâmetros de organização else Autenticação de cliente M2M - Client->>Logto: POST /oidc/token com `grant_type=client_credentials` + parâmetros de organização + Cliente->>Logto: POST /oidc/token com `grant_type=client_credentials` + parâmetros de organização end - Logto->>Client: Retorna token de organização (JWT) - Client->>App: Requisição com Bearer token + Logto->>Cliente: Retorna token de organização (JWT) + Cliente->>App: Requisição com Bearer token App->>App: Valida token de organização, verifica contexto e permissões da organização - alt Token é válido - App->>Client: Permite ações/dados específicos da organização - else Token é inválido - App->>Client: 401 Não autorizado ou nega acesso à interface + alt Token válido + App->>Cliente: Permite ações/dados específicos da organização + else Token inválido + App->>Cliente: 401 Não autorizado ou nega acesso à interface end ``` _Autenticação do usuário = navegador/app. M2M = serviço de backend ou script usando client credentials + contexto de organização._ -## Passos de implementação \{#implementation-steps} +## Etapas de implementação \{#implementation-steps} ### Registrar permissões de organização \{#register-organization-permissions} @@ -108,34 +109,34 @@ Para o passo a passo completo, veja [Usar papéis de organização](/authorizati ### Obter tokens de organização (não-API) \{#obtain-organization-tokens-non-api} -Seu cliente/app deve obter um token de organização (não-API) para acessar permissões de organização. O Logto emite tokens de organização como [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Você pode obtê-los usando o [fluxo de token de atualização](https://auth.wiki/refresh-token) ou o [fluxo client credentials](https://auth.wiki/client-credentials-flow). +Seu cliente/app deve obter um token de organização (não-API) para acessar permissões de organização. O Logto emite tokens de organização como [JSON Web Tokens (JWTs)](https://auth.wiki/jwt). Você pode obtê-los usando o [fluxo de refresh token](https://auth.wiki/refresh-token) ou o [fluxo de client credentials](https://auth.wiki/client-credentials-flow). -#### Fluxo de token de atualização \{#refresh-token-flow} +#### Fluxo de refresh token \{#refresh-token-flow} -Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de token de atualização nativamente. Uma biblioteca padrão de cliente OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo. +Quase todos os SDKs oficiais do Logto suportam a obtenção de tokens de organização usando o fluxo de refresh token nativamente. Uma biblioteca padrão de cliente OAuth 2.0 / OIDC também pode ser usada para implementar esse fluxo. Ao inicializar o Logto SDK, adicione `urn:logto:scope:organizations` e as permissões de organização desejadas (escopos) ao parâmetro `scopes`. -Alguns SDKs do Logto possuem um escopo pré-definido para organizações, como `UserScope.Organizations` em SDKs JavaScript. +Alguns SDKs do Logto possuem um escopo predefinido para organizações, como `UserScope.Organizations` em SDKs JavaScript. -Use `getOrganizationToken` ou um método similar (como `getAccessToken` com um ID de organização) para solicitar um token de organização para uma organização específica. +Use `getOrganizationToken` ou método similar (como `getAccessToken` com um ID de organização) para solicitar um token de organização para uma organização específica. Para detalhes de cada SDK, veja [Inícios rápidos](/quick-starts). -Ao configurar seu cliente OAuth 2.0 ou inicializar o fluxo de código de autorização, certifique-se de incluir os seguintes parâmetros: +Ao configurar seu cliente OAuth 2.0 ou inicializar o fluxo de authorization code, certifique-se de incluir os seguintes parâmetros: - `resource`: Defina como `urn:logto:resource:organizations` para indicar que deseja um token de organização. -- `scope`: Inclua o escopo pré-definido de organização (`urn:logto:scope:organizations`), `offline_access` (para obter tokens de atualização) e quaisquer permissões de organização específicas necessárias (ex.: `invite:member`, `manage:billing`). +- `scope`: Inclua o escopo predefinido de organização (`urn:logto:scope:organizations`), `offline_access` (para obter refresh tokens) e quaisquer permissões de organização específicas necessárias (ex.: `invite:member`, `manage:billing`). -Algumas bibliotecas podem não suportar o parâmetro `resource` nativamente, mas geralmente permitem passar parâmetros adicionais na requisição de autorização. Verifique a documentação da sua biblioteca para detalhes. +Algumas bibliotecas podem não suportar o parâmetro `resource` nativamente, mas geralmente permitem passar parâmetros adicionais na requisição de autorização. Consulte a documentação da sua biblioteca para detalhes. Veja um exemplo não normativo de como a requisição de autorização pode ser: @@ -144,7 +145,7 @@ Veja um exemplo não normativo de como a requisição de autorização pode ser: resource="urn:logto:resource:organizations" /> -Após a autenticação do usuário, você receberá um código de autorização. Use esse código fazendo uma requisição POST para o endpoint `/oidc/token` do Logto. +Após a autenticação do usuário, você receberá um authorization code. Use esse código fazendo uma requisição POST para o endpoint `/oidc/token` do Logto. Veja um exemplo não normativo da requisição de token: @@ -152,11 +153,11 @@ Veja um exemplo não normativo da requisição de token: -Você receberá um token de atualização que pode ser usado para obter tokens de organização. +Você receberá um refresh token que pode ser usado para obter tokens de organização. -Por fim, use o token de atualização para obter um token de organização fazendo uma requisição POST para o endpoint `/oidc/token` do Logto. Lembre-se de incluir: +Por fim, use o refresh token para obter um token de organização fazendo uma requisição POST para o endpoint `/oidc/token` do Logto. Lembre-se de incluir: - O parâmetro `organization_id` definido para o ID da organização desejada. - (Opcional) O parâmetro `scope` para restringir ainda mais as permissões necessárias (ex.: `manage:members view:reports`). @@ -168,9 +169,9 @@ Veja um exemplo não normativo de como a requisição de token pode ser: -#### Fluxo client credentials \{#client-credentials-flow} +#### Fluxo de client credentials \{#client-credentials-flow} -Para cenários máquina para máquina (M2M), você pode usar o fluxo client credentials para obter um token de acesso para permissões de organização. Fazendo uma requisição POST para o endpoint `/oidc/token` do Logto com parâmetros de organização, você pode solicitar um token de organização usando seu client ID e secret. +Para cenários máquina para máquina (M2M), você pode usar o fluxo de client credentials para obter um token de acesso para permissões de organização. Fazendo uma requisição POST para o endpoint `/oidc/token` do Logto com parâmetros de organização, você pode solicitar um token de organização usando seu client ID e secret. Aqui estão os principais parâmetros a serem incluídos na requisição: @@ -198,12 +199,14 @@ Quando seu app recebe um token de organização, você deve: Para guias passo a passo e específicos de linguagem, veja [Como validar tokens de acesso](/authorization/validate-access-tokens). + + ## Boas práticas e dicas de segurança \{#best-practices-and-security-tips} -- **Nunca confie apenas na aplicação na interface:** Sempre valide permissões no backend para ações críticas. +- **Nunca confie apenas na aplicação pela interface:** Sempre valide permissões no backend para ações críticas. - **Use restrições de público:** Sempre verifique a reivindicação `aud` para garantir que o token é para a organização pretendida. -- **Mantenha as permissões orientadas ao negócio:** Use nomes claros que correspondam a ações reais; conceda apenas o necessário para cada papel de organização. -- **Separe permissões de API e não-API** sempre que possível (mas ambas podem estar em um único papel). +- **Mantenha as permissões orientadas ao negócio:** Use nomes claros que correspondam a ações reais; conceda apenas o necessário para cada papel da organização. +- **Separe permissões de API e não-API** quando possível (mas ambas podem estar em um único papel). - **Revise o template de organização regularmente** conforme seu produto evolui. ## Perguntas frequentes \{#faqs} @@ -215,7 +218,7 @@ Para guias passo a passo e específicos de linguagem, veja [Como validar tokens -Não, as permissões de organização (incluindo permissões de API em nível de organização) são definidas pelo template de organização e não podem ser misturadas com permissões globais de API. No entanto, você pode criar papéis que incluam permissões de organização e permissões de API em nível de organização. +Não, permissões de organização (incluindo permissões de API em nível de organização) são definidas pelo template de organização e não podem ser misturadas com permissões globais de API. No entanto, você pode criar papéis que incluam tanto permissões de organização quanto permissões de API em nível de organização. @@ -226,7 +229,7 @@ Não, as permissões de organização (incluindo permissões de API em nível de -Verifique permissões não-API tanto na interface (para controle de funcionalidades) quanto na lógica do servidor para ações sensíveis. +Verifique permissões não-API tanto na interface (para controle de recursos) quanto na lógica do servidor para ações sensíveis. diff --git a/i18n/th/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/th/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..39804360151 --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### ตัวเลือก: จัดการเมื่อสิทธิ์ของผู้ใช้เปลี่ยนแปลง \{#optional-handle-user-permission-change} + +สิทธิ์ของผู้ใช้สามารถเปลี่ยนแปลงได้ตลอดเวลา เนื่องจาก Logto ออก JWT สำหรับการควบคุมการเข้าถึงตามบทบาท (RBAC) การอัปเดตสิทธิ์จะปรากฏเฉพาะในโทเค็นที่ออกใหม่เท่านั้น และจะไม่เปลี่ยนแปลง JWT ที่มีอยู่เดิม + +:::info กฎขอบเขตย่อย (Scope subset rule) +โทเค็นการเข้าถึง (Access token) สามารถมีขอบเขต (scopes) ได้เฉพาะที่ร้องขอในกระบวนการอนุญาต OAuth เดิมเท่านั้น +แม้ว่าผู้ใช้จะได้รับสิทธิ์ใหม่ โทเค็นที่ออกภายหลังจะมีเพียงขอบเขตย่อยของขอบเขตที่ร้องขอไว้แต่แรก +หากต้องการเข้าถึงขอบเขตใหม่ที่ไม่ได้อยู่ในการร้องขอครั้งแรก ไคลเอนต์ต้องเริ่มกระบวนการอนุญาตใหม่ +::: + +#### สิทธิ์ที่ลดลง (Downscoped permissions) \{#downscoped-permissions} + +เมื่อผู้ใช้สูญเสียสิทธิ์: + +- โทเค็นที่ออกใหม่จะแสดงขอบเขตที่ลดลงทันที +- JWT ที่มีอยู่จะยังคงขอบเขตเดิมจนกว่าจะหมดอายุ +- API ของคุณควรตรวจสอบขอบเขตทุกครั้งและพึ่งพาอายุโทเค็นที่สั้น + +หากคุณต้องการให้ระบบตอบสนองเร็วขึ้น ให้สร้างสัญญาณของคุณเองเพื่อแจ้งให้ไคลเอนต์รีเฟรชโทเค็น + +#### สิทธิ์ที่เพิ่มขึ้น (Enlarged permissions) \{#enlarged-permissions} + +{props.type === "global" &&

สำหรับทรัพยากร API ระดับโกลบอล เมื่อผู้ใช้ได้รับสิทธิ์เพิ่ม สิทธิ์ที่เพิ่มขึ้นจะ **ไม่** ปรากฏผ่านการรีเฟรช ไคลเอนต์ต้องดำเนินกระบวนการอนุญาต OAuth ใหม่เพื่อรับโทเค็นที่มีขอบเขตใหม่ ซึ่งสามารถเกิดขึ้นแบบเงียบ ๆ ได้หากผู้ใช้มีเซสชัน Logto ที่ยังใช้งานอยู่

} + +{props.type === "organization" &&

สำหรับโทเค็นองค์กร เมื่อผู้ใช้ได้รับสิทธิ์เพิ่ม สิทธิ์ที่เพิ่มขึ้นจะปรากฏในการออกโทเค็นครั้งถัดไป (รีเฟรชหรือขอโทเค็น) ยังคงต้องใช้โทเค็นใหม่ แต่ไม่จำเป็นต้องยืนยันตัวตนใหม่ทั้งหมด เว้นแต่ขอบเขตใหม่จะเกินชุดที่ร้องขอไว้แต่แรก

} + +#### ข้อแนะนำ \{#recommendations} + +- ตรวจสอบขอบเขตใน API ของคุณทุกครั้งที่เรียกใช้งาน +- กำหนดอายุโทเค็นให้สั้น +- เพิ่มการแจ้งเตือนเสริม หากคุณต้องการให้การเปลี่ยนแปลงสิทธิ์มีผลทันที diff --git a/i18n/th/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/th/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 273b0378383..221fdabd6a8 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -17,11 +18,11 @@ export const resource = 'https://api.your-app.com'; ## ทรัพยากร API ระดับโกลบอลคืออะไร? \{#what-are-global-api-resources} -ทรัพยากร API ระดับโกลบอล คือ endpoint หรือบริการในแอปพลิเคชันของคุณที่ผู้ใช้ทุกคนสามารถเข้าถึงได้ ไม่ว่าจะอยู่ในองค์กรหรือผู้เช่าใดก็ตาม โดยทั่วไปจะเป็น API ที่เปิดเผยต่อสาธารณะ บริการหลักของผลิตภัณฑ์ หรือ endpoint ใด ๆ ที่ไม่ได้จำกัดขอบเขตกับองค์กรใดองค์กรหนึ่ง +ทรัพยากร API ระดับโกลบอล คือ endpoint หรือบริการในแอปพลิเคชันของคุณที่ผู้ใช้ทุกคนสามารถเข้าถึงได้ ไม่ว่าจะอยู่ในองค์กรหรือผู้เช่าใดก็ตาม โดยทั่วไปจะเป็น API ที่เปิดเผยต่อสาธารณะ, บริการหลักของผลิตภัณฑ์ หรือ endpoint ใด ๆ ที่ไม่ได้จำกัดขอบเขตกับองค์กรใดองค์กรหนึ่ง **กรณีการใช้งาน เช่น** -- API สาธารณะหรือ endpoint ที่ใช้ร่วมกันกับผู้ใช้ทั้งหมด +- API สาธารณะ หรือ endpoint ที่ใช้ร่วมกันในกลุ่มผู้ใช้ของคุณ - Microservices ที่ไม่ได้ผูกกับระบบหลายผู้เช่า (multi-tenancy) - API หลักของแอปพลิเคชัน (เช่น `/api/users`, `/api/products`) ที่ลูกค้าทุกคนใช้ @@ -29,9 +30,9 @@ Logto ช่วยให้คุณรักษาความปลอดภ ## วิธีการทำงานใน Logto \{#how-it-works-in-logto} -- **ทรัพยากร API และสิทธิ์ถูกลงทะเบียนในระดับโกลบอล:** แต่ละ API ที่คุณต้องการปกป้องจะถูกกำหนดด้วย resource indicator (URI) ที่ไม่ซ้ำกัน พร้อมชุดสิทธิ์ (scopes) ที่ควบคุมการเข้าถึง -- **การเข้าถึงถูกควบคุมด้วยบทบาทระดับโกลบอล:** คุณสามารถกำหนดสิทธิ์ให้กับบทบาท แล้วนำบทบาทนั้นไปกำหนดให้กับผู้ใช้หรือไคลเอนต์ -- **แยกจากสิทธิ์ระดับองค์กร:** ทรัพยากร API ระดับโกลบอลไม่มีบริบทขององค์กร อย่างไรก็ตาม สามารถใช้ร่วมกับบทบาทขององค์กรเพื่อเพิ่มชั้นบริบทได้หากจำเป็น หากต้องการปกป้อง API ระดับองค์กร ดู [ปกป้องทรัพยากร API ระดับองค์กร](/authorization/organization-level-api-resources) +- **ทรัพยากร API และสิทธิ์ถูกลงทะเบียนในระดับโกลบอล:** แต่ละ API ที่คุณต้องการปกป้องจะถูกกำหนดด้วย resource indicator (URI) เฉพาะ พร้อมชุดสิทธิ์ (scopes) ที่ควบคุมการเข้าถึง +- **การเข้าถูกควบคุมด้วยบทบาทระดับโกลบอล:** คุณสามารถกำหนดสิทธิ์ให้กับบทบาท แล้วมอบหมายบทบาทเหล่านั้นให้กับผู้ใช้หรือไคลเอนต์ +- **แยกจากสิทธิ์ระดับองค์กร:** ทรัพยากร API ระดับโกลบอลไม่มีบริบทขององค์กร อย่างไรก็ตาม สามารถใช้ร่วมกับบทบาทขององค์กรเพื่อเพิ่มชั้นบริบทได้หากต้องการ หากต้องการปกป้อง API ระดับองค์กร ดู [ปกป้องทรัพยากร API ระดับองค์กร](/authorization/organization-level-api-resources) Global API resources RBAC @@ -39,19 +40,19 @@ Logto ช่วยให้คุณรักษาความปลอดภ 1. **ลงทะเบียนทรัพยากร API ของคุณ** และกำหนดสิทธิ์ใน Logto 2. **กำหนดบทบาท** พร้อมสิทธิ์ที่จำเป็นสำหรับการเข้าถึง API -3. **กำหนดบทบาท** ให้กับผู้ใช้หรือไคลเอนต์ -4. **ใช้ OAuth 2.0 authorization flows** เพื่อขอรับโทเค็นการเข้าถึงสำหรับ API (parameter `resource` ต้องตรงกับ API identifier ที่ลงทะเบียนไว้) +3. **มอบหมายบทบาท** ให้กับผู้ใช้หรือไคลเอนต์ +4. **ใช้ OAuth 2.0 authorization flows** เพื่อขอรับโทเค็นการเข้าถึงสำหรับ API (ค่าพารามิเตอร์ resource ต้องตรงกับ API identifier ที่ลงทะเบียนไว้) 5. **ตรวจสอบโทเค็นการเข้าถึง** ใน API ของคุณเพื่อบังคับใช้สิทธิ์ ### ทำความเข้าใจ resource indicator \{#understanding-resource-indicators} -Logto สร้างแบบจำลองทรัพยากร API ตาม [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html) โดย **resource indicator** คือ URI ที่ระบุ API หรือบริการเป้าหมายที่ร้องขออย่างไม่ซ้ำกัน +Logto สร้างแบบจำลองทรัพยากร API ตาม [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html) โดย **resource indicator** คือ URI ที่ระบุ API หรือบริการเป้าหมายที่ร้องขออย่างเฉพาะเจาะจง **ประเด็นสำคัญ** - Resource indicator ต้องเป็น absolute URI (เช่น `https://api.example.com`) - ไม่มี fragment component; หลีกเลี่ยงการใช้ query string หากเป็นไปได้ -- Resource indicator ช่วยให้รองรับ audience-restricted token และสถาปัตยกรรม multi-API +- Resource indicator ช่วยให้รองรับโทเค็นที่จำกัดผู้รับ (audience-restricted tokens) และสถาปัตยกรรม multi-API **ตัวอย่าง** @@ -60,9 +61,9 @@ Logto สร้างแบบจำลองทรัพยากร API ตา ### กระบวนการอนุญาต: การยืนยันตัวตนและปกป้อง API ของคุณ \{#authorization-flow-authenticating-and-securing-your-api} -ขั้นตอนด้านล่างนี้ใช้ได้ทั้งกรณีการยืนยันตัวตนของผู้ใช้ (browser / app) และกรณี backend แบบเครื่องต่อเครื่อง (M2M) +กระบวนการด้านล่างนี้ใช้ได้ทั้งกรณีการยืนยันตัวตนของผู้ใช้แบบโต้ตอบ (browser / app) และกรณี backend เครื่องต่อเครื่อง (M2M) -โปรดทราบว่า flow นี้ไม่ได้แสดงรายละเอียดพารามิเตอร์หรือ header ทั้งหมด แต่เน้นขั้นตอนสำคัญ อ่านต่อเพื่อดูตัวอย่างการทำงานจริง +โปรดทราบว่ากระบวนการนี้ไม่ได้ลงรายละเอียดพารามิเตอร์หรือ header ที่จำเป็นทั้งหมด แต่เน้นขั้นตอนหลัก อ่านต่อเพื่อดูตัวอย่างการทำงานจริง ```mermaid sequenceDiagram @@ -75,14 +76,14 @@ sequenceDiagram Logto->>Logto: เปลี่ยนเส้นทางผู้ใช้ไปยังหน้าลงชื่อเข้าใช้ Logto->>Client: เปลี่ยนเส้นทางกลับพร้อม `authorization_code` alt ใช้ authorization_code grant - Client->>Logto: POST /oidc/token พร้อม `grant_type=authorization_code`
และ parameter `resource` + Client->>Logto: POST /oidc/token พร้อม `grant_type=authorization_code`
และพารามิเตอร์ `resource` else ใช้ refresh_token grant Client->>Logto: POST /oidc/token พร้อม `grant_type=authorization_code` Logto->>Client: ส่งคืน refresh token - Client->>Logto: POST /oidc/token พร้อม `grant_type=refresh_token`
และ parameter `resource` + Client->>Logto: POST /oidc/token พร้อม `grant_type=refresh_token`
และพารามิเตอร์ `resource` end - else การยืนยันตัวตนของไคลเอนต์แบบเครื่องต่อเครื่อง (M2M) - Client->>Logto: POST /oidc/token พร้อม `grant_type=client_credentials`
และ parameter `resource` + else การยืนยันตัวตนของไคลเอนต์เครื่องต่อเครื่อง (M2M) + Client->>Logto: POST /oidc/token พร้อม `grant_type=client_credentials`
และพารามิเตอร์ `resource` end Logto->>Client: ส่งคืนโทเค็นการเข้าถึง (JSON Web Token) @@ -96,10 +97,10 @@ sequenceDiagram end ``` -_การยืนยันตัวตนของผู้ใช้ = browser / app. M2M = backend service หรือ script ที่ใช้ client credentials._ +_การยืนยันตัวตนของผู้ใช้ = browser / app. M2M = บริการ backend หรือสคริปต์ที่ใช้ client credentials._ :::note -parameter `resource` ต้องตรงกับ API identifier (resource indicator) ที่คุณลงทะเบียนใน Logto +ค่าพารามิเตอร์ `resource` ต้องตรงกับ API identifier (resource indicator) ที่คุณลงทะเบียนใน Logto ::: ## ขั้นตอนการนำไปใช้ \{#implementation-steps} @@ -107,15 +108,15 @@ parameter `resource` ต้องตรงกับ API identifier (resource ind ### ลงทะเบียนทรัพยากร API ของคุณ \{#register-your-api-resources} 1. ไปที่ Console → API resources -2. สร้าง API resource ใหม่ (เช่น `https://api.yourapp.com/org`) และกำหนดสิทธิ์ (scopes) +2. สร้าง API resource ใหม่ (เช่น `https://api.yourapp.com/org`) และกำหนดสิทธิ์ (scopes) ของมัน สำหรับขั้นตอนการตั้งค่าแบบละเอียด ดู [กำหนด API resources พร้อมสิทธิ์](/authorization/role-based-access-control#define-api-resources-with-permissions) ### ตั้งค่าบทบาทระดับโกลบอล \{#set-up-global-roles} 1. ไปที่ Console → Roles -2. สร้างบทบาทที่แมปกับสิทธิ์ของ API ของคุณ (เช่น `read:products`, `write:products`) -3. กำหนดบทบาทเหล่านี้ให้กับผู้ใช้หรือไคลเอนต์ที่ต้องการเข้าถึง API +2. สร้างบทบาทที่สอดคล้องกับสิทธิ์ของ API ของคุณ (เช่น `read:products`, `write:products`) +3. มอบหมายบทบาทเหล่านี้ให้กับผู้ใช้หรือไคลเอนต์ที่ต้องการเข้าถึง API สำหรับขั้นตอนการตั้งค่าแบบละเอียด ดู [ใช้บทบาทระดับโกลบอล](/authorization/role-based-access-control#configure-global-roles) @@ -125,37 +126,37 @@ parameter `resource` ต้องตรงกับ API identifier (resource ind #### Authorization code หรือ refresh token flow \{#authorization-code-or-refresh-token-flow} -SDK อย่างเป็นทางการของ Logto ทั้งหมดรองรับการขอโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลด้วย refresh token flow ในตัว คุณยังสามารถใช้ไลบรารี OAuth 2.0 / OIDC client มาตรฐานเพื่อใช้งาน flow นี้ได้ +SDK อย่างเป็นทางการของ Logto ทั้งหมดรองรับการขอโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลด้วย refresh token flow ได้ทันที คุณยังสามารถใช้ไลบรารี OAuth 2.0 / OIDC client มาตรฐานเพื่อใช้งาน flow นี้ได้ -เมื่อเริ่มต้น Logto client ให้เพิ่ม resource indicator ลงใน parameter `resources` (array) จากนั้นเพิ่มสิทธิ์ (scopes) ที่ต้องการลงใน parameter `scopes` +เมื่อเริ่มต้น Logto client ให้เพิ่ม resource indicator ลงในพารามิเตอร์ `resources` (array) แล้วเพิ่มสิทธิ์ (scopes) ที่ต้องการลงในพารามิเตอร์ `scopes` -เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว ให้ส่ง resource indicator ใน parameter `resource` หรือ parameter ที่ชื่อใกล้เคียงกันขณะขอโทเค็นการเข้าถึง (เช่น เรียก `getAccessToken()`) +เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว ให้ส่ง resource indicator ในพารามิเตอร์ `resource` หรือพารามิเตอร์ที่มีชื่อคล้ายกันเมื่อขอโทเค็นการเข้าถึง (เช่น เรียก `getAccessToken()`) -ดูรายละเอียดแต่ละ SDK ได้ที่ [Quick starts](/quick-starts) +ดูรายละเอียดของแต่ละ SDK ได้ที่ [Quick starts](/quick-starts) -เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณใส่ parameter `resource` และ scopes ที่ต้องการใน authorization request +เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณใส่พารามิเตอร์ `resource` และ scopes ที่ต้องการใน authorization request -บางไลบรารีอาจไม่รองรับ parameter `resource` โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่ง parameter เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีที่คุณใช้ +ไลบรารีบางตัวอาจไม่รองรับพารามิเตอร์ `resource` โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่งพารามิเตอร์เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีของคุณสำหรับรายละเอียด -ตัวอย่าง authorization request ที่ไม่เป็นทางการพร้อม parameter `resource` และ `scope`: +นี่คือตัวอย่าง authorization request ที่ไม่เป็นทางการโดยใช้พารามิเตอร์ `resource` และ `scope`: -เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว คุณจะได้รับ authorization code นำ code นี้ไปแลกเป็น access token โดยส่ง POST request ไปที่ endpoint `/oidc/token` ของ Logto พร้อม parameter `resource` ใน request body +เมื่อผู้ใช้ได้รับการยืนยันตัวตนแล้ว คุณจะได้รับ authorization code นำ code นี้ไปแลกเป็น access token โดยส่ง POST request ไปที่ endpoint `/oidc/token` ของ Logto พร้อมพารามิเตอร์ `resource` ใน request body -ตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type authorization code: +นี่คือตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type แบบ authorization code: -คุณยังสามารถใช้ grant type `refresh_token` เพื่อขอโทเค็นการเข้าถึงใหม่โดยไม่ต้องให้ผู้ใช้โต้ตอบ ตราบใดที่มี parameter `resource` ใน request +คุณยังสามารถใช้ grant type แบบ `refresh_token` เพื่อขอโทเค็นการเข้าถึงใหม่โดยไม่ต้องมีการโต้ตอบของผู้ใช้ ตราบใดที่มีพารามิเตอร์ `resource` ใน request -ตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type refresh token: +นี่คือตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type แบบ refresh token: @@ -164,14 +165,14 @@ SDK อย่างเป็นทางการของ Logto ทั้งห #### Client credentials flow \{#client-credentials-flow} -สำหรับกรณีเครื่องต่อเครื่อง (M2M) คุณสามารถใช้ client credentials flow เพื่อขอโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลของคุณ โดยส่ง POST request ไปที่ endpoint `/oidc/token` ของ Logto เพื่อขอโทเค็นโดยใช้ client ID และ secret ของคุณ +สำหรับกรณีเครื่องต่อเครื่อง (M2M) คุณสามารถใช้ client credentials flow เพื่อขอโทเค็นการเข้าถึงสำหรับทรัพยากร API ระดับโกลบอลของคุณ โดยส่ง POST request ไปที่ endpoint `/oidc/token` ของ Logto คุณสามารถขอโทเค็นการเข้าถึงโดยใช้ client ID และ secret ของคุณ -มีสอง parameter สำคัญที่ต้องใส่ใน request: +มีสองพารามิเตอร์สำคัญที่ต้องใส่ใน request: - `resource`: URI ของ resource indicator ของ API ที่คุณต้องการเข้าถึง (เช่น `https://api.yourapp.com`) - `scope`: สิทธิ์ที่คุณต้องการร้องขอสำหรับ API (เช่น `read:products write:products`) -ตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type client credentials: +นี่คือตัวอย่าง token request ที่ไม่เป็นทางการโดยใช้ grant type แบบ client credentials: ## แนวปฏิบัติที่ดีและเคล็ดลับด้านความปลอดภัย \{#best-practices-and-security-tips} -- **ตั้งชื่อสิทธิ์ให้สอดคล้องกับธุรกิจ:** ใช้ชื่อที่ชัดเจนและสื่อถึงการกระทำจริง +- **กำหนดสิทธิ์ตามธุรกิจ:** ใช้ชื่อที่ชัดเจนและสอดคล้องกับการกระทำจริง - **ตั้งอายุโทเค็นให้สั้น:** ลดความเสี่ยงหากโทเค็นรั่วไหล - **จำกัด scope ที่ให้:** ให้โทเค็นเฉพาะสิทธิ์ที่จำเป็นจริง ๆ -- **ใช้ audience restriction:** ตรวจสอบ claim `aud` เสมอเพื่อป้องกันการนำไปใช้ผิดวัตถุประสงค์ +- **ใช้การจำกัดผู้รับ (audience restriction):** ตรวจสอบ claim `aud` เสมอเพื่อป้องกันการนำไปใช้ผิดวัตถุประสงค์ ## คำถามที่พบบ่อย \{#faqs}
-### ถ้าไคลเอนต์ของฉันไม่รองรับ parameter resource ล่ะ? \{#what-if-my-client-doesn-t-support-the-resource-parameter} +### ถ้าไคลเอนต์ของฉันไม่รองรับพารามิเตอร์ resource ล่ะ? \{#what-if-my-client-doesn-t-support-the-resource-parameter} -ตั้งค่า API resource เริ่มต้นใน Logto Console โทเค็นจะใช้ audience นี้โดยอัตโนมัติเมื่อไม่มีการระบุ parameter resource ใน token request +ตั้งค่า API resource เริ่มต้นใน Logto Console โทเค็นจะใช้ audience นี้โดยอัตโนมัติเมื่อไม่มีการระบุ resource parameter ใน token request
-### ทำไม API ของฉันถึงได้ 401 Unauthorized? \{#why-do-i-get-401-unauthorized-from-my-api} +### ทำไมฉันถึงได้รับ 401 Unauthorized จาก API ของฉัน? \{#why-do-i-get-401-unauthorized-from-my-api} ตรวจสอบปัญหาทั่วไปดังต่อไปนี้: -- **ลายเซ็นของโทเค็น:** ตรวจสอบว่า backend ของคุณดึง JWKs ที่ถูกต้องจาก Logto -- **หมดอายุโทเค็น:** ตรวจสอบว่าโทเค็นยังไม่หมดอายุ (`exp` claim) -- **ผู้รับ (Audience):** ตรวจสอบว่า claim `aud` ตรงกับ resource indicator ที่คุณลงทะเบียนไว้ -- **scope ที่จำเป็น:** ตรวจสอบว่าโทเค็นมีสิทธิ์ที่จำเป็นใน claim `scope` +- **ลายเซ็นโทเค็น:** ตรวจสอบว่า backend ของคุณดึง JWKs ที่ถูกต้องจาก Logto +- **อายุโทเค็น:** ตรวจสอบว่าโทเค็นยังไม่หมดอายุ (`exp` claim) +- **ผู้รับ (Audience):** ตรวจสอบว่า claim `aud` ตรงกับ resource indicator ของ API ที่คุณลงทะเบียน +- **scope ที่ต้องการ:** ตรวจสอบว่าโทเค็นมีสิทธิ์ที่จำเป็นใน claim `scope`
@@ -241,18 +238,18 @@ JWT ที่ออกโดย Logto จะมีการอ้างสิท -ใช้ [personal access token](/user-management/personal-access-token) เพื่อจำลองการเรียก API แบบยืนยันตัวตน วิธีนี้ช่วยให้คุณทดสอบ endpoint ของ API ได้โดยไม่ต้องพัฒนา OAuth flow ครบชุดในแอปของคุณ +ใช้ [personal access token](/user-management/personal-access-token) เพื่อจำลองการเรียกแบบยืนยันตัวตน วิธีนี้ช่วยให้คุณทดสอบ endpoint ของ API ได้โดยไม่ต้องพัฒนา OAuth flow ครบถ้วนในแอปไคลเอนต์ของคุณ
-### ขอ scope แบบ prefix หรือแบบย่อได้ไหม? \{#can-i-use-scope-prefixes-or-shortened-versions} +### ขอสิทธิ์โดยใช้ prefix หรือชื่อย่อของ scope ได้หรือไม่? \{#can-i-use-scope-prefixes-or-shortened-versions} -ไม่ได้ ชื่อ scope ต้อง **ตรงกับ** ชื่อสิทธิ์ที่กำหนดไว้ใน API resource ของคุณเท่านั้น ไม่สามารถใช้ prefix หรือแบบย่อแทนได้ +ไม่ได้ ชื่อ scope ต้อง **ตรงกับ** ชื่อสิทธิ์ที่กำหนดไว้ใน API resource ของคุณเท่านั้น ไม่สามารถใช้ prefix หรือชื่อย่อเป็น wildcard ได้ **ตัวอย่าง:** @@ -267,7 +264,7 @@ JWT ที่ออกโดย Logto จะมีการอ้างสิท scopes: ["read:elections", "write:elections"] ``` -แบบนี้จะ **ไม่ได้ผล**: +แบบนี้จะ **ไม่ทำงาน**: ```swift scopes: ["read", "write"] // ❌ ไม่ตรงกับชื่อสิทธิ์ diff --git a/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 6b0760a5e05..c9a0a61fa66 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,21 +6,22 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; import InspectOrganizationClaim from './fragments/_inspect-organization-claim.md'; import OrganizationTokenWarning from './fragments/_organization-token-warning.md'; -# ปกป้องทรัพยากร API ระดับองค์กร (Protect organization-level API resources) +# ปกป้องทรัพยากร API ระดับองค์กร export const resource = 'https://api.your-app.com/organizations'; -ผสานทรัพยากร API เข้ากับเทมเพลตองค์กรเพื่อจำกัดการเข้าถึง API และข้อมูลภายในแต่ละองค์กร เพื่อให้มั่นใจว่ามีการแยกข้อมูลในระดับผู้เช่า (tenant) สำหรับ SaaS ของคุณ +ผสมผสานทรัพยากร API กับเทมเพลตองค์กรเพื่อจำกัดการเข้าถึง API และข้อมูลภายในแต่ละองค์กร เพื่อให้มั่นใจถึงการแยกข้อมูลในระดับผู้เช่า (tenant) สำหรับ SaaS ของคุณ ## ทรัพยากร API ระดับองค์กรคืออะไร? \{#what-are-organization-level-api-resources} -ทรัพยากร API ระดับองค์กรคือ endpoint หรือบริการในแอปของคุณที่ **ถูกจำกัดขอบเขตไว้กับองค์กรใดองค์กรหนึ่ง** API เหล่านี้จะบังคับใช้การอนุญาต (authorization) และการเข้าถึงตามบริบทขององค์กร เพื่อให้แน่ใจว่าผู้ใช้หรือไคลเอนต์จะเข้าถึงข้อมูลและการกระทำที่เกี่ยวข้องกับองค์กรของตนเท่านั้น +ทรัพยากร API ระดับองค์กร คือ endpoint หรือบริการในแอปพลิเคชันของคุณที่ **ถูกกำหนดขอบเขตให้กับองค์กรใดองค์กรหนึ่ง** API เหล่านี้จะบังคับใช้การอนุญาต (authorization) และการเข้าถึงตามบริบทขององค์กร เพื่อให้แน่ใจว่าผู้ใช้หรือไคลเอนต์จะเข้าถึงข้อมูลและการกระทำที่เกี่ยวข้องกับองค์กรของตนเท่านั้น **ตัวอย่างการใช้งาน** @@ -29,38 +30,38 @@ export const resource = 'https://api.your-app.com/organizations'; - Endpoint สำหรับการเรียกเก็บเงิน, การสมัครสมาชิก หรือการตรวจสอบที่ผูกกับองค์กร - API ใด ๆ ที่การกระทำและข้อมูลถูกแยกตามผู้เช่า (tenant) -Logto ช่วยให้คุณรักษาความปลอดภัยให้กับ API องค์กรเหล่านี้ด้วย OAuth 2.1 และ RBAC พร้อมรองรับสถาปัตยกรรม SaaS แบบหลายผู้เช่า (multi-tenant) +Logto ช่วยให้คุณรักษาความปลอดภัยให้กับ API องค์กรเหล่านี้โดยใช้ OAuth 2.1 และ RBAC พร้อมรองรับสถาปัตยกรรม SaaS แบบหลายผู้เช่า (multi-tenant) สิทธิ์เหล่านี้ถูกจัดการผ่าน **บทบาทขององค์กร (organization roles)** ที่กำหนดไว้ใน [เทมเพลตองค์กร](/authorization/organization-template) ทุกองค์กรจะใช้เทมเพลตเดียวกัน เพื่อให้แน่ใจว่ามีโมเดลสิทธิ์ที่สอดคล้องกันในทุกองค์กร ## วิธีการทำงานใน Logto \{#how-it-works-in-logto} - **ทรัพยากร API และสิทธิ์ถูกลงทะเบียนในระดับโกลบอล:** ทรัพยากร API แต่ละรายการจะถูกกำหนดด้วย resource indicator (URI) ที่ไม่ซ้ำกันและชุดสิทธิ์ (scopes) ใน Logto -- **บทบาทในระดับองค์กร:** บทบาทขององค์กรถูกกำหนดในเทมเพลตองค์กร สิทธิ์ของทรัพยากร API (scopes) จะถูกกำหนดให้กับบทบาทขององค์กร ซึ่งจะถูกกำหนดต่อให้กับผู้ใช้หรือไคลเอนต์ **ภายในแต่ละองค์กร** -- **การอนุญาตที่รับรู้บริบท:** เมื่อไคลเอนต์ร้องขอโทเค็นการเข้าถึง (access token) โดยระบุทั้ง API resource และ `organization_id` Logto จะออกโทเค็นที่มีทั้งบริบทขององค์กรและผู้รับ API ในโทเค็น สิทธิ์ (scopes) จะถูกกำหนดตามบทบาทของผู้ใช้ในองค์กรที่ระบุ -- **แยกจากทรัพยากรโกลบอล:** ทรัพยากร API สามารถเข้าถึงได้ทั้งแบบมีหรือไม่มีบริบทองค์กร RBAC ขององค์กรจะถูกนำมาใช้ก็ต่อเมื่อมี `organization_id` ในคำขอ สำหรับ API ที่ใช้ร่วมกันระหว่างผู้ใช้ทั้งหมด ดู [ปกป้องทรัพยากร API ระดับโกลบอล](/authorization/global-api-resources) +- **บทบาทในระดับองค์กร:** บทบาทขององค์กรถูกกำหนดในเทมเพลตองค์กร สิทธิ์ของทรัพยากร API (scopes) จะถูกกำหนดให้กับบทบาทขององค์กร ซึ่งจะถูกกำหนดให้กับผู้ใช้หรือไคลเอนต์ **ภายในแต่ละองค์กร** +- **การอนุญาตที่รับรู้บริบท:** เมื่อไคลเอนต์ร้องขอโทเค็นการเข้าถึงพร้อมทั้ง API resource และ `organization_id` Logto จะออกโทเค็นที่มีทั้งบริบทขององค์กรและ API audience สิทธิ์ (scopes) ของโทเค็นจะถูกกำหนดโดยบทบาทของผู้ใช้ในองค์กรที่ระบุ +- **แยกจากทรัพยากรโกลบอล:** ทรัพยากร API สามารถเข้าถึงได้ทั้งแบบมีหรือไม่มีบริบทองค์กร RBAC ขององค์กรจะถูกนำมาใช้ก็ต่อเมื่อมี `organization_id` ในคำขอ สำหรับ API ที่ใช้ร่วมกันระหว่างผู้ใช้ทุกคน ดู [ปกป้องทรัพยากร API ระดับโกลบอล](/authorization/global-api-resources) Organization-level API resources RBAC -### ภาพรวมการนำไปใช้ \{#implementation-overview} +### ภาพรวมการใช้งาน \{#implementation-overview} 1. **ลงทะเบียนทรัพยากร API ของคุณ** และกำหนดสิทธิ์ (scopes) ใน Logto 2. **กำหนดบทบาทองค์กร** ในเทมเพลตองค์กรและกำหนดสิทธิ์ API ที่เกี่ยวข้อง 3. **กำหนดบทบาท** ให้กับผู้ใช้หรือไคลเอนต์ภายในแต่ละองค์กร -4. **ร้องขอโทเค็นการเข้าถึง** สำหรับ API พร้อม `organization_id` เพื่อรวมบริบทองค์กร +4. **ร้องขอโทเค็นการเข้าถึง** สำหรับ API พร้อม `organization_id` เพื่อรวมบริบทขององค์กร 5. **ตรวจสอบโทเค็นการเข้าถึง** ใน API ของคุณ โดยบังคับใช้ทั้งบริบทองค์กรและสิทธิ์ ### วิธีที่ Logto ใช้ RBAC ระดับองค์กร \{#how-logto-applies-organization-rbac} - หากคุณร้องขอโทเค็นการเข้าถึง **โดยไม่มี** `organization_id` จะพิจารณาเฉพาะบทบาท/สิทธิ์ระดับโกลบอลเท่านั้น - หากคุณร้องขอโทเค็นการเข้าถึง **พร้อม** `organization_id` Logto จะประเมินบทบาทของผู้ใช้ในองค์กรและสิทธิ์ที่เกี่ยวข้องสำหรับองค์กรนั้น -- JWT ที่ได้จะมีทั้งผู้รับ API (`aud` claim) และบริบทองค์กร (`organization_id` claim) โดย scopes จะถูกกรองตามสิทธิ์ที่บทบาทของผู้ใช้ในองค์กรนั้นอนุญาต +- JWT ที่ได้จะมีทั้ง API audience (`aud` claim) และบริบทองค์กร (`organization_id` claim) โดย scopes จะถูกกรองเฉพาะที่ได้รับจากบทบาทของผู้ใช้ในองค์กรนั้น -### กระบวนการอนุญาต: การยืนยันตัวตนและปกป้อง API ด้วยบริบทองค์กร \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} +### กระบวนการอนุญาต: การยืนยันตัวตนและรักษาความปลอดภัย API ด้วยบริบทองค์กร \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} -แผนภาพต่อไปนี้แสดงขั้นตอนที่ไคลเอนต์ (เว็บ, มือถือ หรือ backend) ขอและใช้โทเค็นองค์กรเพื่อเข้าถึงทรัพยากร API ระดับองค์กร +แผนภาพต่อไปนี้แสดงให้เห็นว่าไคลเอนต์ (เว็บ, มือถือ หรือ backend) ขอและใช้โทเค็นองค์กรเพื่อเข้าถึงทรัพยากร API ระดับองค์กรอย่างไร -โปรดทราบว่า flow นี้ไม่ได้แสดงรายละเอียดพารามิเตอร์หรือ header ที่จำเป็นทั้งหมด แต่เน้นขั้นตอนสำคัญ อ่านต่อเพื่อดูตัวอย่างการใช้งานจริง +โปรดทราบว่า flow นี้ไม่ได้ลงรายละเอียดพารามิเตอร์หรือ header ที่จำเป็นทั้งหมด แต่เน้นขั้นตอนสำคัญที่เกี่ยวข้อง อ่านต่อเพื่อดูตัวอย่างการใช้งานจริง ```mermaid sequenceDiagram @@ -73,15 +74,15 @@ sequenceDiagram Logto->>Logto: เปลี่ยนเส้นทางผู้ใช้ไปยังหน้าลงชื่อเข้าใช้ Logto->>Client: เปลี่ยนเส้นทางกลับพร้อม `authorization_code` Client->>Logto: POST /oidc/token พร้อม `grant_type=authorization_code` - Logto->>Client: ส่งคืนโทเค็นรีเฟรช + Logto->>Client: ส่งคืน refresh token Client->>Logto: POST /oidc/token พร้อม `grant_type=refresh_token`
+ resource + organization_id else การยืนยันตัวตนของไคลเอนต์แบบเครื่องต่อเครื่อง (M2M) Client->>Logto: POST /oidc/token พร้อม `grant_type=client_credentials`
+ resource + organization_id end - Logto->>Client: ส่งคืนโทเค็นการเข้าถึง (JWT) - Client->>API: ส่งคำขอพร้อม Bearer token - API->>API: ตรวจสอบโทเค็น ตรวจสอบบริบทองค์กรและสิทธิ์ + Logto->>Client: ส่งคืน access token (JWT) + Client->>API: ร้องขอด้วย Bearer token + API->>API: ตรวจสอบโทเค็น, ตรวจสอบบริบทองค์กรและสิทธิ์ alt โทเค็นถูกต้อง API->>Client: ส่งคืนข้อมูลองค์กร @@ -90,16 +91,16 @@ sequenceDiagram end ``` -_การยืนยันตัวตนของผู้ใช้ = เบราว์เซอร์/แอป M2M = บริการ backend หรือสคริปต์ที่ใช้ client credentials + บริบทองค์กร_ +_การยืนยันตัวตนของผู้ใช้ = เบราว์เซอร์/แอป. M2M = บริการ backend หรือ script ที่ใช้ client credentials + บริบทองค์กร_ -## ขั้นตอนการนำไปใช้ \{#implementation-steps} +## ขั้นตอนการใช้งาน \{#implementation-steps} ### ลงทะเบียนทรัพยากร API ของคุณ \{#register-your-api-resource} 1. ไปที่ Console → API resources 2. สร้างทรัพยากร API ใหม่ (เช่น `https://api.yourapp.com/org`) และกำหนดสิทธิ์ (scopes) -สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู [กำหนดทรัพยากร API พร้อมสิทธิ์](/authorization/role-based-access-control#define-api-resources-with-permissions) +สำหรับขั้นตอนการตั้งค่าแบบละเอียด ดู [กำหนดทรัพยากร API พร้อมสิทธิ์](/authorization/role-based-access-control#define-api-resources-with-permissions) ### ตั้งค่าบทบาทองค์กร \{#set-up-organization-roles} @@ -107,7 +108,7 @@ _การยืนยันตัวตนของผู้ใช้ = เบ 2. สร้างบทบาทองค์กร (เช่น `admin`, `member`) และกำหนดสิทธิ์ API ให้แต่ละบทบาท 3. กำหนดบทบาทให้กับผู้ใช้หรือไคลเอนต์ภายในแต่ละองค์กร หากยังไม่เป็นสมาชิก ให้เชิญหรือเพิ่มเข้าก่อน -สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู [ใช้บทบาทองค์กร](/authorization/role-based-access-control#configure-organization-roles) +สำหรับขั้นตอนการตั้งค่าแบบละเอียด ดู [การใช้บทบาทองค์กร](/authorization/role-based-access-control#configure-organization-roles) ### ขอรับโทเค็นองค์กรสำหรับทรัพยากร API \{#obtain-organization-tokens-for-api-resources} @@ -115,20 +116,20 @@ _การยืนยันตัวตนของผู้ใช้ = เบ #### Refresh token flow \{#refresh-token-flow} -เกือบทุก SDK อย่างเป็นทางการของ Logto รองรับการขอโทเค็นองค์กรผ่าน refresh token flow ได้ทันที คุณยังสามารถใช้ไลบรารี OAuth 2.0 / OIDC มาตรฐานเพื่อทำ flow นี้ได้ +เกือบทุก SDK อย่างเป็นทางการของ Logto รองรับการขอโทเค็นองค์กรผ่าน refresh token flow ได้ทันที คุณยังสามารถใช้ไลบรารี OAuth 2.0 / OIDC client มาตรฐานเพื่อใช้งาน flow นี้ได้ -เมื่อเริ่มต้น Logto SDK ให้เพิ่ม `urn:logto:scope:organizations` และสิทธิ์องค์กรที่ต้องการ (scopes) ลงในพารามิเตอร์ `scopes` +เมื่อเริ่มต้น Logto SDK ให้เพิ่ม `urn:logto:scope:organizations` และสิทธิ์ขององค์กรที่ต้องการ (scopes) ลงในพารามิเตอร์ `scopes` บาง SDK ของ Logto มี scope สำหรับองค์กรที่กำหนดไว้ล่วงหน้า เช่น `UserScope.Organizations` ใน JavaScript SDK -เมื่อเรียกใช้ `getAccessToken()` ให้ระบุทั้ง API resource (`resource`) และรหัสองค์กร (`organizationId`) เพื่อขอโทเค็นองค์กร +เมื่อเรียก `getAccessToken()` ให้ระบุทั้ง API resource (`resource`) และรหัสองค์กร (`organizationId`) เพื่อขอโทเค็นองค์กร -ดูรายละเอียดแต่ละ SDK ได้ที่ [Quick starts](/quick-starts) +ดูรายละเอียดของแต่ละ SDK ได้ที่ [Quick starts](/quick-starts) @@ -136,11 +137,11 @@ _การยืนยันตัวตนของผู้ใช้ = เบ เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณรวมพารามิเตอร์ต่อไปนี้: - `resource`: ตั้งค่าเป็นตัวระบุทรัพยากร API ที่ลงทะเบียนใน Logto (เช่น `https://api.your-app.com/organizations`) -- `scope`: รวม scope องค์กรที่กำหนดไว้ (`urn:logto:scope:organizations`), `offline_access` (เพื่อขอโทเค็นรีเฟรช) และสิทธิ์ API เฉพาะที่ต้องการ (เช่น `manage:members view:analytics`) +- `scope`: รวม scope องค์กรที่กำหนดไว้ (`urn:logto:scope:organizations`), `offline_access` (เพื่อรับ refresh token) และสิทธิ์ API เฉพาะที่คุณต้องการ (เช่น `manage:members view:analytics`) -บางไลบรารีอาจไม่รองรับพารามิเตอร์ `resource` โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่งพารามิเตอร์เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีของคุณ +บางไลบรารีอาจไม่รองรับ `resource` โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่งพารามิเตอร์เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีที่คุณใช้ -ตัวอย่างที่ไม่เป็นทางการของ authorization request: +ตัวอย่างที่ไม่เป็นทางการของ authorization request อาจมีลักษณะดังนี้: -สุดท้าย ใช้ refresh token เพื่อขอโทเค็นองค์กรโดยส่ง POST ไปที่ `/oidc/token` ของ Logto อย่าลืมระบุ: +สุดท้าย ใช้ refresh token เพื่อขอโทเค็นองค์กรโดยส่ง POST ไปที่ endpoint `/oidc/token` ของ Logto อย่าลืมระบุ: - พารามิเตอร์ `resource` ตั้งค่าเป็นตัวระบุทรัพยากร API (เช่น `https://api.yourapp.com/org`) - พารามิเตอร์ `organization_id` ตั้งค่าเป็นรหัสองค์กรที่ต้องการ -- (ไม่บังคับ) พารามิเตอร์ `scope` เพื่อจำกัดสิทธิ์ที่ต้องการ (เช่น `manage:members view:reports`) +- (ไม่บังคับ) พารามิเตอร์ `scope` เพื่อจำกัดสิทธิ์ที่ต้องการเพิ่มเติม (เช่น `manage:members view:reports`) ตัวอย่างที่ไม่เป็นทางการของ token request: @@ -178,13 +179,13 @@ _การยืนยันตัวตนของผู้ใช้ = เบ #### Client credentials flow \{#client-credentials-flow} -สำหรับกรณีเครื่องต่อเครื่อง (M2M) คุณสามารถใช้ client credentials flow เพื่อขอโทเค็นการเข้าถึงสำหรับสิทธิ์ทรัพยากร API ระดับองค์กร โดยส่ง POST ไปที่ `/oidc/token` ของ Logto พร้อมพารามิเตอร์องค์กร คุณสามารถขอโทเค็นองค์กรโดยใช้ client ID และ secret ของคุณ +สำหรับกรณีเครื่องต่อเครื่อง (M2M) คุณสามารถใช้ client credentials flow เพื่อขอโทเค็นการเข้าถึงสำหรับสิทธิ์ทรัพยากร API ระดับองค์กร โดยส่ง POST ไปที่ endpoint `/oidc/token` ของ Logto พร้อมพารามิเตอร์องค์กร คุณสามารถขอโทเค็นองค์กรโดยใช้ client ID และ secret ของคุณ -พารามิเตอร์สำคัญที่ต้องระบุในคำขอ: +พารามิเตอร์สำคัญที่ต้องรวมในคำขอ: - `resource`: ตัวระบุทรัพยากร API (เช่น `https://api.yourapp.com/org`) -- `organization_id`: รหัสองค์กรที่ต้องการโทเค็น -- `scope`: สิทธิ์ทรัพยากร API ระดับองค์กรที่ต้องการ (เช่น `invite:member`, `manage:billing`) +- `organization_id`: รหัสองค์กรที่คุณต้องการโทเค็น +- `scope`: สิทธิ์ทรัพยากร API ระดับองค์กรที่คุณต้องการ (เช่น `invite:member`, `manage:billing`) ตัวอย่างที่ไม่เป็นทางการของ token request ด้วย client credentials grant type: @@ -196,28 +197,30 @@ _การยืนยันตัวตนของผู้ใช้ = เบ ### ตรวจสอบโทเค็นองค์กร \{#validate-organization-tokens} -โทเค็นองค์กร (JWTs) ที่ออกโดย Logto จะมีการอ้างสิทธิ์ (claims) ที่ API ของคุณสามารถใช้เพื่อบังคับใช้การควบคุมการเข้าถึงระดับองค์กร +โทเค็นองค์กร (JWTs) ที่ออกโดย Logto จะมี claim ที่ API ของคุณสามารถใช้เพื่อบังคับใช้การควบคุมการเข้าถึงระดับองค์กร -เมื่อแอปของคุณได้รับโทเค็นองค์กร ควร: +เมื่อแอปของคุณได้รับโทเค็นองค์กร คุณควร: -- ตรวจสอบลายเซ็นโทเค็น (โดยใช้ JWKs ของ Logto) +- ตรวจสอบลายเซ็นของโทเค็น (โดยใช้ JWKs ของ Logto) - ยืนยันว่าโทเค็นไม่หมดอายุ (`exp` claim) -- ตรวจสอบว่า `iss` (ผู้ออก) ตรงกับ endpoint Logto ของคุณ -- ตรวจสอบว่า `aud` (ผู้รับ) ตรงกับตัวระบุทรัพยากร API ที่คุณลงทะเบียน (เช่น `https://api.yourapp.com/org`) -- ตรวจสอบ `organization_id` claim เพื่อให้แน่ใจว่าโทเค็นถูกจำกัดขอบเขตกับองค์กรที่ถูกต้อง +- ตรวจสอบว่า `iss` (issuer) ตรงกับ endpoint Logto ของคุณ +- ตรวจสอบว่า `aud` (audience) ตรงกับตัวระบุทรัพยากร API ที่คุณลงทะเบียน (เช่น `https://api.yourapp.com/org`) +- ตรวจสอบ claim `organization_id` เพื่อให้แน่ใจว่าโทเค็นถูกจำกัดขอบเขตกับองค์กรที่ถูกต้อง - แยก claim `scope` (คั่นด้วยช่องว่าง) และตรวจสอบสิทธิ์ที่ต้องการ -- หาก path ของ API มีรหัสองค์กร (เช่น `/organizations/{organizationId}/members`) ให้ตรวจสอบว่า `organization_id` claim ตรงกับ path parameter +- หาก path ของ API มีรหัสองค์กร (เช่น `/organizations/{organizationId}/members`) ให้ตรวจสอบว่า claim `organization_id` ตรงกับพารามิเตอร์ path -สำหรับคู่มือแบบ step-by-step และเฉพาะภาษา ดู [วิธีตรวจสอบโทเค็นการเข้าถึง](/authorization/validate-access-tokens) +สำหรับคู่มือแบบทีละขั้นตอนและเฉพาะภาษา ดู [วิธีตรวจสอบโทเค็นการเข้าถึง](/authorization/validate-access-tokens) + + ## แนวปฏิบัติที่ดีและเคล็ดลับด้านความปลอดภัย \{#best-practices-and-security-tips} -- **ตรวจสอบบริบทองค์กรเสมอ:** อย่าเชื่อถือแค่โทเค็น ให้ตรวจสอบ `organization_id` claim สำหรับทุก API ที่จำกัดขอบเขตองค์กร -- **ใช้ข้อจำกัดผู้รับ (audience restrictions):** ตรวจสอบ claim `aud` เสมอเพื่อให้แน่ใจว่าโทเค็นสำหรับองค์กรที่ต้องการ +- **ตรวจสอบบริบทองค์กรเสมอ:** อย่าเชื่อถือแค่โทเค็น ให้ตรวจสอบ claim `organization_id` สำหรับทุก API ที่จำกัดขอบเขตองค์กร +- **ใช้ข้อจำกัด audience:** ตรวจสอบ claim `aud` เสมอเพื่อให้แน่ใจว่าโทเค็นสำหรับองค์กรที่ต้องการ - **ให้สิทธิ์สอดคล้องกับธุรกิจ:** ใช้ชื่อที่ชัดเจนและตรงกับการกระทำจริง กำหนดเฉพาะสิ่งที่จำเป็นสำหรับแต่ละบทบาทองค์กร - **แยกสิทธิ์ API และ non-API** หากเป็นไปได้ (แต่ทั้งสองอย่างสามารถอยู่ในบทบาทเดียวกันได้) - **กำหนดอายุโทเค็นให้สั้น:** ลดความเสี่ยงหากโทเค็นรั่วไหล -- **ทบทวนเทมเพลตองค์กรของคุณเป็นประจำ:** อัปเดตบทบาทและสิทธิ์เมื่อผลิตภัณฑ์ของคุณพัฒนา +- **ทบทวนเทมเพลตองค์กรของคุณเป็นประจำ:** อัปเดตบทบาทและสิทธิ์เมื่อผลิตภัณฑ์ของคุณเปลี่ยนแปลง ## คำถามที่พบบ่อย \{#faqs} @@ -228,7 +231,7 @@ _การยืนยันตัวตนของผู้ใช้ = เบ -จะพิจารณาเฉพาะบทบาท/สิทธิ์ระดับโกลบอลเท่านั้น RBAC ขององค์กรจะไม่ถูกนำมาใช้ +จะพิจารณาเฉพาะบทบาท/สิทธิ์ระดับโกลบอลเท่านั้น RBAC ขององค์กรจะไม่ถูกบังคับใช้
@@ -246,8 +249,8 @@ _การยืนยันตัวตนของผู้ใช้ = เบ ## อ่านเพิ่มเติม \{#further-reading} วิธีตรวจสอบโทเค็นการเข้าถึง -ปรับแต่งการอ้างสิทธิ์ในโทเค็น +ปรับแต่ง token claims - กรณีศึกษา: สร้างแอปพลิเคชัน SaaS แบบหลายผู้เช่า + กรณีศึกษา: สร้างแอป SaaS แบบหลายผู้เช่า RFC 8707: Resource Indicators diff --git a/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index c88b10cd71c..85cd2c3750d 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -18,7 +19,7 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md ## สิทธิ์ขององค์กร (ที่ไม่ใช่ API) คืออะไร? \{#what-are-organization-non-api-permissions} -สิทธิ์ขององค์กร (ที่ไม่ใช่ API) จะควบคุมสิ่งที่ผู้ใช้สามารถทำได้ **ภายในบริบทขององค์กร** แต่จะไม่ **บังคับใช้ในระดับ API** โดยจะควบคุมการเข้าถึงฟีเจอร์ของแอป องค์ประกอบ UI เวิร์กโฟลว์ หรือการดำเนินการทางธุรกิจ แทนที่จะเป็น API ฝั่ง backend +สิทธิ์ขององค์กร (ที่ไม่ใช่ API) จะควบคุมสิ่งที่ผู้ใช้สามารถทำได้ **ภายในบริบทขององค์กร** แต่จะไม่ **ถูกบังคับใช้ในระดับ API** โดยจะควบคุมการเข้าถึงฟีเจอร์ของแอป องค์ประกอบ UI เวิร์กโฟลว์ หรือการดำเนินการทางธุรกิจ แทนที่จะเป็น API ฝั่ง backend **ตัวอย่างการใช้งาน เช่น** @@ -27,15 +28,15 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md - จัดการการเรียกเก็บเงิน การตั้งค่า หรือฟังก์ชันผู้ดูแลระบบขององค์กร - เข้าถึงแดชบอร์ด การวิเคราะห์ หรือเครื่องมือภายในที่ไม่มี API endpoint -Logto ช่วยให้คุณรักษาความปลอดภัยของสิทธิ์องค์กรเหล่านี้โดยใช้ OAuth 2.1 และ RBAC พร้อมรองรับสถาปัตยกรรม SaaS แบบหลายผู้เช่า (multi-tenant) +Logto ช่วยให้คุณรักษาความปลอดภัยสิทธิ์ขององค์กรเหล่านี้โดยใช้ OAuth 2.1 และ RBAC พร้อมรองรับสถาปัตยกรรม SaaS แบบหลายผู้เช่า -สิทธิ์เหล่านี้ถูกจัดการผ่าน **บทบาทขององค์กร** ที่กำหนดไว้ใน [เทมเพลตองค์กร](/authorization/organization-template) โดยทุกองค์กรจะใช้เทมเพลตเดียวกัน เพื่อให้แนวทางการกำหนดสิทธิ์สอดคล้องกันในทุกองค์กร +สิทธิ์เหล่านี้ถูกจัดการผ่าน **บทบาทขององค์กร** ที่กำหนดไว้ใน [เทมเพลตองค์กร](/authorization/organization-template) โดยทุกองค์กรจะใช้เทมเพลตเดียวกัน เพื่อให้แนวทางสิทธิ์สอดคล้องกันในทุกองค์กร ## วิธีการทำงานใน Logto \{#how-it-works-in-logto} - **RBAC ระดับองค์กร:** บทบาทและสิทธิ์ถูกกำหนดในเทมเพลตองค์กร เมื่อผู้ใช้เข้าร่วมองค์กร จะได้รับบทบาทหนึ่งหรือมากกว่าเพื่อรับสิทธิ์ที่กำหนด -- **การบังคับใช้ที่ไม่ใช่ API:** การตรวจสอบและบังคับใช้สิทธิ์จะเกิดขึ้นใน UI ของแอป เวิร์กโฟลว์ หรือ logic ฝั่ง backend ของคุณ ไม่จำเป็นต้องผ่าน API gateway -- **แยกจากการปกป้อง API:** สิทธิ์ขององค์กร (ที่ไม่ใช่ API) แตกต่างจากสิทธิ์ของทรัพยากร API คุณสามารถผสมผสานทั้งสองแบบสำหรับกรณีการใช้งานขั้นสูงได้ +- **การบังคับใช้ที่ไม่ใช่ API:** การตรวจสอบสิทธิ์จะเกิดขึ้นใน UI ของแอป เวิร์กโฟลว์ หรือ logic ฝั่ง backend ของคุณ ไม่จำเป็นต้องผ่าน API gateway +- **แยกจากการปกป้อง API:** สิทธิ์ขององค์กร (ที่ไม่ใช่ API) จะแตกต่างจากสิทธิ์ของทรัพยากร API คุณสามารถผสมผสานทั้งสองแบบสำหรับกรณีการใช้งานขั้นสูง
Console → เทมเพลตองค์กร → บทบาทขององค์กร -2. สร้างบทบาทที่รวมสิทธิ์ขององค์กรที่คุณกำหนดไว้ก่อนหน้านี้ (เช่น `admin`, `member`, `billing`) +2. สร้างบทบาทที่รวมสิทธิ์ขององค์กรที่คุณกำหนดไว้ก่อนหน้า (เช่น `admin`, `member`, `billing`) 3. กำหนดบทบาทเหล่านี้ให้กับผู้ใช้หรือ client ในแต่ละองค์กร -สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู [การใช้บทบาทขององค์กร](/authorization/role-based-access-control#configure-organization-roles) +สำหรับขั้นตอนการตั้งค่าแบบเต็ม ดู [ใช้บทบาทขององค์กร](/authorization/role-based-access-control#configure-organization-roles) ### ขอรับโทเค็นองค์กร (ที่ไม่ใช่ API) \{#obtain-organization-tokens-non-api} @@ -112,32 +113,32 @@ client/แอปของคุณควรขอโทเค็นองค์ #### Refresh token flow \{#refresh-token-flow} -เกือบทุก SDK อย่างเป็นทางการของ Logto รองรับการขอโทเค็นองค์กรโดยใช้ refresh token flow ได้ทันที คุณยังสามารถใช้ไลบรารี client มาตรฐาน OAuth 2.0 / OIDC เพื่อดำเนินการ flow นี้ได้ +เกือบทุก SDK อย่างเป็นทางการของ Logto รองรับการขอโทเค็นองค์กรโดยใช้ refresh token flow ได้ทันที ไลบรารี client มาตรฐาน OAuth 2.0 / OIDC ก็สามารถนำไปใช้ได้เช่นกัน เมื่อเริ่มต้น Logto SDK ให้เพิ่ม `urn:logto:scope:organizations` และสิทธิ์ขององค์กรที่ต้องการ (scopes) ลงในพารามิเตอร์ `scopes` -SDK บางตัวของ Logto มี scope สำหรับองค์กรที่กำหนดไว้ล่วงหน้า เช่น `UserScope.Organizations` ใน JavaScript SDK +บาง SDK ของ Logto มี scope สำหรับองค์กรที่กำหนดไว้ล่วงหน้า เช่น `UserScope.Organizations` ใน JavaScript SDK ใช้ `getOrganizationToken` หรือเมธอดที่คล้ายกัน (เช่น `getAccessToken` พร้อม organization ID) เพื่อขอโทเค็นองค์กรสำหรับองค์กรที่ต้องการ -ดูรายละเอียดของแต่ละ SDK ได้ที่ [เริ่มต้นอย่างรวดเร็ว](/quick-starts) +สำหรับรายละเอียดของแต่ละ SDK ดู [Quick starts](/quick-starts) -เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณรวมพารามิเตอร์ต่อไปนี้: +เมื่อกำหนดค่า OAuth 2.0 client หรือเริ่มต้น authorization code flow ให้แน่ใจว่าคุณใส่พารามิเตอร์ต่อไปนี้: -- `resource`: ตั้งค่าเป็น `urn:logto:resource:organizations` เพื่อระบุว่าคุณต้องการโทเค็นองค์กร +- `resource`: ตั้งค่าเป็น `urn:logto:resource:organizations` เพื่อระบุว่าต้องการโทเค็นองค์กร - `scope`: รวม scope องค์กรที่กำหนดไว้ (`urn:logto:scope:organizations`), `offline_access` (เพื่อรับ refresh token) และสิทธิ์ขององค์กรที่ต้องการ (เช่น `invite:member`, `manage:billing`) -ไลบรารีบางตัวอาจไม่รองรับพารามิเตอร์ `resource` โดยตรง แต่โดยทั่วไปจะสามารถส่งพารามิเตอร์เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีที่คุณใช้ +บางไลบรารีอาจไม่รองรับพารามิเตอร์ `resource` โดยตรง แต่โดยทั่วไปจะอนุญาตให้ส่งพารามิเตอร์เพิ่มเติมใน authorization request ได้ ตรวจสอบเอกสารของไลบรารีของคุณ -ตัวอย่างที่ไม่เป็นทางการของ authorization request อาจมีลักษณะดังนี้: +ตัวอย่างที่ไม่เป็นทางการของ authorization request: -- **อย่าพึ่งพาการบังคับใช้ใน UI เพียงอย่างเดียว:** ควรตรวจสอบสิทธิ์ใน backend สำหรับการดำเนินการสำคัญเสมอ +## แนวปฏิบัติที่ดีและเคล็ดลับด้านความปลอดภัย \{#best-practices-and-security-tips} + +- **อย่าอาศัยการบังคับใช้เฉพาะ UI:** ควรตรวจสอบสิทธิ์ใน backend สำหรับการดำเนินการสำคัญเสมอ - **ใช้ข้อจำกัดผู้รับ (audience restriction):** ตรวจสอบ claim `aud` เสมอเพื่อให้แน่ใจว่าโทเค็นสำหรับองค์กรที่ต้องการ -- **ตั้งชื่อสิทธิ์ให้สอดคล้องกับธุรกิจ:** ใช้ชื่อที่ชัดเจนและตรงกับการกระทำจริง กำหนดเฉพาะสิทธิ์ที่จำเป็นสำหรับแต่ละบทบาทขององค์กร +- **ตั้งชื่อสิทธิ์ให้สอดคล้องกับธุรกิจ:** ใช้ชื่อที่ชัดเจนและตรงกับการกระทำจริง กำหนดเฉพาะสิทธิ์ที่จำเป็นสำหรับแต่ละบทบาทองค์กร - **แยกสิทธิ์ API และที่ไม่ใช่ API** เมื่อเป็นไปได้ (แต่สามารถอยู่ในบทบาทเดียวกันได้) -- **ทบทวนเทมเพลตองค์กรเป็นประจำ** เมื่อผลิตภัณฑ์ของคุณมีการเปลี่ยนแปลง +- **ทบทวนเทมเพลตองค์กรเป็นประจำ** เมื่อผลิตภัณฑ์ของคุณพัฒนา ## คำถามที่พบบ่อย \{#faqs} @@ -235,5 +238,5 @@ SDK บางตัวของ Logto มี scope สำหรับองค วิธีตรวจสอบ access token การปรับแต่ง token claims - กรณีศึกษา: สร้างแอปพลิเคชัน SaaS แบบหลายผู้เช่า + กรณีศึกษา: สร้างแอป SaaS แบบหลายผู้เช่า diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..bb622e2d4dd --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### 可选：处理用户权限变更 \{#optional-handle-user-permission-change} + +用户权限随时可能发生变化。由于 Logto 为基于角色的访问控制 (RBAC) 签发 JWT，权限更新只会出现在新签发的令牌中，永远不会修改已有的 JWT。 + +:::info 权限 (Scope) 子集规则 +访问令牌 (Access token) 只能包含在原始 OAuth 授权 (Authorization) 流程中请求的权限 (Scopes)。 +即使用户获得了新的权限 (Permissions)，之后签发的令牌也只能包含最初请求权限 (Scopes) 的子集。 +要访问最初未请求的新权限 (Scopes)，客户端必须重新发起授权 (Authorization) 流程。 +::: + +#### 权限收缩 \{#downscoped-permissions} + +当用户失去权限时： + +- 新签发的令牌会立即反映减少后的权限 (Scopes)。 +- 已有的 JWT 会保留旧的权限 (Scopes)，直到过期为止。 +- 你的 API 应始终校验权限 (Scopes)，并依赖较短的令牌有效期。 + +如果你需要更快的响应，可以实现自己的信号机制，通知客户端刷新令牌。 + +#### 权限扩大 \{#enlarged-permissions} + +{props.type === "global" &&

对于全局 API 资源，当用户获得新权限时，权限扩大不会通过刷新立即体现。客户端必须重新执行 OAuth 授权 (Authorization) 流程，才能获取包含新权限 (Scopes) 的令牌。如果用户有活跃的 Logto 会话，这一过程可以静默完成。

} + +{props.type === "organization" &&

对于组织令牌 (Organization token)，当用户获得新权限时，权限扩大会在下次签发（刷新或令牌请求）时体现。仍然需要获取新令牌，但除非新权限 (Scopes) 超出最初请求集，否则无需完全重新认证 (Authentication)。

} + +#### 建议 \{#recommendations} + +- 在每次 API 调用时校验权限 (Scopes)。 +- 保持令牌过期时间较短。 +- 如需权限变更即时生效，可增加可选通知机制。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index b2aea8b168f..f044208d768 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -27,11 +28,11 @@ export const resource = 'https://api.your-app.com'; Logto 允许你结合 OAuth 2.1 和灵活的基于角色的访问控制来保护这些 API。 -## 在 Logto 中如何工作 \{#how-it-works-in-logto} +## 在 Logto 中的工作原理 \{#how-it-works-in-logto} -- **API 资源和权限是全局注册的**：你想要保护的每个 API 都用唯一的资源指示器（URI）和一组控制访问的权限（scopes）进行定义。 -- **访问由全局角色控制**：你可以将权限分配给角色，然后将角色分配给用户或客户端。 -- **与组织级权限分离**：全局 API 资源没有组织上下文。但如有需要，可以与组织角色结合使用，提供额外的上下文层。要保护组织级 API，请参见 [保护组织级 API 资源](/authorization/organization-level-api-resources)。 +- **API 资源和权限全局注册：** 你想要保护的每个 API 都用唯一的资源指示器（URI）和一组控制访问的权限（scopes）进行定义。 +- **通过全局角色控制访问：** 你可以将权限分配给角色，然后将角色分配给用户或客户端。 +- **与组织级权限分离：** 全局 API 资源没有组织上下文。但如有需要，可以与组织角色结合使用，提供额外的上下文层。要保护组织级 API，请参见 [保护组织级 API 资源](/authorization/organization-level-api-resources)。 全局 API 资源 RBAC @@ -40,7 +41,7 @@ Logto 允许你结合 OAuth 2.1 和灵活的基于角色的访问控制来保护 1. **注册你的 API 资源** 并在 Logto 中定义其权限。 2. **定义角色**，为访问 API 分配所需权限。 3. **分配角色** 给用户或客户端。 -4. **使用 OAuth 2.0 授权流程** 获取 API 的访问令牌（resource 参数必须与注册的 API 标识符一致）。 +4. **使用 OAuth 2.0 授权 (Authorization) 流程** 获取 API 的访问令牌（resource 参数必须与注册的 API 标识符一致）。 5. **在你的 API 中验证访问令牌**，以强制执行权限。 ### 理解资源指示器 \{#understanding-resource-indicators} @@ -58,27 +59,27 @@ Logto 按照 [RFC 8707: OAuth 2.0 的资源指示器](https://www.rfc-editor.org - Management API: `https://my-tenant.logto.app/api` - 自定义全局 API: `https://api.yourapp.com` -### 授权流程：认证 (Authentication) 并保护你的 API \{#authorization-flow-authenticating-and-securing-your-api} +### 授权 (Authorization) 流程：认证 (Authentication) 并保护你的 API \{#authorization-flow-authenticating-and-securing-your-api} -以下流程适用于交互式用户认证 (Authentication)（浏览器 / 应用）和后端机器对机器 (M2M) 场景。 +下述流程适用于交互式用户认证 (Authentication)（浏览器 / 应用）和后端机器对机器 (M2M) 场景。 -请注意，该流程未包含所有必需参数或头信息的详细说明，重点展示关键步骤。继续阅读以了解实际流程。 +请注意，该流程未包含所有必需参数或头部的详细信息，重点展示关键步骤。继续阅读以了解实际流程。 ```mermaid sequenceDiagram participant Client as 客户端 - participant Logto + participant Logto as Logto participant API as API 资源 alt 用户认证 (Authentication) Client->>Logto: GET /oidc/auth Logto->>Logto: 重定向用户到登录页面 - Logto->>Client: 重定向回带有 `authorization_code` - alt 使用 authorization_code 授权码模式 + Logto->>Client: 登录后重定向并带有 `authorization_code` + alt 使用 authorization_code 授权 (Authorization) 码模式 Client->>Logto: POST /oidc/token，带 `grant_type=authorization_code`
和 `resource` 参数 else 使用 refresh_token 模式 Client->>Logto: POST /oidc/token，带 `grant_type=authorization_code` - Logto->>Client: 返回刷新令牌 (refresh token) + Logto->>Client: 返回刷新令牌 (Refresh token) Client->>Logto: POST /oidc/token，带 `grant_type=refresh_token`
和 `resource` 参数 end else 机器对机器 (M2M) 客户端认证 (Authentication) @@ -92,11 +93,11 @@ sequenceDiagram alt 令牌有效 API->>Client: 返回受保护的资源数据 else 令牌无效 - API->>Client: 401 未授权 + API->>Client: 401 未授权 (Unauthorized) end ``` -_用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭证的后端服务或脚本。_ +_用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭据的后端服务或脚本。_ :::note `resource` 参数必须与 Logto 中注册的 API 标识符（资源指示器）完全一致。 @@ -119,125 +120,121 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 完整配置步骤见 [使用全局角色](/authorization/role-based-access-control#configure-global-roles)。 -### 获取全局 API 资源的访问令牌 \{#obtain-access-tokens-for-global-api-resources} +### 获取全局 API 资源的访问令牌 (Access token) \{#obtain-access-tokens-for-global-api-resources} -在访问全局 API 资源前，你的客户端必须获取访问令牌。Logto 会为全局 API 资源签发 [JSON Web Token (JWT)](https://auth.wiki/jwt) 作为访问令牌。通常使用 [OAuth 2.0 授权码流程](https://auth.wiki/authorization-code-flow)、[刷新令牌流程](https://auth.wiki/refresh-token) 或 [客户端凭证流程](https://auth.wiki/client-credentials-flow) 完成。 +在访问全局 API 资源前，你的客户端必须获取访问令牌 (访问令牌 (Access token))。Logto 会为全局 API 资源签发 [JSON Web Token (JWT)](https://auth.wiki/jwt) 作为访问令牌 (Access token)。这通常通过 [OAuth 2.0 授权 (Authorization) 码流程](https://auth.wiki/authorization-code-flow)、[刷新令牌 (Refresh token) 流程](https://auth.wiki/refresh-token) 或 [客户端凭据流程](https://auth.wiki/client-credentials-flow) 完成。 -#### 授权码或刷新令牌流程 \{#authorization-code-or-refresh-token-flow} +#### 授权 (Authorization) 码或刷新令牌 (Refresh token) 流程 \{#authorization-code-or-refresh-token-flow} -所有 Logto 官方 SDK 都原生支持使用刷新令牌流程获取全局 API 资源的访问令牌。你也可以用标准 OAuth 2.0 / OIDC 客户端库实现该流程。 +所有 Logto 官方 SDK 都原生支持通过刷新令牌 (Refresh token) 流程获取全局 API 资源的访问令牌 (Access token)。你也可以用标准 OAuth 2.0 / OIDC 客户端库实现该流程。 -初始化 Logto 客户端时，将资源指示器添加到 `resources` 参数（数组），然后将所需权限（scopes）添加到 `scopes` 参数。 +初始化 Logto 客户端时，将资源指示器添加到 `resources` 参数（数组），再将所需权限（scopes）添加到 `scopes` 参数。 -用户认证 (Authentication) 后，请在请求访问令牌时（如调用 `getAccessToken()`）传递资源指示器到 `resource` 参数或类似参数中。 +用户认证 (Authentication) 后，请在请求访问令牌 (Access token) 时（如调用 `getAccessToken()`）传入资源指示器到 `resource` 参数或类似参数。 各 SDK 详情见 [快速开始](/quick-starts)。 -配置 OAuth 2.0 客户端或初始化授权码流程时，确保在授权请求中包含 `resource` 参数和所需 scopes。 +配置 OAuth 2.0 客户端或初始化授权 (Authorization) 码流程时，确保在授权 (Authorization) 请求中包含 `resource` 参数和所需 scopes。 -部分库可能不原生支持 `resource` 参数，但通常允许你在授权请求中传递额外参数。具体请查阅你的库文档。 +部分库可能不原生支持 `resource` 参数，但通常允许你在授权 (Authorization) 请求中传递额外参数。请查阅你的库文档。 -以下是带 `resource` 和 `scope` 参数的授权请求非规范示例： +以下是带 `resource` 和 `scope` 参数的授权 (Authorization) 请求非规范示例： -用户认证 (Authentication) 后，你将收到授权码。通过向 Logto 的 `/oidc/token` 端点发起 POST 请求，并在请求体中包含 `resource` 参数，将该授权码兑换为访问令牌。 +用户认证 (Authentication) 后，你将收到授权 (Authorization) 码。通过向 Logto 的 `/oidc/token` 端点发起 POST 请求，并在请求体中包含 `resource` 参数，将该码兑换为访问令牌 (Access token)。 -以下是使用授权码模式的令牌请求非规范示例： +以下是使用授权 (Authorization) 码模式的令牌请求非规范示例： -你也可以使用 `refresh_token` 模式，在请求中包含 `resource` 参数，无需用户交互即可获取新访问令牌。 +你也可以使用 `refresh_token` 模式，在包含 `resource` 参数的情况下，无需用户交互获取新访问令牌 (Access token)。 -以下是使用刷新令牌模式的令牌请求非规范示例： +以下是使用刷新令牌 (Refresh token) 模式的令牌请求非规范示例： -#### 客户端凭证流程 \{#client-credentials-flow} +#### 客户端凭据流程 \{#client-credentials-flow} -对于机器对机器 (M2M) 场景，你可以使用客户端凭证流程获取全局 API 资源的访问令牌。通过向 Logto 的 `/oidc/token` 端点发起 POST 请求，使用你的客户端 ID 和密钥请求访问令牌。 +对于机器对机器 (M2M) 场景，你可以使用客户端凭据流程获取全局 API 资源的访问令牌 (Access token)。通过向 Logto 的 `/oidc/token` 端点发起 POST 请求，使用你的客户端 ID 和密钥请求访问令牌 (Access token)。 请求中需包含两个关键参数： - `resource`：你要访问的 API 的资源指示器 URI（如 `https://api.yourapp.com`）。 - `scope`：你要请求的 API 权限（如 `read:products write:products`）。 -以下是使用客户端凭证模式的令牌请求非规范示例： +以下是使用客户端凭据模式的令牌请求非规范示例： -### 在你的 API 中验证 JWT 访问令牌 \{#validating-jwt-access-tokens-in-your-api} +### 在你的 API 中验证 JWT 访问令牌 (Access token) \{#validating-jwt-access-tokens-in-your-api} Logto 签发的 JWT 包含你的 API 可用于强制授权 (Authorization) 的声明 (Claims)。 -当你的 API 收到带有 Logto 签发的访问令牌的请求时，你应： +当你的 API 收到带有 Logto 签发访问令牌 (Access token) 的请求时，你应： - 验证令牌签名（使用 Logto 的 JWKs）。 - 确认令牌未过期（`exp` 声明 (Claim)）。 - 检查 `iss`（发行者 (Issuer)）是否与你的 Logto 端点一致。 -- 确保 `aud`（受众 (Audience)）与你注册的 API 资源标识符一致（如 `https://api.yourapp.com`）。 +- 确认 `aud`（受众 (Audience)）是否与你注册的 API 资源标识符一致（如 `https://api.yourapp.com`）。 - 拆分 `scope` 声明 (Claim)（以空格分隔），检查所需权限。 -分步和特定语言指南见 [如何验证访问令牌](/authorization/validate-access-tokens)。 +分步和各语言指南见 [如何验证访问令牌 (Access token)](/authorization/validate-access-tokens)。 -### 可选：处理用户权限变更 \{#optional-handle-user-permission-change} - -:::info -👷 功能开发中。🚧 -::: + ## 最佳实践与安全建议 \{#best-practices-and-security-tips} -- **权限应以业务为驱动**：使用能映射到实际操作的清晰名称。 -- **令牌过期时间应短**：如果令牌泄露可降低风险。 -- **限制授予的权限 (Scopes)**：只给令牌实际需要的权限。 -- **使用受众限制**：始终验证 `aud` 声明 (Claim)，防止滥用。 +- **权限应以业务为驱动：** 使用能映射到实际操作的清晰名称。 +- **令牌过期时间应短：** 如果令牌泄露可降低风险。 +- **限制授予的权限 (Scopes)：** 只给令牌实际需要的权限。 +- **使用受众 (Audience) 限制：** 始终验证 `aud` 声明 (Claim)，防止滥用。 ## 常见问题 \{#faqs}
-### 如果我的客户端不支持 resource 参数怎么办？\{what-if-my-client-doesn-t-support-the-resource-parameter} \{#what-if-my-client-doesn-t-support-the-resource-parameter} +### 如果我的客户端不支持 resource 参数怎么办？\{#what-if-my-client-doesn-t-support-the-resource-parameter} -在 Logto 控制台设置默认 API 资源。当令牌请求中未指定 resource 参数时，令牌将默认使用该受众 (Audience)。 +在 Logto 控制台设置默认 API 资源。当令牌请求未指定 resource 参数时，令牌将默认使用该受众 (Audience)。
-### 为什么我的 API 返回 401 未授权？\{why-do-i-get-401-unauthorized-from-my-api} \{#why-do-i-get-401-unauthorized-from-my-api} +### 为什么我的 API 返回 401 未授权 (Unauthorized)？\{#why-do-i-get-401-unauthorized-from-my-api} 请检查以下常见问题： -- **令牌签名**：确认你的后端从 Logto 获取了正确的 JWKs -- **令牌过期**：确保令牌未过期（`exp` 声明 (Claim)） -- **受众 (Audience)**：确认 `aud` 声明 (Claim) 与你注册的 API 资源指示器一致 -- **所需权限 (Scopes)**：确认令牌的 `scope` 声明 (Claim) 包含所需权限 +- **令牌签名：** 确认你的后端从 Logto 获取了正确的 JWKs +- **令牌过期：** 确保令牌未过期（`exp` 声明 (Claim)） +- **受众 (Audience)：** 确认 `aud` 声明 (Claim) 与你注册的 API 资源指示器一致 +- **所需权限 (Scopes)：** 验证令牌的 `scope` 声明 (Claim) 包含所需权限
-### 如何在没有完整客户端的情况下测试？\{how-do-i-test-without-a-full-client} \{#how-do-i-test-without-a-full-client} +### 如何在没有完整客户端的情况下测试？\{#how-do-i-test-without-a-full-client} @@ -248,11 +245,11 @@ Logto 签发的 JWT 包含你的 API 可用于强制授权 (Authorization) 的
-### 请求权限时可以使用 scope 前缀或简写吗？\{can-i-use-scope-prefixes-or-shortened-versions} \{#can-i-use-scope-prefixes-or-shortened-versions} +### 请求权限时可以用 scope 前缀或缩写吗？\{#can-i-use-scope-prefixes-or-shortened-versions} -不可以。Scope 名称必须**完全匹配**你在 API 资源中定义的权限名称。前缀和简写不能作为通配符使用。 +不可以。scope 名称必须**完全匹配**你在 API 资源中定义的权限名称。前缀和缩写不能作为通配符使用。 **示例：** @@ -277,9 +274,9 @@ scopes: ["read", "write"] // ❌ 不匹配权限名称 ## 延伸阅读 \{#further-reading} -如何验证访问令牌 +如何验证访问令牌 (Access token) RBAC 实践：为你的应用实现安全授权 (Authorization) 自定义令牌声明 (Claims) -RFC 8707: 资源指示器 +RFC 8707：资源指示器 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 44dfc61d78a..0142ead89a6 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -18,9 +19,9 @@ export const resource = 'https://api.your-app.com/organizations'; 结合 API 资源与组织模板，可以限制每个组织内的 API 和数据访问，确保你的 SaaS 实现租户级隔离。 -## 什么是组织级 API 资源？ \{#what-are-organization-level-api-resources} +## 什么是组织级 API 资源？\{#what-are-organization-level-api-resources} -组织级 API 资源是你应用中**限定于特定组织**的端点或服务。这些 API 会根据组织上下文强制执行授权 (Authorization) 和访问控制，确保用户或客户端只能访问与其组织相关的数据和操作。 +组织级 API 资源是你应用中**限定于特定组织范围**的端点或服务。这些 API 会根据组织上下文强制执行授权 (Authorization) 和访问控制，确保用户或客户端只能访问与其组织相关的数据和操作。 **使用场景包括** @@ -33,32 +34,32 @@ Logto 允许你使用 OAuth 2.1 和基于角色的访问控制 (RBAC) 保护这 这些权限通过在 [组织模板](/authorization/organization-template) 中定义的**组织角色**进行管理。每个组织都使用相同的模板，确保所有组织拥有一致的权限模型。 -## 在 Logto 中的工作原理 \{#how-it-works-in-logto} +## Logto 中的工作原理 \{#how-it-works-in-logto} -- **API 资源和权限全局注册：** 每个 API 资源在 Logto 中都用唯一的资源指示器（URI）和一组权限（scopes）进行定义。 -- **组织级角色：** 组织角色在组织模板中定义。API 资源权限（scopes）分配给组织角色，然后再分配给每个组织内的用户或客户端。 -- **上下文感知授权 (Authorization)：** 当客户端请求带有 API 资源和 `organization_id` 的访问令牌时，Logto 会签发包含组织上下文和 API 受众的令牌。令牌的权限（scopes）由用户在指定组织中的组织角色决定。 +- **API 资源和权限全局注册：** 每个 API 资源在 Logto 中都用唯一的资源指示器（URI）和一组权限（Scopes）定义。 +- **组织级角色：** 组织角色在组织模板中定义。API 资源权限（Scopes）分配给组织角色，然后再分配给每个组织内的用户或客户端。 +- **上下文感知授权 (Authorization)：** 当客户端请求同时包含 API 资源和 `organization_id` 的访问令牌时，Logto 会签发包含组织上下文和 API 受众的令牌。令牌的权限（Scopes）由用户在指定组织中的组织角色决定。 - **与全局资源分离：** API 资源可以带或不带组织上下文访问。只有在请求中包含 `organization_id` 时，才会应用组织 RBAC。对于所有用户共享的 API，请参见 [保护全局 API 资源](/authorization/global-api-resources)。 组织级 API 资源 RBAC ### 实现概览 \{#implementation-overview} -1. **注册你的 API 资源**，并在 Logto 中定义其权限（scopes）。 +1. **注册你的 API 资源**，并在 Logto 中定义其权限（Scopes）。 2. **在组织模板中定义组织角色**，并分配相关 API 权限。 -3. **在每个组织内为用户或客户端分配角色。** -4. **为 API 请求访问令牌**，并带上 `organization_id`，以包含组织上下文。 -5. **在你的 API 中验证访问令牌**，同时校验组织上下文和权限。 +3. **为每个组织内的用户或客户端分配角色。** +4. **为 API 请求访问令牌时带上 `organization_id`，以包含组织上下文。** +5. **在你的 API 中验证访问令牌，强制执行组织上下文和权限。** ### Logto 如何应用组织 RBAC \{#how-logto-applies-organization-rbac} - 如果你请求访问令牌**不带** `organization_id`，只会考虑全局角色 / 权限。 - 如果你请求访问令牌**带有** `organization_id`，Logto 会评估用户在该组织中的组织角色及其关联权限。 -- 最终生成的 JWT 会同时包含 API 受众（`aud` 声明）和组织上下文（`organization_id` 声明），scopes 会被过滤为用户组织角色授予的权限。 +- 最终生成的 JWT 会同时包含 API 受众（`aud` 声明）和组织上下文（`organization_id` 声明），Scopes 会过滤为用户在该组织角色授予的权限。 ### 授权 (Authorization) 流程：带组织上下文的 API 认证 (Authentication) 与保护 \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} -下图展示了客户端（Web、移动端或后端）如何获取并使用组织令牌 (Organization token) 访问组织级 API 资源。 +下方流程展示了客户端（Web、移动端或后端）如何获取并使用组织令牌 (Organization token) 访问组织级 API 资源。 请注意，该流程未包含所有必需参数或请求头的细节，重点展示关键步骤。继续阅读可了解实际流程。 @@ -70,7 +71,7 @@ sequenceDiagram alt 用户认证 (Authentication) Client->>Logto: GET /oidc/auth - Logto->>Logto: 重定向用户到登录页面 + Logto->>Logto: 重定向用户到登录页 Logto->>Client: 登录后重定向并返回 `authorization_code` Client->>Logto: POST /oidc/token，带 `grant_type=authorization_code` Logto->>Client: 返回刷新令牌 (Refresh token) @@ -81,7 +82,7 @@ sequenceDiagram Logto->>Client: 返回访问令牌 (JWT) Client->>API: 使用 Bearer token 请求 - API->>API: 校验令牌，检查组织上下文和权限 + API->>API: 验证令牌，检查组织上下文和权限 alt 令牌有效 API->>Client: 返回组织数据 @@ -90,43 +91,43 @@ sequenceDiagram end ``` -_用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭证 + 组织上下文的后端服务或脚本。_ +_用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭据 + 组织上下文的后端服务或脚本。_ ## 实现步骤 \{#implementation-steps} ### 注册你的 API 资源 \{#register-your-api-resource} 1. 前往 控制台 → API 资源。 -2. 创建新的 API 资源（如 `https://api.yourapp.com/org`），并定义其权限（scopes）。 +2. 创建新的 API 资源（如 `https://api.yourapp.com/org`），并定义其权限（Scopes）。 完整配置步骤见 [定义带权限的 API 资源](/authorization/role-based-access-control#define-api-resources-with-permissions)。 ### 配置组织角色 \{#set-up-organization-roles} 1. 前往 控制台 → 组织模板 → 组织角色。 -2. 创建组织角色（如 `admin`、`member`），并为每个角色分配 API 权限。 +2. 创建组织角色（如 `admin`、`member`），并为每个角色分配 API 权限 3. 在每个组织内为用户或客户端分配角色。如果他们还不是成员，先邀请或添加。 完整配置步骤见 [使用组织角色](/authorization/role-based-access-control#configure-organization-roles)。 -### 获取 API 资源的组织令牌 (Organization token) \{#obtain-organization-tokens-for-api-resources} +### 获取 API 资源的组织令牌 (Organization tokens) \{#obtain-organization-tokens-for-api-resources} -你的客户端 / 应用应同时带上 `resource` 和 `organization_id` 请求令牌，以访问组织级 API。Logto 会以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式签发组织令牌 (Organization token)。你可以通过 [刷新令牌流程](https://auth.wiki/refresh-token) 或 [客户端凭证流程](https://auth.wiki/client-credentials-flow) 获取。 +你的客户端 / 应用应同时带上 `resource` 和 `organization_id` 请求令牌，以访问组织级 API。Logto 会以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式签发组织令牌。你可以通过 [刷新令牌流程](https://auth.wiki/refresh-token) 或 [客户端凭据流程](https://auth.wiki/client-credentials-flow) 获取。 #### 刷新令牌流程 \{#refresh-token-flow} -几乎所有 Logto 官方 SDK 都原生支持通过刷新令牌流程获取组织令牌 (Organization token)。标准 OAuth 2.0 / OIDC 客户端库也可实现该流程。 +几乎所有 Logto 官方 SDK 都原生支持通过刷新令牌流程获取组织令牌。标准 OAuth 2.0 / OIDC 客户端库也可实现该流程。 -初始化 Logto SDK 时，将 `urn:logto:scope:organizations` 及所需组织权限（scopes）加入 `scopes` 参数。 +初始化 Logto SDK 时，将 `urn:logto:scope:organizations` 及所需组织权限（Scopes）加入 `scopes` 参数。 -部分 Logto SDK 已预定义组织 scope，如 JavaScript SDK 的 `UserScope.Organizations`。 +部分 Logto SDK 已预定义组织 Scope，如 JavaScript SDK 的 `UserScope.Organizations`。 -调用 `getAccessToken()` 时，需同时指定 API 资源（`resource`）和组织 ID（`organizationId`），以获取组织令牌 (Organization token)。 +调用 `getAccessToken()` 时，需同时指定 API 资源（`resource`）和组织 ID（`organizationId`），以获取组织令牌。 各 SDK 详情见 [快速开始](/quick-starts)。 @@ -136,9 +137,9 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 配置 OAuth 2.0 客户端或初始化授权码流程时，确保包含以下参数： - `resource`：设置为在 Logto 注册的 API 资源标识符（如 `https://api.your-app.com/organizations`）。 -- `scope`：包含预定义的组织 scope（`urn:logto:scope:organizations`）、`offline_access`（获取刷新令牌），以及你需要的具体 API 权限（如 `manage:members view:analytics`）。 +- `scope`：包含预定义的组织 Scope（`urn:logto:scope:organizations`）、`offline_access`（获取刷新令牌），以及你需要的具体 API 权限（如 `manage:members view:analytics`）。 -部分库可能不原生支持 `resource` 参数，但通常允许你在授权请求中传递额外参数。具体请查阅你的库文档。 +部分库可能不原生支持 `resource` 参数，但通常允许在授权请求中传递额外参数。请查阅你的库文档。 以下为授权请求的非规范示例： @@ -147,7 +148,7 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 scope="urn:logto:scope:organizations invite:member manage:billing" /> -用户认证 (Authentication) 后，你将收到授权码。使用该码向 Logto 的 `/oidc/token` 端点发起 POST 请求。 +用户认证 (Authentication) 后，你将收到授权码。使用该授权码向 Logto 的 `/oidc/token` 端点发起 POST 请求。 以下为令牌请求的非规范示例： @@ -155,11 +156,11 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 -你将获得一个刷新令牌 (Refresh token)，可用于获取组织令牌 (Organization token)。 +你将获得一个刷新令牌，可用于获取组织令牌。 -最后，使用刷新令牌 (Refresh token) 向 Logto 的 `/oidc/token` 端点发起 POST 请求以获取组织令牌 (Organization token)。记得包含： +最后，使用刷新令牌向 Logto 的 `/oidc/token` 端点发起 POST 请求以获取组织令牌。请务必包含： - `resource` 参数，设置为 API 资源标识符（如 `https://api.yourapp.com/org`）。 - `organization_id` 参数，设置为目标组织 ID。 @@ -176,9 +177,9 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 -#### 客户端凭证流程 \{#client-credentials-flow} +#### 客户端凭据流程 \{#client-credentials-flow} -对于机器对机器 (M2M) 场景，你可以使用客户端凭证流程获取组织级 API 资源权限的访问令牌。通过带组织参数向 Logto 的 `/oidc/token` 端点发起 POST 请求，可用客户端 ID 和密钥请求组织令牌 (Organization token)。 +对于机器对机器 (M2M) 场景，你可以使用客户端凭据流程获取组织级 API 资源权限的访问令牌。通过向 Logto 的 `/oidc/token` 端点发起带组织参数的 POST 请求，可使用客户端 ID 和密钥请求组织令牌。 请求中需包含的关键参数： @@ -186,7 +187,7 @@ _用户认证 (Authentication) = 浏览器 / 应用。M2M = 使用客户端凭 - `organization_id`：你希望获取令牌的组织 ID。 - `scope`：你要请求的组织级 API 资源权限（如 `invite:member`、`manage:billing`）。 -以下为使用客户端凭证授权类型的令牌请求非规范示例： +以下为使用客户端凭据授权类型的令牌请求非规范示例： -### 校验组织令牌 (Organization token) \{#validate-organization-tokens} +### 验证组织令牌 (Organization tokens) \{#validate-organization-tokens} -Logto 签发的组织令牌 (Organization token)（JWT）包含你的 API 可用于强制组织级访问控制的声明 (Claim)。 +Logto 签发的组织令牌（JWT）包含你的 API 可用于强制组织级访问控制的声明 (Claims)。 -当你的应用收到组织令牌 (Organization token) 时，你应： +你的应用收到组织令牌后，应： -- 校验令牌签名（使用 Logto 的 JWKs）。 +- 验证令牌签名（使用 Logto 的 JWKs）。 - 确认令牌未过期（`exp` 声明）。 -- 检查 `iss`（发行者）是否与你的 Logto 端点一致。 -- 确保 `aud`（受众）与你注册的 API 资源标识符一致（如 `https://api.yourapp.com/org`）。 +- 检查 `iss`（发行者）是否与你的 Logto 端点匹配。 +- 确认 `aud`（受众）是否与你注册的 API 资源标识符一致（如 `https://api.yourapp.com/org`）。 - 校验 `organization_id` 声明，确保令牌限定于正确的组织。 - 拆分 `scope` 声明（以空格分隔），检查所需权限。 - 如果你的 API 路径包含组织 ID（如 `/organizations/{organizationId}/members`），确保 `organization_id` 声明与路径参数一致。 -分步和特定语言指南见 [如何校验访问令牌](/authorization/validate-access-tokens)。 +分步和多语言指南见 [如何验证访问令牌](/authorization/validate-access-tokens)。 + + ## 最佳实践与安全建议 \{#best-practices-and-security-tips} -- **始终校验组织上下文：** 不要只信任令牌，每次组织范围 API 调用都要检查 `organization_id` 声明。 +- **始终校验组织上下文：** 不要只信任令牌本身，每次组织范围 API 调用都要检查 `organization_id` 声明。 - **使用受众限制：** 始终检查 `aud` 声明，确保令牌用于目标组织。 - **权限保持业务驱动：** 使用清晰的名称映射实际操作，每个组织角色只授予所需权限。 -- **尽量区分 API 权限和非 API 权限**（但两者可在同一角色中）。 -- **保持令牌生命周期短：** 如果令牌泄露，可降低风险。 +- **尽量区分 API 与非 API 权限**（但两者可在同一角色中）。 +- **保持令牌生命周期短：** 若令牌泄露可降低风险。 - **定期审查你的组织模板：** 随产品演进更新角色和权限。 ## 常见问题 \{#faqs} @@ -224,7 +227,7 @@ Logto 签发的组织令牌 (Organization token)（JWT）包含你的 API 可用
-### 如果我在令牌请求中不包含 `organization_id` 会怎样？ \{#what-if-i-don-t-include-organization-id-in-my-token-request} +### 如果我在令牌请求中不包含 `organization_id` 会怎样？\{what-if-i-don-t-include-organization-id-in-my-token-request} \{#what-if-i-don-t-include-organization-id-in-my-token-request} @@ -235,7 +238,7 @@ Logto 签发的组织令牌 (Organization token)（JWT）包含你的 API 可用
-### 我可以在一个角色中混合组织和非组织权限吗？ \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} +### 我可以在一个角色中混合组织和非组织权限吗？\{can-i-mix-organization-and-non-organization-permissions-in-a-single-role} \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} @@ -245,11 +248,11 @@ Logto 签发的组织令牌 (Organization token)（JWT）包含你的 API 可用 ## 延伸阅读 \{#further-reading} -如何校验访问令牌 +如何验证访问令牌 (Access token) 自定义令牌声明 (Claim) - 使用场景：构建多租户 SaaS 应用 + 用例：构建多租户 SaaS 应用 - RFC 8707：资源指示器 (Resource Indicators) + RFC 8707：资源指示器 (Resource indicator) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 17fca37e6a4..071f07fefb4 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,11 +15,11 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # 保护组织（非 API）权限 -使用组织模板在 Logto 中管理和强制执行组织级别的角色和权限，控制在组织上下文内对应用内功能和工作流的访问。 +使用组织模板在 Logto 中管理和强制执行组织级别的角色和权限，控制用户在组织上下文内对应用内功能和工作流的访问。 ## 什么是组织（非 API）权限？ \{#what-are-organization-non-api-permissions} -组织权限（非 API）控制用户在**组织上下文内**可以做什么，但**不会在 API 层面强制执行**。它们用于管理对应用功能、UI 元素、工作流或业务操作的访问，而不是后端 API。 +组织权限（非 API）控制用户在**组织上下文内**可以做什么，但**不会在 API 层面强制执行**。它们主要用于管理对应用功能、UI 元素、工作流或业务操作的访问，而不是后端 API。 **使用场景包括** @@ -35,7 +36,7 @@ Logto 允许你使用 OAuth 2.1 和基于角色的访问控制 (RBAC) 保护这 - **组织级别 RBAC**：角色和权限在组织模板中定义。当用户加入组织时，会被分配一个或多个角色，从而获得特定权限。 - **非 API 强制执行**：权限在你的应用 UI、工作流或后端逻辑中检查和强制执行，不一定由 API 网关处理。 -- **与 API 保护分离**：组织（非 API）权限与 API 资源权限不同。你可以将两者结合用于高级场景。 +- **与 API 保护分离**：组织（非 API）权限与 API 资源权限是分开的。你可以结合两者用于高级场景。
组织权限 RBAC @@ -45,19 +46,19 @@ Logto 允许你使用 OAuth 2.1 和基于角色的访问控制 (RBAC) 保护这 1. 在 Logto 的组织模板下**定义组织权限**。 2. **创建组织角色**，将所需权限打包用于组织特定操作。 -3. **为每个组织内的用户或客户端分配角色**。 -4. 使用刷新令牌 (Refresh token) 或客户端凭据流获取当前组织的**组织令牌 (JWT)**。 -5. 在应用 UI 或后端**验证访问令牌**以强制执行组织权限。 +3. 在每个组织内**为用户或客户端分配角色**。 +4. 通过刷新令牌 (Refresh token) 或客户端凭据流获取当前组织的**组织令牌 (JWT)**。 +5. 在应用 UI 或后端**验证访问令牌**，以强制执行组织权限。 ### 授权 (Authorization) 流程：认证 (Authentication) 并保护组织权限 \{#authorization-flow-authenticating-and-securing-organization-permissions} -以下流程展示了客户端（Web、移动端或后端）如何获取并使用组织令牌来实现非 API 权限的强制执行。 +以下流程展示了客户端（Web、移动端或后端）如何获取并使用组织令牌来强制执行非 API 权限。 请注意，该流程未包含所有必需参数或请求头的详细信息，重点展示关键步骤。继续阅读以了解实际流程。 ```mermaid sequenceDiagram - participant Client + participant Client as 客户端 participant Logto participant App as 应用/UI/后端 @@ -73,7 +74,7 @@ sequenceDiagram end Logto->>Client: 返回组织令牌 (JWT) - Client->>App: 携带 Bearer token 请求 + Client->>App: 携带 Bearer 令牌请求 App->>App: 验证组织令牌，检查组织上下文和权限 alt 令牌有效 @@ -98,22 +99,22 @@ _用户认证 (Authentication) = 浏览器/应用。M2M = 使用客户端凭据 1. 前往 控制台 → 组织模板 → 组织角色。 2. 创建包含你之前定义的组织权限的角色（如 `admin`、`member`、`billing`）。 -3. 将这些角色分配给每个组织内的用户或客户端。 +3. 在每个组织内为用户或客户端分配这些角色。 完整配置步骤见 [使用组织角色](/authorization/role-based-access-control#configure-organization-roles)。 ### 获取组织令牌（非 API） \{#obtain-organization-tokens-non-api} -你的客户端/应用应获取组织令牌（非 API）以访问组织权限。Logto 以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式颁发组织令牌。你可以通过 [刷新令牌流](https://auth.wiki/refresh-token) 或 [客户端凭据流](https://auth.wiki/client-credentials-flow) 获取。 +你的客户端/应用应获取组织令牌（非 API）以访问组织权限。Logto 以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式签发组织令牌。你可以通过 [刷新令牌流程](https://auth.wiki/refresh-token) 或 [客户端凭据流程](https://auth.wiki/client-credentials-flow) 获取。 -#### 刷新令牌流 \{#refresh-token-flow} +#### 刷新令牌流程 \{#refresh-token-flow} -几乎所有 Logto 官方 SDK 都原生支持通过刷新令牌流获取组织令牌。标准 OAuth 2.0 / OIDC 客户端库也可实现该流程。 +几乎所有 Logto 官方 SDK 都原生支持通过刷新令牌流程获取组织令牌。标准 OAuth 2.0 / OIDC 客户端库也可实现该流程。 -初始化 Logto SDK 时，将 `urn:logto:scope:organizations` 及所需组织权限（scopes）添加到 `scopes` 参数中。 +初始化 Logto SDK 时，在 `scopes` 参数中添加 `urn:logto:scope:organizations` 以及所需的组织权限（scopes）。 部分 Logto SDK 预定义了组织相关 scope，如 JavaScript SDK 中的 `UserScope.Organizations`。 @@ -121,19 +122,19 @@ _用户认证 (Authentication) = 浏览器/应用。M2M = 使用客户端凭据 使用 `getOrganizationToken` 或类似方法（如带组织 ID 的 `getAccessToken`）为指定组织请求组织令牌。 -各 SDK 详情见 [快速开始](/quick-starts)。 +各 SDK 详情见 [快速上手](/quick-starts)。 - + 配置 OAuth 2.0 客户端或初始化授权码流程时，确保包含以下参数： - `resource`：设置为 `urn:logto:resource:organizations`，表示你需要组织令牌。 -- `scope`：包含预定义的组织 scope（`urn:logto:scope:organizations`）、`offline_access`（获取刷新令牌）及你需要的具体组织权限（如 `invite:member`、`manage:billing`）。 +- `scope`：包含预定义的组织 scope（`urn:logto:scope:organizations`）、`offline_access`（获取刷新令牌），以及你需要的具体组织权限（如 `invite:member`、`manage:billing`）。 部分库可能不原生支持 `resource` 参数，但通常允许你在授权请求中传递额外参数。请查阅你的库文档。 -以下为授权请求的非规范示例： +以下是授权请求的非规范示例： -你将获得一个刷新令牌 (Refresh token)，可用于获取组织令牌。 +你将获得一个刷新令牌，可用于获取组织令牌。 -最后，使用刷新令牌 (Refresh token) 向 Logto 的 `/oidc/token` 端点发起 POST 请求以获取组织令牌。记得包含： +最后，使用刷新令牌向 Logto 的 `/oidc/token` 端点发起 POST 请求以获取组织令牌。记得包含： - `organization_id` 参数，设置为目标组织 ID。 - （可选）`scope` 参数，进一步缩小所需权限范围（如 `manage:members view:reports`）。 -以下为令牌请求的非规范示例： +以下是令牌请求的非规范示例： -#### 客户端凭据流 \{#client-credentials-flow} +#### 客户端凭据流程 \{#client-credentials-flow} -对于机器对机器 (M2M) 场景，你可以使用客户端凭据流获取组织权限的访问令牌。通过向 Logto 的 `/oidc/token` 端点发起带有组织参数的 POST 请求，可使用客户端 ID 和密钥请求组织令牌。 +对于机器对机器 (M2M) 场景，你可以使用客户端凭据流程获取组织权限的访问令牌。通过携带组织参数向 Logto 的 `/oidc/token` 端点发起 POST 请求，使用你的客户端 ID 和密钥请求组织令牌。 请求中需包含的关键参数： - `organization_id`：你想获取令牌的组织 ID。 - `scope`：你想请求的组织权限（如 `invite:member`、`manage:billing`）。 -以下为使用客户端凭据授权类型的令牌请求非规范示例： +以下是使用客户端凭据授权类型的令牌请求非规范示例： + ## 最佳实践与安全提示 \{#best-practices-and-security-tips} -- **切勿仅依赖 UI 强制执行**：关键操作务必在后端验证权限。 -- **使用受众 (Audience) 限制**：始终检查 `aud` 声明，确保令牌用于目标组织。 -- **保持权限业务驱动**：使用清晰的名称映射到实际操作；仅为每个组织角色授予所需权限。 +- **切勿仅依赖 UI 层强制执行**：关键操作务必在后端验证权限。 +- **使用受众 (Audience) 限制**：始终检查 `aud` 声明，确保令牌属于目标组织。 +- **保持权限业务驱动**：使用清晰的名称映射实际操作；每个组织角色只授予所需权限。 - **尽量区分 API 与非 API 权限**（但两者可在同一角色中）。 -- **定期审查组织模板**，以适应产品演进。 +- **定期审查组织模板**，随产品发展不断优化。 ## 常见问题 \{#faqs} @@ -222,7 +225,7 @@ Logto 颁发的组织令牌 (JWT) 包含你的应用/UI/后端可用于强制执 -在 UI（用于功能开关）和服务器端逻辑（用于敏感操作）都要检查非 API 权限。 +在 UI 层（用于功能开关）和服务端逻辑（针对敏感操作）都要检查非 API 权限。
@@ -231,5 +234,5 @@ Logto 颁发的组织令牌 (JWT) 包含你的应用/UI/后端可用于强制执 如何验证访问令牌 自定义令牌声明 (Claims) - 使用场景：构建多租户 SaaS 应用 + 用例：构建多租户 SaaS 应用 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx new file mode 100644 index 00000000000..b62d2338afa --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/fragments/_handle-user-permission-change.mdx @@ -0,0 +1,31 @@ +### 選用：處理使用者權限變更 \{#optional-handle-user-permission-change} + +使用者權限隨時可能變動。由於 Logto 會針對角色型存取控制 (RBAC, Role-based Access Control) 發行 JWT，權限更新只會反映在新發行的權杖中，現有的 JWT 不會被修改。 + +:::info 權限範圍子集規則 (Scope subset rule) +存取權杖 (Access token) 僅能包含原始 OAuth 授權流程中請求的權限範圍 (Scopes)。 +即使使用者獲得新權限，後續發行的權杖也只能包含原本請求範圍的子集。 +若要存取初始請求未涵蓋的新權限範圍，客戶端必須重新執行授權流程。 +::: + +#### 權限縮減 (Downscoped permissions) \{#downscoped-permissions} + +當使用者失去權限時： + +- 新發行的權杖會立即反映縮減後的權限範圍 (Scopes)。 +- 現有的 JWT 會保留舊的權限範圍，直到過期為止。 +- 你的 API 應始終驗證權限範圍，並依賴短效權杖有效期。 + +若你需要更快的反應，可自行實作通知機制，提示客戶端刷新權杖。 + +#### 權限擴增 (Enlarged permissions) \{#enlarged-permissions} + +{props.type === "global" &&

針對全域 API 資源 (Global API resources)，當使用者獲得新權限時，擴增的權限不會透過刷新顯示。客戶端必須重新執行 OAuth 授權流程，才能取得包含新權限範圍的權杖。如果使用者已有 Logto 活躍工作階段，此流程可靜默進行。

} + +{props.type === "organization" &&

針對組織權杖 (Organization tokens)，當使用者獲得新權限時，擴增的權限會在下次發行（刷新或權杖請求）時顯示。仍需取得新權杖，但除非新權限範圍超出原始請求集，否則不需完整重新驗證。

} + +#### 建議事項 \{#recommendations} + +- 每次 API 呼叫都要驗證權限範圍 (Scopes)。 +- 保持權杖有效期短。 +- 若需即時權限變更傳遞，可加上選用通知機制。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx index 8fbe2d3f081..2c1b2775578 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/global-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-global-api-resour import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -17,39 +18,39 @@ export const resource = 'https://api.your-app.com'; ## 什麼是全域 API 資源 (API resources)？\{#what-are-global-api-resources} -全域 API 資源 (API resources) 是指在你的應用程式中，所有使用者皆可存取的端點或服務，不論其所屬組織或租戶。這些通常是對外公開的 API、核心產品服務，或任何未限定於特定組織的端點。 +全域 API 資源 (API resources) 是指你應用程式中所有使用者皆可存取的端點或服務，無論其所屬組織或租戶。這些通常是對外公開的 API、核心產品服務，或未限定於特定組織的端點。 -**常見應用情境包含** +**常見情境包含** -- 供所有使用者共用的公開 API 或端點。 +- 供所有使用者共享的公開 API 或端點。 - 不屬於多租戶架構的微服務。 - 所有客戶都會用到的核心應用程式 API（如 `/api/users`、`/api/products`）。 Logto 允許你結合 OAuth 2.1 與彈性的角色型存取控制來保護這些 API。 -## Logto 中的運作方式 \{#how-it-works-in-logto} +## 在 Logto 中的運作方式 \{#how-it-works-in-logto} - **API 資源 (API resources) 與權限 (Permissions) 全域註冊：** 你想保護的每個 API 都需以唯一的資源標示符 (Resource indicator, URI) 註冊，並設定一組控制存取的權限範圍 (Scopes)。 - **存取權由全域角色 (Roles) 控制：** 你可以將權限指派給角色，再將角色指派給使用者或用戶端。 -- **與組織層級權限分離：** 全域 API 資源 (API resources) 不具組織上下文。但如有需要，也可與組織角色 (Roles) 搭配，提供額外的上下文層。若要保護組織層級 API，請參閱 [保護組織層級 API 資源 (API resources)](/authorization/organization-level-api-resources)。 +- **與組織層級權限分離：** 全域 API 資源 (API resources) 不具組織脈絡。但如有需要，也可與組織角色 (Roles) 搭配，提供額外脈絡。若需保護組織層級 API，請參閱 [保護組織層級 API 資源 (API resources)](/authorization/organization-level-api-resources)。 全域 API 資源 RBAC -### 實作流程總覽 \{#implementation-overview} +### 實作概覽 \{#implementation-overview} 1. **註冊你的 API 資源 (API resource)** 並在 Logto 中定義其權限。 2. **定義角色 (Roles)**，並賦予存取 API 所需的權限。 3. **指派角色 (Roles)** 給使用者或用戶端。 4. **使用 OAuth 2.0 授權流程** 取得 API 的存取權杖 (Access token)（resource 參數必須與註冊的 API 標識符一致）。 -5. **在 API 端驗證存取權杖 (Access token)**，以強制執行權限控管。 +5. **在你的 API 驗證存取權杖 (Access token)**，以強制執行權限。 ### 認識資源標示符 (Resource indicators) \{#understanding-resource-indicators} -Logto 依據 [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html) 建模 API 資源 (API resources)。**資源標示符 (Resource indicator)** 是唯一識別目標 API 或服務的 URI。 +Logto 依據 [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-editor.org/rfc/rfc8707.html) 建模 API 資源 (API resources)。**資源標示符 (Resource indicator)** 是唯一標識目標 API 或服務的 URI。 **重點說明** -- 資源標示符必須為絕對 URI（如 `https://api.example.com`） +- 資源標示符必須是絕對 URI（如 `https://api.example.com`） - 不可包含 fragment 元件；盡量避免使用查詢字串。 - 資源標示符可實現受眾限制權杖 (Audience-restricted tokens) 與多 API 架構支援。 @@ -60,14 +61,14 @@ Logto 依據 [RFC 8707: Resource Indicators for OAuth 2.0](https://www.rfc-edito ### 授權流程：驗證 (Authentication) 並保護你的 API \{#authorization-flow-authenticating-and-securing-your-api} -下方流程適用於互動式使用者驗證（瀏覽器 / 應用程式）與後端機器對機器 (M2M) 情境。 +下列流程適用於互動式使用者驗證（瀏覽器 / 應用程式）與後端機器對機器 (M2M) 情境。 -請注意，流程未詳列所有必要參數或標頭，僅聚焦於主要步驟。繼續閱讀可瞭解實際運作方式。 +請注意，流程未詳列所有必要參數或標頭，僅聚焦於主要步驟。繼續閱讀可了解實際運作方式。 ```mermaid sequenceDiagram participant Client as 用戶端 (Client) - participant Logto + participant Logto as Logto participant API as API 資源 (API resource) alt 使用者驗證 (User authentication) @@ -106,14 +107,14 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用 client credentials ### 註冊你的 API 資源 (API resources) \{#register-your-api-resources} -1. 前往 主控台 → API 資源 (API resources)。 -2. 建立新的 API 資源（如 `https://api.yourapp.com/org`），並定義其權限（Scopes）。 +1. 前往 Console → API 資源 (API resources)。 +2. 建立新的 API 資源（如 `https://api.yourapp.com/org`），並定義其權限範圍 (Scopes)。 -完整設定步驟請參閱 [定義具權限的 API 資源 (API resources)](/authorization/role-based-access-control#define-api-resources-with-permissions)。 +完整設定步驟請參閱 [定義帶權限的 API 資源 (API resources)](/authorization/role-based-access-control#define-api-resources-with-permissions)。 ### 設定全域角色 (Roles) \{#set-up-global-roles} -1. 前往 主控台 → 角色 (Roles)。 +1. 前往 Console → 角色 (Roles)。 2. 建立對應 API 權限的角色（如 `read:products`、`write:products`）。 3. 將這些角色指派給需要存取 API 的使用者或用戶端。 @@ -121,39 +122,39 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用 client credentials ### 取得全域 API 資源 (API resources) 的存取權杖 (Access tokens) \{#obtain-access-tokens-for-global-api-resources} -在存取全域 API 資源 (API resources) 前，你的用戶端必須先取得存取權杖 (Access token)。Logto 會針對全域 API 資源 (API resources) 發行 [JSON Web Token (JWT)](https://auth.wiki/jwt) 作為存取權杖。這通常透過 [OAuth 2.0 授權碼流程 (authorization code flow)](https://auth.wiki/authorization-code-flow)、[重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [client credentials 流程](https://auth.wiki/client-credentials-flow) 完成。 +在存取全域 API 資源 (API resources) 前，你的用戶端必須先取得存取權杖 (Access token)。Logto 會針對全域 API 資源 (API resources) 發行 [JSON Web Token (JWT)](https://auth.wiki/jwt) 作為存取權杖。這通常透過 [OAuth 2.0 授權碼流程 (authorization code flow)](https://auth.wiki/authorization-code-flow)、[重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [client credentials flow](https://auth.wiki/client-credentials-flow) 完成。 #### 授權碼或重新整理權杖流程 \{#authorization-code-or-refresh-token-flow} -所有 Logto 官方 SDK 均原生支援使用重新整理權杖流程取得全域 API 資源 (API resources) 的存取權杖 (Access token)。你也可以使用標準 OAuth 2.0 / OIDC 用戶端函式庫實作此流程。 +所有 Logto 官方 SDK 均原生支援使用重新整理權杖流程取得全域 API 資源 (API resources) 的存取權杖 (Access tokens)。你也可以使用標準 OAuth 2.0 / OIDC 用戶端函式庫實作此流程。 -初始化 Logto 用戶端時，將資源標示符 (Resource indicator) 加入 `resources` 參數（陣列），再將所需權限（Scopes）加入 `scopes` 參數。 +初始化 Logto client 時，將資源標示符 (Resource indicator) 加入 `resources` 參數（陣列），再將所需權限 (Scopes) 加入 `scopes` 參數。 使用者驗證後，請在請求存取權杖 (Access token) 時，於 `resource` 參數或同名參數傳入資源標示符（如呼叫 `getAccessToken()`）。 -各 SDK 詳細用法請參閱 [快速入門](/quick-starts)。 +各 SDK 詳細用法請參閱 [快速入門 (Quick starts)](/quick-starts)。 -設定 OAuth 2.0 用戶端或初始化授權碼流程時，請確保在授權請求中包含 `resource` 參數與所需 scopes。 +設定 OAuth 2.0 用戶端或初始化授權碼流程時，請務必在授權請求中包含 `resource` 參數與所需權限 (Scopes)。 -部分函式庫可能未原生支援 `resource` 參數，但通常允許你在授權請求中傳遞額外參數。請查閱你的函式庫文件。 +部分函式庫可能不原生支援 `resource` 參數，但通常允許你在授權請求中傳遞額外參數。請查閱你的函式庫文件。 以下為帶有 `resource` 與 `scope` 參數的授權請求非正式範例： -使用者驗證後，你會取得授權碼。將此授權碼透過 POST 請求傳送至 Logto 的 `/oidc/token` 端點，並在請求主體中包含 `resource` 參數，以換取存取權杖 (Access token)。 +使用者驗證後，你會取得授權碼。將此授權碼透過 POST 請求傳送至 Logto `/oidc/token` 端點，並於請求主體中包含 `resource` 參數，以換取存取權杖 (Access token)。 以下為使用授權碼 grant type 的權杖請求非正式範例： -你也可以使用 `refresh_token` grant type，在請求中包含 `resource` 參數，即可於無需使用者互動下取得新存取權杖 (Access token)。 +你也可以使用 `refresh_token` grant type，在請求中包含 `resource` 參數，即可無需使用者互動取得新存取權杖。 以下為使用重新整理權杖 grant type 的權杖請求非正式範例： @@ -162,9 +163,9 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用 client credentials -#### Client credentials 流程 \{#client-credentials-flow} +#### Client credentials flow \{#client-credentials-flow} -針對機器對機器 (M2M) 情境，你可以使用 client credentials 流程取得全域 API 資源 (API resources) 的存取權杖 (Access token)。只需對 Logto 的 `/oidc/token` 端點發送 POST 請求，並使用你的 client ID 與 secret。 +針對機器對機器 (M2M) 情境，你可以使用 client credentials flow 取得全域 API 資源 (API resources) 的存取權杖 (Access token)。只需向 Logto `/oidc/token` 端點發送 POST 請求，並使用你的 client ID 與 secret。 請在請求中包含兩個關鍵參數： @@ -178,81 +179,77 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用 client credentials scope="read:products write:products" /> -### 在 API 端驗證 JWT 存取權杖 (Access tokens) \{#validating-jwt-access-tokens-in-your-api} +### 在你的 API 驗證 JWT 存取權杖 (Access tokens) \{#validating-jwt-access-tokens-in-your-api} Logto 發行的 JWT 內含宣告 (Claims)，你的 API 可據此執行授權 (Authorization)。 -當 API 收到帶有 Logto 發行的存取權杖 (Access token) 的請求時，應： +當你的 API 收到帶有 Logto 發行存取權杖 (Access token) 的請求時，應： - 驗證權杖簽章（使用 Logto 的 JWKs）。 - 確認權杖未過期（`exp` 宣告）。 - 檢查 `iss`（簽發者）是否與你的 Logto 端點一致。 -- 確認 `aud`（受眾）是否與你註冊的 API 資源標示符一致（如 `https://api.yourapp.com`）。 +- 確認 `aud`（受眾）是否與你註冊的 API 資源標識符一致（如 `https://api.yourapp.com`）。 - 拆解 `scope` 宣告（以空格分隔），檢查是否具備所需權限。 各語言詳細教學請參閱 [如何驗證存取權杖 (Access tokens)](/authorization/validate-access-tokens)。 -### 選用：處理使用者權限變更 \{#optional-handle-user-permission-change} - -:::info -👷 功能開發中。🚧 -::: + ## 最佳實踐與安全建議 \{#best-practices-and-security-tips} -- **權限設計以業務為導向：** 使用能對應實際操作的清楚名稱。 +- **權限設計以業務為導向：** 使用能對應實際動作的清楚名稱。 - **縮短權杖有效期：** 若權杖外洩可降低風險。 -- **限制授予的權限範圍 (Scopes)：** 權杖僅給予實際所需權限。 -- **使用受眾限制 (Audience restriction)：** 務必驗證 `aud` 宣告，避免權杖被濫用。 +- **限制授予的權限範圍 (Scopes)：** 僅給予權杖實際所需權限。 +- **使用受眾限制 (Audience restriction)：** 一定要驗證 `aud` 宣告，避免權杖被濫用。 ## 常見問題 \{#faqs}
-### 如果我的用戶端不支援 resource 參數怎麼辦？\{what-if-my-client-doesn-t-support-the-resource-parameter} \{#what-if-my-client-doesn-t-support-the-resource-parameter} +### 如果我的用戶端不支援 resource 參數怎麼辦？\{#what-if-my-client-doesn-t-support-the-resource-parameter} -請在 Logto 主控台設定預設 API 資源。當權杖請求未指定 resource 參數時，將預設使用此受眾。 +請在 Logto Console 設定預設 API 資源。當權杖請求未指定 resource 參數時，權杖將預設發給此受眾 (Audience)。
-### 為什麼我的 API 回傳 401 Unauthorized？\{why-do-i-get-401-unauthorized-from-my-api} \{#why-do-i-get-401-unauthorized-from-my-api} +### 為什麼我的 API 回傳 401 Unauthorized？\{#why-do-i-get-401-unauthorized-from-my-api} 請檢查以下常見問題： -- **權杖簽章：** 確認你的後端有正確取得 Logto 的 JWKs -- **權杖過期：** 確認權杖未過期（`exp` 宣告） -- **受眾 (Audience)：** 確認 `aud` 宣告與你註冊的 API 資源標示符一致 -- **所需權限範圍 (Scopes)：** 確認權杖內含必要權限（`scope` 宣告） +- **權杖簽章**：確認你的後端有正確取得 Logto 的 JWKs +- **權杖過期**：確保權杖尚未過期（`exp` 宣告） +- **受眾 (Audience)**：確認 `aud` 宣告與你註冊的 API 資源標示符一致 +- **所需權限**：確認權杖的 `scope` 宣告包含必要權限
-### 沒有完整用戶端時如何測試？\{how-do-i-test-without-a-full-client} \{#how-do-i-test-without-a-full-client} +### 沒有完整用戶端要怎麼測試？\{#how-do-i-test-without-a-full-client} -可使用 [個人存取權杖 (Personal access token)](/user-management/personal-access-token) 模擬驗證呼叫。這讓你無需在用戶端應用程式實作完整 OAuth 流程即可測試 API 端點。 +可使用 [個人存取權杖 (Personal access token)](/user-management/personal-access-token) 模擬驗證呼叫。這讓你無需在用戶端應用程式實作完整 OAuth 流程，也能測試 API 端點。
-### 請求權限時可以用 scope 前綴或簡寫嗎？\{can-i-use-scope-prefixes-or-shortened-versions} \{#can-i-use-scope-prefixes-or-shortened-versions} +### 請求權限時可以用 scope 前綴或簡寫嗎？\{#can-i-use-scope-prefixes-or-shortened-versions} -不行。Scope 名稱必須**完全符合**你在 API 資源 (API resource) 中定義的權限名稱。前綴或簡寫無法作為萬用字元。 +不行。Scope 名稱必須**完全符合**你在 API 資源 (API resource) 中定義的權限名稱。前綴與簡寫無法作為萬用字元。 **範例：** diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index bf80538fe3f..99ecb4eab15 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-leve import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -20,7 +21,7 @@ export const resource = 'https://api.your-app.com/organizations'; ## 什麼是組織層級 API 資源 (Organization-level API resources)? \{#what-are-organization-level-api-resources} -組織層級 API 資源 (Organization-level API resources) 是指應用程式中**限定於特定組織範圍**的端點或服務。這些 API 會根據組織情境強制執行授權 (Authorization) 與存取控制，確保使用者或客戶端僅能存取與其組織相關的資料與操作。 +組織層級 API 資源 (Organization-level API resources) 是你應用程式中**限定於特定組織範圍**的端點或服務。這些 API 會根據組織情境強制執行授權 (Authorization) 與存取，確保使用者或客戶端僅能存取與其組織相關的資料與操作。 **常見應用情境包括** @@ -29,36 +30,36 @@ export const resource = 'https://api.your-app.com/organizations'; - 綁定組織的帳單、訂閱或稽核端點 - 任何需依租戶隔離操作與資料的 API -Logto 允許你透過 OAuth 2.1 與 RBAC（角色型存取控制 (Role-based access control)）保護這些組織 API，同時支援多租戶 SaaS 架構。 +Logto 允許你利用 OAuth 2.1 與 RBAC（角色型存取控制）保護這些組織 API，同時支援多租戶 SaaS 架構。 這些權限透過 [組織範本 (organization template)](/authorization/organization-template) 中定義的**組織角色 (organization roles)** 管理。每個組織都使用相同範本，確保所有組織的權限模型一致。 ## Logto 的運作方式 \{#how-it-works-in-logto} -- **API 資源與權限全域註冊：** 每個 API 資源會在 Logto 以唯一資源標示符（URI）與一組權限（scopes）註冊。 -- **組織層級角色：** 組織角色在組織範本中定義。API 資源權限（scopes）指派給組織角色，再由組織內的使用者或客戶端繼承。 +- **API 資源與權限全域註冊：** 每個 API 資源會在 Logto 以唯一資源標示符（URI）及一組權限（scopes）註冊。 +- **組織層級角色：** 組織角色於組織範本中定義。API 資源權限（scopes）指派給組織角色，再分配給每個組織內的使用者或客戶端。 - **情境感知授權 (Context-aware authorization)：** 當客戶端請求同時帶有 API 資源與 `organization_id` 的存取權杖 (Access token) 時，Logto 會簽發同時包含組織情境與 API 受眾 (Audience) 的權杖。權杖的權限（scopes）由該使用者於指定組織的組織角色決定。 -- **與全域資源分離：** API 資源可帶或不帶組織情境存取。僅當請求中包含 `organization_id` 時才套用組織 RBAC。若為所有使用者共用的 API，請參閱[保護全域 API 資源](/authorization/global-api-resources)。 +- **與全域資源分離：** API 資源可帶或不帶組織情境存取。僅當請求中包含 `organization_id` 時，才會套用組織 RBAC。若為所有使用者共用的 API，請參閱 [保護全域 API 資源](/authorization/global-api-resources)。 組織層級 API 資源 RBAC -### 實作流程總覽 \{#implementation-overview} +### 實作總覽 \{#implementation-overview} 1. **註冊你的 API 資源**，並在 Logto 定義其權限（scopes）。 2. **在組織範本中定義組織角色**，並指派相關 API 權限。 -3. **將角色指派給每個組織內的使用者或客戶端。** -4. **請求帶有 `organization_id` 的 API 存取權杖**，以納入組織情境。 -5. **在 API 驗證存取權杖**，同時檢查組織情境與權限。 +3. **將角色分配給每個組織內的使用者或客戶端。** +4. **請求帶有 `organization_id` 的 API 存取權杖 (Access token)**，以納入組織情境。 +5. **在你的 API 驗證存取權杖**，同時檢查組織情境與權限。 ### Logto 如何套用組織 RBAC \{#how-logto-applies-organization-rbac} -- 若請求存取權杖**未帶 `organization_id`**，僅會考慮全域角色／權限。 -- 若請求存取權杖**帶有 `organization_id`**，Logto 會評估該使用者於該組織的組織角色及其對應權限。 -- 最終產生的 JWT 會同時包含 API 受眾（`aud` 宣告 (Claim)）與組織情境（`organization_id` 宣告 (Claim)），且權限（scopes）僅限於該使用者於該組織角色所授權的範圍。 +- 若請求存取權杖**未帶** `organization_id`，僅會考慮全域角色／權限。 +- 若請求存取權杖**帶有** `organization_id`，Logto 會評估該使用者於該組織的組織角色及其對應權限。 +- 最終產生的 JWT 會同時包含 API 受眾（`aud` 宣告 (Claim)）與組織情境（`organization_id` 宣告 (Claim)），且權限（scopes）僅限於該使用者組織角色所授予者。 ### 授權流程：以組織情境驗證並保護 API \{#authorization-flow-authenticating-and-securing-apis-with-organization-context} -下列流程展示客戶端（Web、行動或後端）如何取得並使用組織權杖 (Organization token) 存取組織層級 API 資源。 +下列流程展示客戶端（Web、行動裝置或後端）如何取得並使用組織權杖 (Organization token) 存取組織層級 API 資源。 請注意，流程未詳列所有必要參數或標頭，僅聚焦於主要步驟。繼續閱讀可瞭解實際運作方式。 @@ -70,8 +71,8 @@ sequenceDiagram alt 使用者驗證 (User authentication) Client->>Logto: GET /oidc/auth - Logto->>Logto: 導向使用者登入頁 - Logto->>Client: 登入後帶回 `authorization_code` + Logto->>Logto: 將使用者導向登入頁 + Logto->>Client: 登入後導回並帶有 `authorization_code` Client->>Logto: POST /oidc/token，帶 `grant_type=authorization_code` Logto->>Client: 回傳重新整理權杖 (Refresh token) Client->>Logto: POST /oidc/token，帶 `grant_type=refresh_token`
+ resource + organization_id @@ -80,7 +81,7 @@ sequenceDiagram end Logto->>Client: 回傳存取權杖 (JWT) - Client->>API: Bearer 權杖請求 + Client->>API: 以 Bearer 權杖請求 API->>API: 驗證權杖，檢查組織情境與權限 alt 權杖有效 @@ -90,82 +91,82 @@ sequenceDiagram end ``` -_使用者驗證 = 瀏覽器／App。M2M = 使用 client credentials + 組織情境的後端服務或腳本。_ +_使用者驗證 = 瀏覽器／App。M2M = 使用客戶端憑證與組織情境的後端服務或腳本。_ ## 實作步驟 \{#implementation-steps} ### 註冊你的 API 資源 \{#register-your-api-resource} -1. 前往 Console → API 資源 (API resources)。 +1. 前往 主控台 → API 資源。 2. 建立新 API 資源（如 `https://api.yourapp.com/org`），並定義其權限（scopes）。 -完整設定步驟請參閱[定義帶權限的 API 資源](/authorization/role-based-access-control#define-api-resources-with-permissions)。 +完整設定步驟請參閱 [定義帶權限的 API 資源](/authorization/role-based-access-control#define-api-resources-with-permissions)。 ### 設定組織角色 \{#set-up-organization-roles} -1. 前往 Console → 組織範本 (Organization template) → 組織角色 (Organization roles)。 +1. 前往 主控台 → 組織範本 → 組織角色。 2. 建立組織角色（如 `admin`、`member`），並指派 API 權限給每個角色。 -3. 將角色指派給每個組織內的使用者或客戶端。若尚未成員，請先邀請或加入。 +3. 將角色分配給每個組織內的使用者或客戶端。若尚未成員，請先邀請或新增。 -完整設定步驟請參閱[使用組織角色](/authorization/role-based-access-control#configure-organization-roles)。 +完整設定步驟請參閱 [使用組織角色](/authorization/role-based-access-control#configure-organization-roles)。 -### 取得 API 資源的組織權杖 \{#obtain-organization-tokens-for-api-resources} +### 取得 API 資源的組織權杖 (Organization tokens) \{#obtain-organization-tokens-for-api-resources} -你的客戶端／應用程式應同時帶上 `resource` 與 `organization_id` 參數來請求組織層級 API 權杖。Logto 會以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式簽發組織權杖。你可透過 [重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [client credentials flow](https://auth.wiki/client-credentials-flow) 取得。 +你的客戶端／應用程式應同時帶上 `resource` 與 `organization_id` 參數來請求組織層級 API 的權杖。Logto 會以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式簽發組織權杖。你可透過 [重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [客戶端憑證流程 (client credentials flow)](https://auth.wiki/client-credentials-flow) 取得。 #### 重新整理權杖流程 (Refresh token flow) \{#refresh-token-flow} -幾乎所有 Logto 官方 SDK 都原生支援以重新整理權杖流程取得組織權杖。你也可用標準 OAuth 2.0 / OIDC 客戶端函式庫實作此流程。 +幾乎所有 Logto 官方 SDK 都原生支援以重新整理權杖流程取得組織權杖。標準 OAuth 2.0 / OIDC 客戶端函式庫也可實作此流程。 初始化 Logto SDK 時，請將 `urn:logto:scope:organizations` 及所需組織權限（scopes）加入 `scopes` 參數。 -部分 Logto SDK 已預設組織權限範圍，如 JavaScript SDK 的 `UserScope.Organizations`。 +部分 Logto SDK 已預設組織權限範圍，例如 JavaScript SDK 的 `UserScope.Organizations`。 -呼叫 `getAccessToken()` 時，請同時指定 API 資源（`resource`）與組織 ID（`organizationId`），即可取得組織權杖。 +呼叫 `getAccessToken()` 時，請同時指定 API 資源（`resource`）與組織 ID（`organizationId`）以取得組織權杖。 -各 SDK 詳細用法請參閱[快速入門](/quick-starts)。 +各 SDK 詳細用法請參閱 [快速上手](/quick-starts)。 設定 OAuth 2.0 客戶端或初始化授權碼流程時，請確保包含下列參數： -- `resource`：設為 Logto 註冊的 API 資源識別（如 `https://api.your-app.com/organizations`）。 -- `scope`：包含預設組織範圍（`urn:logto:scope:organizations`）、`offline_access`（取得重新整理權杖），以及所需 API 權限（如 `manage:members view:analytics`）。 +- `resource`：設為 Logto 註冊的 API 資源識別碼（如 `https://api.your-app.com/organizations`）。 +- `scope`：包含預設組織權限範圍（`urn:logto:scope:organizations`）、`offline_access`（取得重新整理權杖），以及所需 API 權限（如 `manage:members view:analytics`）。 -部分函式庫可能不原生支援 `resource` 參數，但通常可在授權請求中傳遞額外參數。請查閱你的函式庫文件。 +部分函式庫可能不原生支援 `resource` 參數，但通常可於授權請求中傳遞額外參數。詳情請查閱函式庫文件。 -以下為非正式授權請求範例： +以下為授權請求的非正式範例： -使用者驗證後，你會收到授權碼。請用此碼對 Logto `/oidc/token` 端點發送 POST 請求。 +使用者驗證後，你會收到授權碼。請用此授權碼向 Logto `/oidc/token` 端點發送 POST 請求。 -以下為非正式權杖請求範例： +以下為權杖請求的非正式範例： -你會收到可用於取得組織權杖的重新整理權杖。 +你將收到可用於取得組織權杖的重新整理權杖。 -最後，使用重新整理權杖對 Logto `/oidc/token` 端點發送 POST 請求取得組織權杖。請記得包含： +最後，使用重新整理權杖向 Logto `/oidc/token` 端點發送 POST 請求以取得組織權杖。請記得包含： -- `resource` 參數，設為 API 資源識別（如 `https://api.yourapp.com/org`）。 -- `organization_id` 參數，設為目標組織 ID。 -- （選填）`scope` 參數，進一步縮限所需權限（如 `manage:members view:reports`）。 +- `resource` 參數設為 API 資源識別碼（如 `https://api.yourapp.com/org`）。 +- `organization_id` 參數設為目標組織 ID。 +- （可選）`scope` 參數可進一步縮限所需權限（如 `manage:members view:reports`）。 -以下為非正式權杖請求範例： +以下為權杖請求的非正式範例： -#### Client credentials flow \{#client-credentials-flow} +#### 客戶端憑證流程 (Client credentials flow) \{#client-credentials-flow} -針對機器對機器 (M2M) 情境，可用 client credentials flow 取得組織層級 API 權限的存取權杖。對 Logto `/oidc/token` 端點發送帶有組織參數的 POST 請求，即可用 client ID 與 secret 取得組織權杖。 +針對機器對機器 (M2M) 情境，你可使用客戶端憑證流程取得組織層級 API 資源權限的存取權杖。只需向 Logto `/oidc/token` 端點發送帶有組織參數的 POST 請求，即可用你的客戶端 ID 與密鑰請求組織權杖。 -請在請求中包含下列關鍵參數： +請在請求中包含以下主要參數： -- `resource`：API 資源識別（如 `https://api.yourapp.com/org`）。 +- `resource`：API 資源識別碼（如 `https://api.yourapp.com/org`）。 - `organization_id`：欲取得權杖的組織 ID。 -- `scope`：欲請求的組織層級 API 權限（如 `invite:member`、`manage:billing`）。 +- `scope`：欲請求的組織層級 API 資源權限（如 `invite:member`、`manage:billing`）。 -以下為 client credentials grant type 的非正式權杖請求範例： +以下為使用 client credentials grant type 的權杖請求非正式範例： -### 驗證組織權杖 \{#validate-organization-tokens} +### 驗證組織權杖 (Organization tokens) \{#validate-organization-tokens} -Logto 簽發的組織權杖（JWT）包含可供 API 強制執行組織層級存取控制的宣告 (Claims)。 +Logto 簽發的組織權杖（JWT）包含可供你的 API 強制執行組織層級存取控制的宣告 (Claims)。 當你的應用程式收到組織權杖時，應： - 驗證權杖簽章（使用 Logto 的 JWKs）。 - 確認權杖未過期（`exp` 宣告）。 - 檢查 `iss`（簽發者 (Issuer)）是否為你的 Logto 端點。 -- 確認 `aud`（受眾 (Audience)）是否為你註冊的 API 資源識別（如 `https://api.yourapp.com/org`）。 +- 確認 `aud`（受眾 (Audience)）是否為你註冊的 API 資源識別碼（如 `https://api.yourapp.com/org`）。 - 驗證 `organization_id` 宣告，確保權杖限定於正確組織。 - 拆解 `scope` 宣告（以空格分隔），檢查所需權限。 - 若 API 路徑包含組織 ID（如 `/organizations/{organizationId}/members`），請確保 `organization_id` 宣告與路徑參數一致。 -逐步與語言專屬教學請參閱[如何驗證存取權杖](/authorization/validate-access-tokens)。 +逐步與語言專屬教學請參閱 [如何驗證存取權杖](/authorization/validate-access-tokens)。 + + ## 最佳實踐與安全建議 \{#best-practices-and-security-tips} - **務必驗證組織情境：** 不要只信任權杖，對每個組織範圍 API 呼叫都要檢查 `organization_id` 宣告。 -- **使用受眾限制：** 務必檢查 `aud` 宣告，確保權杖僅用於預期組織。 -- **權限設計以業務為導向：** 權限命名清楚對應實際操作，每個組織角色僅授權所需權限。 -- **盡量區分 API 與非 API 權限**（但兩者可同屬一角色）。 +- **使用受眾限制：** 務必檢查 `aud` 宣告，確保權杖僅用於指定組織。 +- **權限設計以業務為導向：** 權限名稱應清楚對應實際操作，每個組織角色僅授予必要權限。 +- **盡可能區分 API 與非 API 權限**（但兩者可同屬一個角色）。 - **縮短權杖存活時間：** 若權杖外洩可降低風險。 - **定期檢視組織範本：** 隨產品演進更新角色與權限。 @@ -245,10 +248,10 @@ Logto 簽發的組織權杖（JWT）包含可供 API 強制執行組織層級存 ## 延伸閱讀 \{#further-reading} -如何驗證存取權杖 (Access tokens) +如何驗證存取權杖 自訂權杖宣告 (Claims) - 使用情境：打造多租戶 SaaS 應用程式 + 實例：打造多租戶 SaaS 應用程式 RFC 8707：資源標示符 (Resource Indicators) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 29e83072596..68da2b36ec9 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -6,6 +6,7 @@ import illustration from '@site/docs/authorization/assets/rbac-organization-perm import AuthorizationRequestExample from '@site/docs/authorization/fragments/AuthorizationRequestExample'; import ClientCredentialsRequestExample from '@site/docs/authorization/fragments/ClientCredentialsRequestExample'; import TokenRequestExample from '@site/docs/authorization/fragments/TokenRequestExample'; +import HandleUserPermissionChange from '@site/docs/authorization/fragments/_handle-user-permission-change.mdx'; import TabItem from '@theme/TabItem'; import Tabs from '@theme/Tabs'; @@ -14,20 +15,20 @@ import OrganizationTokenWarning from './fragments/_organization-token-warning.md # 保護組織（非 API）權限 -使用組織範本來管理並強制執行 Logto 中的組織層級角色與權限，控制在組織情境下對應用程式內功能與工作流程的存取。 +使用組織範本來管理並強制執行 Logto 中的組織層級角色與權限，控制使用者在組織情境下對應用程式內功能與工作流程的存取。 ## 什麼是組織（非 API）權限？ \{#what-are-organization-non-api-permissions} -組織權限（非 API）控制使用者在**組織情境**下可以執行哪些操作，但**不會在 API 層級強制執行**。這些權限主要用於管理應用程式功能、UI 元素、工作流程或商業行為，而非後端 API。 +組織權限（非 API）控制使用者在**組織情境下**可以執行哪些操作，但**不會在 API 層級強制執行**。這些權限主要用於管理應用程式功能、UI 元素、工作流程或商業行為，而非後端 API。 -**常見使用情境包括** +**常見應用情境包含** - 邀請或管理組織成員 - 指派或變更組織角色 - 管理組織的帳單、設定或管理功能 - 存取沒有 API 端點的儀表板、分析或內部工具 -Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Access Control) 來保護這些組織權限，同時支援多租戶 SaaS 架構。 +Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Access Control) 保護這些組織權限，同時支援多租戶 SaaS 架構。 這些權限透過 [組織範本](/authorization/organization-template) 中定義的**組織角色**來管理。每個組織都使用相同的範本，確保所有組織擁有一致的權限模型。 @@ -35,7 +36,7 @@ Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Acces - **組織層級 RBAC (Role-based Access Control)：** 角色與權限在組織範本中定義。當使用者加入組織時，會被指派一個或多個角色，進而獲得特定權限。 - **非 API 強制執行：** 權限會在你的應用程式 UI、工作流程或後端邏輯中檢查與強制執行，不一定由 API gateway 處理。 -- **與 API 保護分離：** 組織（非 API）權限與 API 資源權限是分開的。你可以在進階情境下同時結合兩者。 +- **與 API 保護分離：** 組織（非 API）權限與 API 資源權限是分開的。你可以根據需求結合兩者以應對進階情境。
組織權限 RBAC @@ -44,10 +45,10 @@ Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Acces ### 實作概覽 \{#implementation-overview} 1. 在 Logto 的組織範本中**定義組織權限**。 -2. **建立組織角色**，將所需權限打包給組織專屬操作。 +2. **建立組織角色**，將組織專屬操作所需的權限打包。 3. 在每個組織內**指派角色**給使用者或用戶端。 4. 透過重新整理權杖 (refresh token) 或用戶端憑證流程 (client credentials flow) **取得當前組織的組織權杖 (JWT)**。 -5. 在應用程式 UI 或後端**驗證存取權杖**，以強制執行組織權限。 +5. 在應用程式的 UI 或後端**驗證存取權杖**以強制執行組織權限。 ### 授權流程：驗證與保護組織權限 \{#authorization-flow-authenticating-and-securing-organization-permissions} @@ -57,18 +58,18 @@ Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Acces ```mermaid sequenceDiagram - participant Client as 用戶端 + participant Client as 用戶端 (Client) participant Logto as Logto - participant App as 應用程式 / UI / 後端 + participant App as 應用程式 / UI / 後端 (App/UI/backend) - alt 使用者驗證 + alt 使用者驗證 (User authentication) Client->>Logto: GET /oidc/auth Logto->>Logto: 導向使用者登入頁面 Logto->>Client: 登入後導回並帶有 `authorization_code` Client->>Logto: POST /oidc/token，帶上 `grant_type=authorization_code` - Logto->>Client: 回傳重新整理權杖 + Logto->>Client: 回傳重新整理權杖 (refresh token) Client->>Logto: POST /oidc/token，帶上 `grant_type=refresh_token` + 組織參數 - else M2M 用戶端驗證 + else M2M 用戶端驗證 (M2M client authentication) Client->>Logto: POST /oidc/token，帶上 `grant_type=client_credentials` + 組織參數 end @@ -76,9 +77,9 @@ sequenceDiagram Client->>App: 以 Bearer 權杖發送請求 App->>App: 驗證組織權杖，檢查組織情境與權限 - alt 權杖有效 + alt 權杖有效 (Token is valid) App->>Client: 允許組織專屬操作 / 資料 - else 權杖無效 + else 權杖無效 (Token is invalid) App->>Client: 401 未授權或拒絕 UI 存取 end ``` @@ -104,7 +105,7 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組 ### 取得組織權杖（非 API） \{#obtain-organization-tokens-non-api} -你的用戶端 / 應用程式應取得組織權杖（非 API）以存取組織權限。Logto 發行的組織權杖為 [JSON Web Tokens (JWTs)](https://auth.wiki/jwt)。你可以透過 [重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [用戶端憑證流程 (client credentials flow)](https://auth.wiki/client-credentials-flow) 取得。 +你的用戶端 / 應用程式應取得組織權杖（非 API）以存取組織權限。Logto 會以 [JSON Web Token (JWT)](https://auth.wiki/jwt) 形式發行組織權杖。你可以透過 [重新整理權杖流程 (refresh token flow)](https://auth.wiki/refresh-token) 或 [用戶端憑證流程 (client credentials flow)](https://auth.wiki/client-credentials-flow) 取得。 #### 重新整理權杖流程 \{#refresh-token-flow} @@ -113,13 +114,13 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組 -初始化 Logto SDK 時，請將 `urn:logto:scope:organizations` 及所需組織權限（scopes）加入 `scopes` 參數。 +初始化 Logto SDK 時，將 `urn:logto:scope:organizations` 及所需組織權限（scopes）加入 `scopes` 參數。 部分 Logto SDK 已預設提供組織專用 scope，例如 JavaScript SDK 的 `UserScope.Organizations`。 -使用 `getOrganizationToken` 或類似方法（如帶組織 ID 的 `getAccessToken`）來請求特定組織的組織權杖。 +使用 `getOrganizationToken` 或類似方法（如帶入組織 ID 的 `getAccessToken`）來為特定組織請求組織權杖。 各 SDK 詳細用法請參閱 [快速入門](/quick-starts)。 @@ -129,7 +130,7 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組 設定 OAuth 2.0 用戶端或初始化授權碼流程時，請確保包含下列參數： - `resource`：設為 `urn:logto:resource:organizations`，表示你要取得組織權杖。 -- `scope`：包含預設組織 scope（`urn:logto:scope:organizations`）、`offline_access`（取得重新整理權杖），以及你需要的特定組織權限（如 `invite:member`、`manage:billing`）。 +- `scope`：包含預設組織 scope（`urn:logto:scope:organizations`）、`offline_access`（取得重新整理權杖），以及你需要的組織權限（如 `invite:member`、`manage:billing`）。 部分函式庫可能不原生支援 `resource` 參數，但通常允許你在授權請求中傳遞額外參數。請查閱你的函式庫文件。 @@ -148,14 +149,14 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組 -你會收到可用於取得組織權杖的重新整理權杖。 +你將收到可用於取得組織權杖的重新整理權杖。 最後，使用重新整理權杖對 Logto 的 `/oidc/token` 端點發送 POST 請求以取得組織權杖。請記得包含： - `organization_id` 參數，設為目標組織 ID。 -- （可選）`scope` 參數，進一步縮限所需權限（如 `manage:members view:reports`）。 +- （選填）`scope` 參數，進一步縮限所需權限（如 `manage:members view:reports`）。 以下為權杖請求的非正式範例： @@ -166,14 +167,14 @@ _使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組 #### 用戶端憑證流程 \{#client-credentials-flow} -針對機器對機器（M2M）情境，你可以使用用戶端憑證流程取得組織權限的存取權杖。只需對 Logto 的 `/oidc/token` 端點發送 POST 請求並帶上組織參數，即可使用用戶端 ID 與密鑰請求組織權杖。 +針對機器對機器（M2M, Machine-to-Machine）情境，你可以使用用戶端憑證流程取得組織權限的存取權杖。只需對 Logto 的 `/oidc/token` 端點發送帶有組織參數的 POST 請求，即可使用用戶端 ID 與密鑰請求組織權杖。 請在請求中包含以下主要參數： - `organization_id`：你要取得權杖的組織 ID。 - `scope`：你要請求的組織權限（如 `invite:member`、`manage:billing`）。 -以下為使用用戶端憑證授權型態的權杖請求非正式範例： +以下為使用用戶端憑證授權類型的權杖請求非正式範例： ## 最佳實踐與安全建議 \{#best-practices-and-security-tips} - **切勿僅依賴 UI 強制執行：** 關鍵操作務必在後端驗證權限。 -- **使用受眾限制：** 一定要檢查 `aud` 宣告，確保權杖屬於目標組織。 -- **權限設計以業務為導向：** 使用清楚對應實際操作的名稱，每個組織角色僅授予必要權限。 +- **使用受眾限制：** 務必檢查 `aud` 宣告，確保權杖屬於目標組織。 +- **權限設計以業務為導向：** 使用明確名稱對應實際操作，每個組織角色僅授予所需權限。 - **盡可能區分 API 與非 API 權限**（但兩者可同時存在於單一角色）。 - **隨產品演進定期檢視組織範本。** @@ -207,7 +210,7 @@ Logto 發行的組織權杖（JWT）包含宣告（claims），你的應用程
-### 我可以在單一角色中混用組織與非組織權限嗎？ \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} +### 可以在單一角色中混用組織與非組織權限嗎？ \{#can-i-mix-organization-and-non-organization-permissions-in-a-single-role} @@ -218,7 +221,7 @@ Logto 發行的組織權杖（JWT）包含宣告（claims），你的應用程
-### 我應該在哪裡強制執行非 API 權限？ \{#where-should-i-enforce-non-api-permissions} +### 應該在哪裡強制執行非 API 權限？ \{#where-should-i-enforce-non-api-permissions} From c2905dc265669f32f4631a7ddbfea3ba26d28e2c Mon Sep 17 00:00:00 2001 From: Charles Zhao Date: Thu, 11 Dec 2025 15:46:26 +0800 Subject: [PATCH 2/2] fix: lint errors --- .../authorization/organization-level-api-resources.mdx | 3 ++- .../current/authorization/organization-permissions.mdx | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx index 5de04d98b6b..2f2651994b4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-level-api-resources.mdx @@ -106,7 +106,8 @@ _ユーザー認証 (Authentication) = ブラウザ／アプリ。M2M = クラ 1. コンソール → 組織テンプレート → 組織ロール - に移動します。 + + に移動します。 2. 組織ロール（例： `admin`、`member`）を作成し、各ロールに API 権限を割り当てます。 3. 各組織内でユーザーやクライアントにロールを割り当てます。まだメンバーでない場合は、招待または追加してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx index 8dc963015d1..7ed147e67e8 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/authorization/organization-permissions.mdx @@ -92,7 +92,8 @@ _ユーザー認証 = ブラウザ/アプリ。M2M = クライアントクレデ 1. コンソール → 組織テンプレート → 組織権限 - にアクセスします。 + + にアクセスします。 2. 必要な組織権限を定義します（例：`invite:member`、`manage:billing`、`view:analytics` など）。 詳細な設定手順は [組織権限の定義](/authorization/role-based-access-control#define-organization-permissions) を参照してください。 @@ -101,7 +102,8 @@ _ユーザー認証 = ブラウザ/アプリ。M2M = クライアントクレデ 1. コンソール → 組織テンプレート → 組織ロール - にアクセスします。 + + にアクセスします。 2. 先ほど定義した組織権限をまとめたロールを作成します（例：`admin`、`member`、`billing` など）。 3. これらのロールを各組織内のユーザーやクライアントに割り当てます。