> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getbifrost.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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**
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](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](/enterprise/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):
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:
| 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) |
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 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**
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/` 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 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