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¶
- Öffne
https://sso.toppyr.de/admin/master/console/ - Wechsle zum Realm collaboration (Dropdown oben links)
- Navigiere zu Clients → Create client
- Einstellungen:
| Feld | Wert |
|---|---|
| Client type | OpenID Connect |
| Client ID | gwoe-antragspruefer |
| Name | GWÖ-Antragsprüfer |
| Always display in UI | Off |
- Next → Capability config:
| Feld | Wert |
|---|---|
| Client authentication | Off (public client für Browser-Flow) |
| Authorization | Off |
| Standard flow | On |
| Direct access grants | Off |
- 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 |
- 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:
- Realm roles → Create role → z.B.
gwoe-editor,gwoe-admin - Groups → Create group → z.B. "Fraktion SPD Hagen", "AG Klima"
- Nutzer den Gruppen zuweisen
- In den Client-Scopes sicherstellen, dass
realm_access.rolesim 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 |