Skip to main content
Configure Keycloak as the identity provider for Metoro. The final configuration should include a confidential Metoro client, a groups claim that emits full group paths, administrator and user groups, and a Kubernetes Secret containing the client secret.

​
Inputs

Choose these values before configuring Keycloak: Use deploymentUrl from the hub values file. It already includes the scheme, so it can be https://... or http://.... The Keycloak issuer URL must be reachable from browsers and from hub pods. The callback URL must match the redirect URI configured on the Keycloak client exactly.

​
Choose The Realm

Choose the Keycloak realm that will own Metoro access. The realm name becomes the final path segment in the issuer URL: https://<keycloak-host>/realms/<realm>. Disable open user registration unless your organization deliberately allows users to create their own Keycloak accounts. Password reset can be enabled if Keycloak is responsible for local user credentials.

​
Create Groups

Create two Keycloak groups: 
metoro-admins
metoro-users
When the group mapper is configured with full group paths, Keycloak emits these as /metoro-admins and /metoro-users. Those emitted values are what the hub role mappings should use. Add at least one operator to metoro-admins before the first login test.

​
Create The Client

Create a Keycloak client for Metoro. Use these client settings: 
Client ID: metoro
Name: Metoro
Client Type / Protocol: OpenID Connect
Enabled: On
Client authentication: On
Standard flow: On
Implicit flow: Off
Direct access grants: Off
Service accounts roles: Off
Client authenticator: Client ID and Secret
Full scope allowed: On
Set the redirect and origin fields from the deployment URL: If the same hub is reachable through multiple browser-facing hostnames, add each callback URL to Valid redirect URIs and each logout origin to Valid post logout redirect URIs. The redirect URL in the hub values file should still match the primary deploymentUrl. After saving the client, open the client credentials tab and copy the generated client secret.

​
Expose The Groups Claim

Configure Keycloak so the hub receives group membership in the token and userinfo response. The hub values request openid profile email groups, so the Keycloak client must be allowed to request the groups scope and Keycloak must emit a token claim named groups. Use a shared groups client scope when you want the setup to match the requested groups OIDC scope.
  1. In Keycloak, open Client scopes.
  2. Open the existing groups client scope, or create one with protocol OpenID Connect.
  3. Open Mappers.
  4. Click Add mapper, then By configuration.
  5. Select Group Membership.
  6. Save the mapper with these settings:
Name: groups
Mapper type: Group Membership
Token claim name: groups
Full group path: On
Add to ID token: On
Add to access token: On
Add to userinfo: On
Add to lightweight access token: On, if your Keycloak version shows this option
Then assign the groups client scope to the metoro client:
  1. Open Clients.
  2. Select the metoro client.
  3. Open Client scopes.
  4. Click Add client scope.
  5. Select groups.
  6. Add it as a Default client scope.
A typical client should have these default scopes: 
web-origins
roles
profile
groups
basic
email
The hub values request openid profile email groups; Keycloak should then include a groups claim containing full group paths such as /metoro-admins. If you only want this mapper on the metoro client, add it through the client’s dedicated scope instead of a shared groups scope:
  1. Open Clients.
  2. Select the metoro client.
  3. Open Client scopes.
  4. Select the dedicated scope, usually named metoro-dedicated.
  5. Open Mappers.
  6. Click Add mapper, then By configuration.
  7. Select Group Membership and use the same mapper settings above.
Keep the groups client scope assigned to the client when the hub requests the groups scope. The mapper can live on the dedicated scope, but the requested OIDC scope still needs to be accepted by the client.