Zum Hauptinhalt springen

Organisationsebene API-Ressourcen schützen

Kombiniere API-Ressourcen mit der Organisationstemplate, um den Zugriff auf APIs und Daten innerhalb jeder Organisation zu beschränken und so eine Mandantenisolation in deinem SaaS sicherzustellen.

Was sind API-Ressourcen auf Organisationsebene?​

API-Ressourcen auf Organisationsebene sind Endpunkte oder Dienste in deiner Anwendung, die auf eine bestimmte Organisation beschränkt sind. Diese APIs erzwingen Autorisierung und Zugriff basierend auf dem Organisationskontext – so wird sichergestellt, dass Benutzer oder Clients nur auf Daten und Aktionen zugreifen, die für ihre Organisation relevant sind.

Anwendungsfälle umfassen

  • APIs zur Verwaltung von Organisationsmitgliedern, Rollen oder Einstellungen (z. B. /organizations/{organizationId}/members)
  • Organisationsbezogene Dashboards, Analysen oder Berichte
  • Abrechnungs-, Abonnement- oder Audit-Endpunkte, die an eine Organisation gebunden sind
  • Jede API, bei der Aktionen und Daten pro Mandant isoliert sind

Logto ermöglicht es dir, diese Organisations-APIs mit OAuth 2.1 und rollenbasierter Zugangskontrolle (RBAC) abzusichern und unterstützt dabei Multi-Tenant-SaaS-Architekturen.

Diese Berechtigungen werden über Organisationsrollen verwaltet, die in der Organisationstemplate definiert sind. Jede Organisation verwendet die gleiche Vorlage, was ein konsistentes Berechtigungsmodell über alle Organisationen hinweg gewährleistet.

So funktioniert es in Logto​

  • API-Ressourcen und Berechtigungen werden global registriert: Jede API-Ressource wird mit einem eindeutigen Ressourcenindikator (URI) und einem Satz von Berechtigungen (Scopes) in Logto definiert.
  • Rollen auf Organisationsebene: Organisationsrollen werden in der Organisationstemplate definiert. API-Ressourcenberechtigungen (Scopes) werden den Organisationsrollen zugewiesen, die dann Benutzern oder Clients innerhalb jeder Organisation zugewiesen werden.
  • Kontextbewusste Autorisierung: Wenn ein Client ein Zugangstoken mit sowohl einer API-Ressource als auch einer organization_id anfordert, stellt Logto ein Token aus, das sowohl den Organisationskontext als auch die API-Zielgruppe enthält. Die Berechtigungen (Scopes) des Tokens werden durch die Organisationsrollen des Benutzers für die angegebene Organisation bestimmt.
  • Trennung von globalen Ressourcen: API-Ressourcen können mit oder ohne Organisationskontext aufgerufen werden. Organisation RBAC wird nur angewendet, wenn eine organization_id in der Anfrage enthalten ist. Für APIs, die für alle Benutzer freigegeben sind, siehe Globale API-Ressourcen schützen.
Organisationsebene API-Ressourcen RBAC

Überblick über die Implementierung​

  1. Registriere deine API-Ressource und definiere deren Berechtigungen (Scopes) in Logto.
  2. Definiere Organisationsrollen in der Organisationstemplate und weise relevante API-Berechtigungen zu.
  3. Weise Rollen Benutzern oder Clients innerhalb jeder Organisation zu.
  4. Fordere ein Zugangstoken für die API mit einer organization_id an, um den Organisationskontext einzubeziehen.
  5. Validiere Zugangstokens in deiner API und erzwinge sowohl Organisationskontext als auch Berechtigungen.

Wie Logto Organisation RBAC anwendet​

  • Wenn du ein Zugangstoken ohne eine organization_id anforderst, werden nur globale Rollen / Berechtigungen berücksichtigt.
  • Wenn du ein Zugangstoken mit einer organization_id anforderst, bewertet Logto die Organisationsrollen des Benutzers und deren zugehörige Berechtigungen für diese Organisation.
  • Das resultierende JWT enthält sowohl die API-Zielgruppe (aud Anspruch) als auch den Organisationskontext (organization_id Anspruch), wobei die Scopes auf diejenigen gefiltert werden, die durch die Organisationsrollen des Benutzers gewährt werden.

Autorisierungsablauf: Authentifizierung und Absicherung von APIs mit Organisationskontext​

Der folgende Ablauf zeigt, wie ein Client (Web, Mobile oder Backend) Organisationstokens erhält und verwendet, um auf API-Ressourcen auf Organisationsebene zuzugreifen.

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-Service oder Skript mit Client-Credentials + Organisationskontext.

Implementierungsschritte​

Registriere deine API-Ressource​

  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.

Organisationsrollen einrichten​

  1. Gehe zu Konsole → Organisationstemplate → Organisationsrollen.
  2. Erstelle Organisationsrollen (z. B. admin, member) und weise jeder Rolle API-Berechtigungen zu.
  3. Weise Rollen Benutzern oder Clients innerhalb jeder Organisation zu. Falls sie noch keine Mitglieder sind, lade sie zuerst ein oder füge sie hinzu.

Für vollständige Konfigurationsschritte siehe Organisationsrollen verwenden.

Organisationstokens für API-Ressourcen erhalten​

Dein Client / deine App sollte ein Token mit sowohl resource als auch organization_id anfordern, um auf APIs auf Organisationsebene zuzugreifen. Logto stellt Organisationstokens als JSON Web Tokens (JWTs) aus. Du kannst diese entweder über den Auffrischungstoken-Flow oder den Client-Credentials-Flow erhalten.

Auffrischungstoken-Flow​

Fast alle offiziellen Logto SDKs unterstützen das Abrufen von Organisationstokens über den Auffrischungstoken-Flow direkt. Eine Standard-OAuth 2.0 / OIDC-Clientbibliothek kann ebenfalls verwendet werden, um diesen Flow zu implementieren.

Beim Initialisieren des Logto SDK füge urn:logto:scope:organizations und die gewünschten Organisationsberechtigungen (Scopes) zum scopes-Parameter hinzu.

Einige Logto SDKs haben einen vordefinierten Scope für Organisationen, wie z. B. UserScope.Organizations in JavaScript SDKs.

hinweis:

Überprüfe den organizations-Anspruch im ID-Token, um eine Liste der Organisations-IDs zu erhalten, denen der Benutzer angehört. Dieser Anspruch listet alle Organisationen auf, bei denen der Benutzer Mitglied ist, was es einfach macht, Organisationen in deiner App aufzulisten oder zu wechseln.

Beim Aufruf von getAccessToken() gib sowohl die API-Ressource (resource) als auch die Organisations-ID (organizationId) an, um ein Organisationstoken zu erhalten.

Für Details zu jedem SDK siehe Quick starts.

Client-Credentials-Flow​

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

Hier sind die wichtigsten Parameter, die in der Anfrage enthalten sein sollten:

  • resource: Der API-Ressourcenbezeichner (z. B. https://api.yourapp.com/org).
  • organization_id: Die ID der Organisation, für die du das Token möchtest.
  • scope: Die API-Ressourcenberechtigungen auf Organisationsebene, die du anfordern möchtest (z. B. invite:member, manage:billing).

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

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/org
&organization_id=your-organization-id
&scope=invite:member manage:billing

Organisationstokens validieren​

Von Logto ausgestellte Organisationstokens (JWTs) enthalten Ansprüche, die deine API zur Durchsetzung der Zugangskontrolle auf Organisationsebene verwenden kann.

Wenn deine App ein Organisationstoken erhält, solltest du:

  • Die Signatur des Tokens ü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-Ressourcenbezeichner übereinstimmt (z. B. https://api.yourapp.com/org).
  • Den organization_id-Anspruch validieren, um sicherzustellen, dass das Token auf die richtige Organisation beschränkt ist.
  • Den scope-Anspruch (durch Leerzeichen getrennt) aufteilen und auf erforderliche Berechtigungen prüfen.
  • Wenn dein API-Pfad die Organisations-ID enthält (z. B. /organizations/{organizationId}/members), stelle sicher, dass der organization_id-Anspruch mit dem Pfadparameter übereinstimmt.

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

Best Practices und Sicherheitstipps​

  • Validiere immer den Organisationskontext: Vertraue nicht nur dem Token; prüfe den organization_id-Anspruch bei jedem organisationsbezogenen API-Aufruf.
  • Verwende Zielgruppenbeschränkungen: Prüfe immer den aud-Anspruch, um sicherzustellen, dass das Token für die beabsichtigte Organisation bestimmt ist.
  • Halte Berechtigungen geschäftsgetrieben: Verwende klare Namen, die echten Aktionen entsprechen; gewähre nur das, was für jede Organisationsrolle benötigt wird.
  • Trenne API- und Nicht-API-Berechtigungen, wo möglich (aber beide können in einer Rolle enthalten sein).
  • Halte Token-Lebensdauern kurz: Reduziert das Risiko, falls ein Token kompromittiert wird.
  • Überprüfe regelmäßig deine Organisationstemplate: Aktualisiere Rollen und Berechtigungen, während sich dein Produkt weiterentwickelt.

FAQs​

Was passiert, wenn ich organization_id nicht in meiner Token-Anfrage angebe?​

Es werden nur globale Rollen / Berechtigungen ausgewertet. Organisation RBAC wird nicht angewendet.

Kann ich Organisations- und Nicht-Organisationsberechtigungen in einer Rolle mischen?​

Nein, Organisationsberechtigungen (einschließlich API-Berechtigungen auf Organisationsebene) werden durch die Organisationstemplate definiert und können nicht mit globalen API-Berechtigungen gemischt werden. Du kannst jedoch Rollen erstellen, die sowohl Organisationsberechtigungen als auch API-Berechtigungen auf Organisationsebene enthalten.

Weiterführende Literatur​

Wie man Zugangstokens validiert Token-Ansprüche anpassen

Anwendungsfall: Multi-Tenant-SaaS-Anwendung bauen

 RFC 8707: Ressourcenindikatoren