gwoe-antragspruefer/docs/how-to/keycloak-setup.md

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:

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:

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