User Provisioning (OIDC + SCIM)

Overview

Bifrost Enterprise connects your organization’s identity provider to Bifrost through OAuth 2.0 / OIDC login, provider-backed directory sync, and inbound SCIM 2.0 provisioning. A single configuration gives you:

Single sign-on (SSO) via OAuth 2.0 / OIDC with JWKS-based JWT validation
Automatic role assignment using custom claims, app roles, or group-to-role mappings
Team synchronization from IdP groups into Bifrost teams
Business unit mapping from IdP attributes to Bifrost business units
Access profile mapping from IdP attributes to Bifrost access profiles
Project mapping from IdP attributes to Bifrost projects
Bulk user provisioning with filter-preview before import
Background directory sync on a schedule you choose (default every 24 hours) when SCIM Provisioning is off
Silent session refresh using server-stored refresh tokens, so IdP changes land without a new sign-in
Inbound SCIM 2.0 — IdPs can push user and group changes to Bifrost in real time via the /scim/v2 API

Once configured, users sign in to Bifrost with their corporate credentials and inherit the right role and permissions immediately — no manual account creation.

New to how this works? Read How identity sync works first - it explains how Bifrost turns IdP claims into roles, teams, business units, and access profiles, how login / refresh / SCIM paths differ, and how partial tokens are handled.

OIDC or SCIM satisfies dashboard authentication. Bifrost Enterprise treats the dashboard and admin API as authenticated when OAuth 2.0 / OIDC login or inbound SCIM 2.0 provisioning is configured. You do not need to additionally enable basic dashboard authentication with an admin username and password. Anywhere the docs require “dashboard auth to be configured”, such as creating a custom-path plugin in v2.0.0, an OIDC or SCIM deployment already meets that requirement.

User Provisioning overview in Bifrost dashboard

Supported Identity Providers

Pick your IdP to follow a step-by-step setup guide. All providers share the same Bifrost configuration surface — the only difference is how the OAuth client and role/group claims are created on the provider side.

Okta

OIDC with Org or Custom Authorization Servers, plus group-to-role mapping and API tokens for bulk user sync and 24-hour background reconciliation.

Microsoft Entra

Entra ID (Azure AD) with app roles, group claims, and v1.0 / v2.0 token support.

Keycloak

Self-hosted or managed Keycloak with OIDC login and Admin REST API based user provisioning.

Zitadel

Cloud or self-hosted Zitadel with project-scoped role claims and service-account-based provisioning.

Google Workspace

Google Workspace domains with OAuth login plus optional Directory API sync via a service account.

Auth0

Auth0 with Post Login Actions for custom claims, role-to-role mapping, and optional M2M app for bulk user sync.

Generic OIDC

Any standards-compliant OIDC provider — PingIdentity, ForgeRock, OneLogin, JumpCloud, and others not covered by a dedicated guide.

How it works

OIDC authentication and provisioning flow

Login — Bifrost redirects unauthenticated users to the provider’s authorization endpoint (Authorization Code flow).
Token exchange — on callback, Bifrost exchanges the code for an access token and refresh token, stores them in an HttpOnly cookie / server session, and validates the JWT against the provider’s JWKS.
Identity extraction — configurable JWT claims (userIdField, rolesField, teamIdsField) are mapped to a Bifrost user, role, and teams. Provider-specific app roles or custom attributes override claim lookup.
Attribute mapping — optional attributeRoleMappings, attributeTeamMappings, attributeBusinessUnitMappings, attributeAccessProfileMappings, and attributeProjectMappings translate claim values (e.g., a department string or Okta group name) into Bifrost roles, teams, business units, access profiles, or projects. A sign-in that resolves to no role is refused; there is no default role.
Session refresh — when a dashboard session expires, Bifrost silently refreshes it with the IdP and re-applies the fresh claims. If the refresh fails and the IdP reports the user is no longer active, the user is removed.
Directory sync — when SCIM Provisioning is off and directory API credentials are configured, Bifrost re-reads users from the IdP every Directory sync interval (default 24 hours), updating and removing users.
Bulk import — admins can preview users matching a filter and bulk-import them via the dashboard, which calls the provider’s user directory API. Unavailable while SCIM Provisioning is on.
SCIM push — IdPs configured with a SCIM provisioning connector can push user creates, updates, deactivations, and deletes to Bifrost in real time via /scim/v2.
Deprovisioning — a SCIM deactivation or DELETE, a failed session refresh for a user the IdP reports inactive, or directory sync no longer finding the user, removes the user locally. A refused sign-in never removes anyone.

For the full picture of what each channel changes, and how removals work, see How identity sync works.

Capabilities

Capability	Description
OAuth 2.0 / OIDC SSO	Authorization Code + PKCE with configurable scopes (`openid profile email offline_access`).
JWKS validation	JWTs are validated against the provider’s published JWKS keys; configuration is cached and auto-refreshed.
Role mapping	Map from a claim value (string or array) to Admin / Developer / Viewer or a custom role. When several match, the role with the most permissions wins by default, or the first matching rule if you choose list order.
Team mapping	Map multiple claim values to Bifrost teams in a single pass (a user can belong to many teams).
Business unit mapping	Map claim values to Bifrost business units. All matching rules apply, and a user can belong to many.
Access profile mapping	Map claim values to access profiles. All matching rules apply, and the user holds every profile they match.
Provisioning preview	Preview up to 50 users matching filters (groups, roles, departments) before importing.
Bulk import	Import matched users into Bifrost with role + team + BU assignments applied.
Team sync	Sync IdP groups as Bifrost teams with a single action.
Business unit sync	Sync IdP organizational units as Bifrost business units.
Inbound SCIM 2.0	IdPs push user and group changes to Bifrost via `/scim/v2` in real time. Bearer-token authenticated.
SCIM attribute mapping	SCIM user attributes (including enterprise extension fields) drive role, team, business unit, and access profile assignments automatically on every SCIM write.
Project mapping	Map claim values to projects.
Deprovisioning	SCIM DELETE and deactivation (`active: false`) are handled immediately. With SCIM off, Bifrost also removes users whose session refresh fails because the IdP reports them inactive, and users directory sync finds disabled, unassigned, or missing.
API key pass-through	Requests using Bifrost API keys (`bfst-*`) bypass OIDC user-provisioning middleware so inference traffic is not affected.

Background lifecycle reconciliation

Bifrost’s lifecycle model combines session refresh, background directory sync, and real-time SCIM push.

Session refresh - When a user’s session expires, Bifrost refreshes it with the IdP and re-applies the fresh claims. If a refresh fails and the IdP reports the user inactive, Bifrost removes the user.
Directory sync - With directory API credentials configured, Bifrost re-reads users from the IdP every Directory sync interval (bulkSyncInterval, default 24h, from 1h to 30d). It updates mapped roles, teams, business units, access profiles, and projects, and removes users that are disabled, unassigned, or no longer listed.
SCIM push - When SCIM Provisioning is on, your IdP pushes every change, including deactivations and deletes, in real time.

Configuration reference

All providers share the same outer config shape in config.json:

{
  "scim_config": {
    "enabled": true,
    "provider": "okta | entra | zitadel | keycloak | google | auth0 | generic | sailpoint",
    "config": {
      "...": "provider-specific fields - see each IdP guide"
    },
    "trusted_networks": [{ "cidr": "10.20.0.0/16", "description": "On-prem Keycloak" }]
  }
}

trusted_networks is the private IP/CIDR allowlist the SSRF guard consults before outbound discovery calls, so a self-hosted IdP on an internal network is reachable - see Generic OIDC for when you need it. Entries are { cidr, description }; a bare IP is a single host and hostnames are rejected. Declaring the key makes config.json own the whole list (an explicit [] clears ranges added from the dashboard); omit it to leave them untouched. Shared fields across providers:

Field	Required	Description
`clientId`	Yes	OAuth client ID from the identity provider.
`clientSecret`	Usually	Client secret. Required for confidential clients and (where applicable) token revocation.
`audience`	Optional	JWT audience to validate against. Defaults vary per provider.
`attributeRoleMappings`	Optional	List of `{ attribute, value, role }` rules. A user gets one role; `roleResolutionStrategy` picks it when several rules match.
`roleResolutionStrategy`	Optional	`highestPermissionCount` (default): the matching role with the most permissions, ties by list order. `order`: the first matching rule.
`attributeTeamMappings`	Optional	List of `{ attribute, value, team }` rules (all matches apply).
`attributeBusinessUnitMappings`	Optional	List of `{ attribute, value, businessUnit }` rules (all matches apply).
`attributeAccessProfileMappings`	Optional	List of `{ attribute, value, accessProfile }` rules (all matches apply). The user holds every profile they match, in addition to those from their role and any assigned by hand.
`attributeProjectMappings`	Optional	List of `{ attribute, value, project }` rules (all matches apply).
`claimsSyncMode`	Optional	Only used when SCIM Provisioning is on. `both` (default): sign-in claims and SCIM both update users. `scim`: SCIM alone; sign-in claims are ignored and new users must be pushed over SCIM. See Choosing a sync mode.
`bulkSyncInterval`	Optional	How often directory sync runs, e.g. `12h` or `7d` (default `24h`, from `1h` to `30d`). Not used when SCIM Provisioning is on or without directory API credentials.
`claimScimAttributes`	Optional	Map of claim name -> `{ attributeType, attributeValue }`, defining per-claim SCIM interpretation. See `claimScimAttributes`.

Provider-specific fields (domain, tenant ID, server URL, service-account credentials) are documented in each IdP’s setup guide.

Changing scim_config at runtime through the UI is applied after saving. For file-based configuration, restart the Bifrost server to pick up changes.

Environment variable support

Fields marked env.* supported accept "env.VAR_NAME" in addition to a literal value — Bifrost resolves the variable from the process environment at startup. Attribute mapping arrays are always plain JSON (they cannot reference env vars).

Okta

Field	JSON key	Required	env.* supported	Notes
Issuer URL	`issuerUrl`	Yes	Yes	Org server: `https://domain.okta.com`; Custom: `…/oauth2/default`
Client ID	`clientId`	Yes	Yes	Application Client ID
Client Secret	`clientSecret`	No	Yes	Required for token revocation
API Token	`apiToken`	No	Yes	Required for bulk user sync, team sync, and 24-hour Okta background reconciliation
Audience	`audience`	No	Yes	Only applies to Custom Authorization Server
Team IDs field	`teamIdsField`	No	Yes	JWT claim for group IDs (default: `"groups"`)
Role mappings	`attributeRoleMappings`	No	Plain only	Array of `{ attribute, value, role }` objects
Team mappings	`attributeTeamMappings`	No	Plain only	Array of `{ attribute, value, team, attributeType, attributeValue }` objects
Business unit mappings	`attributeBusinessUnitMappings`	No	Plain only	Array of `{ attribute, value, businessUnit, attributeType, attributeValue }` objects
Access profile mappings	`attributeAccessProfileMappings`	No	Plain only	Array of `{ attribute, value, accessProfile }` objects. One rule per profile; all matching rules apply.
Claim SCIM attributes	`claimScimAttributes`	No	Plain only	Map of claim name -> `{ attributeType, attributeValue }`

Microsoft Entra ID

Field	JSON key	Required	env.* supported	Notes
Tenant ID	`tenantId`	Yes	Yes	Azure tenant ID or `"common"` for multi-tenant
Client ID	`clientId`	Yes	Yes	Application (client) ID
Client Secret	`clientSecret`	Yes	Yes	Client secret for OAuth authentication
Cloud	`cloud`	No	Yes	`"commercial"` (default) \| `"gcc-high"` \| `"dod"`
Audience	`audience`	No	Yes	JWT audience override (default: `clientId`)
App ID URI	`appIdUri`	No	Yes	App ID URI for v1.0 tokens (e.g. `api://{clientId}`)
Team IDs field	`teamIdsField`	No	Yes	JWT claim for group IDs (default: `"groups"`)
Role mappings	`attributeRoleMappings`	No	Plain only	Array of `{ attribute, value, role }` objects
Team mappings	`attributeTeamMappings`	No	Plain only	Array of `{ attribute, value, team, attributeType, attributeValue }` objects
Business unit mappings	`attributeBusinessUnitMappings`	No	Plain only	Array of `{ attribute, value, businessUnit, attributeType, attributeValue }` objects
Access profile mappings	`attributeAccessProfileMappings`	No	Plain only	Array of `{ attribute, value, accessProfile }` objects. One rule per profile; all matching rules apply.
Claim SCIM attributes	`claimScimAttributes`	No	Plain only	Map of claim name -> `{ attributeType, attributeValue }`

Keycloak

Field	JSON key	Required	env.* supported	Notes
Server URL	`serverUrl`	Yes	Yes	Base URL, e.g. `https://keycloak.company.com` (no `/realms/…`)
Realm	`realm`	Yes	Yes	e.g. `"master"` or `"my-app"`
Client ID	`clientId`	Yes	Yes	Application client ID
Client Secret	`clientSecret`	No	Yes	For confidential clients
Audience	`audience`	No	Yes	JWT audience for token validation
Team IDs field	`teamIdsField`	No	Yes	JWT claim for group IDs (default: `"groups"`)
Role mappings	`attributeRoleMappings`	No	Plain only	Array of `{ attribute, value, role }` objects
Team mappings	`attributeTeamMappings`	No	Plain only	Array of `{ attribute, value, team, attributeType, attributeValue }` objects
Business unit mappings	`attributeBusinessUnitMappings`	No	Plain only	Array of `{ attribute, value, businessUnit, attributeType, attributeValue }` objects
Access profile mappings	`attributeAccessProfileMappings`	No	Plain only	Array of `{ attribute, value, accessProfile }` objects. One rule per profile; all matching rules apply.
Claim SCIM attributes	`claimScimAttributes`	No	Plain only	Map of claim name -> `{ attributeType, attributeValue }`

Zitadel

Field	JSON key	Required	env.* supported	Notes
Domain	`domain`	Yes	Yes	e.g. `"my-instance.zitadel.cloud"` or `"auth.company.com"`
Client ID	`clientId`	Yes	Yes	Application client ID
Client Secret	`clientSecret`	No	Yes	For confidential clients
Project ID	`projectId`	No	Yes	For project-scoped role claims
Audience	`audience`	No	Yes	Access-token audience override
Service account client ID	`serviceAccountClientId`	No	Yes	Service account for provisioning API access
Service account client secret	`serviceAccountClientSecret`	No	Yes	Service account secret
Team IDs field	`teamIdsField`	No	Yes	JWT claim for group IDs
Role mappings	`attributeRoleMappings`	No	Plain only	Array of `{ attribute, value, role }` objects
Team mappings	`attributeTeamMappings`	No	Plain only	Array of `{ attribute, value, team, attributeType, attributeValue }` objects
Business unit mappings	`attributeBusinessUnitMappings`	No	Plain only	Array of `{ attribute, value, businessUnit, attributeType, attributeValue }` objects
Access profile mappings	`attributeAccessProfileMappings`	No	Plain only	Array of `{ attribute, value, accessProfile }` objects. One rule per profile; all matching rules apply.
Claim SCIM attributes	`claimScimAttributes`	No	Plain only	Map of claim name -> `{ attributeType, attributeValue }`

Google Workspace

Field	JSON key	Required	env.* supported	Notes
Domain	`domain`	Yes	Yes	Google Workspace domain (e.g. `"company.com"`)
Client ID	`clientId`	Yes	Yes	Google OAuth2 client ID
Client Secret	`clientSecret`	No	Yes	For token revocation
Credential mode	`credentialMode`	No	Yes	`"inherit"` (ADC) \| `"env"` \| `"file"`
Service account JSON	`serviceAccountJson`	No	Yes	Raw service account JSON string
Service account env var	`serviceAccountEnvVar`	No	Yes	Env var containing the service account JSON
Service account file	`serviceAccountFile`	No	Yes	Path to the service account JSON key file
Admin email	`adminEmail`	Conditional	Yes	Required for Directory API / domain-wide delegation
Impersonate service account	`impersonateServiceAccount`	No	Yes	GCP SA email to impersonate when using ADC + Workload Identity
Audience	`audience`	No	Yes	Optional JWT audience override
Team IDs field	`teamIdsField`	No	Yes	Claim field for group IDs (default: `"groups"`)
Role mappings	`attributeRoleMappings`	No	Plain only	Array of `{ attribute, value, role }` objects
Team mappings	`attributeTeamMappings`	No	Plain only	Array of `{ attribute, value, team, attributeType, attributeValue }` objects
Business unit mappings	`attributeBusinessUnitMappings`	No	Plain only	Array of `{ attribute, value, businessUnit, attributeType, attributeValue }` objects
Access profile mappings	`attributeAccessProfileMappings`	No	Plain only	Array of `{ attribute, value, accessProfile }` objects. One rule per profile; all matching rules apply.
Claim SCIM attributes	`claimScimAttributes`	No	Plain only	Map of claim name -> `{ attributeType, attributeValue }`

Configuring from the dashboard

Navigate to Governance → User Provisioning in the Bifrost dashboard.
Select your identity provider from the OIDC Provider dropdown.
Fill in the provider-specific fields. Required fields are marked and validated on Verify.

Selecting an OIDC provider in the Bifrost dashboard

Click Verify to test credentials end-to-end. Bifrost will reach the provider’s JWKS / directory endpoint and report any failures.
Configure Attribute → Role / Team / Business Unit / Access Profile mappings as needed.
Toggle Enabled and click Save Configuration.

After enabling a new provider, the next dashboard load redirects to your IdP for login. Test in an incognito window first to avoid being locked out of your current session.

Attribute mappings

Attribute mappings let you translate claim values into Bifrost roles, teams, or business units without forcing your IdP admins to restructure claim names.

Preview of users matching an import filter

Each mapping is an ordered rule:

{
  "attribute": "department",
  "value": "Engineering",
  "role": "developer"
}

How matches combine:

Role mappings — a user holds exactly one role. By default the matching role with the most permissions wins, with ties going to the rule higher in the list; switch the role resolution setting to first matching role to make list order decide. A "value": "*" rule matches any value of the attribute, but only when the attribute is present; it is not a fallback for users without it. There is no default role: a sign-in that matches no role rule is refused.
Team mappings, business unit mappings, access profile mappings, and project mappings — all matching rules apply, so a user with department=Platform and group=sre can be placed on multiple teams, business units, and access profiles at once.

Claim values can be strings, arrays, or nested objects — Bifrost resolves dotted paths (e.g., realm_access.roles).

Access profile mappings

attributeAccessProfileMappings grant access profiles from claim values, using the same rule shape as team and business unit mappings:

{
  "attribute": "department",
  "value": "Engineering",
  "accessProfile": "Engineering Baseline"
}

Every matching rule applies. A user matching three rules holds all three profiles at once, and what they can reach is the sum of what each grants. A rule never replaces a profile granted by another rule, or one you assigned by hand — it only adds. See Multiple profiles for how a user’s profiles behave once they hold several. Write one rule per profile. To grant two profiles from the same claim value, write two rules with the same attribute and value and different accessProfile names. In the dashboard you do this in one row by picking several profiles; config.json stores them as separate rules, so the file will have more entries than the screen shows. Every sync re-checks these rules. A profile the user still matches is left alone, keeping its budget and accumulated usage; newly matched profiles are added, and ones they no longer match are removed. Profiles they hold through their role are not affected. If an admin assigned the same profile by hand, the mapping takes it over, and from then on it is removed when the user stops matching. A profile granted this way cannot be detached from the user directly — change the mapping or the underlying attribute instead.

`claimScimAttributes` field

attribute in a role/team/business-unit mapping rule is always an OIDC JWT claim name, and supports dotted paths into nested objects (e.g. realm_access.roles). By default Bifrost also uses that same name to look up the attribute in a SCIM-provisioned user’s stored profile (a flat key-value map) — so for standard SCIM attributes (department, title, userType, costCenter, etc.) mapping rules work unchanged across both the OIDC and SCIM paths. claimScimAttributes is a separate, top-level config field (a sibling of attributeTeamMappings / attributeBusinessUnitMappings, not a field on each rule) for the two cases where that default isn’t enough:

The claim is sourced from a SCIM Group, not a SCIM User attribute — e.g. your IdP pushes group membership via SCIM rather than embedding group names in the user token.
The OIDC claim path differs from the SCIM storage key — e.g. a custom attribute sent under profile.jobFunction in the JWT but stored as jobFunction in the SCIM profile.

It maps each claim name to its SCIM source type and lookup key:

{
  "claimScimAttributes": {
    "groups": {
      "attributeType": "group",
      "attributeValue": "displayName"
    },
    "profile.jobFunction": {
      "attributeType": "user",
      "attributeValue": "jobFunction"
    }
  }
}

Field	Meaning
`attributeType`	`"user"` (default) matches JWT claims or SCIM User resource attributes. `"group"` matches the `displayName` of SCIM Group resources instead — use this when the claim key (e.g. `groups`) corresponds to group membership pushed via SCIM.
`attributeValue`	The SCIM lookup key for this claim — a SCIM User attribute key when `attributeType` is `"user"`, or the group match field (typically `displayName`) when `attributeType` is `"group"`. Defaults to the claim name when not set.

A role mapping can use attributeType: "group" too, so you can assign a role from group membership alone. "value": "*" works here and matches any group, which is useful as a catch-all giving every SCIM-provisioned group member a baseline role:

{
  "attribute": "groups",
  "value": "*",
  "role": "developer",
  "attributeType": "group"
}

{
  "attribute": "displayName",
  "value": "platform-team",
  "team": "Platform",
  "attributeType": "group"
}

A mapping rule then references the claim by its normal attribute name — e.g. { "attribute": "groups", "value": "platform-team", "team": "Platform" } — and Bifrost consults claimScimAttributes["groups"] to know it should match SCIM Group displayName rather than a SCIM User attribute. If you only use OIDC (no inbound SCIM push), claimScimAttributes has no effect.

Team and business unit membership

A user can belong to any number of teams and business units at once. Bifrost remembers how each membership was granted — by an admin, by SCIM, or from a sign-in claim — and uses that to decide what a later sync is allowed to change.

Granted by	How it is added	How it is removed
An admin	Assigned from the dashboard or the API	By an admin. A sync removes it only if your IdP has taken it over (see below).
SCIM	A SCIM user attribute or group push	By SCIM, when the attribute or group no longer points at that team or business unit
A sign-in claim	A mapping matching a claim in the user’s token	At a later sign-in or session refresh where the attribute is present and no longer matches

What this means in practice:

Each sync keeps its own assignments up to date. Memberships the user still matches are kept, and ones they no longer match are removed.
A missing attribute is not a removal. If a refreshed token leaves out the attribute entirely, Bifrost uses the value it last saw. Only an attribute that is present and no longer matches removes the membership.
Your IdP takes over matching manual memberships. If an admin added a user to a business unit by hand and a mapping later grants the same one, the membership follows the IdP from then on, including removal.
Turning SCIM on later is safe. SCIM takes over managing an assignment that came from a claim rather than adding a duplicate.

To view or change memberships from the API, use GET and POST /api/governance/business-units/{id}/users and DELETE /api/governance/business-units/{id}/users/{user_id}. The list response tells you how each member was granted, so you can tell an admin assignment from one your identity provider manages.

SCIM attribute suggestions

When configuring attribute mappings for SCIM-provisioned users, the following attributes are available from the user payload: Core attributes — sent by all SCIM-capable providers:

Attribute	Description
`userName`	The user’s unique identifier (usually email) at the provider.
`displayName`	The user’s display name.
`title`	Job title.
`userType`	User category (e.g. `"Employee"`, `"Contractor"`).

Enterprise extension attributes — sent by most providers via urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:

Attribute	Description
`department`	Department name.
`costCenter`	Cost center code.
`organization`	Organization name.
`division`	Division name.
`employeeNumber`	Employee ID.

Custom extension attributes — any additional attributes sent under custom URNs are flattened and made available by their field name for use in mappings.

Authenticate inference requests

With a provider configured, inference requests can authenticate as an individual user, not only with a virtual key. Bifrost accepts these credentials on inference routes:

Credential	Sent as	Governed by
Virtual key (`sk-bf-*`)	`Authorization: Bearer`, `x-bf-vk`, `x-api-key`, `x-goog-api-key`, or `api-key`	The virtual key
Identity-provider access token	`Authorization: Bearer <token>`	The user the token identifies
Bifrost session token, from Bifrost CLI or Bifrost Edge sign-in	`Authorization: Bearer ck-bf-agent-…`	The signed-in user

Bifrost validates an identity-provider token with the configured provider on every request. When enforce_auth_on_inference is on:

An invalid or expired token is rejected with 401. Bifrost does not refresh tokens sent in a header; the client must send a current one.
A valid token for a user Bifrost does not know yet provisions that user, the same way an SSO sign-in does. The request is rejected with 403 if the token maps to no role or the user was deprovisioned.

When enforcement is off, a token that fails validation does not block the request, and the request continues without a user identity.

Requests with both an identity token and a virtual key

A request can carry an identity-provider token in Authorization and a virtual key in another header, for example x-bf-vk. Dual Credential Conflict Behavior decides which one Bifrost uses. Set it in the dashboard under Settings → Security, or with client.dual_credential_conflict_behavior in config.json.

Value	Dashboard label	Behavior	Use when
`prefer_idp` (default)	Prefer IDP token	Bifrost validates the token and attributes the request to the user. The virtual key is ignored for that request.	Usage, budgets, and rate limits should follow the individual user
`prefer_vk`	Prefer virtual key	Bifrost authenticates and governs the request with the virtual key. The identity token is used only for MCP token exchange.	A shared application authenticates with its own virtual key but forwards each user’s token for MCP token exchange
`error`	Reject request	Bifrost rejects the request with `400`.	You require exactly one credential per request

{
  "client": {
    "dual_credential_conflict_behavior": "prefer_idp"
  }
}

With Helm, set bifrost.client.dualCredentialConflictBehavior.

Under prefer_idp, the virtual key is not a fallback. If the identity token is invalid or expired and inference authentication is enforced, the request fails with 401 even though it also carries a valid virtual key.

The setting applies only when the bearer token is an identity-provider JWT and another header carries a virtual key. Sending the same virtual key in both Authorization and x-bf-vk is not a conflict. Bifrost session tokens (ck-bf-agent-…) are also not subject to this setting. You cannot choose error while any MCP client uses token_exchange authentication, because token exchange relies on requests that carry both credentials. Bifrost rejects the change until those clients are removed.

Inbound SCIM 2.0 provisioning

Bifrost exposes a SCIM 2.0 endpoint that identity providers can use to push user and group changes in real time, without waiting for the next 24-hour reconciliation cycle.

Base URL

https://<your-bifrost-host>/scim/v2

Authentication

All SCIM requests must include a bearer token:

Authorization: Bearer <provisioning-token>

The provisioning token is generated per SCIM provider and can be rotated from the Bifrost dashboard under Governance → User Provisioning → SCIM Settings.

How SCIM writes trigger governance updates

Every SCIM create, replace, or patch immediately re-evaluates the user’s role, team, business unit, access profile, and project mappings against everything SCIM has pushed for that user. Changes are committed and broadcast to all cluster nodes before the SCIM response is returned. Group pushes with more than 500 members are applied in the background.

Roles follow SCIM: a matching rule sets the role, replacing the user’s current one. When nothing maps to a role, the role is removed.
Teams and business units an admin assigned by hand are kept, unless SCIM grants the same one, in which case SCIM takes it over.
Deactivation (active: false) removes the user’s keys, access profiles, and memberships but keeps their stored profile, so reactivating restores them. DELETE also clears the stored profile.

See How identity sync works for the full rules.

Bulk user provisioning

There are two ways to get users into Bifrost, depending on what your IdP supports: Via API token (bulk import): Providers that support a directory API (Okta, Entra, Keycloak, Zitadel, Google Workspace) allow you to preview and import users in bulk from the dashboard:

Go to Governance → User Provisioning → Import Users.
Select a filter — groups, roles, departments, or a custom query depending on provider support.
Click Preview to see up to 50 matching users.
Click Import to create them in Bifrost with role / team / BU assignments applied.

Re-running an import reconciles existing users — role and team changes in the IdP are reflected on the next import. Bulk import is unavailable while SCIM Provisioning is on; your IdP pushes users instead. To apply edited mapping rules to existing users without re-importing, use Reconcile existing users, with a preview first. See Applying rule changes to existing users. Via SCIM push (real-time): If the IdP supports SCIM provisioning (e.g. Okta with a SCIM app), you can configure it to push users to Bifrost automatically — no manual import needed. Users are created, updated, and deactivated in Bifrost as they change in the IdP. See the Inbound SCIM 2.0 provisioning section and your IdP’s setup guide for configuration steps.

Troubleshooting

Symptom	Likely cause
Access denied: no application role or group mapping is assigned to this user.	Make sure you have assigned the user to the Bifrost IdP application and they have a valid group/attribute mapping to a role in Bifrost.
Redirect loop on login	Make sure you have restarted pods/Bifrost instance after changing OIDC configuration, or check for a redirect URI mismatch. Exact string match required — check trailing slashes and `http` vs `https`.
`invalid audience`	`audience` field does not match the access token’s `aud` claim. Use the same value your IdP issues.
Empty roles / teams	Claim mapping is off. Verify the JWT at jwt.io and check `rolesField` / `teamIdsField`.
Token refresh failing	`offline_access` scope missing or refresh token revoked. Re-enable the scope and re-authenticate.
Can’t sign in as the first admin	There is no default role, not even for the first user. Map an IdP group or attribute to the Admin role before signing in.
”Provisioning is managed by SCIM”	The sync mode is SCIM only and your IdP hasn’t pushed this user yet. Assign them to the Bifrost app in your IdP.
SCIM `401 Unauthorized`	The `Authorization: Bearer <token>` header is missing or the provisioning token has been rotated. Rotate a new token and update your IdP SCIM connector.
SCIM writes not updating teams / roles	Ensure `attributeTeamMappings` / `attributeRoleMappings` reference the correct attribute name. SCIM attribute names and values are matched without regard to case; JWT claim names used at sign-in must match exactly.
SCIM group push not placing users in teams	Make sure `claimScimAttributes` sets `"attributeType": "group"` for the claim your `attributeTeamMappings` rules reference. Without this, group `displayName` is not evaluated against team mappings.

Provider-specific troubleshooting lives in each IdP’s guide.

Role-Based Access Control — permissions model and custom roles
How identity sync works — what each sync changes, and how removals work
Access Profiles — what users get from their profiles
Audit Logs — track authentication events and role changes

Getting Started

Moving from OSS

Release Cadence

Migration Guides

Features

Security

User Provisioning (OIDC + SCIM)

Overview

Supported Identity Providers

Okta

Microsoft Entra

Keycloak

Zitadel

Google Workspace

Auth0

Generic OIDC

How it works

Capabilities

Background lifecycle reconciliation

Configuration reference

Environment variable support

Okta

Microsoft Entra ID

Keycloak

Zitadel

Google Workspace

Configuring from the dashboard

Attribute mappings

Access profile mappings

`claimScimAttributes` field

Team and business unit membership

SCIM attribute suggestions

Authenticate inference requests

Requests with both an identity token and a virtual key

Inbound SCIM 2.0 provisioning

Base URL

Authentication

How SCIM writes trigger governance updates

Bulk user provisioning

Troubleshooting

​Overview

​Supported Identity Providers

Okta

Microsoft Entra

Keycloak

Zitadel

Google Workspace

Auth0

Generic OIDC

​How it works

​Capabilities

​Background lifecycle reconciliation

​Configuration reference

​Environment variable support

​Okta

​Microsoft Entra ID

​Keycloak

​Zitadel

​Google Workspace

​Configuring from the dashboard

​Attribute mappings

​Access profile mappings

​claimScimAttributes field

​Team and business unit membership

​SCIM attribute suggestions

​Authenticate inference requests

​Requests with both an identity token and a virtual key

​Inbound SCIM 2.0 provisioning

​Base URL

​Authentication

​How SCIM writes trigger governance updates

​Bulk user provisioning

​Troubleshooting

​Related

Overview

Supported Identity Providers

How it works

Capabilities

Background lifecycle reconciliation

Configuration reference

Environment variable support

Okta

Microsoft Entra ID

Keycloak

Zitadel

Google Workspace

Configuring from the dashboard

Attribute mappings

Access profile mappings

`claimScimAttributes` field

Team and business unit membership

SCIM attribute suggestions

Authenticate inference requests

Requests with both an identity token and a virtual key

Inbound SCIM 2.0 provisioning

Base URL

Authentication

How SCIM writes trigger governance updates

Bulk user provisioning

Troubleshooting

Related