User Provisioning (OIDC)

Authenticate users, sync teams, and provision roles and business units from your identity provider using OAuth 2.0 / OIDC and background directory sync.

Overview

Bifrost Enterprise connects your organization’s identity provider to Bifrost through OAuth 2.0 / OIDC login plus provider-backed directory sync. 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
• Background lifecycle reconciliation every 24 hours for imported users
• OIDC session refresh checks every 15 minutes to confirm users are still active with the IdP
• Silent token refresh using server-stored refresh tokens when the user remains active

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

---

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.

---

How it works

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. Session refresh checks - every 15 minutes, Bifrost refreshes the OIDC session. If the session cannot be refreshed, Bifrost checks with the OIDC server whether the user is still active.
6. Background reconciliation - Bifrost periodically calls the configured provider’s directory APIs to reconcile imported users and mapped roles, teams, and business units.
7. Bulk import - admins can preview users matching a filter and bulk-import them via the dashboard, which calls the provider’s user directory API.
8. Daily sync - Bifrost reconciles imported users every 24 hours.
9. Decommissioning - if the OIDC server reports that a user is no longer active, or the 24-hour reconciliation no longer finds them in the active source set, Bifrost decommissions that user locally.

---

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. Highest-privilege wins when multiple match.
Team mapping	Map multiple claim values to Bifrost teams in a single pass (a user can belong to many teams).
Business unit mapping	Same as team mapping but scoped to business units.
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.
Deprovisioning	Bifrost checks user status during each 15-minute OIDC session refresh and reconciles imported users against the provider directory every 24 hours. Users that are inactive, disabled, unassigned, or missing from the source set are decommissioned locally.
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 does not currently support inbound SCIM management APIs from IdPs. Do not configure an IdP SCIM app or point an IdP provisioning connector at Bifrost /scim/v2 yet. SCIM management API support is coming soon.

Bifrost’s supported lifecycle model is source-side reconciliation plus OIDC session validation. Every 15 minutes, Bifrost refreshes active OIDC sessions. If a session cannot be refreshed, Bifrost checks with the OIDC server whether the user is still active; if the provider reports the user is inactive, Bifrost decommissions that user locally.

After users are imported, Bifrost also uses the configured provider credentials to sync with the IdP in the background every 24 hours. That sync updates mapped roles, teams, and business units, and decommissions imported users that are disabled, unassigned, or no longer present in the provider source set.

---

Configuration reference

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

{
  "scim_config": {
    "enabled": true,
    "provider": "okta | entra | zitadel | keycloak | google",
    "config": {
      "...": "provider-specific fields - see each IdP guide"
    }
  }
}

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	Ordered list of { attribute, value, role } rules evaluated top-to-bottom.
attributeTeamMappings	Optional	List of { attribute, value, team } rules (all matches apply).
attributeBusinessUnitMappings	Optional	List 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

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 } objects
Business unit mappings	attributeBusinessUnitMappings	No	Plain only	Array of { attribute, value, businessUnit } objects

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 } objects
Business unit mappings	attributeBusinessUnitMappings	No	Plain only	Array of { attribute, value, businessUnit } objects

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 } objects
Business unit mappings	attributeBusinessUnitMappings	No	Plain only	Array of { attribute, value, businessUnit } objects

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 } objects
Business unit mappings	attributeBusinessUnitMappings	No	Plain only	Array of { attribute, value, businessUnit } objects

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 } objects
Business unit mappings	attributeBusinessUnitMappings	No	Plain only	Array 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 OIDC Provider dropdown.
3. Fill in the provider-specific fields. Required fields are marked and validated on Verify.

4. Click Verify to test credentials end-to-end. Bifrost will reach the provider’s JWKS / directory endpoint and report any failures.
5. Configure Attribute → Role / Team / Business Unit mappings as needed.
6. 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.

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 OIDC user provisioning 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.

Re-running an import reconciles existing users - role and team changes in the IdP are reflected on the next import.

---

Troubleshooting

Symptom	Likely 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 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.
First user gets Admin	By 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.

---

Related

• Role-Based Access Control - permissions model and custom roles
• Advanced Governance - budgets, limits, and compliance
• Audit Logs - track authentication events and role changes