> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dema.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory Sync with Microsoft Entra ID

> Learn how to provision and manage Dema users automatically from Microsoft Entra ID using SCIM.

Microsoft Entra ID Directory Sync uses the System for Cross-domain Identity Management (SCIM) standard to keep your Dema users aligned with your organization directory.

Directory Sync complements [Microsoft Single Sign-On (SSO)](/guides/organization/microsoft-sso): SSO authenticates users when they sign in, while Directory Sync creates, updates, deactivates, and reactivates their Dema accounts based on changes in Entra ID.

***

## Prerequisites

Before configuring Directory Sync, make sure:

* [Microsoft SSO](/guides/organization/microsoft-sso) is configured for your Dema organization.
* You have at least the **Application Administrator** role in Microsoft Entra ID.
* You can access the enterprise application used for Dema SSO.
* You have selected a test user and decided which users or groups should have access to Dema.
* You have received the **SCIM endpoint URL** and **secret token** from your Dema representative.

<Warning>
  Treat the secret token like a password. Store it securely, do not share it over unapproved channels, and never include it in screenshots or support messages.
</Warning>

***

## Configure automatic provisioning

### Step 1: Open the Dema enterprise application

1. Sign in to the [Microsoft Entra admin center](https://entra.microsoft.com/).
2. Go to **Entra ID → Enterprise applications**.
3. Select the enterprise application already used for Dema SSO.
4. Select **Provisioning**.

### Step 2: Connect Entra ID to Dema

1. Set **Provisioning Mode** to **Automatic**.
2. Under **Admin Credentials**, enter the values provided by Dema:
   * **Tenant URL** — enter the SCIM endpoint URL exactly as provided.
   * **Secret Token** — enter the SCIM secret token.
3. Select **Test Connection**.
4. After the connection succeeds, select **Save**.

<Note>
  The SCIM endpoint and token are separate from the SAML values used for SSO. Do not enter the SSO Reply URL, Entity ID, or federation metadata URL here.
</Note>

### Step 3: Verify user attribute mappings

Open **Mappings → Provision Microsoft Entra ID Users** and confirm that the following SCIM attributes are mapped:

| SCIM attribute                 | User information            |
| ------------------------------ | --------------------------- |
| `userName`                     | Primary sign-in identifier  |
| `name.givenName`               | First name                  |
| `name.familyName`              | Last name                   |
| `emails[type eq "work"].value` | Work email address          |
| `active`                       | Whether the user is enabled |

<Warning>
  Every provisioned user must have a work email mapped to `emails[type eq "work"].value`. Provisioning fails if the email is sent only as `userName`.
</Warning>

### Step 4: Set the provisioning scope

1. Under **Settings**, set **Scope** to **Sync only assigned users and groups**.
2. Review the users and groups already assigned to the enterprise application.
3. Assign the test user if they are not already assigned.
4. Keep automatic provisioning stopped until the test user has been verified.

Only users assigned directly or through an assigned group are included in this scope. Review existing assignments carefully before starting provisioning, because they determine which accounts Entra ID manages in Dema.

***

## Test with one user

Test the connection before enabling scheduled provisioning for everyone:

1. In the enterprise application, open **Provisioning**.
2. Select **Provision on demand**.
3. Search for and select the test user.
4. Select **Provision** and review the result for each provisioning step.
5. Ask your Dema representative to confirm that the user is active and that their name and email address are correct.
6. If needed, update the test user's name in Entra ID and provision them again to confirm that changes are synchronized.

<Tip>
  Record the provisioning time and result. This information helps Dema investigate the request if the user does not appear as expected.
</Tip>

***

## Enable Directory Sync

After the test succeeds:

1. Reconfirm the users and groups assigned to the enterprise application.
2. Return to the application's **Provisioning** page.
3. Start provisioning.
4. Monitor **Provisioning logs** while Entra ID completes the initial cycle.
5. Confirm in Dema that the expected users are active.

The initial provisioning cycle can take longer than later updates. Use **Provision on demand** when you need to test a specific user immediately.

After Directory Sync is enabled, manage synced names, email addresses, and account status in Entra ID. Changes made there are sent to Dema automatically.

***

## User lifecycle behavior

| Change in Microsoft Entra ID      | Result in Dema                                                      |
| --------------------------------- | ------------------------------------------------------------------- |
| Assign a new user                 | Creates and activates the user's Dema account.                      |
| Update a user's mapped attributes | Updates the corresponding Dema account.                             |
| Disable or unassign a user        | Deactivates the Dema account and prevents the user from signing in. |
| Re-enable or reassign a user      | Reactivates the existing Dema account.                              |

Directory Sync deactivates users instead of deleting them. This makes offboarding reversible and preserves the user's existing Dema account if they are assigned again later.

***

## Troubleshooting

| Issue                                    | What to check                                                                                                                                                                                |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Test Connection fails**                | Re-enter the endpoint URL and secret token exactly as provided. Make sure the endpoint does not contain an extra trailing slash.                                                             |
| **A user is not provisioned**            | Confirm that the user is enabled, assigned to the enterprise application, and included in the selected provisioning scope. Review the Entra provisioning result for skipped steps or errors. |
| **Provisioning reports a missing email** | Confirm that the user's work email is mapped to `emails[type eq "work"].value`; `userName` alone is not sufficient.                                                                          |
| **A change has not appeared in Dema**    | Confirm that provisioning is running and check **Provisioning logs**. Use **Provision on demand** to test the user immediately.                                                              |
| **A user was deactivated unexpectedly**  | Check whether the user was disabled, directly unassigned, or removed from an assigned group in Entra ID.                                                                                     |

If the issue continues, contact your Dema representative with the affected user's email address, the provisioning timestamp, and the result shown in Entra ID. Do not include the secret token.

For more information, see Microsoft's guides to [automatic SCIM provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups) and [on-demand provisioning](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/provision-on-demand).