Zum Hauptinhalt springen

Globale API-Ressourcen schützen

Schütze produktweite APIs mit rollenbasierter Zugangskontrolle (RBAC) in Logto. Weise globale Rollen und Berechtigungen zu, um den Zugriff für alle Benutzer und Clients in deiner Anwendung zu steuern.

Was sind globale API-Ressourcen?​

Globale API-Ressourcen sind Endpunkte oder Dienste in deiner Anwendung, die für alle Benutzer zugänglich sind, unabhängig von Organisation oder Mandant. Dies sind typischerweise öffentlich zugängliche APIs, zentrale Produktdienste oder jeder Endpunkt, der nicht auf eine bestimmte Organisation beschränkt ist.

Anwendungsfälle umfassen

  • Öffentliche APIs oder Endpunkte, die von deiner gesamten Benutzerbasis geteilt werden.
  • Microservices, die nicht an Multi-Tenancy gebunden sind.
  • Zentrale Anwendungs-APIs (z. B. /api/users, /api/products), die von allen Kunden genutzt werden.

Logto ermöglicht es dir, diese APIs mit OAuth 2.1 in Kombination mit flexibler, rollenbasierter Zugangskontrolle abzusichern.

So funktioniert es in Logto​

  • API-Ressourcen und Berechtigungen werden global registriert: Jede API, die du schützen möchtest, wird mit einem eindeutigen Ressourcenindikator (URI) und einem Satz von Berechtigungen (Scopes) definiert, die den Zugriff steuern.
  • Der Zugriff wird durch globale Rollen gesteuert: Du kannst Berechtigungen Rollen zuweisen, die dann Benutzern oder Clients zugewiesen werden.
  • Getrennt von organisationsbezogenen Berechtigungen: Globale API-Ressourcen haben keinen Organisationskontext. Sie können jedoch in Verbindung mit Organisationsrollen verwendet werden, um bei Bedarf eine zusätzliche Kontextebene bereitzustellen. Um organisationsbezogene APIs zu schützen, siehe Organisationsbezogene API-Ressourcen schützen.
Globale API-Ressourcen RBAC

Überblick über die Implementierung​

  1. Registriere deine API-Ressource und definiere deren Berechtigungen in Logto.
  2. Definiere Rollen mit den notwendigen Berechtigungen für den Zugriff auf die API.
  3. Weise Rollen Benutzern oder Clients zu.
  4. Nutze OAuth 2.0 Autorisierungsflüsse, um Zugangstokens für die API zu erhalten (der resource-Parameter muss mit dem registrierten API-Identifier übereinstimmen).
  5. Validiere Zugangstokens in deiner API, um Berechtigungen durchzusetzen.

Ressourcenindikatoren verstehen​

Logto modelliert API-Ressourcen gemäß RFC 8707: Resource Indicators for OAuth 2.0. Ein Ressourcenindikator ist eine URI, die die angeforderte Ziel-API oder den Dienst eindeutig identifiziert.

Wichtige Punkte

  • Ressourcenindikatoren müssen absolute URIs sein (z. B. https://api.example.com)
  • Kein Fragmentbestandteil; vermeide nach Möglichkeit die Verwendung von Query-Strings.
  • Ressourcenindikatoren ermöglichen zielgruppenbeschränkte Tokens und unterstützen Multi-API-Architekturen.

Beispiel

  • Management API: https://my-tenant.logto.app/api
  • Benutzerdefinierte globale API: https://api.yourapp.com

Autorisierungsfluss: Authentifizierung und Absicherung deiner API​

Der folgende Ablauf gilt sowohl für interaktive Benutzer-Authentifizierung (Browser / App) als auch für Backend-Maschine-zu-Maschine (M2M)-Szenarien.

Bitte beachte, dass der Ablauf keine vollständigen Details zu den erforderlichen Parametern oder Headern enthält, sondern sich auf die wichtigsten Schritte konzentriert. Lies weiter, um zu sehen, wie der Ablauf in der Praxis funktioniert.

Benutzer-Authentifizierung = Browser / App. M2M = Backend-Dienst oder Skript mit Client-Credentials.

hinweis:

Der resource-Parameter muss exakt mit dem API-Identifier (Ressourcenindikator) übereinstimmen, den du in Logto registriert hast.

Umsetzungsschritte​

Registriere deine API-Ressourcen​

  1. Gehe zu Konsole → API-Ressourcen.
  2. Erstelle eine neue API-Ressource (z. B. https://api.yourapp.com/org) und definiere deren Berechtigungen (Scopes).

Für vollständige Konfigurationsschritte siehe API-Ressourcen mit Berechtigungen definieren.

Richte globale Rollen ein​

  1. Gehe zu Konsole → Rollen.
  2. Erstelle Rollen, die deinen API-Berechtigungen entsprechen (z. B. read:products, write:products).
  3. Weise diese Rollen Benutzern oder Clients zu, die Zugriff auf die API benötigen.

Für vollständige Konfigurationsschritte siehe Globale Rollen verwenden.

Zugangstokens für globale API-Ressourcen erhalten​

Bevor du auf eine globale API-Ressource zugreifst, muss dein Client ein Zugangstoken erhalten. Logto stellt JSON Web Tokens (JWTs) als Zugangstokens für globale API-Ressourcen aus. Dies geschieht typischerweise über den OAuth 2.0 Authorization Code Flow, Auffrischungstoken-Flow oder den Client-Credentials-Flow.

Authorization Code oder Auffrischungstoken-Flow​

Alle offiziellen Logto SDKs unterstützen das Abrufen von Zugangstokens für globale API-Ressourcen mit dem Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann ebenfalls verwendet werden, um diesen Flow zu implementieren.

Beim Initialisieren des Logto-Clients füge den Ressourcenindikator zum resources-Parameter (Array) hinzu und die gewünschten Berechtigungen (Scopes) zum scopes-Parameter.

Sobald der Benutzer authentifiziert ist, übergib den Ressourcenindikator im resource-Parameter oder einem ähnlich benannten Parameter, wenn du das Zugangstoken anforderst (z. B. beim Aufruf von getAccessToken()).

Details zu jedem SDK findest du in den Quick Starts.

Client-Credentials-Flow​

Für Maschine-zu-Maschine (M2M)-Szenarien kannst du den Client-Credentials-Flow verwenden, um ein Zugangstoken für deine globale API-Ressource zu erhalten. Durch eine POST-Anfrage an Logtos /oidc/token-Endpunkt kannst du ein Zugangstoken mit deiner Client-ID und deinem Secret anfordern.

Es gibt zwei wichtige Parameter, die in der Anfrage enthalten sein müssen:

  • resource: Die Ressourcenindikator-URI der API, auf die du zugreifen möchtest (z. B. https://api.yourapp.com).
  • scope: Die Berechtigungen, die du für die API anfordern möchtest (z. B. read:products write:products).

Hier ist ein nicht-normatives Beispiel für die Token-Anfrage mit dem Client Credentials Grant Type:

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&resource=https://api.yourapp.com
&scope=read:products write:products

JWT-Zugangstokens in deiner API validieren​

Von Logto ausgestellte JWTs enthalten Ansprüche, die deine API zur Durchsetzung der Autorisierung verwenden kann.

Wenn deine API eine Anfrage mit einem von Logto ausgestellten Zugangstoken erhält, solltest du:

  • Die Token-Signatur überprüfen (mit Logtos JWKs).
  • Bestätigen, dass das Token nicht abgelaufen ist (exp-Anspruch).
  • Prüfen, dass der iss (Aussteller) mit deinem Logto-Endpunkt übereinstimmt.
  • Sicherstellen, dass der aud (Zielgruppe) mit dem registrierten API-Ressourcenindikator übereinstimmt (z. B. https://api.yourapp.com).
  • Den scope-Anspruch (durch Leerzeichen getrennt) aufteilen und auf erforderliche Berechtigungen prüfen.

Für Schritt-für-Schritt- und sprachspezifische Anleitungen siehe Wie man Zugangstokens validiert.

Optional: Benutzerberechtigungsänderung behandeln​

info:

👷 In Arbeit. 🚧

Best Practices und Sicherheitstipps​

  • Halte Berechtigungen geschäftsorientiert: Verwende klare Namen, die echten Aktionen entsprechen.
  • Halte die Token-Gültigkeit kurz: Reduziert das Risiko bei einem Token-Leak.
  • Beschränke gewährte Scopes: Gib Tokens nur die Berechtigungen, die sie tatsächlich benötigen.
  • Verwende Zielgruppenbeschränkung: Überprüfe immer den aud-Anspruch, um Missbrauch zu verhindern.

FAQs​

Was, wenn mein Client den resource-Parameter nicht unterstützt?​

Setze eine Standard-API-Ressource in der Logto-Konsole. Tokens verwenden diese Zielgruppe, wenn im Token-Request kein resource-Parameter angegeben ist.

Warum erhalte ich 401 Nicht autorisiert von meiner API?​

Überprüfe die folgenden häufigen Probleme:

  • Token-Signatur: Stelle sicher, dass dein Backend die richtigen JWKs von Logto abruft
  • Token-Gültigkeit: Stelle sicher, dass das Token nicht abgelaufen ist (exp-Anspruch)
  • Zielgruppe: Prüfe, dass der aud-Anspruch mit deinem registrierten API-Ressourcenindikator übereinstimmt
  • Erforderliche Scopes: Stelle sicher, dass das Token die notwendigen Berechtigungen im scope-Anspruch enthält

Wie kann ich ohne vollständigen Client testen?​

Verwende ein Personal Access Token, um authentifizierte Aufrufe zu simulieren. So kannst du deine API-Endpunkte testen, ohne einen vollständigen OAuth-Flow in deiner Client-Anwendung zu implementieren.

Weiterführende Literatur​

Wie man Zugangstokens validiert

RBAC in der Praxis: Sichere Autorisierung für deine Anwendung implementieren

 Token-Ansprüche anpassen RFC 8707: Ressourcenindikatoren