The Keycloak lab

A throwaway Keycloak (26.7.4, dev mode, in-memory storage, no database container) with a qfence realm, used to test the orchestrator’s OIDC sign-in end to end. Never use it for anything real: the admin account is admin/admin, every user’s password is <name>-password, and the password grant is enabled for tests.

docker compose -f deploy/keycloak-lab/docker-compose.yml up -d --wait

Issuer: http://127.0.0.1:8180/realms/qfence. Admin console: http://127.0.0.1:8180/admin/ (admin / admin). Nothing survives docker compose down.

What the realm contains

Clients:

• qfence-console: public client for the console’s Authorization Code + PKCE (S256) sign-in. Redirect URIs are the test ports http://127.0.0.1:5185/login and https://127.0.0.1:8450/login.
• qfence-test: public client with the password grant, for automated tests only.

Both put qfence-api in the access token’s audience and the user’s groups in a groups claim.

• qfence-controller: a confidential client with a service account (secret qfence-controller-lab-secret), for the client credentials grant. It stands in for an application’s OAuth admin API client: a controller test type authenticates with it (ADR 0010 §5). Its access tokens live 12 seconds, so a refresh happens within a test.

Running an orchestrator against it

go run ./cmd/orchestrator -listen 127.0.0.1:8450 \
  -oidc-issuer http://127.0.0.1:8180/realms/qfence \
  -oidc-audience qfence-api -oidc-client-id qfence-console \
  -oidc-role-claim groups \
  -oidc-role-map qfence-admins=Administrator,qfence-ops=Operator,qfence-viewers=Viewer

Tests that use it

• QFENCE_KEYCLOAK_URL=http://127.0.0.1:8180 go test ./cmd/orchestrator -run Keycloak runs the real binary against Keycloak’s real tokens. It covers roles from groups, refusal of an unmapped user and a tampered token, the audit actor, and signing-key rotation. For rotation, a token from a new key is accepted within seconds, and a token from a key Keycloak removed stops being accepted. These tests change the realm’s keys.
• QFENCE_KEYCLOAK_URL=http://127.0.0.1:8180 go test ./internal/controllers/tokens -run Keycloak -v registers a controller of a test type whose credentials are qfence-controller’s client id and secret, stored in a local secrets store and named by reference. It gets an access token, uses it at the userinfo endpoint, and refreshes it before it expires; a wrong secret fails the controller without the secret appearing anywhere.
• cd web/console && npx playwright test -c playwright.keycloak.config.ts runs the console’s sign-in in a real browser through Keycloak’s login page. It starts the lab itself if it is not running.