> ## Documentation Index > Fetch the complete documentation index at: https://bifrost-backport-mcp-oauth2-server.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # SSO using OIDC > Configure Keycloak as your identity provider for Bifrost Enterprise using OpenID Connect. ## Prerequisites * A running Keycloak server (self-hosted or cloud) with admin access to a realm * Bifrost Enterprise deployed and accessible * Your Bifrost callback URL: `https:///login` *** ## Step 1: Create an OIDC Client In the Keycloak Admin Console, select your realm from the top-left dropdown. Go to **Clients** in the left nav and click **Create client**. Keycloak Admin Console Clients list with Create client button highlighted

Keycloak Admin Console Clients list with Create client button highlighted

Set the following fields: * **Client type**: OpenID Connect * **Client ID**: `bifrost-oidc` (or any identifier you prefer) * **Name**: `Bifrost` Click **Next**. Keycloak Create client General settings form with Client type OpenID Connect, Client ID bifrost-oidc, and Name Bifrost

Keycloak Create client General settings form with Client type OpenID Connect, Client ID bifrost-oidc, and Name Bifrost

On the **Capability config** step, enable: * **Client authentication** - makes this a confidential client and generates a client secret * **Standard flow** - enables Authorization Code login * **Service accounts roles** - required for Bifrost to call the Keycloak Admin REST API for background user sync Leave all other toggles at their defaults. Click **Next**. Set your redirect URIs: * **Root URL**: `https://` * **Valid redirect URIs**: `https:///login` Optionally, to use Discover Claims during setup, also add: ``` https:///workspace/scim/oauth-discover-callback ``` Click **Save**. Keycloak Login settings form with Root URL, Valid redirect URIs showing the Bifrost login and oauth-discover-callback URLs

Keycloak Login settings form with Root URL, Valid redirect URIs showing the Bifrost login and oauth-discover-callback URLs

The client is now saved. Open it and go to the **Service accounts roles** tab. Click **Assign role**, filter by `realm-management`, and assign: | Role | Required | | - | - | | `view-users` | Required - lets Bifrost list and import users | | `view-realm` | Recommended - enables group and role listing | | `query-groups` | Optional - needed for group-based import filters | These permissions power the **Sync Users from Keycloak** import flow in [Optional Next Steps](#optional-next-steps). *** ## Step 2: Copy Your Client Secret Open the **bifrost-oidc** client and go to the **Credentials** tab. Copy the **Client Secret** - you will need it in [Step 5](#step-5-configure-bifrost). Keycloak Credentials tab showing Client Authenticator set to Client Id and Secret with the Client Secret field

Keycloak Credentials tab showing Client Authenticator set to Client Id and Secret with the Client Secret field

*** ## Step 3: Configure Claim Mappers Keycloak does not include realm roles or full group paths in tokens by default. Add two mappers to the client's dedicated scope. In the **bifrost-oidc** client, go to the **Client scopes** tab. Click on the **bifrost-oidc-dedicated** scope. Keycloak Client scopes tab with bifrost-oidc-dedicated scope highlighted

Keycloak Client scopes tab with bifrost-oidc-dedicated scope highlighted

Click **Add mapper** → **By configuration**. Keycloak Configure a new mapper dialog showing mapper type list with Group Membership visible

Group Membership mapper form with Name Groups, Token Claim Name groups, Full group path On, and all Add to token toggles On

Keep **Full group path** enabled. Keycloak sends groups as paths (e.g. `/Engineering`, `/Platform`). Bifrost's `/${*}` wildcard in team mappings extracts the name after the slash automatically - see [Step 5](#step-5-configure-bifrost). Click **Add mapper** → **By configuration** again. Select **User Realm Role** from the list. Keycloak Configure a new mapper dialog with User Realm Role option highlighted

Keycloak Configure a new mapper dialog with User Realm Role option highlighted

User Realm Role mapper form with Name realm_roles, Token Claim Name realm_access.roles, Multivalued On, and Add to ID and access token enabled

*** ## Step 4: Assign Users In Keycloak, users need to be assigned to the realm roles and groups you plan to map in Bifrost. * Go to **Users** → select a user → **Role mapping** tab → assign the relevant realm roles (e.g. `realm-admin`, `bifrost-viewer`) * Go to **Users** → select a user → **Groups** tab → join the relevant groups (e.g. `/Engineering`, `/Platform`) *** ## Step 5: Configure Bifrost In your Bifrost dashboard, go to **Governance** → **User Provisioning**. Select **Keycloak** as the identity provider and click **Next**. Bifrost Choose Provider screen with Keycloak card selected

Bifrost Choose Provider screen with Keycloak card selected

Enter the details from the previous steps: * **Server URL**: your Keycloak base URL - no `/realms/...` suffix (e.g. `https://keycloak.company.com`) * **Realm**: your realm name (e.g. `Bifrost`) * **Client ID**: the client ID you set in Step 1 (e.g. `bifrost-oidc`) * **Client Secret**: copied from [Step 2](#step-2-copy-your-client-secret) * **Audience**: optional - leave blank to default to the Client ID * **Team IDs Field (Optional)**: leave as `groups` to match the mapper you created in Step 3 Click **Verify & Next** to confirm the connection. Bifrost Provider Configuration form for Keycloak with Server URL, Realm, Client ID, Client Secret, and Team IDs Field filled in

Bifrost Provider Configuration form for Keycloak with Server URL, Realm, Client ID, Client Secret, and Team IDs Field filled in

On the Attribute Mapping screen, click **Discover Claims**. Bifrost opens a sign-in popup with your Keycloak realm - no session is created. Once you authenticate, it returns the exact claims your Keycloak tenant is sending in the JWT. Confirm that `groups` and `realm_access.roles` appear before building your mappings. Bifrost Discover Claims screen showing claims including email, groups with /Engineering and /Platform paths, and realm_access with roles array

Bifrost Discover Claims screen showing claims including email, groups with /Engineering and /Platform paths, and realm_access with roles array

Use the sections below the claim list to map Keycloak claim values to Bifrost roles, teams, and business units. **Attribute-to-Role Mappings** Map a claim value to a Bifrost role. All matching rules are evaluated. If several rules match, Bifrost picks one using your chosen resolution strategy: * **The role with the most permissions** (default) * **The first matching role, by list order** (drag rows to set priority) If no rule matches, no role is assigned and login is denied. Example: map `realm_access.roles` → `realm-admin` → **Admin**, and `realm_access.roles` → `bifrost-viewer` → **Viewer**. **Attribute-to-Team Mappings** Map a claim value to a Bifrost team. All matching rules apply. Three value formats work: * **Exact value** - e.g. `/Engineering` maps that specific group to a fixed team name * **`*`** - syncs the claim value directly as the team name * **`/${*}`** - extracts the group name from Keycloak's full group path - e.g. `/${*}` matches `/Engineering` and creates team **Engineering**, and matches `/Platform` and creates team **Platform** **Attribute-to-Business Unit Mappings** Same wildcard support as team mappings. Three value formats work: * **Exact value** - maps a specific claim value to a fixed business unit name * **`*`** - syncs the claim value directly as the business unit name * **`/${*}`** - extracts the group name from Keycloak's full group path, same as team mappings (e.g. `/${*}` on `/Engineering` → business unit **Engineering**) * When a rule matches, the resolved business unit is assigned to the user. All matching rules apply, so a user can belong to several business units at once * A business unit you assign by hand is never removed by a sync, and one granted from a claim stays even if that claim later stops appearing - remove it by hand or change the mapping $Bifrost Attribute Mapping screen showing realm_access.roles mapped to Admin and Viewer roles, and groups mapped with /${*} wildcard to extract team names$ Click **Next** when done. Review your configuration on the final screen and click **Enable**. Restart your Bifrost server after enabling for the changes to take effect. *** ## Optional Next Steps **Import users from Keycloak** - once SSO is configured, you can bulk-import users from Keycloak into Bifrost without waiting for each user to log in. Go to **Governance** → **Users** → **Sync Users from Keycloak** and filter by group or realm role to preview and import matching users. Sync Users from IdP dialog showing Filter by Groups with Engineering, Operations, and Platform checkboxes, and Filter by Roles section

Sync Users from IdP dialog showing Filter by Groups with Engineering, Operations, and Platform checkboxes, and Filter by Roles section

Imported users appear in **Governance** → **Users** with their role and team assignments applied immediately. Bifrost Users page showing a user with Admin role and Engineering and Platform teams, marked Managed by Keycloak

Bifrost Users page showing a user with Admin role and Engineering and Platform teams, marked Managed by Keycloak

*** ## Troubleshooting **`serverUrl must not include /realms/{realm}`** - the Server URL field takes the base Keycloak URL only. Set the realm separately in the Realm field. Example: `https://keycloak.company.com` + Realm `Bifrost` - not `https://keycloak.company.com/realms/Bifrost`. **Users are redirected back to login** - confirm the client's **Valid redirect URIs** exactly match your Bifrost login URL (trailing slash matters). Verify the client is **Enabled** in Keycloak. **Roles not appearing in the token** - check that the **User Realm Role** mapper adds to both ID and access tokens. Use **Evaluate** on the client scope in Keycloak to preview the token a specific user would receive. **Groups not appearing in the token** - verify the **Group Membership** mapper has **Full group path** enabled and is added to ID token, access token, and userinfo. **`jwks keys not found`** - confirm the Server URL is reachable from Bifrost. The JWKS endpoint is `{serverUrl}/realms/{realm}/protocol/openid-connect/certs`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.