From 1251ff7d0b066d270e42ef0bbcb1b2d0ed5ea478 Mon Sep 17 00:00:00 2001 From: wangsijie <5717882+wangsijie@users.noreply.github.com> Date: Mon, 29 Jun 2026 11:43:32 +0000 Subject: [PATCH] chore: update translations and generated content --- .../current/developers/README.mdx | 25 ++- .../current/developers/audit-logs/README.mdx | 10 +- .../developers/sdk-conventions/README.mdx | 12 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 28 ++-- .../current/developers/webhooks/README.mdx | 24 +-- .../current/developers/webhooks/events.mdx | 109 ++++++------- .../current/security/README.mdx | 22 ++- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 11 +- .../current/developers/audit-logs/README.mdx | 8 +- .../developers/sdk-conventions/README.mdx | 6 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 22 +-- .../current/developers/webhooks/README.mdx | 34 ++-- .../current/developers/webhooks/events.mdx | 73 ++++----- .../current/security/README.mdx | 16 +- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 19 ++- .../current/developers/audit-logs/README.mdx | 10 +- .../developers/sdk-conventions/README.mdx | 2 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 20 +-- .../current/developers/webhooks/README.mdx | 24 +-- .../current/developers/webhooks/events.mdx | 103 ++++++------ .../current/security/README.mdx | 18 ++- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 23 ++- .../current/developers/audit-logs/README.mdx | 44 +++-- .../developers/sdk-conventions/README.mdx | 6 +- .../service-to-service-delegation.mdx | 151 ++++++++++++++++++ .../current/developers/signing-keys.mdx | 34 ++-- .../current/developers/webhooks/README.mdx | 38 ++--- .../current/developers/webhooks/events.mdx | 113 ++++++------- .../current/security/README.mdx | 26 ++- .../current/security/send-rate-limit.mdx | 40 +++++ .../current/developers/README.mdx | 19 ++- .../current/developers/audit-logs/README.mdx | 8 +- .../developers/sdk-conventions/README.mdx | 6 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 34 ++-- .../current/developers/webhooks/README.mdx | 30 ++-- .../current/developers/webhooks/events.mdx | 111 ++++++------- .../current/security/README.mdx | 36 +++-- .../current/security/send-rate-limit.mdx | 39 +++++ .../current/developers/README.mdx | 29 ++-- .../current/developers/audit-logs/README.mdx | 10 +- .../developers/sdk-conventions/README.mdx | 6 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 30 ++-- .../current/developers/webhooks/README.mdx | 26 +-- .../current/developers/webhooks/events.mdx | 69 ++++---- .../current/security/README.mdx | 16 +- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 21 ++- .../current/developers/audit-logs/README.mdx | 22 +-- .../developers/sdk-conventions/README.mdx | 16 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 32 ++-- .../current/developers/webhooks/README.mdx | 42 ++--- .../current/developers/webhooks/events.mdx | 115 ++++++------- .../current/security/README.mdx | 40 +++-- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 17 +- .../current/developers/audit-logs/README.mdx | 8 +- .../developers/sdk-conventions/README.mdx | 10 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 34 ++-- .../current/developers/webhooks/README.mdx | 40 ++--- .../current/developers/webhooks/events.mdx | 115 ++++++------- .../current/security/README.mdx | 32 ++-- .../current/security/send-rate-limit.mdx | 38 +++++ .../current/developers/README.mdx | 17 +- .../current/developers/audit-logs/README.mdx | 8 +- .../developers/sdk-conventions/README.mdx | 8 +- .../service-to-service-delegation.mdx | 149 +++++++++++++++++ .../current/developers/signing-keys.mdx | 44 ++--- .../current/developers/webhooks/README.mdx | 52 +++--- .../current/developers/webhooks/events.mdx | 117 +++++++------- .../current/security/README.mdx | 29 ++-- .../current/security/send-rate-limit.mdx | 38 +++++ 81 files changed, 2842 insertions(+), 975 deletions(-) create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/de/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/es/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/fr/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/ko/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/pt-BR/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/th/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx create mode 100644 i18n/zh-TW/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/README.mdx index 51437ae9e67..d680cc6ecf1 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -39,25 +39,34 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Benutzermimikry (User impersonation)', href: '/developers/user-impersonation', - description: 'Erlaube autorisierten Benutzern, vorübergehend im Namen von Endbenutzern zu handeln – nützlich für Fehlerbehebung, Kundensupport und administrative Aufgaben.', + description: 'Erlaube autorisierten Benutzern, vorübergehend im Namen von Endbenutzern zu agieren – nützlich für Fehlerbehebung, Kundensupport und administrative Aufgaben.', customProps: { icon: , } }, + { + type: 'link', + label: 'Service-zu-Service-Delegation (Service-to-service delegation)', + href: '/developers/service-to-service-delegation', + description: 'Tausche ein Benutzer-Zugangstoken gegen ein nachgelagertes API-Zugangstoken aus, damit Backend-Dienste im Namen des aktuellen Benutzers agieren können.', + customProps: { + icon: , + } + }, ]} /> ``` -## Generisches für Entwickler \{#generics-for-developers} +## Allgemeines für Entwickler \{#generics-for-developers} ```mdx-code-block , } @@ -66,7 +75,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhooks', href: '/developers/webhooks', - description: 'Webhooks unterstützen Echtzeit-Benachrichtigungen über Benutzerinformationen und Berechtigungsaktualisierungen per HTTP-Anfrage und erhöhen die Bequemlichkeit und Flexibilität der Logto-Integration.', + description: 'Webhooks unterstützen Echtzeit-Benachrichtigungen über Benutzerinformationen und Berechtigungsaktualisierungen per HTTP-Anfragen und erhöhen die Bequemlichkeit und Flexibilität der Logto-Integration.', customProps: { icon: , } @@ -75,16 +84,16 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Audit-Logs', href: '/developers/audit-logs', - description: 'Zeichnet benutzerbezogene Authentifizierungsaktivitäten auf, um das Debugging und die Analyse von Benutzeraktivitäten zu erleichtern.', + description: 'Zeichne Aktivitäten im Zusammenhang mit der Benutzer-Authentifizierung auf, um das Debugging und die Analyse von Benutzeraktivitäten zu erleichtern.', customProps: { icon: , } }, { type: 'link', - label: 'SDK-Konvention', + label: 'SDK-Konvention (SDK convention)', href: '/developers/', - description: 'Stellt die Datenstrukturen, Zwecke und Methoden im SDK vor, sodass Nutzer das SDK an verschiedene Geschäftsszenarien anpassen können.', + description: 'Stelle die Datenstrukturen, Zwecke und Methoden im SDK vor, damit Nutzer das SDK an verschiedene Geschäftsszenarien anpassen können.', customProps: { icon: , } diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index e0f4c1d7ca6..404cbaa1385 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Audit-Logs @@ -11,7 +11,7 @@ Das Audit-Log von Logto ermöglicht es dir, Benutzeraktivitäten und Ereignisse Navigiere zu Konsole > Audit-Logs. Logto erfasst und organisiert Authentifizierungsereignisse in einer Tabelle. Es werden der Ereignisname, der Benutzer, die Anwendung und der Zeitstempel protokolliert. Du kannst die Ergebnisse eingrenzen, indem du nach Ereignisname und Anwendungsname filterst. Durch Klicken auf ein bestimmtes Ereignis erhältst du weitere Details. :::warning -Audit-Logs enthalten nur Logs, die während des Authentifizierungsprozesses des Benutzers auftreten. Logs von Management API-Operationen werden nicht aufgezeichnet. +Audit-Logs enthalten nur Protokolle, die während des Authentifizierungsprozesses des Benutzers auftreten. Protokolle von Management API-Operationen werden nicht aufgezeichnet. ::: ## Benutzeraktivität auf Mandantenebene erfassen \{#capture-user-activity-at-the-tenant-level} @@ -32,17 +32,17 @@ Durch die Aufzeichnung dieser Ereignisse können Organisationen potenzielle Sich ## Detaillierte Analyse auf Benutzerebene durchführen \{#perform-a-detailed-analysis-at-the-user-level} -Administratoren können eine detaillierte Analyse der Logs durchführen, die mit bestimmten Benutzern verknüpft sind, um umfassende Untersuchungen zu bestimmten Ereignissen zu ermöglichen. Der Navigationsprozess ist einfach und benutzerfreundlich. +Administratoren können eine detaillierte Analyse der Logs durchführen, die mit bestimmten Benutzern verknüpft sind, und so umfassende Untersuchungen zu bestimmten Ereignissen ermöglichen. Der Navigationsprozess ist einfach und benutzerfreundlich. Um benutzerspezifische Logs einzusehen, folge diesen Schritten: 1. Navigiere zu Konsole > Benutzerverwaltung. 2. Wähle den gewünschten Benutzer aus und gehe zur Detailseite. -3. Klicke auf „Benutzer-Logs“. Die angezeigte Tabelle zeigt ausschließlich Log-Ereignisse, die von diesem bestimmten Benutzer durchgeführt und ausgelöst wurden. +3. Klicke auf „Benutzer-Logs“. Die angezeigte Tabelle zeigt ausschließlich Log-Ereignisse an, die von diesem bestimmten Benutzer durchgeführt und ausgelöst wurden. Audit-Logs, die sich auf einen bestimmten Benutzer beziehen ## FAQs \{#faqs} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index 530c6d14e88..f1b1b92555a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,18 +2,18 @@ id: sdk-conventions title: Plattform-SDK-Konventionen sidebar_label: Plattform-SDK-Konventionen -sidebar_position: 8 +sidebar_position: 9 --- # Plattform-SDK-Konventionen Logto bietet einen sehr leistungsstarken und flexiblen Web-Authentifizierungsdienst. -Im praktischen Einsatz der Logto-Dienste ist es für Entwickler oft notwendig, das Logto SDK in ihre eigenen Client-Anwendungen zu integrieren, um den Anmeldestatus der Benutzer, Berechtigungen und mehr zu verwalten. +Im praktischen Einsatz der Logto-Dienste ist es für Entwickler oft aus Gründen der Bequemlichkeit notwendig, das Logto SDK in ihre eigenen Client-Anwendungen zu integrieren, um den Anmeldestatus der Benutzer, Berechtigungen und mehr zu verwalten. SDKs für alle von Logto unterstützten Programmiersprachen / Frameworks findest du [hier](/quick-starts). -Falls du das gewünschte SDK nicht findest, gibt es hier eine Konvention, der du folgen kannst, um das SDK für deine gewünschte Programmiersprache zu implementieren und so die Nutzung der Logto-Dienste zu erleichtern. +Falls du kein passendes SDK findest, gibt es hier eine Konvention, der du folgen kannst, um das SDK für deine gewünschte Programmiersprache zu implementieren und so die Nutzung der Logto-Dienste zu erleichtern. Diese Konvention besteht aus drei Hauptteilen: @@ -24,13 +24,13 @@ Diese Konvention besteht aus drei Hauptteilen: ## Verwandte Ressourcen \{#related-resources} - Implementierung eines einfachen clientseitigen OIDC SDK + Implementierung eines einfachen clientseitigen OIDC-SDKs - Entwicklung eines Node.js-basierten Framework-SDKs für Logto in wenigen Minuten + In wenigen Minuten ein Node.js-basiertes Framework-SDK für Logto erstellen - Entwicklung eines Web-SDKs für Logto in wenigen Minuten + In wenigen Minuten ein Web-SDK für Logto erstellen diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..6ceb4e9ed06 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: Service-to-service delegation +sidebar_label: Service-to-service delegation +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# Service-to-service delegation + +In einigen API-Architekturen erhält ein Backend-Service eine Anfrage von einem angemeldeten Benutzer und muss einen weiteren Backend-Service aufrufen, während die Identität des Benutzers erhalten bleibt. + +Zum Beispiel: + +```text +Benutzer -> API A -> API B +``` + +API B muss zwei Dinge wissen: + +1. Der Aufrufer ist ein vertrauenswürdiger Service, wie API A. +2. Die Operation wird für den ursprünglichen Benutzer ausgeführt. + +Nutze das Token Exchange Grant von Logto, um das Zugangstoken des Benutzers gegen ein neues Zugangstoken auszutauschen, dessen Zielgruppe die nachgelagerte API-Ressource ist. Dies folgt dem OAuth 2.0 Token Exchange Muster und vermeidet es, das ursprüngliche Benutzertoken an nachgelagerte Dienste weiterzuleiten. + +## Wann dieser Ablauf verwendet werden sollte \{#when-to-use-this-flow} + +Verwende Service-to-service delegation, wenn: + +- API A ein Backend-Service ist, der sich sicher beim Token-Endpunkt von Logto authentifizieren kann. +- API A ein von Logto ausgestelltes Benutzer-Zugangstoken erhält. +- API A API B im Namen desselben Benutzers aufrufen muss. +- API B ein Zugangstoken mit seiner eigenen API-Ressource als Zielgruppe validieren sollte. + +Verwende diesen Ablauf nicht für reinen Maschine-zu-Maschine-Zugriff ohne Benutzer. In diesem Fall verwende den [Client Credentials Flow](/quick-starts/m2m). Für Support-, Admin- oder Agenten-Szenarien, in denen ein Benutzer vorübergehend als ein anderer Benutzer agiert, verwende [Benutzermimikry](/developers/user-impersonation). + +## Wie es funktioniert \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as Benutzer + participant ApiA as API A + participant Logto as Logto Token-Endpunkt + participant ApiB as API B + + Benutzer->>ApiA: Authorization: Bearer Benutzer-Zugangstoken + Note over ApiA: Validiert das Benutzertoken für API A + + ApiA->>Logto: POST /oidc/token mit Token Exchange Grant + Note over ApiA,Logto: subject_token = Zugangstoken des Benutzers
resource = API B Ressourcenindikator + + Logto-->>ApiA: Zugangstoken für API B + ApiA->>ApiB: Authorization: Bearer ausgetauschtes Zugangstoken + Note over ApiB: Validiert Aussteller, Zielgruppe, Ablauf und Berechtigungen +``` + +Das ausgetauschte Zugangstoken repräsentiert den ursprünglichen Benutzer (`sub`) und ist an die nachgelagerte API-Ressource (`aud`) gebunden. Die nachgelagerte API kann auch den `client_id` Anspruch prüfen, um die Anwendung zu identifizieren, die den Austausch initiiert hat. + +## Voraussetzungen \{#prerequisites} + +1. Erstelle API-Ressourcen für die beteiligten Dienste. Siehe [Globale API-Ressourcen schützen](/authorization/global-api-resources). +2. Konfiguriere die Berechtigungen von API B und weise sie Benutzern über Rollen oder Organisationsrollen zu. +3. Verwende eine serverseitige Anwendung für API A, wie eine Maschine-zu-Maschine-App oder eine traditionelle Webanwendung, damit sie sich sicher mit einem App-Secret authentifizieren kann. +4. Aktiviere Token Exchange für die Anwendung von API A. + + + +## Zugangstoken für die nachgelagerte API anfordern \{#request-an-access-token-for-the-downstream-api} + +Wenn API A API B aufrufen muss, stelle eine Token Exchange Anfrage an den [Token-Endpunkt](/integrate-logto/application-data-structure#token-endpoint) von Logto. + +Für traditionelle Webanwendungen oder Maschine-zu-Maschine-Anwendungen mit App-Secret füge die Zugangsdaten in den `Authorization` Header ein: + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +Parameter: + +1. `grant_type`: Verwende `urn:ietf:params:oauth:grant-type:token-exchange`. +2. `subject_token`: Das ursprüngliche, von Logto ausgestellte Benutzer-Zugangstoken, das von API A empfangen wurde. +3. `subject_token_type`: Verwende `urn:ietf:params:oauth:token-type:access_token`. +4. `resource`: Der Ressourcenindikator der API B. +5. `scope`: Die nachgelagerten Berechtigungen, die API A für diesen delegierten Aufruf anfordert. Logto stellt nur die angeforderten Berechtigungen aus, die dem ursprünglichen Benutzer für diese Ressource gemäß den RBAC-Einstellungen zur Verfügung stehen. + +Logto gibt ein Zugangstoken für API B zurück: + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +Nach dem Dekodieren enthält das Zugangstoken Ansprüche wie: + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +Dann ruft API A API B mit dem ausgetauschten Token auf: + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## Token in API B validieren \{#validate-the-token-in-api-b} + +API B sollte das ausgetauschte Token wie jedes von Logto ausgestellte API-Ressourcen-Zugangstoken validieren: + +1. Überprüfe die Signatur mit den JWKs von Logto. +2. Prüfe den Aussteller (`iss`). +3. Prüfe, dass die Zielgruppe (`aud`) mit dem Ressourcenindikator von API B übereinstimmt. +4. Prüfe das Ablaufdatum (`exp`). +5. Prüfe die erforderlichen Berechtigungen. +6. Verwende `sub` als ursprüngliche Benutzer-ID. +7. Optional prüfe `client_id`, wenn nur bestimmte Upstream-Services delegierte Aufrufe durchführen dürfen. + +Siehe [Zugangstokens in API validieren](/authorization/validate-access-tokens) für Implementierungshinweise. + +## Verwandte Ressourcen \{#related-resources} + +Globale API-Ressourcen schützen + +Zugangstokens in API validieren + +Benutzermimikry diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 23ee0573096..de1540d5b59 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,44 +2,44 @@ id: signing-keys title: Signaturschlüssel sidebar_label: Signaturschlüssel -sidebar_position: 5 +sidebar_position: 6 --- # Signaturschlüssel Logto [OIDC-Signaturschlüssel](https://auth.wiki/signing-key), auch bekannt als „OIDC-Private Keys“ und „OIDC-Cookie-Keys“, sind die Signaturschlüssel, die zum Signieren von JWTs ([Zugangstokens (Access tokens)](https://auth.wiki/access-token) und [ID-Tokens (ID tokens)](https://auth.wiki/id-token)) sowie Browser-Cookies in Logto [Anmeldesitzungen](/sessions#what-is-a-logto-session) verwendet werden. Diese Signaturschlüssel werden beim Initialisieren der Logto-Datenbank ([Open-Source](/logto-oss)) oder beim Erstellen eines neuen Mandanten ([Cloud](/logto-cloud)) generiert und können über [CLI](/logto-oss/using-cli) (Open-Source), Management APIs oder die Console UI verwaltet werden. -Standardmäßig verwendet Logto den Elliptische-Kurven-Algorithmus (EC), um digitale Signaturen zu erzeugen. Da Benutzer jedoch häufig JWT-Signaturen überprüfen müssen und viele ältere Tools den EC-Algorithmus nicht unterstützen (sondern nur RSA), haben wir die Möglichkeit implementiert, private Schlüssel zu rotieren und den Signaturalgorithmus auszuwählen (einschließlich RSA und EC). Dies gewährleistet die Kompatibilität mit Diensten, die veraltete Signaturprüfungs-Tools verwenden. +Standardmäßig verwendet Logto den Elliptische-Kurven-Algorithmus (EC), um digitale Signaturen zu erzeugen. Da Benutzer jedoch häufig JWT-Signaturen verifizieren müssen und viele ältere Tools den EC-Algorithmus nicht unterstützen (sondern nur RSA), haben wir die Möglichkeit implementiert, private Schlüssel zu rotieren und den Signaturalgorithmus auszuwählen (einschließlich sowohl RSA als auch EC). Dies gewährleistet die Kompatibilität mit Diensten, die veraltete Signaturprüfungs-Tools verwenden. :::note -Theoretisch sollten Signaturschlüssel nicht kompromittiert werden und haben keine Ablaufzeit, sodass eine Rotation nicht zwingend erforderlich ist. Dennoch kann das regelmäßige Rotieren des Signaturschlüssels nach einer bestimmten Zeitspanne die Sicherheit erhöhen. +Theoretisch sollten Signaturschlüssel nicht kompromittiert werden und haben keine Ablaufzeit, was bedeutet, dass sie nicht rotiert werden müssen. Dennoch kann das regelmäßige Rotieren des Signaturschlüssels nach einer bestimmten Zeitspanne die Sicherheit erhöhen. ::: ## Wie funktioniert das? \{#how-it-works} - **OIDC-Private Key** - Beim Initialisieren einer Logto-Instanz wird automatisch ein Schlüsselpaar aus öffentlichem und privatem Schlüssel generiert und im zugrundeliegenden OIDC-Provider registriert. Wenn Logto ein neues JWT (Zugangstoken oder ID-Token) ausstellt, wird das Token mit dem privaten Schlüssel signiert. Gleichzeitig kann jede Client-Anwendung, die ein JWT erhält, den zugehörigen öffentlichen Schlüssel verwenden, um die Signatur des Tokens zu überprüfen und sicherzustellen, dass das Token nicht von Dritten manipuliert wurde. Der private Schlüssel ist auf dem Logto-Server geschützt. Der öffentliche Schlüssel hingegen ist, wie der Name schon sagt, für jeden zugänglich und kann über die `/oidc/jwks`-Schnittstelle des OIDC-Endpunkts abgerufen werden. Beim Generieren des privaten Schlüssels kann ein Signaturalgorithmus angegeben werden; Logto verwendet standardmäßig den EC-Algorithmus (Elliptische Kurve). Administratoren können den Standardalgorithmus durch Rotation der privaten Schlüssel auf RSA (Rivest-Shamir-Adleman) umstellen. + Beim Initialisieren einer Logto-Instanz wird automatisch ein Schlüsselpaar aus öffentlichem und privatem Schlüssel generiert und im zugrundeliegenden OIDC-Provider registriert. Wenn Logto ein neues JWT (Zugangstoken oder ID-Token) ausstellt, wird das Token mit dem privaten Schlüssel signiert. Gleichzeitig kann jede Client-Anwendung, die ein JWT erhält, den zugehörigen öffentlichen Schlüssel verwenden, um die Signatur des Tokens zu überprüfen und sicherzustellen, dass das Token nicht von Dritten manipuliert wurde. Der private Schlüssel ist auf dem Logto-Server geschützt. Der öffentliche Schlüssel hingegen ist, wie der Name schon sagt, für jeden zugänglich und kann über die `/oidc/jwks`-Schnittstelle des OIDC-Endpunkts abgerufen werden. Ein Signaturschlüssel-Algorithmus kann beim Generieren des privaten Schlüssels angegeben werden, wobei Logto standardmäßig den EC-Algorithmus (Elliptische Kurve) verwendet. Die Administratoren können den Standardalgorithmus durch Rotieren der privaten Schlüssel auf RSA (Rivest-Shamir-Adleman) umstellen. - **OIDC-Cookie-Key** - Wenn ein Benutzer einen Anmelde- oder Registrierungsprozess startet, wird auf dem Server eine „OIDC-Sitzung“ erstellt sowie eine Reihe von Browser-Cookies. Mit diesen Cookies kann der Browser die Logto Experience API nutzen, um im Namen des Benutzers verschiedene Interaktionen durchzuführen, wie Anmeldung, Registrierung und Passwortzurücksetzung. Im Gegensatz zu JWTs werden die Cookies jedoch nur von Logto OIDC selbst signiert und überprüft; asymmetrische Kryptografie ist hierfür nicht erforderlich. Daher gibt es keine zugehörigen öffentlichen Schlüssel für Cookie-Signaturschlüssel und auch keine asymmetrischen Verschlüsselungsalgorithmen. + Wenn ein Benutzer einen Anmelde- oder Registrierungsprozess startet, wird auf dem Server eine „OIDC-Sitzung“ erstellt sowie eine Reihe von Browser-Cookies. Mit diesen Cookies kann der Browser die Logto Experience API nutzen, um im Namen des Benutzers verschiedene Interaktionen durchzuführen, wie Anmeldung, Registrierung und Passwortzurücksetzung. Im Gegensatz zu JWTs werden die Cookies jedoch nur von Logto OIDC selbst signiert und überprüft, asymmetrische Kryptografie ist hierfür nicht erforderlich. Daher gibt es keine zugehörigen öffentlichen Schlüssel für Cookie-Signaturschlüssel und keine asymmetrischen Verschlüsselungsalgorithmen. ## Signaturschlüssel über die Console UI rotieren \{#rotate-signing-keys-from-console-ui} Logto bietet die Funktion „Signaturschlüssel-Rotation“, mit der du einen neuen OIDC-Private Key und Cookie Key in deinem Mandanten erstellen kannst. 1. Navigiere zu Console > Mandanteneinstellungen > OIDC-Konfigurationen. Dort kannst du sowohl OIDC-Private Keys als auch OIDC-Cookie-Keys verwalten. -2. Um den Signaturschlüssel zu rotieren, klicke auf die Schaltfläche „Private Keys rotieren“ oder „Cookie Keys rotieren“. Beim Rotieren der Private Keys kannst du den Signaturalgorithmus ändern. +2. Um den Signaturschlüssel zu rotieren, klicke auf die Schaltfläche „Private Keys rotieren“ oder „Cookie Keys rotieren“. Beim Rotieren der privaten Schlüssel hast du die Möglichkeit, den Signaturalgorithmus zu ändern. 3. Du findest dort eine Tabelle, die alle verwendeten Signaturschlüssel auflistet. Für OIDC-Private Keys kannst du den vorherigen Schlüssel löschen, aber nicht den aktuellen oder nächsten Schlüssel. Für OIDC-Cookie-Keys kannst du den vorherigen Schlüssel löschen, aber nicht den aktuellen Schlüssel. - | Status | Beschreibung | - | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | Next | Dieser Status wird für die gestaffelte Rotation von OIDC-Private Keys verwendet. Der Schlüssel wurde erstellt, aber Logto verwendet ihn erst nach Ablauf der Schonfrist zum Signieren neuer JWTs. | - | Current | Dieser Schlüssel wird aktuell von Logto zum Signieren neu ausgestellter JWTs oder Cookies verwendet. | - | Previous | Bezieht sich auf einen Schlüssel, der zuvor verwendet wurde, aber inzwischen rotiert wurde. Bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, bleiben gültig, bis sie ablaufen oder der Schlüssel gelöscht wird. | + | Status | Beschreibung | + | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | Next | Dieser Status wird für gestaffelte OIDC-Private-Key-Rotation verwendet. Der Schlüssel wurde erstellt, aber Logto verwendet ihn erst zum Signieren neuer JWTs, wenn die Schonfrist endet und der Schlüssel wirksam wird. | + | Current | Dieser Status zeigt an, dass dieser Schlüssel derzeit von Logto zum Signieren neu ausgestellter JWTs oder Cookies verwendet wird. | + | Previous | Bezieht sich auf einen Schlüssel, der zuvor verwendet wurde, aber rotiert wurde. Bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, bleiben gültig, bis sie ablaufen oder der Schlüssel gelöscht wird. | Bitte beachte, dass die Rotation die folgenden drei Aktionen umfasst: 1. **Erstellen eines neuen Signaturschlüssels**: Für OIDC-Private Keys kann Logto den neuen Schlüssel zunächst als „Next“ bereitstellen, sodass deine Anwendungen und APIs Zeit haben, den öffentlichen Schlüssel vom `/oidc/jwks`-Endpunkt zu aktualisieren, bevor der neue Schlüssel zum Signieren verwendet wird. -2. **Rotation des aktuellen Schlüssels**: Wenn die Rotation wirksam wird, wird der „Next“-Schlüssel zum „Current“ und der bisherige „Current“-Schlüssel zum „Previous“. Mit dem vorherigen Schlüssel signierte Tokens bleiben weiterhin gültig. +2. **Rotation des aktuellen Schlüssels**: Wenn die Rotation wirksam wird, wird der „Next“-Schlüssel zum „Current“ und der bisherige „Current“-Schlüssel wird zum „Previous“. Mit dem vorherigen Schlüssel signierte Tokens bleiben weiterhin gültig. 3. **Entfernen des ältesten vorherigen Schlüssels**: Logto behält maximal einen „Previous“-Private Key. Existiert bereits ein vorheriger Private Key, wenn der gestaffelte Schlüssel aktuell wird, wird der ältere vorherige Schlüssel entfernt. Für Logto Cloud tritt die Rotation des OIDC-Private Keys nach einer Schonfrist von 4 Stunden in Kraft. Während dieser Zeit wird der neue Schlüssel vorbereitet und über JWKS bereitgestellt, bevor Logto beginnt, neu ausgestellte JWTs damit zu signieren. In der Console-Tabelle zeigt die Spalte **Wirksam ab** an, wann ein gestaffelter „Next“-Schlüssel zum „Current“ wird. @@ -47,9 +47,9 @@ Für Logto Cloud tritt die Rotation des OIDC-Private Keys nach einer Schonfrist Für selbst gehostete OSS-Deployments beträgt die Standard-Schonfrist für die Rotation privater Schlüssel `0` Sekunden, was bedeutet, dass die Rotation sofort erfolgt. Um eine gestaffelte Rotation zu nutzen, setze die Umgebungsvariable `PRIVATE_KEY_ROTATION_GRACE_PERIOD` im Logto-Service oder übergebe einen expliziten Wert für `rotationGracePeriod` im Request-Body beim Aufruf des Management API-Endpunkts `POST /api/configs/oidc/private-keys/rotate`. :::warning -Vermeide es, Signaturschlüssel wiederholt zu rotieren, bevor die ausstehende Rotation wirksam wird, es sei denn, du möchtest den gestaffelten „Next“-Schlüssel absichtlich ersetzen. +Vermeide es, Signaturschlüssel wiederholt zu rotieren, bevor die ausstehende Rotation wirksam wird, es sei denn, du möchtest absichtlich den gestaffelten „Next“-Schlüssel ersetzen. -Das zu frühe Löschen des einzigen „Previous“-Schlüssels kann dazu führen, dass bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, ungültig werden. +Das zu frühe Löschen des einzigen „Previous“-Schlüssels kann bestehende JWTs oder Cookies, die mit diesem Schlüssel signiert wurden, ungültig machen. ::: ## Verwandte Ressourcen \{#related-resources} diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 0ed84542ab4..b1da46e9e19 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,14 +1,14 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhooks Logto [Webhook](https://auth.wiki/webhook) bieten Echtzeit-Benachrichtigungen für verschiedene Ereignisse, einschließlich Änderungen an Benutzerkonten, Rollen, Berechtigungen, Organisationen, Organisationsrollen, Organisationsberechtigungen und [Benutzerinteraktionen](/end-user-flows). -Wenn ein Ereignis ausgelöst wird, sendet Logto eine HTTP-Anfrage an die von dir angegebene Endpoint-URL, die detaillierte Informationen über das Ereignis enthält, wie Benutzer-ID, Benutzername, E-Mail und weitere relevante Details (für mehr Informationen über die im Payload und Header enthaltenen Daten siehe [Webhook-Anfrage](/developers/webhooks/webhooks-request)). Deine Anwendung kann diese Anfrage verarbeiten und individuelle Aktionen ausführen, wie z. B. das Versenden einer E-Mail oder das Aktualisieren von Daten in einer Datenbank. +Wenn ein Ereignis ausgelöst wird, sendet Logto eine HTTP-Anfrage an die von dir angegebene Endpoint-URL, die detaillierte Informationen über das Ereignis enthält, wie Benutzer-ID, Benutzername, E-Mail und weitere relevante Details (mehr zu den im Payload und Header enthaltenen Daten findest du unter [Webhook-Anfrage](/developers/webhooks/webhooks-request)). Deine Anwendung kann diese Anfrage verarbeiten und individuelle Aktionen ausführen, wie z. B. das Versenden einer E-Mail oder das Aktualisieren von Daten in einer Datenbank. -Wir fügen kontinuierlich weitere Ereignisse basierend auf den Bedürfnissen der Nutzer hinzu. Wenn du spezifische Anforderungen für dein Unternehmen hast, lass es uns bitte wissen. +Wir fügen kontinuierlich weitere Ereignisse basierend auf den Bedürfnissen der Nutzer hinzu. Wenn du spezielle Anforderungen für dein Unternehmen hast, lass es uns bitte wissen. ## Warum Webhook verwenden? \{#why-use-webhook} @@ -19,17 +19,17 @@ Hier sind einige Beispiele für häufige Webhook-Anwendungsfälle im CIAM-Bereic - **E-Mails versenden:** Konfiguriere einen Webhook, um eine Willkommens-E-Mail an neue Benutzer nach der Registrierung zu senden oder Administratoren zu benachrichtigen, wenn sich ein Benutzer von einem neuen Gerät oder Standort anmeldet. - **Benachrichtigungen senden:** Konfiguriere einen Webhook, um einen virtuellen Assistenten mit deinem CRM-System auszulösen, um bei der Anmeldung von Benutzern einen Echtzeit-Kundensupport zu bieten. - **Zusätzliche API-Aufrufe durchführen:** Konfiguriere einen Webhook, um den Benutzerzugang zu überprüfen, indem du deren E-Mail-Domain oder IP-Adresse prüfst und anschließend die Logto Management API verwendest, um entsprechende Rollen mit Ressourcenberechtigungen zuzuweisen. -- **Daten-Synchronisierung:** Konfiguriere Webhooks, um die Anwendung über Änderungen wie Kontosperrungen oder -löschungen auf dem Laufenden zu halten. +- **Daten-Synchronisation:** Konfiguriere einen Webhook, um die Anwendung über Änderungen wie Sperrungen oder Löschungen von Benutzerkonten auf dem Laufenden zu halten. - **Berichte generieren:** Richte einen Webhook ein, um Daten zur Benutzeranmeldeaktivität zu erhalten und diese zur Erstellung von Berichten über Benutzerengagement oder Nutzungsmuster zu nutzen. ## Begriffe \{#terms} -| Item | Beschreibung | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Event | Wenn eine bestimmte Aktion ausgeführt wird, löst sie ein Hook-Ereignis mit einem bestimmten Typ aus. Z. B. gibt Logto ein PostRegister-Hook-Ereignis aus, wenn der Benutzer den Anmeldeprozess abgeschlossen und ein neues Konto erstellt hat. | -| Hook | Eine einzelne oder eine Reihe von Aktionen, die an ein bestimmtes Ereignis angehängt werden. Die Aktion kann ein API-Aufruf, das Ausführen von Code-Snippets usw. sein. | -| Webhook | Ein Subtyp von Hook, der das Aufrufen einer API mit dem Ereignis-Payload bezeichnet. | -| Angenommen, ein Entwickler möchte eine Benachrichtigung senden, wenn sich ein Benutzer über ein neues Gerät anmeldet, kann der Entwickler einen Webhook hinzufügen, der seine Sicherheitsdienst-API für das PostSignIn-Ereignis aufruft. | +| Item | Beschreibung | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Event | Wenn eine bestimmte Aktion ausgeführt wird, löst sie ein Hook-Ereignis mit einem bestimmten Typ aus. Z. B. sendet Logto ein PostRegister-Hook-Ereignis, wenn der Benutzer den Anmeldeprozess abgeschlossen und ein neues Konto erstellt hat. | +| Hook | Eine einzelne oder eine Reihe von Aktionen, die an ein bestimmtes Ereignis angehängt werden. Die Aktion kann ein API-Aufruf, das Ausführen von Code-Snippets usw. sein. | +| Webhook | Ein Subtyp von Hook, der das Aufrufen einer API mit dem Ereignis-Payload bezeichnet. | +| Angenommen, ein Entwickler möchte eine Benachrichtigung senden, wenn sich ein Benutzer über ein neues Gerät anmeldet, kann der Entwickler einen Webhook hinzufügen, der seine Sicherheitsdienst-API zum PostSignIn-Ereignis aufruft. | Hier ist ein Beispiel für das Aktivieren von zwei Webhooks für das `PostSignIn`-Ereignis in Logto: @@ -67,7 +67,7 @@ graph LR -Obwohl synchrone Webhooks den Benutzeranmeldeprozess reibungsloser machen würden, unterstützen wir sie derzeit noch nicht (werden wir aber in Zukunft). Daher erfordern Szenarien, die auf synchronen Webhooks basieren, aktuell verschiedene Workarounds. Wenn du Fragen hast, zögere nicht, uns zu kontaktieren. +Obwohl synchrone Webhooks den Benutzeranmeldeprozess reibungsloser machen würden, unterstützen wir sie derzeit noch nicht (wir werden dies in Zukunft tun). Daher erfordern Szenarien, die auf synchronen Webhooks basieren, aktuell unterschiedliche Workarounds. Wenn du Fragen hast, zögere nicht, uns zu kontaktieren. @@ -89,7 +89,7 @@ Siehe [Benutzerberechtigungsänderung verwalten](/authorization/global-api-resou -Der Endpunkt, der Webhooks empfängt, sollte so schnell wie möglich eine 2xx-Antwort zurückgeben, um Logto mitzuteilen, dass der Webhook erfolgreich empfangen wurde. Da verschiedene Nutzer sehr unterschiedliche Verarbeitungslogiken für Webhooks haben, können übermäßig komplexe Aufgaben mehrere Sekunden dauern, was dazu führt, dass der Logto Webhook ein Timeout erhält. Die beste Praxis ist, eine eigene Ereigniswarteschlange zu pflegen; nach dem Empfang des Logto Webhooks wird das Ereignis in die Warteschlange eingefügt und eine 2xx-Antwort an Logto zurückgegeben. Dann kann dein eigener Worker die Aufgaben in der Warteschlange Schritt für Schritt abarbeiten. Wenn der Worker auf einen Fehler stößt, solltest du ihn auf deinem eigenen Server behandeln. +Der Endpunkt, der Webhooks empfängt, sollte so schnell wie möglich eine 2xx-Antwort zurückgeben, um Logto mitzuteilen, dass der Webhook erfolgreich empfangen wurde. Da verschiedene Nutzer sehr unterschiedliche Verarbeitungslogiken für Webhooks haben, können übermäßig komplexe Aufgaben mehrere Sekunden dauern, was dazu führt, dass der Logto Webhook ein Timeout erhält. Die beste Praxis ist, eine eigene Ereigniswarteschlange zu pflegen; nach dem Empfang des Logto Webhooks wird das Ereignis in die Warteschlange eingefügt und eine 2xx-Antwort an Logto zurückgegeben. Anschließend kann dein eigener Worker die Aufgaben in der Warteschlange Schritt für Schritt abarbeiten. Wenn der Worker auf einen Fehler stößt, solltest du diesen auf deinem eigenen Server behandeln. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index ccb4b658131..f3af8bc2e26 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -7,69 +7,69 @@ sidebar_position: 3 # Webhooks-Ereignisse -Dieser Leitfaden listet die verschiedenen Logto-Webhooks-Ereignisse auf und erklärt, wann jedes Ereignis auftritt. +Dieser Leitfaden listet die verschiedenen Logto Webhook-Ereignisse auf und erklärt, wann jedes Ereignis auftritt. ## Benutzerinteraktions-Hook-Ereignisse \{#user-interaction-hook-events} -| Ereignistyp | Beschreibung | -| ----------------- | ------------------------------------------------------------------------------------------------ | -| PostRegister | Ein Benutzer erstellt erfolgreich ein neues Konto über die UI-Oberfläche. | -| PostSignIn | Ein Benutzer meldet sich erfolgreich über die UI-Oberfläche an. | -| PostResetPassword | Das Passwort eines Benutzers wird erfolgreich über den "Passwort vergessen"-Fluss zurückgesetzt. | +| Ereignistyp | Beschreibung | +| ----------------- | ------------------------------------------------------------------------------------------------- | +| PostRegister | Ein Benutzer erstellt erfolgreich ein neues Konto über die UI-Oberfläche. | +| PostSignIn | Ein Benutzer meldet sich erfolgreich über die UI-Oberfläche an. | +| PostResetPassword | Das Passwort eines Benutzers wird erfolgreich über den „Passwort vergessen“-Ablauf zurückgesetzt. | ## Datenmutations-Hook-Ereignisse \{#data-mutation-hook-events} ### Benutzer \{#user} -| Ereignistyp | Beschreibung | -| ----------------------------- | ------------------------------------------------------------------------------------------ | -| User.Created | Ein neues Benutzerkonto wird erstellt. | -| User.Deleted | Ein Benutzerkonto wird gelöscht. | -| User.Data.Updated | Benutzerdaten werden aktualisiert, z. B. E-Mail, Avatar, custom.data, soziale Kennung usw. | -| User.SuspensionStatus.Updated | Der Sperrstatus eines Benutzers wird geändert (gesperrt oder reaktiviert). | +| Ereignistyp | Beschreibung | +| ----------------------------- | -------------------------------------------------------------------------------------------- | +| User.Created | Ein neues Benutzerkonto wird erstellt. | +| User.Deleted | Ein Benutzerkonto wird gelöscht. | +| User.Data.Updated | Benutzerdaten werden aktualisiert, z. B. E-Mail, Avatar, custom.data, Social-Identifier usw. | +| User.SuspensionStatus.Updated | Der Sperrstatus eines Benutzers wird geändert (gesperrt oder reaktiviert). | ### Rolle \{#role} -| Ereignistyp | Beschreibung | -| ------------------- | --------------------------------------------------------------------------------------------------- | -| Role.Created | Eine neue Rolle wird erstellt. | -| Role.Deleted | Eine Rolle wird gelöscht. | -| Role.Data.Updated | Die Daten einer Rolle werden aktualisiert, z. B. Rollenname, Beschreibung und Standardrollenstatus. | -| Role.Scopes.Updated | Berechtigungen, die einer Rolle zugewiesen sind, werden hinzugefügt oder entfernt. | +| Ereignistyp | Beschreibung | +| ------------------- | --------------------------------------------------------------------------------------------- | +| Role.Created | Eine neue Rolle wird erstellt. | +| Role.Deleted | Eine Rolle wird gelöscht. | +| Role.Data.Updated | Die Daten einer Rolle werden aktualisiert, z. B. Rollenname, Beschreibung und Standardstatus. | +| Role.Scopes.Updated | Berechtigungen, die einer Rolle zugewiesen sind, werden hinzugefügt oder entfernt. | -### Berechtigung (Scope) \{#permission-scope} +### Berechtigung (Berechtigung) \{#permission-scope} -| Ereignistyp | Beschreibung | -| ------------------ | -------------------------------------------------------------------------------------- | -| Scope.Created | Eine neue API-Berechtigung wird erstellt. | -| Scope.Deleted | Eine API-Berechtigung wird gelöscht. | -| Scope.Data.Updated | Die Daten einer API-Berechtigung werden aktualisiert, z. B. Berechtigungsbeschreibung. | +| Ereignistyp | Beschreibung | +| ------------------ | ------------------------------------------------------------------------- | +| Scope.Created | Eine neue API-Berechtigung wird erstellt. | +| Scope.Deleted | Eine API-Berechtigung wird gelöscht. | +| Scope.Data.Updated | Die Daten einer API-Berechtigung werden aktualisiert, z. B. Beschreibung. | ### Organisation \{#organization} -| Ereignistyp | Beschreibung | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | Eine neue Organisation wird erstellt. | -| Organization.Deleted | Eine Organisation wird gelöscht. | -| Organization.Data.Updated | Die Daten einer Organisation werden aktualisiert, z. B. Organisationsname, Beschreibung, custom.data usw. | -| Organization.Membership.Updated | Benutzer oder Anwendungen werden zu einer Organisation hinzugefügt oder daraus entfernt. Die Nutzlast enthält [Mitgliedschaftsdelta-Felder](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | +| Ereignistyp | Beschreibung | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | Eine neue Organisation wird erstellt. | +| Organization.Deleted | Eine Organisation wird gelöscht. | +| Organization.Data.Updated | Die Daten einer Organisation werden aktualisiert, z. B. Name, Beschreibung, custom.data usw. | +| Organization.Membership.Updated | Benutzer oder Anwendungen werden zu einer Organisation hinzugefügt oder entfernt. Die Nutzlast enthält [Mitgliedschafts-Delta-Felder](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | ### Organisationsrolle \{#organization-role} -| Ereignistyp | Beschreibung | -| ------------------------------- | ------------------------------------------------------------------------------------------------------- | -| OrganizationRole.Created | Eine neue Organisationsrolle wird erstellt. | -| OrganizationRole.Deleted | Eine Organisationsrolle wird gelöscht. | -| OrganizationRole.Data.Updated | Die Daten einer Organisationsrolle werden aktualisiert, z. B. Organisationsrollenname und Beschreibung. | -| OrganizationRole.Scopes.Updated | Berechtigungen, die einer Organisationsrolle zugewiesen sind, werden hinzugefügt oder entfernt. | +| Ereignistyp | Beschreibung | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| OrganizationRole.Created | Eine neue Organisationsrolle wird erstellt. | +| OrganizationRole.Deleted | Eine Organisationsrolle wird gelöscht. | +| OrganizationRole.Data.Updated | Die Daten einer Organisationsrolle werden aktualisiert, z. B. Name und Beschreibung der Organisationsrolle. | +| OrganizationRole.Scopes.Updated | Berechtigungen, die einer Organisationsrolle zugewiesen sind, werden hinzugefügt oder entfernt. | -### Organisationsberechtigung (Scope) \{#organization-permission-scope} +### Organisationsberechtigung (Berechtigung) \{#organization-permission-scope} -| Ereignistyp | Beschreibung | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | -| OrganizationScope.Created | Eine neue Organisationsberechtigung wird erstellt. | -| OrganizationScope.Deleted | Eine Organisationsberechtigung wird gelöscht. | -| OrganizationScope.Data.Updated | Die Daten einer Organisationsberechtigung werden aktualisiert, z. B. Organisationsberechtigungsbeschreibung. | +| Ereignistyp | Beschreibung | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- | +| OrganizationScope.Created | Eine neue Organisationsberechtigung wird erstellt. | +| OrganizationScope.Deleted | Eine Organisationsberechtigung wird gelöscht. | +| OrganizationScope.Data.Updated | Die Daten einer Organisationsberechtigung werden aktualisiert, z. B. Beschreibung der Organisationsberechtigung. | ### Management API ausgelöste Ereignisse \{#management-api-triggered-events} @@ -112,22 +112,23 @@ Dieser Leitfaden listet die verschiedenen Logto-Webhooks-Ereignisse auf und erkl ### Experience API ausgelöste Ereignisse \{#experience-api-triggered-events} -| Benutzerinteraktionsaktion | Ereignis | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| Benutzer-E-Mail/Telefon-Verknüpfung | User.Data.Updated | -| Benutzer-MFAs-Verknüpfung | User.Data.Updated | -| Benutzer-Soziale/SSO-Verknüpfung | User.Data.Updated | -| Benutzer-Passwort-Zurücksetzung | User.Data.Updated | -| Benutzerregistrierung | User.Created | -| Benutzer automatisch in eine Organisation bereitgestellt über [Just-in-Time-Bereitstellung](/organizations/just-in-time-provisioning) (übereinstimmende E-Mail-Domain oder Enterprise SSO Connector) | Organization.Membership.Updated | +| Benutzerinteraktionsaktion | Ereignis | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| Benutzer E-Mail/Telefon-Verknüpfung | User.Data.Updated | +| Benutzer MFA-Verknüpfung | User.Data.Updated | +| Benutzer Social/SSO-Verknüpfung | User.Data.Updated | +| Benutzer Passwort zurücksetzen | User.Data.Updated | +| Benutzerregistrierung | User.Created | +| Benutzer wird automatisch einer Organisation zugeordnet über [Just-in-Time-Bereitstellung](/organizations/just-in-time-provisioning) (passende E-Mail-Domain oder Enterprise SSO Connector) | Organization.Membership.Updated | ## Ausnahme-Hook-Ereignisse \{#exception-hook-events} ### Sicherheit \{#security} -| Ereignistyp | Beschreibung | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | Ein Benutzerkonto wird aufgrund aufeinanderfolgender fehlgeschlagener Identitätsüberprüfungsversuche gesperrt. Kann in den folgenden Flüssen ausgelöst werden:
  • Passwortüberprüfung fehlgeschlagen
  • Codeüberprüfung fehlgeschlagen
  • Einmal-Token-Überprüfung fehlgeschlagen
| +| Ereignistyp | Beschreibung | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Identifier.Lockout | Ein Benutzerkonto wird aufgrund aufeinanderfolgender fehlgeschlagener Identitätsüberprüfungsversuche gesperrt. Kann in folgenden Abläufen ausgelöst werden:
  • Passwortüberprüfung fehlgeschlagen
  • Codeüberprüfung fehlgeschlagen
  • Einmal-Token-Überprüfung fehlgeschlagen
| +| Message.RateLimited | Ein Endbenutzer überschreitet das [Sendelimit](/security/send-rate-limit) pro Empfänger für Verifizierungscodes. Wird nur auf den Endbenutzer-Sendepfaden (Experience API und Account API) ausgelöst, mit einer Nutzlast von `{ action, recipient }`. | ## FAQs \{#faqs} @@ -138,6 +139,6 @@ Dieser Leitfaden listet die verschiedenen Logto-Webhooks-Ereignisse auf und erkl -`PostRegister` wird ausgelöst, wenn ein Benutzer erfolgreich ein neues Konto über den Benutzeranmeldefluss erstellt; `User.Created` wird ausgelöst, wenn ein neues Benutzerkonto über die Management API erstellt wird. +`PostRegister` wird ausgelöst, wenn ein Benutzer erfolgreich ein neues Konto über den Benutzer-Registrierungsablauf erstellt; `User.Created` wird ausgelöst, wenn ein neues Benutzerkonto über die Management API erstellt wird. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/de/docusaurus-plugin-content-docs/current/security/README.mdx index 3d508687188..5c3795ed19c 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/security/README.mdx @@ -12,7 +12,7 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; Moderne Authentifizierungs-Sicherheit kämpft gegen Bedrohungen wie Phishing, Credential Stuffing, Brute-Force-Angriffe, Ransomware, DDoS bis hin zu KI-gesteuerten Angriffen. Der Schutz von Benutzeridentitäten ist entscheidend, um das Vertrauen in die Marke und die Einhaltung von Vorschriften zu gewährleisten. -Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist, diesen Risiken direkt entgegenzuwirken. Durch die Priorisierung proaktiver Bedrohungsprävention und Widerstandsfähigkeit stellen wir sicher, dass deine Systeme geschützt bleiben, ohne die Benutzerfreundlichkeit zu beeinträchtigen. Mit Logto ist Sicherheit kein nachträglicher Gedanke – sie ist das Fundament, das Unternehmen befähigt, in einer Ära zu gedeihen, in der sich Bedrohungen weiterentwickeln, aber die Verteidigung noch schneller. +Logto bietet ein robustes, sicheres Zugangsmanagement, das darauf ausgelegt ist, diesen Risiken direkt entgegenzuwirken. Durch die Priorisierung proaktiver Bedrohungsprävention und Widerstandsfähigkeit stellen wir sicher, dass deine Systeme geschützt bleiben, ohne die Benutzerfreundlichkeit zu beeinträchtigen. Mit Logto ist Sicherheit kein nachträglicher Gedanke – sie ist das Fundament, das Unternehmen befähigt, in einer Ära zu gedeihen, in der sich Bedrohungen weiterentwickeln, aber die Verteidigung noch schneller. ## Erweiterter Schutz einrichten \{#set-up-advanced-security-protection} @@ -23,7 +23,7 @@ Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist label: 'Passwortrichtlinie', href: '/security/password-policy', description: - 'Verbessere die Passwortanforderungen, um dich gegen Credential Stuffing und schwache Passwortangriffe zu verteidigen.', + 'Verbessere die Passwortanforderungen, um dich gegen Credential Stuffing und Angriffe mit schwachen Passwörtern zu verteidigen.', customProps: { icon: , }, @@ -58,12 +58,22 @@ Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist icon: , }, }, + { + type: 'link', + label: 'Send Rate Limit', + href: '/security/send-rate-limit', + description: + 'Begrenze die Anzahl der Verifizierungscodes und Nachrichten pro Empfänger, um Spam im Posteingang und Missbrauch durch SMS-Pumping zu verhindern.', + customProps: { + icon: , + }, + }, { type: 'link', label: 'Konto-Existenz verbergen', href: '/end-user-flows/sign-up-and-sign-in', description: - 'Verberge den Kontostatus, um Account-Enumeration-Angriffe zu blockieren und sensible Kontoinformationen nicht preiszugeben.', + 'Verberge den Kontostatus, um Account-Enumeration-Angriffe zu blockieren und die Offenlegung sensibler Kontoinformationen zu vermeiden.', customProps: { icon: , }, @@ -110,7 +120,7 @@ Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist label: 'Signierschlüssel rotieren', href: '/developers/signing-keys', description: - 'Rotiere regelmäßig die Signierschlüssel, um dich gegen Schlüssel-Leakage und Token-Fälschung zu schützen.', + 'Rotiere regelmäßig die Signierschlüssel, um dich gegen Schlüssel-Leaks und Token-Fälschungen zu schützen.', customProps: { icon: , }, @@ -120,7 +130,7 @@ Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist label: 'OIDC Back-Channel Logout', href: '/end-user-flows/sign-out#federated-sign-out-back-channel-logout', description: - 'Aktiviere zentrales Abmelden, um das Risiko von Session-Hijacking und unbefugtem Zugriff zu reduzieren.', + 'Aktiviere zentrales Logout, um das Risiko von Session-Hijacking und unbefugtem Zugriff zu reduzieren.', customProps: { icon: , }, @@ -130,7 +140,7 @@ Logto bietet ein robustes, sicheres Zugriffsmanagement, das darauf ausgelegt ist label: 'Registrierung nur auf Einladung', href: '/end-user-flows', description: - 'Beschränke Registrierungen ausschließlich auf eingeladene Benutzer, indem du E-Mail-Magic-Links für ein sicheres Onboarding verwendest.', + 'Beschränke die Registrierung auf eingeladene Benutzer, indem du E-Mail-Magic-Links für ein sicheres Onboarding verwendest.', customProps: { icon: , }, diff --git a/i18n/de/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/de/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..d27317b0ed3 --- /dev/null +++ b/i18n/de/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: Sende-Rate-Limit +sidebar_position: 5 +--- + +# Sende-Rate-Limitierung + +Logto wendet eine integrierte, empfängerbasierte Rate-Limitierung für ausgehende Verifizierungscodes und andere Nachrichten an, die per E-Mail und SMS versendet werden. Dies schützt deine Benutzer und deine Messaging-Anbieter vor Sende-Missbrauch – etwa wenn ein Angreifer das Postfach oder Telefon eines Opfers mit Codes zuspammt oder SMS-Traffic erzeugt, um deine Kosten in die Höhe zu treiben. + +Dieses Limit ist **verpflichtend und systemweit**: Es gilt für jeden Mandanten, unabhängig vom Tarif, und ist **nicht** mandantenspezifisch konfigurierbar. Es ist unabhängig von: + +- Den **[Identifier Lockout](/security/identifier-lockout)**- und **[CAPTCHA](/security/captcha)**-Richtlinien, die _fehlgeschlagene Verifizierungsversuche_ zur Verifizierungszeit drosseln, nicht aber den _Versand_ selbst. +- Dem globalen, mandantenweiten API-Rate-Limit (Fehlercode `request.rate_limited`), das das gesamte Anfragevolumen eines Mandanten begrenzt. + +## Funktionsweise \{#how-it-works} + +- **Empfängerbasiertes Limit**: Logto begrenzt, wie viele Nachrichten an denselben Empfänger (E-Mail-Adresse oder Telefonnummer) innerhalb eines kurzen, rollierenden Zeitfensters gesendet werden können. Standardmäßig sind bis zu **10 Sendungen pro Empfänger alle 10 Minuten** erlaubt. +- **Wo es gilt**: Alle serverseitigen Versandpfade, einschließlich Experience API- und Account API-Verifizierungscode-Versand (Anmeldung, Registrierung, Passwort zurücksetzen, MFA und Identifier-Bindung), Management API-Verifizierungscode-Versand, Organisations-Einladungsversand und -erneuerung sowie Account (`/me`)-Verifizierungscode-Versand. +- **Wenn das Limit überschritten wird**: Die Anfrage wird mit HTTP `429` und dem Fehlercode `request.message_rate_limited` abgelehnt – dies unterscheidet sich vom globalen Mandanten-Limiter (`request.rate_limited`) und der Verifizierungszeit-Sperre (`session.verification_blocked_too_many_attempts`), sodass du es gezielt in deiner Integration behandeln kannst. + +## Überwache rate-limitierte Sendungen mit einem Webhook \{#monitor-rate-limited-sends-with-a-webhook} + +Wenn ein **Endbenutzer** das empfängerbasierte Limit erreicht, löst Logto das `Message.RateLimited`-[Webhook-Ereignis](/developers/webhooks/webhooks-events#exception-hook-events) aus, sodass du auf Sende-Missbrauch reagieren oder diesen melden kannst. + +- **Wird ausgelöst für**: Nur Endbenutzer-Verifizierungscode-Versandpfade – die Experience API und Account API. Es wird **nicht** ausgelöst für First-Party- oder Admin-initiierte Sendungen (Management API-Verifizierungscodes, Organisationseinladungen oder `/me`). +- **Payload**: Der Hook-Kontext enthält die `action` (zum Beispiel `VerificationCodeSend`) und den `recipient` (die E-Mail-Adresse oder Telefonnummer). + +**Häufige Anwendungsfälle:** + +- Sende Sicherheitswarnungen an dein Team zur Überprüfung. +- Löse nachgelagerte Anti-Missbrauchs-Automatisierung für den betroffenen Empfänger aus. + +Navigiere zu Konsole > Webhooks, um dich zu registrieren, oder erstelle den Hook über die Management API. Für die detaillierte Ereignisstruktur und Konfiguration siehe [Webhooks](/developers/webhooks). + +## Unterdrückte Zustellung an unbekannte Empfänger \{#suppressed-delivery-to-unknown-recipients} + +Um die Konto-Aufzählung zu verhindern, wird – wenn die Anmeldung über einen Identifier deaktiviert ist – ein für eine E-Mail-Adresse oder Telefonnummer angeforderter Anmelde-Verifizierungscode, der **keinem Konto zugeordnet ist**, stillschweigend nicht zugestellt. Die API antwortet dabei genauso, wie sie es bei einem echten Versand tun würde. Ein Angreifer kann diese Antworten daher nicht nutzen, um herauszufinden, welche Adressen registriert sind. Die Zustellung an bestehende Benutzer ist davon nicht betroffen. Siehe auch [Konto-Existenz verbergen](/end-user-flows/sign-up-and-sign-in). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/README.mdx index dc825fd6b6d..9d0adb3d895 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -44,6 +44,15 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; icon: , } }, + { + type: 'link', + label: 'Delegación de servicio a servicio', + href: '/developers/service-to-service-delegation', + description: 'Intercambia un token de acceso de usuario por un token de acceso de API downstream para que los servicios backend puedan actuar en nombre del usuario actual.', + customProps: { + icon: , + } + }, ]} /> ``` @@ -66,7 +75,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhooks', href: '/developers/webhooks', - description: 'Los webhooks permiten notificaciones en tiempo real sobre información de usuario y actualizaciones de permisos a través de solicitudes HTTP, mejorando la comodidad y flexibilidad de la integración con Logto.', + description: 'Los webhooks permiten notificaciones en tiempo real sobre información de usuario y actualizaciones de permisos mediante solicitudes HTTP, mejorando la comodidad y flexibilidad de la integración con Logto.', customProps: { icon: , } diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index dafc402a2de..78806c4a413 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,10 +1,10 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Registros de auditoría -El registro de auditoría de Logto te permite monitorear fácilmente la actividad y los eventos de los usuarios. Proporciona una base sólida para diversos escenarios empresariales de gestión de usuarios y verificación de salud. +El registro de auditoría de Logto te permite monitorear fácilmente la actividad y los eventos de los usuarios. Proporciona una base sólida para diversos escenarios empresariales de gestión de usuarios y verificación del estado del sistema. ## Ver todos los registros \{#view-all-logs} @@ -26,7 +26,7 @@ Los registros de Logto ofrecen detalles completos, garantizando facilidad de acc - Marca de tiempo - User-agent -Al mantener estos registros de eventos, las organizaciones pueden detectar eficazmente posibles riesgos de seguridad y abordarlos rápidamente para evitar accesos no autorizados al sistema. +Al mantener estos registros de eventos, las organizaciones pueden detectar eficazmente posibles riesgos de seguridad y abordarlos rápidamente para prevenir accesos no autorizados al sistema. Consola > Gestión de usuarios. 2. Selecciona el usuario deseado y ve a la página de detalles. -3. Haz clic en "Registros del usuario". La tabla resultante mostrará exclusivamente los eventos de registro realizados y desencadenados por ese usuario en particular. +3. Haz clic en "Registros de usuario". La tabla resultante mostrará exclusivamente los eventos de registro realizados y desencadenados por ese usuario en particular. Estrategia de diseño -Convención principal de SDK +Convención principal del SDK Convención de SDK de plataforma diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..3adb38e5b76 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: Delegación de servicio a servicio +sidebar_label: Delegación de servicio a servicio +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# Delegación de servicio a servicio + +En algunas arquitecturas de API, un servicio backend recibe una solicitud de un usuario autenticado y necesita llamar a otro servicio backend mientras preserva la identidad del usuario. + +Por ejemplo: + +```text +Usuario -> API A -> API B +``` + +API B necesita saber dos cosas: + +1. El llamador es un servicio confiable, como API A. +2. La operación se está realizando para el usuario original. + +Utiliza la concesión de intercambio de tokens de Logto para intercambiar el token de acceso del usuario por un nuevo token de acceso cuyo público sea el recurso de API downstream. Esto sigue el patrón de intercambio de tokens de OAuth 2.0 y evita reenviar el token original del usuario a los servicios downstream. + +## Cuándo usar este flujo \{#when-to-use-this-flow} + +Utiliza la delegación de servicio a servicio cuando: + +- API A es un servicio backend que puede autenticarse de forma segura en el endpoint de token de Logto. +- API A recibe un token de acceso de usuario emitido por Logto. +- API A necesita llamar a API B en nombre del mismo usuario. +- API B debe validar un token de acceso con su propio recurso de API como audiencia. + +No utilices este flujo para acceso puramente máquina a máquina sin un usuario. En ese caso, utiliza el [flujo de credenciales de cliente](/quick-starts/m2m). Para escenarios de soporte, administración o agente donde un usuario actúa temporalmente como otro usuario, utiliza la [suplantación de usuario](/developers/user-impersonation). + +## Cómo funciona \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as Usuario + participant ApiA as API A + participant Logto as Endpoint de token de Logto + participant ApiB as API B + + Usuario->>ApiA: Authorization: Bearer token de acceso de usuario + Note over ApiA: Validar el token de usuario para API A + + ApiA->>Logto: POST /oidc/token con concesión de intercambio de tokens + Note over ApiA,Logto: subject_token = token de acceso del usuario
resource = indicador de recurso de API B + + Logto-->>ApiA: Token de acceso para API B + ApiA->>ApiB: Authorization: Bearer token de acceso intercambiado + Note over ApiB: Validar emisor, audiencia, expiración y alcances +``` + +El token de acceso intercambiado representa al usuario original (`sub`) y está vinculado al recurso de API downstream (`aud`). La API downstream también puede inspeccionar el reclamo `client_id` para identificar la aplicación que inició el intercambio. + +## Requisitos previos \{#prerequisites} + +1. Crea recursos de API para los servicios involucrados. Consulta [Proteger recursos de API globales](/authorization/global-api-resources). +2. Configura los permisos de API B y asígnalos a los usuarios a través de roles o roles de organización. +3. Utiliza una aplicación del lado del servidor para API A, como una aplicación máquina a máquina o una aplicación web tradicional, para que pueda autenticarse de forma segura con un secreto de aplicación. +4. Habilita el intercambio de tokens para la aplicación de API A. + + + +## Solicitar un token de acceso para la API downstream \{#request-an-access-token-for-the-downstream-api} + +Cuando API A necesita llamar a API B, realiza una solicitud de intercambio de tokens al [endpoint de token](/integrate-logto/application-data-structure#token-endpoint) de Logto. + +Para aplicaciones web tradicionales o aplicaciones máquina a máquina con un secreto de aplicación, incluye las credenciales en el encabezado `Authorization`: + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +Parámetros: + +1. `grant_type`: Usa `urn:ietf:params:oauth:grant-type:token-exchange`. +2. `subject_token`: El token de acceso de usuario emitido por Logto recibido por API A. +3. `subject_token_type`: Usa `urn:ietf:params:oauth:token-type:access_token`. +4. `resource`: El indicador de recurso de API de API B. +5. `scope`: Los permisos downstream que API A solicita para esta llamada delegada. Logto emite solo los alcances solicitados que están disponibles para el usuario original para este recurso según la configuración de RBAC. + +Logto devuelve un token de acceso para API B: + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +Al decodificarlo, el token de acceso incluye reclamos similares a: + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +Luego, API A llama a API B con el token intercambiado: + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## Validar el token en API B \{#validate-the-token-in-api-b} + +API B debe validar el token intercambiado igual que cualquier token de acceso de recurso de API emitido por Logto: + +1. Verifica la firma usando los JWKs de Logto. +2. Verifica el emisor (`iss`). +3. Verifica que la audiencia (`aud`) coincida con el indicador de recurso de API B. +4. Verifica la expiración (`exp`). +5. Verifica los alcances requeridos. +6. Usa `sub` como el ID de usuario original. +7. Opcionalmente verifica `client_id` si solo se permite que servicios upstream específicos realicen llamadas delegadas. + +Consulta [Validar tokens de acceso en API](/authorization/validate-access-tokens) para orientación sobre la implementación. + +## Recursos relacionados \{#related-resources} + +Proteger recursos de API globales + +Validar tokens de acceso en API + +Suplantación de usuario diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index e6f2560f462..bdfd135634a 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,23 +2,23 @@ id: signing-keys title: Claves de firma sidebar_label: Claves de firma -sidebar_position: 5 +sidebar_position: 6 --- # Claves de firma Las [claves de firma OIDC](https://auth.wiki/signing-key) de Logto, también conocidas como "claves privadas OIDC" y "claves de cookies OIDC", son las claves de firma utilizadas para firmar JWTs ([tokens de acceso (Access tokens)](https://auth.wiki/access-token) y [tokens de ID (ID tokens)](https://auth.wiki/id-token)) y cookies del navegador en las [sesiones de inicio de sesión (sign-in sessions)](/sessions#what-is-a-logto-session) de Logto. Estas claves de firma se generan al inicializar la base de datos de Logto ([código abierto](/logto-oss)) o al crear un nuevo tenant ([Cloud](/logto-cloud)) y pueden gestionarse a través de la [CLI](/logto-oss/using-cli) (código abierto), Management APIs o la interfaz de la Consola. -Por defecto, Logto utiliza el algoritmo de curva elíptica (EC) para generar firmas digitales. Sin embargo, considerando que los usuarios a menudo necesitan verificar firmas de JWT y muchas herramientas antiguas no admiten el algoritmo EC (solo admiten RSA), hemos implementado la funcionalidad para rotar claves privadas y permitir a los usuarios elegir el algoritmo de firma (incluyendo tanto RSA como EC). Esto garantiza la compatibilidad con servicios que utilizan herramientas de verificación de firmas obsoletas. +Por defecto, Logto utiliza el algoritmo de curva elíptica (EC) para generar firmas digitales. Sin embargo, considerando que los usuarios a menudo necesitan verificar firmas de JWT y muchas herramientas antiguas no admiten el algoritmo EC (solo admiten RSA), hemos implementado la funcionalidad para rotar claves privadas y permitir a los usuarios elegir el algoritmo de firma (incluyendo tanto RSA como EC). Esto garantiza la compatibilidad con servicios que utilizan herramientas de verificación de firmas desactualizadas. :::note -Teóricamente, las claves de firma no deberían filtrarse y no tienen tiempo de expiración, lo que significa que no es necesario rotarlas. Sin embargo, rotar periódicamente la clave de firma después de cierto tiempo puede mejorar la seguridad. +Teóricamente, las claves de firma no deberían filtrarse y no tienen un tiempo de expiración, lo que significa que no es necesario rotarlas. Sin embargo, rotar periódicamente la clave de firma después de cierto tiempo puede mejorar la seguridad. ::: ## ¿Cómo funciona? \{#how-it-works} - **Clave privada OIDC** - Al inicializar una instancia de Logto, se genera automáticamente un par de clave pública y clave privada, que se registran en el proveedor OIDC subyacente. Así, cuando Logto emite un nuevo JWT (token de acceso o token de ID), el token se firma con la clave privada. Mientras tanto, cualquier aplicación cliente que reciba un JWT puede usar la clave pública emparejada para verificar la firma del token, con el fin de asegurar que el token no ha sido manipulado por terceros. La clave privada está protegida en el servidor de Logto. La clave pública, como su nombre indica, es pública para todos y puede accederse a través de la interfaz `/oidc/jwks` del endpoint OIDC. Se puede especificar un algoritmo de clave de firma al generar la clave privada, y Logto utiliza el algoritmo EC (Curva Elíptica) por defecto. Los usuarios administradores pueden cambiar el algoritmo predeterminado a RSA (Rivest-Shamir-Adleman) rotando las claves privadas. + Al inicializar una instancia de Logto, se genera automáticamente un par de clave pública y clave privada, que se registran en el proveedor OIDC subyacente. Así, cuando Logto emite un nuevo JWT (token de acceso o token de ID), el token se firma con la clave privada. Mientras tanto, cualquier aplicación cliente que reciba un JWT puede usar la clave pública emparejada para verificar la firma del token, con el fin de asegurar que el token no haya sido manipulado por terceros. La clave privada está protegida en el servidor de Logto. La clave pública, como su nombre indica, es pública para todos y puede accederse a través de la interfaz `/oidc/jwks` del endpoint OIDC. Se puede especificar un algoritmo de clave de firma al generar la clave privada, y Logto utiliza el algoritmo EC (Curva Elíptica) por defecto. Los usuarios administradores pueden cambiar el algoritmo predeterminado a RSA (Rivest-Shamir-Adleman) rotando las claves privadas. - **Clave de cookie OIDC** Cuando el usuario inicia un flujo de inicio de sesión o registro, se crea una "sesión OIDC" en el servidor, así como un conjunto de cookies en el navegador. Con estas cookies, el navegador puede solicitar a la Experience API de Logto realizar una serie de interacciones en nombre del usuario, como iniciar sesión, registrarse y restablecer la contraseña. Sin embargo, a diferencia de los JWTs, las cookies solo son firmadas y verificadas por el propio servicio OIDC de Logto, no se requieren medidas de criptografía asimétrica. Por lo tanto, no tenemos claves públicas emparejadas para las claves de firma de cookies, ni algoritmos de cifrado asimétrico. @@ -26,28 +26,28 @@ Teóricamente, las claves de firma no deberían filtrarse y no tienen tiempo de Logto introduce la función de "Rotación de claves de firma", que te permite crear una nueva clave privada OIDC y una clave de cookie en tu tenant. -1. Navega a Consola > Configuración del tenant > Configuración OIDC. Desde allí, puedes gestionar tanto las claves privadas OIDC como las claves de cookies OIDC. -2. Para rotar la clave de firma, haz clic en el botón "Rotar claves privadas" o "Rotar claves de cookies". Al rotar las claves privadas, tienes la opción de cambiar el algoritmo de firma. +1. Navega a Consola > Configuración del tenant > Configuraciones OIDC. Desde allí, puedes gestionar tanto las claves privadas OIDC como las claves de cookies OIDC. +2. Para rotar la clave de firma, haz clic en el botón "Rotar claves privadas" o "Rotar claves de cookies". Al rotar claves privadas, tienes la opción de cambiar el algoritmo de firma. 3. Encontrarás una tabla que enumera todas las claves de firma en uso. Para las claves privadas OIDC, puedes eliminar la clave anterior, pero no puedes eliminar la clave actual ni la siguiente. Para las claves de cookies OIDC, puedes eliminar la clave anterior, pero no puedes eliminar la clave actual. | Estado | Descripción | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Siguiente (Next) | Este estado se utiliza para la rotación escalonada de la clave privada OIDC. La clave ha sido creada, pero Logto no la usará para firmar nuevos JWTs hasta que finalice el período de gracia y la clave se vuelva efectiva. | - | Actual (Current) | Indica que esta clave está siendo utilizada actualmente por Logto para firmar los JWTs o cookies recién emitidos. | - | Anterior (Previous) | Se refiere a una clave que se usó previamente pero que ha sido rotada. Los JWTs o cookies existentes firmados con esta clave siguen siendo válidos hasta que expiren o la clave sea eliminada. | + | Actual (Current) | Indica que esta clave es la que Logto utiliza actualmente para firmar los JWTs o cookies recién emitidos. | + | Anterior (Previous) | Se refiere a una clave que se usó anteriormente pero que ha sido rotada. Los JWTs o cookies existentes firmados con esta clave siguen siendo válidos hasta que expiren o la clave sea eliminada. | Recuerda que la rotación implica las siguientes tres acciones: -1. **Crear una nueva clave de firma**: Para las claves privadas OIDC, Logto puede preparar la nueva clave como "Siguiente" primero para que tus aplicaciones y APIs tengan tiempo de actualizar la clave pública desde el endpoint `/oidc/jwks` antes de que la nueva clave se utilice para firmar. +1. **Crear una nueva clave de firma**: Para las claves privadas OIDC, Logto puede preparar la nueva clave como "Siguiente" primero, para que tus aplicaciones y APIs tengan tiempo de actualizar la clave pública desde el endpoint `/oidc/jwks` antes de que la nueva clave se utilice para firmar. 2. **Rotar la clave actual**: Cuando la rotación se hace efectiva, la clave "Siguiente" pasa a ser "Actual", y la clave "Actual" existente pasa a ser "Anterior". Los tokens firmados con la clave anterior seguirán siendo válidos. 3. **Eliminar la clave anterior más antigua**: Logto mantiene como máximo una clave privada "Anterior". Si ya existe una clave privada anterior cuando la clave preparada pasa a ser actual, la clave anterior más antigua será eliminada. Para Logto Cloud, la rotación de la clave privada OIDC entra en vigor después de un período de gracia de 4 horas. Durante este período, la nueva clave se prepara y se expone a través de JWKS antes de que Logto comience a firmar los JWTs recién emitidos con ella. En la tabla de la Consola, la columna **Efectiva en** muestra cuándo una clave "Siguiente" preparada pasará a ser "Actual". -Para implementaciones OSS autogestionadas, el período de gracia predeterminado para la rotación de la clave privada es de `0` segundos, lo que significa que la rotación es inmediata. Para usar la rotación escalonada, establece la variable de entorno `PRIVATE_KEY_ROTATION_GRACE_PERIOD` en el servicio Logto, o pasa un valor explícito de `rotationGracePeriod` en el cuerpo de la solicitud al llamar al endpoint de la Management API `POST /api/configs/oidc/private-keys/rotate`. +Para implementaciones OSS autogestionadas, el período de gracia predeterminado para la rotación de la clave privada es de `0` segundos, lo que significa que la rotación es inmediata. Para usar la rotación escalonada, establece la variable de entorno `PRIVATE_KEY_ROTATION_GRACE_PERIOD` en el servicio Logto, o pasa un valor explícito de `rotationGracePeriod` en el cuerpo de la solicitud al llamar al endpoint de Management API `POST /api/configs/oidc/private-keys/rotate`. :::warning -Evita rotar las claves de firma repetidamente antes de que la rotación pendiente se haga efectiva, a menos que quieras reemplazar intencionalmente la clave "Siguiente" preparada. +Evita rotar las claves de firma repetidamente antes de que la rotación pendiente se haga efectiva, a menos que desees reemplazar intencionalmente la clave "Siguiente" preparada. Eliminar la única clave "Anterior" demasiado pronto puede invalidar los JWTs o cookies existentes que fueron firmados con esa clave. ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 6a2465679f0..a4274fd16a2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,35 +1,35 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhooks Logto [Webhook](https://auth.wiki/webhook) proporciona notificaciones en tiempo real para varios eventos, incluyendo cambios en cuentas de usuario, roles, permisos, organizaciones, roles de organización, permisos de organización e [interacciones de usuario](/end-user-flows). -Cuando se activa un evento, Logto envía una solicitud HTTP a la URL del endpoint que proporciones, conteniendo información detallada sobre el evento, como el ID de usuario, nombre de usuario, correo electrónico y otros detalles relevantes (para más información sobre los datos incluidos en el payload y el encabezado, consulta [Solicitud de Webhook](/developers/webhooks/webhooks-request)). Tu aplicación puede procesar esta solicitud y realizar acciones personalizadas, como enviar un correo electrónico o actualizar datos en la base de datos. +Cuando se activa un evento, Logto envía una solicitud HTTP a la URL del endpoint que proporciones, conteniendo información detallada sobre el evento, como el ID de usuario, nombre de usuario, correo electrónico y otros detalles relevantes (para más información sobre los datos incluidos en el payload y la cabecera, consulta [Solicitud de Webhook](/developers/webhooks/webhooks-request)). Tu aplicación puede procesar esta solicitud y tomar acciones personalizadas, como enviar un correo electrónico o actualizar datos en la base de datos. -Continuamente agregamos más eventos según las necesidades de los usuarios. Si tienes requisitos específicos para tu negocio, por favor háznoslo saber. +Continuamente añadimos más eventos según las necesidades de los usuarios. Si tienes requisitos específicos para tu negocio, por favor háznoslo saber. ## ¿Por qué usar Webhook? \{#why-use-webhook} -Los Webhooks ofrecen comunicación en tiempo real entre aplicaciones, eliminando la necesidad de sondeo y permitiendo actualizaciones de datos inmediatas. Simplifican la integración de aplicaciones y la automatización de flujos de trabajo sin código complejo ni APIs propietarias. +Los Webhooks ofrecen comunicación en tiempo real entre aplicaciones, eliminando la necesidad de sondeo y permitiendo actualizaciones inmediatas de datos. Simplifican la integración de aplicaciones y la automatización de flujos de trabajo sin código complejo ni APIs propietarias. Aquí tienes algunos ejemplos de casos de uso comunes de Webhook para CIAM: - **Enviar correos electrónicos:** Configura un Webhook para enviar un correo de bienvenida a los nuevos usuarios al registrarse o notificar a los administradores cuando un usuario inicia sesión desde un nuevo dispositivo o ubicación. -- **Enviar notificaciones:** Configura un Webhook para activar un asistente virtual con tu sistema CRM y proporcionar soporte al cliente en tiempo real cuando los usuarios se registran. -- **Realizar llamadas API adicionales**: Configura un Webhook para verificar el acceso del usuario comprobando su dominio de correo electrónico o dirección IP y luego utiliza la Management API de Logto para asignar los roles apropiados con permisos de recursos. +- **Enviar notificaciones:** Configura un Webhook para activar un asistente virtual con tu sistema CRM y proporcionar soporte al cliente en tiempo real cuando los usuarios se registren. +- **Realizar llamadas adicionales a API**: Configura un Webhook para verificar el acceso del usuario comprobando su dominio de correo electrónico o dirección IP y luego utiliza la Management API de Logto para asignar los roles apropiados con permisos de recursos. - **Sincronización de datos:** Configura Webhook para mantener la aplicación actualizada sobre cambios como suspensiones o eliminaciones de cuentas de usuario. - **Generar informes**: Configura un Webhook para recibir datos de actividad de inicio de sesión de usuarios y aprovecharlos para crear informes sobre el compromiso o patrones de uso de los usuarios. ## Términos \{#terms} -| Item | Description | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Evento (Event) | Cuando se realiza una acción específica, se activará un evento hook con un tipo específico. Por ejemplo, Logto emitirá un evento hook PostRegister cuando el usuario termine el proceso de registro y cree una nueva cuenta. | -| Hook | Una o varias acciones que se enganchan a un evento específico. La acción puede ser llamar a una API, ejecutar fragmentos de código, etc. | -| Webhook | Un subtipo de hook que indica llamar a una API con el payload del evento. | -| Por ejemplo, si un desarrollador quiere enviar una notificación cuando un usuario inicia sesión desde un nuevo dispositivo, puede añadir un webhook que llame a su API de servicio de seguridad al evento PostSignIn. | +| Item | Description | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Evento (Event) | Cuando se realiza una acción específica, se activará un evento hook con un tipo específico. Por ejemplo, Logto emitirá un evento hook PostRegister cuando el usuario termine el proceso de registro y cree una nueva cuenta. | +| Hook | Una o varias acciones que se enganchan a un evento específico. La acción puede ser llamar a una API, ejecutar fragmentos de código, etc. | +| Webhook | Un subtipo de hook que indica llamar a una API con el payload del evento. | +| Supón que un desarrollador quiere enviar una notificación cuando un usuario inicia sesión desde un nuevo dispositivo, el desarrollador puede añadir un webhook que llame a su API de servicio de seguridad al evento PostSignIn. | Aquí tienes un ejemplo de cómo habilitar dos webhooks para el evento `PostSignIn` en Logto: @@ -53,8 +53,8 @@ graph LR SF -->|Disparar| PS PS --> WH1 PS --> WH2 - WH1 --->|Llamada API POST| E1 - WH2 --->|Llamada API POST| E2 + WH1 --->|Llamada POST API| E1 + WH2 --->|Llamada POST API| E2 ``` @@ -85,11 +85,11 @@ Consulta la guía [Gestionar el cambio de permisos de usuario](/authorization/gl
-### ¿Cómo depurar el tiempo de espera del webhook? \{#how-to-debug-webhook-timeout} +### ¿Cómo depurar el timeout de un webhook? \{#how-to-debug-webhook-timeout} -Para el endpoint que recibe los Webhooks, debe devolver una respuesta 2xx lo más rápido posible para indicar a Logto que el Webhook se ha recibido correctamente. Dado que los diferentes usuarios tienen lógicas de procesamiento muy diferentes para los Webhooks, las tareas excesivamente complejas pueden tardar varios segundos, lo que provoca que el Webhook de Logto agote el tiempo de espera. La mejor práctica es mantener tu propia cola de eventos; al recibir el Webhook de Logto, inserta el evento en la cola y devuelve una respuesta 2xx a Logto. Luego, deja que tu propio worker procese las tareas en la cola paso a paso. Si el worker encuentra un error, manéjalo en tu propio servidor. +Para el endpoint que recibe los Webhooks, debe devolver una respuesta 2xx lo más rápido posible para indicar a Logto que el Webhook se ha recibido correctamente. Dado que los diferentes usuarios tienen lógicas de procesamiento muy diferentes para los Webhooks, las tareas excesivamente complejas pueden tardar varios segundos, provocando que el Webhook de Logto agote el tiempo de espera. La mejor práctica es mantener tu propia cola de eventos; al recibir el Webhook de Logto, inserta el evento en la cola y devuelve una respuesta 2xx a Logto. Luego, deja que tu propio worker procese las tareas en la cola paso a paso. Si el worker encuentra un error, manéjalo en tu propio servidor.
@@ -100,7 +100,7 @@ Para el endpoint que recibe los Webhooks, debe devolver una respuesta 2xx lo má -Sí, puedes obtener la dirección IP, agentes de usuario, etc. en el payload del Webhook. Si necesitas información que actualmente no está soportada, puedes crear solicitudes de características en los issues de GitHub o contactarnos. +Sí, puedes obtener la dirección IP, user agents, etc. en el payload del Webhook. Si necesitas información que actualmente no está soportada, puedes crear solicitudes de características en los issues de GitHub, o contactarnos. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index d44feb0ac3f..925a4fd40a8 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -9,13 +9,13 @@ sidebar_position: 3 Esta guía enumera los diferentes eventos de webhook de Logto y explica cuándo ocurre cada evento. -## Eventos de hook de interacción del usuario \{#user-interaction-hook-events} +## Eventos de hook de interacción de usuario \{#user-interaction-hook-events} -| Tipo de evento | Descripción | -| ----------------- | ---------------------------------------------------------------------------------------------------- | -| PostRegister | Un usuario crea exitosamente una nueva cuenta a través de la interfaz de usuario. | -| PostSignIn | Un usuario inicia sesión exitosamente a través de la interfaz de usuario. | -| PostResetPassword | La contraseña de un usuario se restablece exitosamente a través del flujo de "Olvidé mi contraseña". | +| Tipo de evento | Descripción | +| ----------------- | --------------------------------------------------------------------------------------------------- | +| PostRegister | Un usuario crea exitosamente una nueva cuenta a través de la interfaz de usuario. | +| PostSignIn | Un usuario inicia sesión exitosamente a través de la interfaz de usuario. | +| PostResetPassword | La contraseña de un usuario se restablece exitosamente mediante el flujo de "Olvidé mi contraseña". | ## Eventos de hook de mutación de datos \{#data-mutation-hook-events} @@ -35,24 +35,24 @@ Esta guía enumera los diferentes eventos de webhook de Logto y explica cuándo | Role.Created | Se crea un nuevo rol. | | Role.Deleted | Se elimina un rol. | | Role.Data.Updated | Se actualizan los datos de un rol, por ejemplo, nombre del rol, descripción y estado de rol predeterminado. | -| Role.Scopes.Updated | Se añaden o eliminan permisos asignados a un rol. | +| Role.Scopes.Updated | Se agregan o eliminan permisos asignados a un rol. | ### Permiso (Alcance) \{#permission-scope} -| Tipo de evento | Descripción | -| ------------------ | ----------------------------------------------------------------------------------- | -| Scope.Created | Se crea un nuevo permiso de API. | -| Scope.Deleted | Se elimina un permiso de API. | -| Scope.Data.Updated | Se actualizan los datos de un permiso de API, por ejemplo, descripción del permiso. | +| Tipo de evento | Descripción | +| ------------------ | -------------------------------------------------------------------------------------- | +| Scope.Created | Se crea un nuevo permiso de API. | +| Scope.Deleted | Se elimina un permiso de API. | +| Scope.Data.Updated | Se actualizan los datos de un permiso de API, por ejemplo, la descripción del permiso. | ### Organización \{#organization} -| Tipo de evento | Descripción | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | Se crea una nueva organización. | -| Organization.Deleted | Se elimina una organización. | -| Organization.Data.Updated | Se actualizan los datos de una organización, por ejemplo, nombre de la organización, descripción, custom.data, etc. | -| Organization.Membership.Updated | Se añaden o eliminan usuarios o aplicaciones de una organización. La carga útil incluye [campos delta de membresía](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | +| Tipo de evento | Descripción | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | Se crea una nueva organización. | +| Organization.Deleted | Se elimina una organización. | +| Organization.Data.Updated | Se actualizan los datos de una organización, por ejemplo, nombre de la organización, descripción, custom.data, etc. | +| Organization.Membership.Updated | Se agregan o eliminan usuarios o aplicaciones de una organización. El payload incluye [campos delta de membresía](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | ### Rol de organización \{#organization-role} @@ -61,15 +61,15 @@ Esta guía enumera los diferentes eventos de webhook de Logto y explica cuándo | OrganizationRole.Created | Se crea un nuevo rol de organización. | | OrganizationRole.Deleted | Se elimina un rol de organización. | | OrganizationRole.Data.Updated | Se actualizan los datos de un rol de organización, por ejemplo, nombre y descripción del rol de organización. | -| OrganizationRole.Scopes.Updated | Se añaden o eliminan permisos asignados a un rol de organización. | +| OrganizationRole.Scopes.Updated | Se agregan o eliminan permisos asignados a un rol de organización. | ### Permiso de organización (alcance) \{#organization-permission-scope} -| Tipo de evento | Descripción | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | -| OrganizationScope.Created | Se crea un nuevo permiso de organización. | -| OrganizationScope.Deleted | Se elimina un permiso de organización. | -| OrganizationScope.Data.Updated | Se actualizan los datos de un permiso de organización, por ejemplo, descripción del permiso de organización. | +| Tipo de evento | Descripción | +| ------------------------------ | ----------------------------------------------------------------------------------------------- | +| OrganizationScope.Created | Se crea un nuevo permiso de organización. | +| OrganizationScope.Deleted | Se elimina un permiso de organización. | +| OrganizationScope.Data.Updated | Se actualizan los datos de un permiso de organización, por ejemplo, la descripción del permiso. | ### Eventos desencadenados por Management API \{#management-api-triggered-events} @@ -112,22 +112,23 @@ Esta guía enumera los diferentes eventos de webhook de Logto y explica cuándo ### Eventos desencadenados por Experience API \{#experience-api-triggered-events} -| Acción de interacción del usuario | Evento | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| Enlace de correo electrónico / teléfono del usuario | User.Data.Updated | -| Enlace de MFA del usuario | User.Data.Updated | -| Enlace social / SSO del usuario | User.Data.Updated | -| Restablecimiento de contraseña del usuario | User.Data.Updated | -| Registro de usuario | User.Created | -| Usuario aprovisionado automáticamente en una organización a través de [aprovisionamiento Just-in-Time](/organizations/just-in-time-provisioning) (coincidencia de dominio de correo electrónico o conector SSO empresarial) | Organization.Membership.Updated | +| Acción de interacción de usuario | Evento | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| Enlace de correo electrónico / teléfono del usuario | User.Data.Updated | +| Enlace de MFA del usuario | User.Data.Updated | +| Enlace social / SSO del usuario | User.Data.Updated | +| Restablecimiento de contraseña del usuario | User.Data.Updated | +| Registro de usuario | User.Created | +| Usuario aprovisionado automáticamente en una organización mediante [aprovisionamiento Just-in-Time](/organizations/just-in-time-provisioning) (dominio de correo coincidente o conector SSO empresarial) | Organization.Membership.Updated | ## Eventos de hook de excepción \{#exception-hook-events} ### Seguridad \{#security} -| Tipo de evento | Descripción | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | Una cuenta de usuario se bloquea debido a intentos consecutivos fallidos de verificación de identidad. Puede desencadenarse en los siguientes flujos:
  • Fallo en la verificación de contraseña
  • Fallo en la verificación de código
  • Fallo en la verificación de token de un solo uso
| +| Tipo de evento | Descripción | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identifier.Lockout | Una cuenta de usuario se bloquea debido a intentos consecutivos fallidos de verificación de identidad. Puede desencadenarse en los siguientes flujos:
  • Fallo en la verificación de contraseña
  • Fallo en la verificación de código
  • Fallo en la verificación de token de un solo uso
| +| Message.RateLimited | Un usuario final excede el [límite de envío por destinatario](/security/send-rate-limit) para los códigos de verificación. Solo se activa en las rutas de envío para el usuario final (Experience API y Account API), con un payload de `{ action, recipient }`. | ## Preguntas frecuentes \{#faqs} @@ -138,6 +139,6 @@ Esta guía enumera los diferentes eventos de webhook de Logto y explica cuándo -`PostRegister` se desencadena cuando un usuario crea exitosamente una nueva cuenta a través del flujo de registro de usuario; `User.Created` se desencadena cuando se crea una nueva cuenta de usuario a través de la Management API. +`PostRegister` se activa cuando un usuario crea exitosamente una nueva cuenta mediante el flujo de registro de usuario; `User.Created` se activa cuando se crea una nueva cuenta de usuario a través de Management API. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/es/docusaurus-plugin-content-docs/current/security/README.mdx index e36025a81b3..790788c37a2 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/es/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # Seguridad -La seguridad moderna de la autenticación combate amenazas que van desde phishing, relleno de credenciales, ataques de fuerza bruta, ransomware, DDoS, hasta ataques impulsados por IA. Proteger las identidades de los usuarios es fundamental para salvaguardar la confianza en la marca y el cumplimiento normativo. +La seguridad moderna de la autenticación combate amenazas que van desde phishing, credential stuffing, ataques de fuerza bruta, ransomware, DDoS, hasta ataques impulsados por IA. Proteger las identidades de los usuarios es fundamental para salvaguardar la confianza en la marca y el cumplimiento normativo. -Logto ofrece una gestión de acceso segura y robusta diseñada para contrarrestar estos riesgos de manera directa. Al priorizar la prevención proactiva de amenazas y la resiliencia, aseguramos que tus sistemas permanezcan protegidos sin comprometer la usabilidad. Con Logto, la seguridad no es una ocurrencia tardía: es la base, empoderando a las empresas para prosperar en una era donde las amenazas evolucionan, pero las defensas evolucionan aún más rápido. +Logto ofrece una gestión de acceso segura y robusta diseñada para contrarrestar estos riesgos de manera directa. Al priorizar la prevención proactiva de amenazas y la resiliencia, aseguramos que tus sistemas permanezcan protegidos sin comprometer la usabilidad. Con Logto, la seguridad no es una idea secundaria: es la base, empoderando a las empresas para prosperar en una era donde las amenazas evolucionan, pero las defensas evolucionan aún más rápido. ## Configura protección de seguridad avanzada \{#set-up-advanced-security-protection} @@ -23,7 +23,7 @@ Logto ofrece una gestión de acceso segura y robusta diseñada para contrarresta label: 'Política de contraseñas', href: '/security/password-policy', description: - 'Mejora los requisitos de contraseña para defenderte contra ataques de relleno de credenciales y contraseñas débiles.', + 'Mejora los requisitos de contraseña para defenderte contra ataques de credential stuffing y contraseñas débiles.', customProps: { icon: , }, @@ -58,6 +58,16 @@ Logto ofrece una gestión de acceso segura y robusta diseñada para contrarresta icon: , }, }, + { + type: 'link', + label: 'Límite de envío', + href: '/security/send-rate-limit', + description: + 'Limita el envío de códigos de verificación y mensajes por destinatario para evitar el spam en la bandeja de entrada y el abuso de SMS pumping.', + customProps: { + icon: , + }, + }, { type: 'link', label: 'Ocultar existencia de cuenta', diff --git a/i18n/es/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/es/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..2fcb48b8b51 --- /dev/null +++ b/i18n/es/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: Límite de envío +sidebar_position: 5 +--- + +# Limitación de la tasa de envío + +Logto aplica un límite de tasa incorporado, por destinatario, a los códigos de verificación salientes y otros mensajes enviados por correo electrónico y SMS. Esto protege a tus usuarios y a tus proveedores de mensajería contra el abuso de envíos—como un atacante que envía spam a la bandeja de entrada o teléfono de una víctima con códigos, o que incrementa el tráfico de SMS para inflar tus costos. + +Este límite es **obligatorio y a nivel del sistema**: se aplica a cada inquilino sin importar el plan y **no** es configurable por el inquilino. Es independiente de: + +- Las políticas de **[bloqueo de identificador](/security/identifier-lockout)** y **[CAPTCHA](/security/captcha)**, que limitan _intentos de verificación fallidos_ en el momento de la verificación y no el acto de _enviar_. +- El límite global de tasa de API por inquilino (código de error `request.rate_limited`), que limita el volumen total de solicitudes a través de un inquilino. + +## Cómo funciona \{#how-it-works} + +- **Límite por destinatario**: Logto limita cuántos mensajes se pueden enviar al mismo destinatario (dirección de correo electrónico o número de teléfono) dentro de una ventana de tiempo corta y deslizante. Por defecto, esto permite hasta **10 envíos por destinatario cada 10 minutos**. +- **Dónde se aplica**: todos los caminos de envío del lado del servidor, incluyendo envíos de códigos de verificación de Experience API y Account API (inicio de sesión, registro, restablecimiento de contraseña, MFA y vinculación de identificador), envíos de códigos de verificación de Management API, envío y reenvío de invitaciones de organización, y envíos de códigos de verificación de Account (`/me`). +- **Cuando se excede el límite**: la solicitud es rechazada con HTTP `429` y el código de error `request.message_rate_limited`—diferente del limitador global del inquilino (`request.rate_limited`) y del bloqueo en tiempo de verificación (`session.verification_blocked_too_many_attempts`), para que puedas manejarlo específicamente en tu integración. + +## Monitorea los envíos limitados con un webhook \{#monitor-rate-limited-sends-with-a-webhook} + +Cuando un **usuario final** alcanza el límite por destinatario, Logto dispara el evento de webhook `Message.RateLimited` [evento de webhook](/developers/webhooks/webhooks-events#exception-hook-events), para que puedas alertar o responder ante abuso de envíos. + +- **Se dispara para**: solo los caminos de envío de códigos de verificación para usuarios finales—Experience API y Account API. **No** se dispara para envíos iniciados por primera parte o administrador (códigos de verificación de Management API, invitaciones de organización o `/me`). +- **Payload**: el contexto del hook incluye la `action` (por ejemplo, `VerificationCodeSend`) y el `recipient` (la dirección de correo electrónico o número de teléfono). + +**Casos de uso comunes:** + +- Enviar alertas de seguridad a tu equipo para su revisión. +- Disparar automatizaciones anti-abuso para el destinatario afectado. + +Navega a Consola > Webhooks para suscribirte, o crea el hook a través de la Management API. Para la estructura detallada del evento y la configuración, consulta [Webhooks](/developers/webhooks). + +## Entrega suprimida a destinatarios desconocidos \{#suppressed-delivery-to-unknown-recipients} + +Para prevenir la enumeración de cuentas, cuando el registro mediante un identificador está deshabilitado, un código de verificación de inicio de sesión solicitado para una dirección de correo electrónico o número de teléfono que **no pertenece a ninguna cuenta** no se entrega silenciosamente, y la API responde igual que lo haría para un envío real. Por lo tanto, un atacante no puede usar estas respuestas para saber qué direcciones están registradas. La entrega a usuarios existentes no se ve afectada. Consulta también [Ocultar existencia de cuenta](/end-user-flows/sign-up-and-sign-in). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/README.mdx index 18d9e264af9..d55d8349888 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -21,7 +21,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Jeton d’accès personnalisé', href: '/developers/custom-token-claims', - description: 'Utilisez des scripts personnalisés pour attacher des revendications supplémentaires aux jetons d’accès (access tokens), permettant l’ABAC ou le rejet de l’émission du jeton.', + description: 'Utilisez des scripts personnalisés pour ajouter des revendications supplémentaires aux jetons d’accès (access tokens), permettant l’ABAC ou le rejet de l’émission du jeton.', customProps: { icon: , } @@ -44,11 +44,20 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; icon: , } }, + { + type: 'link', + label: 'Délégation service à service', + href: '/developers/service-to-service-delegation', + description: 'Échangez un jeton d’accès utilisateur contre un jeton d’accès API en aval afin que les services backend puissent agir pour l’utilisateur actuel.', + customProps: { + icon: , + } + }, ]} /> ``` -## Généralités pour les développeurs \{#generics-for-developers} +## Fonctionnalités génériques pour les développeurs \{#generics-for-developers} ```mdx-code-block , } @@ -66,7 +75,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhooks', href: '/developers/webhooks', - description: 'Les Webhooks prennent en charge les notifications en temps réel concernant les informations utilisateur et les mises à jour de permissions via des requêtes HTTP, améliorant la commodité et la flexibilité de l’intégration Logto.', + description: 'Les webhooks prennent en charge les notifications en temps réel concernant les informations utilisateur et les mises à jour de permissions via des requêtes HTTP, améliorant la commodité et la flexibilité de l’intégration Logto.', customProps: { icon: , } @@ -84,7 +93,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Convention SDK', href: '/developers/', - description: 'Présente les structures de données, les objectifs et les méthodes du SDK, permettant aux utilisateurs de personnaliser le SDK pour s’adapter à divers scénarios métier.', + description: 'Présente les structures de données, les objectifs et les méthodes dans le SDK, permettant aux utilisateurs de personnaliser le SDK pour s’adapter à divers scénarios métier.', customProps: { icon: , } diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index 432af9c1696..89f3e379ec4 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,17 +1,17 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Journaux d’audit -Le journal d’audit de Logto vous permet de surveiller facilement l’activité des utilisateurs et les événements. Il constitue une base solide pour divers scénarios métier de gestion des utilisateurs et de vérification de l’état de santé. +Le journal d’audit de Logto vous permet de surveiller facilement l’activité des utilisateurs et les événements. Il constitue une base solide pour divers scénarios métier de gestion des utilisateurs et de vérification de la santé du système. ## Afficher tous les journaux \{#view-all-logs} Accédez à Console > Journaux d’audit. Logto capture et organise les événements d’authentification dans un tableau. Il enregistre le nom de l’événement, l’utilisateur, l’application et l’horodatage. Vous pouvez affiner les résultats en filtrant selon le nom de l’événement et le nom de l’application. En cliquant sur un événement spécifique, vous obtiendrez des détails supplémentaires. :::warning -Les journaux d’audit ne contiennent que les journaux survenant lors du processus d’authentification utilisateur, les opérations de Management API ne sont pas enregistrées. +Les journaux d’audit ne contiennent que les journaux générés lors du processus d’authentification utilisateur, les opérations de Management API ne sont pas enregistrées. ::: ## Capturer l’activité utilisateur au niveau du tenant \{#capture-user-activity-at-the-tenant-level} @@ -35,13 +35,13 @@ En conservant ces enregistrements d’événements, les organisations peuvent d ## Effectuer une analyse détaillée au niveau de l’utilisateur \{#perform-a-detailed-analysis-at-the-user-level} -Les administrateurs peuvent effectuer une analyse détaillée des journaux associés à des utilisateurs spécifiques, facilitant ainsi des enquêtes approfondies sur des événements particuliers. Le processus de navigation est simple et convivial. +Les administrateurs peuvent effectuer une analyse détaillée des journaux associés à des utilisateurs spécifiques, facilitant des enquêtes approfondies sur des événements particuliers. Le processus de navigation est simple et convivial. Pour accéder aux journaux spécifiques à un utilisateur, suivez ces étapes : 1. Accédez à Console > Gestion des utilisateurs. 2. Sélectionnez l’utilisateur souhaité et accédez à la page de détails. -3. Cliquez sur "Journaux utilisateur". Le tableau affichera exclusivement les événements de journal réalisés et déclenchés par cet utilisateur en particulier. +3. Cliquez sur « Journaux utilisateur ». Le tableau affichera exclusivement les événements de journal réalisés et déclenchés par cet utilisateur en particulier. API A -> API B +``` + +API B doit connaître deux choses : + +1. L’appelant est un service de confiance, tel que API A. +2. L’opération est effectuée pour l’utilisateur d’origine. + +Utilisez la délégation d’échange de jeton de Logto pour échanger le jeton d’accès de l’utilisateur contre un nouveau jeton d’accès dont l’audience est la ressource API en aval. Cela suit le modèle d’échange de jeton OAuth 2.0 et évite de transmettre le jeton utilisateur d’origine aux services en aval. + +## Quand utiliser ce flux \{#when-to-use-this-flow} + +Utilisez la délégation service à service lorsque : + +- API A est un service backend qui peut s’authentifier de manière sécurisée auprès du point de terminaison de jeton de Logto. +- API A reçoit un jeton d’accès utilisateur émis par Logto. +- API A doit appeler API B au nom du même utilisateur. +- API B doit valider un jeton d’accès avec sa propre ressource API comme audience. + +N’utilisez pas ce flux pour un accès purement machine à machine sans utilisateur. Dans ce cas, utilisez le [flux client credentials](/quick-starts/m2m). Pour les scénarios de support, d’administration ou d’agent où un utilisateur agit temporairement en tant qu’un autre utilisateur, utilisez [usurpation d’identité utilisateur](/developers/user-impersonation). + +## Fonctionnement \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as Utilisateur + participant ApiA as API A + participant Logto as Point de terminaison de jeton Logto + participant ApiB as API B + + User->>ApiA: Authorization: Bearer jeton d’accès utilisateur + Note over ApiA: Valider le jeton utilisateur pour API A + + ApiA->>Logto: POST /oidc/token avec délégation d’échange de jeton + Note over ApiA,Logto: subject_token = jeton d’accès de l’utilisateur
resource = indicateur de ressource API B + + Logto-->>ApiA: Jeton d’accès pour API B + ApiA->>ApiB: Authorization: Bearer jeton d’accès échangé + Note over ApiB: Valider émetteur, audience, expiration et portées +``` + +Le jeton d’accès échangé représente l’utilisateur d’origine (`sub`) et est lié à la ressource API en aval (`aud`). L’API en aval peut également inspecter la revendication `client_id` pour identifier l’application qui a initié l’échange. + +## Prérequis \{#prerequisites} + +1. Créez des ressources API pour les services concernés. Voir [Protéger les ressources API globales](/authorization/global-api-resources). +2. Configurez les permissions d’API B et assignez-les aux utilisateurs via des rôles ou des rôles d’organisation. +3. Utilisez une application côté serveur pour API A, telle qu’une application machine à machine ou une application web traditionnelle, afin qu’elle puisse s’authentifier de manière sécurisée avec un secret d’application. +4. Activez l’échange de jeton pour l’application d’API A. + + + +## Demander un jeton d’accès pour l’API en aval \{#request-an-access-token-for-the-downstream-api} + +Lorsque API A doit appeler API B, effectuez une demande d’échange de jeton au [point de terminaison de jeton](/integrate-logto/application-data-structure#token-endpoint) de Logto. + +Pour les applications web traditionnelles ou les applications machine à machine avec un secret d’application, incluez les identifiants dans l’en-tête `Authorization` : + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +Paramètres : + +1. `grant_type` : Utilisez `urn:ietf:params:oauth:grant-type:token-exchange`. +2. `subject_token` : Le jeton d’accès utilisateur émis par Logto et reçu par API A. +3. `subject_token_type` : Utilisez `urn:ietf:params:oauth:token-type:access_token`. +4. `resource` : L’indicateur de ressource API de API B. +5. `scope` : Les permissions en aval qu’API A demande pour cet appel délégué. Logto n’émet que les portées demandées qui sont disponibles pour l’utilisateur d’origine pour cette ressource selon les paramètres RBAC. + +Logto retourne un jeton d’accès pour API B : + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +Une fois décodé, le jeton d’accès inclut des revendications similaires à : + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +API A appelle ensuite API B avec le jeton échangé : + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## Valider le jeton dans API B \{#validate-the-token-in-api-b} + +API B doit valider le jeton échangé comme tout jeton d’accès de ressource API émis par Logto : + +1. Vérifiez la signature à l’aide des JWKs de Logto. +2. Vérifiez l’émetteur (`iss`). +3. Vérifiez que l’audience (`aud`) correspond à l’indicateur de ressource d’API B. +4. Vérifiez l’expiration (`exp`). +5. Vérifiez les portées requises. +6. Utilisez `sub` comme identifiant utilisateur d’origine. +7. Vérifiez éventuellement `client_id` si seuls certains services en amont sont autorisés à effectuer des appels délégués. + +Voir [Valider les jetons d’accès dans l’API](/authorization/validate-access-tokens) pour des conseils d’implémentation. + +## Ressources associées \{#related-resources} + +Protéger les ressources API globales + +Valider les jetons d’accès dans l’API + +Usurpation d’identité utilisateur diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 05e0022184e..10e65380502 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,12 +2,12 @@ id: signing-keys title: Clés de signature sidebar_label: Clés de signature -sidebar_position: 5 +sidebar_position: 6 --- # Clés de signature -Les [clés de signature OIDC](https://auth.wiki/signing-key) de Logto, également appelées "clés privées OIDC" et "clés de cookie OIDC", sont les clés utilisées pour signer les JWT ([jetons d’accès (Access tokens)](https://auth.wiki/access-token) et [jetons d’identifiant (ID tokens)](https://auth.wiki/id-token)) ainsi que les cookies de navigateur dans les [sessions de connexion](/sessions#what-is-a-logto-session) Logto. Ces clés de signature sont générées lors de l'initialisation de la base de données Logto ([open-source](/logto-oss)) ou lors de la création d'un nouveau tenant ([Cloud](/logto-cloud)) et peuvent être gérées via le [CLI](/logto-oss/using-cli) (open-source), les Management APIs ou l'interface Console UI. +Les [clés de signature OIDC](https://auth.wiki/signing-key) de Logto, également appelées "clés privées OIDC" et "clés de cookie OIDC", sont les clés utilisées pour signer les JWT ([jetons d’accès (Access tokens)](https://auth.wiki/access-token) et [jetons d’identifiant (ID tokens)](https://auth.wiki/id-token)) ainsi que les cookies de navigateur dans les [sessions de connexion](/sessions#what-is-a-logto-session) Logto. Ces clés de signature sont générées lors de l'initialisation de la base de données Logto ([open-source](/logto-oss)) ou lors de la création d'un nouveau tenant ([Cloud](/logto-cloud)) et peuvent être gérées via le [CLI](/logto-oss/using-cli) (open-source), les Management APIs ou l'interface Console. Par défaut, Logto utilise l'algorithme à courbe elliptique (EC) pour générer les signatures numériques. Cependant, étant donné que les utilisateurs doivent souvent vérifier les signatures JWT et que de nombreux anciens outils ne prennent pas en charge l'algorithme EC (ne supportant que RSA), nous avons implémenté la fonctionnalité de rotation des clés privées et permis aux utilisateurs de choisir l'algorithme de signature (y compris RSA et EC). Cela garantit la compatibilité avec les services utilisant des outils de vérification de signature obsolètes. @@ -18,36 +18,36 @@ Théoriquement, les clés de signature ne devraient pas être divulguées et n'o ## Comment ça fonctionne ? \{#how-it-works} - **Clé privée OIDC** - Lors de l'initialisation d'une instance Logto, une paire de clé publique et clé privée est automatiquement générée et enregistrée dans le fournisseur OIDC sous-jacent. Ainsi, lorsque Logto émet un nouveau JWT (jeton d’accès ou jeton d’identifiant), le jeton est signé avec la clé privée. Pendant ce temps, toute application cliente qui reçoit un JWT peut utiliser la clé publique associée pour vérifier la signature du jeton, afin de s'assurer que le jeton n'a pas été altéré par un tiers. La clé privée est protégée sur le serveur Logto. La clé publique, comme son nom l'indique, est publique et accessible via l'interface `/oidc/jwks` du point de terminaison OIDC. Un algorithme de clé de signature peut être spécifié lors de la génération de la clé privée, et Logto utilise par défaut l'algorithme EC (Elliptic Curve). Les administrateurs peuvent changer l'algorithme par défaut en RSA (Rivest-Shamir-Adleman) en effectuant une rotation des clés privées. + Lors de l'initialisation d'une instance Logto, une paire de clé publique et clé privée est automatiquement générée et enregistrée dans le fournisseur OIDC sous-jacent. Ainsi, lorsque Logto émet un nouveau JWT (jeton d’accès ou jeton d’identifiant), le jeton est signé avec la clé privée. Pendant ce temps, toute application cliente qui reçoit un JWT peut utiliser la clé publique associée pour vérifier la signature du jeton, afin de s'assurer que le jeton n'a pas été altéré par un tiers. La clé privée est protégée sur le serveur Logto. La clé publique, comme son nom l'indique, est accessible à tous et peut être consultée via l'interface `/oidc/jwks` du point de terminaison OIDC. Un algorithme de clé de signature peut être spécifié lors de la génération de la clé privée, et Logto utilise par défaut l'algorithme EC (Elliptic Curve). Les administrateurs peuvent changer l'algorithme par défaut pour RSA (Rivest-Shamir-Adleman) en effectuant une rotation des clés privées. - **Clé de cookie OIDC** - Lorsqu'un utilisateur initie un flux de connexion ou d'inscription, une "session OIDC" est créée sur le serveur, ainsi qu'un ensemble de cookies de navigateur. Avec ces cookies, le navigateur peut demander à l’Experience API Logto d’effectuer une série d’interactions au nom de l’utilisateur, telles que la connexion, l’inscription et la réinitialisation du mot de passe. Cependant, contrairement aux JWT, les cookies sont uniquement signés et vérifiés par le service OIDC Logto lui-même, des mesures de cryptographie asymétrique ne sont pas requises. Ainsi, nous n'avons pas de clés publiques associées pour les clés de signature de cookie, ni d'algorithmes de chiffrement asymétrique. + Lorsqu'un utilisateur initie un flux de connexion ou d'inscription, une "session OIDC" est créée sur le serveur, ainsi qu'un ensemble de cookies de navigateur. Grâce à ces cookies, le navigateur peut demander à l'Experience API Logto d'effectuer une série d'interactions au nom de l'utilisateur, telles que la connexion, l'inscription et la réinitialisation du mot de passe. Cependant, contrairement aux JWT, les cookies sont uniquement signés et vérifiés par le service OIDC Logto lui-même, des mesures de cryptographie asymétrique ne sont pas nécessaires. Ainsi, il n'existe pas de clés publiques associées pour les clés de signature de cookie, ni d'algorithmes de chiffrement asymétrique. -## Rotation des clés de signature depuis la Console UI \{#rotate-signing-keys-from-console-ui} +## Faire tourner les clés de signature depuis l’interface Console \{#rotate-signing-keys-from-console-ui} Logto introduit une fonctionnalité de "Rotation des clés de signature", qui vous permet de créer une nouvelle clé privée OIDC et une clé de cookie dans votre tenant. -1. Accédez à Console > Paramètres du tenant > Configurations OIDC. À partir de là, vous pouvez gérer à la fois les clés privées OIDC et les clés de cookie OIDC. +1. Rendez-vous sur Console > Paramètres du tenant > Configurations OIDC. À partir de là, vous pouvez gérer à la fois les clés privées OIDC et les clés de cookie OIDC. 2. Pour faire tourner la clé de signature, cliquez sur le bouton "Faire tourner les clés privées" ou "Faire tourner les clés de cookie". Lors de la rotation des clés privées, vous avez la possibilité de changer l'algorithme de signature. -3. Vous trouverez un tableau qui liste toutes les clés de signature utilisées. Pour les clés privées OIDC, vous pouvez supprimer la clé précédente, mais vous ne pouvez pas supprimer la clé actuelle ou la clé suivante. Pour les clés de cookie OIDC, vous pouvez supprimer la clé précédente, mais pas la clé actuelle. +3. Vous trouverez un tableau qui liste toutes les clés de signature utilisées. Pour les clés privées OIDC, vous pouvez supprimer l'ancienne clé, mais vous ne pouvez pas supprimer la clé actuelle ou la clé suivante. Pour les clés de cookie OIDC, vous pouvez supprimer l'ancienne clé, mais pas la clé actuelle. | Statut | Description | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Suivante | Ce statut est utilisé pour la rotation planifiée des clés privées OIDC. La clé a été créée, mais Logto ne l'utilisera pas pour signer de nouveaux JWT tant que la période de grâce n'est pas terminée et que la clé devient effective. | - | Actuelle | Cela indique que cette clé est actuellement utilisée par Logto pour signer les nouveaux JWT ou cookies émis. | + | Actuelle | Cela indique que cette clé est actuellement utilisée par Logto pour signer les nouveaux JWT ou cookies. | | Précédente | Il s'agit d'une clé qui était utilisée précédemment mais qui a été remplacée. Les JWT ou cookies existants signés avec cette clé restent valides jusqu'à leur expiration ou la suppression de la clé. | Veuillez noter que la rotation implique les trois actions suivantes : 1. **Création d'une nouvelle clé de signature** : Pour les clés privées OIDC, Logto peut d'abord préparer la nouvelle clé en tant que "Suivante" afin que vos applications et APIs aient le temps de rafraîchir la clé publique depuis le point de terminaison `/oidc/jwks` avant que la nouvelle clé ne soit utilisée pour la signature. 2. **Rotation de la clé actuelle** : Lorsque la rotation devient effective, la clé "Suivante" devient "Actuelle", et la clé "Actuelle" existante devient "Précédente". Les jetons signés avec la clé précédente resteront valides. -3. **Suppression de la plus ancienne clé précédente** : Logto conserve au maximum une seule clé privée "Précédente". Si une clé privée précédente existe déjà lorsque la clé planifiée devient actuelle, l'ancienne clé précédente sera supprimée. +3. **Suppression de la plus ancienne clé précédente** : Logto conserve au maximum une seule clé privée "Précédente". Si une clé privée précédente existe déjà lorsque la clé préparée devient actuelle, l'ancienne clé précédente sera supprimée. Pour Logto Cloud, la rotation des clés privées OIDC prend effet après une période de grâce de 4 heures. Pendant cette période, la nouvelle clé est préparée et exposée via JWKS avant que Logto ne commence à signer les nouveaux JWT avec celle-ci. Dans le tableau de la Console, la colonne **Effective à** indique quand une clé "Suivante" deviendra "Actuelle". Pour les déploiements OSS auto-hébergés, la période de grâce par défaut pour la rotation des clés privées est de `0` secondes, ce qui signifie que la rotation est immédiate. Pour utiliser une rotation planifiée, définissez la variable d'environnement `PRIVATE_KEY_ROTATION_GRACE_PERIOD` sur le service Logto, ou passez une valeur explicite `rotationGracePeriod` dans le corps de la requête lors de l'appel à l'endpoint Management API `POST /api/configs/oidc/private-keys/rotate`. :::warning -Évitez de faire tourner les clés de signature à plusieurs reprises avant que la rotation en attente ne devienne effective, sauf si vous souhaitez intentionnellement remplacer la clé "Suivante" planifiée. +Évitez de faire tourner les clés de signature à plusieurs reprises avant que la rotation en attente ne devienne effective, sauf si vous souhaitez intentionnellement remplacer la clé "Suivante" préparée. Supprimer trop tôt la seule clé "Précédente" peut invalider les JWT ou cookies existants qui ont été signés avec cette clé. ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 3c9f18e388c..602fa13b32b 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,14 +1,14 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhooks Les [Webhooks](https://auth.wiki/webhook) Logto fournissent des notifications en temps réel pour divers événements, notamment les modifications des comptes utilisateurs, des rôles, des permissions, des organisations, des rôles d'organisation, des permissions d'organisation et des [interactions utilisateur](/end-user-flows). -Lorsqu'un événement est déclenché, Logto envoie une requête HTTP à l'URL de point de terminaison que vous fournissez, contenant des informations détaillées sur l'événement, telles que l'ID utilisateur, le nom d'utilisateur, l'e-mail et d'autres détails pertinents (pour en savoir plus sur les données incluses dans la charge utile et l'en-tête, consultez [Requête Webhook](/developers/webhooks/webhooks-request)). Votre application peut traiter cette requête et effectuer des actions personnalisées, comme envoyer un e-mail ou mettre à jour des données dans la base de données. +Lorsqu'un événement est déclenché, Logto envoie une requête HTTP à l'URL de point de terminaison que vous fournissez, contenant des informations détaillées sur l'événement, telles que l'ID utilisateur, le nom d'utilisateur, l'e-mail et d'autres détails pertinents (pour plus d'informations sur les données incluses dans la charge utile et l'en-tête, consultez [Requête Webhook](/developers/webhooks/webhooks-request)). Votre application peut traiter cette requête et effectuer des actions personnalisées, comme envoyer un e-mail ou mettre à jour des données dans une base de données. -Nous ajoutons continuellement de nouveaux événements en fonction des besoins des utilisateurs. Si vous avez des exigences spécifiques pour votre entreprise, n'hésitez pas à nous en faire part. +Nous ajoutons continuellement de nouveaux événements en fonction des besoins des utilisateurs. Si vous avez des besoins spécifiques pour votre entreprise, n'hésitez pas à nous en faire part. ## Pourquoi utiliser un Webhook ? \{#why-use-webhook} @@ -18,7 +18,7 @@ Voici quelques exemples d'utilisations courantes des Webhooks pour le CIAM : - **Envoyer des e-mails :** Configurez un Webhook pour envoyer un e-mail de bienvenue aux nouveaux utilisateurs lors de l'inscription ou pour notifier les administrateurs lorsqu'un utilisateur se connecte depuis un nouvel appareil ou une nouvelle localisation. - **Envoyer des notifications :** Configurez un Webhook pour déclencher un assistant virtuel avec votre système CRM afin de fournir une assistance client en temps réel lors de l'inscription des utilisateurs. -- **Effectuer des appels API supplémentaires** : Configurez un Webhook pour vérifier l'accès utilisateur en contrôlant leur domaine e-mail ou leur adresse IP, puis utilisez la Management API Logto pour attribuer les rôles appropriés avec les permissions de ressource. +- **Effectuer des appels API supplémentaires** : Configurez un Webhook pour vérifier l'accès utilisateur en contrôlant leur domaine e-mail ou adresse IP, puis utilisez la Management API Logto pour attribuer les rôles appropriés avec les permissions de ressource. - **Synchronisation des données :** Configurez un Webhook pour tenir l'application informée des changements tels que la suspension ou la suppression de comptes utilisateurs. - **Générer des rapports :** Configurez un Webhook pour recevoir les données d'activité de connexion des utilisateurs et les exploiter pour créer des rapports sur l'engagement ou les habitudes d'utilisation. @@ -26,9 +26,9 @@ Voici quelques exemples d'utilisations courantes des Webhooks pour le CIAM : | Élément | Description | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Événement (Event) | Lorsqu'une action spécifique est effectuée, elle déclenche un événement hook d'un type spécifique. Par exemple, Logto émettra un événement hook PostRegister lorsque l'utilisateur termine le processus d'inscription et crée un nouveau compte. | -| Hook | Une ou plusieurs actions qui s'accrochent à un événement spécifique. L'action peut consister à appeler une API, exécuter des extraits de code, etc. | -| Webhook | Un sous-type de hook qui consiste à appeler une API avec la charge utile de l'événement. | +| Événement | Lorsqu'une action spécifique est effectuée, elle déclenche un événement hook d'un type spécifique. Par exemple, Logto émettra un événement hook PostRegister lorsque l'utilisateur termine le processus d'inscription et crée un nouveau compte. | +| Hook | Une ou plusieurs actions qui s'accrochent à un événement spécifique. L'action peut être un appel d'API, l'exécution de fragments de code, etc. | +| Webhook | Un sous-type de hook qui indique l'appel d'une API avec la charge utile de l'événement. | | Supposons qu'un développeur souhaite envoyer une notification lorsqu'un utilisateur se connecte via un nouvel appareil, il peut ajouter un webhook qui appelle l'API de son service de sécurité à l'événement PostSignIn. | Voici un exemple d'activation de deux webhooks pour l'événement `PostSignIn` dans Logto : @@ -38,8 +38,8 @@ graph LR subgraph Logto SF(Connexion terminée) PS(Post connexion) - WH2(Webhook 2) - WH1(Webhook 1) + WH2(Web hook 2) + WH1(Web hook 1) end subgraph Service 2 @@ -78,7 +78,7 @@ Bien que les webhooks synchrones rendraient le flux de connexion utilisateur plu -Consultez le guide [Gérer le changement de permission utilisateur](/authorization/global-api-resources/#optional-handle-user-permission-change). +Voir le guide [Gérer le changement de permission utilisateur](/authorization/global-api-resources/#optional-handle-user-permission-change). @@ -89,7 +89,7 @@ Consultez le guide [Gérer le changement de permission utilisateur](/authorizati -Pour le point de terminaison recevant les Webhooks, il doit retourner une réponse 2xx aussi rapidement que possible pour indiquer à Logto que le Webhook a bien été reçu. Comme chaque utilisateur a une logique de traitement des Webhooks très différente, des tâches trop complexes peuvent prendre plusieurs secondes, provoquant un timeout du Webhook Logto. La meilleure pratique consiste à maintenir votre propre file d'événements : dès réception du Webhook Logto, insérez l'événement dans la file et retournez une réponse 2xx à Logto. Ensuite, laissez votre propre worker traiter les tâches dans la file étape par étape. Si le worker rencontre une erreur, gérez-la sur votre propre serveur. +Pour le point de terminaison recevant les Webhooks, il doit retourner une réponse 2xx aussi rapidement que possible pour indiquer à Logto que le Webhook a bien été reçu. Étant donné que les utilisateurs ont des logiques de traitement très différentes pour les Webhooks, des tâches excessivement complexes peuvent prendre plusieurs secondes, entraînant un timeout du Webhook Logto. La meilleure pratique consiste à maintenir votre propre file d'attente d'événements ; dès réception du Webhook Logto, insérez l'événement dans la file d'attente et retournez une réponse 2xx à Logto. Ensuite, laissez votre propre worker traiter les tâches dans la file d'attente étape par étape. Si le worker rencontre une erreur, gérez-la sur votre propre serveur. @@ -100,7 +100,7 @@ Pour le point de terminaison recevant les Webhooks, il doit retourner une répon -Oui, vous pouvez obtenir l'adresse IP, les agents utilisateurs, etc. dans la charge utile du Webhook. Si vous avez besoin d'informations qui ne sont pas encore prises en charge, vous pouvez créer une demande de fonctionnalité sur les issues GitHub, ou nous contacter. +Oui, vous pouvez obtenir l'adresse IP, les user agents, etc. dans la charge utile du Webhook. Si vous avez besoin d'informations qui ne sont pas encore prises en charge, vous pouvez créer une demande de fonctionnalité sur GitHub issues, ou nous contacter. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index 73094c4b106..56c1aa25d23 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -7,7 +7,7 @@ sidebar_position: 3 # Événements Webhooks -Ce guide répertorie les différents événements de webhook Logto et explique quand chaque événement se produit. +Ce guide liste les différents événements webhook de Logto et explique quand chaque événement se produit. ## Événements de hook d'interaction utilisateur \{#user-interaction-hook-events} @@ -21,57 +21,57 @@ Ce guide répertorie les différents événements de webhook Logto et explique q ### Utilisateur \{#user} -| Type d'événement | Description | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| User.Created | Un nouveau compte utilisateur est créé. | -| User.Deleted | Un compte utilisateur est supprimé. | -| User.Data.Updated | Les données du profil utilisateur sont mises à jour, par exemple, email, avatar, custom.data, identifiant social, etc. | -| User.SuspensionStatus.Updated | Le statut de suspension de l'utilisateur est modifié (suspendu ou réactivé). | +| Type d'événement | Description | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | +| User.Created | Un nouveau compte utilisateur est créé. | +| User.Deleted | Un compte utilisateur est supprimé. | +| User.Data.Updated | Les données du profil utilisateur sont mises à jour, par exemple : e-mail, avatar, custom.data, identifiant social, etc. | +| User.SuspensionStatus.Updated | Le statut de suspension de l'utilisateur est modifié (suspendu ou réactivé). | ### Rôle \{#role} -| Type d'événement | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------------- | -| Role.Created | Un nouveau rôle est créé. | -| Role.Deleted | Un rôle est supprimé. | -| Role.Data.Updated | Les données d'un rôle sont mises à jour, par exemple, nom du rôle, description, et statut de rôle par défaut. | -| Role.Scopes.Updated | Les permissions attribuées à un rôle sont ajoutées ou supprimées. | +| Type d'événement | Description | +| ------------------- | --------------------------------------------------------------------------------------------------- | +| Role.Created | Un nouveau rôle est créé. | +| Role.Deleted | Un rôle est supprimé. | +| Role.Data.Updated | Les données d'un rôle sont mises à jour, par exemple : nom du rôle, description, statut par défaut. | +| Role.Scopes.Updated | Les permissions attribuées à un rôle sont ajoutées ou supprimées. | ### Permission (Portée) \{#permission-scope} -| Type d'événement | Description | -| ------------------ | ---------------------------------------------------------------------------------------------- | -| Scope.Created | Une nouvelle permission API est créée. | -| Scope.Deleted | Une permission API est supprimée. | -| Scope.Data.Updated | Les données d'une permission API sont mises à jour, par exemple, description de la permission. | +| Type d'événement | Description | +| ------------------ | ----------------------------------------------------------------------------------------------- | +| Scope.Created | Une nouvelle permission API est créée. | +| Scope.Deleted | Une permission API est supprimée. | +| Scope.Data.Updated | Les données d'une permission API sont mises à jour, par exemple : description de la permission. | ### Organisation \{#organization} -| Type d'événement | Description | -| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | Une nouvelle organisation est créée. | -| Organization.Deleted | Une organisation est supprimée. | -| Organization.Data.Updated | Les données d'une organisation sont mises à jour, par exemple, nom de l'organisation, description, custom.data, etc. | -| Organization.Membership.Updated | Des utilisateurs ou des applications sont ajoutés ou supprimés d'une organisation. La charge utile inclut les [champs delta d'adhésion](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | +| Type d'événement | Description | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | Une nouvelle organisation est créée. | +| Organization.Deleted | Une organisation est supprimée. | +| Organization.Data.Updated | Les données d'une organisation sont mises à jour, par exemple : nom, description, custom.data, etc. | +| Organization.Membership.Updated | Des utilisateurs ou applications sont ajoutés ou retirés d'une organisation. Le payload inclut les [champs delta de membres](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | ### Rôle d'organisation \{#organization-role} -| Type d'événement | Description | -| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | -| OrganizationRole.Created | Un nouveau rôle d'organisation est créé. | -| OrganizationRole.Deleted | Un rôle d'organisation est supprimé. | -| OrganizationRole.Data.Updated | Les données d'un rôle d'organisation sont mises à jour, par exemple, nom et description du rôle d'organisation. | -| OrganizationRole.Scopes.Updated | Les permissions attribuées à un rôle d'organisation sont ajoutées ou supprimées. | +| Type d'événement | Description | +| ------------------------------- | ----------------------------------------------------------------------------------------- | +| OrganizationRole.Created | Un nouveau rôle d'organisation est créé. | +| OrganizationRole.Deleted | Un rôle d'organisation est supprimé. | +| OrganizationRole.Data.Updated | Les données d'un rôle d'organisation sont mises à jour, par exemple : nom et description. | +| OrganizationRole.Scopes.Updated | Les permissions attribuées à un rôle d'organisation sont ajoutées ou supprimées. | ### Permission d'organisation (portée) \{#organization-permission-scope} -| Type d'événement | Description | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| OrganizationScope.Created | Une nouvelle permission d'organisation est créée. | -| OrganizationScope.Deleted | Une permission d'organisation est supprimée. | -| OrganizationScope.Data.Updated | Les données d'une permission d'organisation sont mises à jour, par exemple, description de la permission d'organisation. | +| Type d'événement | Description | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| OrganizationScope.Created | Une nouvelle permission d'organisation est créée. | +| OrganizationScope.Deleted | Une permission d'organisation est supprimée. | +| OrganizationScope.Data.Updated | Les données d'une permission d'organisation sont mises à jour, par exemple : description de la permission. | -### Événements déclenchés par Management API \{#management-api-triggered-events} +### Événements déclenchés par la Management API \{#management-api-triggered-events} | Point de terminaison API | Événement | | ---------------------------------------------------------- | ----------------------------------------------------------- | @@ -110,26 +110,27 @@ Ce guide répertorie les différents événements de webhook Logto et explique q | POST /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated | | DELETE /organization-roles/:id/scopes/:organizationScopeId | OrganizationRole.Scopes.Updated | -### Événements déclenchés par Experience API \{#experience-api-triggered-events} +### Événements déclenchés par l’Experience API \{#experience-api-triggered-events} -| Action d'interaction utilisateur | Événement | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| Liaison email / téléphone utilisateur | User.Data.Updated | -| Liaison MFA utilisateur | User.Data.Updated | -| Liaison sociale / SSO utilisateur | User.Data.Updated | -| Réinitialisation du mot de passe utilisateur | User.Data.Updated | -| Inscription utilisateur | User.Created | -| Utilisateur auto-approvisionné dans une organisation via [approvisionnement Just-in-Time](/organizations/just-in-time-provisioning) (correspondance de domaine email ou connecteur SSO d'entreprise) | Organization.Membership.Updated | +| Action d'interaction utilisateur | Événement | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| Liaison e-mail / téléphone utilisateur | User.Data.Updated | +| Liaison MFA utilisateur | User.Data.Updated | +| Liaison sociale / SSO utilisateur | User.Data.Updated | +| Réinitialisation du mot de passe utilisateur | User.Data.Updated | +| Enregistrement utilisateur | User.Created | +| Provisionnement automatique d'un utilisateur dans une organisation via le [provisionnement Just-in-Time](/organizations/just-in-time-provisioning) (domaine e-mail ou connecteur SSO d’entreprise correspondant) | Organization.Membership.Updated | -## Événements de hook d'exception \{#exception-hook-events} +## Événements de hook d’exception \{#exception-hook-events} ### Sécurité \{#security} -| Type d'événement | Description | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | Un compte utilisateur est verrouillé en raison de tentatives consécutives de vérification d'identité échouées. Peut être déclenché dans les flux suivants :
  • Échec de la vérification du mot de passe
  • Échec de la vérification du code
  • Échec de la vérification du jeton unique
| +| Type d'événement | Description | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identifier.Lockout | Un compte utilisateur est verrouillé suite à des tentatives consécutives de vérification d'identité échouées. Peut être déclenché dans les flux suivants :
  • Échec de la vérification du mot de passe
  • Échec de la vérification du code
  • Échec de la vérification du jeton à usage unique
| +| Message.RateLimited | Un utilisateur final dépasse la [limite d'envoi](/security/send-rate-limit) par destinataire pour les codes de vérification. Se déclenche uniquement sur les chemins d'envoi utilisateur final (Experience API et Account API), avec un payload `{ action, recipient }`. | -## FAQs \{#faqs} +## FAQ \{#faqs}
@@ -138,6 +139,6 @@ Ce guide répertorie les différents événements de webhook Logto et explique q -`PostRegister` est déclenché lorsqu'un utilisateur crée avec succès un nouveau compte via le flux d'inscription utilisateur ; `User.Created` est déclenché lorsqu'un nouveau compte utilisateur est créé via Management API. +`PostRegister` est déclenché lorsqu'un utilisateur crée avec succès un nouveau compte via le flux d'inscription utilisateur ; `User.Created` est déclenché lorsqu'un nouveau compte utilisateur est créé via la Management API.
diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/security/README.mdx index ba8e5b6ee8a..6c9f0dd7d05 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/fr/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # Sécurité -La sécurité moderne de l’authentification doit faire face à des menaces allant du phishing, du bourrage d’identifiants, des attaques par force brute, des ransomwares, des attaques DDoS, jusqu’aux attaques pilotées par l’IA. Protéger les identités des utilisateurs est essentiel pour préserver la confiance envers la marque et la conformité. +La sécurité moderne de l'authentification doit faire face à des menaces allant du phishing, du bourrage d'identifiants, des attaques par force brute, des ransomwares, des attaques DDoS, jusqu’aux attaques pilotées par l’IA. Protéger les identités des utilisateurs est essentiel pour préserver la confiance dans la marque et la conformité. -Logto offre une gestion robuste et sécurisée des accès, conçue pour contrer ces risques de front. En privilégiant la prévention proactive des menaces et la résilience, nous assurons que vos systèmes restent protégés sans compromettre l’expérience utilisateur. Avec Logto, la sécurité n’est pas une réflexion après coup — c’est le socle, permettant aux entreprises de prospérer à une époque où les menaces évoluent, mais où les défenses évoluent encore plus vite. +Logto offre une gestion robuste et sécurisée des accès conçue pour contrer ces risques de front. En privilégiant la prévention proactive des menaces et la résilience, nous veillons à ce que vos systèmes restent protégés sans compromettre l’expérience utilisateur. Avec Logto, la sécurité n’est pas une réflexion après coup — c’est le socle, permettant aux entreprises de prospérer à une époque où les menaces évoluent, mais où les défenses évoluent encore plus vite. ## Mettre en place une protection de sécurité avancée \{#set-up-advanced-security-protection} @@ -58,6 +58,16 @@ Logto offre une gestion robuste et sécurisée des accès, conçue pour contrer icon: , }, }, + { + type: 'link', + label: 'Limite de fréquence d’envoi', + href: '/security/send-rate-limit', + description: + 'Limitez l’envoi de codes de vérification et de messages par destinataire pour éviter le spam de boîtes de réception et l’abus de SMS pumping.', + customProps: { + icon: , + }, + }, { type: 'link', label: 'Masquer l’existence du compte', @@ -80,7 +90,7 @@ Logto offre une gestion robuste et sécurisée des accès, conçue pour contrer label: 'Authentification multi-facteurs (MFA)', href: '/end-user-flows/mfa', description: - 'Ajoutez une couche de protection supplémentaire au processus de connexion avec la prise en charge des OTP d’application d’authentification, des passkeys (WebAuthn) et des codes de secours.', + 'Ajoute une couche de protection supplémentaire au processus de connexion avec la prise en charge des OTP d’application d’authentification, des passkeys (WebAuthn) et des codes de secours.', customProps: { icon: , }, @@ -130,7 +140,7 @@ Logto offre une gestion robuste et sécurisée des accès, conçue pour contrer label: 'Inscription sur invitation uniquement', href: '/end-user-flows', description: - 'Limitez les inscriptions aux seuls utilisateurs invités, en utilisant des liens magiques par e-mail pour un onboarding sécurisé.', + 'Restreignez les inscriptions aux seuls utilisateurs invités, en utilisant des liens magiques par e-mail pour un onboarding sécurisé.', customProps: { icon: , }, diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/fr/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..302d0d3eebd --- /dev/null +++ b/i18n/fr/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: Limite de fréquence d’envoi +sidebar_position: 5 +--- + +# Limitation de la fréquence d’envoi + +Logto applique une limite de fréquence intégrée, par destinataire, aux codes de vérification sortants et autres messages envoyés par e-mail et SMS. Cela protège vos utilisateurs et vos fournisseurs de messagerie contre les abus d’envoi — comme un attaquant qui spammerait la boîte de réception ou le téléphone d’une victime avec des codes, ou qui gonflerait le trafic SMS pour augmenter vos coûts. + +Cette limite est **obligatoire et au niveau du système** : elle s’applique à chaque locataire, quel que soit le plan, et elle **n’est pas** configurable par le locataire. Elle est indépendante de : + +- La politique de **[verrouillage d’identifiant](/security/identifier-lockout)** et de **[CAPTCHA](/security/captcha)**, qui limitent les _tentatives de vérification échouées_ au moment de la vérification, et non l’acte d’_envoi_. +- La limite globale de fréquence d’API par locataire (code d’erreur `request.rate_limited`), qui limite le volume global de requêtes sur un locataire. + +## Fonctionnement \{#how-it-works} + +- **Plafond par destinataire** : Logto limite le nombre de messages pouvant être envoyés au même destinataire (adresse e-mail ou numéro de téléphone) dans une courte fenêtre temporelle glissante. Par défaut, cela autorise jusqu’à **10 envois par destinataire toutes les 10 minutes**. +- **Où cela s’applique** : tous les chemins d’envoi côté serveur, y compris les envois de codes de vérification via Experience API et Account API (connexion, inscription, réinitialisation du mot de passe, MFA et liaison d’identifiant), envois de codes de vérification via Management API, envoi et renvoi d’invitations d’organisation, et envois de codes de vérification via Account (`/me`). +- **Lorsque le plafond est dépassé** : la requête est rejetée avec HTTP `429` et le code d’erreur `request.message_rate_limited` — distinct du limiteur global du locataire (`request.rate_limited`) et du verrouillage au moment de la vérification (`session.verification_blocked_too_many_attempts`), afin que vous puissiez le gérer spécifiquement dans votre intégration. + +## Surveiller les envois limités via un webhook \{#monitor-rate-limited-sends-with-a-webhook} + +Lorsqu’un **utilisateur final** atteint le plafond par destinataire, Logto déclenche l’événement webhook `Message.RateLimited` [événement webhook](/developers/webhooks/webhooks-events#exception-hook-events), afin que vous puissiez être alerté ou réagir à un abus d’envoi. + +- **Déclenché pour** : uniquement les chemins d’envoi de codes de vérification pour les utilisateurs finaux — Experience API et Account API. Il **n’est pas** déclenché pour les envois initiés par une première partie ou un administrateur (codes de vérification Management API, invitations d’organisation ou `/me`). +- **Payload** : le contexte du hook inclut l’`action` (par exemple, `VerificationCodeSend`) et le `recipient` (l’adresse e-mail ou le numéro de téléphone). + +**Cas d’usage courants :** + +- Envoyer des alertes de sécurité à votre équipe pour examen. +- Déclencher une automatisation anti-abus en aval pour le destinataire concerné. + +Accédez à Console > Webhooks pour vous abonner, ou créez le hook via Management API. Pour la structure détaillée de l’événement et la configuration, voir [Webhooks](/developers/webhooks). + +## Livraison supprimée aux destinataires inconnus \{#suppressed-delivery-to-unknown-recipients} + +Pour empêcher l’énumération des comptes, lorsque l’inscription via un identifiant est désactivée, un code de vérification de connexion demandé pour une adresse e-mail ou un numéro de téléphone que **aucun compte ne possède** n’est pas livré silencieusement, et l’API répond comme elle le ferait pour un véritable envoi. Un attaquant ne peut donc pas utiliser ces réponses pour savoir quelles adresses sont enregistrées. La livraison aux utilisateurs existants n’est pas affectée. Voir aussi [Masquer l’existence du compte](/end-user-flows/sign-up-and-sign-in). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/README.mdx index e1c3b00400b..e60803e0f85 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -1,8 +1,8 @@ # 開発者 -Logto は、 [OAuth 2](https://auth.wiki/oauth-2.0) および [OIDC](https://auth.wiki/openid-connect) プロトコルに基づく [アイデンティティおよびアクセス管理 (IAM)](https://auth.wiki/iam) サービスです。Logto のような IAM サービスは、他の Web サービスの基盤として機能することが多く、それらの Web サービス内のさまざまな認可 (Authorization) 状態は Logto によって直接影響を受けます。 +Logto は、 [OAuth 2](https://auth.wiki/oauth-2.0) および [OIDC](https://auth.wiki/openid-connect) プロトコルに基づいた [アイデンティティおよびアクセス管理 (IAM)](https://auth.wiki/iam) サービスです。Logto のような IAM サービスは、他の Web サービスの基盤として機能することが多く、それらの Web サービス内のさまざまな認可 (Authorization) 状態は Logto によって直接影響を受けます。 -ユーザーの利便性を高めるために、Logto は一般的によく使われる開発者向け機能を一連提供しています。 +ユーザーの利便性を高めるために、Logto はよく使われる開発者向け機能を一連で提供しています。 ## サインイン体験関連 \{#sign-in-experience-related} @@ -21,7 +21,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'カスタムアクセス トークン (Custom access token)', href: '/developers/custom-token-claims', - description: 'カスタムスクリプトを使用してアクセス トークン (Access token) に追加のクレーム (Claim) を付与し、ABAC の実現やトークン発行の拒否を可能にします。', + description: 'カスタムスクリプトを使用してアクセス トークンに追加のクレーム (Claims) を付与し、ABAC の実現やトークン発行の拒否を可能にします。', customProps: { icon: , } @@ -30,7 +30,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'カスタム ID トークン (Custom ID token)', href: '/developers/custom-id-token', - description: 'OIDC 仕様に従い、ID トークン (ID token) に含める拡張クレーム (Claim) を制御できます。', + description: 'OIDC 仕様に従い、ID トークンに含める拡張クレーム (Claims) を制御できます。', customProps: { icon: , } @@ -39,11 +39,20 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'ユーザーなりすまし (User impersonation)', href: '/developers/user-impersonation', - description: '認可 (Authorization) されたユーザーが一時的にエンドユーザーとして操作できるようにし、トラブルシューティングやカスタマーサポート、管理作業に役立ちます。', + description: '認可 (Authorization) されたユーザーが一時的にエンドユーザーとして操作できるようにし、トラブルシューティングやカスタマーサポート、管理業務に役立ちます。', customProps: { icon: , } }, + { + type: 'link', + label: 'サービス間委任 (Service-to-service delegation)', + href: '/developers/service-to-service-delegation', + description: 'ユーザーのアクセス トークンを下流 API のアクセス トークンに交換し、バックエンドサービスが現在のユーザーの代理として動作できるようにします。', + customProps: { + icon: , + } + }, ]} /> ``` @@ -66,7 +75,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhook', href: '/developers/webhooks', - description: 'Webhook は、HTTP リクエストを通じてユーザー情報や権限 (Permission) 更新に関するリアルタイム通知をサポートし、Logto 連携の利便性と柔軟性を高めます。', + description: 'Webhook は、HTTP リクエストを通じてユーザー情報や権限更新に関するリアルタイム通知をサポートし、Logto 連携の利便性と柔軟性を高めます。', customProps: { icon: , } @@ -75,7 +84,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '監査ログ (Audit logs)', href: '/developers/audit-logs', - description: 'ユーザーの認証 (Authentication) 関連アクティビティを記録し、ユーザー行動のデバッグや分析を容易にします。', + description: 'ユーザーの認証 (Authentication) 関連アクティビティを記録し、ユーザーアクティビティのデバッグや分析を容易にします。', customProps: { icon: , } diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index 8189dd3aae3..39ad4818e24 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,26 +1,26 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- -# 監査ログ (Audit logs) +# 監査ログ -Logto の監査ログ (Audit logs) を利用すると、ユーザーのアクティビティやイベントを簡単に監視できます。さまざまなユーザー管理やヘルスチェックのビジネスシナリオに強力な基盤を提供します。 +Logto の監査ログは、ユーザーのアクティビティやイベントを簡単に監視できます。さまざまなユーザー管理やヘルスチェックのビジネスシナリオに強力な基盤を提供します。 ## すべてのログを表示する \{#view-all-logs} -コンソール > 監査ログ (Audit logs) に移動します。Logto -は認証 (Authentication) -イベントをキャプチャし、テーブルに整理します。イベント名、ユーザー、アプリケーション、タイムスタンプを記録します。イベント名やアプリケーション名でフィルタリングすることで、結果を絞り込むことができます。特定のイベントをクリックすると、追加の詳細情報が表示されます。 +コンソール > 監査ログ +に移動します。Logto は認証 (Authentication) +イベントをキャプチャし、テーブルに整理します。イベント名、ユーザー、アプリケーション、タイムスタンプを記録します。イベント名やアプリケーション名で絞り込み検索が可能です。特定のイベントをクリックすると、追加の詳細情報が表示されます。 :::warning -監査ログ (Audit logs) にはユーザー認証 (Authentication) プロセス中に発生したログのみが含まれ、Management API 操作のログは記録されません。 +監査ログにはユーザー認証 (Authentication) プロセス中に発生したログのみが含まれ、Management API 操作のログは記録されません。 ::: ## テナントレベルでユーザーアクティビティをキャプチャする \{#capture-user-activity-at-the-tenant-level} -Logto のログは包括的な詳細情報を提供し、迅速な対応と顧客の安全性を確保します。以下の情報をキャプチャし記録します： +Logto のログは包括的な詳細を提供し、アクションの容易さと顧客の安全性を確保します。次の情報をキャプチャし記録します： -- イベントの種類（監査ログ (Audit logs) イベントの全リストは [こちら](/developers/audit-logs/event-types)） +- イベントの種類（監査ログイベントの全リストは [こちら](/developers/audit-logs/event-types) で確認できます） - 関連するアプリケーション - IP アドレス - 関連するユーザー @@ -28,37 +28,35 @@ Logto のログは包括的な詳細情報を提供し、迅速な対応と顧 - タイムスタンプ - ユーザーエージェント -これらのイベント記録を維持することで、組織は潜在的なセキュリティリスクを効果的に検出し、不正なシステムアクセスを防ぐために迅速に対応できます。 +これらのイベント記録を維持することで、組織はセキュリティリスクを効果的に検出し、不正なシステムアクセスを防ぐために迅速に対応できます。 -監査ログ (Audit log) 成功詳細ページ +監査ログ成功詳細ページ -## ユーザーレベルで詳細な分析を行う \{#perform-a-detailed-analysis-at-the-user-level} +## ユーザーレベルで詳細分析を行う \{#perform-a-detailed-analysis-at-the-user-level} -管理者は、特定のユーザーに関連するログを詳細に分析でき、特定のイベントに対する包括的な調査が可能です。ナビゲーションプロセスはシンプルで使いやすいです。 +管理者は、特定ユーザーに関連するログの詳細分析を行うことができ、特定イベントの包括的な調査が容易になります。ナビゲーションはシンプルで使いやすい設計です。 -ユーザー固有のログにアクセスするには、以下の手順に従ってください： +ユーザー固有のログにアクセスするには、次の手順に従います： -1. コンソール > ユーザー管理 に移動します。 -2. 対象のユーザーを選択し、詳細ページに進みます。 +1. コンソール > ユーザー管理 + に移動します。 +2. 対象ユーザーを選択し、詳細ページに進みます。 3. 「ユーザーログ」をクリックします。表示されるテーブルには、そのユーザーによって実行・トリガーされたログイベントのみが表示されます。 特定ユーザーに関連する監査ログ (Audit logs) -## よくある質問 (FAQs) \{#faqs} +## よくある質問 \{#faqs}
-### セルフホスト型 Logto を利用していますが、監査ログ (Audit logs) の取得に数秒かかります。パフォーマンスを改善するにはどうすればよいですか？ \{#im-using-self-hosted-logto-and-it-takes-seconds-to-get-the-audit-logs-how-can-i-improve-the-performance} +### セルフホスト版 Logto を利用していますが、監査ログの取得に数秒かかります。パフォーマンスを改善するには？ \{#im-using-self-hosted-logto-and-it-takes-seconds-to-get-the-audit-logs-how-can-i-improve-the-performance} -OSS ユーザーは、定期的に古い監査ログ (Audit logs) をクリーンアップする cronjob を追加してください。 +OSS ユーザーは、定期的に古い監査ログをクリーンアップする cron ジョブを追加してください。
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index 39562e3cf85..854f457a98b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,18 +2,18 @@ id: sdk-conventions title: プラットフォーム SDK の規約 sidebar_label: プラットフォーム SDK の規約 -sidebar_position: 8 +sidebar_position: 9 --- # プラットフォーム SDK の規約 Logto は非常に強力で柔軟な Web 認証 (Authentication) サービスを提供しています。 -Logto のサービスを実際に利用する際、開発者が自分のクライアントアプリケーションに Logto SDK を統合し、ユーザーのサインイン状態や権限などを管理する必要がある場合が多いです。 +Logto のサービスを実際に利用する際、利便性のために開発者が自身のクライアントアプリケーションに Logto SDK を統合し、ユーザーのサインイン状態や権限などを管理する必要がよくあります。 Logto がサポートするすべてのプログラミング言語 / フレームワーク向けの SDK は [こちら](/quick-starts) で確認できます。 -もし希望する SDK が見つからない場合は、ご自身の希望するプログラミング言語向けに SDK を実装する際に従うことができる規約を以下に示します。これにより、Logto サービスをより簡単に利用できるようになります。 +もし希望する SDK が見つからなかった場合は、ここで紹介する規約に従って、希望するプログラミング言語向けに SDK を実装することで、Logto サービスをより簡単に利用できるようになります。 この規約は主に 3 つのパートで構成されています： diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..82ee47e8953 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,151 @@ +--- +id: service-to-service-delegation +title: サービス間委任 (Service-to-service delegation) +sidebar_label: サービス間委任 (Service-to-service delegation) +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# サービス間委任 (Service-to-service delegation) + +一部の API アーキテクチャでは、バックエンドサービスがサインイン済みユーザーからリクエストを受け取り、そのユーザーのアイデンティティを保持したまま別のバックエンドサービスを呼び出す必要があります。 + +例えば： + +```text +ユーザー -> API A -> API B +``` + +API B は次の 2 点を知る必要があります： + +1. 呼び出し元が信頼できるサービス（例：API A）であること。 +2. 操作が元のユーザーのために実行されていること。 + +Logto のトークンエクスチェンジグラントを利用して、ユーザーのアクセス トークン (Access token) を下流の API リソースをオーディエンス (Audience) とする新しいアクセス トークン (Access token) に交換します。これは OAuth 2.0 のトークンエクスチェンジパターンに従い、元のユーザートークンを下流サービスに転送することを回避します。 + +## このフローを使うべき場合 \{#when-to-use-this-flow} + +サービス間委任を利用するのは、次のような場合です： + +- API A が Logto のトークンエンドポイントに安全に認証できるバックエンドサービスである。 +- API A が Logto 発行のユーザーアクセス トークン (Access token) を受け取る。 +- API A が同じユーザーの代理で API B を呼び出す必要がある。 +- API B が自分の API リソースをオーディエンス (Audience) とする 1 つのアクセス トークン (Access token) を検証すべきである。 + +ユーザーがいない純粋なマシン間通信の場合はこのフローを使用しないでください。その場合は [クライアントクレデンシャルフロー](/quick-starts/m2m) を利用してください。サポートや管理者、エージェントなど、あるユーザーが一時的に別のユーザーとして行動する場合は、[ユーザーなりすまし (User impersonation)](/developers/user-impersonation) を利用してください。 + +## 仕組み \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as ユーザー + participant ApiA as API A + participant Logto as Logto トークンエンドポイント + participant ApiB as API B + + User->>ApiA: Authorization: Bearer ユーザーアクセス トークン (Access token) + Note over ApiA: API A 用のユーザートークンを検証 + + ApiA->>Logto: POST /oidc/token （トークンエクスチェンジグラント） + Note over ApiA,Logto: subject_token = ユーザーのアクセス トークン (Access token)
resource = API B のリソースインジケーター (Resource indicator) + + Logto-->>ApiA: API B 用のアクセス トークン (Access token) + ApiA->>ApiB: Authorization: Bearer 交換済みアクセス トークン (Access token) + Note over ApiB: 発行者 (Issuer)、オーディエンス (Audience)、有効期限、スコープ (Scope) を検証 +``` + +交換されたアクセス トークン (Access token) は元のユーザー（`sub`）を表し、下流の API リソース（`aud`）にバインドされます。下流の API は `client_id` クレーム (Claim) を確認することで、交換を開始したアプリケーションを特定できます。 + +## 前提条件 \{#prerequisites} + +1. 関連するサービス用の API リソースを作成します。詳しくは [グローバル API リソースの保護](/authorization/global-api-resources) を参照してください。 +2. API B の権限 (Permissions) を設定し、ロール (Role) または組織ロール (Organization role) を通じてユーザーに割り当てます。 +3. API A には、アプリシークレットで安全に認証できるサーバーサイドアプリ（マシン間通信アプリや従来型 Web アプリなど）を使用します。 +4. API A のアプリケーションでトークンエクスチェンジを有効にします。 + + + +## 下流 API 用のアクセス トークン (Access token) をリクエストする \{#request-an-access-token-for-the-downstream-api} + +API A が API B を呼び出す必要がある場合、Logto の [トークンエンドポイント](/integrate-logto/application-data-structure#token-endpoint) にトークンエクスチェンジリクエストを送信します。 + +従来型 Web アプリやアプリシークレットを持つマシン間通信アプリの場合、`Authorization` ヘッダーに認証情報を含めます： + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +パラメーター： + +1. `grant_type`：`urn:ietf:params:oauth:grant-type:token-exchange` を指定します。 +2. `subject_token`：API A が受け取った Logto 発行の元のユーザーアクセス トークン (Access token)。 +3. `subject_token_type`：`urn:ietf:params:oauth:token-type:access_token` を指定します。 +4. `resource`：API B のリソースインジケーター (Resource indicator)。 +5. `scope`：この委任呼び出しで API A が要求する下流の権限 (Permissions)。Logto は、RBAC 設定に従い、元のユーザーがこのリソースで利用可能なスコープ (Scope) のみを発行します。 + +Logto は API B 用のアクセス トークン (Access token) を返します： + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +デコードすると、アクセス トークン (Access token) には次のようなクレーム (Claims) が含まれます： + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +その後、API A は交換済みトークンで API B を呼び出します： + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## API B でトークンを検証する \{#validate-the-token-in-api-b} + +API B は、Logto 発行の API リソース用アクセス トークン (Access token) と同様に、交換済みトークンを検証する必要があります： + +1. Logto の JWKs を使って署名を検証します。 +2. 発行者 (`iss`) を確認します。 +3. オーディエンス (`aud`) が API B のリソースインジケーター (Resource indicator) と一致するか確認します。 +4. 有効期限 (`exp`) を確認します。 +5. 必要なスコープ (Scope) を確認します。 +6. `sub` を元のユーザー ID として利用します。 +7. 特定の上流サービスのみ委任呼び出しを許可する場合は、`client_id` も任意で確認します。 + +実装ガイダンスについては [API でのアクセス トークン (Access token) の検証](/authorization/validate-access-tokens) を参照してください。 + +## 関連リソース \{#related-resources} + +グローバル API リソースの保護 + + + API でのアクセス トークン (Access token) の検証 + + +ユーザーなりすまし (User impersonation) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 3d2f1319d60..bdd627bd27f 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,14 +2,14 @@ id: signing-keys title: 署名鍵 sidebar_label: 署名鍵 -sidebar_position: 5 +sidebar_position: 6 --- # 署名鍵 -Logto の [OIDC 署名鍵](https://auth.wiki/signing-key)（「OIDC プライベート鍵」や「OIDC クッキー鍵」とも呼ばれます）は、Logto の [サインインセッション](/sessions#what-is-a-logto-session) で JWT（[アクセス トークン (Access token)](https://auth.wiki/access-token) や [ID トークン (ID token)](https://auth.wiki/id-token)）およびブラウザクッキーに署名するために使用される鍵です。これらの署名鍵は、Logto データベースの初期化時（[オープンソース](/logto-oss)）や新しいテナント作成時（[Cloud](/logto-cloud)）に生成され、[CLI](/logto-oss/using-cli)（オープンソース）、Management API、またはコンソール UI から管理できます。 +Logto の [OIDC 署名鍵](https://auth.wiki/signing-key)（「OIDC プライベート鍵」や「OIDC クッキー鍵」とも呼ばれます）は、Logto の [サインインセッション](/sessions#what-is-a-logto-session) で JWT（[アクセス トークン](https://auth.wiki/access-token) や [ID トークン](https://auth.wiki/id-token)）およびブラウザクッキーに署名するために使用される鍵です。これらの署名鍵は、Logto データベースの初期化時（[オープンソース](/logto-oss)）や新しいテナント作成時（[Cloud](/logto-cloud)）に生成され、[CLI](/logto-oss/using-cli)（オープンソース）、Management API、またはコンソール UI から管理できます。 -デフォルトでは、Logto は楕円曲線 (EC) アルゴリズムを使用してデジタル署名を生成します。しかし、ユーザーが JWT 署名を検証する必要がある場合が多く、古いツールの多くが EC アルゴリズムをサポートしていない（RSA のみサポート）ことを考慮し、プライベート鍵のローテーション機能と署名アルゴリズム（RSA と EC の両方を含む）の選択機能を実装しています。これにより、古い署名検証ツールを使用するサービスとの互換性が確保されます。 +デフォルトでは、Logto は楕円曲線（EC）アルゴリズムを使用してデジタル署名を生成します。しかし、ユーザーが JWT 署名を検証する必要がある場合や、多くの古いツールが EC アルゴリズムをサポートしておらず（RSA のみサポート）、RSA 署名が必要なケースも多いため、プライベート鍵のローテーション機能と署名アルゴリズム（RSA および EC の両方を含む）の選択機能を実装しています。これにより、古い署名検証ツールを使用するサービスとの互換性が確保されます。 :::note 理論的には、署名鍵は漏洩してはならず、有効期限もありません。つまり、ローテーションの必要はありません。しかし、一定期間ごとに署名鍵をローテーションすることでセキュリティを強化できます。 @@ -17,10 +17,10 @@ Logto の [OIDC 署名鍵](https://auth.wiki/signing-key)（「OIDC プライベ ## 仕組み \{#how-it-works} -- **OIDC プライベート鍵** - Logto インスタンスの初期化時に、公開鍵とプライベート鍵のペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークン (Access token) または ID トークン (ID token)）を発行する際、そのトークンはプライベート鍵で署名されます。同時に、JWT を受け取ったクライアントアプリケーションは、対応する公開鍵を使ってトークン署名を検証し、トークンが第三者によって改ざんされていないことを確認できます。プライベート鍵は Logto サーバー上で保護されますが、公開鍵はその名の通り誰でもアクセス可能であり、OIDC エンドポイントの `/oidc/jwks` インターフェースから取得できます。プライベート鍵生成時に署名鍵アルゴリズムを指定でき、Logto はデフォルトで EC（楕円曲線）アルゴリズムを使用します。管理者ユーザーは、プライベート鍵のローテーションによってデフォルトのアルゴリズムを RSA（Rivest-Shamir-Adleman）に変更できます。 -- **OIDC クッキー鍵** - ユーザーがサインインまたはサインアップフローを開始すると、サーバー上に「OIDC セッション」が作成され、同時に一連のブラウザクッキーも生成されます。これらのクッキーにより、ブラウザは Logto Experience API を使ってサインイン、サインアップ、パスワードリセットなどの一連の操作をユーザーの代わりに実行できます。しかし、JWT とは異なり、クッキーは Logto OIDC サービス自身のみが署名・検証を行い、非対称暗号化は必要ありません。そのため、クッキー署名鍵には公開鍵のペアや非対称暗号アルゴリズムはありません。 +- **OIDC プライベート鍵** + Logto インスタンスの初期化時に、公開鍵とプライベート鍵のペアが自動的に生成され、基盤となる OIDC プロバイダーに登録されます。これにより、Logto が新しい JWT（アクセス トークンや ID トークン）を発行する際、そのトークンはプライベート鍵で署名されます。同時に、JWT を受け取ったクライアントアプリケーションは、ペアとなる公開鍵を使ってトークン署名を検証し、トークンが第三者によって改ざんされていないことを確認できます。プライベート鍵は Logto サーバー上で保護されますが、公開鍵はその名の通り誰でもアクセス可能であり、OIDC エンドポイントの `/oidc/jwks` インターフェースから取得できます。署名鍵のアルゴリズムはプライベート鍵生成時に指定でき、Logto はデフォルトで EC（楕円曲線）アルゴリズムを使用します。管理者ユーザーは、プライベート鍵のローテーションによってデフォルトのアルゴリズムを RSA（Rivest-Shamir-Adleman）に変更できます。 +- **OIDC クッキー鍵** + ユーザーがサインインまたはサインアップフローを開始すると、サーバー上で「OIDC セッション」が作成され、同時に一連のブラウザクッキーも生成されます。これらのクッキーにより、ブラウザは Logto Experience API を使ってサインイン、サインアップ、パスワードリセットなどの一連の操作をユーザーの代わりに実行できます。ただし、JWT とは異なり、クッキーは Logto OIDC サービス自身のみが署名・検証を行い、非対称暗号化は必要ありません。そのため、クッキー署名鍵にはペアとなる公開鍵や非対称暗号化アルゴリズムはありません。 ## コンソール UI から署名鍵をローテーションする \{#rotate-signing-keys-from-console-ui} @@ -33,24 +33,24 @@ Logto には「署名鍵ローテーション」機能があり、テナント | ステータス | 説明 | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | 次回 | 段階的な OIDC プライベート鍵ローテーション用のステータスです。鍵は作成されていますが、猶予期間が終了して有効になるまで Logto は新しい JWT の署名にこの鍵を使用しません。 | - | 現在 | この鍵が現在 Logto によって新規発行された JWT やクッキーの署名に使用されていることを示します。 | - | 前回 | 以前使用されていた鍵を指しますが、ローテーションによって置き換えられました。この鍵で署名された既存の JWT やクッキーは、有効期限が切れるか鍵が削除されるまで有効です。 | + | Next | 段階的な OIDC プライベート鍵ローテーション用のステータスです。鍵は作成されていますが、猶予期間が終了して有効になるまで Logto は新しい JWT の署名にこの鍵を使用しません。 | + | Current | 現在 Logto が新しく発行する JWT やクッキーの署名に使用している鍵です。 | + | Previous | 以前使用されていたがローテーションされた鍵です。この鍵で署名された既存の JWT やクッキーは、有効期限が切れるか鍵が削除されるまで有効です。 | ローテーションには以下の 3 つのアクションが含まれることを覚えておいてください： -1. **新しい署名鍵の作成**：OIDC プライベート鍵の場合、Logto は新しい鍵をまず「次回」として段階的に登録できるため、アプリケーションや API が新しい鍵で署名される前に `/oidc/jwks` エンドポイントから公開鍵を更新する時間を確保できます。 -2. **現在の鍵のローテーション**：ローテーションが有効になると、「次回」の鍵が「現在」となり、既存の「現在」の鍵は「前回」となります。前回の鍵で署名されたトークンは引き続き有効です。 -3. **最も古い前回の鍵の削除**：Logto は「前回」のプライベート鍵を最大 1 つまで保持します。段階的な鍵が「現在」になった際、すでに前回の鍵が存在する場合は、より古い前回の鍵が削除されます。 +1. **新しい署名鍵の作成**：OIDC プライベート鍵の場合、Logto は新しい鍵をまず「Next」として段階的に登録できるため、アプリケーションや API が新しい鍵で署名される前に `/oidc/jwks` エンドポイントから公開鍵を更新する時間を確保できます。 +2. **現在の鍵のローテーション**：ローテーションが有効になると、「Next」鍵が「Current」となり、既存の「Current」鍵は「Previous」となります。前の鍵で署名されたトークンは引き続き有効です。 +3. **最も古い Previous 鍵の削除**：Logto は「Previous」プライベート鍵を最大 1 つまで保持します。段階的な鍵が「Current」になる際、すでに「Previous」鍵が存在する場合は、より古い「Previous」鍵が削除されます。 -Logto Cloud では、OIDC プライベート鍵のローテーションは 4 時間の猶予期間後に有効となります。この期間中、新しい鍵は JWKS で公開され、Logto が新しい JWT の署名に使用し始める前に準備されます。コンソールのテーブルでは、**有効日時** 列で段階的な「次回」鍵が「現在」になるタイミングを確認できます。 +Logto Cloud では、OIDC プライベート鍵のローテーションは 4 時間の猶予期間後に有効となります。この期間中、新しい鍵は JWKS で公開され、Logto が新しい JWT の署名に使用し始める前に準備されます。コンソールのテーブルでは、**有効日時** 列に「Next」鍵が「Current」になる時刻が表示されます。 -セルフホスト OSS デプロイメントの場合、デフォルトのプライベート鍵ローテーション猶予期間は `0` 秒であり、ローテーションは即時に行われます。段階的なローテーションを利用するには、Logto サービスで `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 環境変数を設定するか、Management API エンドポイント `POST /api/configs/oidc/private-keys/rotate` を呼び出す際にリクエストボディで明示的に `rotationGracePeriod` 値を指定してください。 +セルフホスト OSS デプロイメントの場合、デフォルトのプライベート鍵ローテーション猶予期間は `0` 秒であり、ローテーションは即時に行われます。段階的なローテーションを利用するには、Logto サービスの `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 環境変数を設定するか、Management API の `POST /api/configs/oidc/private-keys/rotate` エンドポイント呼び出し時にリクエストボディで `rotationGracePeriod` 値を明示的に指定してください。 :::warning -保留中のローテーションが有効になる前に繰り返し署名鍵をローテーションすることは避けてください（意図的に段階的な「次回」鍵を置き換えたい場合を除く）。 +ローテーションが有効になる前に繰り返し署名鍵をローテーションすることは避けてください（意図的に段階的な「Next」鍵を置き換えたい場合を除く）。 -唯一の「前回」鍵を早期に削除すると、その鍵で署名された既存の JWT やクッキーが無効になる可能性があります。 +唯一の「Previous」鍵を早期に削除すると、その鍵で署名された既存の JWT やクッキーが無効になる可能性があります。 ::: ## 関連リソース \{#related-resources} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 93698bb3c0b..4e9358600d2 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,24 +1,24 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhook -Logto [Webhook](https://auth.wiki/webhook) は、ユーザーアカウント、ロール、権限、組織 (Organizations)、組織ロール、組織権限、[ユーザー操作](/end-user-flows) など、さまざまなイベントに対してリアルタイム通知を提供します。 +Logto の [Webhook](https://auth.wiki/webhook) は、ユーザーアカウント、ロール、権限、組織 (Organizations)、組織ロール、組織権限、[ユーザー操作](/end-user-flows) など、さまざまなイベントに対してリアルタイム通知を提供します。 -イベントがトリガーされると、Logto は指定した Endpoint URL に HTTP リクエストを送信し、ユーザー ID、ユーザー名、メールアドレスなど、イベントに関する詳細情報を含みます（ペイロードやヘッダーに含まれるデータの詳細については [Webhook リクエスト](/developers/webhooks/webhooks-request) を参照してください）。アプリケーション側でこのリクエストを処理し、メール送信やデータベースの更新など、カスタマイズしたアクションを実行できます。 +イベントが発生すると、Logto は指定したエンドポイント URL に HTTP リクエストを送信し、ユーザー ID、ユーザー名、メールアドレスなど、イベントに関する詳細情報を含みます（ペイロードやヘッダーに含まれるデータの詳細については [Webhook リクエスト](/developers/webhooks/webhooks-request) を参照してください）。アプリケーション側でこのリクエストを処理し、メール送信やデータベースの更新など、カスタマイズしたアクションを実行できます。 -ユーザーの要望に応じて、対応するイベントを随時追加しています。ビジネスに特化したご要望があれば、ぜひお知らせください。 +ユーザーの要望に応じて、対応するイベントを随時追加しています。ビジネス上の特定の要件があれば、ぜひご連絡ください。 ## なぜ Webhook を使うのか？ \{#why-use-webhook} Webhook はアプリケーション間のリアルタイム通信を実現し、ポーリングの必要をなくし、即時のデータ更新を可能にします。複雑なコードや独自 API なしで、アプリケーション統合やワークフロー自動化をシンプルにします。 -CIAM における Webhook の一般的なユースケース例： +CIAM における一般的な Webhook のユースケース例： -- **メール送信**：Webhook を設定し、新規ユーザー登録時にウェルカムメールを送信したり、新しいデバイスや場所からサインインがあった際に管理者へ通知したりできます。 -- **通知送信**：Webhook を設定し、CRM システムと連携したバーチャルアシスタントをトリガーし、ユーザー登録時にリアルタイムでカスタマーサポートを提供できます。 -- **追加の API コール実行**：Webhook を設定し、ユーザーのメールドメインや IP アドレスを確認してアクセスを検証し、Logto Management API を使ってリソース権限付きの適切なロールを割り当てます。 +- **メール送信**：Webhook を設定し、新規ユーザー登録時にウェルカムメールを送信したり、ユーザーが新しいデバイスや場所からサインインした際に管理者へ通知したりできます。 +- **通知送信**：Webhook を設定し、CRM システムのバーチャルアシスタントをトリガーして、ユーザー登録時にリアルタイムでカスタマーサポートを提供できます。 +- **追加 API コールの実行**：Webhook を設定し、ユーザーのメールドメインや IP アドレスをチェックしてアクセスを検証し、その後 Logto Management API を使ってリソース権限付きの適切なロールを割り当てます。 - **データ同期**：Webhook を設定し、ユーザーアカウントの停止や削除などの変更をアプリケーション側で常に最新に保ちます。 - **レポート生成**：Webhook を設定し、ユーザーのログインアクティビティデータを受け取り、ユーザーエンゲージメントや利用傾向のレポート作成に活用します。 @@ -26,12 +26,12 @@ CIAM における Webhook の一般的なユースケース例： | Item | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Event | 特定のアクションが実行されると、特定タイプのフックイベントがトリガーされます。例：ユーザーがサインアップを完了し新しいアカウントを作成した際、Logto は PostRegister フックイベントを発行します。 | +| Event | 特定のアクションが実行されると、特定タイプのフックイベントがトリガーされます。例：ユーザーがサインアップを完了し新しいアカウントを作成すると、Logto は PostRegister フックイベントを発行します。 | | Hook | 特定イベントにフックする 1 つまたは複数のアクション。アクションには API コールやコードスニペットの実行などが含まれます。 | -| Webhook | イベントのペイロードを使って API を呼び出すフックのサブタイプです。 | +| Webhook | イベントのペイロードを使って API を呼び出すことを示すフックのサブタイプです。 | | たとえば、開発者がユーザーが新しいデバイスからサインインした際に通知を送りたい場合、PostSignIn イベントに対して自身のセキュリティサービス API を呼び出す Webhook を追加できます。 | -以下は、Logto で `PostSignIn` イベントに対して 2 つの Webhook を有効化する例です： +Logto で `PostSignIn` イベントに対して 2 つの Webhook を有効化する例を示します： ```mermaid graph LR @@ -67,43 +67,43 @@ graph LR -同期 Webhook を利用するとユーザーのサインインフローがよりスムーズになりますが、現時点では未対応です（将来的に対応予定）。そのため、同期 Webhook に依存するシナリオは現状では個別のワークアラウンドが必要です。ご質問があればお気軽にお問い合わせください。 +同期 Webhook を利用するとユーザーのサインインフローがよりスムーズになりますが、現時点では未対応です（今後対応予定）。そのため、同期 Webhook に依存するシナリオは現状すべて異なる回避策が必要です。ご質問があればお気軽にご連絡ください。
-### ユーザー権限の変更にはどう対応すればよいですか？ \{#how-to-deal-with-user-permission-change} +### ユーザー権限変更時の対応方法は？ \{#how-to-deal-with-user-permission-change} -[ユーザー権限変更の管理](/authorization/global-api-resources/#optional-handle-user-permission-change) ガイドをご覧ください。 +[ユーザー権限変更の管理](/authorization/global-api-resources/#optional-handle-user-permission-change) ガイドを参照してください。
-### Webhook のタイムアウトをデバッグするには？ \{#how-to-debug-webhook-timeout} +### Webhook タイムアウトのデバッグ方法は？ \{#how-to-debug-webhook-timeout} -Webhook を受信するエンドポイントは、Webhook を正常に受信したことを Logto に伝えるため、できるだけ早く 2xx レスポンスを返す必要があります。Webhook の処理ロジックはユーザーごとに大きく異なるため、複雑な処理は数秒かかる場合があり、Logto Webhook がタイムアウトすることがあります。ベストプラクティスは独自のイベントキューを用意し、Logto Webhook を受信したらイベントをキューに挿入し、すぐに 2xx レスポンスを Logto に返すことです。その後、独自のワーカーでキュー内のタスクを順次処理します。ワーカーでエラーが発生した場合は、自身のサーバーで対応してください。 +Webhook を受信するエンドポイントは、Webhook を正常に受信したことを Logto に伝えるため、できるだけ早く 2xx レスポンスを返す必要があります。Webhook の処理ロジックはユーザーごとに大きく異なるため、処理が複雑すぎると数秒かかり、Logto Webhook がタイムアウトする場合があります。ベストプラクティスは独自のイベントキューを用意し、Logto Webhook を受信したらイベントをキューに挿入し、すぐに 2xx レスポンスを Logto に返すことです。その後、独自のワーカーでキュー内のタスクを順次処理します。ワーカーでエラーが発生した場合は、自身のサーバーで対応してください。
-### `PostSignIn` Webhook からクライアントの IP アドレスを取得できますか？ \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} +### `PostSignIn` Webhook からクライアント IP アドレスを取得できますか？ \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} -はい、Webhook のペイロードから IP アドレスやユーザーエージェントなどを取得できます。現在サポートされていない情報が必要な場合は、GitHub issue でフィーチャーリクエストを作成するか、お問い合わせください。 +はい、Webhook のペイロードで IP アドレスやユーザーエージェントなどを取得できます。現在サポートされていない情報が必要な場合は、GitHub issue でフィーチャーリクエストを作成するか、お問い合わせください。
## 関連リソース \{#related-resources} -Webhooks vs. polling +Webhook とポーリングの違い diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index d7eaf37edff..c0548a6f4e4 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -7,71 +7,71 @@ sidebar_position: 3 # Webhooks イベント -このガイドでは、Logto のさまざまな webhook イベントを一覧にし、各イベントが発生するタイミングを説明します。 +このガイドでは、さまざまな Logto Webhook イベントを一覧し、それぞれのイベントが発生するタイミングを説明します。 ## ユーザーインタラクションフックイベント \{#user-interaction-hook-events} -| イベントタイプ | 説明 | -| ----------------- | ---------------------------------------------------------------------------------- | -| PostRegister | ユーザーが UI インターフェースを通じて新しいアカウントを正常に作成します。 | -| PostSignIn | ユーザーが UI インターフェースを通じて正常にサインインします。 | -| PostResetPassword | ユーザーのパスワードが「パスワードを忘れた」フローを通じて正常にリセットされます。 | +| イベントタイプ | 説明 | +| ----------------- | ------------------------------------------------------------------------------------------ | +| PostRegister | ユーザーが UI インターフェースを通じて新しいアカウントを正常に作成したときに発生します。 | +| PostSignIn | ユーザーが UI インターフェースを通じて正常にサインインしたときに発生します。 | +| PostResetPassword | 「パスワードを忘れた」フローでユーザーのパスワードが正常にリセットされたときに発生します。 | ## データ変更フックイベント \{#data-mutation-hook-events} ### ユーザー \{#user} -| イベントタイプ | 説明 | -| ----------------------------- | --------------------------------------------------------------------------------------------------- | -| User.Created | 新しいユーザーアカウントが作成されます。 | -| User.Deleted | ユーザーアカウントが削除されます。 | -| User.Data.Updated | ユーザープロフィールデータが更新されます。例：メール、アバター、custom.data、ソーシャル識別子など。 | -| User.SuspensionStatus.Updated | ユーザーの停止ステータスが変更されます（停止または再有効化）。 | +| イベントタイプ | 説明 | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| User.Created | 新しいユーザーアカウントが作成されたときに発生します。 | +| User.Deleted | ユーザーアカウントが削除されたときに発生します。 | +| User.Data.Updated | ユーザープロファイルデータが更新されたときに発生します（例：メール、アバター、custom.data、ソーシャル識別子など）。 | +| User.SuspensionStatus.Updated | ユーザーの停止状態が変更されたとき（停止または再有効化）に発生します。 | -### ロール \{#role} +### ロール (Role) \{#role} -| イベントタイプ | 説明 | -| ------------------- | ------------------------------------------------------------------------------ | -| Role.Created | 新しいロールが作成されます。 | -| Role.Deleted | ロールが削除されます。 | -| Role.Data.Updated | ロールのデータが更新されます。例：ロール名、説明、デフォルトロールステータス。 | -| Role.Scopes.Updated | ロールに割り当てられた権限が追加または削除されます。 | +| イベントタイプ | 説明 | +| ------------------- | ---------------------------------------------------------------------------------------- | +| Role.Created | 新しいロールが作成されたときに発生します。 | +| Role.Deleted | ロールが削除されたときに発生します。 | +| Role.Data.Updated | ロールのデータが更新されたときに発生します（例：ロール名、説明、デフォルトロール状態）。 | +| Role.Scopes.Updated | ロールに割り当てられた権限が追加または削除されたときに発生します。 | ### 権限 (スコープ) \{#permission-scope} -| イベントタイプ | 説明 | -| ------------------ | ------------------------------------------------ | -| Scope.Created | 新しい API 権限が作成されます。 | -| Scope.Deleted | API 権限が削除されます。 | -| Scope.Data.Updated | API 権限のデータが更新されます。例：権限の説明。 | +| イベントタイプ | 説明 | +| ------------------ | ---------------------------------------------------------------- | +| Scope.Created | 新しい API 権限が作成されたときに発生します。 | +| Scope.Deleted | API 権限が削除されたときに発生します。 | +| Scope.Data.Updated | API 権限のデータが更新されたときに発生します（例：権限の説明）。 | -### 組織 \{#organization} +### 組織 (Organization) \{#organization} -| イベントタイプ | 説明 | -| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | 新しい組織が作成されます。 | -| Organization.Deleted | 組織が削除されます。 | -| Organization.Data.Updated | 組織のデータが更新されます。例：組織名、説明、custom.data など。 | -| Organization.Membership.Updated | ユーザーまたはアプリケーションが組織に追加または削除されます。ペイロードには [メンバーシップデルタフィールド](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload) が含まれます。 | +| イベントタイプ | 説明 | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | 新しい組織が作成されたときに発生します。 | +| Organization.Deleted | 組織が削除されたときに発生します。 | +| Organization.Data.Updated | 組織のデータが更新されたときに発生します（例：組織名、説明、custom.data など）。 | +| Organization.Membership.Updated | ユーザーまたはアプリケーションが組織に追加または削除されたときに発生します。ペイロードには [メンバーシップ差分フィールド](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload) が含まれます。 | -### 組織ロール \{#organization-role} +### 組織ロール (Organization role) \{#organization-role} -| イベントタイプ | 説明 | -| ------------------------------- | ---------------------------------------------------------- | -| OrganizationRole.Created | 新しい組織ロールが作成されます。 | -| OrganizationRole.Deleted | 組織ロールが削除されます。 | -| OrganizationRole.Data.Updated | 組織ロールのデータが更新されます。例：組織ロール名と説明。 | -| OrganizationRole.Scopes.Updated | 組織ロールに割り当てられた権限が追加または削除されます。 | +| イベントタイプ | 説明 | +| ------------------------------- | -------------------------------------------------------------------------- | +| OrganizationRole.Created | 新しい組織ロールが作成されたときに発生します。 | +| OrganizationRole.Deleted | 組織ロールが削除されたときに発生します。 | +| OrganizationRole.Data.Updated | 組織ロールのデータが更新されたときに発生します（例：組織ロール名や説明）。 | +| OrganizationRole.Scopes.Updated | 組織ロールに割り当てられた権限が追加または削除されたときに発生します。 | ### 組織権限 (スコープ) \{#organization-permission-scope} -| イベントタイプ | 説明 | -| ------------------------------ | ---------------------------------------------------- | -| OrganizationScope.Created | 新しい組織権限が作成されます。 | -| OrganizationScope.Deleted | 組織権限が削除されます。 | -| OrganizationScope.Data.Updated | 組織権限のデータが更新されます。例：組織権限の説明。 | +| イベントタイプ | 説明 | +| ------------------------------ | -------------------------------------------------------------------- | +| OrganizationScope.Created | 新しい組織権限が作成されたときに発生します。 | +| OrganizationScope.Deleted | 組織権限が削除されたときに発生します。 | +| OrganizationScope.Data.Updated | 組織権限のデータが更新されたときに発生します（例：組織権限の説明）。 | -### Management API トリガーイベント \{#management-api-triggered-events} +### Management API によるイベント \{#management-api-triggered-events} | API エンドポイント | イベント | | ---------------------------------------------------------- | ----------------------------------------------------------- | @@ -110,24 +110,25 @@ sidebar_position: 3 | POST /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated | | DELETE /organization-roles/:id/scopes/:organizationScopeId | OrganizationRole.Scopes.Updated | -### Experience API トリガーイベント \{#experience-api-triggered-events} +### Experience API によるイベント \{#experience-api-triggered-events} -| ユーザーインタラクションアクション | イベント | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| ユーザーのメール / 電話のリンク | User.Data.Updated | -| ユーザーの MFA のリンク | User.Data.Updated | -| ユーザーのソーシャル / SSO のリンク | User.Data.Updated | -| ユーザーのパスワードリセット | User.Data.Updated | -| ユーザー登録 | User.Created | -| [ジャストインタイムプロビジョニング](/organizations/just-in-time-provisioning) を通じて組織に自動プロビジョニングされたユーザー (メールドメインまたはエンタープライズ SSO コネクターの一致) | Organization.Membership.Updated | +| ユーザーインタラクションアクション | イベント | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| ユーザーのメール / 電話番号のリンク | User.Data.Updated | +| ユーザーの MFA のリンク | User.Data.Updated | +| ユーザーのソーシャル / SSO のリンク | User.Data.Updated | +| ユーザーのパスワードリセット | User.Data.Updated | +| ユーザー登録 | User.Created | +| [ジャストインタイムプロビジョニング](/organizations/just-in-time-provisioning)（メールドメイン一致またはエンタープライズ SSO コネクター）で組織に自動プロビジョニングされたユーザー | Organization.Membership.Updated | ## 例外フックイベント \{#exception-hook-events} ### セキュリティ \{#security} -| イベントタイプ | 説明 | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | ユーザーアカウントが連続したアイデンティティ検証失敗の試行によりロックされます。次のフローでトリガーされる可能性があります：
  • パスワード検証失敗
  • コード検証失敗
  • ワンタイムトークン検証失敗
| +| イベントタイプ | 説明 | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identifier.Lockout | ユーザーアカウントが連続したアイデンティティ確認失敗によりロックされたときに発生します。次のフローでトリガーされる可能性があります：
  • パスワード認証失敗
  • コード認証失敗
  • ワンタイムトークン認証失敗
| +| Message.RateLimited | エンドユーザーが認証コードの [送信レート制限](/security/send-rate-limit) を超えた場合に発生します。エンドユーザー送信経路（Experience API および Account API）でのみ発火し、ペイロードは `{ action, recipient }` です。 | ## よくある質問 \{#faqs} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/security/README.mdx index 94a45beae23..13480ec913a 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/ja/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # セキュリティ -現代の認証 (Authentication) セキュリティは、フィッシング、クレデンシャルスタッフィング、ブルートフォース攻撃、ランサムウェア、DDoS、AI 駆動型攻撃など、さまざまな脅威と戦っています。ユーザーアイデンティティの保護は、ブランドの信頼とコンプライアンスを守る上で極めて重要です。 +現代の認証 (Authentication) セキュリティは、フィッシング、クレデンシャルスタッフィング、ブルートフォース攻撃、ランサムウェア、DDoS、AI 駆動型攻撃など、さまざまな脅威と戦っています。ユーザーアイデンティティの保護は、ブランドの信頼とコンプライアンスを守るために極めて重要です。 -Logto は、これらのリスクに正面から対抗するために設計された堅牢なセキュアアクセス管理を提供します。積極的な脅威予防とレジリエンスを最優先することで、使いやすさを損なうことなくシステムをしっかりと守ります。Logto では、セキュリティは後付けではなく基盤であり、脅威が進化しても防御がさらに速く進化する時代にビジネスの成長を支えます。 +Logto は、これらのリスクに正面から対抗するために設計された堅牢なセキュアアクセス管理を提供します。積極的な脅威予防とレジリエンスを最優先することで、使いやすさを損なうことなくシステムを保護します。Logto では、セキュリティは後付けではなく基盤であり、脅威が進化しても防御がさらに速く進化する時代にビジネスの成長を支えます。 ## 高度なセキュリティ保護の設定 \{#set-up-advanced-security-protection} @@ -53,17 +53,27 @@ Logto は、これらのリスクに正面から対抗するために設計さ label: '識別子ロックアウト', href: '/security/identifier-lockout', description: - '複数回の認証 (Authentication) 失敗後に識別子を一時的にロックし、ブルートフォースアクセスを防止します。', + '複数回の認証 (Authentication) 失敗後に識別子を一時的にロックし、ブルートフォースアクセスを防ぎます。', customProps: { icon: , }, }, + { + type: 'link', + label: '送信レート制限', + href: '/security/send-rate-limit', + description: + '受信者ごとに認証コードやメッセージの送信回数を制限し、受信箱スパムや SMS ポンピングの悪用を防ぎます。', + customProps: { + icon: , + }, + }, { type: 'link', label: 'アカウント存在の非表示', href: '/end-user-flows/sign-up-and-sign-in', description: - 'アカウントの状態を隠し、アカウント列挙攻撃を防止し、機密性の高いアカウント情報の漏洩を防ぎます。', + 'アカウントの状態を隠し、アカウント列挙攻撃を防止し、機微なアカウント情報の漏洩を防ぎます。', customProps: { icon: , }, @@ -90,7 +100,7 @@ Logto は、これらのリスクに正面から対抗するために設計さ label: 'ステップアップ認証 (Authentication)', href: '/end-user-flows/security-verification', description: - 'ユーザーが機密情報にアクセスしたり高リスクな操作を行う際に、アプリからステップアップ認証 (Authentication) を促せます。', + 'ユーザーが機微な情報へアクセスしたり高リスク操作を行う際に、アプリからステップアップ認証 (Authentication) を促せます。', customProps: { icon: , }, @@ -100,7 +110,7 @@ Logto は、これらのリスクに正面から対抗するために設計さ label: 'ユーザーの一時停止', href: '/user-management/manage-users#suspend-user', description: - 'ユーザーアカウントを一時的に無効化し、データや記録を削除せずにアクセスを遮断します。', + 'データやユーザー記録を削除せずに、ユーザーアカウントを一時的に無効化してアクセスを遮断します。', customProps: { icon: , }, @@ -119,7 +129,7 @@ Logto は、これらのリスクに正面から対抗するために設計さ label: 'OIDC バックチャネルログアウト', href: '/end-user-flows/sign-out#federated-sign-out-back-channel-logout', description: - '集中管理されたログアウトを有効にし、セッションハイジャックや不正アクセスのリスクを低減します。', + '集中管理されたログアウトを有効化し、セッションハイジャックや不正アクセスのリスクを低減します。', customProps: { icon: , }, @@ -129,7 +139,7 @@ Logto は、これらのリスクに正面から対抗するために設計さ label: '招待制サインアップ', href: '/end-user-flows', description: - '招待されたユーザーのみがサインアップできるようにし、メールマジックリンクで安全にオンボーディングします。', + '招待されたユーザーのみがサインアップできるようにし、メールマジックリンクで安全なオンボーディングを実現します。', customProps: { icon: , }, diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/ja/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..213a79715ea --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,40 @@ +--- +slug: /security/send-rate-limit +sidebar_label: 送信レート制限 +sidebar_position: 5 +--- + +# 送信レート制限 + +Logto は、メールや SMS で送信される認証コードやその他のメッセージに対して、受信者ごとに組み込みのレート制限を適用しています。これにより、ユーザーやメッセージングプロバイダーが送信の悪用（たとえば、攻撃者が被害者の受信箱や電話にコードを大量送信したり、SMS トラフィックを増やしてコストを膨らませたりする行為）から保護されます。 + +この制限は **必須かつシステムレベル** です：すべてのテナントにプランに関係なく適用され、**テナント側で設定変更はできません**。この制限は以下とは独立しています： + +- **[識別子ロックアウト](/security/identifier-lockout)** および **[CAPTCHA](/security/captcha)** ポリシー（これらは送信時ではなく、認証失敗時の試行回数を制限します） +- テナントごとのグローバル API レート制限（エラーコード `request.rate_limited`、これはテナント全体のリクエスト量を制限します） + +## 動作概要 \{#how-it-works} + +- **受信者ごとの上限**：Logto は、同じ受信者（メールアドレスまたは電話番号）に対して、短いローリング時間枠内で送信できるメッセージ数を制限します。デフォルトでは、**10 分間に受信者ごとに最大 10 回送信** できます。 +- **適用範囲**：すべてのサーバーサイド送信経路（Experience API や Account API の認証コード送信［サインイン、登録、パスワードリセット、多要素認証 (MFA)、識別子バインディング］、Management API の認証コード送信、組織招待の送信・再送、Account（`/me`）の認証コード送信など） +- **上限超過時**：リクエストは HTTP `429` で拒否され、エラーコード `request.message_rate_limited` が返されます。これはグローバルテナントリミッター（`request.rate_limited`）や認証時ロックアウト（`session.verification_blocked_too_many_attempts`）とは異なるため、統合時に個別に処理できます。 + +## Webhook でレート制限送信を監視する \{#monitor-rate-limited-sends-with-a-webhook} + +**エンドユーザー** が受信者ごとの上限に達した場合、Logto は `Message.RateLimited` [Webhook イベント](/developers/webhooks/webhooks-events#exception-hook-events) をトリガーします。これにより、送信の悪用を検知・対応できます。 + +- **発火対象**：エンドユーザーの認証コード送信経路のみ（Experience API および Account API）。ファーストパーティや管理者による送信（Management API の認証コード、組織招待、`/me` など）には発火しません。 +- **ペイロード**：フックコンテキストには `action`（例：`VerificationCodeSend`）と `recipient`（メールアドレスまたは電話番号）が含まれます。 + +**主なユースケース：** + +- セキュリティアラートをチームに送信して確認する +- 対象受信者に対する下流の悪用防止自動化をトリガーする + +コンソール > Webhooks +から購読するか、Management API でフックを作成できます。詳細なイベント構造や設定については +[Webhooks](/developers/webhooks) を参照してください。 + +## 未登録受信者への配信抑制 \{#suppressed-delivery-to-unknown-recipients} + +アカウント列挙攻撃を防ぐため、識別子によるサインアップが無効な場合、メールアドレスや電話番号に対して **アカウントが存在しない** 場合は、サインイン認証コードのリクエストがあっても静かに配信されず、API は実際の送信時と同じ応答を返します。これにより、攻撃者は応答から登録済みアドレスを特定できません。既存ユーザーへの配信には影響しません。詳細は [アカウント存在の非表示](/end-user-flows/sign-up-and-sign-in) も参照してください。 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/README.mdx index e285ef991de..b57d0d502e0 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -1,6 +1,6 @@ # 개발자 -Logto는 [OAuth 2](https://auth.wiki/oauth-2.0) 및 [OIDC](https://auth.wiki/openid-connect) 프로토콜을 기반으로 한 [아이덴티티 및 접근 관리 (IAM)](https://auth.wiki/iam) 서비스입니다. Logto와 같은 IAM 서비스는 종종 다른 웹 서비스의 기반이 되며, 해당 웹 서비스 내의 다양한 인가 (Authorization) 상태는 Logto에 의해 직접적으로 영향을 받습니다. +Logto는 [OAuth 2](https://auth.wiki/oauth-2.0) 및 [OIDC](https://auth.wiki/openid-connect) 프로토콜을 기반으로 한 [아이덴티티 및 접근 관리 (IAM)](https://auth.wiki/iam) 서비스입니다. Logto와 같은 IAM 서비스는 종종 다른 웹 서비스의 기반 역할을 하며, 해당 웹 서비스 내의 다양한 인가 (Authorization) 상태는 Logto에 의해 직접적으로 영향을 받습니다. 사용자에게 편의를 제공하기 위해, Logto는 자주 사용되는 개발자 기능들을 제공합니다. @@ -44,6 +44,15 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; icon: , } }, + { + type: 'link', + label: '서비스 간 위임 (Service-to-service delegation)', + href: '/developers/service-to-service-delegation', + description: '사용자 액세스 토큰을 다운스트림 API 액세스 토큰으로 교환하여 백엔드 서비스가 현재 사용자를 대신해 동작할 수 있도록 합니다.', + customProps: { + icon: , + } + }, ]} /> ``` @@ -57,7 +66,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '서명 키 (Signing keys)', href: '/developers/signing-keys', - description: '시스템 레벨의 서명 키를 제공하며, 패스워드 금고를 통해 인증 (Authentication) 서비스를 더욱 안전하게 만듭니다.', + description: '시스템 수준의 서명 키를 비밀번호 금고를 통해 제공하여 인증 (Authentication) 서비스를 더욱 안전하게 만듭니다.', customProps: { icon: , } @@ -66,7 +75,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhook', href: '/developers/webhooks', - description: 'Webhook은 HTTP 요청을 통해 사용자 정보 및 권한 (Permission) 업데이트에 대한 실시간 알림을 지원하여, Logto 통합의 편의성과 유연성을 높입니다.', + description: 'Webhook은 HTTP 요청을 통해 사용자 정보 및 권한 (Permission) 업데이트에 대한 실시간 알림을 지원하여 Logto 통합의 편의성과 유연성을 높입니다.', customProps: { icon: , } @@ -75,7 +84,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '감사 로그 (Audit logs)', href: '/developers/audit-logs', - description: '사용자 인증 (Authentication) 관련 활동을 기록하여, 디버깅 및 사용자 활동 분석을 용이하게 합니다.', + description: '사용자 인증 (Authentication) 관련 활동을 기록하여 디버깅 및 사용자 활동 분석을 용이하게 합니다.', customProps: { icon: , } @@ -84,7 +93,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'SDK 규약 (SDK convention)', href: '/developers/', - description: 'SDK 내 데이터 구조, 목적, 메서드를 소개하여 사용자가 다양한 비즈니스 시나리오에 맞게 SDK를 커스터마이즈할 수 있도록 합니다.', + description: 'SDK의 데이터 구조, 목적, 메서드를 소개하여 사용자가 다양한 비즈니스 시나리오에 맞게 SDK를 커스터마이즈할 수 있도록 합니다.', customProps: { icon: , } diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index dc1ba451858..5e35926c145 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # 감사 로그 @@ -21,7 +21,7 @@ Logto의 감사 로그를 통해 사용자 활동과 이벤트를 쉽게 모니 Logto의 로그는 포괄적인 세부 정보를 제공하여 조치의 용이성과 고객의 안전을 보장합니다. 다음 정보를 캡처하고 기록합니다: -- 이벤트 유형 ([감사 로그 이벤트 전체 목록은 여기에서 확인하세요](/developers/audit-logs/event-types)) +- 이벤트 유형 (감사 로그 이벤트 전체 목록은 [여기](/developers/audit-logs/event-types)에서 확인 가능) - 관련 애플리케이션 - IP 주소 - 관련 사용자 @@ -41,7 +41,7 @@ Logto의 로그는 포괄적인 세부 정보를 제공하여 조치의 용이 1. 콘솔 > 사용자 관리로 이동합니다. 2. 원하는 사용자를 선택하고 상세 페이지로 이동합니다. -3. "사용자 로그"를 클릭합니다. 해당 표에는 해당 사용자가 수행하고 트리거한 로그 이벤트만 표시됩니다. +3. "사용자 로그"를 클릭합니다. 해당 표에는 해당 사용자가 수행 및 트리거한 로그 이벤트만 표시됩니다. -OSS 사용자는 정기적으로 오래된 감사 로그를 정리하는 크론잡을 추가해야 합니다. +OSS 사용자는 주기적으로 오래된 감사 로그를 정리하는 크론잡을 추가해야 합니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index f3e7e911c73..5b40902fe3b 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,18 +2,18 @@ id: sdk-conventions title: 플랫폼 SDK 규약 sidebar_label: 플랫폼 SDK 규약 -sidebar_position: 8 +sidebar_position: 9 --- # 플랫폼 SDK 규약 Logto는 매우 강력하고 유연한 웹 인증 (Authentication) 서비스를 제공합니다. -실제 Logto 서비스를 사용할 때, 개발자는 사용자 로그인 상태, 권한 등 관리를 위해 Logto SDK를 자신의 클라이언트 애플리케이션에 통합하는 것이 편리합니다. +실제 Logto 서비스를 사용할 때, 개발자는 사용자 로그인 상태, 권한 (Permissions) 등을 관리하기 위해 Logto SDK를 자신의 클라이언트 애플리케이션에 통합하는 것이 편리합니다. Logto에서 지원하는 모든 프로그래밍 언어 / 프레임워크용 SDK는 [여기](/quick-starts)에서 확인할 수 있습니다. -원하는 SDK가 없다면, 아래의 규약을 참고하여 원하는 프로그래밍 언어용 SDK를 직접 구현할 수 있습니다. 이를 통해 Logto 서비스를 더 쉽게 사용할 수 있습니다. +원하는 SDK를 찾지 못했다면, 원하는 프로그래밍 언어용 SDK를 직접 구현할 때 참고할 수 있는 규약이 아래에 있습니다. 이를 따르면 Logto 서비스를 더 쉽게 사용할 수 있습니다. 이 규약은 세 가지 주요 부분으로 구성되어 있습니다: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..a59a5b33dc8 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: 서비스 간 위임 +sidebar_label: 서비스 간 위임 +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# 서비스 간 위임 + +일부 API 아키텍처에서는 백엔드 서비스가 로그인한 사용자로부터 요청을 받고, 사용자의 아이덴티티를 유지한 채로 다른 백엔드 서비스를 호출해야 할 때가 있습니다. + +예시: + +```text +User -> API A -> API B +``` + +API B는 두 가지를 알아야 합니다: + +1. 호출자가 신뢰할 수 있는 서비스(예: API A)임을 확인해야 합니다. +2. 해당 작업이 원래 사용자에 대해 수행되고 있음을 알아야 합니다. + +Logto의 토큰 교환 그랜트(token exchange grant)를 사용하여 사용자의 액세스 토큰을 다운스트림 API 리소스를 대상으로 하는 새로운 액세스 토큰으로 교환하세요. 이는 OAuth 2.0 토큰 교환 패턴을 따르며, 원래 사용자 토큰을 다운스트림 서비스로 전달하는 것을 방지합니다. + +## 이 플로우를 사용할 때 \{#when-to-use-this-flow} + +서비스 간 위임은 다음과 같은 경우에 사용하세요: + +- API A가 Logto의 토큰 엔드포인트에 안전하게 인증할 수 있는 백엔드 서비스일 때. +- API A가 Logto에서 발급한 사용자 액세스 토큰을 받을 때. +- API A가 동일한 사용자를 대신하여 API B를 호출해야 할 때. +- API B가 자신의 API 리소스를 대상으로 하는 하나의 액세스 토큰을 검증해야 할 때. + +사용자가 없는 순수 기계 간(M2M) 접근에는 이 플로우를 사용하지 마세요. 이 경우 [클라이언트 크리덴셜 플로우](/quick-starts/m2m)를 사용하세요. 한 사용자가 일시적으로 다른 사용자를 대신하는 지원, 관리자, 에이전트 시나리오에는 [사용자 가장](/developers/user-impersonation)을 사용하세요. + +## 작동 방식 \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as 사용자 + participant ApiA as API A + participant Logto as Logto 토큰 엔드포인트 + participant ApiB as API B + + User->>ApiA: Authorization: Bearer 사용자 액세스 토큰 + Note over ApiA: API A용 사용자 토큰을 검증 + + ApiA->>Logto: POST /oidc/token (토큰 교환 그랜트 사용) + Note over ApiA,Logto: subject_token = 사용자 액세스 토큰
resource = API B 리소스 지표 + + Logto-->>ApiA: API B용 액세스 토큰 반환 + ApiA->>ApiB: Authorization: Bearer 교환된 액세스 토큰 + Note over ApiB: 발급자, 대상, 만료, 스코프 검증 +``` + +교환된 액세스 토큰은 원래 사용자(`sub`)를 나타내며, 다운스트림 API 리소스(`aud`)에 바인딩됩니다. 다운스트림 API는 `client_id` 클레임을 확인하여 교환을 시작한 애플리케이션을 식별할 수도 있습니다. + +## 사전 준비 사항 \{#prerequisites} + +1. 관련 서비스에 대한 API 리소스를 생성하세요. [글로벌 API 리소스 보호하기](/authorization/global-api-resources) 참고. +2. API B의 권한을 구성하고, 역할 또는 조직 역할을 통해 사용자에게 할당하세요. +3. API A는 서버 측 애플리케이션(기계 간 앱 또는 전통적인 웹 앱 등)이어야 하며, 앱 시크릿으로 안전하게 인증할 수 있어야 합니다. +4. API A 애플리케이션에 토큰 교환을 활성화하세요. + + + +## 다운스트림 API용 액세스 토큰 요청하기 \{#request-an-access-token-for-the-downstream-api} + +API A가 API B를 호출해야 할 때, Logto의 [토큰 엔드포인트](/integrate-logto/application-data-structure#token-endpoint)에 토큰 교환 요청을 하세요. + +전통적인 웹 애플리케이션 또는 앱 시크릿이 있는 기계 간 애플리케이션의 경우, 크리덴셜을 `Authorization` 헤더에 포함하세요: + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +파라미터: + +1. `grant_type`: `urn:ietf:params:oauth:grant-type:token-exchange` 사용. +2. `subject_token`: API A가 받은 Logto 발급 사용자 액세스 토큰. +3. `subject_token_type`: `urn:ietf:params:oauth:token-type:access_token` 사용. +4. `resource`: API B의 API 리소스 지표. +5. `scope`: 이 위임 호출에 대해 API A가 요청하는 다운스트림 권한. Logto는 RBAC 설정에 따라 원래 사용자가 이 리소스에 대해 가질 수 있는 요청된 스코프만 발급합니다. + +Logto는 API B용 액세스 토큰을 반환합니다: + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +디코딩하면 액세스 토큰에는 다음과 유사한 클레임이 포함됩니다: + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +이후 API A는 교환된 토큰으로 API B를 호출합니다: + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## API B에서 토큰 검증하기 \{#validate-the-token-in-api-b} + +API B는 교환된 토큰을 Logto에서 발급한 API 리소스 액세스 토큰과 동일하게 검증해야 합니다: + +1. Logto의 JWKs를 사용하여 서명을 검증하세요. +2. 발급자(`iss`)를 확인하세요. +3. 대상(`aud`)이 API B의 리소스 지표와 일치하는지 확인하세요. +4. 만료(`exp`)를 확인하세요. +5. 필요한 스코프를 확인하세요. +6. `sub`를 원래 사용자 ID로 사용하세요. +7. 특정 업스트림 서비스만 위임 호출을 허용해야 하는 경우, 선택적으로 `client_id`를 확인하세요. + +구현 가이드는 [API에서 액세스 토큰 검증하기](/authorization/validate-access-tokens)를 참고하세요. + +## 관련 리소스 \{#related-resources} + +글로벌 API 리소스 보호하기 + +API에서 액세스 토큰 검증하기 + +사용자 가장 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index e5024b8fe93..06cb62673d8 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,14 +2,14 @@ id: signing-keys title: 서명 키 sidebar_label: 서명 키 -sidebar_position: 5 +sidebar_position: 6 --- # 서명 키 -Logto [OIDC 서명 키](https://auth.wiki/signing-key)는 "OIDC 개인 키" 또는 "OIDC 쿠키 키"라고도 불리며, Logto [로그인 세션](/sessions#what-is-a-logto-session)에서 JWT ([액세스 토큰](https://auth.wiki/access-token) 및 [ID 토큰](https://auth.wiki/id-token))과 브라우저 쿠키를 서명하는 데 사용되는 서명 키입니다. 이러한 서명 키는 Logto 데이터베이스를 시드할 때 ([오픈소스](/logto-oss)) 또는 새 테넌트를 생성할 때 ([Cloud](/logto-cloud)) 생성되며, [CLI](/logto-oss/using-cli) (오픈소스), Management API 또는 Console UI를 통해 관리할 수 있습니다. +Logto [OIDC 서명 키](https://auth.wiki/signing-key)는 "OIDC 개인 키" 또는 "OIDC 쿠키 키"라고도 하며, Logto [로그인 세션](/sessions#what-is-a-logto-session)에서 JWT([액세스 토큰](https://auth.wiki/access-token) 및 [ID 토큰](https://auth.wiki/id-token))과 브라우저 쿠키를 서명하는 데 사용되는 서명 키입니다. 이 서명 키는 Logto 데이터베이스를 시드할 때([오픈소스](/logto-oss)) 또는 새 테넌트를 생성할 때([Cloud](/logto-cloud)) 생성되며, [CLI](/logto-oss/using-cli) (오픈소스), Management API 또는 Console UI를 통해 관리할 수 있습니다. -기본적으로 Logto는 타원 곡선 (EC) 알고리즘을 사용하여 디지털 서명을 생성합니다. 하지만 사용자가 JWT 서명을 검증해야 하는 경우가 많고, 많은 구버전 도구들이 EC 알고리즘을 지원하지 않고 RSA만 지원하기 때문에, 개인 키를 교체(로테이션)하고 서명 알고리즘(RSA 및 EC 모두 포함)을 선택할 수 있는 기능을 구현했습니다. 이를 통해 구식 서명 검증 도구를 사용하는 서비스와의 호환성을 보장합니다. +기본적으로 Logto는 타원 곡선(EC) 알고리즘을 사용하여 디지털 서명을 생성합니다. 하지만 사용자가 JWT 서명을 검증해야 하는 경우가 많고, 많은 구형 도구들이 EC 알고리즘을 지원하지 않고 RSA만 지원하는 점을 고려하여, 개인 키를 교체(로테이션)하고 서명 알고리즘(RSA와 EC 모두 포함)을 선택할 수 있는 기능을 구현했습니다. 이를 통해 구식 서명 검증 도구를 사용하는 서비스와의 호환성을 보장합니다. :::note 이론적으로 서명 키는 유출되어서는 안 되며 만료 시간이 없으므로 교체할 필요가 없습니다. 그러나 일정 기간 후에 주기적으로 서명 키를 교체하면 보안을 강화할 수 있습니다. @@ -18,34 +18,34 @@ Logto [OIDC 서명 키](https://auth.wiki/signing-key)는 "OIDC 개인 키" 또 ## 동작 방식 \{#how-it-works} - **OIDC 개인 키** - Logto 인스턴스를 초기화할 때, 공개 키와 개인 키 쌍이 자동으로 생성되어 기본 OIDC 제공자에 등록됩니다. 따라서 Logto가 새로운 JWT(액세스 토큰 또는 ID 토큰)를 발급할 때, 해당 토큰은 개인 키로 서명됩니다. 동시에, JWT를 수신하는 모든 클라이언트 애플리케이션은 쌍으로 제공되는 공개 키를 사용하여 토큰 서명을 검증할 수 있으므로, 토큰이 제3자에 의해 변조되지 않았음을 보장할 수 있습니다. 개인 키는 Logto 서버에서 안전하게 보호됩니다. 반면, 공개 키는 이름 그대로 모두에게 공개되어 있으며, OIDC 엔드포인트의 `/oidc/jwks` 인터페이스를 통해 접근할 수 있습니다. 개인 키를 생성할 때 서명 키 알고리즘을 지정할 수 있으며, Logto는 기본적으로 EC (타원 곡선) 알고리즘을 사용합니다. 관리자는 개인 키를 교체(로테이션)하여 기본 알고리즘을 RSA (Rivest-Shamir-Adleman)로 변경할 수 있습니다. + Logto 인스턴스를 초기화할 때, 공개 키와 개인 키 쌍이 자동으로 생성되어 기본 OIDC 제공자에 등록됩니다. 따라서 Logto가 새로운 JWT(액세스 토큰 또는 ID 토큰)를 발급할 때, 해당 토큰은 개인 키로 서명됩니다. 동시에 JWT를 수신하는 모든 클라이언트 애플리케이션은 쌍으로 제공되는 공개 키를 사용하여 토큰 서명을 검증할 수 있으므로, 토큰이 제3자에 의해 변조되지 않았음을 확인할 수 있습니다. 개인 키는 Logto 서버에서 보호됩니다. 반면, 공개 키는 이름 그대로 모두에게 공개되며, OIDC 엔드포인트의 `/oidc/jwks` 인터페이스를 통해 접근할 수 있습니다. 개인 키를 생성할 때 서명 키 알고리즘을 지정할 수 있으며, Logto는 기본적으로 EC(타원 곡선) 알고리즘을 사용합니다. 관리자는 개인 키를 교체(로테이션)하여 기본 알고리즘을 RSA(Rivest-Shamir-Adleman)로 변경할 수 있습니다. - **OIDC 쿠키 키** - 사용자가 로그인 또는 회원가입 플로우를 시작하면, 서버에 "OIDC 세션"이 생성되고 브라우저 쿠키 세트도 함께 생성됩니다. 이 쿠키를 통해 브라우저는 Logto Experience API에 요청하여 로그인, 회원가입, 비밀번호 재설정 등 일련의 상호작용을 사용자를 대신해 수행할 수 있습니다. 하지만 JWT와 달리, 쿠키는 Logto OIDC 서비스 자체에서만 서명 및 검증되며, 비대칭 암호화가 필요하지 않습니다. 따라서 쿠키 서명 키에는 쌍으로 된 공개 키가 없으며, 비대칭 암호화 알고리즘도 사용하지 않습니다. + 사용자가 로그인 또는 회원가입 플로우를 시작하면, 서버에서 "OIDC 세션"이 생성되고 브라우저 쿠키 세트도 함께 생성됩니다. 이 쿠키를 통해 브라우저는 Logto Experience API에 요청하여 로그인, 회원가입, 비밀번호 재설정 등 일련의 상호작용을 사용자를 대신해 수행할 수 있습니다. 하지만 JWT와 달리, 쿠키는 Logto OIDC 서비스 자체에서만 서명 및 검증되며, 비대칭 암호화가 필요하지 않습니다. 따라서 쿠키 서명 키에는 쌍으로 된 공개 키가 없으며, 비대칭 암호화 알고리즘도 사용하지 않습니다. ## Console UI에서 서명 키 교체하기 \{#rotate-signing-keys-from-console-ui} -Logto는 "서명 키 교체" 기능을 도입하여, 테넌트 내에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있도록 합니다. +Logto는 "서명 키 교체" 기능을 도입하여, 테넌트 내에서 새로운 OIDC 개인 키와 쿠키 키를 생성할 수 있습니다. 1. Console > 테넌트 설정 > OIDC 설정으로 이동하세요. 여기서 OIDC 개인 키와 OIDC 쿠키 키를 모두 관리할 수 있습니다. 2. 서명 키를 교체하려면 "개인 키 교체" 또는 "쿠키 키 교체" 버튼을 클릭하세요. 개인 키를 교체할 때는 서명 알고리즘을 변경할 수도 있습니다. 3. 사용 중인 모든 서명 키가 나열된 테이블을 확인할 수 있습니다. OIDC 개인 키의 경우, 이전 키는 삭제할 수 있지만 현재 키나 다음 키는 삭제할 수 없습니다. OIDC 쿠키 키의 경우, 이전 키는 삭제할 수 있지만 현재 키는 삭제할 수 없습니다. - | 상태 | 설명 | - | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | Next | 이 상태는 단계적 OIDC 개인 키 교체를 위한 것입니다. 키가 생성되었지만, 유예 기간이 끝나고 키가 활성화될 때까지 Logto는 이 키로 새로운 JWT를 서명하지 않습니다. | - | Current | 이 키가 현재 Logto에서 새로 발급되는 JWT 또는 쿠키를 서명하는 데 사용되고 있음을 나타냅니다. | - | Previous | 이전에 사용되었으나 교체된 키를 의미합니다. 이 키로 서명된 기존 JWT 또는 쿠키는 만료되거나 키가 삭제될 때까지 유효합니다. | + | 상태 | 설명 | + | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | + | Next | 단계적 OIDC 개인 키 교체를 위한 상태입니다. 키가 생성되었지만, 유예 기간이 끝나고 키가 활성화될 때까지 Logto는 이 키로 새로운 JWT를 서명하지 않습니다. | + | Current | 현재 Logto가 새로 발급하는 JWT 또는 쿠키를 서명하는 데 사용되는 키임을 나타냅니다. | + | Previous | 이전에 사용되었으나 교체(로테이션)된 키를 의미합니다. 이 키로 서명된 기존 JWT 또는 쿠키는 만료되거나 키가 삭제될 때까지 유효합니다. | -교체(로테이션)는 다음 세 가지 작업을 포함한다는 점을 기억하세요: +교체(로테이션)는 다음 세 가지 작업을 포함함을 기억하세요: -1. **새 서명 키 생성**: OIDC 개인 키의 경우, Logto는 새 키를 먼저 "Next"로 준비할 수 있으므로, 애플리케이션과 API가 새 키가 서명에 사용되기 전에 `/oidc/jwks` 엔드포인트에서 공개 키를 갱신할 시간을 가질 수 있습니다. -2. **현재 키 교체**: 교체가 활성화되면, "Next" 키가 "Current"가 되고, 기존 "Current" 키는 "Previous"가 됩니다. 이전 키로 서명된 토큰은 여전히 유효합니다. -3. **가장 오래된 이전 키 삭제**: Logto는 최대 한 개의 "Previous" 개인 키만 유지합니다. 준비된 키가 현재 키가 될 때 이미 이전 개인 키가 존재한다면, 더 오래된 이전 키는 삭제됩니다. +1. **새 서명 키 생성**: OIDC 개인 키의 경우, Logto는 새 키를 먼저 "Next"로 준비할 수 있으므로, 애플리케이션과 API가 새 키로 서명되기 전에 `/oidc/jwks` 엔드포인트에서 공개 키를 갱신할 시간을 가질 수 있습니다. +2. **현재 키 교체**: 교체가 적용되면 "Next" 키가 "Current"가 되고, 기존 "Current" 키는 "Previous"가 됩니다. 이전 키로 서명된 토큰은 여전히 유효합니다. +3. **가장 오래된 이전 키 삭제**: Logto는 최대 하나의 "Previous" 개인 키만 유지합니다. 준비된 키가 "Current"가 될 때 이미 이전 개인 키가 존재한다면, 더 오래된 이전 키는 삭제됩니다. -Logto Cloud의 경우, OIDC 개인 키 교체는 4시간의 유예 기간 후에 적용됩니다. 이 기간 동안 새 키가 준비되어 JWKS를 통해 노출되며, Logto가 새로 발급되는 JWT를 해당 키로 서명하기 시작하기 전까지 유지됩니다. Console 테이블의 **Effective at** 열에서 준비된 "Next" 키가 "Current"가 되는 시점을 확인할 수 있습니다. +Logto Cloud의 경우, OIDC 개인 키 교체는 4시간의 유예 기간 후에 적용됩니다. 이 기간 동안 새 키가 준비되어 JWKS를 통해 노출되며, Logto가 새로 발급하는 JWT를 해당 키로 서명하기 전까지 대기합니다. Console 테이블의 **적용 시점(Effective at)** 열에서 준비된 "Next" 키가 "Current"가 되는 시점을 확인할 수 있습니다. -셀프 호스팅 OSS 배포의 경우, 기본 개인 키 교체 유예 기간은 `0`초로, 즉시 교체가 이루어집니다. 단계적 교체를 사용하려면 Logto 서비스에서 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 환경 변수를 설정하거나, Management API 엔드포인트 `POST /api/configs/oidc/private-keys/rotate` 호출 시 요청 본문에 명시적으로 `rotationGracePeriod` 값을 전달하세요. +셀프 호스팅 OSS 배포의 경우, 기본 개인 키 교체 유예 기간은 `0`초로, 즉시 교체가 이루어집니다. 단계적 교체를 사용하려면 Logto 서비스의 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 환경 변수를 설정하거나, Management API 엔드포인트 `POST /api/configs/oidc/private-keys/rotate` 호출 시 요청 본문에 명시적으로 `rotationGracePeriod` 값을 전달하세요. :::warning 대기 중인 교체가 적용되기 전에 반복적으로 서명 키를 교체하지 마세요. 의도적으로 준비된 "Next" 키를 교체하려는 경우가 아니라면 피해야 합니다. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 4da505e1475..7e2ff290e7a 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,12 +1,12 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhook Logto [Webhook](https://auth.wiki/webhook)은 사용자 계정, 역할, 권한, 조직, 조직 역할, 조직 권한, 그리고 [사용자 상호작용](/end-user-flows) 등 다양한 이벤트에 대한 실시간 알림을 제공합니다. -이벤트가 발생하면, Logto는 여러분이 제공한 Endpoint URL로 HTTP 요청을 보내며, 이 요청에는 사용자 ID, 사용자명, 이메일 등 이벤트에 대한 상세 정보가 포함되어 있습니다 (페이로드 및 헤더에 포함된 데이터에 대한 자세한 내용은 [Webhook 요청](/developers/webhooks/webhooks-request)을 참조하세요). 여러분의 애플리케이션은 이 요청을 처리하여 이메일 발송, 데이터베이스 내 데이터 업데이트 등 맞춤형 작업을 수행할 수 있습니다. +이벤트가 발생하면, Logto는 여러분이 제공한 Endpoint URL로 HTTP 요청을 전송하며, 이 요청에는 사용자 ID, 사용자명, 이메일 등 이벤트에 대한 상세 정보가 포함되어 있습니다 (페이로드 및 헤더에 포함된 데이터에 대한 자세한 내용은 [Webhook 요청](/developers/webhooks/webhooks-request)을 참조하세요). 여러분의 애플리케이션은 이 요청을 처리하여 이메일 발송, 데이터베이스 데이터 업데이트 등 맞춤형 작업을 수행할 수 있습니다. 우리는 사용자 요구에 따라 더 많은 이벤트를 지속적으로 추가하고 있습니다. 비즈니스에 대한 구체적인 요구 사항이 있다면 언제든 알려주세요. @@ -16,19 +16,19 @@ Webhook은 애플리케이션 간 실시간 통신을 제공하여 폴링이 필 다음은 CIAM에서 일반적인 Webhook 사용 사례의 예시입니다: -- **이메일 발송:** Webhook을 구성하여 신규 사용자가 등록할 때 환영 이메일을 보내거나, 사용자가 새로운 기기 또는 위치에서 로그인할 때 관리자가 알림을 받도록 할 수 있습니다. +- **이메일 발송:** Webhook을 구성하여 신규 사용자가 등록할 때 환영 이메일을 보내거나, 사용자가 새로운 기기나 위치에서 로그인할 때 관리자를 알릴 수 있습니다. - **알림 전송:** Webhook을 구성하여 사용자가 가입할 때 CRM 시스템과 연동된 가상 비서를 호출하여 실시간 고객 지원을 제공할 수 있습니다. -- **추가 API 호출 수행:** Webhook을 구성하여 사용자의 이메일 도메인 또는 IP 주소를 확인한 후, Logto Management API를 사용해 리소스 권한이 포함된 적절한 역할을 할당할 수 있습니다. +- **추가 API 호출 수행:** Webhook을 구성하여 사용자의 이메일 도메인이나 IP 주소를 확인한 뒤, Logto Management API를 사용해 리소스 권한이 포함된 적절한 역할을 할당할 수 있습니다. - **데이터 동기화:** Webhook을 구성하여 사용자 계정 정지 또는 삭제와 같은 변경 사항을 애플리케이션에 실시간으로 반영할 수 있습니다. -- **리포트 생성:** Webhook을 설정하여 사용자 로그인 활동 데이터를 수신하고, 이를 활용해 사용자 참여도 또는 사용 패턴에 대한 리포트를 생성할 수 있습니다. +- **리포트 생성:** Webhook을 설정하여 사용자 로그인 활동 데이터를 수신하고, 이를 활용해 사용자 참여도나 사용 패턴에 대한 리포트를 생성할 수 있습니다. ## 용어 \{#terms} -| Item | Description | -| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Event | 특정 작업이 수행되면, 특정 타입의 hook 이벤트가 트리거됩니다. 예: 사용자가 회원가입을 완료하고 새 계정을 생성하면 Logto는 PostRegister hook 이벤트를 발생시킵니다. | -| Hook | 특정 이벤트에 연결된 하나 또는 일련의 작업입니다. 작업에는 API 호출, 코드 스니펫 실행 등이 포함될 수 있습니다. | -| Webhook | 이벤트 페이로드와 함께 API를 호출하는 hook의 하위 유형입니다. | +| Item | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Event | 특정 작업이 수행되면, 해당 작업에 맞는 타입의 hook 이벤트가 트리거됩니다. 예: 사용자가 회원가입을 완료하고 새 계정을 생성하면 Logto는 PostRegister hook 이벤트를 발생시킵니다. | +| Hook | 특정 이벤트에 연결된 하나 또는 일련의 작업입니다. 작업에는 API 호출, 코드 스니펫 실행 등이 포함될 수 있습니다. | +| Webhook | 이벤트 페이로드와 함께 API를 호출하는 hook의 하위 유형입니다. | | 예를 들어, 개발자가 사용자가 새로운 기기로 로그인할 때 알림을 보내고 싶다면, PostSignIn 이벤트에 자신의 보안 서비스 API를 호출하는 webhook을 추가할 수 있습니다. | 다음은 Logto에서 `PostSignIn` 이벤트에 대해 두 개의 웹훅을 활성화하는 예시입니다: @@ -37,7 +37,7 @@ Webhook은 애플리케이션 간 실시간 통신을 제공하여 폴링이 필 graph LR subgraph Logto SF(로그인 완료) - PS(로그인 후) + PS(Post sign-in) WH2(Web hook 2) WH1(Web hook 1) end @@ -63,11 +63,11 @@ graph LR
-### Logto는 동기화된 webhook을 지원하나요? \{#does-logto-support-synced-webhooks} +### Logto는 동기 Webhook을 지원하나요? \{#does-logto-support-synced-webhooks} -동기화된 webhook이 사용자 로그인 흐름을 더 원활하게 만들 수 있지만, 아직 지원하지 않습니다 (향후 지원 예정). 따라서 현재 동기화된 webhook에 의존하는 시나리오는 모두 별도의 우회 방법이 필요합니다. 궁금한 점이 있다면 언제든 문의해 주세요. +동기 Webhook이 사용자 로그인 플로우를 더 원활하게 만들 수 있지만, 아직 지원하지 않습니다 (향후 지원 예정). 따라서 현재 동기 Webhook에 의존하는 시나리오는 모두 별도의 우회 방법이 필요합니다. 궁금한 점이 있으면 언제든 문의해 주세요.
@@ -85,11 +85,11 @@ graph LR
-### webhook 타임아웃을 어떻게 디버깅하나요? \{#how-to-debug-webhook-timeout} +### Webhook 타임아웃을 어떻게 디버깅하나요? \{#how-to-debug-webhook-timeout} -Webhook을 수신하는 엔드포인트는 Logto에 Webhook이 성공적으로 수신되었음을 알리기 위해 가능한 한 빨리 2xx 응답을 반환해야 합니다. 사용자마다 Webhook 처리 로직이 매우 다르기 때문에, 지나치게 복잡한 작업은 몇 초가 걸릴 수 있어 Logto Webhook이 타임아웃될 수 있습니다. 최선의 방법은 자체 이벤트 큐를 유지하는 것입니다. Logto Webhook을 수신하면 이벤트를 큐에 삽입하고 Logto에 2xx 응답을 반환하세요. 이후 자체 워커가 큐의 작업을 단계별로 처리하도록 하세요. 워커에서 오류가 발생하면 자체 서버에서 처리하면 됩니다. +Webhook을 수신하는 엔드포인트는 Webhook이 성공적으로 수신되었음을 Logto에 알리기 위해 가능한 한 빨리 2xx 응답을 반환해야 합니다. 사용자마다 Webhook 처리 로직이 매우 다르기 때문에, 지나치게 복잡한 작업은 몇 초가 걸릴 수 있어 Logto Webhook이 타임아웃될 수 있습니다. 최선의 방법은 자체 이벤트 큐를 유지하는 것입니다. Logto Webhook을 수신하면 이벤트를 큐에 삽입하고 Logto에 2xx 응답을 반환하세요. 이후 자체 워커가 큐의 작업을 단계별로 처리하도록 하세요. 워커에서 오류가 발생하면 자체 서버에서 처리하세요.
diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index 61147f38af5..0b178ff5291 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -7,69 +7,69 @@ sidebar_position: 3 # Webhooks 이벤트 -이 가이드는 다양한 Logto webhook 이벤트를 나열하고 각 이벤트가 발생하는 시점을 설명합니다. +이 가이드에서는 다양한 Logto Webhook 이벤트를 나열하고 각 이벤트가 언제 발생하는지 설명합니다. ## 사용자 상호작용 훅 이벤트 \{#user-interaction-hook-events} -| 이벤트 유형 | 설명 | -| ----------------- | ------------------------------------------------------------------------ | -| PostRegister | 사용자가 UI 인터페이스를 통해 새 계정을 성공적으로 생성합니다. | -| PostSignIn | 사용자가 UI 인터페이스를 통해 성공적으로 로그인합니다. | -| PostResetPassword | 사용자의 비밀번호가 "비밀번호 찾기" 흐름을 통해 성공적으로 재설정됩니다. | +| 이벤트 타입 | 설명 | +| ----------------- | -------------------------------------------------------------------------------------- | +| PostRegister | 사용자가 UI 인터페이스를 통해 새 계정을 성공적으로 생성했을 때 발생합니다. | +| PostSignIn | 사용자가 UI 인터페이스를 통해 성공적으로 로그인했을 때 발생합니다. | +| PostResetPassword | 사용자가 "비밀번호 찾기" 플로우를 통해 비밀번호를 성공적으로 재설정했을 때 발생합니다. | -## 데이터 변형 훅 이벤트 \{#data-mutation-hook-events} +## 데이터 변경 훅 이벤트 \{#data-mutation-hook-events} ### 사용자 \{#user} -| 이벤트 유형 | 설명 | -| ----------------------------- | --------------------------------------------------------------------------------------- | -| User.Created | 새 사용자 계정이 생성됩니다. | -| User.Deleted | 사용자 계정이 삭제됩니다. | -| User.Data.Updated | 사용자 프로필 데이터가 업데이트됩니다. 예: 이메일, 아바타, custom.data, 소셜 식별자 등. | -| User.SuspensionStatus.Updated | 사용자 정지 상태가 변경됩니다 (정지 또는 재활성화). | +| 이벤트 타입 | 설명 | +| ----------------------------- | ------------------------------------------------------------------------------------------- | +| User.Created | 새 사용자 계정이 생성되었습니다. | +| User.Deleted | 사용자 계정이 삭제되었습니다. | +| User.Data.Updated | 사용자 프로필 데이터가 업데이트되었습니다. 예: 이메일, 아바타, custom.data, 소셜 식별자 등. | +| User.SuspensionStatus.Updated | 사용자 정지 상태가 변경되었습니다 (정지 또는 재활성화). | -### 역할 \{#role} +### 역할(Role) \{#role} -| 이벤트 유형 | 설명 | -| ------------------- | -------------------------------------------------------------------- | -| Role.Created | 새 역할이 생성됩니다. | -| Role.Deleted | 역할이 삭제됩니다. | -| Role.Data.Updated | 역할의 데이터가 업데이트됩니다. 예: 역할 이름, 설명, 기본 역할 상태. | -| Role.Scopes.Updated | 역할에 할당된 권한이 추가되거나 제거됩니다. | +| 이벤트 타입 | 설명 | +| ------------------- | --------------------------------------------------------------------------- | +| Role.Created | 새 역할이 생성되었습니다. | +| Role.Deleted | 역할이 삭제되었습니다. | +| Role.Data.Updated | 역할의 데이터가 업데이트되었습니다. 예: 역할 이름, 설명, 기본 역할 상태 등. | +| Role.Scopes.Updated | 역할에 할당된 권한이 추가되거나 제거되었습니다. | -### 권한 (스코프) \{#permission-scope} +### 권한(Permission, Scope) \{#permission-scope} -| 이벤트 유형 | 설명 | -| ------------------ | -------------------------------------------------- | -| Scope.Created | 새 API 권한이 생성됩니다. | -| Scope.Deleted | API 권한이 삭제됩니다. | -| Scope.Data.Updated | API 권한의 데이터가 업데이트됩니다. 예: 권한 설명. | +| 이벤트 타입 | 설명 | +| ------------------ | --------------------------------------------------------- | +| Scope.Created | 새 API 권한이 생성되었습니다. | +| Scope.Deleted | API 권한이 삭제되었습니다. | +| Scope.Data.Updated | API 권한의 데이터가 업데이트되었습니다. 예: 권한 설명 등. | -### 조직 \{#organization} +### 조직(Organization) \{#organization} -| 이벤트 유형 | 설명 | -| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | 새 조직이 생성됩니다. | -| Organization.Deleted | 조직이 삭제됩니다. | -| Organization.Data.Updated | 조직의 데이터가 업데이트됩니다. 예: 조직 이름, 설명, custom.data 등. | -| Organization.Membership.Updated | 조직에 사용자 또는 애플리케이션이 추가되거나 제거됩니다. 페이로드에는 [멤버십 델타 필드](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)가 포함됩니다. | +| 이벤트 타입 | 설명 | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | 새 조직이 생성되었습니다. | +| Organization.Deleted | 조직이 삭제되었습니다. | +| Organization.Data.Updated | 조직의 데이터가 업데이트되었습니다. 예: 조직 이름, 설명, custom.data 등. | +| Organization.Membership.Updated | 사용자 또는 애플리케이션이 조직에 추가되거나 제거되었습니다. 페이로드에는 [멤버십 델타 필드](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)가 포함됩니다. | -### 조직 역할 \{#organization-role} +### 조직 역할(Organization role) \{#organization-role} -| 이벤트 유형 | 설명 | -| ------------------------------- | ---------------------------------------------------------------- | -| OrganizationRole.Created | 새 조직 역할이 생성됩니다. | -| OrganizationRole.Deleted | 조직 역할이 삭제됩니다. | -| OrganizationRole.Data.Updated | 조직 역할의 데이터가 업데이트됩니다. 예: 조직 역할 이름 및 설명. | -| OrganizationRole.Scopes.Updated | 조직 역할에 할당된 권한이 추가되거나 제거됩니다. | +| 이벤트 타입 | 설명 | +| ------------------------------- | ----------------------------------------------------------------------- | +| OrganizationRole.Created | 새 조직 역할이 생성되었습니다. | +| OrganizationRole.Deleted | 조직 역할이 삭제되었습니다. | +| OrganizationRole.Data.Updated | 조직 역할의 데이터가 업데이트되었습니다. 예: 조직 역할 이름 및 설명 등. | +| OrganizationRole.Scopes.Updated | 조직 역할에 할당된 권한이 추가되거나 제거되었습니다. | -### 조직 권한 (스코프) \{#organization-permission-scope} +### 조직 권한(Organization permission, scope) \{#organization-permission-scope} -| 이벤트 유형 | 설명 | -| ------------------------------ | -------------------------------------------------------- | -| OrganizationScope.Created | 새 조직 권한이 생성됩니다. | -| OrganizationScope.Deleted | 조직 권한이 삭제됩니다. | -| OrganizationScope.Data.Updated | 조직 권한의 데이터가 업데이트됩니다. 예: 조직 권한 설명. | +| 이벤트 타입 | 설명 | +| ------------------------------ | --------------------------------------------------------------- | +| OrganizationScope.Created | 새 조직 권한이 생성되었습니다. | +| OrganizationScope.Deleted | 조직 권한이 삭제되었습니다. | +| OrganizationScope.Data.Updated | 조직 권한의 데이터가 업데이트되었습니다. 예: 조직 권한 설명 등. | ### Management API 트리거 이벤트 \{#management-api-triggered-events} @@ -114,22 +114,23 @@ sidebar_position: 3 | 사용자 상호작용 액션 | 이벤트 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -| 사용자 이메일 / 전화번호 연결 | User.Data.Updated | +| 사용자 이메일/전화번호 연결 | User.Data.Updated | | 사용자 MFA 연결 | User.Data.Updated | -| 사용자 소셜 / SSO 연결 | User.Data.Updated | +| 사용자 소셜/SSO 연결 | User.Data.Updated | | 사용자 비밀번호 재설정 | User.Data.Updated | | 사용자 등록 | User.Created | -| [Just-in-Time 프로비저닝](/organizations/just-in-time-provisioning) (이메일 도메인 또는 엔터프라이즈 SSO 커넥터 일치)을 통해 조직에 자동 프로비저닝된 사용자 | Organization.Membership.Updated | +| [Just-in-time 프로비저닝](/organizations/just-in-time-provisioning) (이메일 도메인 또는 엔터프라이즈 SSO 커넥터 일치)을 통해 조직에 자동 프로비저닝된 사용자 | Organization.Membership.Updated | ## 예외 훅 이벤트 \{#exception-hook-events} -### 보안 \{#security} +### 보안(Security) \{#security} -| 이벤트 유형 | 설명 | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | 연속된 아이덴티티 확인 실패 시도로 인해 사용자 계정이 잠깁니다. 다음 흐름에서 트리거될 수 있습니다:
  • 비밀번호 확인 실패
  • 코드 확인 실패
  • 일회용 토큰 확인 실패
| +| 이벤트 타입 | 설명 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Identifier.Lockout | 연속된 아이덴티티 검증 실패로 인해 사용자 계정이 잠겼습니다. 다음 플로우에서 트리거될 수 있습니다:
  • 비밀번호 검증 실패
  • 코드 검증 실패
  • 일회성 토큰 검증 실패
| +| Message.RateLimited | 최종 사용자가 인증 코드에 대한 [수신자별 전송 속도 제한](/security/send-rate-limit)을 초과했습니다. 최종 사용자 전송 경로(Experience API 및 Account API)에서만 발생하며, 페이로드는 `{ action, recipient }`입니다. | -## 자주 묻는 질문 \{#faqs} +## 자주 묻는 질문(FAQs) \{#faqs}
@@ -138,6 +139,6 @@ sidebar_position: 3 -`PostRegister`는 사용자가 사용자 가입 흐름을 통해 새 계정을 성공적으로 생성할 때 트리거됩니다. `User.Created`는 Management API를 통해 새 사용자 계정이 생성될 때 트리거됩니다. +`PostRegister`는 사용자가 사용자 가입 플로우를 통해 새 계정을 성공적으로 생성할 때 트리거됩니다. `User.Created`는 Management API를 통해 새 사용자 계정이 생성될 때 트리거됩니다.
diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/security/README.mdx index f63eb5a6f6c..2a03856dd8a 100644 --- a/i18n/ko/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/ko/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # 보안 (Security) -현대의 인증 (Authentication) 보안은 피싱, 크리덴셜 스터핑, 무차별 대입 공격, 랜섬웨어, DDoS, AI 기반 공격 등 다양한 위협과 싸우고 있습니다. 사용자 아이덴티티를 보호하는 것은 브랜드 신뢰와 규정 준수를 지키는 데 매우 중요합니다. +현대의 인증 (Authentication) 보안은 피싱, 크리덴셜 스터핑, 무차별 대입 공격, 랜섬웨어, DDoS, AI 기반 공격 등 다양한 위협과 싸우고 있습니다. 사용자 아이덴티티 보호는 브랜드 신뢰와 규정 준수를 지키는 데 매우 중요합니다. -Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강력한 보안 접근 관리 기능을 제공합니다. 사전 예방적 위협 방지와 복원력을 우선시함으로써, 사용성을 해치지 않으면서도 시스템을 안전하게 보호합니다. Logto와 함께라면 보안은 뒷전이 아니라, 비즈니스가 번창할 수 있는 기반이 됩니다. 위협이 진화하는 시대에 방어도 더 빠르게 진화할 수 있도록 지원합니다. +Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강력한 보안 접근 관리 기능을 제공합니다. 사전 예방적 위협 방지와 복원력을 우선시함으로써, 사용성을 해치지 않으면서도 시스템이 안전하게 보호되도록 보장합니다. Logto와 함께라면 보안은 뒷전이 아니라, 비즈니스가 번창할 수 있도록 하는 기반입니다. 위협이 진화하는 시대에 방어도 더 빠르게 진화할 수 있도록 지원합니다. ## 고급 보안 보호 설정하기 \{#set-up-advanced-security-protection} @@ -23,7 +23,7 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 label: '비밀번호 정책', href: '/security/password-policy', description: - '크리덴셜 스터핑 및 약한 비밀번호 공격을 방어하기 위해 비밀번호 요구 사항을 강화하세요.', + '크리덴셜 스터핑 및 약한 비밀번호 공격을 방어하기 위해 비밀번호 요구사항을 강화하세요.', customProps: { icon: , }, @@ -33,7 +33,7 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 label: 'CAPTCHA', href: '/security/captcha', description: - '로그인 경험에 CAPTCHA(예: Google reCAPTCHA, Cloudflare Turnstile)를 추가하여 자동화된 봇 공격을 방지하세요.', + '자동화된 봇 공격을 방지하기 위해 로그인 경험에 CAPTCHA(예: Google reCAPTCHA, Cloudflare Turnstile)를 추가하세요.', customProps: { icon: , }, @@ -43,7 +43,7 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 label: '블록리스트', href: '/security/blocklist', description: - '일회용 또는 원하지 않는 이메일 도메인이나 주소를 차단하여 사용자 기반을 제어하세요.', + '일회용 또는 원하지 않는 이메일 도메인이나 주소를 차단하여 사용자 기반을 직접 관리하세요.', customProps: { icon: , }, @@ -58,12 +58,22 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 icon: , }, }, + { + type: 'link', + label: '전송 속도 제한', + href: '/security/send-rate-limit', + description: + '수신자별 인증 코드 및 메시지 전송 횟수를 제한하여 스팸 및 SMS 펌핑 악용을 방지하세요.', + customProps: { + icon: , + }, + }, { type: 'link', label: '계정 존재 숨기기', href: '/end-user-flows/sign-up-and-sign-in', description: - '계정 상태를 숨겨 계정 열거 공격을 차단하고 민감한 계정 상태 정보를 노출하지 마세요.', + '계정 상태를 숨겨 계정 열거 공격을 차단하고 민감한 계정 상태 정보 노출을 방지하세요.', customProps: { icon: , }, @@ -80,17 +90,17 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 label: '다단계 인증 (MFA)', href: '/end-user-flows/mfa', description: - '인증자 앱 OTP, 패스키(WebAuthn), 백업 코드 지원으로 로그인 과정에 추가 보호 계층을 더하세요.', + '인증 (Authentication) 과정에 인증 앱 OTP, 패스키(WebAuthn), 백업 코드 지원 등 추가 보호 계층을 더하세요.', customProps: { icon: , }, }, { type: 'link', - label: '스텝업 인증 (Authentication)', + label: '스텝업 인증', href: '/end-user-flows/security-verification', description: - '사용자가 민감한 정보에 접근하거나 고위험 작업을 수행할 때 앱에서 스텝업 인증 (Authentication)을 요청할 수 있습니다.', + '사용자가 민감한 정보에 접근하거나 고위험 작업을 수행할 때 앱에서 스텝업 인증을 요청할 수 있습니다.', customProps: { icon: , }, @@ -109,7 +119,7 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 type: 'link', label: '서명 키 교체', href: '/developers/signing-keys', - description: '주기적으로 서명 키를 교체하여 키 유출 및 토큰 위조로부터 보호하세요.', + description: '키 유출 및 토큰 위조를 방지하기 위해 서명 키를 주기적으로 교체하세요.', customProps: { icon: , }, @@ -118,16 +128,16 @@ Logto는 이러한 위험에 정면으로 대응할 수 있도록 설계된 강 type: 'link', label: 'OIDC 백채널 로그아웃', href: '/end-user-flows/sign-out#federated-sign-out-back-channel-logout', - description: '중앙 집중식 로그아웃을 활성화하여 세션 탈취 및 무단 접근 위험을 줄이세요.', + description: '중앙 집중식 로그아웃을 활성화하여 세션 하이재킹 및 무단 접근 위험을 줄이세요.', customProps: { icon: , }, }, { type: 'link', - label: '초대 전용 회원가입', + label: '초대 전용 가입', href: '/end-user-flows', - description: '이메일 매직 링크를 사용하여 초대된 사용자만 회원가입할 수 있도록 제한하세요.', + description: '이메일 매직 링크를 사용하여 초대된 사용자만 가입할 수 있도록 제한하세요.', customProps: { icon: , }, diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/ko/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..861815b06e7 --- /dev/null +++ b/i18n/ko/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,39 @@ +--- +slug: /security/send-rate-limit +sidebar_label: 발송 속도 제한 (Send rate limit) +sidebar_position: 5 +--- + +# 발송 속도 제한 (Send rate limiting) + +Logto는 이메일 및 SMS를 통해 발송되는 인증 코드 및 기타 메시지에 대해 수신자별 내장 속도 제한을 적용합니다. 이는 사용자의 메시지 수신함이나 휴대폰에 공격자가 코드를 스팸으로 보내거나, SMS 트래픽을 과도하게 발생시켜 비용을 증가시키는 등의 발송 남용으로부터 사용자와 메시징 공급자를 보호합니다. + +이 제한은 **필수적이며 시스템 수준**입니다. 모든 테넌트에 플랜과 관계없이 적용되며, **테넌트에서 설정할 수 없습니다**. 또한 다음과는 별개로 동작합니다: + +- **[식별자 잠금](/security/identifier-lockout)** 및 **[CAPTCHA](/security/captcha)** 정책은 *인증 시도 실패*를 제한하지만, _발송 행위_ 자체를 제한하지는 않습니다. +- 테넌트별 전체 API 속도 제한(오류 코드 `request.rate_limited`)은 테넌트 전체의 요청량을 제한합니다. + +## 동작 방식 \{#how-it-works} + +- **수신자별 제한**: Logto는 동일한 수신자(이메일 주소 또는 전화번호)에게 짧은 롤링 시간 창 내에 보낼 수 있는 메시지 수를 제한합니다. 기본적으로 **10분마다 수신자당 최대 10회 발송**이 허용됩니다. +- **적용 범위**: 모든 서버 측 발송 경로에 적용됩니다. 여기에는 Experience API 및 Account API의 인증 코드 발송(로그인, 회원가입, 비밀번호 재설정, MFA, 식별자 바인딩), Management API의 인증 코드 발송, 조직 초대 발송 및 재발송, Account(`/me`) 인증 코드 발송이 포함됩니다. +- **제한 초과 시**: 요청은 HTTP `429`와 오류 코드 `request.message_rate_limited`로 거부됩니다. 이는 글로벌 테넌트 제한자(`request.rate_limited`) 및 인증 시도 제한(`session.verification_blocked_too_many_attempts`)과 구분되므로, 통합 시 별도로 처리할 수 있습니다. + +## Webhook으로 속도 제한 발송 모니터링하기 \{#monitor-rate-limited-sends-with-a-webhook} + +**최종 사용자**가 수신자별 제한에 도달하면, Logto는 `Message.RateLimited` [웹훅 이벤트](/developers/webhooks/webhooks-events#exception-hook-events)를 트리거하여 발송 남용에 대해 알림을 보내거나 대응할 수 있도록 합니다. + +- **발생 조건**: 최종 사용자 인증 코드 발송 경로(Experience API 및 Account API)에만 발생합니다. 1st-party 또는 관리자 발송(Management API 인증 코드, 조직 초대, `/me`)에는 발생하지 않습니다. +- **페이로드**: 훅 컨텍스트에는 `action`(예: `VerificationCodeSend`)과 `recipient`(이메일 주소 또는 전화번호)가 포함됩니다. + +**일반적인 사용 사례:** + +- 보안 알림을 팀에 전송하여 검토하도록 합니다. +- 영향을 받은 수신자에 대해 다운스트림 남용 방지 자동화를 트리거합니다. + +Console > Webhooks로 이동하여 구독하거나, Management API를 +통해 훅을 생성하세요. 자세한 이벤트 구조 및 설정은 [Webhooks](/developers/webhooks)를 참고하세요. + +## 미등록 수신자에 대한 발송 억제 \{#suppressed-delivery-to-unknown-recipients} + +계정 열거를 방지하기 위해, 식별자를 통한 회원가입이 비활성화된 경우, **계정이 소유하지 않은** 이메일 주소 또는 전화번호로 로그인 인증 코드가 요청되면 실제로는 발송되지 않으며, API는 실제 발송과 동일하게 응답합니다. 따라서 공격자는 이러한 응답을 통해 어떤 주소가 등록되어 있는지 알 수 없습니다. 기존 사용자에 대한 발송은 영향을 받지 않습니다. 자세한 내용은 [계정 존재 숨기기](/end-user-flows/sign-up-and-sign-in)를 참고하세요. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/README.mdx index 1176ad595d3..5b6514e6cc0 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -1,6 +1,6 @@ # Desenvolvedor -Logto é um serviço de [gerenciamento de identidade e acesso (IAM)](https://auth.wiki/iam) baseado nos protocolos [OAuth 2](https://auth.wiki/oauth-2.0) e [OIDC](https://auth.wiki/openid-connect). Serviços de IAM como o Logto frequentemente servem como base para outros serviços web; vários estados de autorização dentro desses serviços web são diretamente afetados pelo Logto. +Logto é um serviço de [gerenciamento de identidade e acesso (IAM)](https://auth.wiki/iam) baseado nos protocolos [OAuth 2](https://auth.wiki/oauth-2.0) e [OIDC](https://auth.wiki/openid-connect). Serviços IAM como o Logto frequentemente servem como base para outros serviços web; vários estados de autorização dentro desses serviços web são diretamente afetados pelo Logto. Para proporcionar conveniência aos nossos usuários, o Logto oferece uma série de recursos comuns para desenvolvedores. @@ -19,7 +19,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; items={[ { type: 'link', - label: 'Token de acesso personalizado', + label: 'Token de acesso personalizado (Custom access token)', href: '/developers/custom-token-claims', description: 'Use scripts personalizados para anexar reivindicações adicionais aos tokens de acesso, habilitando ABAC ou rejeitando a emissão do token.', customProps: { @@ -28,7 +28,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; }, { type: 'link', - label: 'Token de ID personalizado', + label: 'Token de ID personalizado (Custom ID token)', href: '/developers/custom-id-token', description: 'Controle quais reivindicações estendidas são incluídas nos tokens de ID, seguindo a especificação OIDC.', customProps: { @@ -39,11 +39,20 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Imitação de usuário (User impersonation)', href: '/developers/user-impersonation', - description: 'Permita que usuários autorizados atuem temporariamente em nome de usuários finais, útil para solução de problemas, suporte ao cliente e tarefas administrativas.', + description: 'Permita que usuários autorizados atuem temporariamente em nome de usuários finais, útil para resolução de problemas, suporte ao cliente e tarefas administrativas.', customProps: { icon: , } }, + { + type: 'link', + label: 'Delegação serviço para serviço (Service-to-service delegation)', + href: '/developers/service-to-service-delegation', + description: 'Troque um token de acesso de usuário por um token de acesso de API downstream para que serviços de backend possam agir em nome do usuário atual.', + customProps: { + icon: , + } + }, ]} /> ``` @@ -55,9 +64,9 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; items={[ { type: 'link', - label: 'Chaves de assinatura', + label: 'Chaves de assinatura (Signing keys)', href: '/developers/signing-keys', - description: 'Fornece chave de assinatura em nível de sistema, através do cofre de senhas, tornando o serviço de autenticação mais seguro.', + description: 'Forneça chave de assinatura em nível de sistema, através do cofre de senhas, tornando o serviço de autenticação mais seguro.', customProps: { icon: , } @@ -66,14 +75,14 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Webhooks', href: '/developers/webhooks', - description: 'Webhooks suportam notificações em tempo real sobre informações de usuários e atualizações de permissões por meio de requisições HTTP, aumentando a conveniência e flexibilidade da integração com o Logto.', + description: 'Webhooks suportam notificações em tempo real sobre informações de usuários e atualizações de permissões via requisições HTTP, aumentando a conveniência e flexibilidade da integração com o Logto.', customProps: { icon: , } }, { type: 'link', - label: 'Logs de auditoria', + label: 'Logs de auditoria (Audit logs)', href: '/developers/audit-logs', description: 'Registre atividades relacionadas à autenticação de usuários para facilitar a depuração e análise das atividades dos usuários.', customProps: { @@ -82,9 +91,9 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; }, { type: 'link', - label: 'Convenção do SDK', + label: 'Convenção do SDK (SDK convention)', href: '/developers/', - description: 'Apresenta as estruturas de dados, finalidades e métodos no SDK, permitindo que os usuários personalizem o SDK para se adequar a diversos cenários de negócios.', + description: 'Apresente as estruturas de dados, finalidades e métodos no SDK, permitindo que os usuários personalizem o SDK para se adequar a vários cenários de negócios.', customProps: { icon: , } diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index dda4470a25d..9929da36ab4 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # Logs de auditoria @@ -8,7 +8,7 @@ O log de auditoria do Logto permite monitorar facilmente a atividade e os evento ## Visualizar todos os logs \{#view-all-logs} -Navegue até Console > Logs de auditoria. O Logto captura e organiza eventos de autenticação em uma tabela. Ele registra o nome do evento, usuário, aplicativo e carimbo de data / hora. Você pode refinar os resultados filtrando pelo nome do evento e nome do aplicativo. Ao clicar em um evento específico, serão exibidos detalhes adicionais. +Navegue até Console > Logs de auditoria. O Logto captura e organiza eventos de autenticação em uma tabela. Ele mantém o controle do nome do evento, usuário, aplicativo e carimbo de data / hora. Você pode refinar os resultados filtrando pelo nome do evento e nome do aplicativo. Ao clicar em um evento específico, serão exibidos detalhes adicionais. :::warning Os logs de auditoria contêm apenas logs que ocorrem durante o processo de autenticação do usuário; logs de operações da Management API não são registrados. @@ -41,14 +41,14 @@ Para acessar logs específicos do usuário, siga estes passos: 1. Navegue até Console > Gerenciamento de usuários. 2. Selecione o usuário desejado e vá para a página de detalhes. -3. Clique em "Logs do usuário". A tabela resultante exibirá exclusivamente eventos de log realizados e acionados por esse usuário em particular. +3. Clique em "Logs do usuário". A tabela resultante exibirá exclusivamente eventos de log realizados e acionados por aquele usuário em particular. Logs de auditoria relacionados a um usuário específico -## Perguntas frequentes \{#faqs} +## Perguntas frequentes (FAQs) \{#faqs}
@@ -57,6 +57,6 @@ Para acessar logs específicos do usuário, siga estes passos: -Usuários OSS devem adicionar um cronjob para limpar regularmente os logs de auditoria desatualizados. +Usuários OSS devem adicionar um cronjob para limpar regularmente logs de auditoria desatualizados.
diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index 65d5ce251b9..3fe5ed483e2 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,7 +2,7 @@ id: sdk-conventions title: Convenções de SDK de plataforma sidebar_label: Convenções de SDK de plataforma -sidebar_position: 8 +sidebar_position: 9 --- # Convenções de SDK de plataforma @@ -13,12 +13,12 @@ No uso prático dos serviços do Logto, para conveniência, muitas vezes é nece Você pode encontrar SDKs para todas as linguagens de programação / frameworks suportados pelo Logto [aqui](/quick-starts). -Se você não tiver sorte e não encontrar o SDK desejado, aqui está uma convenção que você pode seguir para implementar o SDK para a linguagem de programação desejada, facilitando o uso dos serviços do Logto. +Se você não tiver sorte e não encontrar o SDK que deseja, aqui está uma convenção que você pode seguir para implementar o SDK para a linguagem de programação desejada, facilitando o uso dos serviços do Logto. Esta convenção contém três partes principais: Estratégia de design -Convenção de SDK central +Convenção de SDK principal Convenção de SDK de plataforma ## Recursos relacionados \{#related-resources} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..e5030825fd5 --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: Delegação serviço para serviço +sidebar_label: Delegação serviço para serviço +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# Delegação serviço para serviço + +Em algumas arquiteturas de API, um serviço backend recebe uma solicitação de um usuário autenticado e precisa chamar outro serviço backend preservando a identidade do usuário. + +Por exemplo: + +```text +Usuário -> API A -> API B +``` + +A API B precisa saber duas coisas: + +1. O chamador é um serviço confiável, como a API A. +2. A operação está sendo realizada para o usuário original. + +Use a concessão de troca de token do Logto para trocar o token de acesso do usuário por um novo token de acesso cujo público é o recurso de API downstream. Isso segue o padrão de troca de token do OAuth 2.0 e evita encaminhar o token original do usuário para serviços downstream. + +## Quando usar este fluxo \{#when-to-use-this-flow} + +Use a delegação serviço para serviço quando: + +- A API A é um serviço backend que pode autenticar-se com segurança no endpoint de token do Logto. +- A API A recebe um token de acesso de usuário emitido pelo Logto. +- A API A precisa chamar a API B em nome do mesmo usuário. +- A API B deve validar um token de acesso com seu próprio recurso de API como público. + +Não use este fluxo para acesso puramente máquina para máquina sem um usuário. Nesse caso, use o [fluxo de credenciais do cliente](/quick-starts/m2m). Para cenários de suporte, administração ou agente, onde um usuário atua temporariamente como outro usuário, use [imitação de usuário](/developers/user-impersonation). + +## Como funciona \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as Usuário + participant ApiA as API A + participant Logto as Endpoint de token do Logto + participant ApiB as API B + + User->>ApiA: Authorization: Bearer token de acesso do usuário + Note over ApiA: Validar o token do usuário para a API A + + ApiA->>Logto: POST /oidc/token com concessão de troca de token + Note over ApiA,Logto: subject_token = token de acesso do usuário
resource = indicador de recurso da API B + + Logto-->>ApiA: Token de acesso para a API B + ApiA->>ApiB: Authorization: Bearer token de acesso trocado + Note over ApiB: Validar emissor, público, expiração e escopos +``` + +O token de acesso trocado representa o usuário original (`sub`) e está vinculado ao recurso de API downstream (`aud`). A API downstream também pode inspecionar a reivindicação `client_id` para identificar o aplicativo que iniciou a troca. + +## Pré-requisitos \{#prerequisites} + +1. Crie recursos de API para os serviços envolvidos. Veja [Proteger recursos globais de API](/authorization/global-api-resources). +2. Configure as permissões da API B e atribua-as aos usuários por meio de papéis ou papéis de organização. +3. Use um aplicativo do lado do servidor para a API A, como um app máquina para máquina ou um app web tradicional, para que ele possa autenticar-se com segurança usando um segredo de aplicativo. +4. Habilite a troca de token para o aplicativo da API A. + + + +## Solicitar um token de acesso para a API downstream \{#request-an-access-token-for-the-downstream-api} + +Quando a API A precisar chamar a API B, faça uma solicitação de troca de token para o [endpoint de token](/integrate-logto/application-data-structure#token-endpoint) do Logto. + +Para aplicativos web tradicionais ou aplicativos máquina para máquina com um segredo de aplicativo, inclua as credenciais no cabeçalho `Authorization`: + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +Parâmetros: + +1. `grant_type`: Use `urn:ietf:params:oauth:grant-type:token-exchange`. +2. `subject_token`: O token de acesso de usuário original emitido pelo Logto recebido pela API A. +3. `subject_token_type`: Use `urn:ietf:params:oauth:token-type:access_token`. +4. `resource`: O indicador de recurso da API B. +5. `scope`: As permissões downstream que a API A está solicitando para esta chamada delegada. O Logto emite apenas os escopos solicitados que estão disponíveis para o usuário original para este recurso de acordo com as configurações de RBAC. + +O Logto retorna um token de acesso para a API B: + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +Quando decodificado, o token de acesso inclui reivindicações semelhantes a: + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +Em seguida, a API A chama a API B com o token trocado: + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## Validar o token na API B \{#validate-the-token-in-api-b} + +A API B deve validar o token trocado como qualquer token de acesso de recurso de API emitido pelo Logto: + +1. Verifique a assinatura usando os JWKs do Logto. +2. Verifique o emissor (`iss`). +3. Verifique se o público (`aud`) corresponde ao indicador de recurso da API B. +4. Verifique a expiração (`exp`). +5. Verifique os escopos necessários. +6. Use `sub` como o ID do usuário original. +7. Opcionalmente, verifique `client_id` se apenas serviços upstream específicos puderem realizar chamadas delegadas. + +Veja [Validar tokens de acesso na API](/authorization/validate-access-tokens) para orientações de implementação. + +## Recursos relacionados \{#related-resources} + +Proteger recursos globais de API + +Validar tokens de acesso na API + +Imitação de usuário diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index 00125861d9f..f5c25235624 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,12 +2,12 @@ id: signing-keys title: Chaves de assinatura sidebar_label: Chaves de assinatura -sidebar_position: 5 +sidebar_position: 6 --- # Chaves de assinatura -As [chaves de assinatura OIDC](https://auth.wiki/signing-key) do Logto, também conhecidas como "chaves privadas OIDC" e "chaves de cookie OIDC", são as chaves usadas para assinar JWTs ([tokens de acesso (Access tokens)](https://auth.wiki/access-token) e [tokens de ID (ID tokens)](https://auth.wiki/id-token)) e cookies de navegador nas [sessões de login (sign-in sessions)](/sessions#what-is-a-logto-session) do Logto. Essas chaves de assinatura são geradas ao inicializar o banco de dados do Logto ([open-source](/logto-oss)) ou ao criar um novo tenant ([Cloud](/logto-cloud)) e podem ser gerenciadas via [CLI](/logto-oss/using-cli) (open-source), Management APIs ou Console UI. +As [chaves de assinatura OIDC](https://auth.wiki/signing-key) do Logto, também conhecidas como "chaves privadas OIDC" e "chaves de cookie OIDC", são as chaves de assinatura usadas para assinar JWTs ([tokens de acesso (Access tokens)](https://auth.wiki/access-token) e [tokens de ID (ID tokens)](https://auth.wiki/id-token)) e cookies de navegador nas [sessões de login (sign-in sessions)](/sessions#what-is-a-logto-session) do Logto. Essas chaves de assinatura são geradas ao inicializar o banco de dados do Logto ([open-source](/logto-oss)) ou ao criar um novo tenant ([Cloud](/logto-cloud)) e podem ser gerenciadas via [CLI](/logto-oss/using-cli) (open-source), Management APIs ou Console UI. Por padrão, o Logto utiliza o algoritmo de curva elíptica (EC) para gerar assinaturas digitais. No entanto, considerando que os usuários frequentemente precisam verificar assinaturas de JWT e muitas ferramentas antigas não suportam o algoritmo EC (apenas RSA), implementamos a funcionalidade de rotação de chaves privadas e permitimos que os usuários escolham o algoritmo de assinatura (incluindo tanto RSA quanto EC). Isso garante compatibilidade com serviços que utilizam ferramentas de verificação de assinatura desatualizadas. @@ -24,32 +24,32 @@ Teoricamente, as chaves de assinatura não devem ser vazadas e não possuem temp ## Rotacionar chaves de assinatura pela Console UI \{#rotate-signing-keys-from-console-ui} -O Logto introduz o recurso de "Rotação de Chaves de Assinatura", que permite criar uma nova chave privada OIDC e uma chave de cookie em seu tenant. +O Logto introduz o recurso de "Rotação de Chaves de Assinatura", que permite criar uma nova chave privada OIDC e uma nova chave de cookie em seu tenant. 1. Navegue até Console > Configurações do tenant > Configurações OIDC. Lá, você pode gerenciar tanto as chaves privadas OIDC quanto as chaves de cookie OIDC. -2. Para rotacionar a chave de assinatura, clique no botão "Rotacionar chaves privadas" ou "Rotacionar chaves de cookie". Ao rotacionar as chaves privadas, você tem a opção de alterar o algoritmo de assinatura. +2. Para rotacionar a chave de assinatura, clique no botão "Rotacionar chaves privadas" ou "Rotacionar chaves de cookie". Ao rotacionar chaves privadas, você tem a opção de alterar o algoritmo de assinatura. 3. Você encontrará uma tabela que lista todas as chaves de assinatura em uso. Para chaves privadas OIDC, você pode excluir a chave anterior, mas não pode excluir a chave atual ou a próxima. Para chaves de cookie OIDC, você pode excluir a chave anterior, mas não pode excluir a chave atual. - | Status | Descrição | - | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | Próxima (Next) | Este status é usado para rotação de chave privada OIDC em estágio. A chave foi criada, mas o Logto não a usará para assinar novos JWTs até que o período de carência termine e a chave se torne efetiva. | - | Atual (Current) | Indica que esta chave está sendo usada atualmente pelo Logto para assinar novos JWTs ou cookies. | - | Anterior (Previous) | Refere-se a uma chave que foi usada anteriormente, mas foi rotacionada. JWTs ou cookies existentes assinados com essa chave permanecem válidos até expirarem ou a chave ser excluída. | + | Status | Descrição | + | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | Next | Este status é usado para rotação de chave privada OIDC em estágio. A chave foi criada, mas o Logto não a usará para assinar novos JWTs até que o período de carência termine e a chave se torne efetiva. | + | Current | Indica que esta chave está sendo usada atualmente pelo Logto para assinar novos JWTs ou cookies. | + | Previous | Refere-se a uma chave que foi usada anteriormente, mas já foi rotacionada. JWTs ou cookies existentes assinados com esta chave permanecem válidos até expirarem ou a chave ser excluída. | Lembre-se de que a rotação envolve as seguintes três ações: -1. **Criar uma nova chave de assinatura**: Para chaves privadas OIDC, o Logto pode preparar a nova chave como "Próxima (Next)" primeiro, para que seus aplicativos e APIs tenham tempo de atualizar a chave pública do endpoint `/oidc/jwks` antes que a nova chave seja usada para assinatura. -2. **Rotacionar a chave atual**: Quando a rotação se torna efetiva, a chave "Próxima (Next)" se torna "Atual (Current)", e a chave "Atual (Current)" existente se torna "Anterior (Previous)". Tokens assinados com a chave anterior ainda permanecerão válidos. -3. **Remover a chave anterior mais antiga**: O Logto mantém no máximo uma chave privada "Anterior (Previous)". Se já existir uma chave privada anterior quando a chave em estágio se tornar atual, a chave anterior mais antiga será removida. +1. **Criar uma nova chave de assinatura**: Para chaves privadas OIDC, o Logto pode preparar a nova chave como "Next" primeiro, para que seus aplicativos e APIs tenham tempo de atualizar a chave pública do endpoint `/oidc/jwks` antes que a nova chave seja usada para assinatura. +2. **Rotacionar a chave atual**: Quando a rotação se torna efetiva, a chave "Next" se torna "Current", e a chave "Current" existente se torna "Previous". Tokens assinados com a chave anterior ainda permanecerão válidos. +3. **Remover a chave anterior mais antiga**: O Logto mantém no máximo uma chave privada "Previous". Se já existir uma chave privada anterior quando a chave em estágio se tornar atual, a chave anterior mais antiga será removida. -Para o Logto Cloud, a rotação da chave privada OIDC entra em vigor após um período de carência de 4 horas. Durante esse período, a nova chave é preparada e exposta via JWKS antes que o Logto comece a assinar novos JWTs com ela. Na tabela do Console, a coluna **Efetiva em (Effective at)** mostra quando uma chave "Próxima (Next)" em estágio se tornará "Atual (Current)". +No Logto Cloud, a rotação da chave privada OIDC entra em vigor após um período de carência de 4 horas. Durante esse período, a nova chave é preparada e exposta via JWKS antes que o Logto comece a assinar novos JWTs com ela. Na tabela do Console, a coluna **Efetiva em** mostra quando uma chave "Next" em estágio se tornará "Current". Para implantações OSS self-hosted, o período de carência padrão para rotação de chave privada é de `0` segundos, o que significa que a rotação é imediata. Para usar rotação em estágio, defina a variável de ambiente `PRIVATE_KEY_ROTATION_GRACE_PERIOD` no serviço Logto, ou passe um valor explícito de `rotationGracePeriod` no corpo da requisição ao chamar o endpoint da Management API `POST /api/configs/oidc/private-keys/rotate`. :::warning -Evite rotacionar as chaves de assinatura repetidamente antes que a rotação pendente se torne efetiva, a menos que você queira substituir intencionalmente a chave "Próxima (Next)" em estágio. +Evite rotacionar as chaves de assinatura repetidamente antes que a rotação pendente se torne efetiva, a menos que você queira substituir intencionalmente a chave "Next" em estágio. -Excluir a única chave "Anterior (Previous)" muito cedo pode invalidar JWTs ou cookies existentes que foram assinados com essa chave. +Excluir a única chave "Previous" muito cedo pode invalidar JWTs ou cookies existentes que foram assinados com essa chave. ::: ## Recursos relacionados \{#related-resources} diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index f258b67b8ef..351caae9441 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,10 +1,10 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhooks -O [Webhook](https://auth.wiki/webhook) do Logto fornece notificações em tempo real para vários eventos, incluindo alterações em contas de usuários, papéis, permissões, organizações, papéis de organização, permissões de organização e [interações do usuário](/end-user-flows). +O [Webhook](https://auth.wiki/webhook) do Logto fornece notificações em tempo real para vários eventos, incluindo alterações em contas de usuários, papéis (roles), permissões, organizações (organizations), papéis de organização, permissões de organização e [interações do usuário](/end-user-flows). Quando um evento é acionado, o Logto envia uma solicitação HTTP para a URL do Endpoint que você fornecer, contendo informações detalhadas sobre o evento, como ID do usuário, nome de usuário, e-mail e outros detalhes relevantes (para saber mais sobre os dados incluídos no payload e no header, consulte [Solicitação de Webhook](/developers/webhooks/webhooks-request)). Seu aplicativo pode processar essa solicitação e tomar ações personalizadas, como enviar um e-mail ou atualizar dados no banco de dados. @@ -18,18 +18,18 @@ Aqui estão alguns exemplos de casos de uso comuns de Webhook para CIAM: - **Enviar e-mails:** Configure um Webhook para enviar um e-mail de boas-vindas a novos usuários após o registro ou notificar administradores quando um usuário fizer login de um novo dispositivo ou local. - **Enviar notificações:** Configure um Webhook para acionar um assistente virtual com seu sistema CRM para fornecer suporte ao cliente em tempo real quando os usuários se cadastrarem. -- **Realizar chamadas adicionais de API**: Configure um Webhook para verificar o acesso do usuário checando seu domínio de e-mail ou endereço IP e, em seguida, use a Management API do Logto para atribuir papéis apropriados com permissões de recurso. +- **Realizar chamadas adicionais de API**: Configure um Webhook para verificar o acesso do usuário conferindo seu domínio de e-mail ou endereço IP e, em seguida, use a Management API do Logto para atribuir papéis apropriados com permissões de recurso. - **Sincronização de dados:** Configure Webhook para manter o aplicativo atualizado sobre alterações como suspensões ou exclusões de contas de usuário. -- **Gerar relatórios**: Configure um Webhook para receber dados de atividade de login do usuário e aproveite-os para criar relatórios sobre engajamento ou padrões de uso dos usuários. +- **Gerar relatórios**: Configure um Webhook para receber dados de atividade de login do usuário e aproveite-os para criar relatórios sobre engajamento ou padrões de uso. ## Termos \{#terms} -| Item | Descrição | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Event | Quando uma ação específica é realizada, ela acionará um evento de hook com um tipo específico. Ex.: o Logto emitirá um evento de hook PostRegister quando o usuário concluir o processo de cadastro e criar uma nova conta. | -| Hook | Uma ou uma série de ações que se conectam a um evento específico. A ação pode ser chamar uma API, executar trechos de código, etc. | -| Webhook | Um subtipo de hook que indica a chamada de uma API com o payload do evento. | -| Digamos que um desenvolvedor queira enviar uma notificação quando o usuário fizer login por um novo dispositivo, o desenvolvedor pode adicionar um webhook que chama a API do seu serviço de segurança para o evento PostSignIn. | +| Item | Descrição | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Event | Quando uma ação específica é realizada, ela aciona um evento de hook com um tipo específico. Ex.: o Logto emitirá um evento de hook PostRegister quando o usuário concluir o processo de cadastro e criar uma nova conta. | +| Hook | Uma ou uma série de ações que se conectam a um evento específico. A ação pode ser chamar uma API, executar trechos de código, etc. | +| Webhook | Um subtipo de hook que indica a chamada de uma API com o payload do evento. | +| Suponha que um desenvolvedor queira enviar uma notificação quando o usuário fizer login por um novo dispositivo, o desenvolvedor pode adicionar um webhook que chama a API do seu serviço de segurança para o evento PostSignIn. | Aqui está um exemplo de habilitação de dois webhooks para o evento `PostSignIn` no Logto: @@ -67,7 +67,7 @@ graph LR -Embora webhooks sincronizados tornassem o fluxo de login do usuário mais suave, ainda não os suportamos (mas iremos no futuro). Portanto, cenários que dependem de webhooks sincronizados atualmente exigem soluções alternativas diferentes. Se você tiver alguma dúvida, não hesite em nos contatar. +Embora webhooks sincronizados tornassem o fluxo de login do usuário mais suave, ainda não os suportamos (mas iremos no futuro). Portanto, cenários que dependem de webhooks sincronizados atualmente exigem soluções alternativas diferentes. Se você tiver dúvidas, não hesite em nos contatar. @@ -89,7 +89,7 @@ Veja o guia [Gerenciar alteração de permissão de usuário](/authorization/glo -Para o endpoint que recebe Webhooks, ele deve retornar uma resposta 2xx o mais rápido possível para informar ao Logto que o Webhook foi recebido com sucesso. Como diferentes usuários têm lógicas de processamento muito diferentes para Webhooks, tarefas excessivamente complexas podem levar vários segundos, causando timeout no Webhook do Logto. A melhor prática é manter sua própria fila de eventos; ao receber o Webhook do Logto, insira o evento na fila e retorne uma resposta 2xx ao Logto. Em seguida, deixe seu próprio worker processar as tarefas na fila passo a passo. Se o worker encontrar um erro, trate-o em seu próprio servidor. +Para o endpoint que recebe Webhooks, ele deve retornar uma resposta 2xx o mais rápido possível para informar ao Logto que o Webhook foi recebido com sucesso. Como diferentes usuários têm lógicas de processamento muito distintas para Webhooks, tarefas excessivamente complexas podem levar vários segundos, causando timeout no Webhook do Logto. A melhor prática é manter sua própria fila de eventos; ao receber o Webhook do Logto, insira o evento na fila e retorne uma resposta 2xx ao Logto. Depois, deixe seu próprio worker processar as tarefas da fila passo a passo. Se o worker encontrar um erro, trate-o em seu próprio servidor. @@ -100,7 +100,7 @@ Para o endpoint que recebe Webhooks, ele deve retornar uma resposta 2xx o mais r -Sim, você pode obter endereço IP, user agents, etc. no payload do Webhook. Se precisar de informações que ainda não são suportadas, você pode criar solicitações de recurso no GitHub Issues ou entrar em contato conosco. +Sim, você pode obter endereço IP, user agents, etc. no payload do Webhook. Se precisar de informações que ainda não são suportadas, você pode criar solicitações de recurso no GitHub Issues ou nos contatar. diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index 055c97539a0..f2b6e7a7111 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -13,65 +13,65 @@ Este guia lista os diferentes eventos de webhook do Logto e explica quando cada | Tipo de evento | Descrição | | ----------------- | ----------------------------------------------------------------------------------- | -| PostRegister | Um usuário cria com sucesso uma nova conta através da interface de usuário. | -| PostSignIn | Um usuário faz login com sucesso através da interface de usuário. | -| PostResetPassword | A senha de um usuário é redefinida com sucesso através do fluxo "Esqueceu a senha". | +| PostRegister | Um usuário cria com sucesso uma nova conta pela interface de usuário. | +| PostSignIn | Um usuário faz login com sucesso pela interface de usuário. | +| PostResetPassword | A senha de um usuário é redefinida com sucesso pelo fluxo de "Esqueci minha senha". | ## Eventos de hook de mutação de dados \{#data-mutation-hook-events} -### Usuário \{#user} +### Usuário (User) \{#user} | Tipo de evento | Descrição | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | | User.Created | Uma nova conta de usuário é criada. | -| User.Deleted | Uma conta de usuário é deletada. | +| User.Deleted | Uma conta de usuário é excluída. | | User.Data.Updated | Os dados do perfil do usuário são atualizados, por exemplo, email, avatar, custom.data, identificador social, etc. | | User.SuspensionStatus.Updated | O status de suspensão do usuário é alterado (suspenso ou reativado). | -### Papel \{#role} +### Papel (Role) \{#role} | Tipo de evento | Descrição | | ------------------- | ----------------------------------------------------------------------------------------------------- | | Role.Created | Um novo papel é criado. | -| Role.Deleted | Um papel é deletado. | +| Role.Deleted | Um papel é excluído. | | Role.Data.Updated | Os dados de um papel são atualizados, por exemplo, nome do papel, descrição e status de papel padrão. | | Role.Scopes.Updated | Permissões atribuídas a um papel são adicionadas ou removidas. | -### Permissão (Escopo) \{#permission-scope} +### Permissão (Escopo) (Permission (Scope)) \{#permission-scope} | Tipo de evento | Descrição | | ------------------ | -------------------------------------------------------------------------------------- | | Scope.Created | Uma nova permissão de API é criada. | -| Scope.Deleted | Uma permissão de API é deletada. | +| Scope.Deleted | Uma permissão de API é excluída. | | Scope.Data.Updated | Os dados de uma permissão de API são atualizados, por exemplo, descrição da permissão. | -### Organização \{#organization} +### Organização (Organization) \{#organization} | Tipo de evento | Descrição | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Organization.Created | Uma nova organização é criada. | -| Organization.Deleted | Uma organização é deletada. | +| Organization.Deleted | Uma organização é excluída. | | Organization.Data.Updated | Os dados de uma organização são atualizados, por exemplo, nome da organização, descrição, custom.data, etc. | | Organization.Membership.Updated | Usuários ou aplicativos são adicionados ou removidos de uma organização. O payload inclui [campos delta de associação](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload). | -### Papel da organização \{#organization-role} +### Papel da organização (Organization role) \{#organization-role} | Tipo de evento | Descrição | | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | | OrganizationRole.Created | Um novo papel de organização é criado. | -| OrganizationRole.Deleted | Um papel de organização é deletado. | -| OrganizationRole.Data.Updated | Os dados de um papel de organização são atualizados, por exemplo, nome e descrição do papel de organização. | +| OrganizationRole.Deleted | Um papel de organização é excluído. | +| OrganizationRole.Data.Updated | Os dados de um papel de organização são atualizados, por exemplo, nome e descrição do papel da organização. | | OrganizationRole.Scopes.Updated | Permissões atribuídas a um papel de organização são adicionadas ou removidas. | -### Permissão da organização (escopo) \{#organization-permission-scope} +### Permissão da organização (escopo) (Organization permission (scope)) \{#organization-permission-scope} | Tipo de evento | Descrição | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | | OrganizationScope.Created | Uma nova permissão de organização é criada. | -| OrganizationScope.Deleted | Uma permissão de organização é deletada. | -| OrganizationScope.Data.Updated | Os dados de uma permissão de organização são atualizados, por exemplo, descrição da permissão de organização. | +| OrganizationScope.Deleted | Uma permissão de organização é excluída. | +| OrganizationScope.Data.Updated | Os dados de uma permissão de organização são atualizados, por exemplo, descrição da permissão da organização. | -### Eventos acionados pela Management API \{#management-api-triggered-events} +### Eventos disparados pela Management API \{#management-api-triggered-events} | Endpoint da API | Evento | | ---------------------------------------------------------- | ----------------------------------------------------------- | @@ -110,34 +110,35 @@ Este guia lista os diferentes eventos de webhook do Logto e explica quando cada | POST /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated | | DELETE /organization-roles/:id/scopes/:organizationScopeId | OrganizationRole.Scopes.Updated | -### Eventos acionados pela Experience API \{#experience-api-triggered-events} +### Eventos disparados pela Experience API \{#experience-api-triggered-events} -| Ação de interação do usuário | Evento | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -| Vinculação de email / telefone do usuário | User.Data.Updated | -| Vinculação de MFAs do usuário | User.Data.Updated | -| Vinculação social / SSO do usuário | User.Data.Updated | -| Redefinição de senha do usuário | User.Data.Updated | -| Registro de usuário | User.Created | -| Usuário provisionado automaticamente em uma organização via [provisionamento Just-in-Time](/organizations/just-in-time-provisioning) (correspondência de domínio de email ou conector SSO corporativo) | Organization.Membership.Updated | +| Ação de interação do usuário | Evento | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| Vinculação de email/telefone do usuário | User.Data.Updated | +| Vinculação de MFA do usuário | User.Data.Updated | +| Vinculação social/SSO do usuário | User.Data.Updated | +| Redefinição de senha do usuário | User.Data.Updated | +| Registro do usuário | User.Created | +| Usuário provisionado automaticamente em uma organização via [provisionamento Just-in-Time](/organizations/just-in-time-provisioning) (domínio de email correspondente ou conector SSO corporativo) | Organization.Membership.Updated | ## Eventos de hook de exceção \{#exception-hook-events} -### Segurança \{#security} +### Segurança (Security) \{#security} -| Tipo de evento | Descrição | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Identifier.Lockout | Uma conta de usuário é bloqueada devido a tentativas consecutivas de verificação de identidade falhadas. Pode ser acionado nos seguintes fluxos:
  • Falha na verificação de senha
  • Falha na verificação de código
  • Falha na verificação de token único
| +| Tipo de evento | Descrição | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identifier.Lockout | Uma conta de usuário é bloqueada devido a tentativas consecutivas de verificação de identidade falhadas. Pode ser disparado nos seguintes fluxos:
  • Falha na verificação de senha
  • Falha na verificação de código
  • Falha na verificação de token único
| +| Message.RateLimited | Um usuário final excede o [limite de envio por destinatário](/security/send-rate-limit) para códigos de verificação. Dispara apenas nos caminhos de envio do usuário final (Experience API e Account API), com payload `{ action, recipient }`. | -## FAQs \{#faqs} +## Perguntas frequentes (FAQs) \{#faqs}
-### Qual é a diferença entre `PostRegister` e `User.Created`? \{#whats-the-difference-between-postregister-and-usercreated} +### Qual a diferença entre `PostRegister` e `User.Created`? \{#whats-the-difference-between-postregister-and-usercreated} -`PostRegister` é acionado quando um usuário cria com sucesso uma nova conta através do fluxo de inscrição do usuário; `User.Created` é acionado quando uma nova conta de usuário é criada através da Management API. +`PostRegister` é disparado quando um usuário cria com sucesso uma nova conta pelo fluxo de cadastro do usuário; `User.Created` é disparado quando uma nova conta de usuário é criada através da Management API.
diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/README.mdx index cf78c27db8d..f7bbdec44e5 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/README.mdx @@ -12,7 +12,7 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; A segurança moderna de autenticação enfrenta ameaças que vão desde phishing, stuffing de credenciais, ataques de força bruta, ransomware, DDoS, até ataques impulsionados por IA. Proteger as identidades dos usuários é fundamental para garantir a confiança na marca e a conformidade. -O Logto oferece uma gestão de acesso segura e robusta, projetada para enfrentar esses riscos de frente. Ao priorizar a prevenção proativa de ameaças e a resiliência, garantimos que seus sistemas permaneçam protegidos sem comprometer a usabilidade. Com o Logto, a segurança não é um pensamento tardio — é a base, capacitando empresas a prosperar em uma era onde as ameaças evoluem, mas as defesas evoluem mais rápido. +O Logto oferece um gerenciamento de acesso seguro e robusto, projetado para enfrentar esses riscos de frente. Priorizando a prevenção proativa de ameaças e a resiliência, garantimos que seus sistemas permaneçam protegidos sem comprometer a usabilidade. Com o Logto, a segurança não é um pensamento tardio — é a base, capacitando empresas a prosperar em uma era onde as ameaças evoluem, mas as defesas evoluem ainda mais rápido. ## Configure proteção de segurança avançada \{#set-up-advanced-security-protection} @@ -40,7 +40,7 @@ O Logto oferece uma gestão de acesso segura e robusta, projetada para enfrentar }, { type: 'link', - label: 'Blocklist', + label: 'Lista de bloqueio', href: '/security/blocklist', description: 'Tenha controle sobre sua base de usuários bloqueando domínios ou endereços de e-mail descartáveis ou indesejados.', @@ -53,11 +53,21 @@ O Logto oferece uma gestão de acesso segura e robusta, projetada para enfrentar label: 'Bloqueio de identificador', href: '/security/identifier-lockout', description: - 'Bloqueie temporariamente um identificador após múltiplas tentativas de autenticação falhadas para evitar acesso por força bruta.', + 'Bloqueie temporariamente um identificador após várias tentativas de autenticação malsucedidas para evitar acesso por força bruta.', customProps: { icon: , }, }, + { + type: 'link', + label: 'Limite de envio', + href: '/security/send-rate-limit', + description: + 'Limite o envio de códigos de verificação e mensagens por destinatário para evitar spam na caixa de entrada e abuso de SMS pumping.', + customProps: { + icon: , + }, + }, { type: 'link', label: 'Ocultar existência da conta', diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..56c4199213c --- /dev/null +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: Limite de envio +sidebar_position: 5 +--- + +# Limitação de taxa de envio + +O Logto aplica um limite de taxa interno, por destinatário, para códigos de verificação enviados e outras mensagens enviadas por e-mail e SMS. Isso protege seus usuários e seus provedores de mensagens contra abuso de envio — como um invasor enviando spam para a caixa de entrada ou telefone de uma vítima com códigos, ou aumentando o tráfego de SMS para inflar seus custos. + +Esse limite é **obrigatório e em nível de sistema**: ele se aplica a todo locatário independentemente do plano e **não** é configurável pelo locatário. Ele é independente de: + +- As políticas de **[bloqueio de identificador](/security/identifier-lockout)** e **[CAPTCHA](/security/captcha)**, que limitam _tentativas de verificação falhas_ no momento da verificação, e não o ato de _enviar_. +- O limite global de taxa de API por locatário (código de erro `request.rate_limited`), que limita o volume geral de solicitações em um locatário. + +## Como funciona \{#how-it-works} + +- **Limite por destinatário**: O Logto limita quantas mensagens podem ser enviadas para o mesmo destinatário (endereço de e-mail ou número de telefone) dentro de uma janela de tempo curta e deslizante. Por padrão, isso permite até **10 envios por destinatário a cada 10 minutos**. +- **Onde se aplica**: todos os caminhos de envio do lado do servidor, incluindo envios de código de verificação da Experience API e Account API (login, registro, redefinição de senha, MFA e vinculação de identificador), envios de código de verificação da Management API, envio e reenvio de convite de organização, e envios de código de verificação da Account (`/me`). +- **Quando o limite é excedido**: a solicitação é rejeitada com HTTP `429` e o código de erro `request.message_rate_limited` — distinto do limitador global do locatário (`request.rate_limited`) e do bloqueio no momento da verificação (`session.verification_blocked_too_many_attempts`), para que você possa tratá-lo especificamente em sua integração. + +## Monitore envios limitados por taxa com um webhook \{#monitor-rate-limited-sends-with-a-webhook} + +Quando um **usuário final** atinge o limite por destinatário, o Logto aciona o evento de webhook `Message.RateLimited` ([eventos de webhook](/developers/webhooks/webhooks-events#exception-hook-events)), para que você possa alertar ou responder a abusos de envio. + +- **Disparado para**: apenas caminhos de envio de código de verificação do usuário final — Experience API e Account API. Ele **não** é disparado para envios de primeira parte ou iniciados por administrador (códigos de verificação da Management API, convites de organização ou `/me`). +- **Payload**: o contexto do hook inclui a `action` (por exemplo, `VerificationCodeSend`) e o `recipient` (o endereço de e-mail ou número de telefone). + +**Casos de uso comuns:** + +- Enviar alertas de segurança para sua equipe revisar. +- Acionar automações antiabuso downstream para o destinatário afetado. + +Navegue até Console > Webhooks para se inscrever, ou crie o hook via Management API. Para a estrutura detalhada do evento e configuração, veja [Webhooks](/developers/webhooks). + +## Entrega suprimida para destinatários desconhecidos \{#suppressed-delivery-to-unknown-recipients} + +Para evitar enumeração de contas, quando o cadastro via identificador está desabilitado, um código de verificação de login solicitado para um endereço de e-mail ou número de telefone que **nenhuma conta possui** não é entregue silenciosamente, e a API responde da mesma forma que faria para um envio real. Assim, um invasor não pode usar essas respostas para descobrir quais endereços estão registrados. A entrega para usuários existentes não é afetada. Veja também [Ocultar existência de conta](/end-user-flows/sign-up-and-sign-in). diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/README.mdx index 3249863c2f5..5b975847729 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -1,6 +1,6 @@ # นักพัฒนา -Logto คือบริการ [การจัดการข้อมูลระบุตัวตนและการเข้าถึง (IAM)](https://auth.wiki/iam) ที่สร้างขึ้นบนโปรโตคอล [OAuth 2](https://auth.wiki/oauth-2.0) และ [OIDC](https://auth.wiki/openid-connect) บริการ IAM เช่น Logto มักเป็นรากฐานของบริการเว็บอื่น ๆ; สถานะการอนุญาต (Authorization) ต่าง ๆ ภายในบริการเว็บเหล่านั้นได้รับผลกระทบโดยตรงจาก Logto +Logto คือบริการ [การจัดการข้อมูลระบุตัวตนและการเข้าถึง (IAM)](https://auth.wiki/iam) ที่สร้างขึ้นบนโปรโตคอล [OAuth 2](https://auth.wiki/oauth-2.0) และ [OIDC](https://auth.wiki/openid-connect) บริการ IAM เช่น Logto มักเป็นรากฐานให้กับบริการเว็บอื่น ๆ; สถานะการอนุญาต (Authorization) ต่าง ๆ ภายในบริการเว็บเหล่านั้นได้รับผลกระทบโดยตรงจาก Logto เพื่ออำนวยความสะดวกให้กับผู้ใช้ Logto จึงมีฟีเจอร์สำหรับนักพัฒนาที่ใช้บ่อยหลายรายการ @@ -21,7 +21,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Custom access token', href: '/developers/custom-token-claims', - description: 'ใช้สคริปต์กำหนดเองเพื่อแนบการอ้างสิทธิ์ (Claims) เพิ่มเติมไปยังโทเค็นการเข้าถึง (Access token) ช่วยให้รองรับ ABAC หรือปฏิเสธการออกโทเค็น', + description: 'ใช้สคริปต์ที่กำหนดเองเพื่อแนบการอ้างสิทธิ์ (claims) เพิ่มเติมไปยังโทเค็นการเข้าถึง (Access token) ช่วยให้สามารถใช้ ABAC หรือปฏิเสธการออกโทเค็นได้', customProps: { icon: , } @@ -30,7 +30,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Custom ID token', href: '/developers/custom-id-token', - description: 'ควบคุมว่าการอ้างสิทธิ์ (Claims) แบบขยายใดจะถูกรวมในโทเค็น ID (ID token) ตามข้อกำหนดของ OIDC', + description: 'ควบคุมว่าการอ้างสิทธิ์ (claims) ที่ขยายเพิ่มเติมใดจะถูกรวมอยู่ในโทเค็น ID (ID token) ตามข้อกำหนดของ OIDC', customProps: { icon: , } @@ -44,6 +44,15 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; icon: , } }, + { + type: 'link', + label: 'Service-to-service delegation', + href: '/developers/service-to-service-delegation', + description: 'แลกเปลี่ยนโทเค็นการเข้าถึงของผู้ใช้ (User access token) เป็นโทเค็นการเข้าถึง API ปลายทาง เพื่อให้บริการ backend สามารถดำเนินการแทนผู้ใช้ปัจจุบันได้', + customProps: { + icon: , + } + }, ]} /> ``` @@ -57,7 +66,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Signing keys', href: '/developers/signing-keys', - description: 'ให้คีย์สำหรับลงนามในระดับระบบ ผ่านตู้นิรภัยรหัสผ่าน (password vault) เพื่อเพิ่มความปลอดภัยให้กับบริการยืนยันตัวตน', + description: 'ให้คีย์สำหรับลงนามในระดับระบบ ผ่าน password vault ทำให้บริการ auth มีความปลอดภัยมากขึ้น', customProps: { icon: , } @@ -75,7 +84,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'Audit logs', href: '/developers/audit-logs', - description: 'บันทึกกิจกรรมที่เกี่ยวข้องกับการยืนยันตัวตนของผู้ใช้ เพื่อช่วยในการดีบักและวิเคราะห์กิจกรรมของผู้ใช้', + description: 'บันทึกกิจกรรมที่เกี่ยวข้องกับการยืนยันตัวตน (Authentication) ของผู้ใช้ เพื่อช่วยในการดีบักและวิเคราะห์กิจกรรมของผู้ใช้', customProps: { icon: , } @@ -84,7 +93,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: 'SDK convention', href: '/developers/', - description: 'แนะนำโครงสร้างข้อมูล วัตถุประสงค์ และวิธีการใน SDK เพื่อให้ผู้ใช้สามารถปรับแต่ง SDK ให้เหมาะกับแต่ละกรณีธุรกิจ', + description: 'แนะนำโครงสร้างข้อมูล วัตถุประสงค์ และวิธีการใน SDK เพื่อให้ผู้ใช้สามารถปรับแต่ง SDK ให้เหมาะกับแต่ละกรณีธุรกิจได้', customProps: { icon: , } diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index e544a34d3fb..a8918627abf 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # บันทึกการตรวจสอบ (Audit logs) @@ -8,25 +8,25 @@ sidebar_position: 7 ## ดูบันทึกทั้งหมด \{#view-all-logs} -ไปที่ Console > บันทึกการตรวจสอบ (Audit logs) Logto จะบันทึกและจัดระเบียบเหตุการณ์การยืนยันตัวตน (authentication events) ลงในตาราง โดยจะติดตามชื่อเหตุการณ์, ผู้ใช้, แอปพลิเคชัน และเวลาที่เกิดเหตุการณ์ คุณสามารถกรองผลลัพธ์โดยใช้ชื่อเหตุการณ์และชื่อแอปพลิเคชันได้ การคลิกที่เหตุการณ์ใดเหตุการณ์หนึ่งจะให้รายละเอียดเพิ่มเติม +ไปที่ Console > บันทึกการตรวจสอบ (Audit logs) Logto จะบันทึกและจัดระเบียบเหตุการณ์การยืนยันตัวตน (authentication events) ลงในตาราง โดยจะติดตามชื่อเหตุการณ์, ผู้ใช้, แอปพลิเคชัน และเวลาที่เกิดเหตุการณ์ คุณสามารถกรองผลลัพธ์ตามชื่อเหตุการณ์และชื่อแอปพลิเคชันได้ การคลิกที่เหตุการณ์ใดเหตุการณ์หนึ่งจะให้รายละเอียดเพิ่มเติม :::warning -บันทึกการตรวจสอบจะมีเฉพาะบันทึกที่เกิดขึ้นระหว่างกระบวนการยืนยันตัวตนของผู้ใช้เท่านั้น บันทึกการดำเนินการของ Management API จะไม่ถูกบันทึกไว้ +บันทึกการตรวจสอบจะบันทึกเฉพาะเหตุการณ์ที่เกิดขึ้นระหว่างกระบวนการยืนยันตัวตนของผู้ใช้เท่านั้น บันทึกการดำเนินการของ Management API จะไม่ถูกบันทึกไว้ ::: ## บันทึกกิจกรรมผู้ใช้ในระดับผู้เช่า (tenant) \{#capture-user-activity-at-the-tenant-level} -บันทึกของ Logto ให้รายละเอียดที่ครบถ้วน เพื่อความสะดวกในการดำเนินการและความปลอดภัยของลูกค้า โดยจะบันทึกข้อมูลดังต่อไปนี้: +บันทึกของ Logto ให้รายละเอียดที่ครอบคลุม เพื่อความสะดวกในการดำเนินการและความปลอดภัยของลูกค้า โดยจะบันทึกข้อมูลดังต่อไปนี้: - ประเภทของเหตุการณ์ (ดูรายการเหตุการณ์บันทึกการตรวจสอบทั้งหมดได้ [ที่นี่](/developers/audit-logs/event-types)) - แอปพลิเคชันที่เกี่ยวข้อง - ที่อยู่ IP - ผู้ใช้ที่เกี่ยวข้อง - รหัสบันทึก (Log ID) -- เวลาที่เกิดเหตุการณ์ +- เวลาที่เกิดเหตุการณ์ (Timestamp) - User-agent -ด้วยการเก็บบันทึกเหตุการณ์เหล่านี้ องค์กรสามารถตรวจจับความเสี่ยงด้านความปลอดภัยที่อาจเกิดขึ้นได้อย่างมีประสิทธิภาพ และตอบสนองได้อย่างทันท่วงทีเพื่อป้องกันการเข้าถึงระบบโดยไม่ได้รับอนุญาต +ด้วยการเก็บบันทึกเหตุการณ์เหล่านี้ องค์กรสามารถตรวจจับความเสี่ยงด้านความปลอดภัยที่อาจเกิดขึ้นได้อย่างมีประสิทธิภาพ และตอบสนองได้อย่างรวดเร็วเพื่อป้องกันการเข้าถึงระบบโดยไม่ได้รับอนุญาต Console > การจัดการผู้ใช้ -2. เลือกผู้ใช้ที่ต้องการและไปที่หน้ารายละเอียด -3. คลิกที่ "บันทึกผู้ใช้ (User logs)" ตารางที่แสดงจะมีเฉพาะเหตุการณ์บันทึกที่ดำเนินการและถูกกระตุ้นโดยผู้ใช้รายนั้นเท่านั้น +2. เลือกผู้ใช้ที่ต้องการและเข้าสู่หน้ารายละเอียด +3. คลิกที่ "บันทึกผู้ใช้ (User logs)" ตารางที่แสดงจะประกอบด้วยเหตุการณ์บันทึกที่ดำเนินการและถูกกระตุ้นโดยผู้ใช้รายนั้นเท่านั้น บันทึกการตรวจสอบที่เกี่ยวข้องกับผู้ใช้เฉพาะราย ## คำถามที่พบบ่อย \{#faqs} diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index 26db1212722..54a2ebbfea1 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,20 +2,20 @@ id: sdk-conventions title: แนวทางปฏิบัติของ Platform SDK sidebar_label: แนวทางปฏิบัติของ Platform SDK -sidebar_position: 8 +sidebar_position: 9 --- # แนวทางปฏิบัติของ Platform SDK -Logto มอบบริการการยืนยันตัวตนบนเว็บที่ทรงพลังและยืดหยุ่นมาก +Logto ให้บริการการยืนยันตัวตน (Authentication) บนเว็บที่ทรงพลังและยืดหยุ่นมาก -ในการใช้งาน Logto จริง เพื่อความสะดวก มักจำเป็นที่นักพัฒนาจะต้องผสานรวม Logto SDK เข้ากับแอปพลิเคชันฝั่งลูกค้าของตนเองเพื่อจัดการสถานะการลงชื่อเข้าใช้ของผู้ใช้, สิทธิ์ (permissions), และอื่น ๆ +ในการใช้งาน Logto จริง เพื่อความสะดวก มักจำเป็นที่นักพัฒนาจะต้องผสานรวม Logto SDK เข้ากับแอปพลิเคชันฝั่งไคลเอนต์ของตนเอง เพื่อจัดการสถานะการลงชื่อเข้าใช้ของผู้ใช้ สิทธิ์ (permissions) และอื่น ๆ -คุณสามารถค้นหา SDK สำหรับภาษา / เฟรมเวิร์กโปรแกรมมิ่งทั้งหมดที่ Logto รองรับได้ [ที่นี่](/quick-starts) +คุณสามารถค้นหา SDK สำหรับภาษา / เฟรมเวิร์กโปรแกรมมิ่งที่ Logto รองรับทั้งหมด [ได้ที่นี่](/quick-starts) -หากคุณไม่พบ SDK ที่ต้องการ ต่อไปนี้คือแนวทางที่คุณสามารถปฏิบัติตามเพื่อพัฒนา SDK สำหรับภาษาที่คุณต้องการ เพื่อให้ง่ายต่อการใช้งานบริการของ Logto +หากคุณไม่พบ SDK ที่ต้องการ นี่คือแนวทางปฏิบัติที่คุณสามารถยึดถือเพื่อพัฒนา SDK สำหรับภาษาที่คุณต้องการ เพื่อให้ใช้งานบริการของ Logto ได้ง่ายขึ้น -แนวทางนี้ประกอบด้วย 3 ส่วนหลัก: +แนวทางปฏิบัตินี้ประกอบด้วย 3 ส่วนหลัก: กลยุทธ์การออกแบบ แนวทางปฏิบัติของ Core SDK @@ -28,9 +28,9 @@ Logto มอบบริการการยืนยันตัวตนบ - สร้าง SDK สำหรับเฟรมเวิร์ก Node.js ของ Logto ได้ในไม่กี่นาที + สร้าง SDK สำหรับเฟรมเวิร์ก Node.js ของ Logto ในไม่กี่นาที - สร้าง SDK สำหรับเว็บของ Logto ได้ในไม่กี่นาที + สร้าง SDK สำหรับเว็บของ Logto ในไม่กี่นาที diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..e1104e335b9 --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: การมอบหมายสิทธิ์ระหว่างบริการ (Service-to-service delegation) +sidebar_label: การมอบหมายสิทธิ์ระหว่างบริการ (Service-to-service delegation) +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# การมอบหมายสิทธิ์ระหว่างบริการ (Service-to-service delegation) + +ในสถาปัตยกรรม API บางแบบ บริการ backend จะได้รับคำขอจากผู้ใช้ที่ลงชื่อเข้าใช้แล้ว และจำเป็นต้องเรียกบริการ backend อื่น โดยยังคงรักษาเอกลักษณ์ของผู้ใช้เดิมไว้ + +ตัวอย่างเช่น: + +```text +User -> API A -> API B +``` + +API B จำเป็นต้องรู้สองสิ่ง: + +1. ผู้เรียกเป็นบริการที่เชื่อถือได้ เช่น API A +2. การดำเนินการนี้ถูกกระทำในนามของผู้ใช้เดิม + +ใช้ grant การแลกเปลี่ยนโทเค็นของ Logto เพื่อแลกเปลี่ยนโทเค็นการเข้าถึงของผู้ใช้เป็นโทเค็นการเข้าถึงใหม่ที่มีผู้รับ (audience) เป็นทรัพยากร API ปลายทาง วิธีนี้เป็นไปตามรูปแบบการแลกเปลี่ยนโทเค็นของ OAuth 2.0 และหลีกเลี่ยงการส่งต่อโทเค็นผู้ใช้เดิมไปยังบริการปลายทาง + +## เมื่อใดควรใช้ flow นี้ \{#when-to-use-this-flow} + +ใช้การมอบหมายสิทธิ์ระหว่างบริการเมื่อ: + +- API A เป็นบริการ backend ที่สามารถยืนยันตัวตนกับ token endpoint ของ Logto ได้อย่างปลอดภัย +- API A ได้รับโทเค็นการเข้าถึงผู้ใช้ที่ออกโดย Logto +- API A จำเป็นต้องเรียก API B ในนามของผู้ใช้เดียวกัน +- API B ควรตรวจสอบโทเค็นการเข้าถึงหนึ่งรายการ โดยมีทรัพยากร API ของตนเองเป็นผู้รับ + +อย่าใช้ flow นี้สำหรับการเข้าถึงแบบเครื่องต่อเครื่อง (machine-to-machine) ที่ไม่มีผู้ใช้ ในกรณีนั้นให้ใช้ [client credentials flow](/quick-starts/m2m) สำหรับกรณีสนับสนุน, แอดมิน หรือเอเจนต์ที่ผู้ใช้หนึ่งสวมรอยเป็นผู้ใช้อีกคน ให้ใช้ [การสวมรอยผู้ใช้ (User impersonation)](/developers/user-impersonation) + +## วิธีการทำงาน \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as ผู้ใช้ + participant ApiA as API A + participant Logto as Logto token endpoint + participant ApiB as API B + + User->>ApiA: Authorization: Bearer โทเค็นการเข้าถึงผู้ใช้ + Note over ApiA: ตรวจสอบโทเค็นผู้ใช้สำหรับ API A + + ApiA->>Logto: POST /oidc/token พร้อม token exchange grant + Note over ApiA,Logto: subject_token = โทเค็นการเข้าถึงของผู้ใช้
resource = ตัวบ่งชี้ทรัพยากรของ API B + + Logto-->>ApiA: โทเค็นการเข้าถึงสำหรับ API B + ApiA->>ApiB: Authorization: Bearer โทเค็นการเข้าถึงที่แลกเปลี่ยนแล้ว + Note over ApiB: ตรวจสอบผู้ออก, ผู้รับ, วันหมดอายุ, และขอบเขต +``` + +โทเค็นการเข้าถึงที่แลกเปลี่ยนแล้วจะแทนผู้ใช้เดิม (`sub`) และผูกกับทรัพยากร API ปลายทาง (`aud`) API ปลายทางยังสามารถตรวจสอบการอ้างสิทธิ์ `client_id` เพื่อระบุแอปพลิเคชันที่เริ่มต้นการแลกเปลี่ยนได้ + +## ข้อกำหนดเบื้องต้น \{#prerequisites} + +1. สร้างทรัพยากร API สำหรับบริการที่เกี่ยวข้อง ดู [ปกป้องทรัพยากร API ระดับโกลบอล](/authorization/global-api-resources) +2. กำหนดสิทธิ์ของ API B และมอบหมายให้ผู้ใช้ผ่านบทบาทหรือบทบาทขององค์กร +3. ใช้แอปพลิเคชันฝั่งเซิร์ฟเวอร์สำหรับ API A เช่นแอป machine-to-machine หรือเว็บแอปแบบดั้งเดิม เพื่อให้สามารถยืนยันตัวตนด้วย app secret ได้อย่างปลอดภัย +4. เปิดใช้งาน token exchange สำหรับแอปพลิเคชันของ API A + + + +## ขอรับโทเค็นการเข้าถึงสำหรับ API ปลายทาง \{#request-an-access-token-for-the-downstream-api} + +เมื่อ API A ต้องเรียก API B ให้ส่งคำขอแลกเปลี่ยนโทเค็นไปยัง [token endpoint](/integrate-logto/application-data-structure#token-endpoint) ของ Logto + +สำหรับเว็บแอปแบบดั้งเดิมหรือแอป machine-to-machine ที่มี app secret ให้ใส่ข้อมูลรับรองใน header `Authorization`: + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +พารามิเตอร์: + +1. `grant_type`: ใช้ `urn:ietf:params:oauth:grant-type:token-exchange` +2. `subject_token`: โทเค็นการเข้าถึงผู้ใช้ที่ออกโดย Logto ซึ่ง API A ได้รับมา +3. `subject_token_type`: ใช้ `urn:ietf:params:oauth:token-type:access_token` +4. `resource`: ตัวบ่งชี้ทรัพยากร API ของ API B +5. `scope`: ขอบเขต downstream ที่ API A ขอสำหรับการเรียกแบบมอบหมายนี้ Logto จะออกเฉพาะขอบเขตที่ผู้ใช้เดิมมีสิทธิ์สำหรับทรัพยากรนี้ตามการตั้งค่า RBAC + +Logto จะส่งคืนโทเค็นการเข้าถึงสำหรับ API B: + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +เมื่อถอดรหัสแล้ว โทเค็นการเข้าถึงจะมีการอ้างสิทธิ์คล้ายกับ: + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +จากนั้น API A จะเรียก API B พร้อมโทเค็นที่แลกเปลี่ยนแล้ว: + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## ตรวจสอบโทเค็นใน API B \{#validate-the-token-in-api-b} + +API B ควรตรวจสอบโทเค็นที่แลกเปลี่ยนแล้วเช่นเดียวกับโทเค็นการเข้าถึงทรัพยากร API ที่ออกโดย Logto: + +1. ตรวจสอบลายเซ็นด้วย JWKs ของ Logto +2. ตรวจสอบผู้ออก (`iss`) +3. ตรวจสอบว่าผู้รับ (`aud`) ตรงกับตัวบ่งชี้ทรัพยากรของ API B +4. ตรวจสอบวันหมดอายุ (`exp`) +5. ตรวจสอบขอบเขตที่ต้องการ +6. ใช้ `sub` เป็น user ID เดิม +7. ตรวจสอบ `client_id` เพิ่มเติมหากอนุญาตเฉพาะ upstream service บางตัวให้เรียกแบบมอบหมาย + +ดู [ตรวจสอบโทเค็นการเข้าถึงใน API](/authorization/validate-access-tokens) สำหรับแนวทางการใช้งาน + +## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} + +ปกป้องทรัพยากร API ระดับโกลบอล + +ตรวจสอบโทเค็นการเข้าถึงใน API + +การสวมรอยผู้ใช้ (User impersonation) diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index bb3480bdfaf..5ebfd47015a 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,32 +2,32 @@ id: signing-keys title: คีย์สำหรับลงนาม (Signing keys) sidebar_label: คีย์สำหรับลงนาม (Signing keys) -sidebar_position: 5 +sidebar_position: 6 --- # คีย์สำหรับลงนาม (Signing keys) -คีย์สำหรับลงนาม OIDC ของ Logto ([OIDC signing keys](https://auth.wiki/signing-key)) หรือที่เรียกว่า "OIDC private keys" และ "OIDC cookie keys" คือคีย์ที่ใช้สำหรับลงนาม JWT ([โทเค็นการเข้าถึง (Access tokens)](https://auth.wiki/access-token) และ [โทเค็น ID (ID tokens)](https://auth.wiki/id-token)) และคุกกี้ของเบราว์เซอร์ใน [เซสชันการลงชื่อเข้าใช้ (sign-in sessions)](/sessions#what-is-a-logto-session) ของ Logto คีย์เหล่านี้จะถูกสร้างขึ้นเมื่อมีการ seed ฐานข้อมูล Logto ([โอเพ่นซอร์ส](/logto-oss)) หรือสร้าง tenant ใหม่ ([Cloud](/logto-cloud)) และสามารถจัดการได้ผ่าน [CLI](/logto-oss/using-cli) (โอเพ่นซอร์ส), Management API หรือ Console UI +คีย์สำหรับลงนาม OIDC ของ Logto ([OIDC signing keys](https://auth.wiki/signing-key)) หรือที่เรียกว่า "OIDC private keys" และ "OIDC cookie keys" คือคีย์ที่ใช้สำหรับลงนาม JWTs ([โทเค็นการเข้าถึง (Access tokens)](https://auth.wiki/access-token) และ [โทเค็น ID (ID tokens)](https://auth.wiki/id-token)) และคุกกี้ของเบราว์เซอร์ใน [เซสชันการลงชื่อเข้าใช้ (sign-in sessions)](/sessions#what-is-a-logto-session) ของ Logto คีย์เหล่านี้จะถูกสร้างขึ้นเมื่อมีการ seed ฐานข้อมูล Logto ([โอเพ่นซอร์ส](/logto-oss)) หรือสร้าง tenant ใหม่ ([Cloud](/logto-cloud)) และสามารถจัดการได้ผ่าน [CLI](/logto-oss/using-cli) (โอเพ่นซอร์ส), Management APIs หรือ Console UI -โดยปกติ Logto จะใช้ อัลกอริทึม elliptic curve (EC) ในการสร้างลายเซ็นดิจิทัล อย่างไรก็ตาม เนื่องจากผู้ใช้มักต้องตรวจสอบลายเซ็นของ JWT และเครื่องมือรุ่นเก่าหลายตัวไม่รองรับอัลกอริทึม EC (รองรับเฉพาะ RSA) เราจึงได้เพิ่มฟีเจอร์หมุนเวียนคีย์ส่วนตัว (private key rotation) และให้ผู้ใช้เลือกอัลกอริทึมสำหรับลายเซ็น (ทั้ง RSA และ EC) เพื่อให้สามารถใช้งานร่วมกับบริการที่ใช้เครื่องมือตรวจสอบลายเซ็นรุ่นเก่าได้ +โดยปกติ Logto จะใช้ อัลกอริทึม elliptic curve (EC) สำหรับสร้างลายเซ็นดิจิทัล อย่างไรก็ตาม เนื่องจากผู้ใช้มักต้องตรวจสอบลายเซ็นของ JWT และเครื่องมือรุ่นเก่าหลายตัวไม่รองรับอัลกอริทึม EC (รองรับเฉพาะ RSA) เราจึงได้เพิ่มฟีเจอร์สำหรับหมุนเวียน (rotate) คีย์ส่วนตัว และให้ผู้ใช้เลือกอัลกอริทึมสำหรับลายเซ็น (ทั้ง RSA และ EC) เพื่อให้แน่ใจว่าสามารถใช้งานร่วมกับบริการที่ใช้เครื่องมือตรวจสอบลายเซ็นรุ่นเก่าได้ :::note -ตามทฤษฎีแล้ว คีย์สำหรับลงนามไม่ควรถูกเปิดเผยและไม่มีวันหมดอายุ หมายความว่าไม่จำเป็นต้องหมุนเวียนคีย์ อย่างไรก็ตาม การหมุนเวียนคีย์เป็นระยะ ๆ หลังจากช่วงเวลาหนึ่งจะช่วยเพิ่มความปลอดภัย +ตามทฤษฎีแล้ว คีย์สำหรับลงนามไม่ควรถูกเปิดเผยและไม่มีวันหมดอายุ หมายความว่าไม่จำเป็นต้องหมุนเวียนคีย์ อย่างไรก็ตาม การหมุนเวียนคีย์เป็นระยะหลังจากใช้งานไปช่วงหนึ่งจะช่วยเพิ่มความปลอดภัย ::: ## ทำงานอย่างไร? \{#how-it-works} - **OIDC private key** - เมื่อเริ่มต้นอินสแตนซ์ Logto จะมีการสร้างคู่คีย์สาธารณะและคีย์ส่วนตัวโดยอัตโนมัติ และลงทะเบียนไว้ใน OIDC provider ที่อยู่เบื้องหลัง ดังนั้นเมื่อ Logto ออก JWT ใหม่ (โทเค็นการเข้าถึง หรือ โทเค็น ID) โทเค็นจะถูกลงนามด้วยคีย์ส่วนตัว ในขณะเดียวกัน แอปพลิเคชันฝั่งไคลเอนต์ที่ได้รับ JWT สามารถใช้คีย์สาธารณะที่จับคู่กันเพื่อตรวจสอบลายเซ็นของโทเค็น เพื่อให้แน่ใจว่าโทเค็นไม่ได้ถูกแก้ไขโดยบุคคลที่สาม คีย์ส่วนตัวจะถูกปกป้องบนเซิร์ฟเวอร์ Logto ส่วนคีย์สาธารณะจะเปิดเผยต่อสาธารณะตามชื่อ สามารถเข้าถึงได้ผ่านอินเทอร์เฟซ `/oidc/jwks` ของ OIDC endpoint สามารถระบุอัลกอริทึมของคีย์สำหรับลงนามได้ขณะสร้างคีย์ส่วนตัว โดย Logto จะใช้อัลกอริทึม EC (Elliptic Curve) เป็นค่าเริ่มต้น ผู้ดูแลระบบสามารถเปลี่ยนอัลกอริทึมเริ่มต้นเป็น RSA (Rivest-Shamir-Adleman) ได้โดยการหมุนเวียนคีย์ส่วนตัว + เมื่อเริ่มต้นอินสแตนซ์ Logto จะมีการสร้างคู่คีย์ public / private ขึ้นโดยอัตโนมัติ และลงทะเบียนไว้ใน OIDC provider ที่อยู่เบื้องหลัง ดังนั้นเมื่อ Logto ออก JWT ใหม่ (โทเค็นการเข้าถึง หรือ โทเค็น ID) โทเค็นจะถูกลงนามด้วยคีย์ส่วนตัว ในขณะเดียวกัน แอปพลิเคชันฝั่งไคลเอนต์ที่ได้รับ JWT สามารถใช้คีย์สาธารณะคู่กันเพื่อตรวจสอบลายเซ็นของโทเค็น เพื่อให้แน่ใจว่าโทเค็นไม่ได้ถูกแก้ไขโดยบุคคลที่สาม คีย์ส่วนตัวจะถูกปกป้องไว้ในเซิร์ฟเวอร์ Logto ส่วนคีย์สาธารณะตามชื่อคือสาธารณะสำหรับทุกคน และเข้าถึงได้ผ่านอินเทอร์เฟซ `/oidc/jwks` ของ OIDC endpoint สามารถระบุอัลกอริทึมของคีย์สำหรับลงนามได้ขณะสร้างคีย์ส่วนตัว โดย Logto จะใช้อัลกอริทึม EC (Elliptic Curve) เป็นค่าเริ่มต้น ผู้ดูแลระบบสามารถเปลี่ยนอัลกอริทึมเริ่มต้นเป็น RSA (Rivest-Shamir-Adleman) ได้โดยการหมุนเวียนคีย์ส่วนตัว - **OIDC cookie key** - เมื่อผู้ใช้เริ่มต้น flow การลงชื่อเข้าใช้หรือสมัครสมาชิก จะมีการสร้าง "OIDC session" บนเซิร์ฟเวอร์ พร้อมกับชุดคุกกี้ของเบราว์เซอร์ ด้วยคุกกี้เหล่านี้ เบราว์เซอร์สามารถร้องขอ Logto Experience API เพื่อดำเนินการต่าง ๆ ในนามของผู้ใช้ เช่น ลงชื่อเข้าใช้ สมัครสมาชิก และรีเซ็ตรหัสผ่าน อย่างไรก็ตาม แตกต่างจาก JWT คุกกี้จะถูกลงนามและตรวจสอบโดยบริการ OIDC ของ Logto เองเท่านั้น ไม่จำเป็นต้องใช้การเข้ารหัสแบบอสมมาตร (asymmetric cryptography) ดังนั้นเราจึงไม่มีคีย์สาธารณะสำหรับคีย์ที่ใช้ลงนามคุกกี้ และไม่ใช้อัลกอริทึมเข้ารหัสแบบอสมมาตร + เมื่อผู้ใช้เริ่มต้น flow การลงชื่อเข้าใช้หรือสมัครสมาชิก จะมีการสร้าง "OIDC session" บนเซิร์ฟเวอร์ พร้อมกับชุดคุกกี้ของเบราว์เซอร์ โดยคุกกี้เหล่านี้ เบราว์เซอร์สามารถร้องขอ Logto Experience API เพื่อดำเนินการต่าง ๆ ในนามของผู้ใช้ เช่น ลงชื่อเข้าใช้ สมัครสมาชิก และรีเซ็ตรหัสผ่าน อย่างไรก็ตาม แตกต่างจาก JWT คุกกี้จะถูกลงนามและตรวจสอบลายเซ็นโดยบริการ OIDC ของ Logto เองเท่านั้น ไม่จำเป็นต้องใช้การเข้ารหัสแบบอสมมาตร (asymmetric cryptography) ดังนั้นเราจึงไม่มีคีย์สาธารณะคู่กับคีย์สำหรับลงนามคุกกี้ และไม่ใช้อัลกอริทึมเข้ารหัสแบบอสมมาตร ## หมุนเวียนคีย์สำหรับลงนามผ่าน Console UI \{#rotate-signing-keys-from-console-ui} -Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่วยให้คุณสร้าง OIDC private key และ cookie key ใหม่ใน tenant ของคุณได้ +Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่วยให้คุณสร้าง OIDC private key และ cookie key ใหม่ใน tenant ของคุณ 1. ไปที่ Console > Tenant settings > OIDC configs จากนั้นคุณสามารถจัดการทั้ง OIDC private keys และ OIDC cookie keys ได้ -2. หากต้องการหมุนเวียนคีย์สำหรับลงนาม ให้คลิกปุ่ม "Rotate private keys" หรือ "Rotate cookie keys" เมื่อหมุนเวียนคีย์ส่วนตัว คุณสามารถเลือกอัลกอริทึมสำหรับลงนามได้ +2. หากต้องการหมุนเวียนคีย์สำหรับลงนาม ให้คลิกปุ่ม "Rotate private keys" หรือ "Rotate cookie keys" เมื่อหมุนเวียนคีย์ส่วนตัว คุณสามารถเลือกอัลกอริทึมสำหรับลายเซ็นได้ 3. คุณจะพบตารางที่แสดงคีย์สำหรับลงนามทั้งหมดที่ใช้งานอยู่ สำหรับ OIDC private keys คุณสามารถลบคีย์ก่อนหน้าได้ แต่ไม่สามารถลบคีย์ปัจจุบันหรือคีย์ถัดไปได้ สำหรับ OIDC cookie keys คุณสามารถลบคีย์ก่อนหน้าได้ แต่ไม่สามารถลบคีย์ปัจจุบันได้ | สถานะ | คำอธิบาย | @@ -36,18 +36,18 @@ Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่ว | Current | หมายถึงคีย์นี้ถูกใช้โดย Logto ในการลงนาม JWT หรือคุกกี้ที่ออกใหม่ในขณะนี้ | | Previous | หมายถึงคีย์ที่เคยถูกใช้มาก่อนแต่ถูกหมุนเวียนออกไปแล้ว JWT หรือคุกกี้ที่ลงนามด้วยคีย์นี้จะยังคงใช้ได้จนกว่าจะหมดอายุหรือคีย์ถูกลบออก | -โปรดจำไว้ว่าการหมุนเวียนคีย์ประกอบด้วย 3 ขั้นตอนดังนี้: +โปรดจำไว้ว่าการหมุนเวียนคีย์เกี่ยวข้องกับ 3 ขั้นตอนดังนี้: -1. **สร้างคีย์สำหรับลงนามใหม่**: สำหรับ OIDC private keys, Logto สามารถเตรียมคีย์ใหม่ไว้ในสถานะ "Next" ก่อน เพื่อให้แอปพลิเคชันและ API ของคุณมีเวลาทำการรีเฟรชคีย์สาธารณะจาก endpoint `/oidc/jwks` ก่อนที่จะใช้คีย์ใหม่ในการลงนาม -2. **หมุนเวียนคีย์ปัจจุบัน**: เมื่อการหมุนเวียนมีผล คีย์ "Next" จะกลายเป็น "Current" และคีย์ "Current" เดิมจะกลายเป็น "Previous" โทเค็นที่ลงนามด้วยคีย์ก่อนหน้านี้จะยังคงใช้ได้ -3. **ลบคีย์ก่อนหน้าที่เก่าที่สุด**: Logto จะเก็บ OIDC private key ในสถานะ "Previous" ได้สูงสุดหนึ่งคีย์ หากมีคีย์ "Previous" อยู่แล้วเมื่อคีย์ staged กลายเป็น current คีย์ previous ที่เก่ากว่าจะถูกลบออก +1. **สร้างคีย์สำหรับลงนามใหม่**: สำหรับ OIDC private keys, Logto สามารถเตรียมคีย์ใหม่เป็นสถานะ "Next" ก่อน เพื่อให้แอปพลิเคชันและ API ของคุณมีเวลาทำการรีเฟรชคีย์สาธารณะจาก endpoint `/oidc/jwks` ก่อนที่คีย์ใหม่จะถูกใช้ในการลงนาม +2. **หมุนเวียนคีย์ปัจจุบัน**: เมื่อการหมุนเวียนมีผล คีย์ "Next" จะกลายเป็น "Current" และคีย์ "Current" เดิมจะกลายเป็น "Previous" โทเค็นที่ลงนามด้วยคีย์ก่อนหน้าจะยังคงใช้ได้ +3. **ลบคีย์ previous ที่เก่าที่สุด**: Logto จะเก็บ OIDC private key สถานะ "Previous" ได้สูงสุด 1 คีย์ หากมี previous key อยู่แล้วเมื่อคีย์ staged กลายเป็น current คีย์ previous ที่เก่ากว่าจะถูกลบออก -สำหรับ Logto Cloud การหมุนเวียน OIDC private key จะมีผลหลังจากช่วงเวลาผ่อนผัน 4 ชั่วโมง ในช่วงเวลานี้ คีย์ใหม่จะถูกเตรียมและเปิดเผยผ่าน JWKS ก่อนที่ Logto จะเริ่มใช้คีย์นี้ลงนาม JWT ที่ออกใหม่ ในตาราง Console คอลัมน์ **Effective at** จะแสดงเวลาที่คีย์ "Next" ที่ staged จะกลายเป็น "Current" +สำหรับ Logto Cloud การหมุนเวียน OIDC private key จะมีผลหลังช่วงเวลาผ่อนผัน 4 ชั่วโมง ในช่วงนี้คีย์ใหม่จะถูกเตรียมและเปิดเผยผ่าน JWKS ก่อนที่ Logto จะเริ่มใช้คีย์นี้ลงนาม JWT ที่ออกใหม่ ในตาราง Console คอลัมน์ **Effective at** จะแสดงเวลาที่คีย์ "Next" จะกลายเป็น "Current" -สำหรับการติดตั้งแบบ self-hosted OSS ค่าเริ่มต้นของช่วงเวลาผ่อนผันสำหรับการหมุนเวียนคีย์ส่วนตัวคือ `0` วินาที หมายความว่าการหมุนเวียนจะเกิดขึ้นทันที หากต้องการใช้ staged rotation ให้ตั้งค่าตัวแปรแวดล้อม `PRIVATE_KEY_ROTATION_GRACE_PERIOD` บน Logto service หรือส่งค่า `rotationGracePeriod` ใน request body เมื่อเรียก Management API endpoint `POST /api/configs/oidc/private-keys/rotate` +สำหรับการติดตั้ง OSS แบบ self-hosted ค่าเริ่มต้นของช่วงเวลาผ่อนผันสำหรับการหมุนเวียนคีย์ส่วนตัวคือ `0` วินาที หมายถึงการหมุนเวียนมีผลทันที หากต้องการใช้ staged rotation ให้ตั้งค่าตัวแปรแวดล้อม `PRIVATE_KEY_ROTATION_GRACE_PERIOD` บน Logto service หรือส่งค่า `rotationGracePeriod` ใน request body เมื่อเรียก Management API endpoint `POST /api/configs/oidc/private-keys/rotate` :::warning -หลีกเลี่ยงการหมุนเวียนคีย์สำหรับลงนามซ้ำ ๆ ก่อนที่การหมุนเวียนที่รอดำเนินการจะมีผล เว้นแต่คุณต้องการแทนที่คีย์ "Next" ที่ staged โดยตั้งใจ +หลีกเลี่ยงการหมุนเวียนคีย์สำหรับลงนามซ้ำ ๆ ก่อนที่การหมุนเวียนที่รอดำเนินการจะมีผล เว้นแต่คุณต้องการแทนที่คีย์ "Next" ที่เตรียมไว้โดยตั้งใจ การลบคีย์ "Previous" เพียงคีย์เดียวเร็วเกินไป อาจทำให้ JWT หรือคุกกี้ที่ลงนามด้วยคีย์นั้นใช้งานไม่ได้ ::: @@ -55,5 +55,5 @@ Logto มีฟีเจอร์ "Signing Keys Rotation" ซึ่งช่ว ## แหล่งข้อมูลที่เกี่ยวข้อง \{#related-resources} - แนะนำอัลกอริทึมการลงนาม EC และ RSA ใน JWT + แนะนำอัลกอริทึมลายเซ็น EC และ RSA ใน JWT (Introduction to EC and RSA signing algorithms in JWT) diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 812bf225905..5fad6e69ece 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,35 +1,35 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhook Logto [Webhook](https://auth.wiki/webhook) ให้การแจ้งเตือนแบบเรียลไทม์สำหรับเหตุการณ์ต่าง ๆ รวมถึงการเปลี่ยนแปลงบัญชีผู้ใช้, บทบาท (Role), สิทธิ์ (Permission), องค์กร (Organization), บทบาทขององค์กร, สิทธิ์ขององค์กร และ [การโต้ตอบของผู้ใช้](/end-user-flows) -เมื่อเกิดเหตุการณ์ Logto จะส่ง HTTP request ไปยัง Endpoint URL ที่คุณกำหนด โดยมีข้อมูลรายละเอียดของเหตุการณ์ เช่น user ID, username, email และรายละเอียดอื่น ๆ ที่เกี่ยวข้อง (สำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลใน payload และ header ดูที่ [Webhook request](/developers/webhooks/webhooks-request)) แอปพลิเคชันของคุณสามารถประมวลผล request นี้และดำเนินการที่กำหนดเอง เช่น ส่งอีเมลหรืออัปเดตข้อมูลในฐานข้อมูล +เมื่อเกิดเหตุการณ์ Logto จะส่ง HTTP request ไปยัง Endpoint URL ที่คุณกำหนด โดยมีข้อมูลรายละเอียดของเหตุการณ์ เช่น user ID, username, email และรายละเอียดอื่น ๆ ที่เกี่ยวข้อง (สำหรับข้อมูลเพิ่มเติมเกี่ยวกับข้อมูลใน payload และ header ดูที่ [Webhook request](/developers/webhooks/webhooks-request)) แอปพลิเคชันของคุณสามารถประมวลผล request นี้และดำเนินการที่กำหนดเอง เช่น ส่งอีเมล หรืออัปเดตข้อมูลในฐานข้อมูล -เรายังคงเพิ่มเหตุการณ์ใหม่ ๆ ตามความต้องการของผู้ใช้ หากคุณมีความต้องการเฉพาะสำหรับธุรกิจของคุณ โปรดแจ้งให้เราทราบ +เรายังคงเพิ่มเหตุการณ์ใหม่ ๆ ตามความต้องการของผู้ใช้ หากคุณมีความต้องการเฉพาะสำหรับธุรกิจของคุณ กรุณาแจ้งให้เราทราบ ## ทำไมต้องใช้ Webhook? \{#why-use-webhook} -Webhook มอบการสื่อสารแบบเรียลไทม์ระหว่างแอปพลิเคชัน ช่วยลดความจำเป็นในการ polling และทำให้ข้อมูลอัปเดตทันที ช่วยให้การผสานแอปพลิเคชันและการทำงานอัตโนมัติของ workflow ง่ายขึ้นโดยไม่ต้องใช้โค้ดที่ซับซ้อนหรือ API เฉพาะทาง +Webhook มอบการสื่อสารแบบเรียลไทม์ระหว่างแอปพลิเคชัน ช่วยลดความจำเป็นในการ polling และทำให้ข้อมูลอัปเดตทันที ช่วยให้การผสานระบบและการทำงานอัตโนมัติของแอปพลิเคชันง่ายขึ้นโดยไม่ต้องใช้โค้ดที่ซับซ้อนหรือ API เฉพาะทาง -ตัวอย่างการใช้งาน Webhook ที่พบบ่อยสำหรับ CIAM ได้แก่: +ตัวอย่างการใช้งาน Webhook ที่พบบ่อยสำหรับ CIAM: -- **ส่งอีเมล:** ตั้งค่า Webhook เพื่อส่งอีเมลต้อนรับให้ผู้ใช้ใหม่เมื่อสมัครสมาชิก หรือแจ้งเตือนผู้ดูแลระบบเมื่อผู้ใช้ลงชื่อเข้าใช้จากอุปกรณ์หรือสถานที่ใหม่ -- **ส่งการแจ้งเตือน:** ตั้งค่า Webhook เพื่อเรียกผู้ช่วยเสมือนกับระบบ CRM ของคุณเพื่อให้การสนับสนุนลูกค้าแบบเรียลไทม์เมื่อผู้ใช้สมัครสมาชิก -- **เรียก API เพิ่มเติม:** ตั้งค่า Webhook เพื่อตรวจสอบการเข้าถึงของผู้ใช้โดยเช็ค domain อีเมลหรือ IP address จากนั้นใช้ Logto Management API เพื่อกำหนดบทบาท (Role) และสิทธิ์ (Permission) ที่เหมาะสมกับทรัพยากร -- **ซิงโครไนซ์ข้อมูล:** ตั้งค่า Webhook เพื่อให้แอปพลิเคชันอัปเดตเกี่ยวกับการเปลี่ยนแปลง เช่น การระงับหรือการลบบัญชีผู้ใช้ -- **สร้างรายงาน:** ตั้งค่า Webhook เพื่อรับข้อมูลกิจกรรมการเข้าสู่ระบบของผู้ใช้และนำไปสร้างรายงานเกี่ยวกับการมีส่วนร่วมของผู้ใช้หรือรูปแบบการใช้งาน +- **ส่งอีเมล:** ตั้งค่า Webhook เพื่อส่งอีเมลต้อนรับให้ผู้ใช้ใหม่เมื่อสมัคร หรือแจ้งเตือนผู้ดูแลระบบเมื่อผู้ใช้ลงชื่อเข้าใช้จากอุปกรณ์หรือสถานที่ใหม่ +- **ส่งการแจ้งเตือน:** ตั้งค่า Webhook เพื่อเรียกผู้ช่วยเสมือนกับระบบ CRM ของคุณเพื่อให้การสนับสนุนลูกค้าแบบเรียลไทม์เมื่อผู้ใช้สมัคร +- **เรียก API เพิ่มเติม:** ตั้งค่า Webhook เพื่อตรวจสอบการเข้าถึงของผู้ใช้โดยเช็ค domain อีเมลหรือ IP address จากนั้นใช้ Logto Management API เพื่อกำหนดบทบาท (Role) และสิทธิ์ (Permission) ที่เหมาะสม +- **ซิงค์ข้อมูล:** ตั้งค่า Webhook เพื่อให้แอปพลิเคชันอัปเดตเกี่ยวกับการเปลี่ยนแปลง เช่น การระงับหรือการลบบัญชีผู้ใช้ +- **สร้างรายงาน:** ตั้งค่า Webhook เพื่อรับข้อมูลกิจกรรมการเข้าสู่ระบบของผู้ใช้และนำไปสร้างรายงานการมีส่วนร่วม หรือรูปแบบการใช้งานของผู้ใช้ ## คำศัพท์ \{#terms} -| Item | Description | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Event | เมื่อมีการดำเนินการเฉพาะ จะเกิด hook event ประเภทหนึ่ง เช่น Logto จะส่งเหตุการณ์ PostRegister เมื่อผู้ใช้ลงทะเบียนเสร็จและสร้างบัญชีใหม่ | -| Hook | การกระทำหนึ่งหรือหลายอย่างที่ผูกกับเหตุการณ์เฉพาะ การกระทำอาจเป็นการเรียก API, รันโค้ด ฯลฯ | -| Webhook | ประเภทหนึ่งของ hook ที่หมายถึงการเรียก API พร้อม payload ของเหตุการณ์นั้น | -| สมมติว่านักพัฒนาต้องการส่งการแจ้งเตือนเมื่อผู้ใช้ลงชื่อเข้าใช้ผ่านอุปกรณ์ใหม่ นักพัฒนาสามารถเพิ่ม webhook ที่เรียก API ของบริการรักษาความปลอดภัยของเขากับเหตุการณ์ PostSignIn ได้ | +| Item | Description | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| Event | เมื่อมีการดำเนินการเฉพาะ จะเกิด hook event ประเภทหนึ่ง เช่น Logto จะส่ง PostRegister hook event เมื่อผู้ใช้สมัครเสร็จและสร้างบัญชีใหม่แล้ว | +| Hook | การกระทำเดี่ยวหรือชุดของการกระทำที่ผูกกับเหตุการณ์หนึ่ง เช่น การเรียก API, การรันโค้ดสั้น ๆ ฯลฯ | +| Webhook | ประเภทหนึ่งของ hook ที่หมายถึงการเรียก API พร้อม payload ของเหตุการณ์นั้น | +| สมมติว่านักพัฒนาต้องการส่งการแจ้งเตือนเมื่อผู้ใช้ลงชื่อเข้าใช้ผ่านอุปกรณ์ใหม่ นักพัฒนาสามารถเพิ่ม webhook ที่เรียก API ของบริการความปลอดภัยของเขากับเหตุการณ์ PostSignIn ได้ | ตัวอย่างการเปิดใช้งาน web hook สองตัวสำหรับเหตุการณ์ `PostSignIn` ใน Logto: @@ -67,7 +67,7 @@ graph LR -แม้ว่า synced webhook จะทำให้ flow การลงชื่อเข้าใช้ของผู้ใช้ราบรื่นขึ้น แต่ขณะนี้เรายังไม่รองรับ (แต่จะรองรับในอนาคต) ดังนั้นกรณีที่ต้องพึ่ง synced webhook ในปัจจุบันจำเป็นต้องใช้วิธีแก้ไขเฉพาะ หากมีคำถามเพิ่มเติมสามารถติดต่อเราได้ +แม้ว่า synced webhook จะทำให้ flow การลงชื่อเข้าใช้ของผู้ใช้ราบรื่นขึ้น แต่ขณะนี้เรายังไม่รองรับ (แต่จะรองรับในอนาคต) ดังนั้นกรณีที่ต้องพึ่งพา synced webhook ในปัจจุบันจึงต้องใช้วิธีแก้ไขเฉพาะ หากคุณมีคำถามเพิ่มเติม โปรดติดต่อเรา @@ -85,22 +85,22 @@ graph LR
-### จะแก้ไขปัญหา webhook timeout อย่างไร? \{#how-to-debug-webhook-timeout} +### จะแก้ไขปัญหา webhook timeout ได้อย่างไร? \{#how-to-debug-webhook-timeout} -สำหรับ endpoint ที่รับ Webhook ควรตอบกลับด้วย response 2xx ให้เร็วที่สุดเพื่อแจ้ง Logto ว่าได้รับ Webhook แล้ว เนื่องจากแต่ละผู้ใช้อาจมีตรรกะการประมวลผล Webhook ที่แตกต่างกัน งานที่ซับซ้อนมากอาจใช้เวลาหลายวินาที ทำให้ Webhook ของ Logto timeout แนวทางที่ดีที่สุดคือสร้าง event queue ของคุณเอง เมื่อได้รับ Webhook จาก Logto ให้ใส่ event ลงใน queue แล้วตอบกลับ 2xx กลับไปที่ Logto จากนั้นให้ worker ของคุณประมวลผลงานใน queue ทีละขั้นตอน หาก worker พบข้อผิดพลาด ให้จัดการที่เซิร์ฟเวอร์ของคุณเอง +สำหรับ endpoint ที่รับ Webhook ควรตอบกลับด้วย 2xx response ให้เร็วที่สุดเพื่อแจ้ง Logto ว่าได้รับ Webhook แล้ว เนื่องจากแต่ละผู้ใช้อาจมีตรรกะการประมวลผล Webhook ที่แตกต่างกัน งานที่ซับซ้อนมากอาจใช้เวลาหลายวินาที ทำให้ Webhook ของ Logto timeout แนวทางที่ดีที่สุดคือสร้าง event queue ของคุณเอง เมื่อได้รับ Webhook จาก Logto ให้ใส่ event ลงใน queue แล้วตอบกลับ 2xx response จากนั้นให้ worker ของคุณประมวลผลงานใน queue ทีละขั้น หาก worker พบข้อผิดพลาด ให้จัดการที่เซิร์ฟเวอร์ของคุณเอง
-### สามารถรับ client IP address จาก webhook `PostSignIn` ได้หรือไม่? \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} +### ฉันสามารถรับ client IP address จาก webhook `PostSignIn` ได้หรือไม่? \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} -ได้ คุณสามารถรับ IP address, user agent ฯลฯ ใน payload ของ Webhook หากต้องการข้อมูลที่ยังไม่รองรับ สามารถสร้าง feature request ใน GitHub issues หรือ ติดต่อเรา +ได้ คุณสามารถรับ IP address, user agent ฯลฯ ใน payload ของ Webhook หากคุณต้องการข้อมูลที่ยังไม่รองรับในปัจจุบัน สามารถสร้าง feature request ใน GitHub issues หรือ ติดต่อเรา
diff --git a/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index 836667ce584..b4e089e22c3 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -1,74 +1,74 @@ --- id: webhooks-events -title: เหตุการณ์ Webhook -sidebar_label: เหตุการณ์ Webhook +title: เหตุการณ์ Webhooks +sidebar_label: เหตุการณ์ Webhooks sidebar_position: 3 --- # เหตุการณ์ Webhooks -คู่มือนี้แสดงรายการเหตุการณ์ Webhook ของ Logto ที่แตกต่างกันและอธิบายว่าแต่ละเหตุการณ์เกิดขึ้นเมื่อใด +คู่มือนี้จะแสดงรายการเหตุการณ์ webhook ของ Logto ที่แตกต่างกันและอธิบายว่าแต่ละเหตุการณ์เกิดขึ้นเมื่อใด -## เหตุการณ์การโต้ตอบของผู้ใช้ \{#user-interaction-hook-events} +## เหตุการณ์ hook จากการโต้ตอบของผู้ใช้ \{#user-interaction-hook-events} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ----------------- | ----------------------------------------------------------- | -| PostRegister | ผู้ใช้สร้างบัญชีใหม่สำเร็จผ่านอินเทอร์เฟซ UI | -| PostSignIn | ผู้ใช้ลงชื่อเข้าใช้สำเร็จผ่านอินเทอร์เฟซ UI | -| PostResetPassword | รหัสผ่านของผู้ใช้ถูกรีเซ็ตสำเร็จผ่านกระบวนการ "ลืมรหัสผ่าน" | +| ประเภทเหตุการณ์ | คำอธิบาย | +| ----------------- | --------------------------------------------------------- | +| PostRegister | ผู้ใช้สร้างบัญชีใหม่สำเร็จผ่านอินเทอร์เฟซ UI | +| PostSignIn | ผู้ใช้ลงชื่อเข้าใช้สำเร็จผ่านอินเทอร์เฟซ UI | +| PostResetPassword | รหัสผ่านของผู้ใช้ถูกรีเซ็ตสำเร็จผ่านขั้นตอน “ลืมรหัสผ่าน” | -## เหตุการณ์การเปลี่ยนแปลงข้อมูล \{#data-mutation-hook-events} +## เหตุการณ์ hook จากการเปลี่ยนแปลงข้อมูล \{#data-mutation-hook-events} ### ผู้ใช้ \{#user} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ----------------------------- | ------------------------------------------------------------------------------------- | -| User.Created | สร้างบัญชีผู้ใช้ใหม่ | -| User.Deleted | ลบบัญชีผู้ใช้ | -| User.Data.Updated | ข้อมูลโปรไฟล์ผู้ใช้ถูกอัปเดต เช่น อีเมล, อวาตาร์, custom.data, ตัวระบุโซเชียล เป็นต้น | -| User.SuspensionStatus.Updated | สถานะการระงับผู้ใช้ถูกเปลี่ยน (ถูกระงับหรือเปิดใช้งานใหม่) | +| ประเภทเหตุการณ์ | คำอธิบาย | +| ----------------------------- | ------------------------------------------------------------------------------ | +| User.Created | มีการสร้างบัญชีผู้ใช้ใหม่ | +| User.Deleted | บัญชีผู้ใช้ถูกลบ | +| User.Data.Updated | ข้อมูลโปรไฟล์ผู้ใช้ถูกอัปเดต เช่น อีเมล อวาตาร์ custom.data ตัวระบุโซเชียล ฯลฯ | +| User.SuspensionStatus.Updated | สถานะการระงับบัญชีผู้ใช้ถูกเปลี่ยน (ถูกระงับหรือเปิดใช้งานใหม่) | -### บทบาท \{#role} +### บทบาท (Role) \{#role} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ------------------- | ----------------------------------------------------------------------- | -| Role.Created | สร้างบทบาทใหม่ | -| Role.Deleted | ลบบทบาท | -| Role.Data.Updated | ข้อมูลของบทบาทถูกอัปเดต เช่น ชื่อบทบาท, คำอธิบาย, และสถานะบทบาทเริ่มต้น | -| Role.Scopes.Updated | สิทธิ์ที่กำหนดให้กับบทบาทถูกเพิ่มหรือลบ | +| ประเภทเหตุการณ์ | คำอธิบาย | +| ------------------- | --------------------------------------------------------------------- | +| Role.Created | มีการสร้างบทบาทใหม่ | +| Role.Deleted | บทบาทถูกลบ | +| Role.Data.Updated | ข้อมูลของบทบาทถูกอัปเดต เช่น ชื่อบทบาท คำอธิบาย และสถานะบทบาทเริ่มต้น | +| Role.Scopes.Updated | มีการเพิ่มหรือลบสิทธิ์ (permissions) ที่กำหนดให้กับบทบาท | -### สิทธิ์ (ขอบเขต) \{#permission-scope} +### สิทธิ์ (ขอบเขต; Permission / Scope) \{#permission-scope} | ประเภทเหตุการณ์ | คำอธิบาย | | ------------------ | ------------------------------------------------- | -| Scope.Created | สร้างสิทธิ์ API ใหม่ | -| Scope.Deleted | ลบสิทธิ์ API | +| Scope.Created | มีการสร้างสิทธิ์ API ใหม่ | +| Scope.Deleted | สิทธิ์ API ถูกลบ | | Scope.Data.Updated | ข้อมูลของสิทธิ์ API ถูกอัปเดต เช่น คำอธิบายสิทธิ์ | -### องค์กร \{#organization} +### องค์กร (Organization) \{#organization} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | สร้างองค์กรใหม่ | -| Organization.Deleted | ลบองค์กร | -| Organization.Data.Updated | ข้อมูลขององค์กรถูกอัปเดต เช่น ชื่อองค์กร, คำอธิบาย, custom.data เป็นต้น | -| Organization.Membership.Updated | ผู้ใช้หรือแอปพลิเคชันถูกเพิ่มหรือลบออกจากองค์กร ข้อมูลที่ส่งมารวมถึง [ฟิลด์การเปลี่ยนแปลงสมาชิก](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload) | +| ประเภทเหตุการณ์ | คำอธิบาย | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | มีการสร้างองค์กรใหม่ | +| Organization.Deleted | องค์กรถูกลบ | +| Organization.Data.Updated | ข้อมูลขององค์กรถูกอัปเดต เช่น ชื่อองค์กร คำอธิบาย custom.data ฯลฯ | +| Organization.Membership.Updated | มีการเพิ่มหรือลบผู้ใช้หรือแอปพลิเคชันออกจากองค์กร Payload จะมี [ฟิลด์ delta ของสมาชิก](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload) | -### บทบาทขององค์กร \{#organization-role} +### บทบาทขององค์กร (Organization role) \{#organization-role} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ------------------------------- | ------------------------------------------------------------------- | -| OrganizationRole.Created | สร้างบทบาทขององค์กรใหม่ | -| OrganizationRole.Deleted | ลบบทบาทขององค์กร | -| OrganizationRole.Data.Updated | ข้อมูลของบทบาทขององค์กรถูกอัปเดต เช่น ชื่อบทบาทขององค์กรและคำอธิบาย | -| OrganizationRole.Scopes.Updated | สิทธิ์ที่กำหนดให้กับบทบาทขององค์กรถูกเพิ่มหรือลบ | +| ประเภทเหตุการณ์ | คำอธิบาย | +| ------------------------------- | ------------------------------------------------------------- | +| OrganizationRole.Created | มีการสร้างบทบาทขององค์กรใหม่ | +| OrganizationRole.Deleted | บทบาทขององค์กรถูกลบ | +| OrganizationRole.Data.Updated | ข้อมูลของบทบาทองค์กรถูกอัปเดต เช่น ชื่อบทบาทองค์กรและคำอธิบาย | +| OrganizationRole.Scopes.Updated | มีการเพิ่มหรือลบสิทธิ์ที่กำหนดให้กับบทบาทขององค์กร | -### สิทธิ์ขององค์กร (ขอบเขต) \{#organization-permission-scope} +### สิทธิ์ขององค์กร (ขอบเขต; Organization permission / scope) \{#organization-permission-scope} | ประเภทเหตุการณ์ | คำอธิบาย | | ------------------------------ | -------------------------------------------------------------- | -| OrganizationScope.Created | สร้างสิทธิ์ขององค์กรใหม่ | -| OrganizationScope.Deleted | ลบสิทธิ์ขององค์กร | +| OrganizationScope.Created | มีการสร้างสิทธิ์ขององค์กรใหม่ | +| OrganizationScope.Deleted | สิทธิ์ขององค์กรถูกลบ | | OrganizationScope.Data.Updated | ข้อมูลของสิทธิ์ขององค์กรถูกอัปเดต เช่น คำอธิบายสิทธิ์ขององค์กร | ### เหตุการณ์ที่ถูกกระตุ้นโดย Management API \{#management-api-triggered-events} @@ -112,32 +112,33 @@ sidebar_position: 3 ### เหตุการณ์ที่ถูกกระตุ้นโดย Experience API \{#experience-api-triggered-events} -| การกระทำการโต้ตอบของผู้ใช้ | เหตุการณ์ | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| การเชื่อมโยงอีเมล / โทรศัพท์ของผู้ใช้ | User.Data.Updated | -| การเชื่อมโยง MFA ของผู้ใช้ | User.Data.Updated | -| การเชื่อมโยงโซเชียล / SSO ของผู้ใช้ | User.Data.Updated | -| การรีเซ็ตรหัสผ่านของผู้ใช้ | User.Data.Updated | -| การลงทะเบียนของผู้ใช้ | User.Created | -| ผู้ใช้ถูกจัดเตรียมอัตโนมัติในองค์กรผ่าน [การจัดเตรียมแบบ Just-in-Time](/organizations/just-in-time-provisioning) (การจับคู่โดเมนอีเมลหรือผู้ให้บริการ SSO ขององค์กร) | Organization.Membership.Updated | +| การกระทำของผู้ใช้ | เหตุการณ์ | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| การเชื่อมโยงอีเมล / โทรศัพท์ของผู้ใช้ | User.Data.Updated | +| การเชื่อมโยง MFA ของผู้ใช้ | User.Data.Updated | +| การเชื่อมโยงโซเชียล / SSO ของผู้ใช้ | User.Data.Updated | +| การรีเซ็ตรหัสผ่านของผู้ใช้ | User.Data.Updated | +| การลงทะเบียนผู้ใช้ | User.Created | +| ผู้ใช้ถูกจัดเตรียมเข้าสู่องค์กรโดยอัตโนมัติผ่าน [Just-in-Time Provisioning](/organizations/just-in-time-provisioning) (จับคู่โดเมนอีเมลหรือ Enterprise SSO Connector) | Organization.Membership.Updated | -## เหตุการณ์ข้อยกเว้น \{#exception-hook-events} +## เหตุการณ์ hook ข้อยกเว้น \{#exception-hook-events} ### ความปลอดภัย \{#security} -| ประเภทเหตุการณ์ | คำอธิบาย | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Identifier.Lockout | บัญชีผู้ใช้ถูกล็อกเนื่องจากความพยายามยืนยันตัวตนที่ล้มเหลวติดต่อกัน สามารถถูกกระตุ้นในกระบวนการต่อไปนี้:
  • การยืนยันรหัสผ่านล้มเหลว
  • การยืนยันรหัสล้มเหลว
  • การยืนยันโทเค็นครั้งเดียวล้มเหลว
| +| ประเภทเหตุการณ์ | คำอธิบาย | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Identifier.Lockout | บัญชีผู้ใช้ถูกล็อกเนื่องจากพยายามยืนยันตัวตนล้มเหลวติดต่อกัน สามารถถูกกระตุ้นในขั้นตอนต่อไปนี้:
  • ยืนยันรหัสผ่านล้มเหลว
  • ยืนยันรหัสล้มเหลว
  • ยืนยันโทเค็นแบบครั้งเดียวล้มเหลว
| +| Message.RateLimited | ผู้ใช้ปลายทางส่งคำขอรหัสยืนยันเกิน [ขีดจำกัดการส่งต่อผู้รับ](/security/send-rate-limit) เหตุการณ์นี้จะเกิดขึ้นเฉพาะในเส้นทางส่งของผู้ใช้ปลายทาง (Experience API และ Account API) โดย payload คือ `{ action, recipient }` | ## คำถามที่พบบ่อย \{#faqs}
-### ความแตกต่างระหว่าง `PostRegister` และ `User.Created` คืออะไร? \{#whats-the-difference-between-postregister-and-usercreated} +### ความแตกต่างระหว่าง `PostRegister` กับ `User.Created` คืออะไร? \{#whats-the-difference-between-postregister-and-usercreated} -`PostRegister` ถูกกระตุ้นเมื่อผู้ใช้สร้างบัญชีใหม่สำเร็จผ่านกระบวนการลงทะเบียนของผู้ใช้; `User.Created` ถูกกระตุ้นเมื่อมีการสร้างบัญชีผู้ใช้ใหม่ผ่าน Management API +`PostRegister` จะถูกกระตุ้นเมื่อผู้ใช้สร้างบัญชีใหม่สำเร็จผ่านขั้นตอนการสมัครของผู้ใช้ ส่วน `User.Created` จะถูกกระตุ้นเมื่อมีการสร้างบัญชีผู้ใช้ใหม่ผ่าน Management API
diff --git a/i18n/th/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/th/docusaurus-plugin-content-docs/current/security/README.mdx index a5a84c1ef16..858748901c1 100644 --- a/i18n/th/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/th/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # ความปลอดภัย -ความปลอดภัยของการยืนยันตัวตน (Authentication) สมัยใหม่ต้องต่อสู้กับภัยคุกคามหลากหลาย ตั้งแต่ฟิชชิ่ง การโจมตีด้วยข้อมูลประจำตัวซ้ำ (credential stuffing) การเดารหัสผ่าน (brute-force) แรนซัมแวร์ DDoS ไปจนถึงการโจมตีที่ขับเคลื่อนด้วย AI การปกป้องตัวตนของผู้ใช้จึงเป็นหัวใจสำคัญในการรักษาความน่าเชื่อถือของแบรนด์และการปฏิบัติตามข้อกำหนด +ความปลอดภัยของการยืนยันตัวตน (Authentication) สมัยใหม่ต้องต่อสู้กับภัยคุกคามตั้งแต่ฟิชชิ่ง, การยัดข้อมูลบัญชี (credential stuffing), การโจมตีแบบ brute-force, แรนซัมแวร์, DDoS ไปจนถึงการโจมตีโดย AI การปกป้องตัวตนของผู้ใช้จึงเป็นสิ่งสำคัญยิ่งต่อความน่าเชื่อถือของแบรนด์และการปฏิบัติตามข้อกำหนด -Logto มอบการจัดการการเข้าถึงที่ปลอดภัยและแข็งแกร่ง ออกแบบมาเพื่อตอบโต้ความเสี่ยงเหล่านี้โดยตรง ด้วยการให้ความสำคัญกับการป้องกันเชิงรุกและความยืดหยุ่นต่อภัยคุกคาม เราจึงมั่นใจว่าระบบของคุณจะได้รับการปกป้องโดยไม่ลดทอนประสบการณ์การใช้งาน สำหรับ Logto ความปลอดภัยไม่ใช่เรื่องที่คิดทีหลัง แต่เป็นรากฐานที่ช่วยให้ธุรกิจเติบโตในยุคที่ภัยคุกคามเปลี่ยนแปลงตลอดเวลา แต่การป้องกันก็พัฒนาเร็วกว่า +Logto มอบการจัดการการเข้าถึงที่ปลอดภัยและแข็งแกร่ง ออกแบบมาเพื่อตอบโต้ความเสี่ยงเหล่านี้โดยตรง ด้วยการให้ความสำคัญกับการป้องกันเชิงรุกและความยืดหยุ่นต่อภัยคุกคาม เราจึงมั่นใจว่าระบบของคุณจะได้รับการปกป้องโดยไม่ลดทอนประสบการณ์การใช้งาน ด้วย Logto ความปลอดภัยไม่ใช่เรื่องที่คิดทีหลัง—แต่เป็นรากฐานที่ช่วยให้ธุรกิจเติบโตในยุคที่ภัยคุกคามพัฒนา แต่การป้องกันก็พัฒนาเร็วยิ่งกว่า ## ตั้งค่าการป้องกันความปลอดภัยขั้นสูง \{#set-up-advanced-security-protection} @@ -23,7 +23,7 @@ Logto มอบการจัดการการเข้าถึงที label: 'นโยบายรหัสผ่าน', href: '/security/password-policy', description: - 'เพิ่มความเข้มงวดของรหัสผ่านเพื่อป้องกันการโจมตีด้วย credential stuffing และรหัสผ่านที่อ่อนแอ', + 'เพิ่มข้อกำหนดของรหัสผ่านเพื่อป้องกันการยัดข้อมูลบัญชี (credential stuffing) และการโจมตีด้วยรหัสผ่านที่อ่อนแอ', customProps: { icon: , }, @@ -33,7 +33,7 @@ Logto มอบการจัดการการเข้าถึงที label: 'CAPTCHA', href: '/security/captcha', description: - 'เพิ่ม CAPTCHA (เช่น Google reCAPTCHA, Cloudflare Turnstile) ในประสบการณ์การลงชื่อเข้าใช้เพื่อป้องกันบอทอัตโนมัติ', + 'เพิ่ม CAPTCHA (เช่น Google reCAPTCHA, Cloudflare Turnstile) ในประสบการณ์การลงชื่อเข้าใช้เพื่อป้องกันการโจมตีจากบอทอัตโนมัติ', customProps: { icon: , }, @@ -43,24 +43,34 @@ Logto มอบการจัดการการเข้าถึงที label: 'Blocklist', href: '/security/blocklist', description: - 'ควบคุมฐานผู้ใช้ของคุณโดยบล็อกโดเมนอีเมลหรือที่อยู่อีเมลที่ไม่ต้องการหรือใช้ชั่วคราว', + 'ควบคุมฐานผู้ใช้ของคุณโดยการบล็อกโดเมนอีเมลหรือที่อยู่อีเมลที่ใช้ชั่วคราวหรือไม่ต้องการ', customProps: { icon: , }, }, { type: 'link', - label: 'ล็อกเอาต์ตัวระบุ', + label: 'ล็อกเอาต์ตัวระบุ (Identifier lockout)', href: '/security/identifier-lockout', description: - 'ล็อกตัวระบุชั่วคราวหลังจากพยายามยืนยันตัวตนล้มเหลวหลายครั้งเพื่อป้องกันการเดารหัสผ่าน (brute force)', + 'ล็อกตัวระบุชั่วคราวหลังจากความพยายามยืนยันตัวตนล้มเหลวหลายครั้งเพื่อป้องกันการเข้าถึงแบบ brute force', customProps: { icon: , }, }, { type: 'link', - label: 'ซ่อนการมีอยู่ของบัญชี', + label: 'จำกัดอัตราการส่ง (Send rate limit)', + href: '/security/send-rate-limit', + description: + 'จำกัดการส่งรหัสยืนยันและข้อความต่อผู้รับแต่ละรายเพื่อป้องกันสแปมในกล่องจดหมายและการโจมตี SMS pumping', + customProps: { + icon: , + }, + }, + { + type: 'link', + label: 'ซ่อนการมีอยู่ของบัญชี (Hide account existence)', href: '/end-user-flows/sign-up-and-sign-in', description: 'ซ่อนสถานะบัญชีเพื่อป้องกันการโจมตีแบบนับบัญชี (account enumeration) และหลีกเลี่ยงการเปิดเผยข้อมูลสถานะบัญชีที่ละเอียดอ่อน', @@ -80,7 +90,7 @@ Logto มอบการจัดการการเข้าถึงที label: 'การยืนยันตัวตนหลายปัจจัย (MFA)', href: '/end-user-flows/mfa', description: - 'เพิ่มชั้นความปลอดภัยให้กับกระบวนการลงชื่อเข้าใช้ ด้วยการรองรับ OTP จากแอปยืนยันตัวตน, passkeys (WebAuthn), และรหัสสำรอง', + 'เพิ่มชั้นการป้องกันพิเศษให้กับกระบวนการลงชื่อเข้าใช้ ด้วยการรองรับ OTP จากแอปยืนยันตัวตน, passkey (WebAuthn), และรหัสสำรอง', customProps: { icon: , }, @@ -90,14 +100,14 @@ Logto มอบการจัดการการเข้าถึงที label: 'การยืนยันตัวตนแบบ Step-up', href: '/end-user-flows/security-verification', description: - 'ให้แอปสามารถร้องขอการยืนยันตัวตนเพิ่มเติมเมื่อผู้ใช้เข้าถึงข้อมูลสำคัญหรือดำเนินการที่มีความเสี่ยงสูง', + 'อนุญาตให้แอปแจ้งขอการยืนยันตัวตนเพิ่มเติมเมื่อผู้ใช้เข้าถึงข้อมูลสำคัญหรือดำเนินการที่มีความเสี่ยงสูง', customProps: { icon: , }, }, { type: 'link', - label: 'ระงับผู้ใช้', + label: 'ระงับผู้ใช้ (Suspend users)', href: '/user-management/manage-users#suspend-user', description: 'ปิดใช้งานบัญชีผู้ใช้ชั่วคราวเพื่อป้องกันการเข้าถึงโดยไม่ต้องลบข้อมูลหรือประวัติผู้ใช้', @@ -107,7 +117,7 @@ Logto มอบการจัดการการเข้าถึงที }, { type: 'link', - label: 'หมุนเวียนคีย์สำหรับลงนาม', + label: 'หมุนเวียนคีย์สำหรับลงนาม (Rotate signing keys)', href: '/developers/signing-keys', description: 'หมุนเวียนคีย์สำหรับลงนามเป็นระยะเพื่อป้องกันการรั่วไหลของคีย์และการปลอมแปลงโทเค็น', @@ -120,17 +130,17 @@ Logto มอบการจัดการการเข้าถึงที label: 'OIDC back-channel logout', href: '/end-user-flows/sign-out#federated-sign-out-back-channel-logout', description: - 'เปิดใช้งานการออกจากระบบแบบศูนย์กลางเพื่อลดความเสี่ยงของการแฮ็กเซสชันและการเข้าถึงโดยไม่ได้รับอนุญาต', + 'เปิดใช้งานการออกจากระบบแบบศูนย์กลางเพื่อลดความเสี่ยงจากการแย่งชิงเซสชันและการเข้าถึงโดยไม่ได้รับอนุญาต', customProps: { icon: , }, }, { type: 'link', - label: 'ลงทะเบียนด้วยคำเชิญเท่านั้น', + label: 'ลงทะเบียนด้วยคำเชิญเท่านั้น (Invitation-only sign up)', href: '/end-user-flows', description: - 'จำกัดการลงทะเบียนเฉพาะผู้ที่ได้รับเชิญ โดยใช้ magic link ทางอีเมลเพื่อความปลอดภัยในการเริ่มต้นใช้งาน', + 'จำกัดการลงทะเบียนเฉพาะผู้ที่ได้รับเชิญ โดยใช้ magic link ทางอีเมลเพื่อการเริ่มต้นใช้งานที่ปลอดภัย', customProps: { icon: , }, diff --git a/i18n/th/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/th/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..8bc69687018 --- /dev/null +++ b/i18n/th/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: ขีดจำกัดอัตราการส่ง +sidebar_position: 5 +--- + +# การจำกัดอัตราการส่ง (Send rate limiting) + +Logto ใช้ขีดจำกัดอัตราการส่งในตัวแบบต่อผู้รับ สำหรับรหัสยืนยันและข้อความอื่น ๆ ที่ส่งออกทางอีเมลและ SMS เพื่อปกป้องผู้ใช้ของคุณและผู้ให้บริการส่งข้อความของคุณจากการถูกละเมิดการส่ง เช่น ผู้โจมตีส่งสแปมรหัสไปยังกล่องจดหมายหรือโทรศัพท์ของเหยื่อ หรือปั๊มทราฟฟิก SMS เพื่อเพิ่มค่าใช้จ่ายของคุณ + +ขีดจำกัดนี้เป็น **ข้อบังคับและอยู่ในระดับระบบ**: ใช้กับทุก tenant ไม่ว่าจะแผนใด และ **ไม่สามารถปรับแต่งได้โดย tenant** ขีดจำกัดนี้แยกจาก: + +- **[การล็อกเอาต์ตามตัวระบุ](/security/identifier-lockout)** และ **[CAPTCHA](/security/captcha)** ซึ่งจำกัด _ความพยายามยืนยันที่ล้มเหลว_ ในขณะยืนยัน ไม่ใช่การ _ส่ง_ +- ขีดจำกัดอัตรา API ต่อ tenant ทั่วโลก (รหัสข้อผิดพลาด `request.rate_limited`) ซึ่งจำกัดปริมาณคำขอโดยรวมของ tenant + +## วิธีการทำงาน \{#how-it-works} + +- **จำกัดต่อผู้รับ**: Logto จำกัดจำนวนข้อความที่สามารถส่งไปยังผู้รับเดียวกัน (ที่อยู่อีเมลหรือหมายเลขโทรศัพท์) ภายในช่วงเวลาสั้น ๆ แบบ rolling โดยค่าเริ่มต้น อนุญาตให้ส่งได้สูงสุด **10 ครั้งต่อผู้รับทุก 10 นาที** +- **จุดที่ใช้ขีดจำกัดนี้**: ทุกเส้นทางการส่งฝั่งเซิร์ฟเวอร์ รวมถึงการส่งรหัสยืนยันผ่าน Experience API และ Account API (ลงชื่อเข้าใช้, ลงทะเบียน, รีเซ็ตรหัสผ่าน, MFA, และการผูกตัวระบุ), การส่งรหัสยืนยันผ่าน Management API, การเชิญองค์กรและการส่งซ้ำ, และการส่งรหัสยืนยันผ่าน Account (`/me`) +- **เมื่อเกินขีดจำกัด**: คำขอจะถูกปฏิเสธด้วย HTTP `429` และรหัสข้อผิดพลาด `request.message_rate_limited` ซึ่งแตกต่างจากขีดจำกัด tenant ทั่วโลก (`request.rate_limited`) และการล็อกเอาต์ขณะยืนยัน (`session.verification_blocked_too_many_attempts`) คุณจึงสามารถจัดการกรณีนี้เฉพาะในระบบของคุณได้ + +## ติดตามการส่งที่ถูกจำกัดด้วย webhook \{#monitor-rate-limited-sends-with-a-webhook} + +เมื่อ **ผู้ใช้ปลายทาง** เจอขีดจำกัดต่อผู้รับ Logto จะทริกเกอร์เหตุการณ์ webhook `Message.RateLimited` [webhook event](/developers/webhooks/webhooks-events#exception-hook-events) เพื่อให้คุณแจ้งเตือนหรือรับมือกับการละเมิดการส่ง + +- **ทริกเกอร์สำหรับ**: เส้นทางการส่งรหัสยืนยันของผู้ใช้ปลายทางเท่านั้น—Experience API และ Account API จะ **ไม่** ทริกเกอร์สำหรับการส่งโดย first-party หรือผู้ดูแลระบบ (รหัสยืนยัน Management API, การเชิญองค์กร หรือ `/me`) +- **Payload**: context ของ hook จะมี `action` (เช่น `VerificationCodeSend`) และ `recipient` (ที่อยู่อีเมลหรือหมายเลขโทรศัพท์) + +**กรณีการใช้งานทั่วไป:** + +- ส่งการแจ้งเตือนความปลอดภัยให้ทีมของคุณตรวจสอบ +- ทริกเกอร์ระบบอัตโนมัติป้องกันการละเมิดสำหรับผู้รับที่ได้รับผลกระทบ + +ไปที่ Console > Webhooks เพื่อสมัครใช้งาน หรือสร้าง hook ผ่าน Management API สำหรับโครงสร้างเหตุการณ์และการตั้งค่าโดยละเอียด ดูที่ [Webhooks](/developers/webhooks) + +## การระงับการส่งไปยังผู้รับที่ไม่รู้จัก \{#suppressed-delivery-to-unknown-recipients} + +เพื่อป้องกันการเดาและระบุบัญชี (account enumeration) เมื่อปิดการสมัครสมาชิกด้วยตัวระบุ หากมีการขอรหัสยืนยันสำหรับที่อยู่อีเมลหรือหมายเลขโทรศัพท์ที่ **ไม่มีบัญชีใดเป็นเจ้าของ** ระบบจะไม่ส่งรหัสนั้นโดยเงียบ ๆ และ API จะตอบกลับเหมือนกับการส่งจริง ผู้โจมตีจึงไม่สามารถใช้การตอบกลับเหล่านี้เพื่อดูว่าที่อยู่นั้นลงทะเบียนแล้วหรือไม่ การส่งไปยังผู้ใช้ที่มีอยู่จะไม่ได้รับผลกระทบ ดูเพิ่มเติมที่ [ซ่อนการมีอยู่ของบัญชี](/end-user-flows/sign-up-and-sign-in) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/README.mdx index 4916e189ef6..861a27fb76c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -1,6 +1,6 @@ # 开发者 -Logto 是一个基于 [OAuth 2](https://auth.wiki/oauth-2.0) 和 [OIDC](https://auth.wiki/openid-connect) 协议的[身份和访问管理 (IAM)](https://auth.wiki/iam)服务。像 Logto 这样的 IAM 服务通常作为其他 Web 服务的基础；这些 Web 服务中的各种授权 (Authorization) 状态会直接受到 Logto 的影响。 +Logto 是一个基于 [OAuth 2](https://auth.wiki/oauth-2.0) 和 [OIDC](https://auth.wiki/openid-connect) 协议的 [身份和访问管理 (IAM)](https://auth.wiki/iam) 服务。像 Logto 这样的 IAM 服务通常作为其他 Web 服务的基础；这些 Web 服务中的各种授权 (Authorization) 状态会直接受到 Logto 的影响。 为了为用户提供便利，Logto 提供了一系列常用的开发者功能。 @@ -39,16 +39,25 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '用户模拟 (User impersonation)', href: '/developers/user-impersonation', - description: '允许有权限的用户临时以终端用户身份操作，适用于故障排查、客户支持和管理任务。', + description: '允许授权 (Authorization) 用户临时以终端用户身份操作，适用于故障排查、客户支持和管理任务。', customProps: { icon: , } }, + { + type: 'link', + label: '服务到服务委托', + href: '/developers/service-to-service-delegation', + description: '将用户访问令牌 (Access token) 换取下游 API 访问令牌 (Access token)，使后端服务能够代表当前用户操作。', + customProps: { + icon: , + } + }, ]} /> ``` -## 通用开发者功能 \{#generics-for-developers} +## 开发者通用功能 \{#generics-for-developers} ```mdx-code-block , } diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index 81317df69ab..8c512b74b17 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # 审计日志 @@ -8,10 +8,10 @@ Logto 的审计日志让你可以轻松监控用户活动和事件。它为各 ## 查看所有日志 \{#view-all-logs} -前往 控制台 > 审计日志。Logto 会捕获并将认证 (Authentication) 事件整理成表格，记录事件名称、用户、应用程序和时间戳。你可以通过事件名称和应用程序名称进行筛选，缩小结果范围。点击某个具体事件可以查看更多详细信息。 +前往 控制台 > 审计日志。Logto 会捕获并将认证 (Authentication) 事件整理成表格。它会记录事件名称、用户、应用程序和时间戳。你可以通过事件名称和应用程序名称进行筛选，以缩小结果范围。点击某个具体事件可以查看更多详细信息。 :::warning -审计日志仅包含用户认证 (Authentication) 过程中的日志，不记录 Management API 操作的日志。 +审计日志仅包含用户认证 (Authentication) 过程中的日志，不会记录 Management API 操作的日志。 ::: ## 在租户级别捕获用户活动 \{#capture-user-activity-at-the-tenant-level} @@ -51,6 +51,6 @@ Logto 的日志提供了全面的细节，确保操作便捷和客户安全。 -OSS 用户应定期添加定时任务清理过期的审计日志。 +OSS 用户应定期添加 cronjob 清理过期的审计日志。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index e74da756070..457d99a2d41 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,7 +2,7 @@ id: sdk-conventions title: 平台 SDK 约定 sidebar_label: 平台 SDK 约定 -sidebar_position: 8 +sidebar_position: 9 --- # 平台 SDK 约定 @@ -13,7 +13,7 @@ Logto 提供了非常强大且灵活的 Web 认证 (Authentication) 服务。 你可以在 [这里](/quick-starts) 找到 Logto 支持的所有编程语言 / 框架的 SDK。 -如果你不幸没有找到你想要的 SDK，这里有一套约定，你可以按照它为你想要的编程语言实现 SDK，从而更方便地使用 Logto 服务。 +如果你不幸没有找到你想要的 SDK，这里有一份约定，你可以按照它为你想要的编程语言实现 SDK，从而更方便地使用 Logto 服务。 本约定包含三个主要部分： @@ -25,6 +25,8 @@ Logto 提供了非常强大且灵活的 Web 认证 (Authentication) 服务。 实现一个简单的客户端 OIDC SDK -几分钟打造基于 Node.js 的 Logto 框架 SDK + + 几分钟内为 Logto 打造基于 Node.js 的框架 SDK + -几分钟打造 Logto Web SDK +几分钟内为 Logto 打造 Web SDK diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..5f4f494e486 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: 服务到服务委托 +sidebar_label: 服务到服务委托 +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# 服务到服务委托 + +在某些 API 架构中，后端服务会收到来自已登录用户的请求，并需要在保留用户身份的情况下调用另一个后端服务。 + +例如： + +```text +用户 -> API A -> API B +``` + +API B 需要知道两件事： + +1. 调用方是受信任的服务，例如 API A。 +2. 操作是为原始用户执行的。 + +使用 Logto 的令牌交换授权 (token exchange grant)，可以将用户的访问令牌 (access token) 交换为以下游 API 资源为受众 (audience) 的新访问令牌 (access token)。这遵循 OAuth 2.0 令牌交换模式，并避免将原始用户令牌转发到下游服务。 + +## 何时使用此流程 \{#when-to-use-this-flow} + +在以下情况下使用服务到服务委托： + +- API A 是一个可以安全地向 Logto 令牌端点进行认证 (Authentication) 的后端服务。 +- API A 收到 Logto 签发的用户访问令牌 (access token)。 +- API A 需要以同一用户的身份调用 API B。 +- API B 应该验证一个以自身 API 资源为受众 (audience) 的访问令牌 (access token)。 + +不要将此流程用于纯机器对机器 (machine-to-machine) 的无用户访问。在这种情况下，请使用 [客户端凭证流程](/quick-starts/m2m)。对于支持、管理员或代理场景，即一个用户临时以另一个用户身份操作，请使用 [用户模拟 (User impersonation)](/developers/user-impersonation)。 + +## 工作原理 \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as 用户 + participant ApiA as API A + participant Logto as Logto 令牌端点 + participant ApiB as API B + + User->>ApiA: Authorization: Bearer 用户访问令牌 (access token) + Note over ApiA: 验证 API A 的用户令牌 + + ApiA->>Logto: POST /oidc/token，使用令牌交换授权 (token exchange grant) + Note over ApiA,Logto: subject_token = 用户的访问令牌 (access token)
resource = API B 资源指示器 (resource indicator) + + Logto-->>ApiA: API B 的访问令牌 (access token) + ApiA->>ApiB: Authorization: Bearer 交换后的访问令牌 (access token) + Note over ApiB: 验证发行者 (Issuer)、受众 (Audience)、过期时间和权限 (Scopes) +``` + +交换后的访问令牌 (access token) 代表原始用户（`sub`），并绑定到下游 API 资源（`aud`）。下游 API 还可以检查 `client_id` 声明 (Claim) 以识别发起交换的应用程序。 + +## 前置条件 \{#prerequisites} + +1. 为涉及的服务创建 API 资源。参见 [保护全局 API 资源](/authorization/global-api-resources)。 +2. 配置 API B 的权限 (Permissions)，并通过角色 (Roles) 或组织角色分配给用户。 +3. 对于 API A，使用服务器端应用程序，如机器对机器 (machine-to-machine) 应用或传统 Web 应用，以便可以通过应用密钥安全认证 (Authentication)。 +4. 为 API A 的应用启用令牌交换。 + + + +## 为下游 API 请求访问令牌 (Access token) \{#request-an-access-token-for-the-downstream-api} + +当 API A 需要调用 API B 时，向 Logto 的 [令牌端点](/integrate-logto/application-data-structure#token-endpoint) 发起令牌交换请求。 + +对于带有应用密钥的传统 Web 应用或机器对机器 (machine-to-machine) 应用，在 `Authorization` 头中包含凭证： + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +参数说明： + +1. `grant_type`：使用 `urn:ietf:params:oauth:grant-type:token-exchange`。 +2. `subject_token`：API A 收到的原始 Logto 用户访问令牌 (access token)。 +3. `subject_token_type`：使用 `urn:ietf:params:oauth:token-type:access_token`。 +4. `resource`：API B 的 API 资源指示器 (resource indicator)。 +5. `scope`：API A 为本次委托调用请求的下游权限 (Scopes)。Logto 仅会根据 RBAC 设置，为原始用户在该资源上可用的权限 (Scopes) 签发请求的权限 (Scopes)。 + +Logto 返回 API B 的访问令牌 (access token)： + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +解码后，访问令牌 (access token) 包含类似如下的声明 (Claims)： + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +然后 API A 使用交换后的令牌调用 API B： + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## 在 API B 中验证令牌 \{#validate-the-token-in-api-b} + +API B 应像验证任何 Logto 签发的 API 资源访问令牌 (access token) 一样验证交换后的令牌： + +1. 使用 Logto 的 JWKs 验证签名。 +2. 检查发行者 (Issuer)（`iss`）。 +3. 检查受众 (Audience)（`aud`）是否与 API B 的资源指示器 (resource indicator) 匹配。 +4. 检查过期时间（`exp`）。 +5. 检查所需的权限 (Scopes)。 +6. 使用 `sub` 作为原始用户 ID。 +7. 如只允许特定上游服务进行委托调用，可选检查 `client_id`。 + +实现指导参见 [在 API 中验证访问令牌 (Access tokens)](/authorization/validate-access-tokens)。 + +## 相关资源 \{#related-resources} + +保护全局 API 资源 + +在 API 中验证访问令牌 (Access tokens) + +用户模拟 (User impersonation) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index fa04fdae0e0..7aeb8322599 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,14 +2,14 @@ id: signing-keys title: 签名密钥 sidebar_label: 签名密钥 -sidebar_position: 5 +sidebar_position: 6 --- # 签名密钥 Logto [OIDC 签名密钥](https://auth.wiki/signing-key)，也被称为 “OIDC 私钥” 和 “OIDC Cookie 密钥”，是用于在 Logto [登录会话](/sessions#what-is-a-logto-session) 中对 JWT（[访问令牌 (Access token)](https://auth.wiki/access-token) 和 [ID 令牌 (ID token)](https://auth.wiki/id-token)）以及浏览器 Cookie 进行签名的密钥。这些签名密钥会在初始化 Logto 数据库（[开源版](/logto-oss)）或创建新租户（[云端](/logto-cloud)）时生成，并可通过 [CLI](/logto-oss/using-cli)（开源版）、Management API 或控制台界面进行管理。 -默认情况下，Logto 使用椭圆曲线（EC）算法生成数字签名。但考虑到用户经常需要验证 JWT 签名，而许多旧工具并不支持 EC 算法（只支持 RSA），我们实现了私钥轮换功能，并允许用户选择签名算法（包括 RSA 和 EC）。这样可以确保与使用过时签名验证工具的服务兼容。 +默认情况下，Logto 使用椭圆曲线（EC）算法生成数字签名。然而，考虑到用户经常需要验证 JWT 签名，并且许多旧工具不支持 EC 算法（只支持 RSA），我们实现了私钥轮换功能，并允许用户选择签名算法（包括 RSA 和 EC）。这确保了与使用过时签名验证工具的服务的兼容性。 :::note 理论上，签名密钥不应泄露且没有过期时间，因此无需轮换。但定期在一段时间后轮换签名密钥可以提升安全性。 @@ -18,7 +18,7 @@ Logto [OIDC 签名密钥](https://auth.wiki/signing-key)，也被称为 “OIDC ## 工作原理 \{#how-it-works} - **OIDC 私钥** - 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并注册到底层 OIDC 提供方。因此，当 Logto 颁发新的 JWT（访问令牌 (Access token) 或 ID 令牌 (ID token)）时，令牌会用私钥进行签名。同时，任何收到 JWT 的客户端应用都可以使用配对的公钥验证令牌签名，以确保令牌未被第三方篡改。私钥在 Logto 服务器上受到保护。而公钥，顾名思义，是公开的，任何人都可以通过 OIDC 端点的 `/oidc/jwks` 接口访问。在生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过轮换私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。 + 在初始化 Logto 实例时，会自动生成一对公钥和私钥，并注册到底层 OIDC 提供方。因此，当 Logto 颁发新的 JWT（访问令牌 (Access token) 或 ID 令牌 (ID token)）时，令牌会用私钥进行签名。同时，任何接收到 JWT 的客户端应用都可以使用配对的公钥来验证令牌签名，以确保令牌未被第三方篡改。私钥在 Logto 服务器上受到保护。而公钥，顾名思义，是公开的，任何人都可以通过 OIDC 端点的 `/oidc/jwks` 接口获取。生成私钥时可以指定签名密钥算法，Logto 默认使用 EC（椭圆曲线）算法。管理员用户可以通过轮换私钥将默认算法更改为 RSA（Rivest-Shamir-Adleman）。 - **OIDC Cookie 密钥** 当用户发起登录或注册流程时，服务器上会创建一个 “OIDC 会话”，以及一组浏览器 Cookie。借助这些 Cookie，浏览器可以代表用户请求 Logto Experience API 执行一系列交互操作，如登录、注册和重置密码。但与 JWT 不同，Cookie 只由 Logto OIDC 服务自身签名和验证，不需要非对称加密措施。因此，Cookie 签名密钥没有配对的公钥，也不使用非对称加密算法。 @@ -26,30 +26,30 @@ Logto [OIDC 签名密钥](https://auth.wiki/signing-key)，也被称为 “OIDC Logto 引入了 “签名密钥轮换” 功能，允许你在租户中创建新的 OIDC 私钥和 Cookie 密钥。 -1. 前往 控制台 > 租户设置 > OIDC 配置。在这里，你可以管理 OIDC 私钥和 OIDC Cookie 密钥。 -2. 要轮换签名密钥，点击 “轮换私钥” 或 “轮换 Cookie 密钥” 按钮。轮换私钥时，你可以选择更改签名算法。 +1. 前往 控制台 > 租户设置 > OIDC 配置。在那里，你可以管理 OIDC 私钥和 OIDC Cookie 密钥。 +2. 若要轮换签名密钥，点击 “轮换私钥” 或 “轮换 Cookie 密钥” 按钮。轮换私钥时，你可以选择更改签名算法。 3. 你会看到一个表格，列出了所有正在使用的签名密钥。对于 OIDC 私钥，你可以删除上一个密钥，但不能删除当前或下一个密钥。对于 OIDC Cookie 密钥，你可以删除上一个密钥，但不能删除当前密钥。 - | 状态 | 说明 | - | ------ | ----------------------------------------------------------------------------------------------------- | - | 下一个 | 用于分阶段 OIDC 私钥轮换的状态。密钥已创建，但 Logto 不会用它签发新的 JWT，直到宽限期结束且密钥生效。 | - | 当前 | 表示 Logto 当前用于签发新 JWT 或 Cookie 的密钥。 | - | 上一个 | 指之前使用过但已被轮换的密钥。用该密钥签名的现有 JWT 或 Cookie 在过期或密钥被删除前仍然有效。 | + | 状态 | 描述 | + | ------ | ------------------------------------------------------------------------------------------------------- | + | 下一个 | 此状态用于分阶段的 OIDC 私钥轮换。密钥已创建，但 Logto 不会用它签名新的 JWT，直到宽限期结束且密钥生效。 | + | 当前 | 表示此密钥当前被 Logto 用于签名新颁发的 JWT 或 Cookie。 | + | 上一个 | 指之前使用过但已被轮换的密钥。用该密钥签名的现有 JWT 或 Cookie 在过期或密钥被删除前仍然有效。 | 请记住，轮换涉及以下三个操作： -1. **创建新签名密钥**：对于 OIDC 私钥，Logto 可以先将新密钥分阶段为 “下一个”，这样你的应用和 API 就有时间从 `/oidc/jwks` 端点刷新公钥，然后再用新密钥进行签名。 -2. **轮换当前密钥**：当轮换生效时，“下一个”密钥变为 “当前”，原有 “当前” 密钥变为 “上一个”。用上一个密钥签名的令牌仍然有效。 -3. **移除最旧的上一个密钥**：Logto 最多只保留一个 “上一个” 私钥。如果在分阶段密钥变为当前时已存在上一个私钥，则会移除更早的上一个密钥。 +1. **创建新签名密钥**：对于 OIDC 私钥，Logto 可以先将新密钥标记为 “下一个”，这样你的应用和 API 就有时间从 `/oidc/jwks` 端点刷新公钥，然后再用新密钥进行签名。 +2. **轮换当前密钥**：当轮换生效时，“下一个”密钥变为“当前”，原有“当前”密钥变为“上一个”。用上一个密钥签名的令牌仍然有效。 +3. **移除最旧的上一个密钥**：Logto 最多只保留一个“上一个”私钥。如果在新密钥生效时已存在上一个私钥，则更早的上一个密钥会被移除。 -对于 Logto Cloud，OIDC 私钥轮换在 4 小时宽限期后生效。在此期间，新密钥已准备好并通过 JWKS 暴露，Logto 会在宽限期结束后才用它签发新的 JWT。在控制台表格中，**生效时间** 列显示分阶段 “下一个” 密钥变为 “当前” 的时间。 +对于 Logto Cloud，OIDC 私钥轮换在 4 小时宽限期后生效。在此期间，新密钥已准备好并通过 JWKS 暴露，Logto 会在宽限期结束后才用它签名新颁发的 JWT。在控制台表格中，**生效时间** 列显示分阶段 “下一个” 密钥何时会变为 “当前”。 -对于自托管开源部署，默认私钥轮换宽限期为 `0` 秒，即轮换立即生效。要使用分阶段轮换，请在 Logto 服务上设置 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 环境变量，或在调用 Management API 端点 `POST /api/configs/oidc/private-keys/rotate` 时在请求体中传递显式的 `rotationGracePeriod` 值。 +对于自托管的开源部署，默认私钥轮换宽限期为 `0` 秒，即轮换立即生效。若需分阶段轮换，请在 Logto 服务上设置 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 环境变量，或在调用 Management API 端点 `POST /api/configs/oidc/private-keys/rotate` 时在请求体中传递显式的 `rotationGracePeriod` 值。 :::warning -在待轮换生效前，避免反复轮换签名密钥，除非你有意替换分阶段的 “下一个” 密钥。 +在待轮换密钥尚未生效前，避免反复轮换签名密钥，除非你有意替换分阶段的 “下一个” 密钥。 -过早删除唯一的 “上一个” 密钥，可能会导致用该密钥签名的现有 JWT 或 Cookie 失效。 +过早删除唯一的 “上一个” 密钥，可能导致用该密钥签名的现有 JWT 或 Cookie 失效。 ::: ## 相关资源 \{#related-resources} diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 57f7b170a86..ba35258f10a 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,35 +1,35 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhook Logto [Webhook](https://auth.wiki/webhook) 为各种事件提供实时通知，包括用户账户、角色、权限、组织 (Organizations)、组织角色、组织权限以及 [用户交互](/end-user-flows) 的变更。 -当事件被触发时，Logto 会向你提供的 Endpoint URL 发送 HTTP 请求，其中包含有关事件的详细信息，如用户 ID、用户名、邮箱以及其他相关细节（关于 payload 和 header 中包含的数据，详见 [Webhook 请求](/developers/webhooks/webhooks-request)）。你的应用可以处理该请求并执行自定义操作，比如发送邮件或更新数据库中的数据。 +当事件被触发时，Logto 会向你提供的 Endpoint URL 发送 HTTP 请求，其中包含有关事件的详细信息，如用户 ID、用户名、邮箱及其他相关细节（有关 payload 和 header 中包含的数据详情，请参阅 [Webhook 请求](/developers/webhooks/webhooks-request)）。你的应用可以处理此请求并执行自定义操作，比如发送邮件或更新数据库中的数据。 我们会根据用户需求持续增加更多事件。如果你有特定的业务需求，请告知我们。 -## 为什么要使用 Webhook？ \{#why-use-webhook} +## 为什么要使用 Webhook？\{#why-use-webhook} Webhook 在应用之间提供实时通信，无需轮询，能够实现即时数据更新。它们简化了应用集成和工作流自动化，无需复杂代码或专有 API。 以下是 CIAM 常见 Webhook 用例示例： -- **发送邮件：** 配置 Webhook，在新用户注册时发送欢迎邮件，或在用户从新设备或新地点登录时通知管理员。 -- **发送通知：** 配置 Webhook，当用户注册时，触发与你的 CRM 系统集成的虚拟助手，提供实时客户支持。 +- **发送邮件：** 配置 Webhook，在新用户注册时发送欢迎邮件，或在用户从新设备或位置登录时通知管理员。 +- **发送通知：** 配置 Webhook，当用户注册时，触发你的 CRM 系统中的虚拟助手，提供实时客户支持。 - **执行额外 API 调用：** 配置 Webhook，通过检查用户邮箱域名或 IP 地址来验证用户访问权限，然后使用 Logto Management API 分配带有资源权限的合适角色。 - **数据同步：** 配置 Webhook，确保应用及时获知如用户账户被暂停或删除等变更。 - **生成报告：** 设置 Webhook 接收用户登录活动数据，并利用这些数据生成用户参与度或使用模式报告。 ## 术语 \{#terms} -| Item | Description | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Event | 当执行特定操作时，会触发具有特定类型的 hook 事件。例如，当用户完成注册流程并创建新账户时，Logto 会发出 PostRegister hook 事件。 | -| Hook | 挂载到特定事件上的一个或一系列操作。操作可以是调用 API、执行代码片段等。 | -| Webhook | hook 的一种子类型，表示用事件 payload 调用 API。 | -| 假如开发者希望在用户通过新设备登录时发送通知，可以为 PostSignIn 事件添加一个调用其安全服务 API 的 webhook。 | +| Item | Description | +| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| Event | 当执行特定操作时，会触发带有特定类型的 hook 事件。例如，用户完成注册流程并创建新账户后，Logto 会发出 PostRegister hook 事件。 | +| Hook | 挂载到特定事件上的一个或一系列操作。操作可以是调用 API、执行代码片段等。 | +| Webhook | hook 的一种子类型，表示用事件 payload 调用 API。 | +| 假如开发者希望在用户通过新设备登录时发送通知，可以为 PostSignIn 事件添加一个 webhook，调用其安全服务 API。 | 以下是在 Logto 中为 `PostSignIn` 事件启用两个 web hook 的示例： @@ -63,47 +63,47 @@ graph LR
-### Logto 支持同步 webhook 吗？ \{#does-logto-support-synced-webhooks} +### Logto 支持同步 webhook 吗？\{#does-logto-support-synced-webhooks} -虽然同步 webhook 能让用户登录流程更顺畅，但我们目前还不支持（未来会支持）。因此，目前依赖同步 webhook 的场景都需要不同的变通方案。如果你有任何疑问，欢迎随时联系我们。 +虽然同步 webhook 能让用户登录流程更加流畅，但我们目前还不支持（未来会支持）。因此，目前依赖同步 webhook 的场景都需要不同的变通方案。如果你有任何疑问，欢迎随时联系我们。
-### 如何处理用户权限变更？ \{#how-to-deal-with-user-permission-change} +### 如何处理用户权限变更？\{#how-to-deal-with-user-permission-change} -参见 [管理用户权限变更](/authorization/global-api-resources/#optional-handle-user-permission-change) 指南。 +请参阅 [管理用户权限变更](/authorization/global-api-resources/#optional-handle-user-permission-change) 指南。
-### 如何调试 webhook 超时？ \{#how-to-debug-webhook-timeout} +### 如何调试 webhook 超时？\{#how-to-debug-webhook-timeout} -对于接收 Webhook 的 endpoint，应尽快返回 2xx 响应，告知 Logto Webhook 已被成功接收。由于不同用户对 Webhook 的处理逻辑差异很大，过于复杂的任务可能需要几秒钟，导致 Logto Webhook 超时。最佳实践是维护你自己的事件队列；收到 Logto Webhook 后，将事件插入队列，并立即返回 2xx 响应给 Logto。然后让你自己的 worker 按顺序处理队列中的任务。如果 worker 遇到错误，请在你自己的服务器上处理。 +对于接收 Webhook 的 endpoint，应尽快返回 2xx 响应，告知 Logto Webhook 已成功接收。由于不同用户对 Webhook 的处理逻辑差异很大，过于复杂的任务可能需要几秒钟，导致 Logto Webhook 超时。最佳实践是维护你自己的事件队列；收到 Logto Webhook 后，将事件插入队列，并立即返回 2xx 响应给 Logto。然后让你自己的 worker 逐步处理队列中的任务。如果 worker 遇到错误，请在你自己的服务器上处理。
-### 我可以从 `PostSignIn` webhook 获取客户端 IP 地址吗？ \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} +### 我可以从 `PostSignIn` webhook 获取客户端 IP 地址吗？\{#can-i-get-the-client-ip-address-from-postsignin-webhooks} -可以，你可以在 Webhook payload 中获取 IP 地址、user agent 等信息。如果你需要目前未支持的信息，可以在 GitHub issue 提交功能需求，或联系我们。 +可以，你可以在 Webhook payload 中获取 IP 地址、user agent 等信息。如果你需要目前未支持的信息，可以在 GitHub issues 上创建功能请求，或联系我们。
## 相关资源 \{#related-resources} -Webhooks 与轮询 +Webhooks 与轮询对比 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index cadab678f3c..bce06d1ef18 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -1,15 +1,15 @@ --- id: webhooks-events -title: Webhook 事件 -sidebar_label: Webhook 事件 +title: Webhooks 事件 +sidebar_label: Webhooks 事件 sidebar_position: 3 --- # Webhooks 事件 -本指南列出了不同的 Logto webhook 事件，并解释了每个事件发生的时间。 +本指南列出了不同的 Logto Webhook 事件，并解释了每个事件发生的时机。 -## 用户交互钩子事件 \{#user-interaction-hook-events} +## 用户交互 Hook 事件 \{#user-interaction-hook-events} | 事件类型 | 描述 | | ----------------- | ------------------------------------ | @@ -17,63 +17,63 @@ sidebar_position: 3 | PostSignIn | 用户通过 UI 界面成功登录。 | | PostResetPassword | 用户通过“忘记密码”流程成功重置密码。 | -## 数据变更钩子事件 \{#data-mutation-hook-events} +## 数据变更 Hook 事件 \{#data-mutation-hook-events} ### 用户 \{#user} -| 事件类型 | 描述 | -| ----------------------------- | --------------------------------------------------------------------- | -| User.Created | 创建了一个新的用户账户。 | -| User.Deleted | 删除了一个用户账户。 | -| User.Data.Updated | 用户资料数据被更新，例如，电子邮件、头像、custom.data、社交标识符等。 | -| User.SuspensionStatus.Updated | 用户的暂停状态被更改（暂停或重新激活）。 | +| 事件类型 | 描述 | +| ----------------------------- | ------------------------------------------------------------- | +| User.Created | 创建了新用户账户。 | +| User.Deleted | 删除了用户账户。 | +| User.Data.Updated | 用户资料数据被更新，例如邮箱、头像、custom.data、社交标识等。 | +| User.SuspensionStatus.Updated | 用户的封禁状态发生变化（被封禁或重新激活）。 | -### 角色 \{#role} +### 角色 (Role) \{#role} -| 事件类型 | 描述 | -| ------------------- | ------------------------------------------------------ | -| Role.Created | 创建了一个新的角色。 | -| Role.Deleted | 删除了一个角色。 | -| Role.Data.Updated | 角色的数据被更新，例如，角色名称、描述和默认角色状态。 | -| Role.Scopes.Updated | 分配给角色的权限被添加或移除。 | +| 事件类型 | 描述 | +| ------------------- | -------------------------------------------------- | +| Role.Created | 创建了新角色。 | +| Role.Deleted | 删除了角色。 | +| Role.Data.Updated | 角色数据被更新，例如角色名称、描述和默认角色状态。 | +| Role.Scopes.Updated | 分配给角色的权限被添加或移除。 | ### 权限 (Scope) \{#permission-scope} -| 事件类型 | 描述 | -| ------------------ | -------------------------------------- | -| Scope.Created | 创建了一个新的 API 权限。 | -| Scope.Deleted | 删除了一个 API 权限。 | -| Scope.Data.Updated | API 权限的数据被更新，例如，权限描述。 | +| 事件类型 | 描述 | +| ------------------ | ---------------------------------- | +| Scope.Created | 创建了新的 API 权限。 | +| Scope.Deleted | 删除了 API 权限。 | +| Scope.Data.Updated | API 权限数据被更新，例如权限描述。 | ### 组织 (Organization) \{#organization} -| 事件类型 | 描述 | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | 创建了一个新的组织。 | -| Organization.Deleted | 删除了一个组织。 | -| Organization.Data.Updated | 组织的数据被更新，例如，组织名称、描述、custom.data 等。 | -| Organization.Membership.Updated | 用户或应用程序被添加到或从组织中移除。负载包括 [membership delta fields](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)。 | +| 事件类型 | 描述 | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | 创建了新组织。 | +| Organization.Deleted | 删除了组织。 | +| Organization.Data.Updated | 组织数据被更新，例如组织名称、描述、custom.data 等。 | +| Organization.Membership.Updated | 用户或应用被添加到组织或从组织移除。Payload 包含 [成员变更字段](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)。 | -### 组织角色 \{#organization-role} +### 组织角色 (Organization role) \{#organization-role} -| 事件类型 | 描述 | -| ------------------------------- | ------------------------------------------------ | -| OrganizationRole.Created | 创建了一个新的组织角色。 | -| OrganizationRole.Deleted | 删除了一个组织角色。 | -| OrganizationRole.Data.Updated | 组织角色的数据被更新，例如，组织角色名称和描述。 | -| OrganizationRole.Scopes.Updated | 分配给组织角色的权限被添加或移除。 | +| 事件类型 | 描述 | +| ------------------------------- | -------------------------------------------- | +| OrganizationRole.Created | 创建了新的组织角色。 | +| OrganizationRole.Deleted | 删除了组织角色。 | +| OrganizationRole.Data.Updated | 组织角色数据被更新，例如组织角色名称和描述。 | +| OrganizationRole.Scopes.Updated | 分配给组织角色的权限被添加或移除。 | -### 组织权限 (Scope) \{#organization-permission-scope} +### 组织权限 (Organization permission / scope) \{#organization-permission-scope} -| 事件类型 | 描述 | -| ------------------------------ | ------------------------------------------ | -| OrganizationScope.Created | 创建了一个新的组织权限。 | -| OrganizationScope.Deleted | 删除了一个组织权限。 | -| OrganizationScope.Data.Updated | 组织权限的数据被更新，例如，组织权限描述。 | +| 事件类型 | 描述 | +| ------------------------------ | -------------------------------------- | +| OrganizationScope.Created | 创建了新的组织权限。 | +| OrganizationScope.Deleted | 删除了组织权限。 | +| OrganizationScope.Data.Updated | 组织权限数据被更新，例如组织权限描述。 | ### Management API 触发的事件 \{#management-api-triggered-events} -| API 端点 | 事件 | +| API endpoint | 事件 | | ---------------------------------------------------------- | ----------------------------------------------------------- | | POST /users | User.Created | | DELETE /users/:userId | User.Deleted | @@ -112,32 +112,33 @@ sidebar_position: 3 ### Experience API 触发的事件 \{#experience-api-triggered-events} -| 用户交互操作 | 事件 | -| ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| 用户电子邮件/电话关联 | User.Data.Updated | -| 用户 MFA 关联 | User.Data.Updated | -| 用户社交/SSO 关联 | User.Data.Updated | -| 用户密码重置 | User.Data.Updated | -| 用户注册 | User.Created | -| 用户通过 [即时供应](/organizations/just-in-time-provisioning)（匹配电子邮件域或企业 SSO 连接器）自动供应到组织中 | Organization.Membership.Updated | +| 用户交互操作 | 事件 | +| ------------------------------------------------------------------------------------------------------------ | ------------------------------- | +| 用户邮箱 / 手机号绑定 | User.Data.Updated | +| 用户 MFA 绑定 | User.Data.Updated | +| 用户社交 / SSO 绑定 | User.Data.Updated | +| 用户密码重置 | User.Data.Updated | +| 用户注册 | User.Created | +| 用户通过 [即时供应](/organizations/just-in-time-provisioning)（匹配邮箱域名或企业 SSO 连接器）被自动加入组织 | Organization.Membership.Updated | -## 异常钩子事件 \{#exception-hook-events} +## 异常 Hook 事件 \{#exception-hook-events} ### 安全 \{#security} -| 事件类型 | 描述 | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| Identifier.Lockout | 由于连续身份验证失败，用户账户被锁定。可以在以下流程中触发：
  • 密码验证失败
  • 代码验证失败
  • 一次性令牌验证失败
| +| 事件类型 | 描述 | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Identifier.Lockout | 由于连续身份验证失败，用户账户被锁定。可在以下流程中触发：
  • 密码验证失败
  • 验证码验证失败
  • 一次性令牌验证失败
| +| Message.RateLimited | 终端用户超过了每个收件人的[发送速率限制](/security/send-rate-limit)（用于验证码）。仅在终端用户发送路径（Experience API 和 Account API）触发，payload 为 `{ action, recipient }`。 | ## 常见问题 \{#faqs}
-### `PostRegister` 和 `User.Created` 之间有什么区别？ \{#whats-the-difference-between-postregister-and-usercreated} +### `PostRegister` 和 `User.Created` 有什么区别？\{#whats-the-difference-between-postregister-and-usercreated} -`PostRegister` 在用户通过用户注册流程成功创建新账户时触发；`User.Created` 在通过 Management API 创建新用户账户时触发。 +`PostRegister` 在用户通过注册流程成功创建新账户时触发；`User.Created` 在通过 Management API 创建新用户账户时触发。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/README.mdx index 8cd5f563855..93039b39a25 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/README.mdx @@ -10,9 +10,9 @@ import SuspendIcon from '@site/src/assets/suspend.svg'; # 安全 -现代认证 (Authentication) 安全需要应对从网络钓鱼、凭证填充、暴力破解、勒索软件、DDoS 到 AI 驱动攻击等各种威胁。保护用户身份对于维护品牌信任和合规至关重要。 +现代认证 (Authentication) 安全需要应对各种威胁，包括网络钓鱼、凭证填充、暴力破解、勒索软件、DDoS 以及 AI 驱动的攻击。保护用户身份对于维护品牌信任和合规至关重要。 -Logto 提供强大的安全访问管理，专为正面应对这些风险而设计。通过优先考虑主动威胁防御和弹性，我们确保你的系统在不影响易用性的前提下始终受到保护。在 Logto，安全不是事后的考虑——而是基础，让企业在威胁不断演变的时代中蓬勃发展，因为防御进化得更快。 +Logto 提供强大的安全访问管理，专为正面应对这些风险而设计。通过优先考虑主动威胁防护和系统韧性，我们确保你的系统在不影响易用性的前提下始终受到保护。在 Logto，安全不是事后考虑——而是基础，助力企业在威胁不断演变的时代中蓬勃发展，让防御始终快人一步。 ## 设置高级安全防护 \{#set-up-advanced-security-protection} @@ -32,7 +32,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 label: 'CAPTCHA', href: '/security/captcha', description: - '在你的登录体验中添加 CAPTCHA（如 Google reCAPTCHA、Cloudflare Turnstile），以防止自动化机器人攻击。', + '为你的登录体验添加 CAPTCHA（如 Google reCAPTCHA、Cloudflare Turnstile），防止自动化机器人攻击。', customProps: { icon: , }, @@ -41,7 +41,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 type: 'link', label: '黑名单', href: '/security/blocklist', - description: '通过屏蔽一次性或不需要的邮箱域名或地址，掌控你的用户群。', + description: '通过屏蔽一次性或不需要的邮箱域名或地址，掌控你的用户基础。', customProps: { icon: , }, @@ -50,16 +50,25 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 type: 'link', label: '标识符锁定', href: '/security/identifier-lockout', - description: '在多次认证 (Authentication) 失败后临时锁定标识符，以防止暴力破解访问。', + description: '在多次认证 (Authentication) 失败后临时锁定标识符，防止暴力破解访问。', customProps: { icon: , }, }, + { + type: 'link', + label: '发送速率限制', + href: '/security/send-rate-limit', + description: '限制每个收件人的验证码和消息发送次数，防止收件箱垃圾邮件和短信轰炸滥用。', + customProps: { + icon: , + }, + }, { type: 'link', label: '隐藏账户存在性', href: '/end-user-flows/sign-up-and-sign-in', - description: '隐藏账户状态，以阻止账户枚举攻击并避免泄露敏感账户状态信息。', + description: '隐藏账户状态，阻止账户枚举攻击，避免泄露敏感账户状态信息。', customProps: { icon: , }, @@ -67,7 +76,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 ]} /> -## 发现更多保护你的应用的方法 \{#discover-more-ways-to-protect-your-apps} +## 发现更多保护应用的方式 \{#discover-more-ways-to-protect-your-apps} , }, @@ -84,7 +94,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 type: 'link', label: '升级认证 (Authentication)', href: '/end-user-flows/security-verification', - description: '允许应用在用户访问敏感信息或执行高风险操作时，提示升级认证 (Authentication)。', + description: '允许应用在用户访问敏感信息或执行高风险操作时，触发升级认证 (Authentication)。', customProps: { icon: , }, @@ -93,7 +103,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 type: 'link', label: '暂停用户', href: '/user-management/manage-users#suspend-user', - description: '临时禁用用户账户，在不删除数据或用户记录的情况下阻止访问。', + description: '临时禁用用户账户，阻止访问但不删除数据或用户记录。', customProps: { icon: , }, @@ -102,7 +112,7 @@ Logto 提供强大的安全访问管理，专为正面应对这些风险而设 type: 'link', label: '轮换签名密钥', href: '/developers/signing-keys', - description: '定期轮换签名密钥，以防止密钥泄露和令牌伪造。', + description: '定期轮换签名密钥，防止密钥泄露和令牌伪造。', customProps: { icon: , }, diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..2724b40cc17 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: 发送速率限制 +sidebar_position: 5 +--- + +# 发送速率限制 + +Logto 对通过电子邮件和短信发送的外发验证码及其他消息，针对每个收件人应用了内置的速率限制。它可以保护你的用户和消息服务提供商免受滥发行为的影响——例如攻击者向受害者的收件箱或手机大量发送验证码，或通过短信轰炸来增加你的成本。 + +此限制是**强制且系统级别**的：它适用于每个租户，无论套餐如何，且**不可**由租户自行配置。它独立于以下内容： + +- **[标识符锁定](/security/identifier-lockout)** 和 **[验证码](/security/captcha)** 策略，这些策略是在验证时限制*失败的验证尝试*，而不是限制*发送*行为。 +- 全局每租户 API 速率限制（错误码 `request.rate_limited`），该限制约束整个租户的请求总量。 + +## 工作原理 \{#how-it-works} + +- **每收件人上限**：Logto 限制在一个短时间滚动窗口内，向同一收件人（电子邮件地址或手机号）发送消息的次数。默认情况下，**每 10 分钟每个收件人最多允许发送 10 次**。 +- **适用范围**：所有服务端发送路径，包括 Experience API 和 Account API 的验证码发送（登录、注册、重置密码、多因素认证 (MFA) 和标识符绑定）、Management API 验证码发送、组织邀请发送和重发，以及 Account (`/me`) 验证码发送。 +- **超出上限时**：请求将被拒绝，返回 HTTP `429` 和错误码 `request.message_rate_limited`——该错误码与全局租户限制器（`request.rate_limited`）和验证时锁定（`session.verification_blocked_too_many_attempts`）不同，因此你可以在集成中专门处理它。 + +## 使用 Webhook 监控被限速的发送 \{#monitor-rate-limited-sends-with-a-webhook} + +当**终端用户**触发每收件人上限时，Logto 会触发 `Message.RateLimited` [Webhook 事件](/developers/webhooks/webhooks-events#exception-hook-events)，这样你可以对滥发行为进行告警或响应。 + +- **触发对象**：仅限终端用户验证码发送路径——即 Experience API 和 Account API。对于第一方或管理员发起的发送（Management API 验证码、组织邀请或 `/me`），**不会**触发。 +- **负载**：Hook 上下文包含 `action`（例如 `VerificationCodeSend`）和 `recipient`（电子邮件地址或手机号）。 + +**常见用例：** + +- 向你的团队发送安全告警以便审核。 +- 针对受影响的收件人触发下游反滥用自动化。 + +前往 控制台 > Webhook 进行订阅，或通过 Management API 创建 Hook。有关详细的事件结构和配置，请参见 [Webhook](/developers/webhooks)。 + +## 对未知收件人的投递抑制 \{#suppressed-delivery-to-unknown-recipients} + +为防止账户枚举，当通过标识符注册被禁用时，如果为**没有账户拥有**的电子邮件地址或手机号请求登录验证码，系统会静默不投递，API 的响应与真实发送时一致。因此，攻击者无法通过这些响应判断哪些地址已注册。对现有用户的投递不受影响。另见 [隐藏账户存在性](/end-user-flows/sign-up-and-sign-in)。 diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/README.mdx index b5d7d9192da..1ab590147e3 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/README.mdx @@ -4,7 +4,7 @@ Logto 是一個基於 [OAuth 2](https://auth.wiki/oauth-2.0) 和 [OIDC](https:// 為了方便使用者，Logto 提供了一系列常用的開發者功能。 -## 登入體驗相關 \{#sign-in-experience-related} +## 登入體驗相關功能 \{#sign-in-experience-related} ```mdx-code-block import DocCardList from '@theme/DocCardList'; @@ -39,11 +39,20 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '使用者模擬 (User impersonation)', href: '/developers/user-impersonation', - description: '允許授權 (Authorization) 使用者暫時以終端使用者身分操作，適用於疑難排解、客服與管理作業。', + description: '允許授權 (Authorization) 使用者暫時以終端使用者身分操作，適用於疑難排解、客服與管理任務。', customProps: { icon: , } }, + { + type: 'link', + label: '服務對服務委派 (Service-to-service delegation)', + href: '/developers/service-to-service-delegation', + description: '將使用者存取權杖 (Access token) 交換為下游 API 存取權杖 (Access token)，讓後端服務能以當前使用者身分執行操作。', + customProps: { + icon: , + } + }, ]} /> ``` @@ -57,7 +66,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '簽章金鑰 (Signing keys)', href: '/developers/signing-keys', - description: '提供系統層級簽章金鑰，透過密碼保管庫，讓驗證 (Authentication) 服務更加安全。', + description: '提供系統層級簽章金鑰，透過密碼保管庫提升驗證 (Authentication) 服務安全性。', customProps: { icon: , } @@ -75,7 +84,7 @@ import Settings from '@site/docs/developers/assets/icons/gear.svg'; type: 'link', label: '稽核日誌 (Audit logs)', href: '/developers/audit-logs', - description: '記錄使用者驗證 (Authentication) 相關活動，方便除錯與分析使用者行為。', + description: '記錄使用者驗證 (Authentication) 相關活動，便於除錯與分析使用者行為。', customProps: { icon: , } diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx index 6ca82be64f8..5773e66b9d3 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/audit-logs/README.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 8 --- # 稽核日誌 (Audit logs) @@ -16,9 +16,9 @@ Logto 的稽核日誌讓你輕鬆監控使用者活動與事件，為各種使 ## 在租戶層級捕捉使用者活動 \{#capture-user-activity-at-the-tenant-level} -Logto 的日誌提供完整細節，確保操作便利與客戶安全。日誌會捕捉並記錄以下資訊： +Logto 的日誌提供完整細節，確保操作便利與客戶安全。它們會捕捉並記錄以下資訊： -- 事件類型（完整稽核日誌事件列表請參閱[此處](/developers/audit-logs/event-types)） +- 事件類型（完整稽核日誌事件列表請參閱[這裡](/developers/audit-logs/event-types)） - 涉及的應用程式 - IP 位址 - 涉及的使用者 @@ -32,7 +32,7 @@ Logto 的日誌提供完整細節，確保操作便利與客戶安全。日誌 ## 在使用者層級進行詳細分析 \{#perform-a-detailed-analysis-at-the-user-level} -管理員可針對特定使用者相關日誌進行詳細分析，便於對特定事件展開全面調查。導覽流程簡單且易於操作。 +管理員可針對特定使用者相關日誌進行詳細分析，便於對特定事件進行全面調查。導覽流程簡單且易於操作。 存取特定使用者日誌，請依下列步驟操作： diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx index cc5d0f2db2d..eec5870fd2b 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/sdk-conventions/README.mdx @@ -2,18 +2,18 @@ id: sdk-conventions title: 平台 SDK 慣例 (Platform SDK conventions) sidebar_label: 平台 SDK 慣例 (Platform SDK conventions) -sidebar_position: 8 +sidebar_position: 9 --- # 平台 SDK 慣例 (Platform SDK conventions) -Logto 提供功能強大且靈活的網頁驗證 (Authentication) 服務。 +Logto 提供功能強大且彈性的網頁驗證 (Authentication) 服務。 -在實際使用 Logto 服務時，為了方便，開發者通常需要將 Logto SDK 整合到自己的用戶端應用程式中，以管理使用者登入狀態、權限等。 +在實際使用 Logto 服務時，為了方便，開發者通常需要將 Logto SDK 整合進自己的用戶端應用程式，以管理使用者登入狀態、權限等。 你可以在 [這裡](/quick-starts) 找到 Logto 支援的所有程式語言 / 框架的 SDK。 -如果你不幸沒找到想要的 SDK，這裡有一套慣例可供參考，協助你為目標程式語言實作 SDK，讓你更輕鬆使用 Logto 服務。 +如果你不幸沒找到想要的 SDK，這裡有一份慣例可供參考，協助你為目標程式語言實作 SDK，讓你更輕鬆使用 Logto 服務。 本慣例包含三個主要部分： diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx new file mode 100644 index 00000000000..183be796c34 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/service-to-service-delegation.mdx @@ -0,0 +1,149 @@ +--- +id: service-to-service-delegation +title: 服務對服務委派 (Service-to-service delegation) +sidebar_label: 服務對服務委派 (Service-to-service delegation) +sidebar_position: 5 +--- + +import TokenExchangePrerequisites from './fragments/_token-exchange-prerequisites.mdx'; + +# 服務對服務委派 (Service-to-service delegation) + +在某些 API 架構中，後端服務會接收到已登入使用者的請求，並需要在保留使用者身分的情況下呼叫另一個後端服務。 + +例如： + +```text +使用者 (User) -> API A -> API B +``` + +API B 需要知道兩件事： + +1. 呼叫方是受信任的服務，例如 API A。 +2. 這個操作是為原始使用者執行的。 + +使用 Logto 的權杖交換 (token exchange) grant，可以將使用者的存取權杖 (access token) 交換成以下游 API 資源為受眾 (audience) 的新存取權杖。這符合 OAuth 2.0 權杖交換模式，並避免將原始使用者權杖直接轉發給下游服務。 + +## 何時使用此流程 \{#when-to-use-this-flow} + +當符合以下情境時，請使用服務對服務委派： + +- API A 是可以安全驗證至 Logto 權杖端點的後端服務。 +- API A 收到 Logto 發出的使用者存取權杖 (access token)。 +- API A 需要以同一使用者的身分呼叫 API B。 +- API B 應驗證一個以自身 API 資源為受眾 (audience) 的存取權杖 (access token)。 + +不要在純機器對機器（無使用者）存取時使用此流程。此時請改用 [client credentials flow](/quick-starts/m2m)。若為支援、管理員或代理人等場景，需讓一位使用者暫時以另一位使用者身分操作，請參考 [使用者模擬 (User impersonation)](/developers/user-impersonation)。 + +## 運作方式 \{#how-it-works} + +```mermaid +sequenceDiagram + participant User as 使用者 (User) + participant ApiA as API A + participant Logto as Logto 權杖端點 (token endpoint) + participant ApiB as API B + + User->>ApiA: Authorization: Bearer 使用者存取權杖 (user access token) + Note over ApiA: 驗證 API A 的使用者權杖 + + ApiA->>Logto: POST /oidc/token，使用權杖交換 grant + Note over ApiA,Logto: subject_token = 使用者的存取權杖
resource = API B 資源標示符 (resource indicator) + + Logto-->>ApiA: 給 API B 的存取權杖 (access token) + ApiA->>ApiB: Authorization: Bearer 交換後的存取權杖 (exchanged access token) + Note over ApiB: 驗證簽發者 (issuer)、受眾 (audience)、過期時間 (expiration) 與權限範圍 (scopes) +``` + +交換後的存取權杖 (access token) 代表原始使用者（`sub`），並綁定於下游 API 資源（`aud`）。下游 API 也可檢查 `client_id` 宣告 (claim) 以識別發起交換的應用程式。 + +## 先決條件 \{#prerequisites} + +1. 為相關服務建立 API 資源。請參閱 [保護全域 API 資源](/authorization/global-api-resources)。 +2. 設定 API B 的權限，並透過角色或組織角色指派給使用者。 +3. API A 請使用伺服器端應用程式（如機器對機器應用程式或傳統 Web 應用程式），以便能安全地使用應用程式密鑰進行驗證。 +4. 為 API A 的應用程式啟用權杖交換 (token exchange)。 + + + +## 為下游 API 請求存取權杖 \{#request-an-access-token-for-the-downstream-api} + +當 API A 需要呼叫 API B 時，請向 Logto 的 [token endpoint](/integrate-logto/application-data-structure#token-endpoint) 發起權杖交換請求。 + +對於傳統 Web 應用程式或具備應用程式密鑰的機器對機器應用程式，請在 `Authorization` 標頭中帶入憑證： + +```bash +POST /oidc/token HTTP/1.1 +Host: tenant.logto.app +Content-Type: application/x-www-form-urlencoded +# highlight-next-line +Authorization: Basic + +grant_type=urn:ietf:params:oauth:grant-type:token-exchange +&subject_token= +&subject_token_type=urn:ietf:params:oauth:token-type:access_token +&resource=https://api-b.example.com +&scope=read:orders +``` + +參數說明： + +1. `grant_type`：請使用 `urn:ietf:params:oauth:grant-type:token-exchange`。 +2. `subject_token`：API A 收到的原始 Logto 發行的使用者存取權杖 (access token)。 +3. `subject_token_type`：請使用 `urn:ietf:params:oauth:token-type:access_token`。 +4. `resource`：API B 的資源標示符 (resource indicator)。 +5. `scope`：API A 這次委派呼叫所需的下游權限範圍 (scopes)。Logto 僅會根據 RBAC 設定，發行原始使用者對該資源可用的請求權限範圍。 + +Logto 會回傳給 API B 的存取權杖 (access token)： + +```json +{ + "access_token": "eyJhbGci...", + "token_type": "Bearer", + "expires_in": 3600, + "scope": "read:orders" +} +``` + +解碼後的存取權杖內容類似： + +```json +{ + "sub": "user_id", + "client_id": "api_a_app_id", + "iss": "https://tenant.logto.app/oidc", + "aud": "https://api-b.example.com", + "scope": "read:orders", + "exp": 1760000000 +} +``` + +接著，API A 使用交換後的權杖呼叫 API B： + +```bash +GET /orders HTTP/1.1 +Host: api-b.example.com +Authorization: Bearer +``` + +## 在 API B 驗證權杖 \{#validate-the-token-in-api-b} + +API B 應像驗證任何 Logto 發行的 API 資源存取權杖 (access token) 一樣驗證交換後的權杖： + +1. 使用 Logto 的 JWKs 驗證簽章。 +2. 檢查簽發者 (`iss`)。 +3. 檢查受眾 (`aud`) 是否與 API B 的資源標示符相符。 +4. 檢查過期時間 (`exp`)。 +5. 檢查所需權限範圍 (scopes)。 +6. 使用 `sub` 作為原始使用者 ID。 +7. 若僅允許特定上游服務進行委派呼叫，可選擇性檢查 `client_id`。 + +實作指引請參閱 [在 API 中驗證存取權杖](/authorization/validate-access-tokens)。 + +## 相關資源 \{#related-resources} + +保護全域 API 資源 + +在 API 中驗證存取權杖 + +使用者模擬 (User impersonation) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx index c3d5a0189e3..48345898bfb 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/signing-keys.mdx @@ -2,58 +2,58 @@ id: signing-keys title: 簽章金鑰 (Signing keys) sidebar_label: 簽章金鑰 (Signing keys) -sidebar_position: 5 +sidebar_position: 6 --- # 簽章金鑰 (Signing keys) -Logto [OIDC 簽章金鑰](https://auth.wiki/signing-key)（又稱「OIDC 私鑰」與「OIDC Cookie 金鑰」）是用於簽署 JWT（[存取權杖 (Access tokens)](https://auth.wiki/access-token) 與 [ID 權杖 (ID tokens)](https://auth.wiki/id-token)）以及 Logto [登入階段 (Sign-in sessions)](/sessions#what-is-a-logto-session) 中的瀏覽器 Cookie 的簽章金鑰。這些簽章金鑰會在初始化 Logto 資料庫時（[開源版](/logto-oss)）或建立新租戶時（[雲端版](/logto-cloud)）自動產生，並可透過 [CLI](/logto-oss/using-cli)（開源版）、Management API 或 Console UI 進行管理。 +Logto [OIDC 簽章金鑰](https://auth.wiki/signing-key)（又稱「OIDC 私鑰」與「OIDC Cookie 金鑰」）是用於簽署 JWT（[存取權杖 (Access tokens)](https://auth.wiki/access-token) 與 [ID 權杖 (ID tokens)](https://auth.wiki/id-token)）以及 Logto [登入階段 (Sign-in sessions)](/sessions#what-is-a-logto-session) 中的瀏覽器 Cookie 的簽章金鑰。這些簽章金鑰會在初始化 Logto 資料庫（[開源版](/logto-oss)）或建立新租戶（[雲端版](/logto-cloud)）時產生，並可透過 [CLI](/logto-oss/using-cli)（開源版）、Management API 或 Console UI 進行管理。 -預設情況下，Logto 使用橢圓曲線（EC）演算法產生數位簽章。然而，考量到使用者常需驗證 JWT 簽章，且許多舊有工具不支援 EC 演算法（僅支援 RSA），我們實作了私鑰輪替功能，並允許使用者選擇簽章演算法（包含 RSA 與 EC）。這確保了與使用舊版簽章驗證工具的服務相容。 +預設情況下，Logto 使用橢圓曲線（EC）演算法產生數位簽章。然而，考量到使用者經常需要驗證 JWT 簽章，且許多舊有工具不支援 EC 演算法（僅支援 RSA），我們實作了私鑰輪替功能，並允許使用者選擇簽章演算法（包含 RSA 與 EC）。這確保了與使用舊版簽章驗證工具的服務相容。 :::note -理論上，簽章金鑰不應外洩且沒有到期時間，因此無需輪替。但定期在一定時間後輪替簽章金鑰可提升安全性。 +理論上，簽章金鑰不應外洩且沒有過期時間，意即無需輪替。但定期在一定時間後輪替簽章金鑰可提升安全性。 ::: -## 運作原理？\{#how-it-works} +## 運作原理 \{#how-it-works} - **OIDC 私鑰 (OIDC private key)** - 初始化 Logto 實例時，會自動產生一對公鑰與私鑰，並註冊於底層 OIDC 提供者。當 Logto 發行新的 JWT（存取權杖或 ID 權杖）時，會以私鑰簽署該權杖。同時，任何收到 JWT 的用戶端應用程式都可利用配對的公鑰驗證權杖簽章，以確保權杖未被第三方竄改。私鑰會受到 Logto 伺服器保護，而公鑰則如其名，對所有人公開，可透過 OIDC 端點的 `/oidc/jwks` 介面存取。產生私鑰時可指定簽章金鑰演算法，Logto 預設使用 EC（橢圓曲線）演算法。管理員可透過輪替私鑰將預設演算法改為 RSA（Rivest-Shamir-Adleman）。 + 當初始化 Logto 實例時，會自動產生一對公鑰與私鑰，並註冊於底層 OIDC 提供者。當 Logto 發行新的 JWT（存取權杖或 ID 權杖）時，會以私鑰簽署該權杖。同時，任何收到 JWT 的用戶端應用程式都可使用配對的公鑰驗證權杖簽章，以確保權杖未被第三方竄改。私鑰會受到 Logto 伺服器保護，而公鑰則如其名，對所有人公開，可透過 OIDC 端點的 `/oidc/jwks` 介面存取。產生私鑰時可指定簽章金鑰演算法，Logto 預設使用 EC（橢圓曲線）演算法。管理員可透過輪替私鑰將預設演算法改為 RSA（Rivest-Shamir-Adleman）。 - **OIDC Cookie 金鑰 (OIDC cookie key)** - 當使用者啟動登入或註冊流程時，伺服器會建立一個「OIDC 階段 (Session)」，同時產生一組瀏覽器 Cookie。藉由這些 Cookie，瀏覽器可代表使用者向 Logto Experience API 發起一系列互動（如登入、註冊、重設密碼）。但與 JWT 不同，Cookie 僅由 Logto OIDC 服務自身簽署與驗證，無需非對稱加密。因此，Cookie 簽章金鑰沒有配對公鑰，也不採用非對稱加密演算法。 + 當使用者啟動登入或註冊流程時，伺服器會建立一個「OIDC 階段 (Session)」，以及一組瀏覽器 Cookie。藉由這些 Cookie，瀏覽器可代表使用者向 Logto Experience API 發起一系列互動（如登入、註冊、重設密碼）。但與 JWT 不同，Cookie 僅由 Logto OIDC 服務本身簽署與驗證，不需非對稱加密。因此，Cookie 簽章金鑰沒有配對的公鑰，也不使用非對稱加密演算法。 ## 透過 Console UI 輪替簽章金鑰 \{#rotate-signing-keys-from-console-ui} Logto 提供「簽章金鑰輪替 (Signing Keys Rotation)」功能，讓你能在租戶中建立新的 OIDC 私鑰與 Cookie 金鑰。 -1. 前往 Console > 租戶設定 > OIDC 設定，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。 -2. 若要輪替簽章金鑰，點擊「輪替私鑰 (Rotate private keys)」或「輪替 Cookie 金鑰 (Rotate cookie keys)」按鈕。輪替私鑰時，你可選擇更換簽章演算法。 +1. 前往 Console > Tenant settings > OIDC configs，即可管理 OIDC 私鑰與 OIDC Cookie 金鑰。 +2. 若要輪替簽章金鑰，點擊「Rotate private keys」或「Rotate cookie keys」按鈕。輪替私鑰時，你可選擇更換簽章演算法。 3. 你會看到一個表格，列出所有正在使用的簽章金鑰。對於 OIDC 私鑰，你可以刪除前一個金鑰，但無法刪除目前或下一個金鑰。對於 OIDC Cookie 金鑰，你可以刪除前一個金鑰，但無法刪除目前金鑰。 - | 狀態 | 說明 | - | ------ | --------------------------------------------------------------------------------------------------- | - | 下一個 | 用於分階段 OIDC 私鑰輪替。金鑰已建立，但 Logto 會等到寬限期結束、金鑰生效後才用它簽署新的 JWT。 | - | 目前 | 表示 Logto 目前用此金鑰簽署新發行的 JWT 或 Cookie。 | - | 前一個 | 指先前使用過但已被輪替的金鑰。用該金鑰簽署的現有 JWT 或 Cookie 仍然有效，直到過期或金鑰被刪除為止。 | + | 狀態 | 說明 | + | -------- | -------------------------------------------------------------------------------------------------- | + | Next | 用於分階段 OIDC 私鑰輪替。金鑰已建立，但在寬限期結束並成為有效金鑰前，Logto 不會用它簽署新的 JWT。 | + | Current | 目前 Logto 用來簽署新發行 JWT 或 Cookie 的金鑰。 | + | Previous | 先前使用過但已被輪替的金鑰。用該金鑰簽署的現有 JWT 或 Cookie 仍然有效，直到過期或金鑰被刪除為止。 | 請記得，輪替包含以下三個動作： -1. **建立新簽章金鑰**：對於 OIDC 私鑰，Logto 可先將新金鑰設為「下一個 (Next)」，讓你的應用程式與 API 有時間從 `/oidc/jwks` 端點刷新公鑰，之後才用新金鑰簽署。 -2. **輪替目前金鑰**：當輪替生效時，「下一個 (Next)」金鑰會變成「目前 (Current)」，而現有「目前」金鑰則變為「前一個 (Previous)」。用前一個金鑰簽署的權杖仍然有效。 -3. **移除最舊的前一個金鑰**：Logto 最多僅保留一組「前一個 (Previous)」私鑰。若在新金鑰生效時已存在前一個私鑰，舊的前一個金鑰會被移除。 +1. **建立新簽章金鑰**：對於 OIDC 私鑰，Logto 可先將新金鑰標記為「Next」，讓你的應用程式與 API 有時間從 `/oidc/jwks` 端點刷新公鑰，之後才用新金鑰簽署。 +2. **輪替目前金鑰**：當輪替生效時，「Next」金鑰會變成「Current」，而原本的「Current」金鑰則變為「Previous」。用前一個金鑰簽署的權杖仍然有效。 +3. **移除最舊的前一個金鑰**：Logto 最多只保留一把「Previous」私鑰。若在新金鑰生效時已存在前一個私鑰，則會移除更舊的那一把。 -在 Logto Cloud 中，OIDC 私鑰輪替會在 4 小時寬限期後生效。這段期間內，新金鑰會先準備好並透過 JWKS 公開，Logto 會等到寬限期結束才用它簽署新發行的 JWT。在 Console 表格中，**生效時間 (Effective at)** 欄位會顯示分階段「下一個 (Next)」金鑰何時會變成「目前 (Current)」。 +對於 Logto Cloud，OIDC 私鑰輪替會在 4 小時寬限期後生效。在此期間，新金鑰會先準備好並透過 JWKS 公開，Logto 之後才會用它簽署新發行的 JWT。在 Console 表格中，**Effective at** 欄位會顯示分階段「Next」金鑰成為「Current」的時間。 -對於自架 OSS 部署，預設私鑰輪替寬限期為 `0` 秒，即輪替立即生效。若要使用分階段輪替，請在 Logto 服務設定 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 環境變數，或在呼叫 Management API 端點 `POST /api/configs/oidc/private-keys/rotate` 時於 request body 傳入明確的 `rotationGracePeriod` 值。 +對於自架設的 OSS 部署，預設私鑰輪替寬限期為 `0` 秒，意即輪替立即生效。若要使用分階段輪替，請在 Logto 服務設定 `PRIVATE_KEY_ROTATION_GRACE_PERIOD` 環境變數，或在呼叫 Management API 端點 `POST /api/configs/oidc/private-keys/rotate` 時於 request body 傳入明確的 `rotationGracePeriod` 值。 :::warning -除非你有意更換分階段「下一個 (Next)」金鑰，否則請避免在待生效輪替尚未生效前重複輪替簽章金鑰。 +除非你有意更換分階段「Next」金鑰，否則請避免在待處理輪替尚未生效前重複輪替簽章金鑰。 -過早刪除唯一的「前一個 (Previous)」金鑰，可能導致用該金鑰簽署的現有 JWT 或 Cookie 失效。 +過早刪除唯一的「Previous」金鑰，可能導致用該金鑰簽署的現有 JWT 或 Cookie 失效。 ::: ## 相關資源 \{#related-resources} - JWT 中 EC 與 RSA 簽章演算法介紹 + JWT 中 EC 與 RSA 簽章演算法介紹 (Introduction to EC and RSA signing algorithms in JWT) diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx index 2ae0abab1f4..bd87b756d34 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/README.mdx @@ -1,52 +1,52 @@ --- -sidebar_position: 6 +sidebar_position: 7 --- # Webhook -Logto [Webhook](https://auth.wiki/webhook) 為各種事件提供即時通知，包括使用者帳號、角色、權限、組織、組織角色、組織權限，以及 [使用者互動](/end-user-flows) 的變更。 +Logto [Webhook](https://auth.wiki/webhook) 提供各種事件的即時通知，包括使用者帳號、角色 (Role)、權限 (Permission)、組織 (Organization)、組織角色 (Organization Role)、組織權限 (Organization Permission) 以及 [使用者互動](/end-user-flows) 的變更。 -當事件被觸發時，Logto 會向你提供的 Endpoint URL 發送 HTTP 請求，內容包含事件的詳細資訊，例如使用者 ID、使用者名稱、電子郵件及其他相關細節（關於 payload 與 header 所含資料，請參閱 [Webhook 請求](/developers/webhooks/webhooks-request)）。你的應用程式可以處理這個請求並執行自訂動作，例如發送電子郵件或更新資料庫資料。 +當事件被觸發時，Logto 會向你提供的 Endpoint URL 發送 HTTP 請求，內容包含事件的詳細資訊，例如使用者 ID、使用者名稱、電子郵件及其他相關細節（關於 payload 與 header 所包含的資料，請參閱 [Webhook 請求](/developers/webhooks/webhooks-request)）。你的應用程式可以處理這個請求並執行自訂動作，例如發送電子郵件或更新資料庫資料。 我們會根據用戶需求持續新增更多事件。如果你有特定業務需求，歡迎告訴我們。 -## 為什麼要使用 Webhook？\{#why-use-webhook} +## 為什麼要使用 Webhook？ \{#why-use-webhook} -Webhook 提供應用程式間的即時通訊，免除輪詢需求，實現即時資料更新。它們簡化了應用程式整合與工作流程自動化，無需複雜程式碼或專屬 API。 +Webhook 提供應用程式間的即時通訊，免除輪詢需求，實現即時資料更新。它們簡化了應用程式整合與工作流程自動化，無需複雜程式碼或專有 API。 -以下是 CIAM 常見 Webhook 使用案例： +以下是 CIAM 常見 Webhook 應用案例： -- **發送電子郵件：** 設定 Webhook，讓新使用者註冊時自動發送歡迎信，或在使用者從新裝置 / 地點登入時通知管理員。 +- **發送電子郵件：** 設定 Webhook，讓新使用者註冊時自動發送歡迎信，或當使用者從新裝置 / 地點登入時通知管理員。 - **發送通知：** 設定 Webhook，當使用者註冊時觸發 CRM 系統的虛擬助理，提供即時客戶支援。 -- **執行額外 API 呼叫：** 設定 Webhook，透過檢查使用者電子郵件網域或 IP 來驗證存取，然後使用 Logto Management API 指派具備資源權限的適當角色。 +- **執行額外 API 呼叫：** 設定 Webhook，根據使用者電子郵件網域或 IP 位址驗證其存取權，然後使用 Logto Management API 指派具備資源權限的適當角色 (Role)。 - **資料同步：** 設定 Webhook，讓應用程式即時獲知如使用者帳號停用或刪除等變更。 - **產生報表：** 設定 Webhook 接收使用者登入活動資料，並用於產生使用者參與度或使用模式報表。 ## 術語 \{#terms} -| Item | Description | -| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| Event | 當特定動作發生時，會觸發具有特定型別的 hook 事件。例如，當使用者完成註冊流程並建立新帳號時，Logto 會發出 PostRegister hook 事件。 | -| Hook | 連接到特定事件的一個或一系列動作。動作可以是呼叫 API、執行程式碼片段等。 | -| Webhook | 一種 hook 子型別，表示以事件 payload 呼叫 API。 | -| 假設開發者希望在使用者從新裝置登入時發送通知，可以新增一個 webhook，於 PostSignIn 事件呼叫其安全服務 API。 | +| Item | Description | +| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | +| Event | 當特定動作發生時，會觸發具有特定類型的 hook 事件。例如，當使用者完成註冊流程並建立新帳號時，Logto 會發出 PostRegister hook 事件。 | +| Hook | 連接到特定事件的一個或一系列動作。動作可以是呼叫 API、執行程式碼片段等。 | +| Webhook | hook 的一種子類型，表示以事件 payload 呼叫 API。 | +| 假設開發者希望在使用者透過新裝置登入時發送通知，可以新增一個 webhook，將 PostSignIn 事件呼叫其安全服務 API。 | -以下是在 Logto 中為 `PostSignIn` 事件啟用兩個 web hook 的範例： +以下是在 Logto 為 `PostSignIn` 事件啟用兩個 webhook 的範例： ```mermaid graph LR subgraph Logto SF(登入完成 (Sign-in finished)) PS(登入後 (Post sign-in)) - WH2(Web hook 2) - WH1(Web hook 1) + WH2(Webhook 2) + WH1(Webhook 1) end - subgraph Service 2 + subgraph 服務 2 (Service 2) E2(Endpoint) end - subgraph Service 1 + subgraph 服務 1 (Service 1) E1(Endpoint) end @@ -63,18 +63,18 @@ graph LR
-### Logto 支援同步 webhook 嗎？\{#does-logto-support-synced-webhooks} +### Logto 支援同步 webhook 嗎？ \{#does-logto-support-synced-webhooks} -雖然同步 webhook 能讓使用者登入流程更順暢，但目前尚未支援（未來會支援）。因此，目前所有依賴同步 webhook 的情境都需要其他替代方案。如有疑問，歡迎聯絡我們。 +雖然同步 webhook 能讓使用者登入流程更順暢，但目前尚未支援（未來會支援）。因此，目前所有依賴同步 webhook 的場景都需要不同的替代方案。如有疑問，歡迎聯繫我們。
-### 如何處理使用者權限變更？\{#how-to-deal-with-user-permission-change} +### 如何處理使用者權限變更？ \{#how-to-deal-with-user-permission-change} @@ -85,22 +85,22 @@ graph LR
-### 如何除錯 webhook 超時？\{#how-to-debug-webhook-timeout} +### 如何除錯 webhook 超時？ \{#how-to-debug-webhook-timeout} -接收 Webhook 的 endpoint 應盡快回傳 2xx 響應，告知 Logto Webhook 已成功接收。由於不同用戶對 Webhook 的處理邏輯差異極大，過於複雜的任務可能需數秒，導致 Logto Webhook 超時。最佳實踐是維護自己的事件佇列；收到 Logto Webhook 時，將事件插入佇列並立即回傳 2xx 給 Logto，然後讓自己的 worker 逐步處理佇列任務。若 worker 發生錯誤，請於自家伺服器處理。 +接收 Webhook 的 endpoint 應盡快回傳 2xx 回應，告知 Logto Webhook 已成功接收。由於不同用戶對 Webhook 的處理邏輯差異很大，過於複雜的任務可能需數秒，導致 Logto Webhook 超時。最佳做法是維護自己的事件佇列；收到 Logto Webhook 時，將事件寫入佇列並立即回傳 2xx 給 Logto，然後讓自己的 worker 逐步處理佇列任務。若 worker 發生錯誤，請在自己的伺服器上處理。
-### 可以從 `PostSignIn` webhook 取得 client IP 嗎？\{#can-i-get-the-client-ip-address-from-postsignin-webhooks} +### 我可以從 `PostSignIn` webhook 取得 client IP 嗎？ \{#can-i-get-the-client-ip-address-from-postsignin-webhooks} -可以，你可以在 Webhook payload 中取得 IP 位址、user agent 等資訊。如需目前未支援的資訊，歡迎於 GitHub issues 提出功能需求，或聯絡我們。 +可以，你可以在 Webhook payload 中取得 IP 位址、user agent 等資訊。如果你需要目前尚未支援的資訊，歡迎在 GitHub issue 提出功能需求，或聯繫我們。
diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx index f19f0bd5742..fec83b2da95 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/developers/webhooks/events.mdx @@ -7,73 +7,73 @@ sidebar_position: 3 # Webhooks 事件 -本指南列出不同的 Logto webhook 事件，並解釋每個事件發生的時機。 +本指南列出不同的 Logto Webhook 事件，並說明每個事件發生的時機。 -## 使用者互動 hook 事件 \{#user-interaction-hook-events} +## 使用者互動 Hook 事件 \{#user-interaction-hook-events} -| 事件類型 | 描述 | -| ----------------- | ------------------------------------------ | -| PostRegister | 使用者透過 UI 介面成功創建新帳戶。 | -| PostSignIn | 使用者透過 UI 介面成功登入。 | -| PostResetPassword | 使用者的密碼透過「忘記密碼」流程成功重設。 | +| 事件類型 | 說明 | +| ----------------- | ---------------------------------------- | +| PostRegister | 使用者透過 UI 介面成功建立新帳號。 | +| PostSignIn | 使用者透過 UI 介面成功登入。 | +| PostResetPassword | 使用者透過「忘記密碼」流程成功重設密碼。 | -## 資料變更 hook 事件 \{#data-mutation-hook-events} +## 資料變更 Hook 事件 \{#data-mutation-hook-events} ### 使用者 \{#user} -| 事件類型 | 描述 | -| ----------------------------- | --------------------------------------------------------------- | -| User.Created | 創建新使用者帳戶。 | -| User.Deleted | 刪除使用者帳戶。 | -| User.Data.Updated | 更新使用者資料，例如電子郵件、頭像、custom.data、社交識別符等。 | -| User.SuspensionStatus.Updated | 使用者的停權狀態改變（停權或重新啟用）。 | +| 事件類型 | 說明 | +| ----------------------------- | ------------------------------------------------------------------- | +| User.Created | 建立新使用者帳號。 | +| User.Deleted | 刪除使用者帳號。 | +| User.Data.Updated | 更新使用者個人資料，例如電子郵件、頭像、custom.data、社交識別碼等。 | +| User.SuspensionStatus.Updated | 使用者停權狀態變更（停權或重新啟用）。 | -### 角色 \{#role} +### 角色 (Role) \{#role} -| 事件類型 | 描述 | +| 事件類型 | 說明 | | ------------------- | ------------------------------------------------ | -| Role.Created | 創建新角色。 | +| Role.Created | 建立新角色。 | | Role.Deleted | 刪除角色。 | -| Role.Data.Updated | 更新角色資料，例如角色名稱、描述和預設角色狀態。 | -| Role.Scopes.Updated | 為角色分配的權限被新增或移除。 | +| Role.Data.Updated | 更新角色資料，例如角色名稱、描述、預設角色狀態。 | +| Role.Scopes.Updated | 新增或移除指派給角色的權限。 | ### 權限（Scope）\{#permission-scope} -| 事件類型 | 描述 | -| ------------------ | ----------------------------------- | -| Scope.Created | 創建新的 API 權限。 | -| Scope.Deleted | 刪除 API 權限。 | -| Scope.Data.Updated | 更新 API 權限的資料，例如權限描述。 | +| 事件類型 | 說明 | +| ------------------ | --------------------------------- | +| Scope.Created | 建立新的 API 權限。 | +| Scope.Deleted | 刪除 API 權限。 | +| Scope.Data.Updated | 更新 API 權限資料，例如權限描述。 | -### 組織 \{#organization} +### 組織 (Organization) \{#organization} -| 事件類型 | 描述 | -| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| Organization.Created | 創建新組織。 | -| Organization.Deleted | 刪除組織。 | -| Organization.Data.Updated | 更新組織資料，例如組織名稱、描述、custom.data 等。 | -| Organization.Membership.Updated | 使用者或應用程式被新增或移除出組織。負載包含 [membership delta fields](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)。 | +| 事件類型 | 說明 | +| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Organization.Created | 建立新組織。 | +| Organization.Deleted | 刪除組織。 | +| Organization.Data.Updated | 更新組織資料，例如組織名稱、描述、custom.data 等。 | +| Organization.Membership.Updated | 新增或移除組織中的使用者或應用程式。Payload 包含 [membership delta fields](/developers/webhooks/webhooks-request#organizationmembershipupdated-payload)。 | -### 組織角色 \{#organization-role} +### 組織角色 (Organization role) \{#organization-role} -| 事件類型 | 描述 | +| 事件類型 | 說明 | | ------------------------------- | ------------------------------------------ | -| OrganizationRole.Created | 創建新組織角色。 | +| OrganizationRole.Created | 建立新組織角色。 | | OrganizationRole.Deleted | 刪除組織角色。 | -| OrganizationRole.Data.Updated | 更新組織角色資料，例如組織角色名稱和描述。 | -| OrganizationRole.Scopes.Updated | 為組織角色分配的權限被新增或移除。 | +| OrganizationRole.Data.Updated | 更新組織角色資料，例如組織角色名稱與描述。 | +| OrganizationRole.Scopes.Updated | 新增或移除指派給組織角色的權限。 | ### 組織權限（Scope）\{#organization-permission-scope} -| 事件類型 | 描述 | -| ------------------------------ | -------------------------------------- | -| OrganizationScope.Created | 創建新的組織權限。 | -| OrganizationScope.Deleted | 刪除組織權限。 | -| OrganizationScope.Data.Updated | 更新組織權限的資料，例如組織權限描述。 | +| 事件類型 | 說明 | +| ------------------------------ | ------------------------------------ | +| OrganizationScope.Created | 建立新組織權限。 | +| OrganizationScope.Deleted | 刪除組織權限。 | +| OrganizationScope.Data.Updated | 更新組織權限資料，例如組織權限描述。 | -### Management API 觸發的事件 \{#management-api-triggered-events} +### Management API 觸發事件 \{#management-api-triggered-events} -| API 端點 | 事件 | +| API endpoint | 事件 | | ---------------------------------------------------------- | ----------------------------------------------------------- | | POST /users | User.Created | | DELETE /users/:userId | User.Deleted | @@ -110,34 +110,35 @@ sidebar_position: 3 | POST /organization-roles/:id/scopes | OrganizationRole.Scopes.Updated | | DELETE /organization-roles/:id/scopes/:organizationScopeId | OrganizationRole.Scopes.Updated | -### Experience API 觸發的事件 \{#experience-api-triggered-events} +### Experience API 觸發事件 \{#experience-api-triggered-events} -| 使用者互動操作 | 事件 | -| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| 使用者電子郵件/電話連結 | User.Data.Updated | -| 使用者 MFA 連結 | User.Data.Updated | -| 使用者社交/SSO 連結 | User.Data.Updated | -| 使用者密碼重設 | User.Data.Updated | -| 使用者註冊 | User.Created | -| 使用者透過 [即時佈建 (JIT, Just-in-Time provisioning)](/organizations/just-in-time-provisioning) 自動佈建到組織（匹配電子郵件域或企業級 SSO 連接器） | Organization.Membership.Updated | +| 使用者互動行為 | 事件 | +| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| 使用者綁定電子郵件 / 電話 | User.Data.Updated | +| 使用者綁定 MFA | User.Data.Updated | +| 使用者綁定社交 / SSO | User.Data.Updated | +| 使用者重設密碼 | User.Data.Updated | +| 使用者註冊 | User.Created | +| 使用者透過 [即時佈建 (Just-in-Time provisioning)](/organizations/just-in-time-provisioning)（符合電子郵件網域或企業級 SSO 連接器）自動加入組織 | Organization.Membership.Updated | -## 異常 hook 事件 \{#exception-hook-events} +## 例外 Hook 事件 \{#exception-hook-events} ### 安全性 \{#security} -| 事件類型 | 描述 | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| Identifier.Lockout | 使用者帳戶因連續身份驗證失敗而被鎖定。可能在以下流程中觸發：
  • 密碼驗證失敗
  • 代碼驗證失敗
  • 一次性權杖驗證失敗
| +| 事件類型 | 說明 | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Identifier.Lockout | 使用者帳號因連續身分驗證失敗而被鎖定。可於下列流程觸發：
  • 密碼驗證失敗
  • 驗證碼驗證失敗
  • 一次性權杖驗證失敗
| +| Message.RateLimited | 終端使用者超過每收件人 [發送速率限制](/security/send-rate-limit) 的驗證碼發送次數。僅於終端使用者發送路徑（Experience API 與 Account API）觸發，payload 為 `{ action, recipient }`。 | ## 常見問題 \{#faqs}
-### `PostRegister` 和 `User.Created` 有什麼區別？\{#whats-the-difference-between-postregister-and-usercreated} +### `PostRegister` 與 `User.Created` 有什麼不同？\{#whats-the-difference-between-postregister-and-usercreated} -`PostRegister` 在使用者透過使用者註冊流程成功創建新帳戶時觸發；`User.Created` 在透過 Management API 創建新使用者帳戶時觸發。 +`PostRegister` 於使用者透過註冊流程成功建立新帳號時觸發；`User.Created` 則於透過 Management API 建立新使用者帳號時觸發。
diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/README.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/README.mdx index 185806cfe8b..72f6c1984e6 100644 --- a/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/README.mdx +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/README.mdx @@ -8,11 +8,11 @@ import SecurityIcon from '@site/src/assets/security.svg'; import SendEmailIcon from '@site/src/assets/send-mail.svg'; import SuspendIcon from '@site/src/assets/suspend.svg'; -# 安全性 (Security) +# 安全性 -現代驗證 (Authentication) 安全性需對抗各種威脅，包括網路釣魚、憑證填充、暴力破解、勒索軟體、DDoS 以及 AI 驅動攻擊。保護使用者身分對於維護品牌信任與合規至關重要。 +現代驗證 (Authentication) 安全性需對抗各種威脅，包括網路釣魚、憑證填充、暴力破解、勒索軟體、DDoS 以及 AI 驅動攻擊。保護使用者身分對於維護品牌信任與法規遵循至關重要。 -Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而設計。我們以主動威脅預防與韌性為優先，確保你的系統在不犧牲易用性的前提下持續受到保護。對 Logto 而言，安全性不是事後考量，而是基石，讓企業在威脅不斷演進的時代中依然能夠蓬勃發展，因為防禦進化得更快。 +Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而設計。我們以主動威脅預防與韌性為優先，確保你的系統在不犧牲易用性的前提下持續受到防護。對 Logto 而言，安全性不是事後考量，而是基石，讓企業在威脅不斷演進的時代中依然能夠蓬勃發展，因為防禦總是更快進化。 ## 設定進階安全防護 \{#set-up-advanced-security-protection} @@ -41,7 +41,7 @@ Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而 type: 'link', label: '封鎖清單 (Blocklist)', href: '/security/blocklist', - description: '封鎖一次性或不受歡迎的電子郵件網域或地址，掌控你的使用者基礎。', + description: '透過封鎖一次性或不受歡迎的電子郵件網域或地址，掌控你的使用者基礎。', customProps: { icon: , }, @@ -55,11 +55,20 @@ Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而 icon: , }, }, + { + type: 'link', + label: '發送速率限制 (Send rate limit)', + href: '/security/send-rate-limit', + description: '限制每位收件人的驗證碼與訊息發送次數，防止收件匣垃圾郵件與簡訊濫用。', + customProps: { + icon: , + }, + }, { type: 'link', label: '隱藏帳號存在狀態 (Hide account existence)', href: '/end-user-flows/sign-up-and-sign-in', - description: '隱藏帳號狀態，阻擋帳號枚舉攻擊並避免洩漏敏感帳號資訊。', + description: '隱藏帳號狀態，阻擋帳號枚舉攻擊，避免洩漏敏感帳號資訊。', customProps: { icon: , }, @@ -75,7 +84,7 @@ Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而 type: 'link', label: '多重要素驗證 (MFA, Multi-Factor Authentication)', href: '/end-user-flows/mfa', - description: '為登入流程新增額外防護層，支援驗證器 App OTP、通行密鑰（WebAuthn）與備用代碼。', + description: '為登入流程新增額外防護層，支援驗證器 App OTP、通行密鑰（WebAuthn）與備用碼。', customProps: { icon: , }, @@ -100,16 +109,16 @@ Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而 }, { type: 'link', - label: '輪替簽章金鑰 (Rotate signing keys)', + label: '簽章金鑰輪替 (Rotate signing keys)', href: '/developers/signing-keys', - description: '定期輪替簽章金鑰，以防止金鑰洩漏與權杖偽造。', + description: '定期輪替簽章金鑰，防止金鑰洩漏與權杖偽造。', customProps: { icon: , }, }, { type: 'link', - label: 'OIDC 後端通道登出 (OIDC back-channel logout)', + label: 'OIDC 後台登出 (OIDC back-channel logout)', href: '/end-user-flows/sign-out#federated-sign-out-back-channel-logout', description: '啟用集中式登出，降低工作階段劫持與未授權存取風險。', customProps: { @@ -120,7 +129,7 @@ Logto 提供強大且安全的存取管理，專為正面迎擊這些風險而 type: 'link', label: '僅限邀請註冊 (Invitation-only sign up)', href: '/end-user-flows', - description: '僅允許受邀使用者註冊，並透過電子郵件魔法連結進行安全導入。', + description: '僅允許受邀使用者註冊，透過電子郵件魔術連結進行安全導入。', customProps: { icon: , }, diff --git a/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx b/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx new file mode 100644 index 00000000000..2848d738971 --- /dev/null +++ b/i18n/zh-TW/docusaurus-plugin-content-docs/current/security/send-rate-limit.mdx @@ -0,0 +1,38 @@ +--- +slug: /security/send-rate-limit +sidebar_label: 傳送速率限制 (Send rate limit) +sidebar_position: 5 +--- + +# 傳送速率限制 (Send rate limiting) + +Logto 針對外發驗證碼及其他透過電子郵件和簡訊發送的訊息，對每個收件人實施內建的速率限制。這可保護你的使用者及訊息服務供應商免於傳送濫用——例如攻擊者大量發送驗證碼到受害者的信箱或手機，或惡意推高簡訊流量以增加你的成本。 + +此限制為**強制且系統層級**：適用於每個租戶，無論方案為何，且**無法**由租戶自行設定。它獨立於以下項目： + +- **[識別碼鎖定](/security/identifier-lockout)** 與 **[CAPTCHA](/security/captcha)** 政策，這些是在驗證時限制*失敗驗證嘗試*，而非*傳送*行為本身。 +- 全域每租戶 API 速率限制（錯誤碼 `request.rate_limited`），該限制針對整個租戶的請求總量。 + +## 運作方式 \{#how-it-works} + +- **每收件人上限**：Logto 限制在短時間內對同一收件人（電子郵件地址或手機號碼）可傳送的訊息數量。預設為**每 10 分鐘內，每個收件人最多可傳送 10 次**。 +- **適用範圍**：所有伺服器端傳送路徑，包括 Experience API 與 Account API 的驗證碼傳送（登入、註冊、重設密碼、MFA、識別碼綁定）、Management API 驗證碼傳送、組織邀請傳送與重發，以及 Account (`/me`) 驗證碼傳送。 +- **超過上限時**：請求會被拒絕，回傳 HTTP `429` 及錯誤碼 `request.message_rate_limited`——這與全域租戶限制器（`request.rate_limited`）及驗證時鎖定（`session.verification_blocked_too_many_attempts`）不同，因此你可在整合時針對此情境進行特別處理。 + +## 透過 Webhook 監控速率受限的傳送 \{#monitor-rate-limited-sends-with-a-webhook} + +當**終端使用者**觸發每收件人上限時，Logto 會觸發 `Message.RateLimited` [Webhook 事件](/developers/webhooks/webhooks-events#exception-hook-events)，讓你能針對傳送濫用發出警示或採取行動。 + +- **觸發時機**：僅針對終端使用者驗證碼傳送路徑——即 Experience API 與 Account API。**不會**針對第一方或管理員發起的傳送（Management API 驗證碼、組織邀請或 `/me`）觸發。 +- **Payload**：Hook context 會包含 `action`（例如 `VerificationCodeSend`）及 `recipient`（電子郵件地址或手機號碼）。 + +**常見應用場景：** + +- 向你的團隊發送安全警示以供審查。 +- 針對受影響收件人觸發下游防濫用自動化。 + +前往 Console > Webhooks 訂閱，或透過 Management API 建立 Hook。詳細事件結構與設定，請參閱 [Webhooks](/developers/webhooks)。 + +## 對未知收件人的傳送抑制 \{#suppressed-delivery-to-unknown-recipients} + +為防止帳號枚舉，當透過識別碼註冊功能被停用時，若對**尚未註冊帳號**的電子郵件地址或手機號碼請求登入驗證碼，系統會靜默不傳送，且 API 回應與實際傳送時相同。攻擊者因此無法藉由回應判斷哪些地址已註冊。對現有使用者的傳送不受影響。詳見 [隱藏帳號存在性](/end-user-flows/sign-up-and-sign-in)。