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

Bifrost Enterprise uses SCIM-backed identity provisioning to connect your organization’s identity provider to Bifrost. 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
  • Bulk user provisioning with filter-preview before import
  • Silent token refresh using server-stored refresh tokens
Once configured, users sign in to Bifrost with their corporate credentials and inherit the right role and permissions immediately - no manual account creation.
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.

Microsoft Entra

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

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.

​
How it works

SCIM authentication and provisioning flow
  1. Login - Bifrost redirects unauthenticated users to the provider’s authorization endpoint (Authorization Code flow).
  2. 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.
  3. 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.
  4. Attribute mapping - optional attributeRoleMappings, attributeTeamMappings, and attributeBusinessUnitMappings translate arbitrary claim values (e.g., a department string or Okta group name) into Bifrost roles, teams, or business units.
  5. Bulk import - admins can preview users matching a filter and bulk-import them via the dashboard, which calls the provider’s user directory API.
  6. Silent refresh - when the access token expires, Bifrost uses the stored refresh token to mint a new one without requiring re-login.

​
Capabilities

CapabilityDescription
OAuth 2.0 / OIDC SSOAuthorization Code + PKCE with configurable scopes (openid profile email offline_access).
JWKS validationJWTs are validated against the provider’s published JWKS keys; configuration is cached and auto-refreshed.
Role mappingMap from a claim value (string or array) to Admin / Developer / Viewer or a custom role. Highest-privilege wins when multiple match.
Team mappingMap multiple claim values to Bifrost teams in a single pass (a user can belong to many teams).
Business unit mappingSame as team mapping but scoped to business units.
Provisioning previewPreview up to 50 users matching filters (groups, roles, departments) before importing.
Bulk importImport matched users into Bifrost with role + team + BU assignments applied.
Team syncSync IdP groups as Bifrost teams with a single action.
Business unit syncSync IdP organizational units as Bifrost business units.
DeprovisioningRe-running import reconciles removed users and updates role / team assignments.
API key pass-throughRequests using Bifrost API keys (bfst-*) bypass SCIM middleware so inference traffic is not affected.

​
Configuration reference

All providers share the same outer config shape in config.json: 
{
  "scim_config": {
    "enabled": true,
    "provider": "okta | entra | zitadel | keycloak | google | sailpoint",
    "config": {
      "...": "provider-specific fields - see each IdP guide"
    }
  }
}
Shared fields across providers:
FieldRequiredDescription
clientIdYesOAuth client ID from the identity provider.
clientSecretUsuallyClient secret. Required for confidential clients and (where applicable) token revocation.
audienceOptionalJWT audience to validate against. Defaults vary per provider.
attributeRoleMappingsOptionalOrdered list of { attribute, value, role } rules evaluated top-to-bottom.
attributeTeamMappingsOptionalList of { attribute, value, team } rules (all matches apply).
attributeBusinessUnitMappingsOptionalList of { attribute, value, businessUnit } rules (all matches apply).
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

FieldJSON keyRequiredenv.* supportedNotes
Issuer URLissuerUrlYesYesOrg server: https://domain.okta.com; Custom: …/oauth2/default
Client IDclientIdYesYesApplication Client ID
Client SecretclientSecretNoYesRequired for token revocation
API TokenapiTokenNoYesRequired for bulk user / team sync
AudienceaudienceNoYesOnly applies to Custom Authorization Server
Team IDs fieldteamIdsFieldNoYesJWT claim for group IDs (default: "groups")
Role mappingsattributeRoleMappingsNoPlain onlyArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoPlain onlyArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoPlain onlyArray of { attribute, value, businessUnit } objects

​
Microsoft Entra ID

FieldJSON keyRequiredenv.* supportedNotes
Tenant IDtenantIdYesYesAzure tenant ID or "common" for multi-tenant
Client IDclientIdYesYesApplication (client) ID
Client SecretclientSecretYesYesClient secret for OAuth authentication
CloudcloudNoYes"commercial" (default) | "gcc-high" | "dod"
AudienceaudienceNoYesJWT audience override (default: clientId)
App ID URIappIdUriNoYesApp ID URI for v1.0 tokens (e.g. api://{clientId})
Team IDs fieldteamIdsFieldNoYesJWT claim for group IDs (default: "groups")
Role mappingsattributeRoleMappingsNoPlain onlyArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoPlain onlyArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoPlain onlyArray of { attribute, value, businessUnit } objects

​
Keycloak

FieldJSON keyRequiredenv.* supportedNotes
Server URLserverUrlYesYesBase URL, e.g. https://keycloak.company.com (no /realms/…)
RealmrealmYesYese.g. "master" or "my-app"
Client IDclientIdYesYesApplication client ID
Client SecretclientSecretNoYesFor confidential clients
AudienceaudienceNoYesJWT audience for token validation
Team IDs fieldteamIdsFieldNoYesJWT claim for group IDs (default: "groups")
Role mappingsattributeRoleMappingsNoPlain onlyArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoPlain onlyArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoPlain onlyArray of { attribute, value, businessUnit } objects

​
Zitadel

FieldJSON keyRequiredenv.* supportedNotes
DomaindomainYesYese.g. "my-instance.zitadel.cloud" or "auth.company.com"
Client IDclientIdYesYesApplication client ID
Client SecretclientSecretNoYesFor confidential clients
Project IDprojectIdNoYesFor project-scoped role claims
AudienceaudienceNoYesAccess-token audience override
Service account client IDserviceAccountClientIdNoYesService account for provisioning API access
Service account client secretserviceAccountClientSecretNoYesService account secret
Team IDs fieldteamIdsFieldNoYesJWT claim for group IDs
Role mappingsattributeRoleMappingsNoPlain onlyArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoPlain onlyArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoPlain onlyArray of { attribute, value, businessUnit } objects

​
Google Workspace

FieldJSON keyRequiredenv.* supportedNotes
DomaindomainYesYesGoogle Workspace domain (e.g. "company.com")
Client IDclientIdYesYesGoogle OAuth2 client ID
Client SecretclientSecretNoYesFor token revocation
Credential modecredentialModeNoYes"inherit" (ADC) | "env" | "file"
Service account JSONserviceAccountJsonNoYesRaw service account JSON string
Service account env varserviceAccountEnvVarNoYesEnv var containing the service account JSON
Service account fileserviceAccountFileNoYesPath to the service account JSON key file
Admin emailadminEmailConditionalYesRequired for Directory API / domain-wide delegation
Impersonate service accountimpersonateServiceAccountNoYesGCP SA email to impersonate when using ADC + Workload Identity
AudienceaudienceNoYesOptional JWT audience override
Team IDs fieldteamIdsFieldNoYesClaim field for group IDs (default: "groups")
Role mappingsattributeRoleMappingsNoPlain onlyArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoPlain onlyArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoPlain onlyArray of { attribute, value, businessUnit } objects

​
SailPoint

SailPoint fields are plain values only - env.* references are not supported for any SailPoint config field.
FieldJSON keyRequiredNotes
ProductproductYes"isc" (SailPoint Identity Security Cloud) | "iiq" (IdentityIQ)
TenanttenantConditionalISC only: tenant name (e.g. "acme")
Client IDclientIdConditionalRequired for ISC; optional for IIQ OAuth
Client SecretclientSecretConditionalRequired for ISC; optional for IIQ OAuth
Base URLbaseUrlConditionalIIQ only: SCIM base URL
UsernameusernameConditionalIIQ basic auth username
PasswordpasswordConditionalIIQ basic auth password
Team IDs fieldteamIdsFieldNoJWT claim for group IDs
Role mappingsattributeRoleMappingsNoArray of { attribute, value, role } objects
Team mappingsattributeTeamMappingsNoArray of { attribute, value, team } objects
Business unit mappingsattributeBusinessUnitMappingsNoArray of { attribute, value, businessUnit } objects

​
Configuring from the dashboard

  1. Navigate to Governance → User Provisioning in the Bifrost dashboard.
  2. Select your identity provider from the SCIM Provider dropdown.
  3. Fill in the provider-specific fields. Required fields are marked and validated on Verify.
Selecting a SCIM provider in the Bifrost dashboard
  1. Click Verify to test credentials end-to-end. Bifrost will reach the provider’s JWKS / directory endpoint and report any failures.
  2. Configure Attribute → Role / Team / Business Unit mappings as needed.
  3. 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"
}
Rules are evaluated top-to-bottom:
  • Role mappings - first match wins. Set a fallback with "attribute": "*" at the end.
  • Team mappings and business unit mappings - all matching rules apply, so a user with department=Platform and group=sre can be placed on multiple teams.
Claim values can be strings, arrays, or nested objects - Bifrost resolves dotted paths (e.g., realm_access.roles).

​
Bulk user provisioning

Once SCIM is enabled, import users in bulk from your IdP:
  1. Go to Governance → User Provisioning → Import Users.
  2. Select a filter - groups, roles, departments, or a custom query depending on provider support.
  3. Click Preview to see up to 50 matching users.
  4. Click Import to create them in Bifrost with role / team / BU assignments applied.
Preview of users matching an import filter
Re-running an import reconciles existing users - role and team changes in the IdP are reflected on the next import.

​
Troubleshooting

SymptomLikely cause
Access denied: no application role or group mapping is assigned to this user.Make sure you have assigned user to the Bifrost IdP application and they have a valid group/attribute mapping to role in Bifrost
Redirect loop on loginMake sure you have restarted pods/Bifrost instance after changing SCIM configuration, or check for a redirect URI mismatch. Exact string match required - check trailing slashes and http vs https.
invalid audienceaudience field does not match the access token’s aud claim. Use the same value your IdP issues.
Empty roles / teamsClaim mapping is off. Verify the JWT at jwt.io and check rolesField / teamIdsField.
Token refresh failingoffline_access scope missing or refresh token revoked. Re-enable the scope and re-authenticate.
First user gets AdminBy design - if no matching role mapping applies, the first user is promoted to Admin so they can finish configuration. Subsequent users default to Viewer.
Provider-specific troubleshooting lives in each IdP’s guide.