Setting up Okta

Step-by-step guide to configure Okta as your identity provider for Bifrost Enterprise SSO authentication.

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 synchronized from Okta.

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)

You can map any attribute (include custom roles/groups) to assign roles to users. You can learn more about RBAC docs.

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:

Field	Value
Data type	string
Display name	bifrostRole
Variable name	bifrostRole
Enum	Check “Define enumerated list of values”
Attribute members	Admin → admin, Developer → developer, Viewer → viewer
Attribute type	Personal

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:

Field	Value
Name	role
Include in token type	Access Token, Always
Value type	Expression
Value	user.bifrostRole
Include in	Any scope

5. Click Create

If you named your custom attribute differently, update the Value expression accordingly (e.g., user.yourAttributeName).

---

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)

Use a consistent naming convention for your groups. This makes it easier to configure group filters and role mappings later.

Add Groups Claim to Tokens

Okta exposes group claims in different places depending on which authorization server you use in Bifrost.

Org Authorization Server: App-Level Group Claims

Use this path when Bifrost is configured with Org Authorization Server. This works on every Okta tenant and uses Okta’s legacy app-level Group Claims configuration.

1. Navigate to Applications → Applications
2. Open your Bifrost Enterprise application
3. Go to the Sign On tab
4. In the OpenID Connect ID Token section, configure Group Claims
5. Set the claim name to groups
6. Set the filter to match the groups Bifrost should receive, for example .* or bifrost-.*
7. Save the application settings

For the Org Authorization Server, assign the relevant Okta groups to the Bifrost application. Custom Authorization Servers do not emit app-level Sign On Group Claims.

Custom Authorization Server: Authorization Server Claim

Use this path when Bifrost is configured with Custom Authorization Server. 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:

Field	Value
Name	groups
Include in token type	ID Token, Always
Value type	Groups
Filter	Matches regex: .* (or specify a prefix like bifrost-.*)
Include in	Any scope

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

3. 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: Understand Okta user sync

Bifrost does not currently support Okta SCIM management APIs or inbound Okta SCIM provisioning. Do not create or configure an Okta SCIM app for Bifrost yet.

For Okta, Bifrost uses the API token from Step 7 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 Okta.

Every 15 minutes, Bifrost also refreshes active OIDC sessions. If a session cannot be refreshed, Bifrost checks with Okta whether the user is still active; if Okta reports the user is inactive, Bifrost decommissions that user locally.

Support for Okta SCIM management APIs is coming soon.

---

Step 9: 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 OIDC Provider
3. Enter the following configuration:

Field	Value
Client ID	Your Okta application Client ID
Issuer URL	Your Okta issuer URL
Authorization Server	Select Org Authorization Server or Custom Authorization Server
Audience	Your API audience (required only for Custom Authorization Server)
Client Secret	Your Okta application Client Secret (optional, for token revocation)
API Token	Okta API token used for bulk import and 24-hour background sync

Choose the authorization server type based on your Okta setup:

Option	When to use	Issuer URL format
Org Authorization Server (free, every tenant)	Recommended default. Use this if you do not need Okta claim expressions or a custom audience. Supports group-based mappings through app-level Group Claims.	https://your-domain.okta.com
Custom Authorization Server (requires API Access Management)	Use this only if your Okta plan includes API Access Management and you need claim expressions, custom claims, or a custom audience.	https://your-domain.okta.com/oauth2/default

If you are unsure, select Org Authorization Server. For Org Authorization Server, leave Audience empty because Bifrost validates the ID token audience against the Okta app Client ID. For Custom Authorization Server, set Audience to the API audience configured on that authorization server.

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

After saving, you’ll need to restart your Bifrost server for the changes to take effect.

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

When you mark value as ”*” - the claim value is mapped as is to the entity name. Values comparisons are case-insensitive.

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 a user matches multiple role mapping rules, the highest privilege role is assigned. If no mapping matches, the user is not allowed to log in.
• 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).

After saving, you’ll need to restart your Bifrost server for the changes to take effect.

Configuration Reference

Field	Required	Description
issuerUrl	Yes	Okta issuer URL. Use a bare org URL for Org Authorization Server or /oauth2/<id> for Custom Authorization Server.
authServerType	Yes	org for Org Authorization Server or custom for Custom Authorization Server. Defaults to org for new configs.
clientId	Yes	Application Client ID from Okta
clientSecret	Yes	Application Client Secret (enables token revocation)
audience	Custom only	API audience identifier from your Custom Authorization Server. Leave empty for Org Authorization Server.
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).

---

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 OIDC 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 (OIDC) - Overview of OIDC user provisioning 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