Identity Provider

The SCF Controls Platform can authenticate users through OpenID Connect (OIDC) single sign-on. This is optional and off by default — with VITE_OIDC_ENABLED unset or false, the platform keeps using the existing Google Sign-In / API-key authentication and nothing on this page applies.

When you turn it on, you have two paths:

• Bundled Keycloak — the stack can bring up a self-hosted Keycloak identity provider for you. No external IdP account required; users live in a dedicated schema on the bundled Postgres container. It requires the bundled database — see the warning below.
• Bring your own OIDC — point the platform at Okta, Microsoft Entra ID, Auth0, Google Workspace, or any standards-compliant OIDC provider. The generic relying-party layer (authorization code + PKCE, issuer discovery, JWKS) works with any of them.

The master API key is still your recovery path

Enabling OIDC does not remove the master API_KEY. If your IdP is unreachable, the master key remains the way to reach the platform, so a broken SSO configuration never locks you out.

The bundled Keycloak requires the bundled database

Keycloak’s connection is hardcoded in docker-compose.yml — KC_DB_URL: jdbc:postgresql://postgres:5432/cg_scf with KC_DB_USERNAME: cg. It does not interpolate DB_HOST, DB_USER or any of the other DB_* settings, and the keycloak-schema-init one-shot connects to the same literal host.

So on an install pointed at an external database, the bundled IdP puts your identity data in the local bundled Postgres while your application data lives elsewhere. Nothing in the installer or the stack refuses that combination, and nothing warns you about it. The consequences:

• Two databases to back up, on two different mechanisms, with no coordinated restore point
• scripts/backup.sh captures the Keycloak schema (it dumps the bundled container) and not your application data — the exact inverse of what you want
• A restore of either one alone leaves users and organisations out of step

If you use an external database, use your own OIDC provider — the Bring your own OIDC path below works with Entra ID, Okta, Auth0, Google Workspace or anything standards-compliant, and keeps identity where you already manage it.

Setup

Bundled Keycloak

The bundled IdP lives behind a Docker Compose profile, so it stays off until you ask for it. Keycloak stores its realm and users in a dedicated keycloak schema on the existing Postgres (KC_DB_SCHEMA=keycloak) and auto-imports its realm from idp/scf-realm.json on first boot.

On a new install, the installer does all of this

Choose bundled Keycloak in scripts/install.sh and it generates KC_ADMIN_PASSWORD and OIDC_CLIENT_SECRET, writes them as 0600 files in your secrets directory, sets the OIDC variables in .env, and asks you for one thing only: the email address of the first platform administrator. No credential is invented by a person and none is typed twice.

The Keycloak master admin account is infrastructure, not your login. Its password lives in the secrets directory as KC_ADMIN_PASSWORD and is never displayed — you need it only to reach the Keycloak admin console directly. Your platform login is the bootstrapped admin below, and steps 3 and 4 (the one-time temporary password and the two forced first-login screens) are unchanged: they are load-bearing security features, not friction to be removed.

If you ran scripts/install.sh --up, cli.admin setup --admin-email has already been run for you. Otherwise run it yourself after the stack is up.

The manual path below remains supported for an existing install.

1. Set the required variables in .env. At minimum, turn on OIDC and give Keycloak its admin credentials (the IdP containers exit loudly if KC_ADMIN_USER / KC_ADMIN_PASSWORD are empty):

   VITE_OIDC_ENABLED=true
   KC_ADMIN_USER=admin
   KC_ADMIN_PASSWORD=<a-strong-password>
   OIDC_CLIENT_SECRET=<openssl rand -hex 32>
   BOOTSTRAP_ADMIN_EMAIL=you@example.com     # seeds a first platform admin (optional)

   See the environment variables table below for the full list and defaults.

2. Start the stack with the idp profile:

   docker compose --profile idp up -d

   Port 8081 already taken?

   Keycloak publishes on host port 8081 by default — a popular default for other admin UIs. If it’s in use, set KEYCLOAK_PORT in .env to remap it; KC_HOSTNAME’s default follows the remapped port automatically. Remember to use the new port in OIDC_ISSUER too.

   This brings up Keycloak 26.3 (quay.io/keycloak/keycloak:26.3) plus a one-shot idp-init container. idp-init writes OIDC_CLIENT_SECRET into the realm’s client and — if BOOTSTRAP_ADMIN_EMAIL is set — creates that admin user with a random temporary password. It is idempotent, so re-running the profile is safe.

3. Read the one-time temporary password from the idp-init logs. The password is printed once, only to that container’s logs:

   docker compose logs idp-init

   Copy the temporary password for the bootstrapped admin before continuing.

4. Sign in for the first time. Open the app at http://localhost:5173, click Sign in, and you are redirected to Keycloak (http://localhost:8081). Enter your BOOTSTRAP_ADMIN_EMAIL and the temporary password. Keycloak then forces two required actions on this first login:

   1. Update Password — replace the temporary password.
   2. Update Account Information — set your first and last name.

   You are then redirected back through /api/auth/callback and land in the app.

5. (Optional) Reach the Keycloak admin console at http://localhost:8081/admin, signing in with KC_ADMIN_USER / KC_ADMIN_PASSWORD. This is where you create additional users, enable self-registration, or adjust the realm.

After first login you still need an organization

The bootstrapped admin is a platform admin but has no organization membership yet, so no workspace will appear until one is assigned. See After first login: assign an organization.

Bring your own OIDC

To use an existing provider (Okta, Microsoft Entra ID, Auth0, Google Workspace, or any compliant OIDC IdP), do not start the idp profile. Just point the OIDC_* variables at your provider:

1. Register an application / client in your IdP as a confidential client with the authorization code flow and PKCE. Register the redirect URI http://localhost:5173/api/auth/callback (adjust the host for your deployment) and note the client ID and secret.

2. Set the OIDC variables in .env:

   VITE_OIDC_ENABLED=true
   OIDC_ISSUER=https://your-idp.example.com/…        # public issuer, byte-for-byte the token `iss`
   OIDC_DISCOVERY_URL=https://your-idp.example.com/…  # bare realm/tenant base the backend fetches
   OIDC_CLIENT_ID=<your-client-id>
   OIDC_CLIENT_SECRET=<your-client-secret>
   OIDC_REDIRECT_URI=http://localhost:5173/api/auth/callback
   OIDC_SCOPES=openid email profile

   Read Choosing ISSUER vs DISCOVERY_URL before you fill these in — mixing them up is the most common cause of failed logins behind a reverse proxy.

3. Start the stack normally (no idp profile):

   docker compose up -d

4. Sign in. The app redirects to your IdP, the user authenticates there, and is returned through /api/auth/callback. Users must already exist in your IdP — see User provisioning.

Deploying on a remote host

The setup examples above use localhost, which is correct only when your browser runs on the same machine as the Docker stack. If the stack runs on a different machine (a home server, a VM, a cloud host), the sign-in redirect and token validation both involve URLs your browser must reach — localhost won’t resolve there, and the first login fails.

Set these three in .env to the host’s reachable address (IP or DNS name):

8080/realms/scf

KC_HOSTNAME=http://<docker-host>:8081                          # what Keycloak advertises
OIDC_ISSUER=http://<docker-host>:8081/realms/scf               # must byte-match the token `iss`
OIDC_REDIRECT_URI=http://<docker-host>:5173/api/auth/callback  # where the browser returns to

• OIDC_DISCOVERY_URL does not change. The backend fetches it server-side over the Docker network; it is never browser-facing.
• If you remapped KEYCLOAK_PORT or FRONTEND_PORT, use the remapped ports in the URLs above.
• Behind a reverse proxy with TLS, use the public https:// URL for all three and add KC_PROXY_HEADERS=xforwarded to the keycloak service.

After changing them, restart the stack (docker compose --profile idp up -d) and verify discovery returns the public issuer: curl http://<docker-host>:8081/realms/scf should return HTTP 200 and the JSON’s issuer should match your OIDC_ISSUER exactly.

Environment variables

File-backed credentials

On an install created by scripts/install.sh, KC_ADMIN_PASSWORD and OIDC_CLIENT_SECRET are not in .env at all — they are 0600 files in SCF_SECRETS_DIR, delivered to the containers through the docker-compose.secrets.yml overlay as /run/secrets/<NAME>, so docker inspect on a running service shows no credential value. The variables below still work and still take precedence in the documented order (database, then file, then environment); the table describes the environment tier.

These variables configure the OIDC relying-party layer and the bundled Keycloak. KC_* values only apply when you run the idp profile.

Variable	Default	Purpose
VITE_OIDC_ENABLED	false	Frontend: use redirect-based OIDC sign-in instead of Google. Build-time (baked into the frontend image)
OIDC_ISSUER	http://localhost:8081/realms/scf	PUBLIC issuer; must byte-match the token iss claim and be browser-reachable
OIDC_DISCOVERY_URL	http://keycloak:8080/realms/scf	INTERNAL realm base the backend fetches (bare base, no /.well-known suffix)
OIDC_CLIENT_ID	scf-platform	OIDC client ID
OIDC_CLIENT_SECRET	changeme-generate-a-real-oidc-secret	Confidential client secret; idp-init writes it into Keycloak at boot
OIDC_REDIRECT_URI	http://localhost:5173/api/auth/callback	OAuth callback URI (must be registered on the client)
OIDC_SCOPES	openid email profile	Requested scopes
KC_ADMIN_USER	admin	Keycloak admin user — REQUIRED with --profile idp. The backend also reads it to create Keycloak accounts at invite time — see User provisioning
KC_ADMIN_PASSWORD	changeme-keycloak-admin	Keycloak admin password — REQUIRED with --profile idp. Also read by the backend for invite-time provisioning
KC_HOSTNAME	http://localhost:<KEYCLOAK_PORT>	Public base URL Keycloak advertises; default follows a remapped KEYCLOAK_PORT. Set explicitly for remote hosts or a reverse proxy
BOOTSTRAP_ADMIN_EMAIL	(blank)	If set, idp-init seeds this platform admin with a one-time random temp password printed to the idp-init logs

Secrets

The changeme-* placeholders in .env.example are for local evaluation only. Generate real values (openssl rand -hex 32 for OIDC_CLIENT_SECRET) for anything beyond local eval, and set a strong KC_ADMIN_PASSWORD. KC_ADMIN_USER and KC_ADMIN_PASSWORD are required whenever the idp profile is used — the IdP containers exit loudly if they are empty.

Choosing ISSUER vs DISCOVERY_URL

OIDC_ISSUER and OIDC_DISCOVERY_URL look similar but serve different roles, and confusing them is the classic footgun — especially behind a reverse proxy.

ISSUER is public, DISCOVERY is internal — and DISCOVERY takes the bare base

• OIDC_ISSUER is the PUBLIC issuer. It must be byte-for-byte identical to the iss claim in the tokens and to the URL the browser is redirected to. For the bundled IdP that is http://localhost:8081/realms/scf.
• OIDC_DISCOVERY_URL is the INTERNAL realm base the backend fetches server-side, over Docker’s network (http://keycloak:8080/realms/scf). This host is not browser-reachable.
• Set OIDC_DISCOVERY_URL to the bare realm base only. The backend appends /.well-known/openid-configuration itself. If you add that suffix yourself you get a doubled path → 404.

Keep the issuer public and the discovery URL internal, or logins fail token validation behind a reverse proxy.

After first login: assign an organization

A freshly-provisioned OIDC user — bundled or bring-your-own — authenticates successfully but has zero organization memberships. Until an admin adds them to an organization, the app has no workspace to show them and they land on a loading state rather than data.

This applies to the bootstrapped BOOTSTRAP_ADMIN_EMAIL user too: it is a platform admin but still needs an organization membership before a workspace appears.

To grant membership, an existing admin adds the user to an organization via Admin → User Management (or the org members API). See User Management for the workflow.

User provisioning

What an invite does depends on which identity provider the platform is pointed at.

Bundled Keycloak

When the platform runs the bundled Keycloak (docker compose --profile idp) and the backend has KC_ADMIN_USER, KC_ADMIN_PASSWORD and OIDC_DISCOVERY_URL / OIDC_ISSUER configured, inviting somebody from Settings › User Management › Invite User also creates their Keycloak account.

The backend looks the email up in the realm first:

• Not in the realm — it creates the user (username = the email address, enabled, email marked verified, required action Update Password) and sets a generated temporary password. The password is temporary, so Keycloak forces a new one at first sign-in.
• Already in the realm — nothing is changed and no password is set. The existing identity is left exactly as it is.

The temporary password is shown once

The generated password appears once in the Invite User modal, with a copy button, and is included in the invitation email when email delivery (Resend) is configured. It is never stored and never shown again. If it is lost, cancel the invite and re-invite, or reset the password in the Keycloak admin console.

When the invite created the account, the invitee’s first sign-in accepts the invitation: after Keycloak has made them replace the temporary password they arrive in the organisation with the role and employment type on the invite, and they appear in User Management straight away. They do not need to open the invitation link, though the link still works if they do. The platform ties this to the Keycloak account it created (the subject on the invite), never to an email address, so an account the platform did not create is not joined this way — those invitees, like everyone on the paths below, join through the link.

Cancelling an invite deletes the Keycloak account only when the invite created it and the person has never signed in to the platform. In every other case the identity is left alone.

Every Keycloak account the platform creates or deletes is written to the platform audit log under entity type idp_user.

Bring your own OIDC, or Google

Nothing changes on these paths. The platform does not create accounts in an external identity provider: an admin still creates the account in the IdP as usual, and the invite links that identity to the organisation the first time the person signs in.

Reading the invite badges

Each outstanding invitation in the pending-invite list carries a badge saying which of the above applied:

Badge	Meaning
IdP account	An account exists in the bundled Keycloak — created by the invite, or already there before it
No IdP account	The bundled Keycloak is enabled, but no account exists for this email
External IdP	Provisioning is disabled — a bring-your-own OIDC or Google install, where the IdP owns accounts

The BOOTSTRAP_ADMIN_EMAIL user seeded by idp-init is created independently of any invite, and still is.

Troubleshooting

Symptom	Cause	Fix
Login fails with a 404 fetching discovery	OIDC_DISCOVERY_URL has a /.well-known/openid-configuration suffix, giving a doubled path	Set OIDC_DISCOVERY_URL to the bare realm base — the backend appends the suffix itself
Signed in but stuck on the loading spinner, no workspace	The user has no organization membership	An admin adds them to an organization (see above)
User can’t sign in at the IdP at all	No account exists for them in the IdP	Check the badge on their pending invite. No IdP account on a bundled-Keycloak install means KC_ADMIN_USER / KC_ADMIN_PASSWORD were not configured for the backend when they were invited — cancel the invite and re-invite, or create the user in the Keycloak admin console. On External IdP installs, create the user in your own IdP
idp-init or Keycloak container exits immediately	KC_ADMIN_USER / KC_ADMIN_PASSWORD are empty	Set both in .env; they are required with --profile idp
Login works locally but fails behind a reverse proxy	OIDC_ISSUER does not byte-match the public token iss	Set OIDC_ISSUER to the exact public issuer; keep OIDC_DISCOVERY_URL internal
Sign-in redirects to localhost from another machine, or iss validation fails	Stack runs on a remote host but the browser-facing URLs still say localhost	Set KC_HOSTNAME, OIDC_ISSUER, and OIDC_REDIRECT_URI to the host’s reachable address — see Deploying on a remote host

Related Guides

• Authentication — Sign-in paths and account management
• Configuration — Environment variable reference
• Deployment — Bringing up the self-hosted stack
• User Management — Assigning organizations and roles