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.tsapps/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-Providertoolctrl-admin-panelmuss existieren, Groups + Mapping müssen konfiguriert sein01-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 (inapps/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, generiertstate(CSRF) +nonce(Replay-Schutz), persistiert beide in signed/encrypted Cookie (HttpOnly, Secure, SameSite=Lax, kurze TTL), redirected zu Authentik-authorization_endpointGET /auth/admin/callback?code=…&state=…— verifiziert State-Cookie, tauscht Code gegen Tokens viatoken_endpoint(mit PKCE-Verifier + Client-Secret), verifiziert ID-Token-Signatur via Authentik-JWKS, validiertiss/aud/exp/nonce, extrahiertsub+groups+email+nameClaims, ruft JIT-Provisioning auf, setzt App-Session-Cookie, redirected zu/adminPOST /auth/admin/logout— killt lokale Session, redirected zu Authentik-end_session_endpointmitid_token_hint+post_logout_redirect_uri
JIT-Provisioning-Regel (in jit-provisioning.server.ts):
- Lookup
AdminUserviassoSubjectId(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 neuenAdminUsermit Rolle aus Group-Mapping; nein: 403 (Login abgelehnt)
- Fallback-Lookup via
- Wenn gefunden: update
ssoGroups,lastSsoLoginAt,email(falls geändert),name. Updaterolegemäß 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-Flagtrue - 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
warninAuditEventUND 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
-
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
- Files:
-
DB-Schema: AdminUser erweitern
- Files:
prisma/schema.prisma,prisma/migrations/<ts>_admin_user_sso_fields/migration.sql - Aktion:
AdminUserum 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
- Files:
-
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)
- Discovery via
- Commit:
09-authentik/admin-oidc: implement openid-client initialization
- Files:
-
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(viagenerators.codeVerifier()aus openid-client),code_challenge(viagenerators.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
- Files:
-
Login-Route
- Files:
apps/web/app/routes/auth.admin.login.tsx,apps/web/app/routes.ts(Route registrieren) - Aktion:
loaderruftclient.authorizationUrl({state, code_challenge, code_challenge_method:'S256', nonce, scope:'openid profile email groups'}), setzt Challenge-Cookie, returnedredirect(authorizationUrl) - Kein Component (reine Redirect-Route)
- Type-Generation:
pnpm run typechecknach Route-Registration - Commit:
09-authentik/admin-oidc: add /auth/admin/login route
- Files:
-
Callback-Route
- Files:
apps/web/app/routes/auth.admin.callback.tsx,apps/web/app/routes.ts - Aktion:
loader:consumeLoginChallenge(request)→ state/nonce/verifier aus Cookieclient.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ätzlichemail_verified=trueprüfen (falls Claim vorhanden) - Claims extrahieren:
sub,email,name,groups jitProvision(claims)aufrufen (Step 7) → liefertAdminUser- App-Session-Cookie setzen via existierende Admin-Session-Library,
id_token(raw) zusätzlich in Session speichern (für RP-Initiated-Logout) AuditEventschreiben:admin.login.sso.success,actorAdminUserId,meta: {ssoSubjectId, groups, ip, userAgent}- Bei jedem Error:
AuditEventadmin.login.sso.failuremit Error-Klasse + Sentry-Capture; User-redirect zu/admin/login?error=sso_failed - Success-Redirect zu
/admin(oder zurreturnTo-Query-Param falls vorhanden + safe)
- Commit:
09-authentik/admin-oidc: add /auth/admin/callback route with token exchange and verification
- Files:
-
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>nulljitProvision({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:
rolere-syncen (Authentik = Source-of-Truth),ssoGroups,lastSsoLoginAt,email/nameaktualisieren
- Lookup via
- 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
- Files:
-
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_tokenaus App-Session - Lokale Session killen (App-Cookie destroyen, Session-Store-Eintrag löschen)
AuditEventadmin.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)
- Lese
- Wenn
id_tokenfehlt (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
- Files:
-
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_failedQuery-Param: rote Error-Banner mit Hinweis auf Operator-Kontakt - Wenn
logged_out=1Query-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:
AuditEventadmin.login.fallback.successmit Severitywarn+ Sentry-Breadcrumb - Bei Fail:
admin.login.fallback.failure
- Primary-CTA: großer Button „Login mit SSO" → linked auf
- Type-Generation:
pnpm run typecheck - Commit:
09-authentik/admin-oidc: update admin login page with SSO CTA and gated fallback
- Files:
-
Fallback-Login-Guards (Server-Side)
- Files:
apps/web/app/services/auth/admin-session.server.ts(modifiziert oder neu) - Aktion:
assertFallbackLoginAllowed(email: string)— wirft 403 wennADMIN_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
- Files:
-
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
actionKeyinSENSITIVE_ADMIN_ACTIONSUND letzter erfolgreicher App-MFA-Challenge der Session älter als 15 Min ist: redirect zu/admin/security/mfa-challenge?returnTo=<encoded> - Nutzt
verifyTotpTokenausapps/web/app/services/auth/totp.server.ts(konsolidierte otpauth aus #26)
- Wenn
- 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 zureturnTo - Sensible Actions (in ihren jeweiligen Action-Handlern) rufen
await requireAppMfa(request, 'impersonation.start')als ersten Step
- Konstante
- Commit:
09-authentik/admin-oidc: add app-level MFA gate for sensitive admin actions
- Files:
-
Audit-Events verdrahten
- Files:
apps/web/app/modules/admin-sso/audit.server.ts(neu, dünner Wrapper) — schreibt in existierendesAuditEvent-Modell - Events:
admin.login.sso.successadmin.login.sso.failure(mit Error-Klasse)admin.login.fallback.success(severitywarn)admin.login.fallback.failureadmin.logout.ssoadmin.mfa.app.challenge.successadmin.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
- Files:
-
Env-Vars + .env.example
- Files:
apps/web/.env.example(oder zentrales.env.example),apps/web/app/utils/env.server.ts(Schema-Erweiterung mitzod) - Keys:
AUTHENTIK_ISSUER_URL=https://auth.example.com/application/o/toolctrl-admin-panel/AUTHENTIK_ADMIN_CLIENT_ID=toolctrl-admin-panelAUTHENTIK_ADMIN_CLIENT_SECRET=(Coolify-Vault, niemals committen)AUTHENTIK_ADMIN_REDIRECT_URI=https://admin.example.com/auth/admin/callbackAUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI=https://admin.example.com/admin/login?logged_out=1AUTHENTIK_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=falseADMIN_FALLBACK_LOGIN_EMAILS=(komma-separierte Allowlist, leer per Default)
- Zod-Schema: alle URLs als
z.string().url(), Boolean alsz.enum(['true','false']).transform(v => v === 'true') - Commit:
09-authentik/admin-oidc: add SSO env vars and zod schema
- Files:
-
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-adminodertoolctrl-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:
- Operator setzt
ADMIN_FALLBACK_LOGIN_ENABLED=true+ADMIN_FALLBACK_LOGIN_EMAILS=bootstrap@example.comin Coolify-Env, Redeploy - Login mit Bootstrap-Admin via Email/Passwort
- Authentik wiederherstellen (siehe
docs/operations/authentik-setup.mdDisaster-Recovery) - Fallback wieder ausschalten + Sentry-Alert auflösen
- Operator setzt
- 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 (Scopegroupsnicht in Authentik-Provider konfiguriert)
- Commit:
09-authentik/admin-oidc: document SSO operations and fallback recovery
- Files:
-
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
AdminUserbekommenssoProvider = null,ssoSubjectId = null(Default ehnull, 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)
- Files:
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'])→nullmapGroupsToRole([])→null
apps/web/app/modules/admin-sso/state.server.test.ts:createLoginChallenge()generiert distincte state/nonce/verifierconsumeLoginChallengereturned 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 mitrole='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 →
rolewird beim nächsten Login re-synced - Concurrent JIT-Calls für gleichen User → keine Duplicate-Errors (Unique-Constraint greift)
- Neuer User mit
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):assertFallbackLoginAllowedwirft wenn Env-Flagfalse- wirft wenn Email nicht in Allowlist
- passt durch wenn beide Bedingungen erfüllt
- Integration-Tests (Vitest mit Mock-Authentik via
mswoder 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
- Login-Flow End-to-End (Mock-Authentik): GET
- 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.successmitwarn-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-challengeredirected; 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% aufclaims.server.tsundstate.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.mdMANUELL 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/logoutfunktional und registriert inapps/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=trueUND Email inADMIN_FALLBACK_LOGIN_EMAILS - App-MFA-Gate für
SENSITIVE_ADMIN_ACTIONSfunktioniert (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 typecheckgrün.env.exampleenthält alle neuen Keys aus Step 13, mit kommentierten Beispielwertendocs/operations/admin-sso.mdangelegt 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-FlagADMIN_SSO_ENABLED=falsedeaktiviert werden (Empfehlung: dieser Flag wird zusätzlich in Step 13 implementiert, defaulttrue). - DB-Migration revertieren:
- Migration ist additive (nur neue Spalten + Index), Rollback via
prisma migrate resolve+ manuellemALTER TABLE DROP COLUMN-SQL - Down-Migration in Migration-Folder hinterlegen
- Kein Daten-Loss (SSO-Felder waren
nullable)
- Migration ist additive (nur neue Spalten + Index), Rollback via
- 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-
.envupdaten, 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 indocs/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_verifierniemals 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=trueprü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 —
lastAppMfaAtMUSS server-side gespeichert sein (Session-Store, nicht im Client-Cookie); im Cookie wäre Modifikation möglich. - Logout-Idempotenz — auch wenn
id_tokenschon 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;ssoSubjectIdist okay (opake ID), aberid_tokenraw NIEMALS persistieren in AuditEvent.
Subagent Recommendations
- Research:
Explore-Subagent mit Brief: "Recherchiereopenid-client-Version-Compatibility mit Node-Version auspackage.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 bestehendeapps/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, keinreact-router-dom). Nach jeder Routepnpm 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: "Schreibedocs/operations/admin-sso.mdmit allen Mindest-Sections. Mermaid-Diagramm für Login-Flow + Logout-Flow + Fallback-Flow." - Verification:
gsd-verifierodergeneral-purposefür Acceptance-Criteria-Check + manuelles Durchspielen der Fallback-Recovery-Procedure. - Code-Review:
gsd-code-reviewernach Task-Completion mit Fokus auf: Crypto-Korrektheit (State/Nonce/PKCE), Audit-Vollständigkeit, Fallback-Hardening, Session-Fixation-Schutz, Permission-Mapping-Korrektheit.
Staging-Deployment-Steps
- Branch
agent/phase-09-admin-oidc-loginerstellen + pushen - Voraussetzung: Authentik auf Staging läuft (#81 completed),
toolctrl-admin-panel-Provider aktiv - In Authentik-UI: Client-Secret für
toolctrl-admin-panelgenerieren/abrufen, in Coolify-Vault alsAUTHENTIK_ADMIN_CLIENT_SECRETablegen - Coolify-Web-Service-Env-Vars setzen:
AUTHENTIK_ISSUER_URL=https://auth.<staging-domain>/application/o/toolctrl-admin-panel/AUTHENTIK_ADMIN_CLIENT_ID=toolctrl-admin-panelAUTHENTIK_ADMIN_CLIENT_SECRET=<aus-vault>AUTHENTIK_ADMIN_REDIRECT_URI=https://admin.<staging-domain>/auth/admin/callbackAUTHENTIK_ADMIN_POST_LOGOUT_REDIRECT_URI=https://admin.<staging-domain>/admin/login?logged_out=1ADMIN_FALLBACK_LOGIN_ENABLED=true(initial für Bootstrap, später auffalse)ADMIN_FALLBACK_LOGIN_EMAILS=bootstrap@<staging-domain>
- In Authentik-UI: zwei Test-User anlegen:
admin-test@<staging-domain>in Grouptoolctrl-admin, MFA-TOTP enrolledstaff-test@<staging-domain>in Grouptoolctrl-staff, MFA-TOTP enrolled
- Coolify deployt den Branch, DB-Migration läuft automatisch
- 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 Rollesuper_adminsichtbar (Test via Debug-Endpoint oder UI-Element das Rolle zeigt) - DB-Check:
AdminUserfüradmin-test@…existiert mitssoSubjectId,ssoProvider='authentik',role='super_admin',lastSsoLoginAtgesetzt - Logout-Test: Logout-Button → Authentik-Session-End → Redirect zu
/admin/login?logged_out=1, Erfolgs-Banner sichtbar - staff-test Login analog,
role='staff'verifizieren
- 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.failuremit reasonforbidden_groupin DB
- In Authentik dritten User anlegen
- 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
lastAppMfaAtauf > 15 Min zurücksetzen → erneute Challenge erscheint
- admin-test versucht Impersonation (oder eine andere sensible Action) → Redirect zu
- Fallback-Test (mit Flag
true):- Fallback-Toggle aufklappen → Email + Passwort vom Bootstrap-Admin → Login erfolgreich
- AuditEvent
admin.login.fallback.successmitseverity=warnin DB - Sentry-Breadcrumb mit
warn-Level sichtbar
- 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, AuditEventadmin.login.fallback.failure
- Coolify-Env auf
- 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
- E2E-Playwright-Suite gegen Staging laufen lassen:
pnpm e2e --grep "admin-sso" - 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-awareapps/web/app/routes/login.tsx(admin host detected viagetHostRoutingContextFromRequest). 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.tsdelegates to the existing@toolctrl/db/audit-events.serverboundary rather than introducing a parallel audit pipeline. Theseverity=warnsignal 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.requireAdminMfaForActionis 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 asMFA_STEP_UP_MAX_AGE_MS = 10 * 60 * 1000in 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_tokencookie scoped to/auth/adminrather 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.)