---
title: "Setting up Okta"
description: "Step-by-step guide to configure Okta as your identity provider for Bifrost Enterprise SSO authentication."
icon: "o"
---

## 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](/enterprise/rbac) 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**

<Frame>
  <img src="/media/user-provisioning/okta-create-app.png" alt="Okta Applications page" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-app-configuration.png" alt="Create new app integration dialog" />
</Frame>

5. Click **Next** to continue

---

## Step 2: Configure Application Settings

Configure the following settings for your application:

<Frame>
  <img src="/media/user-provisioning/okta-app-integration-main-page.png" alt="New Web App Integration settings" />
</Frame>

**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](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)

<Note>
  You can map any attribute (include custom roles/groups) to assign roles to users. You can learn more about
  [RBAC](/enterprise/rbac) docs.
</Note>

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

1. Navigate to **Directory** → **Profile Editor**

<Frame>
  <img src="/media/user-provisioning/okta-profile-editor-screen.png" alt="Okta Profile Editor" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-custom-attribute-creation.png" alt="Add custom attribute for bifrostRole" />
</Frame>

| 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**

<Frame>
  <img src="/media/user-provisioning/okta-claim-addition.png" alt="Add role claim" />
</Frame>

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**

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

---

## 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**

<Frame>
  <img src="/media/user-provisioning/okta-groups-page.png" alt="Okta Groups page" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-create-groups.png" alt="Groups created in Okta" />
</Frame>

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

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

| 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

<Frame>
  <img src="/media/user-provisioning/okta-assign-users.png" alt="Application Assignments tab" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-assign-custom-role.png" alt="Assign custom role to user" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-tokens-screen.png" alt="Okta API tokens screen" />
</Frame>

1. Click on "Create token"

<Frame>
  <img src="/media/user-provisioning/okta-create-token-form.png" alt="Create token dialog in Okta" />
</Frame>

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

<Frame>
  <img src="/media/user-provisioning/okta-form.png" alt="Create token dialog in Okta" />
</Frame>

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

| Field             | Value                                                                |
| ----------------- | -------------------------------------------------------------------- |
| **Client ID**     | Your Okta application Client ID                                      |
| **Issuer URL**    | Issuer URL                                                           |
| **Audience**      | Your API audience (e.g., `api://default` or custom)                  |
| **Client Secret** | Your Okta application Client Secret (optional, for token revocation) |

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**

<Warning>
After saving, you'll need to restart your Bifrost server for the changes to take effect.
</Warning>

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

5. 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                                                                         |
| ------------------------------- | -------- | ----------------------------------------------------------------------------------- |
| `issuerUrl`                     | Yes      | Okta authorization server URL (e.g., `https://your-domain.okta.com/oauth2/default`) |
| `clientId`                      | Yes      | Application Client ID from Okta                                                     |
| `clientSecret`                  | Yes       | Application Client Secret (enables token revocation)                                |
| `audience`                      | Yes      | API audience identifier from your 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 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)](./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