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

123 lines
9.3 KiB
Markdown

# 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.)_