Identity synchronization and duplicate attribute resiliency
Duplicate Attribute Resiliency is a feature in Microsoft Entra ID that eliminates friction caused by UserPrincipalName and SMTP ProxyAddress conflicts when running one of Microsoft’s synchronization tools.
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.
The new behavior that this feature enables is in the cloud portion of the sync pipeline, therefore it's client agnostic and relevant for any Microsoft synchronization product including Microsoft Entra Connect, DirSync, and MIM + Connector. The generic term “sync client” is used in this document to represent any one of these products.
Current behavior
If there is an attempt 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. The sync client retries the provisioning attempt or update upon each export cycle, and it continues to fail until the conflict is resolved. An error report email is generated upon each attempt and an error is logged by the sync client.
Behavior with Duplicate Attribute Resiliency
Instead of completely failing to provision or update an object with a duplicate attribute, Microsoft Entra ID “quarantines” the duplicate attribute which would violate 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.
Upon quarantining the attribute, information about the conflict is sent in the same error report email used in the old behavior. However, this info only appears in the error report one time, when the quarantine happens, it doesn't continue to be logged in future emails. Also, since the export for this object is successful, the sync client doesn't log an error and doesn't retry the create / update operation upon subsequent sync cycles.
To support this behavior a new attribute is added to the User, Group, and Contact object classes:
DirSyncProvisioningErrors
This is a multi-valued attribute that is used to store 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 have been resolved, and automatically removes the attributes in question from quarantine.
Enabling Duplicate Attribute Resiliency
Duplicate Attribute Resiliency is the new default behavior across all Microsoft Entra tenants. It's on by default for all tenants that enabled synchronization for the first time on August 22nd, 2016 or later. Tenants that enabled sync before this date have the feature enabled in batches. This rollout began in September 2016, and an email notification is sent to each tenant's technical notification contact with the specific date when the feature is enabled.
Note
Once Duplicate Attribute Resiliency is turned on it cannot be disabled.
To check if the feature is enabled for your tenant, you can do so by downloading the latest version of the Azure Active Directory PowerShell module and running:
Get-MsolDirSyncFeatures -Feature DuplicateUPNResiliency
Get-MsolDirSyncFeatures -Feature DuplicateProxyAddressResiliency
Note
You can no longer use Set-MsolDirSyncFeature cmdlet to proactively enable the Duplicate Attribute Resiliency feature before it's turned on for your tenant. To be able to test the feature, you'll need to create a new Microsoft Entra tenant.
Note
Azure AD and MSOnline PowerShell modules are deprecated as of March 30, 2024. To learn more, read the deprecation update. After this date, support for these modules are limited to migration assistance to Microsoft Graph PowerShell SDK and security fixes. The deprecated modules will continue to function through March, 30 2025.
We recommend migrating to Microsoft Graph PowerShell to interact with Microsoft Entra ID (formerly Azure AD). For common migration questions, refer to the Migration FAQ. Note: Versions 1.0.x of MSOnline may experience disruption after June 30, 2024.
Identifying Objects with DirSyncProvisioningErrors
There are currently two methods to identify objects that have these errors due to duplicate property conflicts, Azure Active Directory PowerShell and the Microsoft 365 admin center. There are plans to extend to additional portal based reporting in the future.
Azure Active Directory PowerShell
For the PowerShell cmdlets in this topic, the following is true:
- All of the following cmdlets are case sensitive.
- The –ErrorCategory PropertyConflict must always be included. There are currently no other types of ErrorCategory, but this may be extended in the future.
First, get started by running Connect-MsolService and entering credentials for a tenant administrator.
Then, use the following cmdlets and operators to view errors in different ways:
- See All
- By Property Type
- By Conflicting Value
- Using a String Search
- Sorted
- In a Limited Quantity or All
See all
Once connected, to see a general list of attribute provisioning errors in the tenant run:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict
This produces a result like the following:
By property type
To see errors by property type, add the -PropertyName flag with the UserPrincipalName or ProxyAddresses argument:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyName UserPrincipalName
Or
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyName ProxyAddresses
By conflicting value
To see errors relating to a specific property add the -PropertyValue flag (-PropertyName must be used as well when adding this flag):
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -PropertyValue User@domain.com -PropertyName UserPrincipalName
Using a string search
To do a broad string search use the -SearchString flag. This can be used independently from all of the above flags, with the exception of -ErrorCategory PropertyConflict, which is always required:
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -SearchString User
In a limited quantity or all
- MaxResults <Int> can be used to limit the query to a specific number of values.
- All can be used to ensure all results are retrieved in the case that a large number of errors exists.
Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict -MaxResults 5
Microsoft 365 admin center
You can view directory synchronization errors in the Microsoft 365 admin center. The report in the Microsoft 365 admin center only displays User objects that have these errors. It doesn't show info about conflicts between Groups and Contacts.
For instructions on how to view directory synchronization errors in the Microsoft 365 admin center, see Identify directory synchronization errors in Microsoft 365.
Identity synchronization error report
When an object with a duplicate attribute conflict is handled with this new behavior, a notification is included in the standard Identity Synchronization Error Report email that is sent to the Technical Notification contact for the tenant. However, there is an important change in this behavior. In the past, information about a duplicate attribute conflict would be included in every subsequent error report until the conflict was resolved. With this new behavior, the error notification for a given conflict does only appear once- at the time the conflicting attribute is quarantined.
Here is an example of what the email notification looks like for a ProxyAddress conflict:
Resolving conflicts
Troubleshooting strategy and resolution tactics for these errors shouldn't differ from the way duplicate attribute errors were handled in the past. The only difference is that the timer task sweeps through the tenant on the service-side to automatically add the attribute in question to the proper object once the conflict is resolved.
The following article outlines various troubleshooting and resolution strategies: Duplicate or invalid attributes prevent directory synchronization in Office 365.
Known issues
None of these known issues causes data loss or service degradation. Several of them are aesthetic, others cause standard “pre-resiliency” duplicate attribute errors to be thrown instead of quarantining the conflict attribute, and another causes certain errors to require extra manual fix-up.
Core behavior:
Objects with specific attribute configurations continue to receive export errors as opposed to the duplicate attribute(s) being quarantined.
For example:a. New user is created in AD with a UPN of Joe@contoso.com and ProxyAddress smtp:Joe@contoso.com
b. The properties of this object conflict with an existing Group, where ProxyAddress is SMTP:Joe@contoso.com.
c. Upon export, a ProxyAddress conflict error is thrown instead of having the conflict attributes quarantined. The operation is retried upon each subsequent sync cycle, as it would have been before the resiliency feature was enabled.
If two Groups are created on-premises with the same SMTP address, one fails to provision on the first attempt with a standard duplicate ProxyAddress error. However, the duplicate value is properly quarantined upon the next sync cycle.
Office Portal Report:
The detailed error message for two objects in a UPN conflict set is the same. This indicates that they have both had their UPN changed / quarantined, when in fact only a one of them had any data changed.
The detailed error message for a UPN conflict shows the wrong displayName for a user whose UPN changed/quarantined. For example:
a. User A syncs up first with UPN = User@contoso.com.
b. User B is attempted to be synced up next with UPN = User@contoso.com.
c. User B’s UPN is changed to User1234@contoso.onmicrosoft.com and User@contoso.com is added to DirSyncProvisioningErrors.
d. The error message for User B should indicate that User A already has User@contoso.com as a UPN, but it shows User B’s own displayName.
Identity synchronization error report:
The link for steps on how to resolve this issue is incorrect:
It should point to https://aka.ms/duplicateattributeresiliency.