RnD/infra
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
infra/stacks/keycloak
History
R de Ren 33a794e35d feat(sso): wire Keycloak SSO end-to-end across all apps 
New stack:
- stacks/oauth2-proxy/ — per-app sidecars (mlflow, portainer, rabbitmq)
  that gate vhosts via nginx auth_request against Keycloak's wbd realm.

Native OIDC wired into:
- grafana       (generic_oauth, role-attribute-path → Admin/Editor/Viewer)
- jupyterhub    (oauthenticator.GenericOAuthenticator)
- node-red      (passport-openidconnect; in-memory state store + users()
                 resolver because adminAuth doesn't expose req.session)
- jenkins       (oic-auth plugin via JCasC; matrix-auth for authz; setup
                 wizard suppressed; custom image with plugins.txt)

Infra fixes uncovered while bringing the above online:
- nginx-proxy: bump proxy_buffer_size to 16k so oauth2-proxy callbacks
  don't 502 on the JWT-bearing Set-Cookie header.
- nginx-proxy: add `resolver 127.0.0.11 valid=30s` so service names
  re-resolve after sidecar recreates (was cross-wiring oauth2-proxy
  upstreams after restart).
- jupyterhub: pass --allow-root to the singleuser spawner (hub runs as
  root inside its container; jupyter-server refused root without flag).
- jupyterhub Dockerfile: install jupyterlab + notebook so
  SimpleLocalProcessSpawner has something to launch.
- node-red Dockerfile: install passport-openidconnect into the image
  so settings.js can require() it.
- portainer: pre-seed local admin via --admin-password=<bcrypt-hash>
  so the 5-minute "no admin → lockout" timer can never trigger.
- deploy.sh: restore executable bit (was 644 in repo).

Admin/viewer policy:
- Created realm role `app-admin` in keycloak wbd realm.
- Grafana maps app-admin → Admin (default Viewer).
- Jenkins matrix-auth grants r.de.ren Overall/Administer, authenticated
  users get Overall/Read + Job/Read + View/Read.
- Node-RED: NODERED_ADMIN_USERS env list → permissions "*", others
  ["read"]. (TODO: switch to app-admin realm role.)
- JupyterHub: JUPYTERHUB_ADMIN_USERS env list. (Same TODO.)
- Gitea: r.de.ren pre-created as local admin; OIDC auto-links via email.

Docs:
- README, cloud/README, stacks/oauth2-proxy/README, and per-stack
  READMEs updated to reflect the new state and remove resolved TODOs.
- cloud/.env.example gains all the new OIDC client + cookie-secret keys.
- cloud/README documents the full kcadm realm bootstrap, including the
  hardcoded-audience mapper and post-logout redirect URIs that are
  non-obvious gotchas.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 18:34:37 +00:00
..
.env.example
feat(cloud): short function-based subdomains + harden keycloak with postgres
2026-05-21 13:54:57 +02:00
compose.yml
feat(cloud): short function-based subdomains + harden keycloak with postgres
2026-05-21 13:54:57 +02:00
README.md
feat(sso): wire Keycloak SSO end-to-end across all apps
2026-05-21 18:34:37 +00:00

README.md

keycloak

Identity provider for SSO across all R&D services. Cloud-only for now (edges get their own realms once we cover the edge layer).

  • Public hostname: auth.wbd-rd.nl (reverse-proxied via nginx-proxy at HTTPS → backend HTTP 8080)
  • Networks: app (OIDC endpoints for relying-party apps) + mgmt (admin console) + data (postgres backend)
  • Backend: postgres keycloak database in sql stack — provisioned automatically by sql/config/init.d/01-databases.sh on first start
  • Volume: keycloak-data (themes, providers, realm exports)

First-run bootstrap

KC_BOOTSTRAP_ADMIN_USERNAME + KC_BOOTSTRAP_ADMIN_PASSWORD create the master-realm admin on first start. Change the password immediately after first login via the admin console.

After cloud/deploy.sh succeeds, run the kcadm bootstrap from cloud/README.md → Keycloak realm bootstrap (one-time). That single script provisions:

  • the wbd realm
  • one OIDC client per app (with redirect URI + hardcoded audience mapper + post-logout URI)
  • the app-admin realm role
  • the first operator user

Realm + clients

Every human-accessible app is wired to a Keycloak client in realm wbd:

Client ID App Redirect URI Mechanism
gitea Gitea https://git.wbd-rd.nl/user/oauth2/keycloak/callback native OIDC
grafana Grafana https://dash.wbd-rd.nl/login/generic_oauth native OIDC (generic_oauth)
node-red Node-RED https://flow.wbd-rd.nl/auth/strategy/callback/ native OIDC (passport-openidconnect)
jenkins Jenkins https://ci.wbd-rd.nl/securityRealm/finishLogin native OIDC (oic-auth plugin via JCasC)
jupyterhub JupyterHub https://hub.wbd-rd.nl/hub/oauth_callback native OIDC (oauthenticator.GenericOAuthenticator)
mlflow MLflow https://ml.wbd-rd.nl/oauth2/callback oauth2-proxy + nginx auth_request
portainer-ce Portainer https://ops.wbd-rd.nl/oauth2/callback oauth2-proxy + nginx auth_request
rabbitmq RabbitMQ UI https://mq.wbd-rd.nl/oauth2/callback oauth2-proxy + nginx auth_request

Required client config (gotchas)

  • Hardcoded audience mapper (oidc-audience-mapper with included.client.audience=<clientId>) on every client. Without this, the access-token aud is [realm-management, account] and oauth2-proxy clients return HTTP 500 at callback time. The kcadm bootstrap script in cloud/README.md creates this mapper for every client.
  • Valid post-logout redirect URIs must be set (Keycloak 24+ requirement) — https://<app-host>/*. Otherwise logout returns "Invalid redirect URI".
  • directAccessGrantsEnabled=false unless you specifically need ROPC for that client.

Realm roles

  • app-admin — granted to operators who should get full admin in every app. Each app's config maps this role to its own admin role:
    • Grafana: app-admin → Admin
    • Jenkins: matrix-auth grants Overall/Administer to specific usernames (not the role itself yet — TODO)
    • Node-RED / JupyterHub: env-var lists are still username-based; switching to role-based is a TODO
  • Anyone without app-admin gets viewer / read-only.

Realm-as-code

Once you're happy with the manual setup, export the realm so future deploys auto-import:

docker compose exec keycloak /opt/keycloak/bin/kc.sh \
  export --dir /opt/keycloak/data/import --realm wbd

Commit the resulting JSON to stacks/keycloak/config/realms/wbd.json. Keycloak imports anything in /opt/keycloak/data/import/ on first start.

TODO

  • Export realm config → commit config/realms/wbd.json
  • Theme: WBD branding (logo, colors)
  • User federation (LDAP from corporate AD, if applicable)
  • 2FA policy
  • Session / token lifetimes per client
  • Switch Node-RED + JupyterHub admin lookup from env-var lists to app-admin realm role checks (Grafana already does this)
Reference in New Issue View Git Blame Copy Permalink