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-Providertoolctrl-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.comzwingend 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
- Tenant-SSO-Provider-Definition in Authentik — den in Phase 09 bereits als Platzhalter angelegten
toolctrl-tenant-ssoOIDC-Provider aktivieren und mit eigenem Client-ID/Secret konfigurieren. Commit:11-backlog/customer-tenant-sso: enable tenant-sso oidc provider - Tenant-Login-Flow in Boilerplate — neuer Route
/auth/tenant-sso/start?tenant=...&email=...→ Redirect zu Authentik mit Domain-Hint, Callback-Handler erstellt/updatedTenantUser. Commit:11-backlog/customer-tenant-sso: tenant login + callback - Authentik-API-Client — kleine Wrapper-Lib in
app/utils/authentik/mit MethodscreateSource,updateSource,listSources(REST via Authentik-API-Token). Commit:11-backlog/customer-tenant-sso: authentik api client - Tenant-Admin-UI —
/app/$tenant/settings/ssoSeite: 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 - 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 - 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 - 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 - 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-ssoaktiv mit eigenem Client - Tenant-Admin kann unter
/app/$tenant/settings/ssoeine 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
TenantUsermit korrekt gemappter Rolle beim ersten Login - Logout triggert Authentik-End-Session
- Audit-Events
tenant.sso.login.success/failure/jit_provisioned/source_created/source_updatedwerden geschrieben - Tests grün
- Docs angelegt
- Progress-Log + PROGRESS.md aktualisiert
Rollback Strategy
- Feature-Flag
tenant_sso.enabledschaltet 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-verifierfür Acceptance-Criteria; manueller Test mit echtem Okta-Dev-Account - Code-Review:
gsd-code-reviewernach Step 5 (Domain-Verification — security-kritisch) und nach Step 8 (final)
Staging-Deployment-Steps
- Branch
agent/11-backlog-customer-tenant-ssopushen - Authentik auf Staging muss laufen (aus Phase 09)
- Okta-Developer-Account (free) als externe SAML-IdP-Test-Source einrichten
- Test-Tenant in Boilerplate-Staging mit verifizierter Domain anlegen
- End-to-End-Login via Okta verifizieren
- 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.)