Keycloak and identity providers

Deckgauge authenticates every user through Keycloak. A realm ships pre-configured, self-registration is on by default, and Microsoft Entra ID can be added as an identity provider — but only if you set its variables before the container's first start.

deckgauge · Keycloak realm import

deckgauge realm

deckgauge-web client

microsoft IdP

The Microsoft identity-provider node only exists in the imported realm when all three MICROSOFT_* variables are set.

The realm and its client

The realm is deckgauge, imported from keycloak/realm-export.json on container start (start-dev --import-realm). It ships with registrationAllowed and loginWithEmailAllowed both on, so the first person to sign in can register directly — there's no separate admin step to create the first user. It defines one client, deckgauge-web, a confidential OIDC client with a 24-hour access-token lifespan; its id and secret are exactly the KEYCLOAK_CLIENT_ID / KEYCLOAK_CLIENT_SECRET values in .env.example.

How to create users

Open http://localhost:8080 and either self-register from the Deckgauge login page, or sign in to the Keycloak admin console with admin / admin (the container's default admin credentials).
Create a user manually from the admin console under the deckgauge realm, if you'd rather not rely on self-registration.
Grant board access from inside Deckgauge — Keycloak only handles authentication; board roles (viewer/editor/owner) are assigned per board once the user exists. See Access & security.

Wiring Microsoft as an identity provider

Set MICROSOFT_TENANT_ID, MICROSOFT_CLIENT_ID, and MICROSOFT_CLIENT_SECRET from your Azure AD app registration, then start (or restart) the keycloak container. Its entrypoint, configure-microsoft-idp.sh, runs before the server boots and checks all three variables:

All three set — it substitutes them into the realm import and Microsoft appears as a sign-in option.
Any one missing — it deletes identityProviders and identityProviderMappers from the realm import entirely (via jq, or a sed fallback if jq isn't available) before Keycloak ever reads it.

This edits a file in your working copydocker-compose.yml mounts keycloak/realm-export.json read-write (not read-only, unlike the other Keycloak mounts), and the entrypoint writes its processed result straight back to that path. Every container start rewrites the file on your host: with all three variables set, your real client secret gets substituted into a version-controlled file; with any missing, the identity-provider block is stripped from your working copy. Either way, treat that file as generated output once Microsoft SSO is in play — check git diff before committing anything under keycloak/.

The trapThis check runs once, at container start, against the realm import file — not against a running realm. Setting the Microsoft variables after the keycloak container is already up does nothing on a plain restart, since the check only runs when the entrypoint executes. If Microsoft sign-in isn't appearing, the most common cause isn't a wrong credential — it's that the container's first boot happened before the variables were set. Add the identity provider from the admin console instead of trying to force Keycloak to reprocess the import file (see below).

Under the hood

The realm's redirect URIs and web origins are pre-populated for the local ports Deckgauge's own staging overlays use (3000, 3010, 3030) — reachable from localhost only, matching the product's localhost-first design. KC_HOSTNAME_STRICT is off and KC_HOSTNAME is pinned to localhost so browser redirects work while server-side calls (from api and web) use the Docker service name instead.

If it looks wrong

Symptom	Cause	Fix
Microsoft sign-in never shows up, though the variables are set	The container imported the realm before the variables existed	Add the Microsoft identity provider directly from the Keycloak admin console (`http://localhost:8080`, under the `deckgauge` realm) — that takes effect immediately. Recreating the container only reliably helps if the realm has never been imported yet; once it already exists in the persisted Keycloak database, whether a recreate makes Keycloak reprocess it isn't something this repo can confirm
Users can't register at all	`registrationAllowed` was turned off in a customized realm export	Re-check the realm export, or create users from the admin console instead
Login redirects fail with a mismatch error	You're accessing Deckgauge from a host or port not in the realm's redirect URIs	Use one of the pre-configured local ports, or add your host to `redirectUris` / `webOrigins` in the realm export

Configuration reference — every Keycloak and Microsoft variable.
Access & security — board roles once a user exists.
Services & architecture — where Keycloak sits in the stack.

Last updated 6 September 2026