Skip to main content

​
Prerequisites

  • A Microsoft Azure account with admin access to create app registrations in Entra ID
  • Bifrost Enterprise deployed and accessible
  • Your Bifrost callback URL: https://<your-bifrost-domain>/login

​
Step 1: Register an application

1

Open App registrations

Sign in to the Azure Portal and navigate to Microsoft Entra ID → App registrations.Click New registration.
2

Fill in the registration form

Configure the new registration:
FieldValue
NameBifrost SSO
Supported account typesAccounts in this organizational directory only (Single tenant)
Redirect URIWeb: https://<your-bifrost-domain>/login
Register an Application dialog in Microsoft Entra showing name, account type, and redirect URI fields
Click Register.
You can add an app icon to make the application easily recognizable. The Bifrost logo is available at https://www.getmaxim.ai/bifrost/bifrost-logo-only.png.
3

Add the second redirect URI

After registering, go to Authentication and add a second redirect URI for the attribute discovery flow:
URIPurpose
https://<your-bifrost-domain>/loginOIDC sign-in callback
https://<your-bifrost-domain>/workspace/scim/oauth-discover-callbackAttribute discovery callback
Authentication blade showing the two Bifrost redirect URIs configured

​
Step 2: Capture app registration information

1

Copy your Client ID and Tenant ID

Navigate to App registrations → Bifrost SSO → Overview.
Entra App Registration Overview page showing Application (client) ID and Directory (tenant) ID in the Essentials section
ValueWhere to find
Application (client) IDOverview → Essentials
Directory (tenant) IDOverview → Essentials

​
Step 3: Create app roles (optional)

1

Add roles to the app registration

This step is optional. App roles are one way to assign Bifrost roles to users, but you can also map any other Entra attribute (e.g. groups, department) instead. Role mapping itself is required.
In your app registration, go to App roles and click Create app role.Create a role for each Bifrost role you want to use. For example, for the Viewer role:
FieldValue
Display nameViewer
Allowed member typesUsers/Groups
Valueviewer
DescriptionViewer role on Bifrost
StateEnabled
Repeat with developer and admin.
Entra App Roles list showing Admin, Developer, and Viewer roles configured for the Bifrost Enterprise application

​
Step 4: Create a client secret

1

Generate a secret

In your app registration, go to Certificates & secrets and click New client secret.
FieldValue
DescriptionBifrost Enterprise Secret
ExpiresChoose based on your security policy (e.g. 24 months)
Click Add.
Entra Certificates and secrets page showing the client secret value
Copy the secret Value immediately — it is only shown once. Do not copy the Secret ID by mistake.

​
Step 5: Configure API permissions (optional — bulk sync only)

This step is only required if you plan to use bulk user sync (importing users via the User Provisioning page). For standard OIDC login, skip this step — role and team mappings are evaluated from the JWT at login time.
1

Add the required permissions

In your app registration, go to API permissions and click Add a permission → Microsoft Graph.Add the following Delegated permissions:
  • openid, profile, email, offline_access, User.Read
Add the following Application permissions:
  • User.Read.All, GroupMember.Read.All, Group.Read.All
  • Application.Read.All — needed to read the app role catalog during bulk sync
  • AppRoleAssignment.ReadWrite.All — needed to read each user’s app role assignments
Entra API permissions page showing all configured Delegated and Application permissions for Microsoft Graph
Permission type matters: openid, profile, email, offline_access, and User.Read must be Delegated, while the remaining five must be Application. The same name can appear under both types — adding the wrong one will cause failures even though the permission appears granted.
2

Grant admin consent

Click Grant admin consent for [Your Organization].Without admin consent, Application permissions are not effective even though they appear in the list.

​
Step 6: Configure token claims

1

Add a groups claim

If you prefer to configure claims via the App Manifest JSON in Step 7, you can skip this step — the manifest overrides UI-based token configuration.
In your app registration, go to Token configuration and click Add groups claim.Select Security groups or Groups assigned to the application, enable ID and Access token types, and click Add.
Token configuration page showing the groups claim configured for ID, Access, and SAML tokens
If you configure claims via the Manifest editor instead, also set "requestedAccessTokenVersion": 2 (or "accessTokenAcceptedVersion": 2 for legacy registrations) and "groupMembershipClaims": "ApplicationGroup" to restrict the groups claim to only app-assigned groups.

​
Step 7: Enable assignment requirement

1

Open the Enterprise Application

From the Entra ID main menu, go to Enterprise applications and find Bifrost SSO.
Enterprise Applications list in Microsoft Entra showing the Bifrost SSO entry
2

Set assignment requirement

Go to Properties.
Enterprise Application Properties showing Assignment required and Enabled for users to sign-in toggles
Set Assignment required? to Yes, Enabled for users to sign-in? to Yes, and click Save.

​
Step 8: Assign users and roles

1

Assign users or groups to the application

Go to Bifrost SSO → Users and groups and click Add user/group.Select users or groups, choose the appropriate role (Admin, Developer, or Viewer), and click Assign.
Enterprise Application Users and groups page showing assigned users with their roles
Assign roles to groups for easier management. All users in a group inherit the assigned role. The group itself must appear in Users and groups with a role selected — adding users to an unassigned group does not propagate roles.

​
Step 9: Configure Bifrost

1

Open User Provisioning and choose Entra

In your Bifrost dashboard, go to Governance → User Provisioning.Select Microsoft Entra as the identity provider and click Next.
Bifrost Choose Provider screen with Microsoft Entra highlighted
2

Fill in the provider configuration

Enter the credentials you collected in Steps 2 and 4:
FieldValue
Client IDApplication (client) ID from Step 2
Tenant IDDirectory (tenant) ID from Step 2
Client SecretThe secret value from Step 4
AudienceYour Client ID (optional, defaults to Client ID)
App ID URIapi://{client-id} (optional, for v1.0 tokens)
Click Verify & Next to confirm the connection.
3

Discover claims

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 Entra tenant is sending in the JWT.Use this to confirm that the attributes you configured in Steps 3 and 6 — such as roles and groups — are present before building your mappings.
Bifrost Discover Claims screen listing all claims returned by Entra including roles, groups, email, and custom attributes
4

Set up attribute mappings

Use the sections below the claim list to map Entra claim values to Bifrost roles, teams, and business units.Attribute-to-Role MappingsMap 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 MappingsMap 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 MappingsSame 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
  • When a rule matches, the resolved business unit is assigned to all of that user’s teams
Bifrost Attribute Mapping screen showing role, team, and business unit mapping rules
Setting a value to * maps the claim value directly as the entity name. Value comparisons are case-insensitive.
Click Next when done.
5

Review and enable

Review your configuration on the final screen, then click Enable.
Restart your Bifrost server after enabling for the changes to take effect.

​
How background sync works

Bifrost uses the app 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 Entra. Every 15 minutes, Bifrost also refreshes active OIDC sessions. If a session cannot be refreshed, Bifrost checks with Entra whether the user is still active; if Entra reports the user as inactive, Bifrost decommissions that user locally.

​
Optional next steps

Sync users and groups in real time — OIDC alone provisions users on first login. To keep Bifrost in sync with Entra as users are created, deactivated, or moved between groups, set up SCIM with Entra.

​
Troubleshooting

User is not redirected to Microsoft login — verify the provider is enabled in Bifrost and the server was restarted after saving. Check that the Tenant ID and Client ID are correct. AADSTS50011: The reply URL does not match — verify both redirect URIs in Authentication (Step 1) exactly match your Bifrost URLs. Check for trailing slashes or http vs https mismatches. AADSTS7000215: Invalid client secret — regenerate the client secret in Azure and ensure you are copying the secret Value, not the secret ID. Check for leading/trailing whitespace. Claim "roles" is not present in the token — the user signed in but Entra did not emit a roles claim. Common causes:
  • User isn’t assigned a role at the Enterprise Application level — edit the assignment in Step 9 and select a role
  • Role assignment is via a group that isn’t itself assigned to the app — the group must appear in Users and groups with a role selected
  • Optional roles claim is missing from the manifest — confirm Step 6 includes roles under optionalClaims.idToken (see the Note at the bottom of Step 6)
  • Sign out and back in to clear the cached token
Bulk user sync assigns Viewer instead of the mapped role — confirm the user has an app role assigned in Entra, and that Application.Read.All and AppRoleAssignment.ReadWrite.All are granted with admin consent (Step 5). Server logs will contain [ENTRA-ROLES] failed to fetch app role catalog: ... 403 if the permission is missing. Token validation errors — ensure the Tenant ID matches your Azure directory, the Client ID is correct, and the app registration is in the same tenant as your users.