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 sind unter anderem

  • Öffentliche APIs oder Endpunkte, die von deiner gesamten Nutzerbasis 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 zugeordnet werden.
  • Getrennt von organisationsbezogenen Berechtigungen: Globale API-Ressourcen haben keinen Organisationskontext. Sie können jedoch zusammen mit Organisationsrollen verwendet werden, um bei Bedarf eine zusätzliche Kontextebene bereitzustellen. Um organisationsbezogene APIs zu schützen, siehe Organisationsbezogene API-Ressourcen schützen.
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 (resource indicator) 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 Query-Strings.
  • Ressourcenindikatoren ermöglichen zielgruppenbeschränkte Tokens und unterstützen Multi-API-Architekturen.

Beispiel

  • Management API: https://my-tenant.logto.app/api
  • Eigene 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.

Beachte, dass der Ablauf nicht alle Details zu erforderlichen Parametern oder Headern enthält, sondern sich auf die wichtigsten Schritte konzentriert. Lies weiter, um zu sehen, wie der Ablauf in der Praxis funktioniert.

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

hinweis:

Der resource-Parameter muss exakt mit dem in Logto registrierten API-Identifier (Ressourcenindikator) übereinstimmen.

Implementierungsschritte​

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.

Globale Rollen einrichten​

  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 auf eine globale API-Ressource zugegriffen werden kann, 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 direkt über den Auffrischungstoken-Flow. Auch eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann für diesen Flow verwendet werden.

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 das Zugangstoken angefordert wird (z. B. beim Aufruf von getAccessToken()).

Details zu jedem SDK findest du in den Schnellstarts.

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 URI des Ressourcenindikators der API, auf die du zugreifen möchtest (z. B. https://api.yourapp.com).
  • scope: Die Berechtigungen, die du für die API anfordern möchtest (z. B. read:products write:products).

Hier ein nicht-normatives Beispiel für die Token-Anfrage mit dem Grant-Typ client_credentials:

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 Signatur des Tokens überprüfen (mit Logtos JWKs).
  • Sicherstellen, 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) auf erforderliche Berechtigungen prüfen.

Für Schritt-für-Schritt- und sprachspezifische Anleitungen siehe Zugangstokens validieren.

Optional: Benutzerberechtigungsänderung behandeln​

info:

👷 In Arbeit. 🚧

Best Practices und Sicherheitstipps​

  • Berechtigungen geschäftsorientiert halten: Verwende klare Namen, die echten Aktionen entsprechen.
  • Token-Ablauf kurz halten: Reduziert das Risiko bei Token-Leakage.
  • Vergebene Scopes begrenzen: Gib Tokens nur die Berechtigungen, die sie tatsächlich benötigen.
  • Zielgruppenbeschränkung nutzen: Überprüfe immer den aud-Anspruch, um Missbrauch zu verhindern.

FAQs​

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

Lege eine Standard-API-Ressource in der Logto-Konsole fest. 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 korrekten JWKs von Logto abruft
  • Token-Ablauf: Stelle sicher, dass das Token nicht abgelaufen ist (exp-Anspruch)
  • Zielgruppe: Prüfe, ob der aud-Anspruch mit deinem registrierten API-Ressourcenindikator übereinstimmt
  • Erforderliche Scopes: Stelle sicher, dass das Token die notwendigen Berechtigungen im scope-Anspruch enthält

Wie kann ich ohne vollständigen Client testen?​

Nutze ein persönliches Zugangstoken, um authentifizierte Aufrufe zu simulieren. So kannst du deine API-Endpunkte testen, ohne einen vollständigen OAuth-Flow in deiner Client-Anwendung zu implementieren.

Kann ich Scope-Präfixe oder Kurzformen bei der Berechtigungsanfrage verwenden?​

Nein. Scope-Namen müssen exakt mit den in deiner API-Ressource definierten Berechtigungsnamen übereinstimmen. Präfixe und Kurzformen funktionieren nicht als Platzhalter.

Beispiel:

Wenn deine API-Ressource definiert:

  • read:elections
  • write:elections

Musst du anfordern:

scopes: ["read:elections", "write:elections"]

Das funktioniert NICHT:

scopes: ["read", "write"]  // ❌ Stimmt nicht mit den Berechtigungsnamen überein

Weiterführende Literatur​

Zugangstokens validieren

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

 Token-Ansprüche anpassen RFC 8707: Ressourcenindikatoren