Setting up Okta

​

Overview

This guide walks you through configuring Okta as your identity provider for Bifrost Enterprise. After completing this setup, your users will be able to sign in to Bifrost using their Okta credentials, with roles and team memberships automatically synchronized.

​

Prerequisites

• An Okta organization with admin access
• Bifrost Enterprise deployed and accessible
• The redirect URI for your Bifrost instance (e.g., https://your-bifrost-domain.com/login)
• Ensure you have created all the roles in Bifrost that you are aiming to map to with Okta.

---

​

Step 1: Create an OIDC Application

1. Log in to the Okta Admin Console
2. Navigate to Applications → Applications
3. Click Create App Integration

4. In the dialog, select:
   • Sign-in method: OIDC - OpenID Connect
   • Application type: Web Application

5. Click Next to continue

---

​

Step 2: Configure Application Settings

Configure the following settings for your application: General Settings:

• App integration name: Bifrost Enterprise
• Logo (optional): You can upload the Bifrost logo from https://www.getmaxim.ai/bifrost/bifrost-logo-only.png

Grant type:

• Enable Authorization Code
• Enable Refresh Token

Sign-in redirect URIs:

• Add your Bifrost login callback URL: https://your-bifrost-domain.com/login

Sign-out redirect URIs (Optional):

• Add your Bifrost base URL: https://your-bifrost-domain.com

Assignments:

• Choose Skip group assignment for now (we’ll configure this later)

6. Click Save to create the application
7. After saving, note down the following from the General tab:
   • Client ID
   • Client Secret (click to reveal)

---

​

Step 3: Create Custom Role Attribute (Optional)

To map Okta users to Bifrost roles (Admin, Developer, Viewer), you need to create a custom attribute.

1. Navigate to Directory → Profile Editor

2. Click on your application’s user profile (e.g., Bifrost Enterprise User)
3. Click Add Attribute
4. Configure the attribute:

5. Click Save

---

​

Step 4: Add Role Claim to Tokens (If you have added custom role attribute)

Configure the authorization server to include the role in the access token.

1. Navigate to Security → API → Authorization Servers
2. Click on your authorization server (e.g., default)
3. Go to the Claims tab
4. Click Add Claim

Configure the claim:

5. Click Create

---

​

Step 5: Configure Groups

Bifrost can automatically sync Okta groups for two purposes:

• Team synchronization — Groups are synced as Bifrost teams
• Role mapping — Groups can be mapped to Bifrost roles (Admin, Developer, Viewer) using Group-to-Role Mappings in the Bifrost UI.

​

Create Groups in Okta

1. Navigate to Directory → Groups

2. Click Add group
3. Create groups that correspond to your teams or roles (e.g., bifrost-staging-admins, bifrost-staging-viewers)

​

Add Groups Claim to Tokens

This approach adds the groups claim through your authorization server, providing more flexibility for complex configurations.

1. Navigate to Security → API → Authorization Servers
2. Select your authorization server (e.g., default)
3. Go to the Claims tab
4. Click Add Claim

Configure the groups claim:

5. Click Create

---

​

Step 6: Assign Users to the Application

1. Navigate to your application’s Assignments tab

2. Click Assign → Assign to People or Assign to Groups

​

For Assigning Roles (If step 3 and step 4 are followed)

For each user, set their bifrostRole (if you are planning to do role-level mapping):

4. Click Save and Go Back

---

​

Step 7: Create API token for bulk user and team sync

To create an API token, navigate to Security → API → Tokens.

1. Click on “Create token”

2. Copy token to be used in the next step.

​

Step 8: Configure Bifrost

Now configure Bifrost to use Okta as the identity provider.

​

Using the Bifrost UI

1. Navigate to Governance → User Provisioning in your Bifrost dashboard
2. Select Okta as the SCIM Provider
3. Enter the following configuration:

4. Verify configuration and see if you get any errors. Make sure you get no errors/warnings.
5. Toggle Enabled to activate the provider
6. Click Save Configuration

​

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

​

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.

​

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).

5. Click Save Configuration

​

Configuration Reference

---

​

Testing the Integration

1. Open your Bifrost dashboard in a new browser or incognito window
2. You should be redirected to Okta 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 Okta

• Verify the SCIM provider is enabled in Bifrost
• Check that the Bifrost server was restarted after configuration
• Ensure the Issuer URL is correct and accessible

​

Attribute mapping is not working

• Verify that token configuration includes all the attributes used for mapping.

​

Token refresh failing

• Ensure the Refresh Token grant type is enabled for your application
• Verify the offline_access scope is included in your authorization requests

---

​

Next Steps

• User Provisioning (SCIM) - Overview of SCIM in Bifrost and alternative identity providers
• Advanced Governance - Learn about user budgets and compliance features
• Role-Based Access Control - Understand the Admin, Developer, Viewer hierarchy
• Audit Logs - Monitor user authentication and activity