gwoe-antragspruefer/docs/adr/0012-debug-auth-token-bypass.md

0012 — DEBUG_AUTH_TOKEN-Bypass für Diagnose-Sessions

Status	accepted
Datum	2026-05-06
Refs	commit f8cfa42 (Bypass), d853101 (Logging+Rotation), MEMORY/reference_debug_auth_bypass.md

Kontext

Bei UI-Bugs auf gwoe-dev.toppyr.de brauche ich (oder ein Diagnose- Tool) Zugriff auf admin-only HTML-Pages und API-Endpoints. Der reguläre Pfad ist Keycloak-Login mit User-Passwort — funktioniert für den User selbst, aber nicht für headless Tests, die in CI oder im Background laufen.

Vor Phase 11b war der einzige Weg: Browser-Console-Output vom User abfragen. Das ist langsam (User muss DevTools öffnen, Screenshot schicken, Kontext erklären) und unsicher (User muss erinnern, wo er geklickt hat).

Optionen

Option A — User-Passwort fest hinterlegen

Service-Account mit festem Passwort, in .env gespeichert. Test- Skripte loggen sich darüber ein.

• Pro: funktioniert mit echtem Keycloak-Flow.
• Kontra: Service-Account ist ein vollwertiger User in Keycloak, Passwort-Rotation muss synchron mit Keycloak geschehen. Login-Flow ist langsam (3 HTTP-Roundtrips).

Option B — JWT mit langer Laufzeit pre-generieren

Keycloak-Admin-API generiert ein JWT mit z.B. 7 Tagen Laufzeit, in .env ablegen. Tests senden es als Bearer-Header.

• Pro: kein Login-Flow nötig.
• Kontra: 7 Tage langes JWT widerspricht der Token-Lifecycle- Idee. Bei Leak: Keycloak kennt das Token nicht und kann es nicht invalidieren (außer durch Sessions-Revocation des Users).

Option C — Eigenes ENV-Secret als Bypass-Token

Eine zusätzliche Header-/Query-Pruefung im require_auth-Pfad: wenn X-Debug-Token (oder ?__debug_token=) dem ENV-Secret entspricht, wird ein Mock-Admin-User zurückgegeben.

• Pro: kein Keycloak-Roundtrip, einfach rotierbar (ENV-Update + Container-Recreate), inactive bei leerem ENV.
• Kontra: parallele Auth-Pfad neben Keycloak — Risiko bei Audit- Anfragen, ob das System tatsächlich nur über Keycloak authentifiziert.

Entscheidung

Option C umgesetzt mit folgender Härtung:

1. ENV-binär: DEBUG_AUTH_TOKEN= (leer) → Bypass komplett aus. Default in docker-compose.dev.yml ist ${DEBUG_AUTH_TOKEN:-} → wenn nicht in .env, kein Bypass.
2. Nur dev-compose reicht die ENV durch. Prod-docker-compose.yml referenziert sie nicht, der Container sieht sie nicht — selbst wenn jemand sie auf vserver setzt.
3. Mock-User-Rollen: ["admin", "gwoe-admin"] — keine echten Keycloak-Rollen, sodass z.B. audit_log zwischen Bypass und regulärem Login unterscheiden kann (sub=debug-user vs. echte UUID).
4. Audit-Logging: jeder Use schreibt in auth_bypass_uses (used_at, client_ip, path, user_agent) plus logger.warning. Best-Effort, schlägt unter keinen Umständen den Request fehl.
5. Rotation: scripts/rotate-debug-token.sh läuft wöchentlich (Sonntag 04:00 Cron) und generiert ein neues secrets.token_urlsafe(32) in .env mit docker compose up -d --force-recreate.
6. Manuelle Rotation ist trivial:

   NEW=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
   ssh vserver "sed -i 's|^DEBUG_AUTH_TOKEN=.*|DEBUG_AUTH_TOKEN='$NEW'|' /opt/gwoe-antragspruefer-dev/.env"
   

Konsequenzen

Positiv

• Headless Smoketests (siehe tests/e2e/test_smoke_browser.py) laufen ohne Keycloak-Setup. 9 Tests in 52 s gegen Live-System.
• Diagnose-Sessions (Playwright + Console-Hook) sind möglich, ohne User-Passwort zu kennen oder zu erfragen.
• Bei Audit-Anfragen: auth_bypass_uses-Tabelle liefert vollständige Use-Historie mit IP+Path.

Negativ

• Parallele Auth-Pfad. Wenn das ENV-Secret leakt, hat der Angreifer Admin-Zugang zu dev. Mitigation: nur dev, Rotation, Logging.
• Bypass-User hat keine echte Identität — manche Endpoints wie Mail-Versand würden mit email="debug@local" arbeiten. Keine echten Mails an reale Empfänger möglich (Tabu-Regel), aber defensives Coding nötig.

Folgen für andere ADRs

• 0005 Keycloak SSO mit Dev-Bypass-Fallback: das war der „kein-Keycloak-konfiguriert"-Bypass. ADR 0012 ergänzt einen zweiten Bypass für konfiguriertes Keycloak — beide sind orthogonal und nicht konkurrierend.
• Folge-Issue: wenn prod-Diagnose nötig wird, könnte ein separater prod-Bypass mit eigener Kontrollebene (z.B. HMAC-signierte Tokens, IP-Whitelist) sinnvoll sein.