> ## Documentation Index > Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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:///login` * Bifrost [roles](../rbac) created for the roles you plan to map *** ## Step 1: Create a web application 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. Zitadel Create Application wizard showing Bifrost OIDC name and Web type selected On the **Redirect URIs** step, add your login callback to **Redirect URIs**: ``` https:///login ``` Optionally, to use the **Discover Claims** feature during Bifrost setup, also add: ``` https:///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. Zitadel application redirect URIs step showing the Bifrost login and discovery callback URLs After saving, open the application detail page. Copy the **Client ID** shown in the OIDC Settings section. Zitadel Bifrost OIDC application detail page showing Client ID in the OIDC Settings section *** ## 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. 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 Zitadel project General settings showing Return user roles during authentication checkbox enabled 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) 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`). Zitadel project Roles tab showing Bifrost-Admin and Bifrost-Viewer roles created Go to **Role Assignments** and authorize each user to the relevant project roles. Zitadel Role Assignments screen showing users assigned to Bifrost-Admin and Bifrost-Viewer roles *** ## Step 4: Configure token settings 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** Zitadel application token settings showing JWT type selected and Add user roles to access token enabled *** ## 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. Navigate to **Users → Service Accounts → New**. Name it (e.g. `Bifrost Service Account`) and create it. Open the service account and go to **Actions → Generate Client Secret**. Zitadel Bifrost Service Account page with Actions menu open showing Generate Client Secret option 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. 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). Zitadel Add an Administrator dialog showing Bifrost Service Account being added with org manager role *** ## Step 6: Configure Bifrost In your Bifrost dashboard, go to **Governance** → **User Provisioning**. Select **Zitadel** as the identity provider and click **Next**. Bifrost Choose Provider screen with Zitadel highlighted 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. Bifrost Provider Configuration form for Zitadel showing Domain, Project ID, Client ID, and Service Account fields with connection verified 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. 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 Bifrost Attribute Mapping screen showing role mappings for urn:zitadel:iam:org:project:roles and team mapping with wildcard for groups Click **Next** when done. Review your full configuration on the final screen - connection details and attribute mappings - then click **Save & Enable**. Bifrost Review and Enable screen showing Zitadel domain, Client ID, role and team attribute mappings summary 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`.