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://<your-bifrost-domain>/login

---

Step 1: Create an OIDC Client

1. Open the Clients list

   In the Keycloak Admin Console, select your realm from the top-left dropdown.

   Go to Clients in the left nav and click Create client.

   

   The Clients list — click Create client to start.

2. Fill in General settings

   Set the following fields:

   • Client type: OpenID Connect
   • Client ID: bifrost-oidc (or any identifier you prefer)
   • Name: Bifrost

   Click Next.

   

   General settings — set Client type to OpenID Connect and provide a Client ID.

3. Configure Capability config

   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.

4. Configure Login settings

   Set your redirect URIs:

   • Root URL: https://<your-bifrost-domain>
   • Valid redirect URIs: https://<your-bifrost-domain>/login

   Optionally, to use Discover Claims during setup, also add:

   https://<your-bifrost-domain>/workspace/scim/oauth-discover-callback
   

   Click Save.

   

   Login settings — add your Bifrost login URL and optionally the Discover Claims callback URI.

5. Grant Admin REST API permissions to the service account

   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.

---

Step 2: Copy Your Client Secret

1. Open the Credentials tab

   Open the bifrost-oidc client and go to the Credentials tab.

   Copy the Client Secret — you will need it in Step 5.

   

   Credentials tab — copy the Client Secret.

---

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.

1. Open the dedicated scope

   In the bifrost-oidc client, go to the Client scopes tab.

   Click on the bifrost-oidc-dedicated scope.

   

   Client scopes tab — open the dedicated scope to add mappers.

2. Add the Group Membership mapper

   Click Add mapper → By configuration.

   

   Configure a new mapper — select Group Membership from the list.

   Select Group Membership and configure it:

   Field	Value
   Name	Groups
   Token Claim Name	groups
   Full group path	On
   Add to ID token	On
   Add to access token	On
   Add to userinfo	On

   Click Save.

   

   Group Membership mapper — Full group path must be On so Bifrost receives paths like /Engineering instead of just Engineering.

   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.

3. Add the User Realm Role mapper

   Click Add mapper → By configuration again.

   Select User Realm Role from the list.

   

   Select User Realm Role from the mapper list to expose realm roles in the JWT.

   Configure it:

   Field	Value
   Name	realm_roles
   Token Claim Name	realm_access.roles
   Claim JSON Type	String
   Multivalued	On
   Add to ID token	On
   Add to access token	On

   Click Save.

   

   User Realm Role mapper — Token Claim Name realm_access.roles matches the dotted path Bifrost uses for role lookup.

---

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

1. Open User Provisioning and choose Keycloak

   In your Bifrost dashboard, go to Governance → User Provisioning.

   Select Keycloak as the identity provider and click Next.

   

   Select Keycloak from the list of identity providers.

2. Fill in the provider configuration

   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
   • 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.

   

   Provider Configuration — enter your Keycloak Server URL, Realm, Client ID, and Client Secret.

3. Discover claims

   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.

   

   Discover Claims shows the live JWT from Keycloak — confirm groups (full paths) and realm_access.roles are present.

4. Set up attribute mappings

   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 multiple rules match, the role with the highest permissions is assigned
   • If no rule matches, the user is not assigned a role 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 all of that user’s teams
   • Manually assigned teams are left unchanged

   

   Attribute Mapping — role rules use realm_access.roles, team rules use groups with /${*} to extract the team name from Keycloak's full group path.

   Click Next when done.

5. Review and enable

   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 Keycloak — filter by group membership or realm role to select which users to import into Bifrost.

Imported users appear in Governance → Users with their role and team assignments applied immediately.

Users page after syncing — users are marked Managed by Keycloak and receive their roles and teams from the attribute mappings.

---

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.