Keycloak-Bootstrap-Skript (Realm-Import via Admin-REST-API)

tool/keycloak_bootstrap.sh importiert den Realm `holzleitner` idempotent über
die Keycloak-Admin-REST-API und konfiguriert ihn passend zum Backend (Client
holzleitner-app mit PKCE + Audience-Mapper holzleitner-api + personalnummer-
Claim, Rolle driver, Service-Account-Client holzleitner-provisioner, Test-User).

Löst den compose-`--import-realm`-Gotcha (greift nur beim ersten Start mit
leerem Volume): das Skript wendet die Realm-JSON jederzeit an.
- Startet Keycloak bei Bedarf (docker compose), wartet auf Erreichbarkeit,
  holt Admin-Token, legt den Realm via POST /admin/realms an.
- Default non-destruktiv (überspringt vorhandenen Realm); --reset löscht +
  importiert neu (Warnung: provisionierte Fahrer-Konten gehen verloren).
- Verifiziert die Clients und gibt die passenden [keycloak]-config.toml-Werte
  aus. Deps: bash + curl + python3 (kein jq).

Verifiziert: Import gegen Test-Realm → Token für testfahrer trägt
aud=holzleitner-api, personalnummer=1001 (int), Rolle driver.

README: Keycloak-Abschnitt aktualisiert (Import-Gotcha + Skript).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -39,10 +39,28 @@ curl http://127.0.0.1:3000/accounts/1001
 | Test-User | `testfahrer` / `test`  · Personalnummer 1001 · Rolle `driver` |
 | Audience im Access-Token | `holzleitner-api` |
 
-Der Realm wird bei jedem `docker compose up` aus
-`keycloak/import/realm-holzleitner.json` frisch importiert. Wer in der
-Admin-UI Änderungen macht, sollte sie **in die JSON zurückspielen**,
-sonst sind sie beim nächsten `docker compose down` weg.
+Der Realm liegt in `keycloak/import/realm-holzleitner.json` und ist bereits
+passend zum Backend konfiguriert (Client `holzleitner-app` mit PKCE +
+Audience-Mapper `holzleitner-api` + `personalnummer`-Claim, Rolle `driver`,
+Service-Account-Client `holzleitner-provisioner`, Test-User). Wer in der
+Admin-UI Änderungen macht, sollte sie **in die JSON zurückspielen**.
+
+**Wichtig:** Das compose-`--import-realm` greift nur beim **ersten** Start
+(solange das `keycloak-data`-Volume leer ist) — spätere JSON-Änderungen landen
+NICHT automatisch in Keycloak. Zum Anwenden/Bootstrappen:
+
+```bash
+# Importiert den Realm über die Admin-REST-API (idempotent, startet Keycloak
+# bei Bedarf via docker compose). Tut nichts, falls der Realm schon existiert.
+./tool/keycloak_bootstrap.sh
+
+# Sauberer Neu-Import (LÖSCHT den Realm inkl. provisionierter Fahrer-Konten):
+./tool/keycloak_bootstrap.sh --reset
+```
+
+Das Skript gibt am Ende die `[keycloak]`-Werte aus, die in die `config.toml`
+gehören (issuer_url, audience, provisioner-secret …). Overrides via
+`KC_URL` / `KC_ADMIN` / `KC_ADMIN_PASSWORD` / `REALM_FILE`.
 
 ### Token für Dev-Tests holen