Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/11-backlog/customer-tenant-sso.md
T

9.3 KiB

Customer-Tenant-SSO (Federation mit Okta / AzureAD / Google-Workspace)

Status: backlog: Enterprise-Verkauf ab Deal-Größe ~$50k/Jahr oder bei expliziter Compliance-Anforderung (z.B. SOC2-Customer-Audit, ISO 27001) Task-ID: #66 Phase: 11 (Backlog) Estimated Effort: 1-2 Wochen Integration + 1 Woche Admin-UI (= 2-3 Wochen total) wenn aktiviert Owner: unassigned

Problem

Tenants im Enterprise-Bereich verlangen häufig, dass ihre Mitarbeiter sich nicht mit Email/Passwort einloggen, sondern per SSO ihres bestehenden IdPs (Okta, AzureAD, Google-Workspace, OneLogin). Solange das nicht da ist, scheitern Verkäufe an Security-Reviews oder es entsteht Friction bei Onboarding/Offboarding (keine zentrale Lifecycle-Verwaltung).

Vor Aktivierung lohnt es sich nicht, weil typische SMB-Tenants kein SSO benötigen und die Wartung pro IdP nicht trivial ist.

Depends on

  • ../09-authentik-admin-sso/authentik-setup.md — Authentik-Instanz muss laufen
  • ../09-authentik-admin-sso/admin-oidc-login.md — Authentik-OIDC-Flow ist im Codebase verdrahtet, gleiche Patterns werden für Tenant-SSO wiederverwendet
  • bestehende Tenant-Member-Verwaltung (app/modules/tenants/)

Blocks

  • nichts (Backlog-Item, blockt keine aktive Roadmap)

Approach

Aufbau auf der bereits in Phase 09 hochgezogenen Authentik-Instanz statt eigenes saml-jackson-Setup. Begründung:

  • Alternativplan im ursprünglichen Backlog: saml-jackson als separate Tenant-IdP-Brücke aufsetzen: separater Stack, eigene DB, eigene Maintenance — verworfen, weil Authentik bereits multi-tenant-fähig ist
  • Authentik als Federation-Hub (gewählt): Authentik kann beliebig viele Source-Provider definieren (SAML, OIDC, OAuth2) und sie als Inbound-Federation in eine bestehende Authentik-Identity-Welt mappen. Wir definieren pro Tenant eine Source (z.B. „Tenant Acme — Okta-SAML") in Authentik, und der Tenant-Login-Flow läuft: Tenant-User → Boilerplate /auth/login → Authentik (zweiter OIDC-Provider toolctrl-tenant-sso) → Authentik routet anhand der Email-Domain auf die richtige Source → externer IdP-Login → Authentik-Callback → Boilerplate-Session

Das spart vs. ursprünglichem Plan ~1 Woche, weil saml-jackson nicht extra aufgesetzt werden muss.

Per-Tenant-IdP-Config-UI: unter /app/$tenant/settings/sso konfiguriert ein Tenant-Admin seine eigene Source. Die UI nutzt die Authentik-API (Token + REST), um Sources programmatisch anzulegen/zu aktualisieren — der Admin sieht nie das Authentik-UI direkt. Unterstützte Source-Typen: SAML 2.0 + OIDC.

Authentik handhabt:

  • Identity-Mapping (Email als primary Key, Mappings für name, groups)
  • JIT-Provisioning der zentralen Authentik-Identity beim ersten externen Login
  • SCIM-Server-Endpoint für IdPs die User-Provisioning pushen können

Boilerplate-Seite muss handhaben:

  • Domain-Verification für SAML-Pflicht-Durchsetzung (Tenant muss DNS-TXT-Record setzen, damit User mit Email @acme.com zwingend per Tenant-SSO einloggen muss, nicht per Email/Passwort)
  • Tenant-Membership-Synchronisation (Authentik-User → TenantUser-Record mit korrekter Rolle, JIT bei erstem Login)
  • Session-Logout: Boilerplate-Logout triggert Authentik-End-Session, optional IdP-Initiated-SLO durchreichen

Implementation Steps

  1. Tenant-SSO-Provider-Definition in Authentik — den in Phase 09 bereits als Platzhalter angelegten toolctrl-tenant-sso OIDC-Provider aktivieren und mit eigenem Client-ID/Secret konfigurieren. Commit: 11-backlog/customer-tenant-sso: enable tenant-sso oidc provider
  2. Tenant-Login-Flow in Boilerplate — neuer Route /auth/tenant-sso/start?tenant=...&email=... → Redirect zu Authentik mit Domain-Hint, Callback-Handler erstellt/updated TenantUser. Commit: 11-backlog/customer-tenant-sso: tenant login + callback
  3. Authentik-API-Client — kleine Wrapper-Lib in app/utils/authentik/ mit Methods createSource, updateSource, listSources (REST via Authentik-API-Token). Commit: 11-backlog/customer-tenant-sso: authentik api client
  4. Tenant-Admin-UI — /app/$tenant/settings/sso Seite: Source-Typ wählen (SAML/OIDC), Metadata-XML hochladen oder Endpoints manuell eingeben, Test-Connection-Button, Status-Anzeige. Commit: 11-backlog/customer-tenant-sso: tenant sso admin ui
  5. Domain-Verification — Tenant trägt zu verifizierende Email-Domain ein, App generiert DNS-TXT-Token, Background-Check via DNS-Resolver, bei Erfolg wird Domain als „SSO-Pflicht" markiert (Email/Passwort-Login für diese Domain abgewiesen). Commit: 11-backlog/customer-tenant-sso: domain verification + sso enforcement
  6. JIT-Provisioning + Role-Mapping — Callback-Handler liest Authentik-Group-Claims, mappt auf Tenant-Rollen (default: alle User werden „Member", Admin-Mapping per Tenant-Config), schreibt Audit-Event. Commit: 11-backlog/customer-tenant-sso: jit provisioning + role mapping
  7. Logout + optionales SLO — Tenant-Logout triggert Authentik-End-Session; SLO (IdP-Initiated) als opt-in pro Source. Commit: 11-backlog/customer-tenant-sso: logout + slo
  8. Doku — docs/operations/tenant-sso-setup.md (Operator-Sicht), docs/tenant-admin/sso-configuration.md (Tenant-Admin-Sicht mit Beispielen für Okta + AzureAD + Google-Workspace). Commit: 11-backlog/customer-tenant-sso: documentation

Test Requirements

  • Unit-Tests: Domain-Verification-Logik, Email-Domain-zu-Tenant-Resolver, Role-Mapping-Funktion, Authentik-API-Wrapper (mit gemocktem Authentik-Server)
  • Integration-Tests: Tenant-SSO-Login End-to-End gegen lokale Authentik-Instanz mit gemockter externer Source; JIT-Provisioning erzeugt TenantUser; Domain-Verification durchgesetzt
  • E2E-Tests (Playwright): Tenant-Admin konfiguriert SAML-Source, Test-User loggt sich via Source ein, landet im Tenant-Dashboard mit korrekter Rolle
  • Coverage-Target: ≥75% für app/modules/tenant-sso/ + app/utils/authentik/
  • Test-Files: neben Source, E2E unter apps/web/playwright/tenant-sso/

NICHT als completed markieren bevor alle Tests grün sind.

Acceptance Criteria

  • Authentik-OIDC-Provider toolctrl-tenant-sso aktiv mit eigenem Client
  • Tenant-Admin kann unter /app/$tenant/settings/sso eine SAML- oder OIDC-Source anlegen, Test-Connection-Button bestätigt Konfiguration
  • Domain-Verification per DNS-TXT funktioniert, verifizierte Domain wird SSO-Pflicht
  • Tenant-User mit verifizierter Email-Domain kann sich nur per SSO einloggen (Email/Passwort wird abgewiesen)
  • JIT-Provisioning erstellt TenantUser mit korrekt gemappter Rolle beim ersten Login
  • Logout triggert Authentik-End-Session
  • Audit-Events tenant.sso.login.success/failure/jit_provisioned/source_created/source_updated werden geschrieben
  • Tests grün
  • Docs angelegt
  • Progress-Log + PROGRESS.md aktualisiert

Rollback Strategy

  • Feature-Flag tenant_sso.enabled schaltet die SSO-Login-Routes ab, Tenants fallen auf Email/Passwort zurück
  • Domain-Verification-Pflicht kann pro Tenant deaktiviert werden, ohne dass Source-Definition in Authentik gelöscht werden muss
  • Authentik-Sources sind in Authentik-DB persistent — Rollback der Boilerplate-Seite löscht sie nicht, sie können manuell oder beim nächsten Tenant-Edit re-aktiviert werden
  • Bei Notfall: Tenant-Admin kann Source temporär in der UI deaktivieren, Authentik routet dann auf Default-Login

Security Notes

  • Domain-Verification ist kritisch — ohne sie könnte ein User mit Email einer fremden Domain einen eigenen Tenant aufmachen und SSO mit der fremden Domain forcen. DNS-TXT-Check vor SSO-Pflicht-Aktivierung Pflicht
  • Authentik-API-Token: Boilerplate-Backend braucht Schreibrechte auf Sources — Token nur in Server-Env, niemals im Client
  • SAML-Metadata-Upload: XML-Parsing muss XXE-Hardened sein (entweder via DOMPurify-äquivalente Library oder strenges XSD-Validation)
  • IdP-Initiated-SAML-Logins (vs SP-Initiated) sind anfälliger für Replay-Attacken — als opt-in markieren, Default ist SP-Initiated
  • Group-Claims von externer IdP nicht blind als Admin-Rolle übernehmen — Tenant-Admin muss Mapping explizit konfigurieren (kein Auto-Promotion)
  • Session-Fixation-Schutz: nach erfolgreichem SSO-Callback neue Session-ID generieren

Subagent Recommendations

  • Planning: Plan-Subagent mit Phase-09-Outputs als Input (insb. Authentik-Setup-Doku)
  • Research: Explore-Subagent für Authentik-Multi-Source-Federation-Best-Practices und konkrete Okta/AzureAD/Google-Workspace-Setup-Schritte
  • Implementation: ein general-purpose-Subagent pro Step
  • Tests: separater general-purpose-Subagent für SAML-Integration-Tests (XXE-Hardening-Verify)
  • Verification: gsd-verifier für Acceptance-Criteria; manueller Test mit echtem Okta-Dev-Account
  • Code-Review: gsd-code-reviewer nach Step 5 (Domain-Verification — security-kritisch) und nach Step 8 (final)

Staging-Deployment-Steps

  1. Branch agent/11-backlog-customer-tenant-sso pushen
  2. Authentik auf Staging muss laufen (aus Phase 09)
  3. Okta-Developer-Account (free) als externe SAML-IdP-Test-Source einrichten
  4. Test-Tenant in Boilerplate-Staging mit verifizierter Domain anlegen
  5. End-to-End-Login via Okta verifizieren
  6. Domain-Verification-Pflicht testen (User mit verifizierter Domain darf nicht per Email/Passwort einloggen)

Deviations from Plan

(Wird vom ausführenden Agent gefüllt.)

Progress Log

(Wird vom ausführenden Agent gefüllt.)