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.
-
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.
- Client type: OpenID Connect, Client ID:
-
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
- Token Claim Name:
-
(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
entrepotin access tokens. Entrepot accepts a bearer access token when itsazpis the client ID or itsaudcontains one ofauth.oidc.bearerAudiences(default: the client ID). -
Create the groups
For example
entrepot-admins(system administrators) anddevelopers, and add users to them. -
Configure Entrepot
values.yaml baseURL: https://entrepot.example.comauth:existingSecret: entrepot-auth # keys: session-secret, oidc-client-secret, …adminGroups: [entrepot-admins]oidc:enabled: trueissuerURL: https://keycloak.example.com/realms/platformclientID: entrepotdisplayName: KeycloakgroupsClaim: groupsusernameClaim: preferred_usernameTerminal window kubectl create secret generic entrepot-auth \--from-literal=session-secret="$(openssl rand -base64 48)" \--from-literal=oidc-client-secret='<client secret from Keycloak>'server:baseURL: https://entrepot.example.comauth:sessionSecret: <at least 32 random bytes>adminGroups: [entrepot-admins]oidc:enabled: trueissuerURL: https://keycloak.example.com/realms/platformclientID: entrepotclientSecret: <secret> # or ENTREPOT_AUTH_OIDC_CLIENTSECRET(_FILE)displayName: KeycloakgroupsClaim: groupsusernameClaim: preferred_usernamescopes: [openid, profile, email]Terminal window ENTREPOT_SERVER_BASEURL=https://entrepot.example.comENTREPOT_AUTH_ADMINGROUPS=entrepot-adminsENTREPOT_AUTH_OIDC_ENABLED=trueENTREPOT_AUTH_OIDC_ISSUERURL=https://keycloak.example.com/realms/platformENTREPOT_AUTH_OIDC_CLIENTID=entrepotENTREPOT_AUTH_OIDC_CLIENTSECRET_FILE=/run/secrets/oidc-client-secretENTREPOT_AUTH_OIDC_GROUPSCLAIM=groups -
Sign in and grant access
Open
https://entrepot.example.comand choose Sign in with Keycloak (the button usesdisplayName). A member ofentrepot-adminsis an administrator; grant everyone else access with role bindings, for example letdeveloperspublish to every*-internalrepository: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"}'
OIDC settings
Section titled “OIDC settings”| 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. |
Troubleshooting
Section titled “Troubleshooting”Invalid parameter: redirect_uriin Keycloak — the redirect URI must be exactly<baseURL>/auth/callback. Checkserver.baseURL.- Login works but the user has no permissions — the
groupsclaim 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 toauth.oidc.bearerAudiences.