register-referentie/docs/runbooks/keycloak.md

Keycloak runbook

Keycloak (infra/keycloak/docker-compose.yml) runs in dev mode with four realms imported at boot from infra/keycloak/realms/: digid, eherkenning, eidas, medewerker. It mocks the Dutch identity brokers so portals can do real OIDC logins locally. Host port :8180.

Quick test (make)

make keycloak-up      # start Keycloak + import realms (~30-60s first boot)
make keycloak-smoke   # start + verify every realm logs in and returns its claim
make keycloak-down    # stop + wipe

make keycloak-smoke runs infra/keycloak/check_realms.py, which does a password-grant login per realm and asserts the identifying claim:

Realm	User	Claim asserted
digid	jan-burger	bsn
eherkenning	acme-ondernemer	kvk
eidas	pierre-dupont	eidas_id
medewerker	merel-behandelaar	role behandelaar

All test users / credentials are in ../synthetic-data.md.

Notes

• Admin console: http://localhost:8180/ — admin / admin (dev only).
• Client big-portal is public with standardFlowEnabled (browser redirect login) and directAccessGrantsEnabled (password grant, used by the smoke test).
• Dev store: in-memory H2 via start-dev; realms re-import on each boot, so changes made in the admin UI don't persist. Edit the realm JSONs to make durable changes.
• Image pinned to quay.io/keycloak/keycloak:26.1.
• Claims are injected by OIDC protocol mappers on big-portal (user attribute → token claim); medewerker roles come through realm_access.roles.