Docs: Keycloak-Setup How-to + ADR-Index aktualisiert

docs/adr/README.md

@@ -21,6 +21,7 @@ und Konsequenzen. Format inspiriert von [Michael Nygard](https://cognitect.com/b
 | [0002](0002-adapter-architecture.md) | Adapter-Pattern mit ParlamentAdapter-Basisklasse + Registry | accepted | 2026-04-10 |
 | [0003](0003-citation-property-tests.md) | Sub-D Property-Verification: Zitate als Substring der zitierten PDF-Seite | accepted | 2026-04-10 |
 | [0004](0004-deployment-workflow.md) | Docker Compose Deploy mit DB-/Reports-Volume und SN-XML-Sonderpfad | accepted | 2026-04-10 |
+| [0005](0005-keycloak-sso-with-dev-bypass.md) | Keycloak SSO mit Dev-Bypass für Read/Write-Trennung | accepted | 2026-04-10 |
 
 ## Wann ADR, wann nicht
 

docs/how-to/keycloak-setup.md

@@ -0,0 +1,89 @@
+# Keycloak-Client einrichten
+
+Schritt-für-Schritt-Anleitung zum Aktivieren der Authentifizierung
+auf `gwoe.toppyr.de`. Voraussetzung: Admin-Zugang zu
+`sso.toppyr.de` (Keycloak).
+
+## 1. Client anlegen
+
+1. Öffne `https://sso.toppyr.de/admin/master/console/`
+2. Wechsle zum Realm **collaboration** (Dropdown oben links)
+3. Navigiere zu **Clients** → **Create client**
+4. Einstellungen:
+
+| Feld | Wert |
+|---|---|
+| Client type | OpenID Connect |
+| Client ID | `gwoe-antragspruefer` |
+| Name | GWÖ-Antragsprüfer |
+| Always display in UI | Off |
+
+5. **Next** → Capability config:
+
+| Feld | Wert |
+|---|---|
+| Client authentication | **Off** (public client für Browser-Flow) |
+| Authorization | Off |
+| Standard flow | **On** |
+| Direct access grants | Off |
+
+6. **Next** → Login settings:
+
+| Feld | Wert |
+|---|---|
+| Root URL | `https://gwoe.toppyr.de` |
+| Home URL | `https://gwoe.toppyr.de` |
+| Valid redirect URIs | `https://gwoe.toppyr.de/*` |
+| Valid post logout redirect URIs | `https://gwoe.toppyr.de/*` |
+| Web origins | `https://gwoe.toppyr.de` |
+
+7. **Save**
+
+## 2. Verifizieren
+
+Nach dem Speichern sollte der "Anmelden"-Button auf `gwoe.toppyr.de`
+zum Keycloak-Login führen (statt "client not found").
+
+Schnelltest via curl:
+
+```bash
+curl -s "https://sso.toppyr.de/realms/collaboration/protocol/openid-connect/auth?client_id=gwoe-antragspruefer&redirect_uri=https://gwoe.toppyr.de/&response_type=code&scope=openid" -o /dev/null -w "%{http_code}"
+# Erwartet: 200 (Login-Seite), nicht 400 (client not found)
+```
+
+## 3. Optional: Gruppen/Rollen konfigurieren
+
+Für die künftigen Features Bookmarks/Kommentare (#94) werden
+Keycloak-Gruppen benötigt. Diese können später angelegt werden:
+
+1. **Realm roles** → Create role → z.B. `gwoe-editor`, `gwoe-admin`
+2. **Groups** → Create group → z.B. "Fraktion SPD Hagen", "AG Klima"
+3. Nutzer den Gruppen zuweisen
+4. In den Client-Scopes sicherstellen, dass `realm_access.roles` im
+   JWT-Token enthalten ist (Default bei Keycloak ≥ 18)
+
+Die `auth.py`-Middleware liest `realm_access.roles` aus dem JWT und
+stellt sie über `user["roles"]` bereit.
+
+## 4. ENV-Variablen (bereits konfiguriert)
+
+Die docker-compose.yml enthält bereits:
+
+```yaml
+environment:
+  - KEYCLOAK_URL=https://sso.toppyr.de
+  - KEYCLOAK_REALM=collaboration
+  - KEYCLOAK_CLIENT_ID=gwoe-antragspruefer
+```
+
+Solange diese gesetzt sind, ist Auth aktiv. Zum Deaktivieren
+(Dev-Modus): `KEYCLOAK_URL` auf leer setzen.
+
+## Troubleshooting
+
+| Problem | Lösung |
+|---|---|
+| "client not found" | Client-ID Tippfehler oder Client nicht im richtigen Realm |
+| 401 bei POST obwohl eingeloggt | Token abgelaufen → neu einloggen; oder JWKS-Cache (1h) hat den neuen Key noch nicht |
+| "Anmelden" tut nichts | Browser-Konsole prüfen; `/api/auth/login-url` muss `enabled: true` zurückgeben |
+| Alles offen trotz Keycloak | `KEYCLOAK_URL` in `.env` auf dem Server prüfen — wenn leer, ist Dev-Modus aktiv |

mkdocs.yml

@@ -27,6 +27,8 @@ nav:
     - Adapter-Capabilities: reference/adapter-capabilities.md
     - Datenmodelle: reference/models.md
     - Embeddings & Citations: reference/embeddings.md
+  - How-to:
+    - Keycloak einrichten: how-to/keycloak-setup.md
   - Archiv:
     - Übersicht: archive/index.md