Skip to main content

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.

​
Overview

This guide walks you through configuring Zitadel as your identity provider for Bifrost Enterprise. Zitadel uses standard OIDC with JWKS-based JWT validation, plus a separate service account for user provisioning (Zitadel web applications cannot perform the client_credentials grant - a dedicated service account is required for directory-level reads). After completing this guide users will sign in to Bifrost with their Zitadel credentials, and admins can bulk-import users and teams from the Zitadel Management API.

​
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
  • The redirect URI for your Bifrost instance (e.g. https://your-bifrost-domain.com/login)
  • Bifrost roles created for the roles you plan to map (Admin, Developer, Viewer, or custom)

​
Step 1: Create a Web Application

The Web Application is what end users log in through.
  1. Open the Zitadel Console and choose Projects → your project → New Application.
Creating a new application in Zitadel
  1. Configure the application:
FieldValue
TypeWeb
Authentication methodPKCE (recommended) or Basic
Redirect URIhttps://your-bifrost-domain.com/login
Post logout URIhttps://your-bifrost-domain.com
  1. After creating the app, note the Client ID from the application detail page.
Zitadel application Client ID
  1. If you chose a confidential authentication method, also copy the Client Secret (shown once).

​
Step 2: Enable role claims on the project (Optional)

In Bifrost, you can map any attribute to role. If you decide to map Zitadel project roles, then follow step 2 and step 3.
Zitadel only emits role claims in access tokens when the project is configured to assert them.
  1. Open Projects → your project → General.
  2. Enable Assert Roles on Authentication.
  3. Enable Check Authorization on Authentication if you want to enforce that every user has at least one project role.
Assert Roles on Authentication toggle in Zitadel
  1. Note the Project ID - you’ll need it for the Bifrost config so Bifrost can resolve the correct project roles.
Without Assert Roles on Authentication, the token will not contain role claims and every user will fall back to the default role (Viewer, or Admin for the first signin).

​
Step 3: Create project roles (Optional)

Create project roles in Zitadel
  1. In the same project, open the Roles tab and create a role for each Bifrost role you plan to map. Common pattern:
  2. Authorize users to the relevant roles via Users → Roles.
Create project roles in Zitadel

​
Step 4: Create a service account for provisioning

Web apps in Zitadel cannot use the client_credentials grant. Bifrost needs a dedicated service account to list users via the Management API.
  1. Navigate to Users → Service Accounts → New.
Creating a service account in Zitadel
  1. Name it (e.g. bifrost-provisioning) and create it.
  2. Open the service account → Actions → Generate Client Secret.
Creating a service account in Zitadel
  1. 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.
  1. Grant the service account IAM_USER_READ (or Org Owner if you want broader visibility):
    • Organization → Managers → Add Manager → select the service account → role IAM_USER_READ.
Assigning IAM_USER_READ to the service account

​
Step 5: App token settings

  1. Change Auth Token Type to JWT.
  2. Enable roles and profile info in ID token.
Assigning IAM_USER_READ to the service account

​
Step 6: Configure Bifrost

​
Using the Bifrost dashboard

  1. In Bifrost, go to Governance → User Provisioning.
  2. Select Zitadel as the SCIM Provider.
  3. Fill in the fields:
FieldValue
DomainYour Zitadel host, e.g. my-instance.zitadel.cloud or auth.company.com (no scheme, no path)
Project IDThe project ID from Step 2
Client IDWeb Application Client ID from Step 1
Client SecretWeb Application Client Secret from Step 1 (optional for PKCE)
AudienceOptional access-token audience override
Service Account Client IDFrom Step 4
Service Account Client SecretFrom Step 4
  1. Click Verify - Bifrost connects to Zitadel’s JWKS and service account token endpoints to confirm the credentials.
  2. Configure Attribute → Role / Team / Business Unit mappings if you need to translate project roles or metadata into Bifrost roles.
  3. Toggle Enabled and click Save Configuration.
Creating a service account in Zitadel

​
Using config.json

{
  "scim_config": {
    "enabled": true,
    "provider": "zitadel",
    "config": {
      "domain": "my-instance.zitadel.cloud",
      "projectId": "123456789012345678",
      "clientId": "123456789012345678@my-project",
      "clientSecret": "env.ZITADEL_CLIENT_SECRET",
      "serviceAccountClientId": "987654321098765432@my-project",
      "serviceAccountClientSecret": "env.ZITADEL_SA_CLIENT_SECRET",
      "teamIdsField": "groups"
    }
  }
}

​
Custom attribute mapping

You can also map any custom attributes to any entity (role, team or business unit). Make sure these are configured to send back to Bifrost in token configuration.
Attribute Mappings configuration in Bifrost

​
Configuration reference

FieldRequiredDescription
domainYesZitadel instance host (no scheme). Examples: my-instance.zitadel.cloud, auth.company.com.
clientIdYesClient ID of the Web Application used for user login.
clientSecretYesWeb Application secret. Omit for PKCE-only flows.
projectIdYesRequired to resolve project-scoped role claims and sync role grants.
audienceNoOverride the expected JWT aud claim.
serviceAccountClientIdYesService account used to list users via the Management API.
serviceAccountClientSecretYesService account secret (shown once in Zitadel).
attributeRoleMappingsYesOrdered list of attribute→role mappings.
attributeTeamMappingsNoAttribute→team mappings (all matches apply).
attributeBusinessUnitMappingsNoAttribute→business-unit mappings (all matches apply).

​
Testing the Integration

  1. Open the Bifrost dashboard in an incognito window.
  2. You’ll be redirected to Zitadel. Sign in with a user who has a project authorization.
  3. On successful login you return to Bifrost and appear in Governance → Users with the correct role.
  4. From Governance → User Provisioning → Import Users, verify you can preview and import additional users via the service account.

​
Troubleshooting

​
role claims missing in token

  • Enable Assert Roles on Authentication on the project (Step 2).
  • Ensure the user has an active authorization for the project.

​
invalid audience when validating the JWT

  • Check the audience field in the Bifrost config. It must match the aud claim issued by Zitadel. Leaving it empty uses the default (the project’s resource owner).

​
Service account cannot list users

  • Confirm the service account has IAM_USER_READ or Org Owner role in the organization.
  • Regenerate the client secret if you’ve lost it - the original secret cannot be retrieved.

​
Redirect URI mismatch

  • Zitadel requires an exact string match. Check for trailing slashes and http vs https.

​
Next Steps