> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Provisioning roles with SCIM
> Assign Cortex roles from Microsoft Entra ID, so your identity provider controls who has which role.
PRIVATE BETA
With SCIM role provisioning, your identity provider (IdP) decides which roles each user has in Cortex. You assign app roles to users in Microsoft Entra ID, Entra ID sends those role values to Cortex, and Cortex gives each user the matching roles. When someone changes teams or leaves, you update them in one place.
> [!NOTE]
>
> SCIM role provisioning is in Private Beta and is only available for Microsoft Entra ID. To request access, contact your Cortex account team.
## How role provisioning works
Entra ID sends each user's role values to Cortex, and Cortex turns those values into Cortex roles.
```mermaid theme={null}
flowchart LR
A["1. Entra ID
Sends a value for each
app role a user has,
such as OWNER"]
B{"2. Cortex
Looks up
each value"}
C["Exact match
Mapped automatically"]
D["Your mapping
Uses the roles you chose"]
E["No match
Uses the fallback role"]
F["3. User's roles
The user gets every
role that matched"]
A --> B
B --> C
B --> D
B --> E
C --> F
D --> F
E --> F
```
A few things to keep in mind:
* **Users get every role their values map to.** A user with several values gets all of the matching roles. You can map several values to one role, and one value to several roles.
* **The fallback role covers everyone else.** A user whose values don't match any role, or who has no values, gets the fallback role you choose. If you don't choose one, the fallback role is User.
* **Your IdP becomes the source of truth.** While role provisioning is on, you can't change a user's roles in Cortex. Make role changes in Entra ID instead.
### Automatic mapping
Cortex maps a value automatically when it exactly matches one of the following:
| Value from Entra ID | Cortex role |
| - | - |
| `VIEWER` | Viewer |
| `USER` | User |
| `MANAGER` | Manager |
| `OWNER` | Admin |
| A custom role's identifier, such as `scorecard-owners` | That custom role |
Matching is case-sensitive. For example, `manager` doesn't match `MANAGER`. If you add your own mapping for a value, your mapping replaces the automatic one.
## Prerequisites
* [Entra ID SCIM is configured](https://docs.cortex.io/configure/settings/managing-users/scim/entraid-scim.md), and users are provisioning to Cortex.
* Both **Enable automatic provisioning of users** and **Enable automatic deprovisioning of users** are turned on in [SCIM settings](https://docs.cortex.io/configure/settings/managing-users/scim/configuring-scim.md). If you turn either one off later, role provisioning turns off too.
* You have the `Configure Open ID Connector & SCIM` permission to change SCIM settings and the `Edit Roles` permission to map roles. Both are included in the Admin role.
* In Entra ID, you're logged in as an Application Administrator, Cloud Application Administrator, or Global Administrator.
## Step 1: Creating app roles in Entra ID
Create one app role for each role value you want to send to Cortex.
1. Log in to the Microsoft Entra Admin Center at [https://entra.microsoft.com](https://entra.microsoft.com).
2. Navigate to **Entra ID > App registrations**, then open your Cortex SCIM application.
3. From the left menu, select **App roles**.
4. Click **+ Create app role**, then complete the following fields:
* **Display name** - The name of the role.
* **Allowed member types** - Select **Users/Groups**.
* **Value** - The role value.
* **Description** - A short description of the role.
5. Click **Apply**.
> [!TIP]
>
> To skip manual mapping in Cortex, name your app roles so they match a Cortex role exactly. For example, use `OWNER` for Admin. Cortex matches on the role value it receives. Depending on your Entra ID configuration, that value comes from the app role's display name or its value, so set both to the same text.
## Step 2: Adding a roles attribute mapping in Entra ID
Choose the mapping that fits how you assign roles.
1. In the Entra Admin Center, navigate to **Entra ID > Enterprise apps**, then open your Cortex SCIM application.
2. From the left menu, select **Provisioning**.
3. Under **Manage**, select **Attribute mapping**. The **Users** tab opens by default.
4. Follow the steps for one of the options below.
> [accordion] One role per user
>
> Use this option when each user has a single app role and its name matches a Cortex role.
>
> 1. Click **+ Add attribute mapping**.
> 2. From the **Mapping type** dropdown, select **Expression**.
> 3. In the **Expression** field, enter `SingleAppRoleAssignment([appRoleAssignments])`.
> 4. From the **Target attribute (customappsso)** dropdown, select `roles[primary eq "True"].value`.
> 5. Click **Add**, then click **Save**.
> [accordion] Multiple roles per user
>
> Use this option when users can have more than one app role.
>
> 1. Click **Advanced options**, then select **Edit customappsso user attributes**.
> 2. Scroll to the bottom of the list, then click **+ Add new attribute**.
> 3. Enter `roles` as the name, select the **Multi-value** checkbox, then click **Save**.
> 4. On the **Attribute mapping** page, click **+ Add attribute mapping**.
> 5. From the **Mapping type** dropdown, select **Expression**.
> 6. In the **Expression** field, enter `AppRoleAssignmentsComplex([appRoleAssignments])`.
> 7. From the **Target attribute (customappsso)** dropdown, select `roles`.
> 8. Click **Add**, then click **Save**.
## Step 3: Assigning app roles to users in Entra ID
1. In the Entra Admin Center, navigate to **Entra ID > Enterprise apps**, then open your Cortex SCIM application.
2. From the left menu, select **Users and groups**.
3. Click **+ Add user/group**.
4. Select the user or group, select the role, then click **Assign**.
Entra ID sends role changes to Cortex during its next sync, which runs every 40 minutes. To send a user's roles right away, select **Provisioning > Provision on demand**, choose the user, then click **Provision**.
## Step 4: Mapping role values in Cortex
Turn on role mapping setup first. During setup, Cortex records the role values Entra ID sends, but doesn't change anyone's roles. This lets you finish your mappings before they take effect.
1. In Cortex, click your avatar in the bottom-left corner of the main sidebar, then select **Settings**.
2. From the **Settings** menu, scroll to the **Security and access** section, then select **SCIM**.
3. Toggle on **Set up role mapping**.
4. Click the **Roles** button. The **Permissions** page opens on the **Roles** tab.
5. Review the banner at the top of the tab. It lists the values Entra ID has sent that don't match a role yet, and how many users have each one. Click **Show all** to see the full list.
6. On a role's card, click **Add IdP role** to add the value(s) that should grant that role. You can choose an unmatched value, choose a value that's already mapped to another role, or type a new value.
Values that Cortex mapped automatically are labeled `auto` on the role's card and can't be removed. If every value you send matches a Cortex role automatically, you don't need to add any mappings.
> [!NOTE]
>
> Cortex lists a value only after Entra ID has sent it for at least one user. If you already know a value that Entra ID will send, type it in to add the mapping before any user is provisioned with it. To make a missing value appear in the list, provision a user who has that app role on demand.
## Step 5: Turning on role provisioning
> [!NOTE]
>
> Turning on role provisioning replaces roles for everyone in your workspace, and only users provisioned through SCIM can log in. Before you continue, make sure everyone who needs access, including admins, is assigned to your Cortex SCIM application in Entra ID. For details, see [what changes](#what-changes-when-role-provisioning-is-on).
1. From the **Settings** menu, scroll to the **Security and access** section, then select **SCIM**.
2. Toggle on **Manage user roles from your identity provider**.
3. Click the **Roles** button. The **Permissions** page opens on the **Roles** tab.
4. On the **Fallback role** card, select the role for users whose values don't match any role. The default role is `User`. You can change the fallback role at any time.
Cortex applies the recorded values to every active user right away. To confirm, select **Permissions** from the **Settings** menu. The **IdP values** column shows the values each user received from Entra ID, next to the roles those values grant.
If the new roles would put your workspace over its seat limit, Cortex doesn't turn on role provisioning. Remove users, change your mappings, or add seats, then try again.
## What changes when role provisioning is on
* **Roles from Entra ID replace manually assigned roles.** A user's existing roles are removed and replaced with the roles their values map to.
* **Only users provisioned through SCIM can log in.** Anyone who isn't assigned to your Cortex SCIM application in Entra ID loses access to Cortex.
* **You can't edit users' roles in Cortex.** User rows on the **Permissions** tab are locked, and bulk role actions aren't available. The same applies to the Cortex API.
* **Mapping changes apply right away.** When you add or remove a value on the **Roles** tab, Cortex updates every user who has that value. If you remove a user's only matching value, they get the fallback role.
* **You can't delete a custom role that has a value you mapped to it.** Remove the value from the role first. A custom role that only has an automatic mapping can still be deleted.
* **You can still delete users.** Deleting a user in Cortex works the same way as before.
Role changes are recorded in the [audit logs](https://docs.cortex.io/configure/settings/audit-logs.md).
## Turning off role provisioning
Turn off role provisioning in SCIM settings at any time. Users keep the roles they have, and you can edit roles in Cortex again. Role mapping setup can only be turned off after role provisioning is off.
1. From the **Settings** menu, scroll to the **Security and access** section, then select **SCIM**.
2. Toggle off **Manage user roles from your identity provider**.
## Related topics
- [Configuring Microsoft Entra ID SCIM for Cortex](https://docs.cortex.io/configure/settings/managing-users/scim/entraid-scim.md)
- [Provisioning Cortex users with SCIM](https://docs.cortex.io/configure/settings/managing-users/scim/provisioning-users-with-scim.md)
- [Cortex beta program and release phases](https://docs.cortex.io/resources/beta.md)