Troubleshoot directory synchronization
- 9 minutes
Microsoft 365 Administrators must troubleshoot any directory synchronization issues that occur. In doing so, they analyze logs for errors and remediate synchronization errors with whichever synchronization tool they're using (Microsoft Entra Connect Sync or Microsoft Entra Cloud Sync). Typical issues that can lead to synchronization problems include:
- Authentication errors, such as using incorrect on-premises or Microsoft 365 credentials.
- Inadvertently deactivating directory synchronization in the Microsoft 365 admin center or through Windows PowerShell.
- Unexpected changes in on-premises Active Directory that affect OU scoping or attribute filtering.
- Corrupted on-premises Active Directory, requiring directory recovery.
- Duplicate attributes that must be unique, such as UserPrincipalName and Proxy Address for User, Group, or Contact objects.
Microsoft 365 Administrators should become familiar with the following tasks and tools to successfully troubleshoot directory synchronization issues:
- Deactivate and Reactivate Directory Synchronization.
- View directory synchronization errors in the Microsoft 365 admin center.
- Identity synchronization and duplicate attribute resiliency.
- Unhealthy Identity Synchronization Notification.
- Directory Synchronization Troubleshooter.
- Synchronization Service Manager.
- Troubleshoot password hash synchronization with Microsoft Entra Connect Sync.
Deactivate and reactivate directory synchronization
One key area that can lead to issues unless clearly understood is when an organization deactivates directory synchronization and then reactivates it in the Microsoft 365 admin center. When an organization deactivates directory synchronization, the source of authority transfers from the on-premises Active Directory to Microsoft 365. Organizations must deactivate directory synchronization when they no longer use on-premises Active Directory to create and manage users, groups, contacts, and mailboxes. For example, after a staged Exchange migration to the cloud, where the organization no longer wants to manage objects from on-premises.
Problems can occur if an organization reactivates directory synchronization. At that time, the source of authority transfers back from Microsoft 365 to the on-premises Active Directory.
For example, let's assume Contoso deployed AD FS and single sign-on. To meet this requirement, Contoso activated directory synchronization and it created new users on-premises. Following this deployment, directory synchronization synced the new user objects that Contoso created on-premises to Microsoft 365. The source of authority for these user objects was the on-premises Active Directory. Then, later in the year, Contoso deactivated directory synchronization. As a result, the source of authority transferred to Microsoft 365. From that point on, the organization edited objects in Microsoft 365.
Warning
When an organization reactivates directory synchronization, the sync process overwrites any changes made to Microsoft 365 objects.
Identity synchronization and duplicate attribute resiliency
Duplicate attribute resiliency is a feature in Microsoft Entra ID that eliminates friction caused by UserPrincipalName and ProxyAddress conflicts when running directory synchronization. These two attributes are required to be unique across all User, Group, or Contact objects in a given Microsoft Entra tenant.
Note
Only users can have UPNs.
If an organization attempts to provision a new object with a UPN or ProxyAddress value that violates this uniqueness constraint, Microsoft Entra ID blocks that object from being created. Similarly, if an object is updated with a non-unique UPN or ProxyAddress, the update fails. While the sync client retries the provisioning attempt or update upon each export cycle, it will continue to fail until the conflict is resolved. During this process, an error report email is generated upon each attempt, and the sync client logs an error.
The resolution to this issue is a feature known as Duplicate attribute resiliency. This feature enables organizations to synchronize object attributes even if the attributes aren’t unique. Instead of completely failing to provision or update an object with a duplicate attribute, Microsoft Entra ID “quarantines” the duplicate attribute that violates the uniqueness constraint. If this attribute is required for provisioning, like UserPrincipalName, the service assigns a placeholder value. The format of these temporary values is:
<OriginalPrefix>+<4DigitNumber>@<InitialTenantDomain>.onmicrosoft.com
The attribute resiliency process handles only UPN and SMTP ProxyAddress values.
If the attribute isn't required, like a ProxyAddress, Microsoft Entra ID simply quarantines the conflict attribute and proceeds with the object creation or update. Once the attribute is quarantined, information about the conflict is sent in the same error report email used in the old behavior. However, this information only appears in the error report one time, which is at the time the quarantine happens. It doesn't continue to be logged in future emails. Also, since the export for this object succeeded, the sync client doesn't log an error and doesn't retry the create or update operation upon subsequent sync cycles.
To support this behavior, Microsoft added a new attribute called DirSyncProvisioningErrors to the User, Group, and Contact object classes. DirSyncProvisioningErrors is a multi-valued attribute that stores the conflicting attributes that would violate the uniqueness constraint should they be added normally. A background timer task is enabled in Microsoft Entra ID that runs every hour to look for duplicate attribute conflicts that were resolved. It automatically removes the attributes in question from quarantine.
Additional reading. For more information, see Identity synchronization and duplicate attribute resiliency.
View directory synchronization errors in the Microsoft 365 admin center
The Microsoft 365 admin center provides an overview of directory synchronization errors. For example, let's assume that an organization has 10,000 objects that it must synchronize to Microsoft Entra ID. The sync process might generate errors for some objects, such as attributes that must be unique, like UserPrincipalName and ProxyAddress.
To view any directory synchronization errors in the Microsoft 365 admin center, complete the following steps:
- Sign in to the Microsoft 365 admin center with an administrative account, such as a global admin account.
- On the Home page, select the User management card.
- On the User management card, select Sync errors under Microsoft Entra Connect to see the errors.
- On the Directory sync errors page, select any of the errors to display the details pane with information about the error and tips on how to fix it.
After viewing an error, see fixing problems with directory synchronization for Microsoft 365 to correct any identified issues.
Unhealthy identity synchronization notification
Microsoft Entra Connect Sync informs the Microsoft 365 Administrator by default through email about directory synchronization errors. The subject of this email report is "Directory Synchronization Error Report: Date + Time." The system sends the email to the technical contact email address the Microsoft 365 administrator configured in the company's Microsoft 365 tenant. The administrator can modify the technical contact email address in the Microsoft 365 admin center.
Directory synchronization troubleshooter
Microsoft Entra Connect Sync includes a troubleshooting task that identifies possible issues. It also provides guidance on changes that can fix any synchronization issues.
The Microsoft 365 administrator can choose one of the following options when running this task:
- Quick Scan. This option scans your event logs and Microsoft 365 settings.
- Full Scan. This option runs the quick scan and also scans your Active Directory objects.
After choosing the type of scan to run, the administrator must download the Microsoft 365 Support Assistant tool. The purpose of this tool is to run and evaluate these checks. You should download the tool to a desktop or a member server, depending on your environment. The user must have at least Read permissions in the on-premises Active Directory and Microsoft 365 tenant to run the tool.
Synchronization Service Manager
To check synchronization issues, the Microsoft 365 administrator must open the Synchronization Service Manager in the Microsoft Entra Connect Sync group on the Start menu. Within the application, the administrator can select the Operations tab to confirm whether the following operations completed successfully:
- Import on the AD Connector
- Import on the Microsoft Entra Connector
- Export on the AD Connector
- Export on the Microsoft Entra Connector
- Full Sync on the AD Connector
- Full Sync on the Microsoft Entra Connector
Review the result from these operations to validate the directory synchronization status and to identify any errors.
By default, directory synchronization runs every 30 minutes. If you don't want to wait 30 minutes to troubleshoot an issue, complete the following procedure to force a manual synchronization:
- In the Synchronization Service Manager, on the Connectors page, select Actions in menu bar and then select Run.
- In the Run Connector window, in the Connector drop-down list, select the source directory. For example, to synchronize changes from the on-premises Active Directory to Microsoft Entra ID, select the organization's domain name, such as adatum.com.
- In the Run profiles section, select whether to run a Full, Delta, or Export synchronization.
- Select Run to start the directory synchronization.
You can use Windows PowerShell to start a manual directory synchronization on your organization's Microsoft Entra Connect Sync server. The following table displays the necessary cmdlets.
| Cmdlet | Description |
|---|---|
| Start-ADSyncSyncCycle -PolicyType Initial | Start a full synchronization. |
| Start-ADSyncSyncCycle -PolicyType Delta | Start a delta synchronization. |
Additional reading. For more information, see Troubleshooting Errors during synchronization.
Troubleshoot password hash synchronization with Microsoft Entra Connect Sync
Password hash synchronization is one of the sign-in methods that accomplishes hybrid identity. Microsoft Entra Connect Sync synchronizes a hash of a user's password (and NOT the actual password itself) from an on-premises Active Directory instance to a cloud-based Microsoft Entra ID instance.
Password hash synchronization is an extension to the directory synchronization feature implemented by Microsoft Entra Connect Sync. Organizations use this feature to enable their users to sign in to Microsoft Entra ID services like Microsoft 365. You sign in to the service with the same password you use to sign in to your on-premises Active Directory instance.
Directory synchronization synchronizes passwords in near real time, specifically every two minutes. The directory synchronization scheduler isn't responsible for a full sync of all passwords. To complete a full sync of all passwords, you must manually request it through PowerShell.
An organization can get an overview of its password hash synchronization configuration by running a PowerShell script provided by Microsoft.
If you're experiencing issues with one object, ensure your organization didn't select the User must change password at next logon option for the user in Active Directory Users and Computers. You shouldn't select this option because the system doesn't synchronize temporary passwords to Microsoft Entra ID.
Additionally, if your organization has an inbound or outbound rule with PasswordSync set to True, you should check the following rules in the Synchronization Service Manager:
- In from AD – User AccountEnabled
- Out to Microsoft Entra ID – User Join sync
Additional reading. For more information, see Troubleshooting password hash synchronization with Microsoft Entra Connect Sync.
Links for more assistance
For more assistance, see the following list of common directory synchronization problems along with links to possible causes of each issue:
- Password hashes aren't synchronizing, or I'm seeing an alert in the admin center that indicates a password hash synchronization hasn't recently occurred.
- Synchronized objects aren't appearing or updating online, or I'm getting synchronization error reports from the Service.
- I have an alert in the admin center, or I'm receiving automated emails that indicate there hasn't been a recent synchronization event.
- Troubleshoot connectivity issues with Microsoft Entra Connect
- Microsoft Entra Connect Accounts and permissions
- Microsoft Entra Connect Sync: How to manage the Microsoft Entra service account
- Directory synchronization to Microsoft Entra ID stops or you're warned that sync hasn't registered in more than a day
- I'm seeing an alert that the Object quota is exceeded.
- Microsoft defined a built-in object quota to help protect the directory synchronization service. If you have too many objects in your directory that need to sync to Microsoft 365, you have to Contact support for business products to increase your quota.
- I need to know which attributes are synchronized.
- You can find a list of all the attributes that are synced between on-premises and the cloud right here.
- I can't manage or remove objects that were synchronized to the cloud.
- Are you ready to manage objects in the cloud only? Or is there an object that was deleted on-premises, but is stuck in the cloud? Take a look at this Troubleshooting Errors during synchronization and support article for guidance on how to resolve these issues.
- I got an error message that my company exceeded the number of objects that can be synchronized.
- You can read more about this issue here.
Knowledge check
Choose the best response for the following question.