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)

---

​

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: Configure Authorization Server (optional)

Bifrost uses Okta’s Authorization Server to issue tokens. You have three options:

1. Use /oauth2/default with role claims (recommended) — Complete Steps 4-7 to configure custom role claims on the default authorization server. This enables automatic RBAC synchronization.
2. Use /oauth2/default without role claims — Skip Steps 4-7. The first user to sign in automatically receives the Admin role and can manage RBAC for all subsequent users through the Bifrost dashboard.
3. Skip Step 3 entirely — Authorization is not configured through Okta. You’ll need an alternative authentication mechanism.

​

Configuring the Authorization Server

1. Navigate to Security → API
2. Click on Authorization Servers

3. Note the Issuer URI for your authorization server (e.g., https://your-domain.okta.com/oauth2/default)

---

​

Step 4: Create Custom Role Attribute

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 5: Add Role Claim to Tokens

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 6: Configure Groups for Team and Role Synchronization

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

You have two options for configuring the groups claim. Choose the one that best fits your Okta plan and requirements.

​

Option A: Using App-Level Groups Claim (All Okta Plans)

This approach configures the groups claim directly in your application’s settings and works with all Okta plans, including free tiers.

1. Navigate to your application’s Sign On tab
2. Scroll down to the OpenID Connect ID Token section
3. Click Edit to modify the settings
4. Configure the Groups claim filter:
   • Groups claim type: Filter
   • Groups claim filter: Set a claim name (e.g., groups) and filter condition (e.g., “Starts with” bifrost-staging)

5. Click Save

​

Option B: Using Authorization Server Groups Claim

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

You can also configure an additional groups claim in the application’s Sign On settings:

1. Navigate to your application’s Sign On tab

2. Under OpenID Connect ID Token, configure:
   • Groups claim type: Expression
   • Groups claim expression: Arrays.flatten(Groups.startsWith("OKTA", "bifrost", 100))

---

​

Step 7: Assign Users to the Application

1. Navigate to your application’s Assignments tab

2. Click Assign → Assign to People or Assign to Groups
3. For each user, set their bifrostRole:

4. Click Save and Go Back

---

​

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. Toggle Enabled to activate the provider
5. Click Save Configuration

​

Group-to-Role Mappings (Optional)

If you configured groups in Okta (Step 6), you can map Okta group names directly to Bifrost roles. This is an alternative to using custom role claims (Steps 4-5) and works with all Okta plans.

1. In the User Provisioning configuration, scroll down to Group-to-Role Mappings
2. Click Add Mapping
3. Enter the Group Claim Name exactly as it appears in your Okta groups (e.g., bifrost-staging-admins)
4. Select the corresponding Role (Admin, Developer, or Viewer)
5. Repeat for each group you want to map

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

​

”Invalid audience” error

• Verify the audience field matches your Okta authorization server’s audience
• Check if you’re using a custom authorization server and update the issuer URL accordingly

​

Roles not syncing

• Ensure the role claim is configured in your authorization server
• Verify users have the bifrostRole attribute set
• Check that the claim is included in the access token (use Okta’s Token Preview feature)

​

Groups not appearing as teams

• Verify the groups claim is configured in your authorization server
• Ensure users are assigned to the relevant groups
• Check that groups are assigned to the application

​

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

• 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