Authentifizierung

OctoMesh verwendet OAuth 2.0 und OpenID Connect (OIDC) für die Authentifizierung. Diese Seite erklärt, wie die Authentifizierung funktioniert, welche Flows unterstützt werden und was während des Anmeldevorgangs geschieht.

Überblick

Unterstützte Flows

Authorization Code mit PKCE

Verwendet von Webanwendungen wie Data Refinery Studio. Der Browser leitet auf die Login-Seite des Identity Service weiter, der Benutzer authentifiziert sich, und der Browser erhält einen Authorization Code, der gegen Tokens eingetauscht wird.

• PKCE (Proof Key for Code Exchange) ist erforderlich — verhindert das Abfangen des Authorization Code
• Für öffentliche Clients (SPAs) wird kein Client Secret benötigt
• Unterstützt offline_access für Refresh Tokens

Device Code

Verwendet von octo-cli und anderen Geräten ohne Browser. Die CLI zeigt eine URL und einen Code an, der Benutzer öffnet die URL in einem beliebigen Browser, gibt den Code ein und authentifiziert sich.

• Die CLI fragt /connect/token per Polling ab, bis der Benutzer die Authentifizierung abgeschlossen hat
• Unterstützt offline_access für langlebige Sitzungen

Client Credentials

Verwendet für die Dienst-zu-Dienst-Kommunikation, an der kein Benutzer beteiligt ist. Der Client authentifiziert sich mit seinen eigenen Anmeldedaten (Client-ID + Secret) und erhält ein Access Token.

• Die Token-Anfrage muss acr_values=tenant:{tenantId} mitführen. Clients werden pro Tenant gespeichert, und /connect/token hat kein Tenant-Pfadsegment — acr_values ist die einzige Möglichkeit, dem Identity Service mitzuteilen, in welchem Client-Speicher welches Tenants gesucht werden soll. Ohne dies fällt die Suche auf den System-Tenant zurück, sodass ein tenantregistrierter Client mit invalid_client fehlschlägt. (Nur Clients, die tatsächlich im System-Tenant leben, dürfen es weglassen.)
• Kein Benutzerkontext — das Token hat keinen sub-Claim und auch keine tenant_id- / allowed_tenants-Claims. Die Tenant-Bindung des Clients wird allein dadurch hergestellt, welches Tenants Client zum Zeitpunkt der Token-Ausstellung gematcht hat.
• Client-Credentials-Tokens umgehen die routenbasierte Tenant-Autorisierungsprüfung in nachgelagerten Diensten (siehe Tenant-Autorisierung) — der Token-Endpunkt selbst ist jedoch wie oben beschrieben tenantbezogen.
• Wenn dem Client Rollen zugewiesen wurden (direkt oder über Gruppenmitgliedschaft), trägt das Token die aufgelösten role-Claims — in derselben Form wie ein Benutzer-Token — sodass der Client rollengeschützte Endpunkte aufrufen kann. Rollen werden in dem über acr_values gewählten Tenant aufgelöst. Siehe Client-Rollen und Gruppenmitgliedschaft.
• Verwendet für Hintergrundjobs, dienstübergreifende Aufrufe und automatisierte Prozesse

Token Exchange (RFC 8693) — tenantübergreifender Wechsel

Verwendet von den MCP Services, um den operativen Tenant einer Sitzung ohne eine neue Browser-Anmeldung zu wechseln. Jedes Access Token ist an genau einen operativen Tenant gebunden (tenant_id-Claim); Dienste setzen dies strikt durch. Anstatt sich erneut zu authentifizieren, wird ein bereits gültiges Access Token aus dem aktuellen Tenant des Benutzers gegen ein Token des Ziel-Tenants eingetauscht:

• Der Austausch wird nur gewährt, wenn der Benutzer tenantübergreifenden Zugriff auf den Ziel-Tenant hat (ein ExternalTenantUserMapping; siehe Tenantübergreifende Authentifizierung)
• Das ausgestellte Token läuft unter dem Shadow-User (xt_…) des Ziel-Tenants, sodass Rollen im Ziel-Tenant neu aufgelöst werden — Rollen aus dem Quell-Tenant gelangen niemals hinüber
• Für eingetauschte Tokens wird kein Refresh Token ausgestellt; der Client tauscht bei Bedarf erneut aus dem noch gültigen Original-Token
• Nur Clients mit dem Token-Exchange-Grant dürfen ihn aufrufen (der octo-mcpServices-device-Client)

Delegation / On-Behalf-Of

Ein Service-Account-Client (Maschine-zu-Maschine) kann ein Access Token erhalten, das unter der Identität eines Benutzers läuft, sodass die im Namen dieses Benutzers ausgeführte Arbeit dem Benutzer zurechenbar ist und durch das begrenzt wird, was beide Parteien dürfen. Dies ist keine Impersonation: Das Service Account kann niemals seine eigene Autorität überschreiten.

• Das ausgestellte Token trägt role = serviceAccountRoles ∩ userRoles — ein breit privilegiertes Service Account, das für einen Benutzer mit geringen Rechten handelt, erhält die enge Menge des Benutzers, und umgekehrt. Über Gruppen geerbte Rollen zählen auf beiden Seiten. Eine leere Schnittmenge ist ein erfolgreicher Grant: Das Token trägt keinen role-Claim, und jeder rollengesteuerte Konsument schlägt fail-closed fehl.
• Der act-Claim nennt die client_id des Service Accounts, sodass Dienste und der Audit-Trail ein delegiertes Token von einem unterscheiden können, das der Benutzer selbst erhalten hat.
• Nur derselbe Tenant: Der Tenant in acr_values, die tenant_id des Subject Token und der Anfrage-Tenant müssen übereinstimmen; tenantübergreifende Identitätsbewegung nutzt den obigen Token-Exchange-Grant.
• Keine Refresh Tokens — die Anforderung von offline_access wird mit invalid_scope abgelehnt. Die Rollen- Schnittmenge wird zum Zeitpunkt der Ausstellung berechnet; ein Refresh würde sie einfrieren, sodass eine auf einer der beiden Seiten widerrufene Rolle weiter funktionieren würde. Delegierte Tokens werden aus dem noch gültigen Benutzer-Token neu ausgestellt.
• Nur Clients, die die Grant-URN in ihren AllowedGrantTypes aufführen, dürfen ihn aufrufen.

Der Hauptkonsument dieses Grants ist die Pipeline-Identität: eine Pipeline, die im Namen des aufrufenden Benutzers läuft.

Dynamic Client Registration (RFC 7591)

Interaktive MCP-Clients (Claude Code, Claude Desktop) verwenden keine vorkonfigurierte client_id — sie registrieren sich selbst am registration_endpoint des Identity Service (POST /connect/register), bevor sie den Authorization Code + PKCE Flow starten.

• Registrierte Clients heißen octo-dcr-* und sind stark eingeschränkt: Redirect-URIs nur auf Loopback, PKCE erforderlich, öffentlicher Client (kein Secret), servergebundene Scopes, begrenzte Lebensdauer, Rate-Limit pro IP und Obergrenze pro Tenant
• Die Registrierung allein gewährt nichts — für ein Token ist weiterhin eine echte Benutzeranmeldung erforderlich
• Standardmäßig aktiviert; pro Deployment mit OCTO_IDENTITY__DYNAMICCLIENTREGISTRATION__ENABLED=false deaktivierbar
• Da die Registrierung tenantunabhängig ist, läuft die anschließende Anmeldung über die Tenant-Discovery (E-Mail-basierte Tenant-Auswahl); der registrierte Client wird automatisch in alle Tenants gespiegelt

Mandantenfähige Authentifizierung

Die Authentifizierung in OctoMesh ist immer auf einen Tenant beschränkt. Die Tenant-ID bestimmt, welche Benutzerdatenbank, Identity Provider und Rollen verwendet werden.

Tenant-Auflösung

Verschiedene Endpunkte lösen den Tenant unterschiedlich auf:

Endpunkt	Tenant-Quelle
REST-API (/{tenantId}/v1/...)	URL-Pfadsegment
/connect/authorize	Query-Parameter acr_values=tenant:{tenantId}
/connect/token (authorization_code, device_code, refresh_token)	Aus dem Authorization Code, Device Code oder Refresh Token zugeordnet
/connect/token (client_credentials, Token Exchange)	Formularparameter acr_values=tenant:{tenantId} — erforderlich; ohne ihn fällt die Client-Suche auf den System-Tenant zurück
/connect/endsession	Aus dem id_token_hint-JWT dekodiert

Cookie-Isolation pro Tenant

Der Identity Service begrenzt Authentifizierungs-Cookies pro Tenant, indem er die Tenant-ID an die Cookie-Namen anhängt:

Standard-Cookie	Tenant-bezogenes Cookie
.AspNetCore.Identity.Application	.AspNetCore.Identity.Application.{tenantId}
idsrv	idsrv.{tenantId}
idsrv.session	idsrv.session.{tenantId}

Dies verhindert das Durchsickern von Sitzungen zwischen Tenants, wenn ein Benutzer in mehreren Tenants im selben Browser Sitzungen hat.

Identity-Provider-Schemata pro Tenant

Externe Identity-Provider-Schemata werden mit einem Tenant-Präfix registriert, um Konflikte zu vermeiden:

{tenantId}:{providerName}

Examples:
  octosystem:Google
  customer-project:AzureAD

Jeder Tenant konfiguriert unabhängig, welche Provider verfügbar sind und deren Anmeldedaten. Provider werden zur Laufzeit dynamisch registriert — das Hinzufügen oder Aktualisieren eines Providers wird sofort wirksam, ohne den Dienst neu zu starten.

Tenantbezogene Authentifizierung für externe Clients

Externe Anwendungen (Datasource-Plugins, Drittanbieter-Integrationen, benutzerdefinierte Web-Apps), die Benutzer gegen einen bestimmten Tenant authentifizieren müssen, müssen den Parameter acr_values in die OAuth-Authorize-Anfrage aufnehmen. Der Parameter acr_values ist in der OpenID Connect Core Specification (Abschnitt 3.1.2.1) definiert und ist der Standardmechanismus zur Anforderung bestimmter Authentifizierungskontexte.

Authorize-Anfrage mit Tenant-Auswahl:

GET /connect/authorize?
    response_type=code
    &client_id=my-application
    &redirect_uri=https://my-app.example.com/callback
    &scope=openid profile email role octo_api
    &acr_values=tenant:customer-project
    &code_challenge=...
    &code_challenge_method=S256
    &state=...

Was geschieht:

Der Identity Service:

1. Parst tenant:customer-project aus dem Parameter acr_values
2. Leitet den Benutzer auf die Login-Seite des Tenants weiter (/customer-project/login)
3. Der Benutzer sieht nur die für diesen Tenant konfigurierten Authentifizierungsmethoden
4. Nach der Authentifizierung trägt das ausgestellte Token tenant_id: customer-project mit Rollen und Scopes aus diesem Tenant

Gleichzeitige mandantenübergreifende Sitzungen: Da Cookies pro Tenant begrenzt sind, kann sich ein Benutzer im selben Browser bei mehreren Tenants authentifizieren. Der Wechsel zwischen Tenants nach der ersten Anmeldung erfolgt nahtlos — das vorhandene Tenant-Cookie ermöglicht SSO, ohne die Anmeldedaten erneut einzugeben.

Client-Registrierung: Der OAuth-Client muss in jedem Tenant registriert sein, in dem sich Benutzer authentifizieren müssen. Details siehe Clients und API-Scopes.

Struktur des Access Token

Wenn die Authentifizierung erfolgreich ist, stellt der Identity Service ein JWT-Access-Token aus, das Folgendes enthält:

Standard-Claims

Claim	Beschreibung	Beispiel
sub	Benutzer-ID	"a1b2c3d4"
preferred_username	Benutzername	"john.doe"
name	Anzeigename	"John Doe"
email	E-Mail-Adresse	"john@example.com"
given_name	Vorname	"John"
family_name	Nachname	"Doe"

OctoMesh-spezifische Claims

Claim	Beschreibung	Beispiel
tenant_id	Tenant, in den sich der Benutzer angemeldet hat	"customer-project"
allowed_tenants	Tenants, auf die der Benutzer zugreifen darf (wiederholter Claim)	"customer-project", "octosystem"
role	Effektive Rollen (direkt + über Gruppen geerbt, wiederholter Claim)	"Development", "DashboardViewer"
home_tenant_id	Für tenantübergreifende Benutzer: ihr übergeordneter Tenant	"octosystem"

Effektive Rollen

Die role-Claims umfassen die Vereinigung von:

• Rollen, die dem Benutzer direkt zugewiesen sind
• Rollen, die über Gruppenmitgliedschaft geerbt werden (rekursiv bis zu 10 Ebenen der Verschachtelung aufgelöst)

Rollen werden zum Zeitpunkt der Token-Ausstellung aufgelöst und beim Token-Refresh aktualisiert. Dieselbe Auflösung gilt für Clients, die sich über client_credentials authentifizieren — ihre direkt zugewiesenen und über Gruppen geerbten Rollen werden als identische role-Claims ausgegeben.

Erlaubte Tenants

Die allowed_tenants-Claims werden aufgelöst aus:

1. Dem Login-Tenant — immer enthalten
2. Dem Home-Tenant — für tenantübergreifende Benutzer ihr übergeordneter Tenant
3. Ancestor-Tenants — läuft die Tenant-Hierarchie über OctoTenantIdentityProvider-Elternreferenzen nach oben (bis zu 10 Ebenen)
4. Descendant-Tenants — BFS-Traversierung nach unten durch untergeordnete Tenants, in denen für diesen Benutzer ein ExternalTenantUserMapping existiert (kaskadiert über mehrere Ebenen)

Token-Validierung durch Dienste

Alle OctoMesh-Dienste validieren eingehende Anfragen nach demselben Muster:

Bearer-Token-Authentifizierung

Dienste validieren JWT-Tokens gegen die Signaturschlüssel des Identity Service. Das Token muss:

• Ein gültiges, vom Identity Service signiertes JWT sein
• Nicht abgelaufen sein
• Die erforderlichen Scopes für die angeforderte Operation enthalten

Tenant-Autorisierung

Nach der Standard-JWT-Validierung setzt die TenantAuthorizationMiddleware den Tenant-Zugriff durch:

1. Extrahiere {tenantId} aus dem Pfad der Anfrage-URL
2. Lies die allowed_tenants-Claims aus dem validierten Token
3. Wenn der Routen-Tenant nicht in der erlaubten Liste ist → 403 Forbidden
4. Client-Credentials-Tokens (ohne sub-Claim) umgehen diese Prüfung

Request: GET /customer-project/v1/runtime/entities

Token claims:
  sub: "a1b2c3d4"
  allowed_tenants: ["customer-project", "octosystem"]

→ "customer-project" is in allowed_tenants → Access granted

Request: GET /other-tenant/v1/runtime/entities

Token claims:
  sub: "a1b2c3d4"
  allowed_tenants: ["customer-project", "octosystem"]

→ "other-tenant" is NOT in allowed_tenants → 403 Forbidden

Authentifizierungs-Flow: Schritt für Schritt

Dieser Abschnitt verfolgt einen vollständigen Authentifizierungs-Flow für eine browserbasierte Anwendung.

1. Benutzer öffnet die Anwendung

Die Client-Anwendung (z. B. Data Refinery Studio) erkennt keine gültige Sitzung und leitet auf den Identity Service weiter:

GET /connect/authorize?
  client_id=octo-data-refinery-studio
  &response_type=code
  &scope=openid profile email role octo_api
  &redirect_uri=https://studio.example.com/callback
  &code_challenge=...
  &code_challenge_method=S256
  &acr_values=tenant:customer-project

2. Identity Service präsentiert die Login-Seite

Der Identity Service rendert die Login-Seite für den Tenant customer-project und zeigt die verfügbaren Identity Provider an (z. B. „Corporate Azure AD", lokales Login-Formular).

Tenant nicht verfügbar

Wenn ein untergeordneter Tenant keine lokalen Benutzer und keine tenantübergreifenden Benutzerzuordnungen hat, zeigt die Login-Seite „This tenant is not available. Please contact your administrator." statt des Login-Formulars an. Dies weist darauf hin, dass der Tenant noch nicht mit Benutzerzugriff bereitgestellt wurde. Ein Administrator muss zunächst Benutzer provisionieren vom übergeordneten Tenant aus.

3. Benutzer authentifiziert sich

Der Benutzer:

• Gibt Benutzername/Passwort ein (gegen die lokale Benutzerdatenbank des Tenants validiert)
• Klickt auf eine Schaltfläche eines externen Providers (Weiterleitung zu Google, Azure AD usw.)
• Wird über einen übergeordneten Tenant authentifiziert (wenn ein OctoTenantIdentityProvider konfiguriert ist)

4. Verarbeitung der ersten Anmeldung

Bei der ersten Anmeldung über einen externen Provider führt der Identity Service Folgendes aus:

1. Erstellt einen lokalen Benutzerdatensatz, der mit der externen Identität verknüpft ist
2. Prüft die E-Mail-Domain-Gruppenregeln und fügt den Benutzer passenden Gruppen hinzu
3. Wenn der Provider eine DefaultGroupRtId hat, fügt er den Benutzer dieser Gruppe hinzu
4. Löst die effektiven Rollen aus Gruppenmitgliedschaften auf

5. Token-Ausstellung

Der Identity Service:

1. Löst alle effektiven Rollen auf (direkt + über Gruppen geerbt)
2. Löst die erlaubten Tenants auf (Login-Tenant + Home-Tenant + untergeordnete Tenants mit Zuordnungen)
3. Stellt ein JWT-Access-Token mit allen Claims aus
4. Gibt das Token an die Client-Anwendung zurück

6. API-Aufrufe

Der Client fügt das Access Token in API-Anfragen ein:

GET /customer-project/v1/runtime/entities
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Der Ziel-Dienst validiert das Token und prüft die Tenant-Autorisierung, bevor er die Anfrage verarbeitet.

Ersteinrichtung

Beim allerersten Start des Identity Service existieren keine Benutzer. Der Setup-Endpunkt erstellt den initialen Administrator:

octo-cli -c Setup -e "admin@example.com" -p "SecurePassword123"

Dieser Endpunkt:

1. Verifiziert, dass keine Benutzer im System-Tenant existieren (andernfalls schlägt er fehl)
2. Erstellt den Admin-Benutzer mit den angegebenen Anmeldedaten
3. Der Administrator kann sich dann anmelden und Tenants, Clients und Provider konfigurieren

Nach dem Setup hat der System-Tenant:

• Den Admin-Benutzer
• Standard-Clients (octo-cli, Swagger UI)
• Standard-Identity-Ressourcen (openid, profile, email, role)
• Standard-API-Scopes und -Ressourcen
• Standard-Identity-Provider (Google, Microsoft — deaktiviert; nur System-Tenant)
• Standardrollen und TenantOwners-Gruppe

Siehe auch

• octo-cli — Setup — den initialen Admin-Benutzer bootstrappen
• octo-cli — LogIn und LogInClientCredentials — interaktive und nicht-interaktive Authentifizierung von der CLI aus
• octo-cli — AuthStatus — die Claims des aktiven Tokens inspizieren