Tenantübergreifende Authentifizierung

OctoMesh unterstützt ein hierarchisches Tenant-Modell, bei dem ein übergeordneter Tenant Benutzer in untergeordneten Tenants authentifizieren kann. Dies ermöglicht es Organisationen, ein einziges Benutzerverzeichnis zu pflegen und gleichzeitig Zugriff auf mehrere isolierte Tenants zu gewähren.

Funktionsweise

Parent Tenant (e.g., "octosystem")
├── User: alice (local user)
├── User: bob (local user)
│
└── Child Tenant (e.g., "customer-project")
    ├── OctoTenantIdentityProvider → points to "octosystem"
    ├── ExternalTenantUserMapping: alice → roles: [Development, DashboardViewer]
    └── ExternalTenantUserMapping: bob → roles: [TenantManagement]

1. alice meldet sich bei customer-project mit ihren octosystem-Anmeldedaten an
2. Der Identity Service findet den OctoTenantIdentityProvider, der auf octosystem verweist
3. Er validiert alices Anmeldedaten gegen den übergeordneten Tenant
4. Er findet ein ExternalTenantUserMapping für alice, das ihr die Rollen Development und DashboardViewer gewährt
5. Ein JWT-Token wird ausgestellt mit tenant_id: customer-project, home_tenant_id: octosystem und den zugeordneten Rollen

Zwei Dinge sind erforderlich, damit die tenantübergreifende Authentifizierung funktioniert:

• Ein OctoTenantIdentityProvider im untergeordneten Tenant, der auf den übergeordneten verweist (wird automatisch erstellt, wenn der untergeordnete Tenant erstellt wird)
• Ein ExternalTenantUserMapping für jeden Benutzer, der Zugriff haben soll (erstellt über Admin-Provisionierung oder manuell)

Zugriff auf einen untergeordneten Tenant gewähren

Dies ist das häufigste Szenario: Sie sind im übergeordneten Tenant (z. B. octosystem) angemeldet und möchten sich selbst oder einem anderen Benutzer Zugriff auf einen untergeordneten Tenant (z. B. meshtest) gewähren. Sie benötigen dazu keinen Zugriff auf den untergeordneten Tenant.

Schnellstart: Sich selbst Zugriff gewähren

# 1. Log into the parent (system) tenant
octo-cli -c Config -tid "octosystem"
octo-cli -c LogIn -i

# 2. Provision yourself in the child tenant (grants all roles + TenantOwners group)
octo-cli -c ProvisionCurrentUser -ttid "meshtest"

# 3. Log into the child tenant (token now includes meshtest in allowed_tenants)
octo-cli -c Config -tid "meshtest"
octo-cli -c LogIn -i

Das war's. Sie haben nun vollen Zugriff auf meshtest.

Was ProvisionCurrentUser tut

1. Erstellt ein ExternalTenantUserMapping mit allen verfügbaren Rollen im Ziel-Tenant
2. Fügt die Zuordnung der TenantOwners-Gruppe hinzu (gewährt alle Standardrollen über Gruppenvererbung)
3. Wenn der Ziel-Tenant noch initialisiert (CK-Modell nicht geladen), wird automatisch erneut versucht

Einem bestimmten Benutzer Zugriff gewähren

Um einen anderen Benutzer mit ausgewählten Rollen zu provisionieren:

# Still logged into the system tenant
octo-cli -c CreateAdminProvisioningMapping \
  -ttid "meshtest" \
  -stid "octosystem" \
  -suid "<user-id>" \
  -sun "alice" \
  -rids "Development,DashboardViewer"

Der Benutzer muss sich ab- und wieder anmelden, um den aktualisierten allowed_tenants-Claim zu erhalten.

Provisionierte Benutzer auflisten und löschen

# List all provisioned users in target tenant
octo-cli -c GetAdminProvisioningMappings -ttid "meshtest"

# Delete a provisioning
octo-cli -c DeleteAdminProvisioningMapping -ttid "meshtest" -mid "<mapping-rtid>"

Vollständiger Workflow: Neuer Tenant von Grund auf

# 1. Log into the system tenant
octo-cli -c Config -tid "octosystem"
octo-cli -c LogIn -i

# 2. Create the child tenant
octo-cli -c Create -tid "new-project" -db "new_project_db"

# 3. Provision yourself (no access to child tenant needed)
octo-cli -c ProvisionCurrentUser -ttid "new-project"

# 4. Log into the new tenant
octo-cli -c Config -tid "new-project"
octo-cli -c LogIn -i

# 5. Optionally provision other users
octo-cli -c CreateAdminProvisioningMapping \
  -ttid "new-project" \
  -stid "octosystem" \
  -suid "<bob-user-id>" \
  -sun "bob" \
  -rids "DashboardViewer,ReportingViewer"

info

Wenn ein neuer untergeordneter Tenant erstellt wird, wird automatisch ein OctoTenantIdentityProvider erstellt, der auf den übergeordneten verweist. Sie müssen ihn nicht manuell erstellen.

hinweis

Bis mindestens ein Benutzer in einem untergeordneten Tenant provisioniert ist, zeigt die Login-Seite „This tenant is not available. Please contact your administrator." an — das Login-Formular wird nicht angezeigt.

Wichtige Konzepte

OctoTenant Identity Provider

Ein OctoTenant Identity Provider delegiert die Authentifizierung an einen übergeordneten Tenant. Wenn ein Benutzer versucht, sich anzumelden, und kein lokaler Benutzer gefunden wird, läuft der Identity Service die Tenant-Hierarchie (über OctoTenantIdentityProviders) nach oben, um den Benutzer zu finden und zu authentifizieren.

• Die Hierarchie unterstützt bis zu 10 Ebenen Tiefe
• Die Zykluserkennung verhindert Endlosschleifen
• Der Provider kann mit AllowSelfRegistration und DefaultGroupRtId konfiguriert werden

External Tenant User Mappings

Ein External Tenant User Mapping verknüpft einen Benutzer aus einem übergeordneten Tenant mit einer Menge von Rollen (und optional Gruppen) im untergeordneten Tenant. Ohne eine Zuordnung hat ein authentifizierter tenantübergreifender Benutzer keine Rollen im untergeordneten Tenant.

Jede Zuordnung enthält:

Eigenschaft	Beschreibung
SourceTenantId	Der übergeordnete Tenant, aus dem der Benutzer stammt
SourceUserId	Die ID des Benutzers im übergeordneten Tenant
SourceUserName	Der Name des Benutzers im übergeordneten Tenant
RoleIds	Im untergeordneten Tenant zugewiesene Rollen
GroupNames	Gruppen, denen der Benutzer im untergeordneten Tenant angehört

Präfix für tenantübergreifende Benutzer

Wenn sich ein tenantübergreifender Benutzer zum ersten Mal anmeldet, erstellt der Identity Service einen lokalen Benutzerdatensatz im untergeordneten Tenant mit dem Präfix xt_{parentTenantId}_{username}. Dieser lokale Datensatz ist mit dem External Tenant User Mapping verknüpft.

Zuordnungen im untergeordneten Tenant verwalten

Sobald Sie Zugriff auf den untergeordneten Tenant haben, können Sie Benutzerzuordnungen auch direkt innerhalb dieses Tenants verwalten. Dies gibt Ihnen eine feinkörnigere Kontrolle als die Admin-Provisionierung.

Eine Zuordnung erstellen

# Switch to the child tenant context
octo-cli -c Config -tid "customer-project"
octo-cli -c LogIn -i

# Create a mapping for a parent tenant user
octo-cli -c CreateExternalTenantUserMapping \
  -stid "octosystem" \
  -suid "<user-id-from-parent>" \
  -sun "alice" \
  -rids "Development,DashboardViewer"

Zuordnungen auflisten und löschen

# List all mappings
octo-cli -c GetExternalTenantUserMappings

# Filter by source tenant
octo-cli -c GetExternalTenantUserMappings -stid "octosystem"

# Delete a mapping
octo-cli -c DeleteExternalTenantUserMapping -id "<mapping-rtid>"

Einen OctoTenant Identity Provider manuell erstellen

Dies ist nur notwendig, wenn Sie einen untergeordneten Tenant auf einen anderen übergeordneten Tenant verweisen müssen als den, aus dem er erstellt wurde, oder wenn der Provider gelöscht wurde:

octo-cli -c AddOctoTenantIdentityProvider \
  -n "Parent Tenant" \
  -ptid "octosystem" \
  -e true

Nicht-interaktiver Tenant-Wechsel (Token Exchange)

Browser-Sitzungen wechseln Tenants über die Endpunkte für den tenantübergreifenden Auto-Login. Nicht-Browser-Clients — allen voran die MCP Services (switch_tenant-Tool) — verwenden stattdessen RFC 8693 Token Exchange: Ein gültiges Access Token aus dem aktuellen Tenant des Benutzers wird an /connect/token gegen ein Access Token des Ziel-Tenants eingetauscht.

Der Austausch setzt dieselben Regeln durch wie ein interaktiver tenantübergreifender Login:

1. Das Subject Token muss gültig sein und einen Benutzerkontext tragen
2. Der Benutzer muss tenantübergreifenden Zugriff auf den Ziel-Tenant haben (validiert gegen die Tenant-Hierarchie und das ExternalTenantUserMapping des Ziel-Tenants); für einen Benutzer, der selbst ein tenantübergreifender Shadow-User (xt_…) ist, läuft die Prüfung von seinem Home-Tenant aus — dem gemeinsamen Ancestor — sodass der Wechsel zwischen Geschwister-Tenants funktioniert
3. Der Shadow-User wird im Ziel-Tenant gefunden oder erstellt, und Rollen werden dort neu aufgelöst — das ausgestellte Token trägt die tenant_id des Ziel-Tenants und im Ziel aufgelöste Rollen, niemals die Rollen des Quell-Tenants

Abgelehnte Austausche schlagen mit unauthorized_client fehl und werden in das Audit-Event-Log geschrieben. Für eingetauschte Tokens wird kein Refresh Token ausgestellt; Clients tauschen erneut aus dem noch gültigen Original-Token.

Auflösung der erlaubten Tenants

Zum Zeitpunkt der Token-Ausstellung löst der Identity Service auf, auf welche Tenants ein Benutzer zugreifen darf. Der Algorithmus hat vier Phasen:

1. Login-Tenant — immer enthalten
2. Home-Tenant — für tenantübergreifende Benutzer (Benutzername beginnt mit xt_) wird ihr übergeordneter Tenant extrahiert und einbezogen
3. Ancestor-Tenants — läuft die Tenant-Hierarchie nach oben, indem den OctoTenantIdentityProvider-Elternreferenzen gefolgt wird (bis zu 10 Ebenen, mit Zykluserkennung)
4. Descendant-Tenants — BFS-Traversierung nach unten durch untergeordnete Tenants, wobei nach ExternalTenantUserMapping-Einträgen gesucht wird, die dem Benutzer entsprechen. Dies kaskadiert über mehrere Ebenen (z. B. octosystem → customer-project → sub-project)

Die resultierende Liste wird als allowed_tenants-Claims in das JWT-Access-Token ausgegeben. Dienste validieren diese Claims, um den Tenant-Zugriff zu autorisieren.

Beispiel

octosystem (parent)
├── customer-project (child)
│   └── sub-project (grandchild)

Wenn der Benutzer alice aus octosystem ein ExternalTenantUserMapping in customer-project hat und ihre tenantübergreifende Identität xt_octosystem_alice eine Zuordnung in sub-project hat, wird ihr allowed_tenants alle drei Tenants enthalten.