# Configuring Microsoft Entra ID SCIM for Cortex

This article explains how to configure Microsoft Entra ID SCIM to work with Cortex. If you're looking to turn on SSO in Cortex via Entra ID, refer to [this article](https://docs.cortex.io/configure/settings/managing-users/configuring-sso/entraid).

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

{% hint style="info" %}
Prior to configuring Entra ID 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 %}

## Prerequisites

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.

{% hint style="info" %}
Be sure to copy the API key and save it for later. Do not skip this step—you can only view the key once!
{% endhint %}

## Step 1: Adding an Entra ID non-gallery application for SCIM <a href="#step-1" id="step-1"></a>

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

1. Log in to the Microsoft Entra Admin Center at <https://entra.microsoft.com>.
2. Navigate to **Entra ID > Enterprise apps**.
3. Click **+ New application**.
4. Click **+ Create your own application**.
5. Enter the application name, i.e. `Cortex SCIM`.
6. Select **Integrate any other application you don't find in the gallery (Non-gallery)**.
7. Click **Create**.

## Step 2: Configuring Entra ID automatic provisioning for SCIM <a href="#step-2" id="step-2"></a>

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

### Setting up the connection between Cortex and Entra ID <a href="#step-2a" id="step-2a"></a>

1. Log in to the Microsoft Entra Admin Center at <https://entra.microsoft.com>.
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](#step-1).
4. From the left menu, select **Provisioning**.
5. Click **Connect your application**.
6. Below *Admin Credentials* complete the following fields:
   1. From the *Select authentication method* drop-down menu, select **Bearer authentication**.
   2. In the *Tenant URL* field, enter `https://api.getcortexapp.com/scim/v2`.
   3. In the *Secret token* field, enter your Cortex-generated API key.
7. Click **Test Connection**. A **Success** message appears.
8. Click **Create**.

### Configuring scope in Entra ID <a href="#step-2b" id="step-2b"></a>

Follow the steps below to set the user provisioning scope.

1. Log in to the Microsoft Entra Admin Center at <https://entra.microsoft.com>.
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](#step-1).
4. From the left menu, select **Provisioning**.
5. Select the **Properties** tab.
6. Click the **pencil icon** next to Basics.
7. In the right panel, locate the *Scope* drop-down menu, then choose one of the following options:
   * **Sync only assigned users and groups** (recommended) - Only users explicitly assigned to the Cortex SCIM app will be provisioned in Cortex.
   * **Sync all users and groups** - All users in your directory will be provisioned in Cortex.

## Step 3: Enabling and verifying Entra ID SCIM provisioning <a href="#step-3" id="step-3"></a>

You must be logged in to Entra ID as one of the following roles: Application Administrator, Cloud Application Administrator, or Global Administrator.

When SCIM provisioning is turned on with Entra ID, the following happens:

* Entra ID begins the initial synchronization with Cortex. This process may take 15 to 20 minutes.
* Entra ID triggers ongoing incremental synchronizations with Cortex every 40 minutes.

{% hint style="info" %}
You can monitor the synchronization status in Entra ID via the provisioning logs.
{% endhint %}

Users are created in Cortex based on the user assignments configured in Entra ID.

### Turning on provisioning in Entra ID <a href="#step-3a" id="step-3a"></a>

Follow the steps below to enable user provisioning in Entra ID.

1. Log in to the Microsoft Entra Admin Center at <https://entra.microsoft.com>.
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](#step-1).
4. From the left menu, select **Provisioning**.
5. Click **Start Provisioning**.

### Verifying provisioning in Entra ID <a href="#step-3b" id="step-3b"></a>

Follow the steps below to confirm successful user provisioning in Entra ID.

1. Log in to the Microsoft Entra Admin Center at <https://entra.microsoft.com>.
2. Navigate to **Entra ID > Enterprise apps**.
3. Open the Cortex SCIM application you created in [Step 1: Adding an Entra ID Non-gallery Application for SCIM](#step-1).
4. From the left menu, select **Provisioning**.
5. From the left menu, select **Provisioning logs**.
6. Review the logs for any errors.
7. Verify that users display a **Success** status.

{% hint style="info" %}
Entra ID synchronizes with Cortex every 40 minutes. If you are within the 40-minute window, there may not be any recent information in the logs.
{% endhint %}

### Verifying provisioning in Cortex <a href="#step-3c" id="step-3c"></a>

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 Entra ID. Select the <em>Default role</em> drop-down menu to change the default role.</p></div>

### Deprovisioning users <a href="#step-3d" id="step-3d"></a>

When a user is [removed or deprovisioned in Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/how-provisioning-works#deprovisioning), 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.