SSO: OIDC with Okta

Prerequisites

Before you begin, ensure you have admin access to your Okta dashboard.

Step 1: Set Up an Okta Application for Control D

Note: If you intend to use specific controld-* groups (e.g., controld-admin, controld-owner, controld-viewer) for role-based access, create these groups first as outlined in Step 3.

1. Log in to your Okta Admin Dashboard.

2. Navigate to Applications and click Create App Integration.

3. Select OIDC - OpenID Connect as the sign-in method and choose Web Application as the application type. Click Next.

4. Fill in the application details:

   Field	Data
   App Integration Name	Control D
   Logo (Optional)
   Sign-in redirect URIs	https://controld.com/sso/callback?provider=okta
   Sign-out redirect URIs	Delete all entries

   📘

   For IDP Initiated Login support

   This allows for one-click login from the Okta user homepage

   Field	Data
   Login initiated by	Either Okta or App
   Application visibility	Display application icon to users
   Login flow	Redirect to app to initiate login (OIDC Compliant)
   Initiate login URI	https://api.controld.com/okta/auth_init

   

5. Under Assignments, you can assign people or groups to the application, or select Skip group assignment for now if you wish to assign them later.
   If you plan to use role-based groups, assign the controld-* groups (controld-admin, controld-owner, controld-viewer) created earlier.

6. Ensure the Grant Type is set to Authorization Code.
7. Leave the Okta API Scopes tab unconfigured. Control D does not call the Okta Management APIs. It requests the standard OIDC scopes openid, profile, email, and groups during sign-in instead.
8. Click Save to create the application.

Step 2: Configure the Okta Application for Control D

1. Open the newly created Control D application in Okta.

2. Go to the General Settings tab and note down the Client ID and Client Secret.

3. Go to the Sign On tab and ensure the OpenID Connect ID Token option is enabled.

4. Under Groups Claim, leave the claim name as groups, set Groups claim type to Filter, choose Starts With, and enter controld. This includes the default controld-admin, controld-owner, and controld-viewer groups.

5. Save the claim.

Step 3: Assign User Groups in Okta

By default, create one Control D group for each role. If you want to map your organization's existing groups instead, skip this section and follow Optional: Map Existing Okta Groups to Control D Roles.

1. Go to Directory > Groups in Okta.

2. Create three groups for Control D access (if not already created). The default names are:

   • controld-admin
   • controld-owner
   • controld-viewer

3. Assign users to these groups based on their roles and responsibilities within Control D.

Optional: Map Existing Okta Groups to Control D Roles

Use this option instead of creating the default controld-* groups. Control D can map three existing Okta-native or directory-imported groups to its Owner, Admin, and Viewer roles.

1. On the Control D application's Sign On tab, configure one active ID-token claim named exactly groups. Set Groups claim type to Expression and use the .![name] projection shown below.

2. Choose which memberships Okta sends:

   • All Okta-native and directory-imported groups:

     Text

     user.getGroups({'group.type': {'OKTA_GROUP', 'APP_GROUP'}}).![name]

     

   • Only the three groups mapped to Control D roles (recommended): Replace these examples with the exact names of your existing groups:

     Text

     user.getGroups(
       {'group.type': {'OKTA_GROUP', 'APP_GROUP'}},
       {
         'group.profile.name': {
           'Example.ControlD.Owner',
           'Example.ControlD.Admin',
           'Example.ControlD.Viewer'
         },
         'operator': 'EXACT'
       }
     ).![name]

     

3. Assign the existing groups to the Control D application so that their members can launch it. Application assignment controls access to the application; it does not add a group to the ID-token claim or override the expression.

   

4. In Step 4, enter the three exact group names in the Owner Group, Admin Group, and Viewer Group fields. Matching is case-sensitive. If a user belongs to multiple mapped groups, Control D applies the highest role in this order: Owner, Admin, then Viewer.

   

See Okta Expression Language group functions for additional filtering options. Okta's Token Preview under Security > API > Authorization Servers is for custom authorization servers and does not reproduce Control D's org authorization server flow.

Step 4: Add SSO Configuration in Control D

1. Log in to the Control D.

2. Navigate to My Organization, scroll to SSO Provider, and click the toggle to enable.

3. Fill in the required fields:

   • Okta Domain: <your-subdomain>.okta.com
   • Client ID: The value you copied from the Okta application.
   • Client Secret: The value you copied from the Okta application.
   • Email Domains: Enter the domains associated with your organization, e.g., example.com. This is necessary to map email domains to your Control D customer account so that login attempts are redirected to the correct Okta authentication server.
   • Owner Group, Admin Group, and Viewer Group: To use custom group mappings, enter the corresponding Okta group name in all three fields. When adding SSO without a custom mapping, leave all three fields blank to use the default Control D group names.

4. Click Save to enable Okta SSO for your organization.

Step 5: Test SSO Login

1. Log out of Control D and navigate to the login page.
2. Enter your Okta email address, leaving the password blank.
3. Click the Log in with Okta button.
4. Enter your Okta credentials and confirm successful login.
5. Verify role-based access permissions by testing users in each of the three configured groups.

Troubleshooting

If you encounter any issues:

1. Verify the redirect URIs in your Okta application settings.
2. Confirm that the app has one active ID-token claim named exactly groups and that its expression includes the mapped groups.
3. Ensure the user is assigned to the expected groups and to the Control D application in Okta.
4. Check the SSO configuration in the Control D Admin Panel for typos or missing fields. Group names are case-sensitive.
5. Refer to the Okta logs for debugging SSO errors. Do not share raw ID tokens.

For additional support, contact Control D Support.