Keycloak SSO Setup

Keycloak is the most powerful open-source identity provider. This guide walks through setting up Keycloak as dockmesh’s SSO provider, including group mapping for RBAC.

In Keycloak

Create a client

Clients → Create client:

Client type: OpenID Connect
Client ID: dockmesh
Name: dockmesh
Click Next

Capability config:

Client authentication: ON (confidential client — we’ll use client secret)
Standard flow: ON (authorization code flow)
Direct access grants: OFF (we don’t need password flow)
Service accounts roles: OFF
Click Next

Login settings:

Valid redirect URIs: https://dockmesh.example.com/auth/oidc/callback
Valid post logout redirect URIs: https://dockmesh.example.com
Web origins: https://dockmesh.example.com
Click Save

Get the client secret

Credentials tab → copy the Client secret value.

Configure groups in the ID token

By default, Keycloak doesn’t include user groups in tokens. To enable:

Client scopes → dockmesh-dedicated → Add mapper → By configuration → Group Membership

Field	Value
Name	`groups`
Token Claim Name	`groups`
Full group path	OFF (we want short names like `admins`, not `/admins`)
Add to ID token	ON
Add to access token	ON
Add to userinfo	ON

Save.

Optional: email verification

Client scopes → email → Scope: set to Default so email is always in the ID token.

In dockmesh

Settings → Authentication → OIDC → Add provider:

Field	Value
Display name	`Keycloak`
Issuer URL	`https://keycloak.example.com/realms/<your-realm>`
Client ID	`dockmesh`
Client secret	paste from Keycloak
Scopes	`openid profile email groups`
Redirect URI	`https://dockmesh.example.com/auth/oidc/callback` (auto-filled)
Groups claim	`groups`

Click Test — dockmesh performs an OIDC discovery request against the issuer URL. Should succeed.

Click Save.

Group mapping

Settings → Authentication → Group mappings → New mapping:

Group claim value	dockmesh role	Scope
`dockmesh-admins`	Admin	All hosts
`dockmesh-operators`	Operator	All hosts
`dockmesh-team-a`	Operator	tag=`team-a`
`dockmesh-viewers`	Viewer	All hosts

The group names must match what Keycloak puts in the groups claim. Test by logging in and checking the profile page in dockmesh — it shows your resolved role + scope.

Your Keycloak login page now has a “Login with Keycloak” button… wait, that’s backwards. Go to dockmesh’s login page. Click Login with Keycloak. Redirects to Keycloak, you auth, come back logged in.

On the first SSO login, dockmesh creates the user automatically with their email + the resolved role.

User lifecycle

Remove access: delete the user from Keycloak, or remove them from the relevant group. Next login attempt fails (no group match → no role → no access).

Change role: move them to a different group in Keycloak. Role updates on next login — no dockmesh-side action needed.

Audit trail: every SSO login is written to the audit log with the IdP and resolved role.

Disabling local accounts

Once SSO is working, disable local password login:

Settings → Authentication → Local accounts:

Disable local login (SSO only)
Keep one emergency break-glass admin account (for IdP outages) with a strong password + 2FA, rotate the password quarterly

Troubleshooting

“Authentication failed” after Keycloak login:

dockmesh logs will show the reason:

journalctl -u dockmesh | grep oidc

Common causes:

Redirect URI mismatch (character-level exactness required)
Clock skew > 60s between dockmesh and Keycloak
Keycloak’s groups claim missing (check the mapper config)

User created but no role:

No group mapping matched. The user is created with no role — add a mapping or fix the group name

Logout doesn’t redirect properly:

Check Valid post logout redirect URIs in Keycloak includes the dockmesh URL
SLO (single logout) is optional — if you want logout-from-dockmesh to also log out of Keycloak, configure SLO in both