Auth: Migration- und Deployment-Dokumentation

[jurei733]

Parent: #151

Ziel

Auth-/OIDC-Aenderungen sind fuer Betrieb und Deployment nachvollziehbar dokumentiert.

Akzeptanzkriterien

• Migrationsschritte fuer bestehende Deployments sind dokumentiert.
• Env-Variablen, Keycloak-Clients und Rollen sind beschrieben.
• Lokale Entwicklung und Produktivbetrieb sind getrennt erklaert.
• Troubleshooting fuer typische Auth-Fehler ist enthalten.

[jurei733]

Stand 2026-06-02: Ich habe die offenen und jüngsten PRs gegen die Akzeptanzkriterien geprüft.

Relevanter PR ist #448 (Feature/OIDC authenticate flow). Der PR enthält bereits wesentliche Vorarbeiten für dieses Issue, u. a. OIDC-Dokumentation (docs/oidc-authentication-de.md, docs/oidc-authentication.md), Env-Template-Änderungen, Keycloak-Realm-/Client-Konfiguration und ein Migrationsskript (scripts/migration/2.0.0.sh). #412 ist nur der geschlossene Vorgänger von #448; #628 ist Auth-nah, betrifft aber Bootstrap/Healthcheck und nicht diese Migrations-/Deployment-Dokumentation.

Einschätzung: teilweise umgesetzt, aber noch nicht abschlussreif für #571.

Abgleich mit den Akzeptanzkriterien:

• Migrationsschritte für bestehende Deployments: teilweise vorhanden, aber noch zu generisch. Es fehlt eine klare Update-Checkliste für bestehende Installationen. Außerdem sollte das Migrationsskript geprüft werden; insbesondere wirkt die Behandlung von OAUTH2_REDIRECT_URL/neuen OIDC-Variablen noch nicht vollständig konsistent.
• Env-Variablen, Keycloak-Clients und Rollen: weitgehend beschrieben. Allerdings gibt es Inkonsistenzen bei Realm-/Endpoint-Beispielen (coding-box vs. /realms/iqb), die vor dem Abschluss bereinigt werden sollten.
• Lokale Entwicklung und Produktivbetrieb getrennt erklärt: teilweise. Dev- und Prod-Templates sind vorhanden, die Doku vermischt aber stellenweise Entwicklungsbefehle wie make dev-up mit Deployment-Hinweisen. Der Produktiv-/Update-Pfad sollte klarer dargestellt werden.
• Troubleshooting für typische Auth-Fehler: gut abgedeckt. Die Doku enthält typische Fälle zu Env, Redirect URI, PKCE, Token Exchange, Keycloak, CORS, SSL und Logs.

Zusätzlich ist #448 aktuell offen und merge-konfliktbehaftet (DIRTY/conflicting), obwohl die Checks grün sind. Daher sollte #571 aus meiner Sicht offen bleiben, bis #448 konfliktfrei ist und die genannten Doku-/Konsistenzpunkte nachgezogen wurden.