# 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:
   ```bash
   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.