Configure SSO with Keycloak

This walks through Keycloak specifically, using the local instance compose.yaml already runs for development — the same steps apply to a production Keycloak, just at a different URL. Any other OIDC provider works too (see Authentication); only the console screens differ.

1. Create a realm

Open the admin console at http://localhost:8080 (admin / admin on the local dev instance — see compose.yaml’s own comment on that container). Create a new realm, e.g. atlas. Its discovery document then lives at:

http://localhost:8080/realms/atlas/.well-known/openid-configuration

That URL is ATLAS_AUTH_OIDC_DISCOVERY_URL.

2. Create a client

Inside the realm, create a client:

Client type: OpenID Connect
Client ID: atlas (or anything — this becomes ATLAS_AUTH_OIDC_CLIENT_ID)
Client authentication: on (confidential client) — Atlas’s OIDC exchange happens server-side in the API, never in the browser, so a client secret is safe to hold
Valid redirect URIs: the API’s own callback route, e.g. http://localhost:8000/api/v1/auth/oidc/callback

Once saved, the client’s Credentials tab shows the client secret — that’s ATLAS_AUTH_OIDC_CLIENT_SECRET.

3. Map a `groups` claim (optional, but needed for group-based roles)

Authorization’s grant_match can key on any claim the token carries, including groups — but Keycloak doesn’t send it by default. In the client’s Client scopes, add a mapper of type Group Membership (name it groups, token claim name groups, full group path off unless your rules match on the full path), then make sure the scope carrying it is requested:

ATLAS_AUTH_OIDC_SCOPE=openid profile email groups

4. Wire it into Atlas

ATLAS_AUTH_OIDC_DISCOVERY_URL=http://localhost:8080/realms/atlas/.well-known/openid-configuration
ATLAS_AUTH_OIDC_CLIENT_ID=atlas
ATLAS_AUTH_OIDC_CLIENT_SECRET=<from the Credentials tab>
ATLAS_AUTH_OIDC_SCOPE=openid profile email groups
ATLAS_AUTH_FRONTEND_URL=http://localhost:3000

Restart the API — these are read once at startup, not hot-reloaded.

5. Decide who can log in

ATLAS_ALLOW_SELF_REGISTRATION=false

false (the default) means an admin must create a principal (POST /principals) — or a workspace role’s grant_match must already cover the identity, e.g. by groups — before that person’s first login succeeds. true auto-provisions a principal on first login instead, which is convenient for an internal tool but means anyone who can authenticate against your realm gets an Atlas account.

6. Test it

Open the frontend and use the login button — it only appears once ATLAS_AUTH_OIDC_DISCOVERY_URL is set (GET /auth/config is what the frontend checks). A successful login lands back on ATLAS_AUTH_FRONTEND_URL.