393 lines
14 KiB
Plaintext
393 lines
14 KiB
Plaintext
---
|
|
title: "Setting up Microsoft Entra"
|
|
description: "Step-by-step guide to configure Microsoft Entra ID (Azure AD) as your identity provider for Bifrost Enterprise SSO authentication."
|
|
icon: "microsoft"
|
|
---
|
|
|
|
## 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
|
|
|
|
1. Sign in to the [Azure Portal](https://portal.azure.com)
|
|
2. Navigate to **Microsoft Entra ID** (or **Azure Active Directory**)
|
|
3. Go to **App registrations**
|
|
4. 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` |
|
|
|
|
5. Click **Register**
|
|
|
|
<Tip>
|
|
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](https://www.getmaxim.ai/bifrost/bifrost-logo-only.png)
|
|
</Tip>
|
|
|
|
6. After registration, note down the following from the **Overview** page:
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-app-information.png" alt="Entra App Registration Overview" />
|
|
</Frame>
|
|
|
|
| Value | Where to Find |
|
|
|-------|---------------|
|
|
| **Application (client) ID** | Overview → Essentials |
|
|
| **Directory (tenant) ID** | Overview → Essentials |
|
|
|
|
---
|
|
|
|
## Step 2: Create App Roles (Optional)
|
|
|
|
<Note>
|
|
This step is optional. You can create custom roles if thats the preferred way. Or you can map any attribute to role/team/business unit. Role mapping is required step.
|
|
</Note>
|
|
|
|
Configure roles in Entra that map to Bifrost's role hierarchy (Admin, Developer, Viewer).
|
|
|
|
1. In your app registration, go to **App roles**
|
|
2. Click **Create app role**
|
|
3. Create the following three roles:
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-create-app-roles.png" alt="Entra App Roles configuration" />
|
|
</Frame>
|
|
|
|
### 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 |
|
|
|
|
---
|
|
|
|
## Step 3: Enable Assignment Required
|
|
|
|
To control which users can access Bifrost, enable assignment requirement on the Enterprise Application.
|
|
|
|
1. Go to **Enterprise applications** (from the main Entra ID menu)
|
|
2. Find and select **Bifrost Enterprise**
|
|
3. Go to **Properties**
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-enable-assignment.png" alt="Entra Enterprise Application Properties" />
|
|
</Frame>
|
|
|
|
4. Set **Assignment required?** to **Yes**
|
|
5. Set **Enabled for users to sign-in?** to **Yes**
|
|
6. Click **Save**
|
|
|
|
---
|
|
|
|
## Step 4: Create a Client Secret
|
|
|
|
Bifrost requires a client secret for OAuth authentication.
|
|
|
|
1. Go back to **App registrations** → **Bifrost Enterprise**
|
|
2. Navigate to **Certificates & secrets**
|
|
3. Click **New client secret**
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-create-client-secret.png" alt="Entra Enterprise Client Secrets" />
|
|
</Frame>
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| **Description** | Bifrost Enterprise Secret |
|
|
| **Expires** | Choose based on your security policy (e.g., 24 months) |
|
|
|
|
4. Click **Add**
|
|
5. **Copy the secret value immediately** - it won't be shown again!
|
|
|
|
<Warning>
|
|
Store the client secret securely. You'll need it for the Bifrost configuration.
|
|
</Warning>
|
|
|
|
---
|
|
|
|
## Step 5: Configure API Permissions
|
|
|
|
Ensure your application has the necessary permissions.
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-api-permissions.png" alt="Entra Enterprise API Permissions" />
|
|
</Frame>
|
|
|
|
1. In your app registration, go to **API permissions**
|
|
2. Click **Add a permission**
|
|
3. Select **Microsoft Graph**
|
|
4. Choose **Delegated permissions**
|
|
5. Add the following permissions:
|
|
- `openid`
|
|
- `profile`
|
|
- `email`
|
|
- `offline_access` (for refresh tokens)
|
|
|
|
6. In addition to above roles, following 4 roles are required
|
|
- `User.Read`
|
|
- `User.Read.All`
|
|
- `GroupMember.Read.All`
|
|
- `Group.Read.All`
|
|
|
|
7. Click **Add permissions**
|
|
8. If required by your organization, click **Grant admin consent for [Your Organization]**
|
|
|
|
|
|
|
|
---
|
|
|
|
## Step 6: Configure Token Claims (Optional)
|
|
|
|
<Note>
|
|
Groups and other attributes are required in the claim when you configure their mapping in Bifrost.
|
|
</Note>
|
|
|
|
By default, Entra includes the `roles` claim when app roles are assigned. To include group memberships for team synchronization:
|
|
|
|
1. Go to **Token configuration**
|
|
2. Click **Add groups claim**
|
|
3. Select:
|
|
- **Security groups** or **Groups assigned to the application**
|
|
- For token type, enable **ID** and **Access**
|
|
4. Click **Add**
|
|
|
|
---
|
|
|
|
## Step 7: Assign Users and Roles
|
|
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-user-assignments.png" alt="Entra User Assignments" />
|
|
</Frame>
|
|
|
|
1. Go to **Enterprise applications** → **Bifrost Enterprise**
|
|
2. Navigate to **Users and groups**
|
|
3. Click **Add user/group**
|
|
4. Select users or groups
|
|
5. Select the appropriate role (Admin, Developer, or Viewer)
|
|
6. Click **Assign**
|
|
|
|
<Tip>
|
|
You can assign roles to groups for easier management. All users in a group will inherit the assigned role.
|
|
</Tip>
|
|
|
|
---
|
|
|
|
## Step 8: Configure App Manifest
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-app-manifest.png" alt="Microsoft entra app manifest"/>
|
|
</Frame>
|
|
|
|
You will need to make 2 changes in the app manifest
|
|
|
|
```json
|
|
"requestedAccessTokenVersion": 2
|
|
```
|
|
|
|
and
|
|
|
|
```json
|
|
"optionalClaims": {
|
|
"idToken": [
|
|
{
|
|
"name": "roles",
|
|
"source": null,
|
|
"essential": false,
|
|
"additionalProperties": []
|
|
},
|
|
{
|
|
"name": "groups",
|
|
"source": null,
|
|
"essential": false,
|
|
"additionalProperties": ["cloud_displayname", "sam_account_name"]
|
|
}
|
|
],
|
|
"accessToken": [],
|
|
"saml2Token": []
|
|
}
|
|
```
|
|
|
|
## Step 9: Configure Bifrost
|
|
|
|
Now configure Bifrost to use Microsoft Entra as the identity provider.
|
|
|
|
### Using the Bifrost UI
|
|
|
|
<Frame>
|
|
<img src="/media/user-provisioning/entra-form.png" alt="Create token dialog in Okta" />
|
|
</Frame>
|
|
|
|
1. Navigate to **Governance** → **User Provisioning** in your Bifrost dashboard
|
|
2. Select **Microsoft Entra** as the SCIM Provider
|
|
3. 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) |
|
|
|
|
5. **Verify** configuration and see if you get any errors. Make sure you get no errors/warnings.
|
|
6. Toggle **Enabled** to activate the provider
|
|
7. Click **Save Configuration**
|
|
|
|
<Warning>
|
|
After saving, you'll need to restart your Bifrost server for the changes to take effect.
|
|
</Warning>
|
|
|
|
### 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) |
|
|
| `attributeRoleMappings` | Yes | Ordered list of attribute→role mappings. First match wins. |
|
|
| `attributeTeamMappings` | No | Attribute→team mappings (all matches apply). |
|
|
| `attributeBusinessUnitMappings` | No | Attribute→business-unit mappings (all matches apply). |
|
|
|
|
---
|
|
|
|
### Attribute Mappings
|
|
|
|
Attribute mappings let you translate Okta claim values into Bifrost roles, teams, or business units without restructuring your Okta claims. Bifrost supports three mapping types:
|
|
|
|
- **`attributeRoleMappings`**: map a claim value to a Bifrost role (Admin, Developer, Viewer, or a custom role)
|
|
- **`attributeTeamMappings`**: map a claim value to a Bifrost team
|
|
- **`attributeBusinessUnitMappings`**: map a claim value to a Bifrost business unit
|
|
|
|
These mappings work with any Okta claim — the `groups` claim from Step 5, the custom `role` claim from Step 4, or any other claim your authorization server includes in the token (e.g., `department`, `organization`).
|
|
|
|
To configure attribute mappings:
|
|
|
|
1. In the User Provisioning configuration, scroll down to **Attribute Mappings**
|
|
2. Click **Add Mapping** under the relevant mapping type (Role, Team, or Business Unit)
|
|
3. Enter the **Attribute** (the claim name from the token), the **Value** to match, and the target **Role**, **Team**, or **Business Unit**
|
|
4. Repeat for each rule you need
|
|
|
|
<Frame>
|
|
<img
|
|
src="/media/user-provisioning/attribute-to-entity-mapping.png"
|
|
alt="Attribute Mappings configuration in Bifrost"
|
|
/>
|
|
</Frame>
|
|
|
|
<Note>
|
|
When you mark value as "*" - the claim value is mapped as is to the entity name. Values comparisons are case-insensitive.
|
|
</Note>
|
|
|
|
### Custom attribute mapping
|
|
|
|
You can also map any custom attributes to any entity (role, team or business unit). Make sure these are configured to send back to Bifrost in token configuration.
|
|
|
|
<Frame>
|
|
<img
|
|
src="/media/user-provisioning/custom-attribute-mapping.png"
|
|
alt="Attribute Mappings configuration in Bifrost"
|
|
/>
|
|
</Frame>
|
|
|
|
|
|
#### Evaluation rules
|
|
|
|
- **Role mappings**: Ordered, first match wins. If no rule matches, users are not allowed to login into the system.
|
|
- **Team and business unit mappings**: All matching rules apply — users can be placed on multiple teams and business units simultaneously.
|
|
- **Claim values**: Can be strings, arrays, or nested objects. Bifrost resolves dotted paths (e.g., `realm_access.roles`).
|
|
|
|
<Note>
|
|
If a user matches multiple role mapping rules, the highest privilege role is assigned. If no
|
|
mapping matches, the first user to sign in receives the **Admin** role, and subsequent users receive the **Viewer**
|
|
role.
|
|
</Note>
|
|
|
|
5. Click **Save Configuration**
|
|
|
|
---
|
|
|
|
## Testing the Integration
|
|
|
|
1. Open your Bifrost dashboard in a new browser or incognito window
|
|
2. You should be redirected to Entra for authentication
|
|
3. Log in with an assigned user
|
|
4. After successful authentication, you'll be redirected back to Bifrost
|
|
5. 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
|
|
|
|
### 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
|
|
|
|
- **[User Provisioning (SCIM)](./user-provisioning)** - Overview of SCIM in Bifrost and alternative identity providers
|
|
- **[Advanced Governance](./advanced-governance)** - Learn about user budgets and compliance features
|
|
- **[Role-Based Access Control](./advanced-governance#role-hierarchy)** - Understand the Admin, Developer, Viewer hierarchy
|
|
- **[Audit Logs](./audit-logs)** - Monitor user authentication and activity
|
|
|