> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak OIDC Setup

> Create the Keycloak realm, client, groups, group claim, client Secret, and values required for OIDC login

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:

<pre />

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:

```text theme={null}
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:

```text theme={null}
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:

<pre />

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:

```text theme={null}
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:

```text theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.