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

# Sync people from Microsoft Entra

> Choose people from your Microsoft directory, keep their details and groups up to date, and handle departures without losing completed history.

Use Microsoft Entra to keep your ClearPolicy people list up to date with your organization’s Microsoft directory. Choose who to include, place them in ClearPolicy groups, and review the first sync before turning it on.

Changes flow from Microsoft to ClearPolicy. ClearPolicy does not edit Microsoft accounts. Sync adds **people** who receive documents; it does not invite **team members** or give anyone management access to ClearPolicy.

## Before you start

* You need an **Owner** or **Administrator** role in ClearPolicy and an active trial or subscription.
* Use your organization’s Microsoft work or school directory, not a personal Microsoft account.
* Have a Microsoft administrator available to approve directory access. See [Microsoft administrator details](#microsoft-administrator-details) for the required role and permission.
* Check **Automatic request emails** in any ClearPolicy groups you plan to populate. Sync can send document requests through those groups.

Microsoft Entra sync, **Sign in with Microsoft**, and [OneDrive imports](https://docs.clearpolicy.app/integrations/microsoft.md) are separate connections. Setting up one does not enable the others.

## Connect your directory

1. Open **Settings → Integrations** and find **Microsoft Entra**.
2. Click **Connect**.
3. Sign in to the Microsoft directory you want to connect and complete the administrator approval.
4. Return to ClearPolicy. Wait for the directory information to finish loading.

Connecting loads information for setup and previews. It does not start importing people. You choose the selection and review the changes first.

After connecting, use **Configure** on the Microsoft Entra integration card to return to its settings. The **Microsoft Entra** panel combines connection details, sync status, and available actions. **People and sync settings** below it contains your selection and return settings.

You can connect one Microsoft directory to a ClearPolicy organization. If setup is unavailable, [contact support](https://docs.clearpolicy.app/guides/get-support.md).

## Choose who to sync

Under **People and sync settings**, choose **Everyone in the directory** or **People who match conditions**.

Conditions let you select people by these Microsoft profile fields:

| Field | Example use |
| - | - |
| **Employee type** | Include employees, contractors, or another value your organization uses. |
| **Department** | Include the Operations department. |
| **Company name** | Include people assigned to a particular company. |
| **Job title** | Include people with a particular role. |
| **Office location** | Include people based at the Denver office. |
| **Account status** | Check whether the Microsoft account is enabled or disabled. |
| **Account type** | Distinguish Microsoft member accounts from guest accounts. |

Select **Match all conditions** when every condition must be true. Select **Match any condition** when one match is enough.

For example, to include employees at your Denver office, choose **Match all conditions**, then add **Employee type → Is → Employee** and **Office location → Is → Denver**. Use the values that actually appear in your directory.

### Choose values and handle empty fields

Search the value picker to see values from the last directory refresh and how many people have each value. Those counts describe the directory field, before applying your other conditions.

You can also type a future value, such as an office that has not opened yet. Zero matches does not prevent you from saving a selection. If sync is already in use, check the review: changing the selection can archive people who no longer match.

* **Is** matches a value. Text matching ignores capitalization and surrounding spaces.
* **Is not** excludes that value but also excludes people whose field is empty.
* **Is empty** includes people with no value in that field.
* **Is not empty** includes people with any value in that field.

> [!NOTE]
>
> Disabled Microsoft accounts are not added as active people, even if they match
> your conditions or you choose everyone. A linked person whose Microsoft
> account becomes disabled is archived. The sync review shows these effects.

## Preview matches and review changes

These actions answer different questions:

| Action | What it does |
| - | - |
| **Preview matching people** | Shows who matches your current conditions using the directory information already loaded. Search by name, email, or department and browse 15 people per page. |
| **Refresh directory** | Reads the latest Microsoft profiles and updates the values, counts, and information used by previews. It does not change people in ClearPolicy. |
| **Review sync changes** | Shows what ClearPolicy would add, update, connect, archive, or restore, including group changes and document requests. Nothing is applied until you confirm. |

The **Directory updated** time tells you how recent the preview information is. Refresh after making a change in Microsoft or when ClearPolicy asks for newer information. Preview information is kept for up to one hour; it is not a live view of Microsoft.

The matching count is not a promise that every match will be imported. Someone may match your conditions but need an email correction, an existing-person decision, or a restoration decision in the sync review.

Closing either sheet preserves your settings edits. A sync review expires after 15 minutes. If the review expires or something changes before you apply it, open a fresh review.

When you choose an existing person or make a restoration decision, wait for the review to recalculate before applying. The Apply action is unavailable while the review is loading or has an error.

## Review and enable the first sync

1. Finish your selection and choose what should happen **When archived people match again**. The default is **Review before restoring**.
2. Click **Review sync changes**.
3. Check the people, group changes, document assignments, and requests shown. Resolve any decisions you can.
4. Click **Apply and start sync**. ClearPolicy applies the reviewed changes, then starts daily sync after they finish successfully.

You do not need to save your selection before reviewing. **Apply and start sync** also saves the settings you reviewed.

Before the first sync, **Save selection** appears when you have unsaved settings edits. Use it if you want to save your setup without importing people or starting daily sync.

### Connect an existing person

If a Microsoft email matches someone already in ClearPolicy, the review asks you to check the existing person. Choose **Connect to \[name]** only when they are the same person.

An email match alone does not connect the records automatically. Once connected, ClearPolicy follows the Microsoft account even if its email changes. People already in ClearPolicy who are not connected to Entra are not archived just because they fall outside your Entra selection.

### Understand “Needs attention”

A held person needs a correction or decision before their changes can proceed. The review explains why. Common reasons include a missing first name, missing or invalid email, duplicate email, or an archived person awaiting restoration.

You can apply the other reviewed changes while a person remains held. Later, the **Microsoft Entra** panel shows how many people need attention. Use **Review sync changes** there when offered to review outstanding issues and any other current sync changes.

## Keep profile details up to date

For connected people, Microsoft maintains the first name, last name, email address, and usable phone number. Make lasting corrections in Microsoft; a later sync can replace manual edits to these fields in ClearPolicy.

Phone sync uses a usable mobile number first, then the first business number. Numbers must include a country code. If neither number is usable, ClearPolicy keeps the saved phone number.

Name and email changes update pending document requests without resending them. Completed records keep their original details. An email change also replaces pending signing links; use the normal [request follow-up actions](https://docs.clearpolicy.app/guides/manage-requests.md) if the person needs a new email.

## Put synced people in groups

Groups decide which documents people need. Entra group conditions work within your organization’s people selection; they cannot bring in someone excluded by that selection.

1. Open a ClearPolicy group and click **Edit group settings**.
2. Under **Which synced people belong in this group?**, choose **Use Microsoft Entra selection**.
3. Choose **Everyone selected for sync** or **People who match conditions**. For example, put selected people from the Denver office into a **Denver staff** group.
4. Check the group’s **Automatic request emails** and **Default Recipient Message**.
5. Click **Save changes**. If sync has already been enabled, check the review and click **Apply reviewed changes**. Before activation, the rules are saved for the first sync.

These rules use profile fields, not Microsoft group membership. You create and choose the ClearPolicy groups yourself.

### Membership changes

* Entra adds matching people and removes memberships it manages when people stop matching the group’s rules.
* Memberships added separately, such as by your team or another integration, are kept. A review may show **Keep independent membership**.
* If you manually remove someone who still matches the Entra rules, a later sync can add them back. Change the rules for a lasting change.
* Choose **Manage membership manually** to stop Entra managing that group. Existing members stay in the group.

Leaving a group does not, by itself, cancel requests or end existing signature assignments. Read access granted by that group ends unless another group still grants it. [Archiving a person](#when-people-leave-or-return) has broader effects.

### When sync sends document requests

Sync follows each group’s **Automatic request emails** setting:

* **On:** newly active, eligible assignments to published documents that require a signature can send requests.
* **Off:** prepare the assignments, then use **Send missing** when ready.
* **Available to read:** published documents become accessible through group membership without request emails.

Turning automatic emails on also checks for existing eligible missing requests. Review the confirmation or Entra changes before applying. The review shows requests and recipient messages. Overlapping groups do not generate duplicate requests for the same newly applicable person and document.

See [group automation](https://docs.clearpolicy.app/guides/manage-groups.md#automatic-request-emails) for the full sending behavior.

## When people leave or return

ClearPolicy automatically archives a connected person when their Microsoft account is disabled, deleted, or no longer matches the organization’s selection. This happens during routine sync; there is no separate approval for each departure.

Archiving:

* Removes the person from active lists and compliance counts.
* Cancels pending document requests and ends active document assignments.
* Keeps completed records and request history available.

Entra-managed group memberships can also be removed when the person leaves your selection. Memberships added separately are kept.

Changing your selection can therefore archive people. Review those effects before applying settings changes.

### Choose how people return

Under **When archived people match again**, choose:

| Setting | Result |
| - | - |
| **Review before restoring** | The person stays archived until you review and choose **Restore this person**, then apply the changes. This is the default. |
| **Restore automatically** | A later sync restores an eligible person who was archived by this integration. |

Both options apply only to people archived by this integration. Someone archived manually stays archived; use the person’s **Unarchive** action if you want them active again.

Restoring a person reestablishes document assignments from their current groups. It does not reopen canceled requests or send new requests as part of restoration. Review their documents and use **Send missing** when new requests are needed.

## Run, pause, or change sync

With **Sync people** on, ClearPolicy schedules a daily sync for 3 AM in your [organization’s time zone](https://docs.clearpolicy.app/guides/timezone.md). A successful manual sync earlier that day satisfies the daily run. This is a daily check, not an immediate response to every Microsoft change.

Daily sync and **Sync now** read a complete, fresh directory before applying changes. They do not rely on the older information shown in the selection preview. An incomplete directory read is not treated as evidence that people were deleted.

| Action | When to use it |
| - | - |
| **Sync now** | Apply your saved settings to the latest Microsoft information without waiting for the daily schedule. It can update people, archive departures, and send requests according to group settings. |
| **Sync people** off | Turn off the switch to pause sync. Completed changes stay in place; remaining work stops. Requests already created can still be delivered. |
| **Sync people** on | Turn on the switch to resume an intentionally paused sync when no review is required. It allows future daily runs; it does not resume an old, stopped run. |
| **Continue sync** | Continue interrupted work when ClearPolicy offers this action. Already completed changes are kept. If you were starting or resuming daily sync, it starts only after the changes finish. |
| **Review sync changes** | Check effects before applying edited settings, or review people needing attention when this action is offered. |

The **Microsoft Entra** panel shows the last successful sync, results, and anything needing attention. **Sync now** is available after setup while sync is on and no review is required. If it is unavailable, review or reset unsaved settings, wait for the current sync, or follow the recovery action shown in that panel.

### Change your settings

Edit your selection or return setting under **People and sync settings**, then click **Review sync changes** at the bottom of that panel. You do not need to save first. Check the effects and click **Apply reviewed changes** to save and apply the reviewed settings.

If you intentionally paused sync, **Apply reviewed changes** applies those changes but leaves daily sync paused. Use the **Sync people** switch afterward when you are ready to resume. You cannot turn it on while settings edits are unsaved; review and apply them, or use **Reset** to discard them first.

### Reconnect and resume

If Microsoft access expired or was revoked, use **Reconnect Microsoft Entra** in the connection panel and complete Microsoft approval again. If you previously disconnected, use **Connect** on the integration card. Reconnect before trying to review or continue interrupted work.

After reconnecting, your saved selection is kept. Check it under **People and sync settings**, click **Review sync changes**, then choose **Apply and resume sync**. Daily sync resumes only after the reviewed changes finish successfully. If your organization has never completed its first sync, the action is **Apply and start sync** instead.

## Disconnect the directory

Open **Settings → Integrations**, click **Configure** for **Microsoft Entra**, then choose **Disconnect directory** in the connection panel.

Disconnecting stops Entra sync and keeps your saved selection. It does not delete people, undo completed changes, or disconnect Microsoft sign-in or OneDrive. Reconnecting the same Microsoft directory preserves the existing person connections, but you must review changes again before sync resumes.

Disconnecting in ClearPolicy does not revoke permission in Microsoft. Your Microsoft administrator can remove consent for **ClearPolicy Directory Sync** in the Entra admin center. See [Microsoft’s permission management instructions](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/manage-application-permissions).

To switch to a different Microsoft directory, contact support rather than trying to reuse the connection for another directory.

## Troubleshooting

> [accordion] Microsoft asks for administrator approval
>
> Ask your Microsoft administrator to approve **ClearPolicy Directory Sync**.
> A ClearPolicy Administrator role does not grant Microsoft administrator
> rights. The required Microsoft roles are listed below.

> [accordion] An office, department, or person is missing from the preview
>
> Check the profile in Microsoft, then click **Refresh directory**. Confirm
> your **Match all conditions** or **Match any condition** choice and look for
> empty fields. You can type a future field value before anyone has it.
>
> If the person appears in the matching list but is not synced, open
> **Review sync changes** for the reason. A disabled account or a missing
> required profile detail can prevent them from being added.

> [accordion] A person needs an email or name correction
>
> Correct the Microsoft profile’s first name and email, then refresh and
> review again. A Microsoft sign-in name is not always a usable email address.
> Ask your administrator to check the profile’s email field.
>
> If the review reports a duplicate or an email already used by someone else,
> resolve that conflict first. Do not connect two different people to bypass it.

> [accordion] An archived person is not returning
>
> Confirm that their Microsoft account is enabled and matches the selection.
> With **Review before restoring**, you must choose **Restore this person**
> and apply the review. People archived manually require **Unarchive** on
> their ClearPolicy person page.

> [accordion] No document requests were sent
>
> Check the group’s **Automatic request emails**, the document’s publication
> status, and **Requires a signature**. Existing assignments are not newly
> active simply because another group includes them. Restoration also does
> not send requests. Use [Send missing](https://docs.clearpolicy.app/guides/manage-groups.md#send-missing-requests)
> for eligible gaps and [delivery help](https://docs.clearpolicy.app/guides/delivery-failures.md) for requests
> that already exist but did not arrive.

> [accordion] The sync stopped or asks for another review
>
> Follow the action in the **Microsoft Entra** panel. Use **Continue sync**
> when offered to finish interrupted work. If the page asks for a review,
> check **People and sync settings** and use **Review sync changes** below it.
> Work already completed is kept.
>
> If an open review expires or settings or people change before you apply it,
> use **Review latest changes** in the review sheet, then check the updated
> effects before applying. Applying an ordinary review while daily sync is
> paused does not resume it; **Apply and resume sync** explicitly does.
>
> If ClearPolicy shows a wait time after repeated clicks, wait before trying
> again. If Microsoft is limiting directory requests, allow time for it to
> recover. If the page reports that access was revoked or expired, use
> **Reconnect Microsoft Entra** first. Review and continue actions are
> unavailable until you reconnect.

> [accordion] The directory exceeds the current setup limit
>
> Contact support with your approximate directory size and what you want to
> sync. Selection conditions limit who ClearPolicy syncs, but the connection
> still needs to read the directory to evaluate those conditions.

For help, use **Support** in ClearPolicy or email [support@clearpolicy.app](mailto:support@clearpolicy.app). Include your organization name, what you were trying to do, and the error text. Do not send passwords or access tokens.

## Microsoft administrator details

> [accordion] Consent, access scope, and Microsoft roles
>
> ClearPolicy Directory Sync requests Microsoft Graph **User.Read.All** as an
> **application permission**, shown by Microsoft as **Read all users’ full
> profiles**. This allows unattended directory reads without a team member
> staying signed in.
>
> Ask a Microsoft **Privileged Role Administrator** or **Global Administrator**
> to approve this access. **Application Administrator** and **Cloud Application
> Administrator** alone cannot grant Microsoft Graph application permissions.
> Your tenant’s consent policies may add an approval process. See
> [Microsoft’s admin consent guidance](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent).
>
> This permission reads profiles across your Microsoft directory. The
> ClearPolicy conditions decide which people to sync; they do not narrow the
> Microsoft permission to a department, office, or group. No Microsoft group
> memberships are mirrored by this integration.
>
> The directory permission does not grant access to OneDrive files or mailbox
> contents, and it does not allow account changes. File importing uses the
> separate OneDrive connection. See [Microsoft’s permission reference](https://learn.microsoft.com/en-us/graph/permissions-reference#userreadall).

> [accordion] Profile fields and matching identity
>
> | ClearPolicy use | Microsoft Graph property |
> | - | - |
> | First and last name | `givenName`, `surname` |
> | Email address | `mail` |
> | Phone | `mobilePhone`, then the first entry in `businessPhones` |
> | Name displayed in previews | `displayName` |
> | Selection and group conditions | `employeeType`, `department`, `companyName`, `jobTitle`, `officeLocation`, `accountEnabled`, `userType` |
>
> A first name and valid, unique email are needed to sync a profile. ClearPolicy
> does not substitute `userPrincipalName` for a missing `mail` address. Account
> status uses `accountEnabled`; disabled accounts are never added as active
> people.
>
> After an initial connection is reviewed, identity follows the Microsoft
> directory and object ID, not the email address. Reusing an email for a different
> Microsoft account does not silently transfer the connection. If a connected
> person was deleted from ClearPolicy, a later sync holds that profile for
> attention rather than automatically attaching it to another person.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.