Zum Hauptinhalt springen

Tenant-Autorisierung und Tenant-Generationen

Jedes OctoMesh-Access-Token ist an genau einen Tenant gebunden. Diese Seite erklärt, wie die Dienste diese Bindung prüfen, was mit Tokens geschieht, wenn ein Tenant gelöscht, neu angelegt oder wiederhergestellt wird, was Clients und Integratoren tun müssen und wie Betreiber einer selbst betriebenen Installation die Prüfungen konfigurieren und einschalten.

Die zwei Prüfungen​

PrüfungFrageWo sie läuft
Routen-TenantWurde das Token für den Tenant ausgestellt, den die Anfrage anspricht?Jeder OctoMesh-API-Dienst mit einer Tenant-Route (/{tenantId}/...), einschließlich der eigenen API des Identity Service, und CK-Methodenaufrufe. Platform Services führt keine Tenant-Prüfung aus.
Tenant-GenerationWurde das Token für diesen Tenant ausgestellt oder für einen früheren Tenant mit derselben ID?Dieselben Stellen, dazu der Token-Endpunkt des Identity Service (Refresh Tokens, Authorization Codes, Device Codes, Token Exchange, On-Behalf-Of)

Beide vergleichen mit dem tenant_id-Claim des Access Tokens. Der allowed_tenants-Claim listet nur die Tenants auf, zu denen ein Benutzer wechseln kann (für eine Tenant-Auswahl); er gewährt nie Zugriff auf eine API.

Routen-Tenant-Prüfung​

Eine Anfrage an /{tenantId}/... ist erlaubt, wenn der Routen-Tenant gleich der tenant_id des Tokens ist. Andernfalls antwortet der Dienst im Modus Enforce mit 403 Forbidden und einem JSON-Body {"message": "..."}, der den Grund nennt. Es gibt zwei Ausnahmen:

  • Administration durch den übergeordneten Tenant. Endpunkte, die ausdrücklich als Tenant-Administration markiert sind (zum Beispiel Backup und Wiederherstellung eines untergeordneten Tenants), akzeptieren ein Benutzer-Token des übergeordneten Tenants. Datenrouten (Entitäten, Abfragen, Stream Data und GraphQL mit der einen Ausnahme unten) und die Identity-Daten eines untergeordneten Tenants (Benutzer, Rollen, Gruppen, Clients) gehören nie dazu. Die Ausnahme: Am GraphQL-Endpunkt gilt das für eine Anfrage, die ausschließlich aus den Methoden für Backup, Wiederherstellung und Archivdaten oder aus Lesezugriffen auf deren Operationen besteht, siehe Administration durch den übergeordneten Tenant über CK-Methoden.
  • Service-Clients auf der Allow-List. Ein Client-Credentials-Client, der in TenantAuthorization:CrossTenantServiceClientIds steht, darf andere Tenants ansprechen. Die Liste soll leer bleiben; jeder Eintrag ist eine dauerhafte Ausnahme.

Client-Credentials-Tokens werden wie Benutzer-Tokens geprüft (ServiceTokenEnforcement, standardmäßig Enforce; das Chart octo-mesh betreibt Identity in LogOnly, solange kein Wert gesetzt ist, siehe Konfiguration): Ihre tenant_id ist der Tenant, für den das Token mit acr_values=tenant:<tenantId> angefordert wurde. Ein Client-Credentials-Login ohne acr_values erhält ein Token des System-Tenants und wird auf den Routen jedes anderen Tenants abgewiesen (siehe Client Credentials).

Administration durch den übergeordneten Tenant über CK-Methoden​

Ein Administrator eines übergeordneten Tenants sichert, stellt wieder her und exportiert oder importiert die Archivdaten eines untergeordneten Tenants über dieselben CK-Methoden, die der Administrator des untergeordneten Tenants verwendet, und verfolgt die Operationen über runtime.operations — genau das, was der REST-Jobs-Endpunkt {tenantId}/v1/jobs erlaubt. Die Regel spiegelt die REST-Regel und erlaubt nichts darüber hinaus:

Erlaubt mit einem Benutzer-Token des übergeordneten Tenants P auf Tenant C
MethodenNur System.Bot/TenantRepository.Dump-1, Restore-1, ExportArchiveData-1 und ImportArchiveData-1 (GraphQL runtime { systemBotTenantRepositorys { dump / restore / exportArchiveData / importArchiveData } }). Jede andere Methode auf C ist METHOD_FORBIDDEN mit reason = tenant-not-allowed.
Operationenruntime.operations auf C listet und liest nur die Operationen dieser vier Methoden: über das Handle (operationId) für den Aufrufer, der sie gestartet hat, mit allOwners: true die aller Aufrufer für einen Administrator (AdminPanelManagement) von P. Andere Operationen von C werden nicht gefunden.
Welche TenantsC muss ein registrierter direkter untergeordneter Tenant von P sein. Der System-Tenant erreicht jeden Tenant. Ein Tenant zwei Ebenen tiefer, ein Geschwister-Tenant, der übergeordnete Tenant des eigenen Tenants und ein gelöschter oder noch nicht registrierter Tenant werden abgelehnt.
RollenDie Rolle, die die Methoden deklarieren, TenantManagement, im übergeordneten Tenant (dieselbe Rolle, die der REST-Jobs-Endpunkt verlangt). Ohne sie: METHOD_FORBIDDEN mit reason = not-authorized, und es werden keine Operationen gelistet.
TokensNur Benutzer-Tokens. Ein Client-Credentials-Token von P wird auf C wie bisher abgelehnt; nur Clients auf TenantAuthorization:CrossTenantServiceClientIds sprechen andere Tenants an.
Tenant-GenerationDas tenant_gen des Tokens wird gegen den übergeordneten Tenant P geprüft. Ein Token von P, das ausgestellt wurde, bevor P gelöscht und neu angelegt wurde, wird wie auf P selbst abgelehnt.
HTTP-PrüfungEine Anfrage an /tenants/{C}/graphQl besteht die Routen-Tenant-Prüfung nur, wenn jedes Feld der Anfrage einer der Methodenaufrufe oben oder ein Lesezugriff auf runtime.operations ist: ein JSON-POST, kein Batch, keine Fragmente, kein Query-String. Eine Anfrage, die ein erlaubtes und ein anderes Feld mischt, wird als Ganzes abgelehnt. Senden Sie eine einfache Operation pro Anfrage.

Jeder erlaubte Aufruf wird auf Stufe Information mit Subjekt, Client, beiden Tenants und der Methode protokolliert. Die Datei eines Backups wird über den downloadPath des Operationsergebnisses heruntergeladen ({C}/v1/jobs/download?id=… des Bot-Dienstes), der das Token des übergeordneten Tenants aus demselben Grund akzeptiert.

Auch der Identity Service prüft den Routen-Tenant​

Der Identity Service führt dieselbe Routen-Tenant-Prüfung auch auf seiner eigenen Tenant-API (Benutzer, Rollen, Gruppen, Clients, Identity Provider und die übrigen /{tenantId}/...-Routen) für Bearer-Tokens aus. Frühere Versionen hielten ein Token eines anderen Tenants dort nur durch die Rollenanforderungen der einzelnen Endpunkte auf.

Was Integratoren ändern müssen: Ein Client, der die Identity-Service-API von Tenant B mit einem Token von Tenant A aufruft, erhält 403. Verwenden Sie ein Token des Tenants, den Sie ansprechen:

  • Benutzer und interaktive Anwendungen: im Ziel-Tenant anmelden (Login mit acr_values=tenant:<tenantId>) oder das aktuelle Token mit dem Token Exchange gegen eines des Ziel-Tenants tauschen.
  • Service-Clients: pro Tenant ein Token anfordern, jeweils mit acr_values=tenant:<tenantId>; der Client muss in diesem Tenant registriert sein (zum Beispiel durch Client-Spiegelung in untergeordnete Tenants).
  • Administratoren des übergeordneten Tenants, die Benutzer oder Clients eines untergeordneten Tenants verwalten, tun das mit einem Token des untergeordneten Tenants, nicht mit dem Token des übergeordneten.

Betreiber können diese Prüfung zuerst in einem reinen Protokollmodus betreiben, siehe Konfiguration.

Tenant-Generationen (tenant_gen)​

Eine Tenant-ID kann wiederverwendet werden: Wenn der Tenant my-project gelöscht und ein neuer Tenant my-project angelegt wird, passt ein Token des gelöschten Tenants bis zu seinem Ablauf noch zur tenant_id des neuen. Um die beiden zu unterscheiden, trägt jedes Access Token den Claim tenant_gen, die Generation seines Tenants: den Erstellungszeitpunkt des Tenants in Unix-Millisekunden als Dezimal-String (zum Beispiel "1794750381540"). ID-Tokens und die userinfo-Antwort tragen ihn nicht.

EreignisGenerationWirkung auf bestehende Tokens
Tenant anlegenneue Generation—
Backup über den bestehenden Tenant wiederherstellenbleibt erhaltenAccess Tokens bleiben gültig. Refresh Tokens und Codes sind die des Backups: Die nach dem Backup ausgestellten sind weg, und ihre Clients melden sich neu an (invalid_grant).
Tenant löschendie Generation endetRefresh Tokens, Authorization Codes und Device Codes des Tenants sind sofort weg (sie liegen in der Datenbank des Tenants). Access Tokens sind in sich geschlossen und bleiben bis zum Ablauf gültig, aber mit der Prüfung in Enforce weisen die Dienste sie ab, sobald der Tenant neu angelegt ist.
Löschen und mit derselben ID neu anlegenneue GenerationTokens des gelöschten Tenants werden vom neuen Tenant nie akzeptiert (mit der Prüfung in Enforce).
Löschen, neu anlegen und ein Backup des gelöschten Tenants wiederherstellendie neue Generation des AnlegensTokens, Refresh Tokens und Codes des gelöschten Tenants werden abgewiesen, auch solche, die die wiederhergestellten Daten zurückbringen (mit der Prüfung in Enforce).

Der System-Tenant wird von der Generationsprüfung nie abgewiesen. Tenants ohne gespeicherten Erstellungszeitpunkt (von älteren Plattformversionen angelegt) haben keine Generation und werden nicht geprüft.

Alte Backups in einen neu angelegten Tenant wiederherstellen

Betreiben Sie die Generationsprüfung in Enforce, bevor Sie ein Backup eines gelöschten Tenants in einen neuen Tenant mit derselben ID wiederherstellen. In LogOnly wird ein Refresh Token aus diesem Backup, das ausgestellt wurde, bevor der Identity Service Generationen gespeichert hat, beim nächsten Refresh akzeptiert und trägt danach die Generation des neuen Tenants.

Was die Prüfung abweist​

Mit der Prüfung in Enforce:

AufruferToken eines früheren Tenants oder Token ohne tenant_genGeneration kann nicht gelesen werden
Dienst-API (/{tenantId}/...)403 Forbidden mit einer JSON-Meldung503 Service Unavailable
CK-MethodenaufrufMETHOD_FORBIDDEN, Grund tenant-not-allowedMETHOD_HANDLER_FAILED
Token-Endpunkt des Identity Service: Refresh Token, Authorization Code, Device Code, Token Exchange, On-Behalf-Ofinvalid_grant (ein abgewiesenes Refresh Token wird nicht rotiert)server_error

In LogOnly (dem Standard) wird keine dieser Anfragen abgewiesen; jede wird in den Metriken der Tenant-Autorisierung gezählt, und ein Token eines früheren Tenants oder ohne tenant_gen wird als „would be denied" protokolliert (höchstens einmal pro Minute und Client; ein gescheitertes Lesen wird nur gezählt).

Tokens, die ausgestellt wurden, bevor der Identity Service tenant_gen gesetzt hat, tragen keine Generation. Sie werden in Enforce ebenfalls abgewiesen; deshalb schaltet eine Umgebung erst auf Enforce, wenn solche Tokens abgelaufen sind (siehe Empfohlene Einführung).

Was Clients tun müssen​

SituationWas zu tun ist
Interaktiver Benutzer (Refinery Studio, Anwendungen, octo-cli LogIn) erhält 403 oder invalid_grant, nachdem der Tenant neu angelegt wurdeNeu anmelden. Die neue Anmeldung stellt Tokens des neuen Tenants aus.
Der Refresh eines Clients scheitert mit invalid_grantDas gespeicherte Refresh Token verwerfen und die Anmeldung erneut durchführen.
Client-Credentials-Client erhält 403Ein neues Token anfordern (acr_values=tenant:<tenantId>). Wurde der Tenant neu angelegt, muss der Client zuerst im neuen Tenant existieren (neu registriert oder neu gespiegelt).
Langlaufender Dienst, der Tokens zwischenspeichertEin Token nicht über das Löschen eines Tenants hinaus behalten. Bei einem 403 für einen neu angelegten Tenant das zwischengespeicherte Token verwerfen und ein neues anfordern.

Konfiguration​

Betreiber einer selbst betriebenen Installation konfigurieren die Prüfungen pro Dienst über den Konfigurationsabschnitt TenantAuthorization (Präfix der Umgebungsvariablen OCTO_, doppelter Unterstrich zwischen den Ebenen).

KonfigurationsschlüsselUmgebungsvariableWerteStandardDienste
TenantAuthorization:TenantGenerationEnforcementOCTO_TENANTAUTHORIZATION__TENANTGENERATIONENFORCEMENTLogOnly, Enforce, DisabledLogOnlyJeder Dienst, der die Prüfung ausführt: Identity (seine API und seine Grants), Asset Repository, Bot, Communication Controller, Report Services, MCP Service, AI Services
TenantAuthorization:UserTokenEnforcementOCTO_TENANTAUTHORIZATION__USERTOKENENFORCEMENTLogOnly, EnforceEnforce in Identity, Report, MCP und AI Services; LogOnly in Asset Repository und Communication Controller. Das Chart octo-mesh rendert LogOnly für Identity, Asset Repository und Communication Controller, solange kein Wert gesetzt istRouten-Tenant-Prüfung von Benutzer-Tokens
TenantAuthorization:ServiceTokenEnforcementOCTO_TENANTAUTHORIZATION__SERVICETOKENENFORCEMENTLogOnly, Enforce, DisabledEnforce im Dienst; das Chart octo-mesh rendert LogOnly für Identity, solange kein Wert gesetzt istRouten-Tenant-Prüfung von Client-Credentials-Tokens
TenantAuthorization:CrossTenantServiceClientIdsOCTO_TENANTAUTHORIZATION__CROSSTENANTSERVICECLIENTIDS__0, __1, ...Client-IDs; ein abschließendes * passt auf ein PräfixleerService-Clients, die andere Tenants ansprechen dürfen

Die Modi:

  • LogOnly ändert kein Ergebnis. Eine Anfrage, die Enforce abweisen würde, wird als Warnung protokolliert, die den Client und die Tenants nennt (nie das Token); die Generationsprüfung protokolliert höchstens einmal pro Minute je Client und Ergebnis und zählt jede Prüfung in den Metriken der Tenant-Autorisierung.
  • Enforce weist diese Anfragen wie oben beschrieben ab.
  • Disabled (nur Generationsprüfung und Service-Tokens) schaltet die Prüfung ohne Protokoll und Metrik ab. Nur als Notausgang verwenden und danach zu LogOnly zurückkehren, weil es verbirgt, welche Clients betroffen wären.

Die Benutzer-Token-Modi von Asset Repository und Communication Controller (standardmäßig LogOnly) werden getrennt eingeschaltet, mit denselben Schritten wie unter Empfohlene Einführung.

Das Asset Repository schützt seine Datei-Routen (REST und GraphQL-Operationen auf System.Files) zusätzlich mit einem eigenen Schalter Files:TenantGuard (OCTO_Files__TenantGuard, Enforce oder LogOnly, Standard Enforce; ein unbekannter Wert zählt als Enforce). Er weist ein Benutzer-Token eines anderen Tenants auf diesen Routen auch dann ab, wenn UserTokenEnforcement auf LogOnly steht, ist von den Schaltern dieser Seite unabhängig und wird für sich gesetzt und beobachtet.

Setzen Sie die Generationsprüfung auf jedem Dienst einer Installation auf denselben Wert. Ein teilweises Umschalten ist nicht unsicher, aber der Schutz ist erst vollständig, wenn jeder Dienst durchsetzt.

Helm-Werte​

Im Chart octo-mesh:

tenantAuthorization:
tenantGenerationEnforcement: LogOnly # LogOnly | Enforce | Disabled, all services of the chart

services:
identity:
userTokenEnforcement: LogOnly # LogOnly | Enforce
serviceTokenEnforcement: LogOnly # LogOnly | Enforce | Disabled
# tenantGenerationEnforcement: Enforce # optional override for this service only
WertStandardRendert
tenantAuthorization.tenantGenerationEnforcementLogOnlyOCTO_TENANTAUTHORIZATION__TENANTGENERATIONENFORCEMENT auf Identity, Asset Repository, Bot, Communication Controller und AI Services
services.<service>.tenantGenerationEnforcement mit <service> = identity, assetRepository, bot, communication, aiServicesnicht gesetzt = der globale Wertdieselbe Variable nur auf diesem Dienst
services.identity.userTokenEnforcementLogOnlyOCTO_TENANTAUTHORIZATION__USERTOKENENFORCEMENT auf Identity
services.identity.serviceTokenEnforcementLogOnlyOCTO_TENANTAUTHORIZATION__SERVICETOKENENFORCEMENT auf Identity
services.assetRepository.userTokenEnforcement, services.communication.userTokenEnforcementLogOnlyOCTO_TENANTAUTHORIZATION__USERTOKENENFORCEMENT auf diesem Dienst

Die Charts octo-mesh-reporting, octo-mesh-mcp und octo-mesh-ai haben denselben Wert tenantAuthorization.tenantGenerationEnforcement (Standard LogOnly); setzen Sie ihn auf denselben Wert wie in octo-mesh. Jeder andere als die genannten Werte lässt das Rendern des Charts scheitern. Platform Services und Refinery Studio führen die Prüfungen nicht aus und erhalten keinen Wert.

Schalten Sie eine Umgebung nach der anderen um, Testumgebungen zuerst:

  1. LogOnly betreiben. Das Release des Identity Service, das tenant_gen setzt und seine Grants prüft, zusammen mit den Diensten, die die Generationsprüfung ausführen, ausrollen, alle in LogOnly.

  2. Ablauf alter Tokens abwarten. Tokens und Refresh Tokens, die vor diesem Identity-Service-Release ausgestellt wurden, tragen keine Generation und würden in Enforce abgewiesen. Warten Sie mindestens die längste Refresh-Token-Lebensdauer, die an einem Client konfiguriert ist (Standard 30 Tage), und mindestens die längste Access-Token-Lebensdauer, wenn sie größer ist. Statt auf die Refresh Tokens zu warten, können Sie in Kauf nehmen, dass Benutzer mit älteren Sitzungen sich neu anmelden müssen; die längste Access-Token-Lebensdauer muss in jedem Fall vergehen.

  3. Beobachten. Prüfen Sie die Protokolle mindestens einen Tag vor dem Umschalten auf „would be denied"-Zeilen:

    • This would be denied with TenantGenerationEnforcement=Enforce (Generationsprüfung, alle Dienste und der Token-Endpunkt),
    • This would be denied with UserTokenEnforcement=Enforce und This would be denied with ServiceTokenEnforcement=Enforce vom Identity Service (Routen-Tenant-Prüfung). Asset Repository und Communication Controller protokollieren dieselben Benutzer-Token-Zeilen, solange ihr eigenes userTokenEnforcement auf LogOnly steht; das ist ein eigener Schalter mit eigenen Werten.

    Jede Zeile nennt den Client. Eine Zeile für ein Token eines gelöschten und neu angelegten Tenants ist genau das, was Enforce abweisen muss. Jeder andere Client wird zuerst korrigiert: Er fordert seine Tokens mit acr_values=tenant:<tenantId> an, meldet sich neu an oder wird — nur wenn er wirklich tenantübergreifend arbeitet — in CrossTenantServiceClientIds aufgenommen. Die Metriken der Tenant-Autorisierung zeigen dieselben Ergebnisse pro Client, ohne Tenant- oder Benutzerdaten.

  4. Auf Enforce umschalten. services.identity.userTokenEnforcement und services.identity.serviceTokenEnforcement sowie tenantAuthorization.tenantGenerationEnforcement in octo-mesh und in den Charts für Reporting, MCP und AI setzen, dann die Deployments ausrollen. Direkt nach dem Ausrollen einen Smoke-Test durchführen: eine frische Anmeldung, eine GraphQL-Abfrage, ein CK-Methodenaufruf, ein Token-Refresh und ein Client-Credentials-Aufruf. Die Denied: ...-Protokollzeilen einen Tag lang beobachten.

  5. Zurückrollen. Die Werte auf LogOnly zurücksetzen und erneut ausrollen. Abgewiesene Anfragen funktionieren sofort wieder; es ändern sich keine Daten.

Fehlerbehebung​

403, nachdem ein Tenant gelöscht und neu angelegt oder neu angelegt und wiederhergestellt wurde​

Symptom: API-Aufrufe an den Tenant antworten mit 403 und der Meldung "Access is denied: the token was issued for an earlier tenant '...' that was deleted and created again, or before the tenant generation was issued. Sign in again.", obwohl der Benutzer oder Client die richtigen Rollen hat.

Ursache: Das Token wurde für den gelöschten Tenant mit derselben ID ausgestellt. Mit der Generationsprüfung in Enforce akzeptiert der neue Tenant es nie. Eine Wiederherstellung eines Backups in den neu angelegten Tenant ändert daran nichts: Der wiederhergestellte Tenant behält die Generation des Anlegens.

Lösung: neu anmelden (Benutzer) oder ein neues Token anfordern (Client-Credentials-Clients). Ein Client, der auch im neuen Tenant existieren muss, wird dort zuerst registriert oder gespiegelt.

invalid_grant beim Token-Refresh nach einer Wiederherstellung​

Symptom: Ein Token-Refresh, das Einlösen eines Authorization Codes oder Device Codes oder ein Token Exchange scheitert mit invalid_grant, nachdem der Tenant gelöscht, neu angelegt und aus einem Backup wiederhergestellt wurde.

Ursache: Das Refresh Token oder der Code gehört zum früheren Tenant. Die Wiederherstellung bringt die gespeicherten Grants des Backups zurück, aber der Identity Service weist Grants ab, deren Tenant-Generation nicht zum aktuellen Tenant passt.

Lösung: Das Refresh Token verwerfen und neu anmelden. Eine Wiederherstellung über den bestehenden Tenant (ohne Löschen) behält die Generation, sodass die Refresh Tokens des Backups gültig bleiben; ein Refresh Token, das nach dem Backup ausgestellt wurde, ist in der wiederhergestellten Datenbank nicht enthalten und scheitert aus diesem Grund ebenfalls mit invalid_grant.

403 auf der Identity-Service-API mit einem Token eines anderen Tenants​

Symptom: Aufrufe von /{tenantId}/...-Endpunkten des Identity Service antworten mit 403, und die Meldung nennt den Tenant des Tokens und den Routen-Tenant.

Lösung: ein Token des Routen-Tenants verwenden: in diesem Tenant anmelden, den Token Exchange verwenden oder (Service-Clients) das Token mit acr_values=tenant:<tenantId> anfordern. Siehe Auch der Identity Service prüft den Routen-Tenant.

503 von einem Dienst mit der Generationsprüfung in Enforce​

Symptom: Die Meldung lautet "The tenant of the token cannot be verified right now. Try again later."

Ursache: Der Dienst konnte die Generation des Tenants nicht aus der Systemdatenbank lesen. In Enforce antwortet er mit 503, statt das Token ungeprüft zu akzeptieren. Die Anfrage gelingt wieder, sobald die Datenbank erreichbar ist; prüfen Sie die Verbindung zwischen dem Dienst und MongoDB.

Siehe auch​