Skip to content

Keycloak (OIDC) setup

This walks through a production Keycloak setup. The quick start imports an equivalent realm (deploy/compose/keycloak-realm.json) if you want to compare.

The examples assume the realm platform on https://keycloak.example.com and Entrepot on https://entrepot.example.com.

  1. Create the client

    In the realm, open Clients → Create client:

    • Client type: OpenID Connect, Client ID: entrepot.
    • Client authentication: On (a confidential client).
    • Authentication flow: Standard flow on. Direct access grants and implicit flow off.
    • Valid redirect URIs: https://entrepot.example.com/auth/callback
    • Valid post logout redirect URIs: https://entrepot.example.com/*
    • Web origins: https://entrepot.example.com

    Under Advanced → Advanced settings, set Proof Key for Code Exchange Code Challenge Method to S256. Copy the client secret from the Credentials tab.

  2. Send group membership

    In Client scopes → entrepot-dedicated → Add mapper → By configuration → Group Membership:

    • Token Claim Name: groups
    • Full group path: off (on also works — a leading / is stripped)
    • Add to ID token, Add to access token, Add to userinfo: on
  3. (Optional) Add an audience for bearer tokens

    If scripts will call Entrepot with Keycloak access tokens obtained by other clients, add an Audience mapper that includes entrepot in access tokens. Entrepot accepts a bearer access token when its azp is the client ID or its aud contains one of auth.oidc.bearerAudiences (default: the client ID).

  4. Create the groups

    For example entrepot-admins (system administrators) and developers, and add users to them.

  5. Configure Entrepot

    values.yaml
    baseURL: https://entrepot.example.com
    auth:
    existingSecret: entrepot-auth # keys: session-secret, oidc-client-secret, …
    adminGroups: [entrepot-admins]
    oidc:
    enabled: true
    issuerURL: https://keycloak.example.com/realms/platform
    clientID: entrepot
    displayName: Keycloak
    groupsClaim: groups
    usernameClaim: preferred_username
    Terminal window
    kubectl create secret generic entrepot-auth \
    --from-literal=session-secret="$(openssl rand -base64 48)" \
    --from-literal=oidc-client-secret='<client secret from Keycloak>'
  6. Sign in and grant access

    Open https://entrepot.example.com and choose Sign in with Keycloak (the button uses displayName). A member of entrepot-admins is an administrator; grant everyone else access with role bindings, for example let developers publish to every *-internal repository:

    Terminal window
    curl -fsS -H "Authorization: Bearer $ADMIN" -X POST https://entrepot.example.com/api/v1/role-bindings \
    -d '{"role":"developer","subjectType":"group","subject":"developers","repositoryPattern":"*-internal"}'
Key Default Meaning
auth.oidc.enabled false Turn on single sign-on.
auth.oidc.issuerURL — The realm’s issuer, e.g. https://keycloak.example.com/realms/platform.
auth.oidc.clientID / clientSecret — The confidential client.
auth.oidc.scopes [openid, profile, email] Scopes requested at login.
auth.oidc.groupsClaim groups Claim holding group membership.
auth.oidc.usernameClaim preferred_username Claim used as the username in bindings and the audit log.
auth.oidc.bearerAudiences the client ID Accepted aud values for access tokens presented as bearer tokens.
auth.oidc.displayName Single sign-on Shown on the login button (Sign in with …).
auth.sessionTTL 12h Lifetime of a UI session.
  • Invalid parameter: redirect_uri in Keycloak — the redirect URI must be exactly <baseURL>/auth/callback. Check server.baseURL.
  • Login works but the user has no permissions — the groups claim is missing from the token (check the mapper adds it to the ID token and userinfo), or no binding matches the group name.
  • oidc_unavailable (502) on login — Entrepot can’t reach the issuer’s discovery document. Inside Kubernetes, the issuer URL must be resolvable from the pods and identical to what browsers see.
  • Bearer access tokens get 401 — add an Audience mapper, or add the token’s audience to auth.oidc.bearerAudiences.