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üfung | Frage | Wo sie läuft |
|---|---|---|
| Routen-Tenant | Wurde 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-Generation | Wurde 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:CrossTenantServiceClientIdssteht, 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 | |
|---|---|
| Methoden | Nur 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. |
| Operationen | runtime.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 Tenants | C 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. |
| Rollen | Die 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. |
| Tokens | Nur Benutzer-Tokens. Ein Client-Credentials-Token von P wird auf C wie bisher abgelehnt; nur Clients auf TenantAuthorization:CrossTenantServiceClientIds sprechen andere Tenants an. |
| Tenant-Generation | Das 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üfung | Eine 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.
| Ereignis | Generation | Wirkung auf bestehende Tokens |
|---|---|---|
| Tenant anlegen | neue Generation | — |
| Backup über den bestehenden Tenant wiederherstellen | bleibt erhalten | Access 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öschen | die Generation endet | Refresh 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 anlegen | neue Generation | Tokens 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 wiederherstellen | die neue Generation des Anlegens | Tokens, 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.
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:
| Aufrufer | Token eines früheren Tenants oder Token ohne tenant_gen | Generation kann nicht gelesen werden |
|---|---|---|
Dienst-API (/{tenantId}/...) | 403 Forbidden mit einer JSON-Meldung | 503 Service Unavailable |
| CK-Methodenaufruf | METHOD_FORBIDDEN, Grund tenant-not-allowed | METHOD_HANDLER_FAILED |
| Token-Endpunkt des Identity Service: Refresh Token, Authorization Code, Device Code, Token Exchange, On-Behalf-Of | invalid_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
| Situation | Was zu tun ist |
|---|---|
Interaktiver Benutzer (Refinery Studio, Anwendungen, octo-cli LogIn) erhält 403 oder invalid_grant, nachdem der Tenant neu angelegt wurde | Neu anmelden. Die neue Anmeldung stellt Tokens des neuen Tenants aus. |
Der Refresh eines Clients scheitert mit invalid_grant | Das gespeicherte Refresh Token verwerfen und die Anmeldung erneut durchführen. |
| Client-Credentials-Client erhält 403 | Ein 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 zwischenspeichert | Ein 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üssel | Umgebungsvariable | Werte | Standard | Dienste |
|---|---|---|---|---|
TenantAuthorization:TenantGenerationEnforcement | OCTO_TENANTAUTHORIZATION__TENANTGENERATIONENFORCEMENT | LogOnly, Enforce, Disabled | LogOnly | Jeder 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:UserTokenEnforcement | OCTO_TENANTAUTHORIZATION__USERTOKENENFORCEMENT | LogOnly, Enforce | Enforce 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 ist | Routen-Tenant-Prüfung von Benutzer-Tokens |
TenantAuthorization:ServiceTokenEnforcement | OCTO_TENANTAUTHORIZATION__SERVICETOKENENFORCEMENT | LogOnly, Enforce, Disabled | Enforce im Dienst; das Chart octo-mesh rendert LogOnly für Identity, solange kein Wert gesetzt ist | Routen-Tenant-Prüfung von Client-Credentials-Tokens |
TenantAuthorization:CrossTenantServiceClientIds | OCTO_TENANTAUTHORIZATION__CROSSTENANTSERVICECLIENTIDS__0, __1, ... | Client-IDs; ein abschließendes * passt auf ein Präfix | leer | Service-Clients, die andere Tenants ansprechen dürfen |
Die Modi:
LogOnlyändert kein Ergebnis. Eine Anfrage, dieEnforceabweisen 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.Enforceweist 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 zuLogOnlyzurü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
| Wert | Standard | Rendert |
|---|---|---|
tenantAuthorization.tenantGenerationEnforcement | LogOnly | OCTO_TENANTAUTHORIZATION__TENANTGENERATIONENFORCEMENT auf Identity, Asset Repository, Bot, Communication Controller und AI Services |
services.<service>.tenantGenerationEnforcement mit <service> = identity, assetRepository, bot, communication, aiServices | nicht gesetzt = der globale Wert | dieselbe Variable nur auf diesem Dienst |
services.identity.userTokenEnforcement | LogOnly | OCTO_TENANTAUTHORIZATION__USERTOKENENFORCEMENT auf Identity |
services.identity.serviceTokenEnforcement | LogOnly | OCTO_TENANTAUTHORIZATION__SERVICETOKENENFORCEMENT auf Identity |
services.assetRepository.userTokenEnforcement, services.communication.userTokenEnforcement | LogOnly | OCTO_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.
Empfohlene Einführung
Schalten Sie eine Umgebung nach der anderen um, Testumgebungen zuerst:
-
LogOnlybetreiben. Das Release des Identity Service, dastenant_gensetzt und seine Grants prüft, zusammen mit den Diensten, die die Generationsprüfung ausführen, ausrollen, alle inLogOnly. -
Ablauf alter Tokens abwarten. Tokens und Refresh Tokens, die vor diesem Identity-Service-Release ausgestellt wurden, tragen keine Generation und würden in
Enforceabgewiesen. 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. -
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=EnforceundThis would be denied with ServiceTokenEnforcement=Enforcevom Identity Service (Routen-Tenant-Prüfung). Asset Repository und Communication Controller protokollieren dieselben Benutzer-Token-Zeilen, solange ihr eigenesuserTokenEnforcementaufLogOnlysteht; 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
Enforceabweisen muss. Jeder andere Client wird zuerst korrigiert: Er fordert seine Tokens mitacr_values=tenant:<tenantId>an, meldet sich neu an oder wird — nur wenn er wirklich tenantübergreifend arbeitet — inCrossTenantServiceClientIdsaufgenommen. Die Metriken der Tenant-Autorisierung zeigen dieselben Ergebnisse pro Client, ohne Tenant- oder Benutzerdaten. -
Auf
Enforceumschalten.services.identity.userTokenEnforcementundservices.identity.serviceTokenEnforcementsowietenantAuthorization.tenantGenerationEnforcementinocto-meshund 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. DieDenied: ...-Protokollzeilen einen Tag lang beobachten. -
Zurückrollen. Die Werte auf
LogOnlyzurü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
- Authentifizierung — Flows, Tokens und Claims
- Tenant-Lebenszyklus — Tenants anlegen, wiederherstellen und löschen
- Tenantübergreifende Authentifizierung — Benutzer eines Tenants in einem anderen Tenant