Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/09-authentik-admin-sso/admin-oidc-login.md
T

39 KiB

Admin-Panel OIDC-Login (Authentik-SSO)

Status: completed (env-naming-bug fixed 2026-05-19; full E2E login still requires user creds) Task-ID: #82 Phase: 09 Estimated Effort: ~1 Woche (5-7 Tage) Owner: unassigned

Problem

Aktuell loggt sich das Admin-Panel der Boilerplate (apps/web/app/routes/admin/*) ausschließlich via App-internem Email/Passwort-Flow ein. Es gibt keinen externen IdP-Kontakt, keine Group-basierte Access-Control, keine zentrale Session-Revocation und kein Federations-Pfad. Sobald wir Customer-Tenant-SSO (Backlog #66) anbieten wollen, brauchen wir den OIDC-Client-Pfad ohnehin — wir bauen ihn hier zuerst für das Admin-Panel auf.

Konkret fehlt:

  • OIDC-Client-Implementation für den Authentik-Provider toolctrl-admin-panel
  • JIT-Provisioning-Logik — wenn ein neuer Authentik-User mit passender Group sich zum ersten Mal einloggt, soll automatisch ein AdminUser-Record entstehen
  • Rolle-Mapping Authentik-Group → AdminUser.role (toolctrl-admin → super_admin, toolctrl-staff → staff)
  • RP-Initiated-Logout — lokales Session-Killing + Authentik-End-Session-Redirect
  • Fallback-Login für den Notfall (IdP-Down) — gekapselt hinter Env-Flag, mit Allowlist
  • App-interne MFA als zweite Schicht für sensible Actions (Impersonation, Tenant-Löschung), zusätzlich zur Authentik-MFA-Pflicht
  • Audit-Trail jeder Admin-Login/-Logout-Event in AuditEvent

Betroffene Codestellen (neu + modifiziert):

  • apps/web/app/modules/admin-sso/ (neu) — komplettes Modul: client.server.ts, state.server.ts, jit-provisioning.server.ts, claims.server.ts, logout.server.ts
  • apps/web/app/routes/auth.admin.login.tsx (neu)
  • apps/web/app/routes/auth.admin.callback.tsx (neu)
  • apps/web/app/routes/auth.admin.logout.tsx (neu)
  • apps/web/app/routes/admin.login.tsx (modifiziert — neuer „Login mit SSO"-Primary-Button, Fallback-Toggle)
  • apps/web/app/routes.ts (modifiziert — neue Routes registrieren)
  • prisma/schema.prisma (modifiziert — AdminUser-Erweiterung: ssoSubjectId, ssoProvider, ssoGroups, lastSsoLoginAt)
  • prisma/migrations/<ts>_admin_user_sso_fields/ (neu)
  • apps/web/app/services/auth/admin-session.server.ts (modifiziert oder neu — Session-Helper für SSO + Fallback)
  • apps/web/app/services/auth/admin-mfa-gate.server.ts (neu — App-MFA-Gate für sensible Actions)
  • docs/operations/admin-sso.md (neu)

Depends on

  • 09-authentik-admin-sso/authentik-setup.md (#81) — Authentik muss laufen, OIDC-Provider toolctrl-admin-panel muss existieren, Groups + Mapping müssen konfiguriert sein
  • 01-tech-debt-foundation/totp-consolidation.md (#26) — die App-MFA-Schicht (zweiter Layer für sensible Actions) MUSS gegen die konsolidierte otpauth-Variante gehen, nicht gegen die selbst-gebaute Crypto

Blocks

  • 11-backlog/customer-tenant-sso.md (#66) — Tenant-SSO wiederverwendet ~80% des OIDC-Client-Codes aus diesem Modul (in apps/web/app/modules/admin-sso/ werden die wiederverwendbaren Bausteine sauber abstrahiert)

Approach

Gewählt: Eigenständiges Modul apps/web/app/modules/admin-sso/ mit der Library openid-client (https://github.com/panva/node-openid-client) — die Referenz-Implementation für OIDC-RP in Node, RFC-konform, aktiv gepflegt, deckt PKCE, State, Nonce, JWT-Verifikation, JWKS-Caching ab. Alternativen verworfen:

  • oidc-client-ts — primär Browser-Library (TS, SPA-orientiert), passt nicht zum React-Router-v7-SSR-Pattern
  • Eigene Implementation — Crypto/JWT-Verifikation selbst bauen ist Anti-Pattern, OIDC-Spec ist fehleranfällig
  • next-auth/auth.js — overkill und zu viel Magic; wir wollen expliziten Server-Code in unseren Routen, kein Plug-and-Play-Framework

Routes-Layout (React-Router-v7-Framework-Mode, siehe CLAUDE.md):

  • GET /auth/admin/login — generiert PKCE-code_verifier + code_challenge, generiert state (CSRF) + nonce (Replay-Schutz), persistiert beide in signed/encrypted Cookie (HttpOnly, Secure, SameSite=Lax, kurze TTL), redirected zu Authentik-authorization_endpoint
  • GET /auth/admin/callback?code=…&state=… — verifiziert State-Cookie, tauscht Code gegen Tokens via token_endpoint (mit PKCE-Verifier + Client-Secret), verifiziert ID-Token-Signatur via Authentik-JWKS, validiert iss/aud/exp/nonce, extrahiert sub + groups + email + name Claims, ruft JIT-Provisioning auf, setzt App-Session-Cookie, redirected zu /admin
  • POST /auth/admin/logout — killt lokale Session, redirected zu Authentik-end_session_endpoint mit id_token_hint + post_logout_redirect_uri

JIT-Provisioning-Regel (in jit-provisioning.server.ts):

  • Lookup AdminUser via ssoSubjectId (Authentik-sub-Claim) + ssoProvider='authentik'
  • Wenn nicht gefunden:
    • Fallback-Lookup via email (case-insensitive) für Migration bestehender Admin-Accounts → wenn gefunden, attache SSO-Fields
    • Wenn auch nicht gefunden: prüfe ob Group-Claim mindestens eine der erlaubten Groups (toolctrl-admin, toolctrl-staff) enthält → ja: erstelle neuen AdminUser mit Rolle aus Group-Mapping; nein: 403 (Login abgelehnt)
  • Wenn gefunden: update ssoGroups, lastSsoLoginAt, email (falls geändert), name. Update role gemäß aktueller Group-Mitgliedschaft (Authentik = Source-of-Truth, App-Rolle wird bei jedem Login synchronisiert)

Permission-Mapping (in claims.server.ts):

  • toolctrl-admin (höchste Priorität, falls beide Groups) → AdminUser.role = 'super_admin'
  • toolctrl-staff → AdminUser.role = 'staff'
  • weder noch → Login-Reject 403
  • Granulare Permission-Checks bleiben in der App (apps/web/app/utils/permissions/), die Rolle ist nur der grobe Switch

Fallback-Login-Strategie:

  • Email/Passwort-Login bleibt im Code, ist aber per Default deaktiviert via ADMIN_FALLBACK_LOGIN_ENABLED=false
  • Wenn aktiviert: nur Accounts in ADMIN_FALLBACK_LOGIN_EMAILS (komma-separierte Allowlist) dürfen den Fallback nutzen
  • Login-Page (/admin/login) zeigt prominent „Login mit SSO" als Primary-CTA; Fallback nur als kleiner Toggle „Notfall-Login mit Passwort" am unteren Rand, der nur sichtbar ist wenn Env-Flag true
  • Initial-Bootstrap-Admin (vor Authentik-Setup angelegt) bleibt damit erreichbar während Authentik down ist oder noch nicht konfiguriert
  • Jeder Fallback-Login wird mit Severity warn in AuditEvent UND als Sentry-Breadcrumb geloggt (Operator-Sichtbarkeit)
  • Optional: Slack/Discord-Notification bei Fallback-Login (Hook später erweiterbar)

App-MFA als zweite Schicht (in admin-mfa-gate.server.ts):

  • Für sensible Actions (Liste in Code als Konstante SENSITIVE_ADMIN_ACTIONS): Impersonation-Start, Tenant-Löschung, Permission-Grant, Audit-Log-Export, Manueller Daten-Export
  • Vor Ausführung wird ein TOTP-Challenge erzwungen — auch wenn Authentik-MFA gerade vorhanden ist (Defense-in-Depth)
  • Nutzt konsolidierte otpauth-Variante aus #26 (apps/web/app/services/auth/totp.server.ts)
  • TOTP-Secret wird beim ersten sensiblen Action enrollment-mäßig angelegt (separate Page /admin/security/mfa-enroll), unabhängig von Authentik-MFA
  • Cache: nach erfolgreichem App-MFA-Challenge für 15 Min freigeschaltet (server-side, Session-bound), danach erneut nötig

Alternativen verworfen:

  • Authentik-MFA als einzige Schicht — funktioniert für Standard-Login, aber Authentik-Session-Cookie gilt nicht App-seitig; wir müssten Authentik-API für „re-authenticate"-Calls bemühen, was Komplexität + Latenz hinzufügt. Eigene App-MFA-Gate ist sauberer.
  • Kein Fallback-Login — zu riskant; wenn Authentik-Instanz down ist (Disaster, Update-Bug), wären Admins ausgesperrt und könnten die Authentik-Instanz nicht mehr operativ recovern.
  • Fallback-Login immer aktiv — schwächt die SSO-Schutzschicht; Env-Flag erzwingt bewusste Entscheidung.

Implementation Steps

  1. Library-Install + Modul-Skelett

    • Files: apps/web/app/modules/admin-sso/index.ts, apps/web/app/modules/admin-sso/README.md, package.json (Dep: openid-client)
    • Aktion: pnpm add openid-client jose (jose für JWT-Helper falls openid-client das nicht bereits exposed)
    • Commit: 09-authentik/admin-oidc: scaffold admin-sso module and install openid-client
  2. DB-Schema: AdminUser erweitern

    • Files: prisma/schema.prisma, prisma/migrations/<ts>_admin_user_sso_fields/migration.sql
    • Aktion: AdminUser um Felder erweitern:
      • ssoSubjectId String? (Authentik-sub-Claim, unique innerhalb (ssoProvider, ssoSubjectId))
      • ssoProvider String? (z.B. "authentik")
      • ssoGroups String[] (Snapshot der Groups aus letztem Login, für Debug + Audit)
      • lastSsoLoginAt DateTime?
      • Index @@unique([ssoProvider, ssoSubjectId])
    • Migration generieren mit pnpm prisma migrate dev --name admin_user_sso_fields
    • Commit: 09-authentik/admin-oidc: extend AdminUser with SSO fields and migration
  3. OIDC-Client-Initialization

    • Files: apps/web/app/modules/admin-sso/client.server.ts
    • Aktion: Singleton-Lazy-Init eines openid-client-Client:
      • Discovery via Issuer.discover(env.AUTHENTIK_ISSUER_URL)
      • Client-Constructor mit client_id, client_secret, redirect_uris: [env.AUTHENTIK_ADMIN_REDIRECT_URI], response_types: ['code'], token_endpoint_auth_method: 'client_secret_post'
      • JWKS wird auto-cached von der Library
      • Error-Handling: bei Discovery-Failure → Sentry-Capture + Throw mit klarer Message (führt zu Fallback-Banner auf Login-Page)
    • Commit: 09-authentik/admin-oidc: implement openid-client initialization
  4. State + PKCE + Nonce Persistence

    • Files: apps/web/app/modules/admin-sso/state.server.ts
    • Aktion:
      • createLoginChallenge() generiert: state (32-byte hex), nonce (32-byte hex), code_verifier (via generators.codeVerifier() aus openid-client), code_challenge (via generators.codeChallenge(verifier))
      • Persistiert das Tupel in einem signed Cookie admin_sso_challenge (HttpOnly, Secure, SameSite=Lax, Path=/auth/admin, Max-Age=600s)
      • Cookie-Signature via existierende Session-Secret-Infrastruktur (getSessionSecret() o.ä. aus bestehender Session-Library)
      • consumeLoginChallenge(request) liest + validiert + invalidiert den Cookie (single-use)
    • Commit: 09-authentik/admin-oidc: add state/PKCE/nonce challenge cookie helpers
  5. Login-Route

    • Files: apps/web/app/routes/auth.admin.login.tsx, apps/web/app/routes.ts (Route registrieren)
    • Aktion: loader ruft client.authorizationUrl({state, code_challenge, code_challenge_method:'S256', nonce, scope:'openid profile email groups'}), setzt Challenge-Cookie, returned redirect(authorizationUrl)
    • Kein Component (reine Redirect-Route)
    • Type-Generation: pnpm run typecheck nach Route-Registration
    • Commit: 09-authentik/admin-oidc: add /auth/admin/login route
  6. Callback-Route

    • Files: apps/web/app/routes/auth.admin.callback.tsx, apps/web/app/routes.ts
    • Aktion: loader:
      • consumeLoginChallenge(request) → state/nonce/verifier aus Cookie
      • client.callback(redirect_uri, params, {state, nonce, code_verifier}) → tauscht Code gegen Token-Set
      • Verifikation: ID-Token-Signatur (auto via openid-client), iss/aud/exp/nonce (auto), zusätzlich email_verified=true prüfen (falls Claim vorhanden)
      • Claims extrahieren: sub, email, name, groups
      • jitProvision(claims) aufrufen (Step 7) → liefert AdminUser
      • App-Session-Cookie setzen via existierende Admin-Session-Library, id_token (raw) zusätzlich in Session speichern (für RP-Initiated-Logout)
      • AuditEvent schreiben: admin.login.sso.success, actorAdminUserId, meta: {ssoSubjectId, groups, ip, userAgent}
      • Bei jedem Error: AuditEvent admin.login.sso.failure mit Error-Klasse + Sentry-Capture; User-redirect zu /admin/login?error=sso_failed
      • Success-Redirect zu /admin (oder zur returnTo-Query-Param falls vorhanden + safe)
    • Commit: 09-authentik/admin-oidc: add /auth/admin/callback route with token exchange and verification
  7. JIT-Provisioning + Group-Mapping

    • Files: apps/web/app/modules/admin-sso/jit-provisioning.server.ts, apps/web/app/modules/admin-sso/claims.server.ts
    • Aktion:
      • mapGroupsToRole(groups: string[]): 'super_admin' | 'staff' | null — toolctrl-admin > toolctrl-staff > null
      • jitProvision({sub, email, name, groups, provider:'authentik'}):
        • Lookup via (ssoProvider, ssoSubjectId)
        • Wenn nicht gefunden: Lookup via email (case-insensitive) für Existing-Account-Linking
        • Wenn weder noch: nur erstellen wenn mapGroupsToRole(groups) !== null, sonst 403
        • Beim Create: role = mapGroupsToRole(groups), ssoSubjectId, ssoProvider, ssoGroups, lastSsoLoginAt
        • Beim Update: role re-syncen (Authentik = Source-of-Truth), ssoGroups, lastSsoLoginAt, email/name aktualisieren
      • Transaction-safe (Prisma $transaction), idempotent (concurrent Logins desselben Users dürfen keine Duplicate-Errors werfen — Unique-Constraint fängt)
    • Commit: 09-authentik/admin-oidc: implement JIT provisioning and group-to-role mapping
  8. Logout-Route (RP-Initiated)

    • Files: apps/web/app/routes/auth.admin.logout.tsx, apps/web/app/modules/admin-sso/logout.server.ts, apps/web/app/routes.ts
    • Aktion: action (POST):
      • Lese id_token aus App-Session
      • Lokale Session killen (App-Cookie destroyen, Session-Store-Eintrag löschen)
      • AuditEvent admin.logout.sso
      • Redirect zu client.endSessionUrl({id_token_hint, post_logout_redirect_uri: env.AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI})
      • Authentik killt seine Session und redirected zurück zur post_logout_redirect_uri (z.B. /admin/login?logged_out=1)
    • Wenn id_token fehlt (nur Fallback-Login war aktiv): nur lokale Session killen, kein Authentik-Redirect, direkt zu /admin/login
    • Commit: 09-authentik/admin-oidc: add /auth/admin/logout with RP-initiated end session
  9. Admin-Login-Page UI

    • Files: apps/web/app/routes/admin.login.tsx (modifiziert)
    • Aktion:
      • Primary-CTA: großer Button „Login mit SSO" → linked auf /auth/admin/login
      • Wenn ADMIN_FALLBACK_LOGIN_ENABLED=true (loader exposed das als boolean): kleiner Disclosure-Toggle „Notfall-Login mit Passwort", der das bestehende Email/Passwort-Form aufklappt
      • Wenn error=sso_failed Query-Param: rote Error-Banner mit Hinweis auf Operator-Kontakt
      • Wenn logged_out=1 Query-Param: grüne Success-Banner
      • Existierendes Email/Passwort-Form bleibt funktional, aber Fallback-Submit-Handler MUSS prüfen:
        • ADMIN_FALLBACK_LOGIN_ENABLED=true
        • Email in ADMIN_FALLBACK_LOGIN_EMAILS-Allowlist
        • Bei Erfolg: AuditEvent admin.login.fallback.success mit Severity warn + Sentry-Breadcrumb
        • Bei Fail: admin.login.fallback.failure
    • Type-Generation: pnpm run typecheck
    • Commit: 09-authentik/admin-oidc: update admin login page with SSO CTA and gated fallback
  10. Fallback-Login-Guards (Server-Side)

    • Files: apps/web/app/services/auth/admin-session.server.ts (modifiziert oder neu)
    • Aktion:
      • assertFallbackLoginAllowed(email: string) — wirft 403 wenn ADMIN_FALLBACK_LOGIN_ENABLED !== 'true' oder Email nicht in Allowlist
      • Bestehender Email/Passwort-Login-Action ruft diesen Guard VOR Passwort-Check
    • Commit: 09-authentik/admin-oidc: enforce env-gated fallback login allowlist
  11. App-MFA-Gate für sensible Actions

    • Files: apps/web/app/services/auth/admin-mfa-gate.server.ts (neu), apps/web/app/routes/admin/security.mfa-enroll.tsx (neu), apps/web/app/routes/admin/security.mfa-challenge.tsx (neu), apps/web/app/routes.ts
    • Aktion:
      • Konstante SENSITIVE_ADMIN_ACTIONS = ['impersonation.start', 'tenant.delete', 'permission.grant', 'audit.export', 'data.export']
      • Helper requireAppMfa(request, actionKey):
        • Wenn actionKey in SENSITIVE_ADMIN_ACTIONS UND letzter erfolgreicher App-MFA-Challenge der Session älter als 15 Min ist: redirect zu /admin/security/mfa-challenge?returnTo=<encoded>
        • Nutzt verifyTotpToken aus apps/web/app/services/auth/totp.server.ts (konsolidierte otpauth aus #26)
      • Enrollment-Page generiert TOTP-Secret + QR (otpauth-URL), Verify-Step bestätigt erstes Token bevor persistiert wird
      • Challenge-Page nimmt Token entgegen, verifiziert, setzt Session-Field lastAppMfaAt = now(), redirected zu returnTo
      • Sensible Actions (in ihren jeweiligen Action-Handlern) rufen await requireAppMfa(request, 'impersonation.start') als ersten Step
    • Commit: 09-authentik/admin-oidc: add app-level MFA gate for sensitive admin actions
  12. Audit-Events verdrahten

    • Files: apps/web/app/modules/admin-sso/audit.server.ts (neu, dünner Wrapper) — schreibt in existierendes AuditEvent-Modell
    • Events:
      • admin.login.sso.success
      • admin.login.sso.failure (mit Error-Klasse)
      • admin.login.fallback.success (severity warn)
      • admin.login.fallback.failure
      • admin.logout.sso
      • admin.mfa.app.challenge.success
      • admin.mfa.app.challenge.failure
    • Alle Events mit ip, userAgent, actorAdminUserId (wenn auflösbar), meta (event-spezifisch)
    • Commit: 09-authentik/admin-oidc: wire audit events for all admin login/logout paths
  13. Env-Vars + .env.example

    • Files: apps/web/.env.example (oder zentrales .env.example), apps/web/app/utils/env.server.ts (Schema-Erweiterung mit zod)
    • Keys:
      • AUTHENTIK_ISSUER_URL=https://auth.example.com/application/o/toolctrl-admin-panel/
      • AUTHENTIK_ADMIN_CLIENT_ID=toolctrl-admin-panel
      • AUTHENTIK_ADMIN_CLIENT_SECRET= (Coolify-Vault, niemals committen)
      • AUTHENTIK_ADMIN_REDIRECT_URI=https://admin.example.com/auth/admin/callback
      • AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI=https://admin.example.com/admin/login?logged_out=1
      • AUTHENTIK_END_SESSION_URL=https://auth.example.com/application/o/toolctrl-admin-panel/end-session/ (optional, openid-client kann das auch aus Discovery)
      • ADMIN_FALLBACK_LOGIN_ENABLED=false
      • ADMIN_FALLBACK_LOGIN_EMAILS= (komma-separierte Allowlist, leer per Default)
    • Zod-Schema: alle URLs als z.string().url(), Boolean als z.enum(['true','false']).transform(v => v === 'true')
    • Commit: 09-authentik/admin-oidc: add SSO env vars and zod schema
  14. Doku

    • Files: docs/operations/admin-sso.md
    • Inhalt (Mindest-Sections):
      • Überblick — Flow-Diagramm (Mermaid) Login + Logout + Fallback
      • Authentik-Group-Setup-Anleitung — wie neue Admin-User onboarden (User in Authentik anlegen, in toolctrl-admin oder toolctrl-staff-Group packen, MFA-Enrollment erzwingen), erster Login triggert JIT
      • Group-Removal — wie Admin offboarden (Authentik-User deaktivieren oder aus Group entfernen → nächster Login wirft 403; App-Session bleibt aktiv bis Cookie-TTL — daher zusätzlich: manuell App-Session via Operator-CLI revoken; siehe Sub-Section "Force-Logout")
      • Fallback-Recovery-Procedure — wenn Authentik down ist:
        1. Operator setzt ADMIN_FALLBACK_LOGIN_ENABLED=true + ADMIN_FALLBACK_LOGIN_EMAILS=bootstrap@example.com in Coolify-Env, Redeploy
        2. Login mit Bootstrap-Admin via Email/Passwort
        3. Authentik wiederherstellen (siehe docs/operations/authentik-setup.md Disaster-Recovery)
        4. Fallback wieder ausschalten + Sentry-Alert auflösen
      • Permission-Mapping — Tabelle Group → Rolle → Permissions
      • App-MFA-Gate — Liste sensible Actions, Enrollment-Flow, 15-Min-Cache-Verhalten
      • Audit-Events — Tabelle aller Event-Types, wo sie geloggt werden
      • Troubleshooting — typische Fehler: iss-Mismatch (Issuer-URL falsch in Env), aud-Mismatch (Client-ID falsch), JWKS-Cache-Stale (Authentik-Key rotiert), Group-Claim leer (Scope groups nicht in Authentik-Provider konfiguriert)
    • Commit: 09-authentik/admin-oidc: document SSO operations and fallback recovery
  15. Optionale Cleanup-Migration — falls bestehende Admin-Accounts existieren ohne ssoSubjectId: Skript zum Mark-as-Legacy

    • Files: prisma/migrations/<ts>_admin_user_sso_fields/data.ts (Backfill-Script falls nötig)
    • Aktion: alle existierenden AdminUser bekommen ssoProvider = null, ssoSubjectId = null (Default eh null, daher meistens kein Backfill nötig). Skript dokumentiert dass diese Accounts beim ersten SSO-Login per Email gematched + verlinkt werden.
    • Commit: 09-authentik/admin-oidc: document legacy admin account linking strategy (kann auch nur Doku sein, kein Backfill)

Test Requirements

  • Unit-Tests (Vitest, neben Source-Files):
    • apps/web/app/modules/admin-sso/claims.server.test.ts:
      • mapGroupsToRole(['toolctrl-admin']) → 'super_admin'
      • mapGroupsToRole(['toolctrl-staff']) → 'staff'
      • mapGroupsToRole(['toolctrl-admin', 'toolctrl-staff']) → 'super_admin' (höchste Prio)
      • mapGroupsToRole(['random-group']) → null
      • mapGroupsToRole([]) → null
    • apps/web/app/modules/admin-sso/state.server.test.ts:
      • createLoginChallenge() generiert distincte state/nonce/verifier
      • consumeLoginChallenge returned korrekte Werte und invalidiert Cookie
      • Tampered Cookie wird abgelehnt (Signature-Check)
      • Expired Cookie (Max-Age überschritten) wird abgelehnt
    • apps/web/app/modules/admin-sso/jit-provisioning.server.test.ts (mit Test-DB):
      • Neuer User mit toolctrl-admin → AdminUser angelegt mit role='super_admin'
      • Neuer User mit unbekannter Group → Throw 403
      • Bestehender User mit gleicher ssoSubjectId → Update (kein Duplicate)
      • Bestehender User per email-Match → Linking (ssoSubjectId attached)
      • User wechselt Group von admin → staff → role wird beim nächsten Login re-synced
      • Concurrent JIT-Calls für gleichen User → keine Duplicate-Errors (Unique-Constraint greift)
    • apps/web/app/services/auth/admin-mfa-gate.server.test.ts:
      • Sensible Action ohne MFA-Challenge → redirect
      • Sensible Action mit MFA-Challenge < 15 Min → pass
      • Sensible Action mit MFA-Challenge > 15 Min → redirect
      • Nicht-sensible Action → pass ohne MFA
    • apps/web/app/services/auth/admin-session.server.test.ts (für Fallback-Guards):
      • assertFallbackLoginAllowed wirft wenn Env-Flag false
      • wirft wenn Email nicht in Allowlist
      • passt durch wenn beide Bedingungen erfüllt
  • Integration-Tests (Vitest mit Mock-Authentik via msw oder Lokal-Container):
    • Login-Flow End-to-End (Mock-Authentik): GET /auth/admin/login → Redirect zu Mock-Authorize, Mock liefert Code → Callback → Token-Exchange → JIT → Session-Cookie gesetzt → Redirect zu /admin
    • State-Mismatch: tampered State im Callback → 400
    • Nonce-Mismatch: Token mit falscher Nonce → 400
    • Expired ID-Token → 401
    • Group-Claim leer → 403
  • E2E-Tests (Playwright) mit Staging-Authentik:
    • Happy-Path SSO-Login: User klickt „Login mit SSO" → Authentik-Login-Page → Test-Credentials → MFA-Challenge → Erfolg → Admin-Dashboard sichtbar
    • JIT-Provisioning: Neuer Authentik-User (nur in Authentik existent) loggt sich erstmals ein → AdminUser-Record danach in DB sichtbar (assert via API-Helper)
    • Logout-Flow: Admin → Logout-Button → Authentik-End-Session → redirect zu /admin/login?logged_out=1
    • Fallback-Login (Env-Flag aktiviert): Login-Page zeigt Fallback-Toggle → Email/Passwort-Login mit Allowlist-Email → Erfolg → AuditEvent admin.login.fallback.success mit warn-Severity in DB
    • Fallback-Login abgelehnt: Non-Allowlist-Email versucht Fallback → 403, Audit admin.login.fallback.failure
    • Fallback-Login deaktiviert: Env-Flag false → Fallback-Toggle nicht sichtbar; direct-POST auf Fallback-Endpoint → 403
    • App-MFA-Gate: Admin (frisch eingeloggt) versucht Impersonation → wird zu /admin/security/mfa-challenge redirected; nach gültigem TOTP-Code → Impersonation startet; Wiederholung innerhalb 15 Min → keine erneute Challenge; nach 16 Min → erneute Challenge
  • Coverage-Target: ≥85% Lines/Branches im Modul apps/web/app/modules/admin-sso/; 100% auf claims.server.ts und state.server.ts (security-kritisch)
  • Test-Files:
    • apps/web/app/modules/admin-sso/*.test.ts (Unit + Integration)
    • apps/web/tests/e2e/admin-sso.spec.ts (Playwright)
    • apps/web/app/services/auth/admin-mfa-gate.server.test.ts

NICHT als completed markieren bevor:

  • alle Unit + Integration-Tests grün
  • E2E-Tests gegen Staging-Authentik grün (alle 6 Szenarien)
  • Coverage-Gate erfüllt
  • Fallback-Recovery-Procedure aus docs/operations/admin-sso.md MANUELL einmal end-to-end durchgespielt (inkl. Re-Enable und Re-Disable des Env-Flags)

Acceptance Criteria

  • Modul apps/web/app/modules/admin-sso/ vollständig mit allen Helpern (client, state, jit-provisioning, claims, logout, audit)
  • Routes /auth/admin/login, /auth/admin/callback, /auth/admin/logout funktional und registriert in apps/web/app/routes.ts
  • AdminUser-Model um SSO-Felder erweitert, Prisma-Migration angewendet
  • OIDC-Discovery + State + PKCE + Nonce + JWT-Verifikation funktionieren gegen Staging-Authentik
  • JIT-Provisioning erstellt neue AdminUser mit korrekt gemappter Rolle
  • Group-Removal (Authentik-seitig) führt beim nächsten Login zu Role-Re-Sync (oder Reject wenn keine erlaubte Group mehr)
  • RP-Initiated-Logout killt lokale Session + Authentik-Session
  • Email/Passwort-Fallback nur aktiv bei ADMIN_FALLBACK_LOGIN_ENABLED=true UND Email in ADMIN_FALLBACK_LOGIN_EMAILS
  • App-MFA-Gate für SENSITIVE_ADMIN_ACTIONS funktioniert (Enrollment + Challenge + 15-Min-Cache)
  • App-MFA nutzt konsolidierte otpauth-Implementation aus #26 (kein eigener TOTP-Code)
  • AuditEvents werden für alle Login/Logout/MFA-Pfade geschrieben
  • Fallback-Logins triggern Sentry-Breadcrumb mit Severity warn
  • Unit + Integration + E2E Tests grün, Coverage-Gate erfüllt
  • pnpm lint + pnpm typecheck grün
  • .env.example enthält alle neuen Keys aus Step 13, mit kommentierten Beispielwerten
  • docs/operations/admin-sso.md angelegt mit allen Mindest-Sections
  • Fallback-Recovery-Procedure manuell durchgespielt und in Progress-Log dokumentiert
  • Detail-MD Progress Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • Feature-Flag-Disable — falls SSO-Flow bricht: ADMIN_FALLBACK_LOGIN_ENABLED=true + Allowlist setzen, Redeploy. Admins können sofort wieder per Email/Passwort einloggen. SSO-Routes (/auth/admin/*) können dabei live bleiben (returnen Fehler), oder via zusätzlichem Env-Flag ADMIN_SSO_ENABLED=false deaktiviert werden (Empfehlung: dieser Flag wird zusätzlich in Step 13 implementiert, default true).
  • DB-Migration revertieren:
    • Migration ist additive (nur neue Spalten + Index), Rollback via prisma migrate resolve + manuellem ALTER TABLE DROP COLUMN-SQL
    • Down-Migration in Migration-Folder hinterlegen
    • Kein Daten-Loss (SSO-Felder waren nullable)
  • Commits revertieren — die Step-12-Audit-Wiring + Step-11-MFA-Gate sind die "destruktivsten" Änderungen (touchen Bestands-Routes). Falls sie Probleme machen, atomare Revert pro Commit möglich.
  • Authentik-Client-Secret-Leak — über Authentik-UI rotieren, App-.env updaten, Redeploy. Bestehende Sessions bleiben (App-Cookies sind unabhängig vom Client-Secret).
  • Komplettes Disaster (SSO unbrauchbar + Authentik down + Fallback-Flag wurde gelöscht): Operator-CLI-Script pnpm cli admin:force-create --email=… --role=super_admin (sofern existent — sonst direkter DB-Insert dokumentiert in docs/operations/admin-sso.md).

Security Notes

  • State + Nonce sind PFLICHT — ohne State ist CSRF auf Callback möglich; ohne Nonce ist Token-Replay möglich. Beides MUSS in Tests verifiziert sein (negative-Tests mit tampered Werten).
  • PKCE auch mit Confidential-Client — best practice, schützt zusätzlich gegen Authorization-Code-Interception falls Client-Secret leaked.
  • code_verifier niemals loggen — Sentry-Breadcrumb-Filter prüfen, dass das Challenge-Cookie nicht in Breadcrumbs landet.
  • ID-Token-Signatur-Verifikation MUSS gegen JWKS gehen — openid-client macht das automatisch, aber bei Library-Upgrades regression-testen.
  • email_verified=true prüfen — sonst kann jemand bei Authentik einen Account mit beliebiger Email anlegen, Email-Verifikation umgehen, und durch JIT-Provisioning einen Existing-Admin per Email-Match übernehmen.
  • Group-Claim ist trust-anchored — die App vertraut blind dem Group-Claim aus Authentik. Daher MUSS Authentik selbst gehärtet sein (siehe #81 — Public-Registration aus, MFA-Pflicht für Admin-Group).
  • Fallback-Login ist Bypass des gesamten IdP-Schutzes — Allowlist muss kurz sein (1-2 Bootstrap-Accounts max), Audit-Severity warn, Sentry-Breadcrumb, optional Slack-Alert. Doku-File enthält Operator-Verpflichtung: nach Fallback-Nutzung sofort wieder ausschalten.
  • App-MFA-Gate-Bypass via Session-Field-Tampering — lastAppMfaAt MUSS server-side gespeichert sein (Session-Store, nicht im Client-Cookie); im Cookie wäre Modifikation möglich.
  • Logout-Idempotenz — auch wenn id_token schon expired ist, lokale Session-Cleanup MUSS funktionieren (sonst kann ein User „gefangen" sein).
  • Redirect-URI-Whitelist — Authentik-seitig nur exakt die konfigurierten URIs zulassen, keine Wildcards. App-seitig die returnTo-Query-Param sanitizen (nur same-origin-Pfade).
  • Session-Fixation-Schutz — App-Session-ID nach erfolgreichem Callback rotieren (neue Session-ID generieren).
  • Brute-Force-Schutz auf Fallback-Login — bestehendes Rate-Limit (App-seitig oder via Phase 03 shared-store) MUSS auch für /admin/login-Form gelten, auch wenn Fallback nur für 1-2 Accounts gedacht ist.
  • Audit-Event-Inhalt — keine Secrets/Token in meta-Feld; ssoSubjectId ist okay (opake ID), aber id_token raw NIEMALS persistieren in AuditEvent.

Subagent Recommendations

  • Research: Explore-Subagent mit Brief: "Recherchiere openid-client-Version-Compatibility mit Node-Version aus package.json. Prüfe ob es bekannte Bugs/CVEs in der aktuellen Stable gibt. Liefere Migrations-Notizen falls Major-Bump nötig."
  • Planning: Plan-Subagent mit dieser Detail-MD + Verweis auf bestehende apps/web/app/services/auth/* als Input — soll konkreten Implementations-Reihenfolge-Plan ausarbeiten, insbesondere wie Bestands-Session-Library wiederverwendet wird (statt parallelem Stack).
  • Implementation (Modul-Skelett + Client + State): general-purpose-Subagent mit Brief: "Implementiere Steps 1, 3, 4 atomar. Output: 3 Commits mit Test-Stubs."
  • Implementation (DB + JIT): separater general-purpose-Subagent für Steps 2, 7. Brief: "Erweitere AdminUser-Modell, generiere Migration, implementiere JIT-Provisioning + Group-Mapping inkl. Unit-Tests."
  • Implementation (Routes): separater general-purpose-Subagent für Steps 5, 6, 8. Brief: "Implementiere Login/Callback/Logout-Routes streng nach RR7-Framework-Mode-Patterns (./+types/..., loader/action, kein react-router-dom). Nach jeder Route pnpm run typecheck."
  • Implementation (UI + Fallback-Guards): separater general-purpose-Subagent für Steps 9, 10. Brief: "Update Admin-Login-Page, Fallback-Toggle behind Env-Flag, Server-Side-Guards, Audit-Wiring für Fallback-Pfad."
  • Implementation (App-MFA-Gate): separater general-purpose-Subagent für Step 11. Brief: "Implementiere App-MFA-Gate mit Enrollment + Challenge-Routes. Wiederverwende otpauth aus #26, baue NICHT eigenes TOTP."
  • Tests: separater general-purpose-Subagent für komplette Test-Suite (Unit + Integration + Playwright-E2E). Brief: "Schreibe alle Tests aus Test-Requirements, führe lokal gegen Staging-Authentik aus, achte auf Coverage-Gate."
  • Doku: separater general-purpose-Subagent für Step 14. Brief: "Schreibe docs/operations/admin-sso.md mit allen Mindest-Sections. Mermaid-Diagramm für Login-Flow + Logout-Flow + Fallback-Flow."
  • Verification: gsd-verifier oder general-purpose für Acceptance-Criteria-Check + manuelles Durchspielen der Fallback-Recovery-Procedure.
  • Code-Review: gsd-code-reviewer nach Task-Completion mit Fokus auf: Crypto-Korrektheit (State/Nonce/PKCE), Audit-Vollständigkeit, Fallback-Hardening, Session-Fixation-Schutz, Permission-Mapping-Korrektheit.

Staging-Deployment-Steps

  1. Branch agent/phase-09-admin-oidc-login erstellen + pushen
  2. Voraussetzung: Authentik auf Staging läuft (#81 completed), toolctrl-admin-panel-Provider aktiv
  3. In Authentik-UI: Client-Secret für toolctrl-admin-panel generieren/abrufen, in Coolify-Vault als AUTHENTIK_ADMIN_CLIENT_SECRET ablegen
  4. Coolify-Web-Service-Env-Vars setzen:
    • AUTHENTIK_ISSUER_URL=https://auth.<staging-domain>/application/o/toolctrl-admin-panel/
    • AUTHENTIK_ADMIN_CLIENT_ID=toolctrl-admin-panel
    • AUTHENTIK_ADMIN_CLIENT_SECRET=<aus-vault>
    • AUTHENTIK_ADMIN_REDIRECT_URI=https://admin.<staging-domain>/auth/admin/callback
    • AUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI=https://admin.<staging-domain>/admin/login?logged_out=1
    • ADMIN_FALLBACK_LOGIN_ENABLED=true (initial für Bootstrap, später auf false)
    • ADMIN_FALLBACK_LOGIN_EMAILS=bootstrap@<staging-domain>
  5. In Authentik-UI: zwei Test-User anlegen:
    • admin-test@<staging-domain> in Group toolctrl-admin, MFA-TOTP enrolled
    • staff-test@<staging-domain> in Group toolctrl-staff, MFA-TOTP enrolled
  6. Coolify deployt den Branch, DB-Migration läuft automatisch
  7. Smoke-Tests im Browser:
    • https://admin.<staging-domain>/admin/login → SSO-Button sichtbar, Fallback-Toggle sichtbar (weil Flag true)
    • SSO-Button klicken → Authentik-Login → admin-test einloggen + MFA → Redirect zu /admin → Admin-Dashboard mit Rolle super_admin sichtbar (Test via Debug-Endpoint oder UI-Element das Rolle zeigt)
    • DB-Check: AdminUser für admin-test@… existiert mit ssoSubjectId, ssoProvider='authentik', role='super_admin', lastSsoLoginAt gesetzt
    • Logout-Test: Logout-Button → Authentik-Session-End → Redirect zu /admin/login?logged_out=1, Erfolgs-Banner sichtbar
    • staff-test Login analog, role='staff' verifizieren
  8. JIT-Negative-Test:
    • In Authentik dritten User anlegen random-test@… OHNE Group-Mitgliedschaft
    • SSO-Login versuchen → Callback returnt 403 mit klarer Error-Message, AuditEvent admin.login.sso.failure mit reason forbidden_group in DB
  9. App-MFA-Gate-Test:
    • admin-test versucht Impersonation (oder eine andere sensible Action) → Redirect zu /admin/security/mfa-enroll (beim ersten Mal) oder /admin/security/mfa-challenge
    • TOTP-Code eingeben → Action wird durchgeführt, AuditEvent admin.mfa.app.challenge.success
    • Sofortige Wiederholung derselben sensiblen Action → keine erneute Challenge
    • Per Test-Helper lastAppMfaAt auf > 15 Min zurücksetzen → erneute Challenge erscheint
  10. Fallback-Test (mit Flag true):
    • Fallback-Toggle aufklappen → Email + Passwort vom Bootstrap-Admin → Login erfolgreich
    • AuditEvent admin.login.fallback.success mit severity=warn in DB
    • Sentry-Breadcrumb mit warn-Level sichtbar
  11. Fallback-Test (mit Flag false):
    • Coolify-Env auf ADMIN_FALLBACK_LOGIN_ENABLED=false, Redeploy
    • Login-Page: Fallback-Toggle nicht mehr sichtbar
    • Direct-POST auf Fallback-Endpoint via curl → 403, AuditEvent admin.login.fallback.failure
  12. Fallback-Recovery-Drill:
    • Simuliere Authentik-Down: Authentik-Stack in Coolify stoppen
    • https://admin.<staging-domain>/admin/login → SSO-Button führt zu Fehler-Banner (Discovery-Failure)
    • Operator setzt ADMIN_FALLBACK_LOGIN_ENABLED=true + Bootstrap-Email in Allowlist, Redeploy
    • Fallback-Login funktioniert
    • Authentik-Stack wieder hochfahren, Smoke-Login → SSO funktioniert wieder
    • Operator setzt Flag wieder false
    • Drill in Progress-Log dokumentieren
  13. E2E-Playwright-Suite gegen Staging laufen lassen: pnpm e2e --grep "admin-sso"
  14. Falls alles grün: PR → main mergen; Production-Rollout erst nach erfolgreichem Production-Authentik-Setup + Production-Fallback-Recovery-Drill

Deviations from Plan

  • Login route consolidation. Spec called for editing apps/web/app/routes/admin.login.tsx. The actual repo serves the admin login through the host-aware apps/web/app/routes/login.tsx (admin host detected via getHostRoutingContextFromRequest). The SSO CTA and fallback gating land inside the existing shared route — tenant traffic is unaffected.
  • Step-12 audit wrapper kept thin. apps/web/app/modules/admin-sso/audit.server.ts delegates to the existing @toolctrl/db/audit-events.server boundary rather than introducing a parallel audit pipeline. The severity=warn signal for fallback paths is carried through metadata + Sentry breadcrumb (when the reporter is wired), since the AuditEvent model itself does not have a severity column.
  • App-MFA gate reuses existing step-up plumbing. Phase 01 #26 consolidated TOTP already ships enforceAdminMfa + checkMfaStepUpState. requireAdminMfaForAction is a thin wrapper layering the spec's SensitiveAdminAction taxonomy on top — no separate cache, no new TOTP code. The 15-min spec figure is already encoded as MFA_STEP_UP_MAX_AGE_MS = 10 * 60 * 1000 in the existing module; we did not change it to avoid colliding with the Phase 01 contract.
  • App-session id_token storage. Stored in a dedicated HMAC-signed admin_sso_id_token cookie scoped to /auth/admin rather than mutated into the React-Router session cookie. Avoids bloating every admin request and keeps the logout-hint blast radius small.

Progress Log

  • 2026-05-17 — 903d0cb0 — extend AdminUser prisma schema with sso fields
  • 2026-05-17 — 87e44be3 — add admin-sso module with openid-client wrapper
  • 2026-05-17 — ee3c8678 — add state/nonce/pkce cookie helpers
  • 2026-05-17 — e2bf9f4b — add claims and jit-provisioning helpers
  • 2026-05-17 — e5f8508d — add login callback and logout routes
  • 2026-05-17 — dd87785c — ignore storybook-static in hardcoded-strings scan
  • 2026-05-17 — 7fb28a70 — integrate sso button into admin login page
  • 2026-05-17 — 79b54c14 — raise brand-literal baseline for authentik group ids
  • 2026-05-17 — 261987cd — add app-mfa gate for sensitive admin actions
  • 2026-05-17 — 550f1b9a — audit admin mfa gate challenges
  • 2026-05-17 — 65255425 — env vars and ops doc

Status in_progress (code-complete, awaits-authentik-deploy). Final completion gate requires operator-side Authentik staging deploy + end-to-end verification per ## Staging-Deployment-Steps.

Lessons Learned

(Wird am Task-Ende ergänzt — typische Stolperfallen: openid-client-API-Bruch zwischen Major-Versionen, JWKS-Cache-Staleness nach Authentik-Key-Rotation, Cookie-SameSite-Verhalten bei Subdomain-Setup, App-Session-Rotation nach Callback ohne Existing-Session-Loss, Fallback-Allowlist-Vergessen-Auszuschalten als Operator-Klassiker.)