Setting up Okta

Overview

This guide walks you through configuring Okta as your identity provider for DeepIntShield Enterprise. After completing this setup, your users will be able to sign in to DeepIntShield using their Okta credentials, with roles and team memberships automatically synchronized.

Prerequisites

• An Okta organization with admin access
• DeepIntShield Enterprise deployed and accessible
• The redirect URI for your DeepIntShield instance (e.g., https://your-deepintshield-domain.com/login)

---

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: DeepIntShield Enterprise
• Logo (optional): You can upload the DeepIntShield logo from https://www.getmaxim.ai/deepintshield/deepintshield-logo-only.png

Grant type:

• Enable Authorization Code
• Enable Refresh Token

Sign-in redirect URIs:

• Add your DeepIntShield login callback URL: https://your-deepintshield-domain.com/login

Sign-out redirect URIs (Optional):

• Add your DeepIntShield base URL: https://your-deepintshield-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: Configure Authorization Server (optional)

Note

The default authorization server (/oauth2/default) is available to all Okta plans and supports custom claims, including role claims. The API Access Management paid add-on is only required to create additional custom authorization servers beyond the default.

DeepIntShield uses Okta’s Authorization Server to issue tokens. You have three options:

1. Use /oauth2/default with role claims (recommended) — Complete Steps 4-7 to configure custom role claims on the default authorization server. This enables automatic RBAC synchronization.

2. Use /oauth2/default without role claims — Skip Steps 4-7. The first user to sign in automatically receives the Admin role and can manage RBAC for all subsequent users through the DeepIntShield dashboard.

3. Skip Step 3 entirely — Authorization is not configured through Okta. You’ll need an alternative authentication mechanism.

Configuring the Authorization Server

1. Navigate to Security → API
2. Click on Authorization Servers

3. Note the Issuer URI for your authorization server (e.g., https://your-domain.okta.com/oauth2/default)

Note

The Issuer URI is used as the issuerUrl in your DeepIntShield configuration. Make sure to use the full URL including /oauth2/default (or your custom authorization server path).

---

Step 4: Create Custom Role Attribute

To map Okta users to DeepIntShield 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., DeepIntShield 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 5: Add Role Claim to Tokens

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

Note

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

---

Step 6: Configure Groups for Team and Role Synchronization

DeepIntShield can automatically sync Okta groups for two purposes:

• Team synchronization — Groups are synced as DeepIntShield teams
• Role mapping — Groups can be mapped to DeepIntShield roles (Admin, Developer, Viewer) using Group-to-Role Mappings in the DeepIntShield 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., deepintshield-staging-admins, deepintshield-staging-viewers)

Note

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

You have two options for configuring the groups claim. Choose the one that best fits your Okta plan and requirements.

Option A: Using App-Level Groups Claim (All Okta Plans)

This approach configures the groups claim directly in your application’s settings and works with all Okta plans, including free tiers.

1. Navigate to your application’s Sign On tab
2. Scroll down to the OpenID Connect ID Token section
3. Click Edit to modify the settings
4. Configure the Groups claim filter:
   • Groups claim type: Filter
   • Groups claim filter: Set a claim name (e.g., groups) and filter condition (e.g., “Starts with” deepintshield-staging)

5. Click Save

Note

The filter ensures only relevant groups are included in the token. Adjust the filter condition based on your group naming convention.

Option B: Using Authorization Server Groups Claim

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 deepintshield-.*)
Include in	Any scope

5. Click Create

You can also configure an additional groups claim in the application’s Sign On settings:

1. Navigate to your application’s Sign On tab

2. Under OpenID Connect ID Token, configure:
   • Groups claim type: Expression
   • Groups claim expression: Arrays.flatten(Groups.startsWith("OKTA", "deepintshield", 100))

Note

Adjust the group filter expression based on your naming convention. The example above includes groups starting with “deepintshield”.

---

Step 7: Assign Users to the Application

1. Navigate to your application’s Assignments tab

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

3. For each user, set their bifrostRole:

4. Click Save and Go Back

Note

Role claims are available only when you configure custom claims on your authorization server. Ensure you add role claims to your chosen authorization server (for example, /oauth2/default) to enable RBAC. If you skipped Steps 4-7, the first user to sign in automatically receives the Admin role and can manage RBAC for all subsequent users through the DeepIntShield dashboard.

---

Step 8: Configure DeepIntShield

Now configure DeepIntShield to use Okta as the identity provider.

Using the DeepIntShield UI

1. Navigate to Governance → User Provisioning in your DeepIntShield 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. Toggle Enabled to activate the provider
5. Click Save Configuration

Group-to-Role Mappings (Optional)

If you configured groups in Okta (Step 6), you can map Okta group names directly to DeepIntShield roles. This is an alternative to using custom role claims (Steps 4-5) and works with all Okta plans.

1. In the User Provisioning configuration, scroll down to Group-to-Role Mappings
2. Click Add Mapping
3. Enter the Group Claim Name exactly as it appears in your Okta groups (e.g., deepintshield-staging-admins)
4. Select the corresponding Role (Admin, Developer, or Viewer)
5. Repeat for each group you want to map

Group Claim Name	Role
deepintshield-staging-admins	Admin
deepintshield-staging-viewers	Viewer

Note

If a user belongs to multiple groups with different role mappings, the highest privilege role is assigned. If no mapping matches, the first user to sign in receives the Admin role, and subsequent users receive the Viewer role.

6. Click Save Configuration

Caution

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

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	No	Application Client Secret (enables token revocation)
audience	Yes	API audience identifier from your authorization server
userIdField	No	JWT claim for user ID (default: uid)
rolesField	No	JWT claim for roles (default: roles)
teamIdsField	No	JWT claim for group/team IDs (default: groups)

---

Testing the Integration

1. Open your DeepIntShield 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 DeepIntShield
5. Verify the user appears in the DeepIntShield users list with the correct role

---

Troubleshooting

User not redirected to Okta

• Verify the SCIM provider is enabled in DeepIntShield
• Check that the DeepIntShield server was restarted after configuration
• Ensure the Issuer URL is correct and accessible

”Invalid audience” error

• Verify the audience field matches your Okta authorization server’s audience
• Check if you’re using a custom authorization server and update the issuer URL accordingly

Roles not syncing

• Ensure the role claim is configured in your authorization server
• Verify users have the bifrostRole attribute set
• Check that the claim is included in the access token (use Okta’s Token Preview feature)

Groups not appearing as teams

• Verify the groups claim is configured in your authorization server
• Ensure users are assigned to the relevant groups
• Check that groups are assigned to the application

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

• 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