Howto Keycloak OIDC

How to set up Keycloak

This guide configures Keycloak as an OIDC provider for Bindery. Users sign in via the Keycloak login page and are mapped to Bindery accounts by their stable Keycloak user UUID (sub).

Prerequisites:

• Keycloak v21+ running with an existing realm
• Bindery v0.24.0+
• Admin access to the Keycloak admin console
• BINDERY_OIDC_REDIRECT_BASE_URL set to your public Bindery URL

---

Steps

1. Create the Bindery client in Keycloak

1. In the Keycloak admin console, select your realm (e.g. myrealm).
2. Go to Clients → Create client.
3. Fill in:
   • Client type: OpenID Connect
   • Client ID: bindery
4. Click Next.
5. Enable Client authentication (this makes it a confidential client with a secret).
6. Authentication flow: leave Standard flow checked, uncheck everything else.
7. Click Next, then Save.

Expected result: client bindery appears in the Clients list.

2. Configure the redirect URI

1. Open the bindery client → Settings tab.
2. Under Valid redirect URIs, add:

   https://bindery.example.com/api/v1/auth/oidc/keycloak/callback
   

3. Under Web origins, add https://bindery.example.com.
4. Click Save.

3. Copy the client secret

1. Go to the Credentials tab of the bindery client.
2. Copy the Client secret value.

4. Add a groups mapper (optional but recommended)

To pass group membership to Bindery so you can use allowed_groups / allowed_admin_groups:

1. Go to the bindery client → Client scopes tab → click bindery-dedicated.
2. Click Add mapper → By configuration → Group Membership.
3. Fill in:
   • Name: groups
   • Token Claim Name: groups
   • Full group path: On
   • Add to ID token: On
4. Click Save.

Keycloak groups in the token are prefixed with / — e.g. /bindery-users. Match this exactly in allowed_groups.

5. Set the redirect base URL in Bindery

environment:
  BINDERY_OIDC_REDIRECT_BASE_URL: "https://bindery.example.com"

Restart Bindery if adding for the first time.

6. Add the Keycloak provider in Bindery

Settings → Security → OIDC Providers → Add provider, or:

curl -X POST http://bindery:8787/api/v1/settings/auth/oidc/providers \
  -H "X-Api-Key: <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "keycloak",
    "name": "Keycloak",
    "issuer": "https://keycloak.example.com/realms/myrealm",
    "client_id": "bindery",
    "client_secret": "<your-client-secret>",
    "scopes": "openid email profile groups",
    "allowed_groups": "/bindery-users"
  }'

The issuer must include the realm path — Keycloak's OIDC discovery endpoint is at <issuer>/.well-known/openid-configuration.

Expected result: Sign in with Keycloak button appears on the Bindery login page.

7. Test the login flow

1. Open a private window → https://bindery.example.com/login → click Sign in with Keycloak.
2. Browser redirects to Keycloak → log in.
3. Keycloak redirects back to Bindery → Bindery validates the ID token, maps the user by (https://keycloak.example.com/realms/myrealm, <keycloak-user-uuid>), provisions the account.
4. Confirm in Settings → Users.

The Keycloak user UUID is the stable sub claim. Renaming the Keycloak username does not change the UUID, so no orphaned accounts are created.

---

When this goes wrong

Symptom	Cause	Fix
Bindery can't reach Keycloak discovery URL	Network/firewall blocking Bindery → Keycloak	Test: curl https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration from inside the Bindery container
invalid_client on callback	Client secret wrong or client not confidential	Re-copy the secret from Keycloak Credentials tab; confirm Client authentication is enabled
redirect_uri_mismatch	Redirect URI not registered	Add https://bindery.example.com/api/v1/auth/oidc/keycloak/callback to Valid redirect URIs in Keycloak
issuer mismatch in token validation	issuer in Bindery config doesn't match Keycloak realm URL	The issuer must be https://keycloak.example.com/realms/<realm-name> exactly — check the iss claim in the ID token with BINDERY_LOG_LEVEL=debug
allowed_groups blocks all users	Groups not in token, or wrong format	Confirm the groups mapper is added to the client scope (step 4). Groups are /-prefixed: use /bindery-users not bindery-users
Users outside allowed_groups can still log in	allowed_groups not saved to Bindery provider	Re-check the provider config via GET /api/v1/settings/auth/oidc/providers/keycloak

See also: Troubleshooting — OIDC | docs/auth-oidc.md