Configuring Okta SCIM for Cortex

This article explains how to configure Okta SCIM to work with Cortex. If you're looking to turn on SSO in Cortex via Okta, refer to this article.

When Okta SCIM is configured, you can create, import, edit, and deactivate users.

Prior to configuring Okta SCIM, you must first turn on SCIM in Cortex. Refer to Configuring SCIM in Cortex for more information.

Limitations

Note the following limitations when using Okta SCIM:

• A user's email cannot be changed

• Only given and family names can be updated

• Users can only be reactivated via a PUT operation

Prerequisites

1. Create an API key in Cortex that has the Admin role or a custom role that contains the Configure Open ID Connector & SCIM, Edit Roles, and Manage Identity Mappings permissions. See API Keys, Secrets, and Tokens for more information.

   Note: Be sure to copy the API key and save it for later. Do not skip this step—you can only view the key once!

2. In Okta, navigate to Applications > Sign on > Credential details and set the Application username format to Email. SCIM requires this format.

3. If your organization requires you to allowlist domains, ensure that Okta's IP addresses can access your Cortex instance:

   1. In Cortex, click your avatar in the bottom-left corner, then click Settings.

   2. From the Settings menu, locate the Security and access section, then click IP allowlist. If there are no IP addresses listed here, access is allowed from any IP address.

   3. Click Add IP addresses in the upper-right corner.

   4. Enter an individual IP address or an IP range in CIDR notation, then click Add addresses.

Step 1: Adding the Cortex OIN app

Add the Cortex OIN app for Okta from Okta's Cortex integration docs. This is also available in your Okta instance under Applications > App integration catalog.

Step 2: Configuring the API integration

1. In your Okta admin dashboard, navigate to Applications then click the Cortex app.

2. Click the Provisioning tab.

3. Under the Settings panel, click Integration. Do the following:

   • Select the Enable API integration checkbox.

   • API token - Enter your Cortex-generated API key.

4. Click Test API Credentials to verify that your configuration works.

5. Click Save.

Step 3: Turning on provisioning in Okta

Provisioning settings can be turned on once the integration is configured.

1. Enable the following settings in Okta:

   • Create users - This creates a user in Cortex when the app is assigned to a user in Okta.

     • The default username used to create accounts is set to the Okta username.

   • Update user attributes - This setting allows Okta to update a user's attributes in Cortex when the app is assigned.

     • Cortex only supports updating the user's name (i.e. birth and family names).

   • Deactivate users - This deactivates or deletes a user's Cortex account when the app is unassigned to that user or when their Okta account is deactivated.

     • Accounts can be reactivated if the app is reassigned to the user in Okta.

     • By default, deprovisioned users will not remain visible in team membership. Contact Cortex Support to change this behavior.

     • When a deprovisioned user is reprovisioned and logs back in with the same email, any ownership or team membership that still references their email will continue to be associated with them.

2. Click Save.

Syncing user data between Okta and Cortex

Follow the steps below to force a data sync between Okta and Cortex.

1. In your Okta admin dashboard, open the Cortex app then select the Provisioning tab.

2. Under the Settings panel, click To App.

3. Under Cortex Attribute Mappings, click Force sync.

Verifying provisioning in Cortex

Follow the steps below to confirm successful user provisioning in Cortex.

1. Log in to Cortex.

2. From the main sidebar, click your avatar in the bottom-left corner.

3. Click Settings.

4. From the Settings menu, scroll to the Security and access section, then select Permissions.

5. Confirm that users are listed in the Users tab.

   You can change the default role assigned to new users who are provisioned from Okta. Select the Default role drop-down menu to change the default role.

Deprovisioning users

When a user is removed or deprovisioned in Okta, the following happens in Cortex:

• The user's roles are removed

• The user's team memberships are removed

• The user's personal API keys are deleted

• All of the user's active sessions are immediately invalidated

Deprovisioned users can no longer access Cortex, even if they had an active browser session at the time of removal. No additional action is required to enforce access revocation—removal from your identity provider is sufficient.

Verifying a user has been deprovisioned in Cortex:

1. Log in to Cortex.

2. From the main sidebar, click your avatar in the bottom-left corner.

3. Click Settings.

4. From the Settings menu, scroll to the Security and access section, then select Permissions.

5. Select the Users tab, then verify that the user has been removed.

Troubleshooting and FAQ

Why might I see a "Forbidden from remote server" error in Okta when testing authentication?

This can happen if you did not configure user provisioning in your SCIM settings in Cortex before testing the integration in Okta. Follow the steps to configure SCIM, then try again.

Do I need the Okta integration set up on the Cortex side to use Okta SCIM?

You do not need to have the Okta integration configured on the Cortex side. However, you will still need to use the Cortex Okta Integration Network app within Okta using a valid Cortex API key.