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

---

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.

   

   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.

   

   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
   

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

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

   

   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.

   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 — each row is a claim Okta will include in the JWT.
   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 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.

   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.

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

   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.

   

   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.

   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)

   

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

   

   Create an API token under Security → API → Tokens.

   This background sync runs every 24 hours and reconciles users, roles, and group memberships — catching anything that may have been missed if you also have SCIM set up. You can skip this if you plan to rely on SCIM push alone, but the two work well together.

---

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.

   

   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 24-hour background sync

   Click Verify & Next to confirm the connection.

   

   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 — such as groups, department, or division — are present before building your mappings.

   

   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 multiple rules match, the role with the highest permissions is assigned
   • If no rule matches, the user is not assigned a role 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 all of that user’s teams
   • Manually assigned teams are left unchanged

   

   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.

   

   Review your Okta SSO configuration before enabling.

   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.

---

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.