# 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](https://docs.cortex.io/configure/settings/managing-users/configuring-sso/okta).

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

{% hint style="info" %}
Prior to configuring Okta SCIM, you must first turn on SCIM in Cortex. Refer to [Configuring SCIM in Cortex](https://docs.cortex.io/configure/settings/managing-users/provisioning-users-with-scim/configuring-scim) for more information.
{% endhint %}

## 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](https://docs.cortex.io/configure/api-keys#create-api-key) 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](https://support.okta.com/help/s/article/list-of-ip-addresses-that-should-be-allowlisted-for-inbound-traffic) 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](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing), then click **Add addresses**.

## Step 1: Adding the Cortex OIN app

Add the Cortex OIN app for Okta from [Okta's Cortex integration docs](https://www.okta.com/integrations/cortex/). 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](mailto:help@cortex.io) 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 click 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 left menu, click your avatar in the bottom 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.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p>You can change the default role assigned to new users who are provisioned from Okta. Select the <em>Default role</em> drop-down menu to change the default role.</p></div>

## Deprovisioning users

When a user is [removed or deprovisioned in Okta](https://developer.okta.com/docs/concepts/scim/#delete-deprovision), 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 left menu, click your avatar in the bottom 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](https://docs.cortex.io/configure/settings/managing-users/provisioning-users-with-scim/configuring-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.