# Microsoft Entra Directory

The Microsoft Entra directory integration syncs your Entra user directory with Incode, enabling employee lookups and claims matching during identity verification sessions. This integration is required for any flow that requires verifying a user against their Entra directory record, including Self-Serve Portal password and MFA resets, ITSM verifications, and claims matching in Entra IAM flows.

This is a directory-only integration. It does not trigger verification sessions. Use [Microsoft Entra External Authentication Method (EAM)](https://developer.incode.com/docs/microsoft-entra-eam) integration for authentication-layer integration with Microsoft Entra.

> 📘 **Note**
>
> If your Microsoft Entra environment uses federated access through Okta as the identity provider, follow the<br />[Okta Directory](https://developer.incode.com/update/docs/okta-directory) guide instead.

***

## Prerequisites

Ensure you have the following before you begin:

- Access to the Integrations page in Dashboard. Contact your Incode Representative if you do not see it.
- A Microsoft Entra account with the following roles:
  - **User Administrator**, **Groups Administrator**, **Application Administrator**, and **App Developer** for App<br />Registration, group, and user setup
  - **Global Administrator** to grant the required app permissions

***

## Synced Data

Incode reads user profile data from Microsoft Entra to perform claims matching. Depending on your claims matching policy, some of the following fields may be required for verification to succeed. Ensure these attributes are populated for all users in the groups you intend to sync:

| Attribute                                         | Used for                                    |
| ------------------------------------------------- | ------------------------------------------- |
| First name (given name)                           | Name claim matching                         |
| Last name (surname)                               | Name claim matching                         |
| User principal name (UPN)                         | Primary user lookup (`loginHint`)           |
| Email                                             | Notification delivery, email claim matching |
| Mobile phone                                      | Phone claim matching                        |
| Date of birth                                     | Date of birth claim matching                |
| Street address, city, state, postal code, country | Address claim matching                      |

> 📘 **Note**
>
> Missing attributes will cause claims matching failures for affected users. Ensure the relevant fields are populated in Entra before triggering a directory sync.

***

## Set Up Entra Directory Integration

### Configure the Integration in Dashboard

1. Log in to Dashboard.
2. In the left menu, click **Integrations**.
3. Click **New Integration**.
4. From the **Directory** tab, select **Microsoft Entra Directory**, then
   click **Continue**.
5. Enter a **Directory Name**.
6. Enter the **User Group ID** (Object ID) of the Entra group containing the employees you want to sync. To find this, go to your Microsoft Entra portal > **Groups** > **All groups**, and copy the Object ID for the relevant group.
7. Select the permission level for the integration:
   - **Read-only**: Allows directory sync only
   - **Read and write**: Allows directory sync and Self-Serve password and MFA resets
8. Click **Save**.

### Grant Directory Permissions in Microsoft Entra

After saving, Dashboard redirects you to the Microsoft Entra admin consent page to approve the required permissions. A **Global Administrator** must complete this step.

> 📘 **Note**
>
> If permissions are rejected, or the approving user does not have sufficient permissions, the integration will remain in an incomplete state and you must restart setup.

### Sync the Directory

After permissions are granted, trigger an initial sync to import your users into Incode.

1. In the left menu, click **Integrations**.
2. From the **Directory** tab, locate the integration you just created.
3. On the integration card, click **Sync Directory**.

Depending on the size of your directory, the initial sync may take several minutes.

***

## View Synced Users

Click **Directory Information** in the left menu to view all synced users and their enrollment status. Users shown as **not enrolled** have been synced from Entra but have not yet completed an Incode verification session. To initiate verification for these users, trigger a session through your configured IAM or ITSM integration.