> For the complete documentation index, see [llms.txt](https://docs.natoma.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.natoma.ai/docs/enterprise/secure-access-to-natoma/entra-scim-roles.md).

# Manage Natoma Role from Entra ID

This guide walks Entra ID admins through configuring SCIM provisioning for Natoma so that users are automatically created with the correct role (Admin, AppAdmin, or Member) based on their Entra group assignment.

{% hint style="info" %}
You must be signed in to the Microsoft Entra admin center as an Application Administrator, Cloud Application Administrator, or Global Administrator.
{% endhint %}

***

## Step 1 — Create App Roles in Entra ID

Entra ID uses App Roles to represent the roles that will be provisioned to Natoma. You need to define one App Role per Natoma role value.

1. In the Microsoft Entra admin center, go to **App registrations**.
2. Select your Natoma enterprise application.
3. In the left sidebar, click **App roles**, then click **Create app role**.
4. Create the following three roles (repeat for each):

**Role 1**

| Field                | Value        |
| -------------------- | ------------ |
| Display name         | `Admin`      |
| Value                | `admin`      |
| Allowed member types | Users/Groups |

**Role 2**

| Field                | Value        |
| -------------------- | ------------ |
| Display name         | `AppAdmin`   |
| Value                | `AppAdmin`   |
| Allowed member types | Users/Groups |

**Role 3**

| Field                | Value        |
| -------------------- | ------------ |
| Display name         | `Member`     |
| Value                | `member`     |
| Allowed member types | Users/Groups |

5. Click **Apply** after creating each role.

***

## Step 2 — Assign the Natoma App to an Entra Group

Assign the Natoma enterprise application to each Entra group you want to use for role-based provisioning (e.g. Natoma Admins, Natoma Members).

1. In the Entra admin center, go to **Enterprise applications** and open the Natoma app.
2. In the left sidebar, click **Users and groups**.
3. Click **Add user/group**.
4. Under **Users and groups**, search for and select your group (e.g. `Natoma Admins`).
5. Click **Select a role** and choose the corresponding App Role (e.g. `Admin`).
6. Click **Assign**.

{% hint style="info" %}
Repeat this step for each group/role combination. Every group must have a role selected — users without a role assignment will be skipped during provisioning.
{% endhint %}

***

## Step 3 — Configure the Attribute Mapping for the Role Field

By default, Entra ID does not map the app role assignment to a SCIM role attribute. You need to add this mapping manually.

1. In the Natoma enterprise app, go to **Provisioning** in the left sidebar.
2. Click **Edit attribute mappings**.
3. Expand **Mappings** and click **Provision Microsoft Entra ID Users**.
4. Scroll to the bottom of the attribute list and click **Add New Mapping**.
5. Configure the new mapping as follows:

| Field            | Value                                           |
| ---------------- | ----------------------------------------------- |
| Mapping type     | Expression                                      |
| Expression       | `SingleAppRoleAssignment([appRoleAssignments])` |
| Target attribute | `roles[primary eq "True"].value`                |

6. Click **OK**, then click **Save** on the attribute mapping page.

{% hint style="info" %}
`SingleAppRoleAssignment` is recommended when each user will have a single Natoma role. It reads the App Role assigned to the user or their group and writes the role value to the SCIM roles attribute.
{% endhint %}

***

## Step 4 — Enable Automatic Provisioning

Connect Entra ID to Natoma's SCIM endpoint and enable automatic provisioning.

1. In the Natoma enterprise app, go to **Provisioning**.
2. Click **Get started** (or **Edit provisioning** if previously configured).
3. Set the **Provisioning Mode** to **Automatic**.
4. In the **Admin Credentials** section, enter:
   * **Tenant URL**: your Natoma SCIM endpoint URL
   * **Secret Token**: your Natoma SCIM bearer token
5. Click **Test Connection** to verify, then click **Save**.
6. Under **Settings**, confirm **Scope** is set to **Sync only assigned users and groups**.
7. Click **Start provisioning**.

{% hint style="info" %}
Entra ID syncs on a cycle of approximately 40 minutes. To test immediately, use **Provision on demand** from the Provisioning page and select a specific user.
{% endhint %}

***

## Step 5 — Test the Configuration

1. Add a test user to one of the groups configured in Step 2.
2. In the Natoma enterprise app, go to **Provisioning** and click **Provision on demand**.
3. Search for and select the test user, then click **Provision**.
4. In Natoma, confirm the user appears with the expected role.

{% hint style="warning" %}
If the role field is empty, check the provisioning logs: **Provisioning → View provisioning logs**.
{% endhint %}

***

## Troubleshooting

**User provisioned but role is missing** — Confirm the user's group has a role selected under **Users and groups → Edit assignment**. A missing role selection causes Entra to skip role provisioning.

**Provisioning skipped entirely** — Entra ID skips users not assigned to the app. Ensure the user's group is listed under **Users and groups** with a role selected.

**MultipleGrantsNotSupported error** — This occurs if a user belongs to multiple groups with different roles. Either ensure users are in only one Natoma role group, or contact Natoma support about multi-role handling.

**Sync not reflecting changes** — Trigger an immediate sync via **Provision on demand**, or restart provisioning from the **Provisioning** page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.natoma.ai/docs/enterprise/secure-access-to-natoma/entra-scim-roles.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.