Local Keycloak dev instance for auth development

[vredchenko]

Overview

Keycloak at identity.diamond.ac.uk requires VPN access, which is inconvenient for local development. We need a local Keycloak instance that both the frontend and backend can use during development.

Proposed approach

Run Keycloak in Docker using its start-dev mode (in-memory H2 database, instant startup):

docker run -p 8080:8080 \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:26.1 start-dev

What's needed

1. Realm export JSON — checked into devtools (or mounted as a volume) so setup is reproducible. Should include:

   • A smartem realm (or whatever matches production)
   • A smartem-frontend public client (SPA, no secret)
   • Valid redirect URIs for local dev (http://localhost:5174/*)
   • A test user or two

2. Frontend config — VITE_KEYCLOAK_URL=http://localhost:8080 in .env.development.local. The auth infrastructure already supports this (PR Add app config #74 in smartem-frontend).

3. Backend config — when backend token validation is added, it needs the same Keycloak URL for JWKS discovery. The local instance's /.well-known/openid-configuration endpoint provides everything needed for offline JWT verification.

4. Developer documentation — how-to guide in devtools docs for setting up local auth.

Integration points

• smartem-frontend: keycloak-js connects to local instance, gets real tokens, full OAuth redirect flow works
• smartem-backend: FastAPI validates tokens against local instance's JWKS endpoint (when auth is implemented)
• Both services share the same token issuer, so tokens from frontend work with backend — identical to production

Alternatives considered

• mock-oauth2-server (NAV) — lighter (~30MB) but not Keycloak-specific, token claims may differ
• App-level mock — frontend-only, doesn't help backend, doesn't test real auth flow
• Vite proxy — won't work, OAuth uses browser redirects not API calls

Acceptance criteria

• Docker command or compose service that starts local Keycloak
• Realm export JSON with pre-configured client and test users
• Frontend can complete full login/logout flow against local instance
• Backend can validate tokens from local instance (when auth is added)
• Developer how-to guide