Overview
This guide walks you through configuring Microsoft Entra ID (formerly Azure Active Directory) as your identity provider for Bifrost Enterprise. After completing this setup, your users will be able to sign in to Bifrost using their Microsoft credentials, with roles and team memberships automatically synchronized.
Prerequisites
- A Microsoft Azure account with access to Entra ID (Azure AD)
- Admin access to create app registrations
- Bifrost Enterprise deployed and accessible
- The redirect URI for your Bifrost instance (e.g.,
https://your-bifrost-domain.com/login)
Step 1: Register an Application
- Sign in to the Azure Portal
- Navigate to Microsoft Entra ID (or Azure Active Directory)
- Go to App registrations
- Click New registration
Configure the registration:
| Field | Value |
|---|
| Name | Bifrost Enterprise |
| Supported account types | Accounts in this organizational directory only (Single tenant) |
| Redirect URI | Web: https://your-bifrost-domain.com/login |
- Click Register
- After registration, note down the following from the Overview page:
| Value | Where to Find |
|---|
| Application (client) ID | Overview → Essentials |
| Directory (tenant) ID | Overview → Essentials |
Step 2: Create App Roles
Configure roles in Entra that map to Bifrost’s role hierarchy (Admin, Developer, Viewer).
- In your app registration, go to App roles
- Click Create app role
- Create the following three roles:
Viewer Role
| Field | Value |
|---|
| Display name | Viewer |
| Allowed member types | Users/Groups |
| Value | viewer |
| Description | Viewer role on Bifrost |
| State | Enabled |
Developer Role
| Field | Value |
|---|
| Display name | Developer |
| Allowed member types | Users/Groups |
| Value | developer |
| Description | Developer role on Bifrost |
| State | Enabled |
Admin Role
| Field | Value |
|---|
| Display name | Admin |
| Allowed member types | Users/Groups |
| Value | admin |
| Description | Admin role on Bifrost |
| State | Enabled |
The role Value must be lowercase (admin, developer, viewer) to match Bifrost’s role resolution logic. Users with multiple roles will be assigned the highest privilege role.
Step 3: Enable Assignment Required
To control which users can access Bifrost, enable assignment requirement on the Enterprise Application.
- Go to Enterprise applications (from the main Entra ID menu)
- Find and select Bifrost Enterprise
- Go to Properties
- Set Assignment required? to Yes
- Set Enabled for users to sign-in? to Yes
- Click Save
Step 4: Create a Client Secret
Bifrost requires a client secret for OAuth authentication.
- Go back to App registrations → Bifrost Enterprise
- Navigate to Certificates & secrets
- Click New client secret
| Field | Value |
|---|
| Description | Bifrost Enterprise Secret |
| Expires | Choose based on your security policy (e.g., 24 months) |
- Click Add
- Copy the secret value immediately - it won’t be shown again!
Store the client secret securely. You’ll need it for the Bifrost configuration.
Ensure your application has the necessary permissions.
-
In your app registration, go to API permissions
-
Click Add a permission
-
Select Microsoft Graph
-
Choose Delegated permissions
-
Add the following permissions:
openidprofileemailoffline_access (for refresh tokens)
-
Click Add permissions
-
If required by your organization, click Grant admin consent for [Your Organization]
By default, Entra includes the roles claim when app roles are assigned. To include group memberships for team synchronization:
- Go to Token configuration
- Click Add groups claim
- Select:
- Security groups or Groups assigned to the application
- For token type, enable ID and Access
- Click Add
Group IDs from Entra will be used as team IDs in Bifrost. You may want to create groups in Entra that correspond to your teams.
Step 7: Assign Users and Roles
- Go to Enterprise applications → Bifrost Enterprise
- Navigate to Users and groups
- Click Add user/group
- Select users or groups
- Select the appropriate role (Admin, Developer, or Viewer)
- Click Assign
You can assign roles to groups for easier management. All users in a group will inherit the assigned role.
Now configure Bifrost to use Microsoft Entra as the identity provider.
Using the Bifrost UI
- Navigate to Workspace → SCIM in your Bifrost dashboard
- Select Microsoft Entra as the SCIM Provider
- Enter the following configuration:
| Field | Value |
|---|
| Client ID | Application (client) ID from Azure |
| Tenant ID | Directory (tenant) ID from Azure |
| Client Secret | The secret you created in Step 4 |
| Audience | Your Client ID (optional, defaults to Client ID) |
| App ID URI | api://{client-id} (optional, for v1.0 tokens) |
- Toggle Enabled to activate the provider
- Click Save Configuration
After saving, you’ll need to restart your Bifrost server for the changes to take effect.
Configuration Reference
| Field | Required | Description |
|---|
tenantId | Yes | Azure Directory (tenant) ID |
clientId | Yes | Application (client) ID |
clientSecret | Yes | Client secret for OAuth authentication |
audience | No | JWT audience for validation (defaults to clientId) |
appIdUri | No | App ID URI for v1.0 tokens (e.g., api://{clientId}) |
userIdField | No | JWT claim for user ID (default: oid) |
rolesField | No | JWT claim for roles (default: roles) |
teamIdsField | No | JWT claim for group/team IDs (default: groups) |
Role Mapping
Bifrost automatically maps Entra app roles to its internal role hierarchy:
| Entra Role Value | Bifrost Role | Privilege Level |
|---|
admin | Admin | Highest |
developer | Developer | Medium |
viewer | Viewer | Lowest |
viewer and developer roles will be assigned the Developer role in Bifrost.
Default Role: Users without any assigned role will default to the Viewer role.
Testing the Integration
- Open your Bifrost dashboard in a new browser or incognito window
- You should be redirected to Microsoft login
- Log in with an assigned user
- After successful authentication, you’ll be redirected back to Bifrost
- Verify the user appears in the Bifrost users list with the correct role
Troubleshooting
User not redirected to Microsoft login
- Verify the SCIM provider is enabled in Bifrost
- Check that the Bifrost server was restarted after configuration
- Ensure the Tenant ID and Client ID are correct
”AADSTS50011: The reply URL does not match”
- Verify the redirect URI in your app registration exactly matches your Bifrost login URL
- Ensure there are no trailing slashes or protocol mismatches (http vs https)
“AADSTS7000215: Invalid client secret”
- Regenerate the client secret in Azure
- Ensure you’re using the secret Value, not the secret ID
- Check for any leading/trailing whitespace when copying
Roles not appearing in token
- Ensure users are assigned to the Enterprise Application with a role
- Verify app roles are created with the correct lowercase values
- Check that “Assignment required” is enabled
”AADSTS70011: The provided request includes an invalid scope”
- This usually happens when mixing
.default scope with other scopes
- Bifrost handles this automatically - ensure you’re using the latest version
Groups not syncing as teams
- Verify the groups claim is configured in Token configuration
- Ensure users are members of the groups
- Check that groups are created and assigned in Entra
Token validation errors
- Ensure the Tenant ID matches your Azure directory
- Verify the Client ID is correct
- Check that the app registration is in the same tenant as your users
Next Steps
