# 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 |