SSO using OIDC

Configure Zitadel (cloud or self-hosted) as your identity provider for Bifrost Enterprise using OpenID Connect.

Prerequisites

• A Zitadel instance (cloud at *.zitadel.cloud or self-hosted) with admin access
• An existing Zitadel Project in the organization you want to connect
• Bifrost Enterprise deployed and accessible
• Your Bifrost callback URL: https://<your-bifrost-domain>/login
• Bifrost roles created for the roles you plan to map

---

Step 1: Create a web application

1. Add a new application to your project

   Open the Zitadel Console and go to Projects → your project → New Application.

   Give it a name - e.g. Bifrost OIDC - and select Web as the application type.

   

   Create application - name it and select Web as the type.

2. Configure redirect URIs

   On the Redirect URIs step, add your login callback to Redirect URIs:

   https://<your-bifrost-domain>/login
   

   Optionally, to use the Discover Claims feature during Bifrost setup, also add:

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

   Discover Claims opens a one-time sign-in popup during configuration so Bifrost can inspect the exact JWT your Zitadel tenant sends - useful for verifying role claims are present before you build your attribute mappings. You can skip it and add the URL later if needed.

   

   Redirect URIs - the login callback is required; the discovery callback is optional and only used during initial setup.

3. Copy the Client ID

   After saving, open the application detail page. Copy the Client ID shown in the OIDC Settings section.

   

   Application OIDC settings - copy the Client ID. You will need it when configuring Bifrost.

---

Step 2: Enable role claims on the project (optional)

Skip this step if you plan to map roles using a different claim (e.g. groups or a custom attribute) rather than Zitadel project roles.

1. Enable Return user roles during authentication

   Open Projects → your project → General and enable:

   • Return user roles during authentication - required for role claims to appear in the token
   • Only authorized users can authenticate - enforces that every user has at least one project role

   

   Project General settings - enable Return user roles during authentication to include role claims in the token.

   Note the Project ID - you will need it for the Bifrost configuration.

   Without Return user roles during authentication, the token will not contain role claims and every user will fall back to the default role.

---

Step 3: Create project roles (optional)

1. Add roles to the project

   In the same project, open the Roles tab and create a role for each Bifrost role you plan to map (e.g. Bifrost-Admin, Bifrost-Viewer).

   

   Project Roles - create roles that match the values you will use in Bifrost attribute mappings.

2. Assign roles to users

   Go to Role Assignments and authorize each user to the relevant project roles.

   

   Role Assignments - each user needs at least one project role authorization for the role claim to appear in their token.

---

Step 4: Configure token settings

1. Set auth token type and enable claims

   In the application settings, go to Token Settings:

   1. Set Auth Token Type to JWT
   2. Enable Add user roles to the access token
   3. Enable User Info inside ID Token

   

   Token settings - set JWT token type and enable roles and profile info in the ID token.

---

Step 5: Create a service account for bulk sync (optional)

This step is only required if you want Bifrost to import users in bulk and sync them in the background every 24 hours. If you only need SSO login, skip this step.

1. Create the service account

   Navigate to Users → Service Accounts → New.

   Name it (e.g. Bifrost Service Account) and create it.

2. Generate a client secret

   Open the service account and go to Actions → Generate Client Secret.

   

   Generate a client secret for the service account - copy both the Client ID and Client Secret immediately.

   Copy the Client ID and Client Secret immediately - the secret is shown only once.

   Store the service account Client Secret in your password manager. It cannot be retrieved after this screen.

3. Grant the service account org access

   Go to Organization → Managers → Add Manager, select the service account, and assign it the Org User Manager role (or Org Owner Viewer for broader visibility).

   

   Organization Managers - add the service account as an admin so Bifrost can list users for directory sync.

---

Step 6: Configure Bifrost

1. Open User Provisioning and choose Zitadel

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

   Select Zitadel as the identity provider and click Next.

   

   Choose Provider - select Zitadel from the list of supported identity providers.

2. Fill in the provider configuration

   Enter the credentials you collected in the steps above:

   Field	Value
   Domain	Your Zitadel host, e.g. my-instance.zitadel.cloud or auth.company.com (no scheme, no path)
   Project ID	Project ID from Step 2
   Client ID	Web Application Client ID from Step 1
   Audience	Optional access-token audience override
   Service Account Client ID	From Step 5 (optional - bulk sync only)
   Service Account Client Secret	From Step 5 (optional - bulk sync only)

   Click Verify & Next to confirm the connection.

   

   Provider Configuration - enter your Zitadel domain, Project ID, Client ID, and service account credentials, then verify the connection.

3. Discover claims

   On the Attribute Mapping screen, click Discover Claims.

   Bifrost opens a sign-in popup - no session is created.

   Once you authenticate, it returns the exact claims your Zitadel tenant is sending in the JWT - including project roles, groups, and any custom metadata. Use this to confirm the urn:zitadel:iam:org:project:roles claim is present before building your mappings.

4. Set up attribute mappings

   Use the sections below the claim list to map Zitadel 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

   Attribute-to-Team Mappings

   Map a claim value to a Bifrost team. All matching rules apply.

   • Use a specific value (e.g. engineering) to map that exact claim value to a named Bifrost team
   • Use * as the value to sync the claim value directly as the team name
   • Use ${*} to extract part of the string - e.g. Bifrost Playground: ${*} Team matches Bifrost Playground: Alpha Team and creates team Alpha

   Attribute-to-Business Unit Mappings

   Same wildcard support as team mappings.

   • Use a specific value (e.g. platform) to map that exact claim value to a named Bifrost business unit
   • Use ${*} to extract a substring as the business unit name - e.g. Bifrost Playground: ${*} BU matches Bifrost Playground: Alpha BU and creates business unit Alpha
   • 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 - map urn:zitadel:iam:org:project:roles values to Bifrost roles, and map groups to teams and business units.

   Click Next when done.

5. Review and enable

   Review your full configuration on the final screen - connection details and attribute mappings - then click Save & Enable.

   

   Review & Enable - confirm your Zitadel domain, Client ID, and attribute mappings before activating the provider.

   Restart your Bifrost server after enabling for the changes to take effect.

---

How background sync works

Bifrost uses the service account credentials from this setup to sync users in the background every 24 hours. During that sync, Bifrost reconciles imported users, role mappings, team mappings, and business-unit mappings from Zitadel.

Every 15 minutes, Bifrost also refreshes active OIDC sessions. If a session cannot be refreshed, Bifrost checks with Zitadel whether the user is still active; if Zitadel reports the user as inactive, Bifrost decommissions that user locally.

---

Troubleshooting

Role claims missing in the token - enable Return user roles during authentication on the project (Step 2) and ensure the user has an active role authorization for the project.

invalid audience when validating the JWT - check the audience field in Bifrost. It must match the aud claim issued by Zitadel. Leaving it empty uses the project resource owner as the audience.

Service account cannot list users - confirm the service account has Org User Manager or Org Owner Viewer role in the organization. Regenerate the client secret if you’ve lost it - the original cannot be retrieved.

Redirect URI mismatch - Zitadel requires an exact string match. Check for trailing slashes and http vs https.