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

# SSO using OIDC

> Configure Okta as your identity provider for Bifrost Enterprise using OpenID Connect.

## Prerequisites

* An Okta account with admin access to create applications
* Bifrost Enterprise deployed and accessible
* Your Bifrost callback URL: `https://<your-bifrost-domain>/login` (under a `server.base_path` prefix: `https://<your-bifrost-domain>/<prefix>/login`; the SSO wizard shows the exact value)

***

## Step 1: Create an OIDC App

**1. Open the Okta admin console**

Sign in to `https://<your-tenant>-admin.okta.com`.

In the left navigation, go to **Applications** → **Applications** and click **Create App Integration**.

![Okta admin console left nav with Applications → Applications highlighted](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-applications.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=9fbf9c04fb656b8b4947954bc3af29b5)

Open Applications from the left nav of the Okta admin console.

**2. Select the app type**

In the dialog that appears, set:

* **Sign-in method**: OIDC – OpenID Connect
* **Application type**: Web Application

Click **Next**.

![Create App Integration dialog with OIDC – OpenID Connect and Web Application selected](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-create-app.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=2f9fef7b57e8f40d2b882e7c080be667)

Select OIDC – Web Application.

**3. Fill in the app settings**

Give the app a name - e.g. `Bifrost Enterprise`.

Under **Grant type**, enable **Authorization Code** only.

In **Sign-in redirect URIs**, add:

```
https://<your-bifrost-domain>/login
```

Under a `server.base_path` prefix, insert it before the path: `https://<your-bifrost-domain>/<prefix>/login`.

Optionally, to use claim discovery during setup, also add:

```
https://<your-bifrost-domain>/workspace/scim/oauth-discover-callback
```

Under a `server.base_path` prefix, insert it before the path: `https://<your-bifrost-domain>/<prefix>/workspace/scim/oauth-discover-callback`.

![New Web App Integration form showing app name, grant type, redirect URIs, and assignment settings](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-app-settings.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=20cc5868a85ee0cc8ed4ea45f910f9d6)

New Web App Integration settings.

Under **Assignments**, select **Skip group assignment for now**.

Click **Save**.

***

## Step 2: Configure Claim Attributes

**1. Open the Sign On tab**

In your Bifrost Enterprise app, go to the **Sign On** tab.

![Sign On tab in the Okta app settings](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-app-settings-signon.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=3381918cc00c28961504e07d6fbbabcc)

Sign On tab in the Okta app settings.

Scroll down to find the token claims section. This is where you control what attributes Okta includes in the JWT token sent to Bifrost.

![Token claims table showing claim names, value expressions, and group filter configuration](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-token-claims.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=25dd1b1283b2c2c2f93505a0df6ab2cf)

Token claims - each row is a claim Okta will include in the JWT. \<br/> The Value column uses an Okta expression to pull from the user profile in the above example (e.g. user.division)

Any attribute you add here is available in Bifrost for role, team, or business unit mappings.

You can use an [Okta expression](https://help.okta.com/oie/en-us/content/topics/apps/federated-claims-overview.html) to derive or transform values:

```
user.department
user.profileUrl != null ? user.profileUrl : "default"
```

**2. Add a groups claim**

To sync group membership, add a groups claim under the OpenID Connect ID Token section. Set:

* **Claim name**: `groups`
* **Value type**: Groups
* **Filter**: Matches regex `.*` (or a tighter prefix like `bifrost-.*`)

Click **Save**.

> [!NOTE]
>
> This path works for the **Org Authorization Server** and adds the claim to ID tokens only. If you are using a **Custom Authorization Server**, expand the section below instead.

> [accordion] Using a Custom Authorization Server
>
> Use this path when Bifrost is configured with a **Custom Authorization Server**. This adds the groups claim through your authorization server and supports both ID and access tokens.
>
> 1. Navigate to **Security** → **API** → **Authorization Servers**
> 2. Select your authorization server (e.g. `default`)
>
> ![Authorization Servers list under Security → API in the Okta admin console](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-api-custom-oauth.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=60310846715333efebf28b90cecc7917)
>
> Authorization Servers list in the Okta Security API settings.
>
> 3. Go to the **Claims** tab and click **Add Claim**
> 4. Configure the claim:
>
> | Field | Value |
> | - | - |
> | **Name** | `groups` |
> | **Include in token type** | ID Token, Always |
> | **Value type** | Groups |
> | **Filter** | Matches regex `.*` (or a prefix like `bifrost-.*`) |
> | **Include in** | Any scope |
>
> ![Add Claim dialog configured for the groups claim on a Custom Authorization Server](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-api-custom-claim-oauth.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=ff4a6c572d1de6023d137656ebc701c5)
>
> Add Claim dialog configured for the groups claim on a Custom Authorization Server.
>
> 5. Click **Create**

***

## Step 3: Assign Users in Okta

**1. Open the Assignments tab**

In your Bifrost Enterprise app, go to the **Assignments** tab.

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

![Assignments tab in the Bifrost Enterprise Okta app with Assign button highlighted](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-assignments.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=8ff4617ff18c1230bda898c556c235cd)

Assigning users or groups to the Bifrost Enterprise application.

**2. Select users or groups**

Select the users or groups that should have access to Bifrost and click **Done**.

![Selecting users or groups to assign to the Bifrost Enterprise application](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-group-assignment.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=de4ec8b230e8f7ce6505437522649483)

Selecting users or groups to assign to the Bifrost Enterprise application.

> [!NOTE]
>
> Only users explicitly assigned to the application can authenticate via Okta.

***

## Step 4: Copy Your Credentials

**1. Copy the Client ID and Secret**

Open the **General** tab of your Bifrost Enterprise app.

Copy the following - you will need them in Step 5:

* **Client ID**
* **Client Secret** (click to reveal)

![General tab of the Okta app showing Client ID and Client Secret fields](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-credentials.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=9331c2ecb47d8f94d39087f85432c3d2)

Client ID and Client Secret on the General tab.

**2. Note your Issuer URL**

Your issuer URL depends on which authorization server you use:

| Authorization Server | Issuer URL |
| - | - |
| **Org** (default) | `https://<your-tenant>.okta.com` |
| **Custom** | `https://<your-tenant>.okta.com/oauth2/<server-id>` |

**3. Create an API token (optional)**

If you want Bifrost to automatically sync users and groups from Okta every **Directory sync interval** (default 24 hours), you need to create an API token.

Go to **Security** → **API** → **Tokens** and click **Create token**. Give it a name, then copy the token value - it will only be shown once.

![Security → API → Tokens page in Okta with Create Token button](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/okta-oidc-api-token.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=712d63934e7a721972d6d53409f4e059)

Create an API token under Security → API → Tokens.

> [!NOTE]
>
> This background sync runs every **Directory sync interval** (default 24 hours) and reconciles users, roles, and group memberships. It is turned off while SCIM Provisioning is enabled, so you can skip this if you plan to rely on SCIM push.

***

## Step 5: Configure Bifrost

**1. Open User Provisioning and choose Okta**

In your Bifrost dashboard, go to **Governance** → **User Provisioning**.

Select **Okta** as the identity provider and click **Next**.

![Bifrost Choose Provider screen with Okta selected](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/bifrost-provider-selection.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=9c3c094dfad424fb235c0b2dd0723514)

Select Okta from the list of identity providers.

**2. Fill in the provider configuration**

Enter the credentials you copied in Step 4:

* **Issuer URL**: your Okta issuer URL
* **Authorization Server**: Org or Custom - match your Okta setup
* **Client ID**: from the Okta app General tab
* **Client Secret**: from the Okta app General tab
* **Audience**: required only for Custom Authorization Server
* **API Token**: optional - paste the token from Step 4 if you want background sync every **Directory sync interval** (default 24 hours)
* **Sync all users**: with an API token, choose which Okta users that sync keeps. On (the default) keeps every user assigned to the app except **suspended** and **deactivated** ones; off keeps **active** users only. In `config.json` or Helm this is `syncAllUsers` under the SCIM provider `config`.

Click **Verify & Next** to confirm the connection.

![Bifrost Provider Configuration form with Issuer URL, Authorization Server, Client ID, Client Secret, and API Token fields](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/bifrost-okta-provider-config.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=1dd97a10969b169d493a2fa610b8a7ca)

Provider Configuration - enter your Okta credentials and verify the connection.

**3. Discover claims**

On the Attribute Mapping screen, click **Discover Claims**.

Bifrost opens a sign-in popup - no session is created.

Once you authenticate, it returns the exact claims your Okta tenant is sending in the JWT.

Use this to confirm that the attributes you set up in [Step 2](#step-2-configure-claim-attributes) - such as `groups`, `department`, or `division` - are present before building your mappings.

![Bifrost Discover Claims screen listing all claims returned by Okta including groups, email, and custom attributes](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/bifrost-discover-claims.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=323fd6916d491fa74ce04830a1dc48d9)

Discover Claims shows the exact claims Okta is returning for your user, including groups and any custom profile attributes.

**4. Set up attribute mappings**

Use the sections below the claim list to map Okta claim values to Bifrost roles, teams, and business units.

**Attribute-to-Role Mappings**

Map a claim value to a Bifrost role. All matching rules are evaluated. If several rules match, Bifrost picks one using your chosen resolution strategy:

* **The role with the most permissions** (default)
* **The first matching role, by list order** (drag rows to set priority)

If no rule matches, no role is assigned and login is denied.

**Attribute-to-Team Mappings**

Map a claim value to a Bifrost team. All matching rules apply.

* Use a specific value (e.g. `engineering`) to map that exact claim value to a named Bifrost team
* Use `*` as the value to sync the claim value directly as the team name
* Use `${*}` to extract part of the string - e.g. `Bifrost Playground: ${*} Team` matches `Bifrost Playground: Alpha Team` and creates team **Alpha**

**Attribute-to-Business Unit Mappings**

Same wildcard support as team mappings.

* Use a specific value (e.g. `platform`) to map that exact claim value to a named Bifrost business unit
* Use `${*}` to extract a substring as the business unit name - e.g. `Bifrost Playground: ${*} BU` matches `Bifrost Playground: Alpha BU` and creates business unit **Alpha**
* When a rule matches, the resolved business unit is assigned to the user. All matching rules apply, so a user can belong to several business units at once
* A business unit you assign by hand stays until you remove it, unless a mapping later grants the same one, in which case it follows your IdP. One granted from a claim is removed at a later sign-in where the attribute is present and no longer matches; a refreshed token that leaves the attribute out entirely doesn't remove it

![Bifrost Attribute Mapping screen showing role, team, and business unit mapping rules](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/bifrost-attribute-setup.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=8d6420fb675f0e98e0b9ba78438a3638)

Attribute Mapping - configure role, team, and business unit rules based on the claims Okta sends.

Click **Next** when done.

**5. Review and enable**

Review your configuration on the final screen, then click **Enable**.

![Bifrost Review and Enable screen summarising the Okta OIDC configuration before activation](https://mintcdn.com/bifrost/xzA5tsApkV1N-gkH/media/user-provisioning/okta/bifrost-review-oidc.png?fit=max\&auto=format\&n=xzA5tsApkV1N-gkH\&q=85\&s=da60033414053b9ae258432bc415ac7f)

Review your Okta SSO configuration before enabling.

> [!WARNING]
>
> Restart your Bifrost server after enabling for the changes to take effect.

***

## Optional Next Steps

**Sync users and groups automatically** - SSO alone provisions users on first login. To keep Bifrost in sync with Okta in real time (deactivations, group changes, new users before they log in), set up [SCIM with Okta](https://docs.getbifrost.ai/enterprise/setting-up-okta/scim.md).

***

## Troubleshooting

**User is not redirected to Okta** - verify the provider is enabled in Bifrost and the server was restarted after saving. Check that the Issuer URL has no trailing slash and is reachable from your server.

**Login fails with an invalid client error** - the Client ID or Client Secret is incorrect. Regenerate the secret in the Okta app General tab and update Bifrost.

**Roles or teams are not assigned after login** - confirm the claim (e.g. `groups`) is included in the token. Verify the attribute mapping values in Bifrost match exactly what Okta sends.

**Empty email after login** - the `email` scope is not included. Ensure `openid` and `email` are requested, and that the Okta user has a primary email set.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.