Directory synchronization basics
- 2/21/2018
- Directory structure
- Data uniqueness
- Understanding directory synchronization
Data uniqueness
Unlike on-premises Active Directory, where it’s possible (but not recommended) to have objects with the same value populated for attributes that should be unique across your directory, Azure does not allow this. In fact, this is the most common type of error encountered when syncing objects to Azure and can be the most challenging to resolve.
The two most common types of attribute value conflict are UserPrincipalName and ProxyAddresses.
UserPrincipalName
The UserPrincipalName attribute, because it is used for authentication with Azure AD, must be unique for every object in your enterprise. Unlike the SamAccountName value, which is used for authentication to on-premises Active Directory and therefore must be unique for logon to Active Directory, the UserPrincipalName value is used for authentication to Azure AD and therefore must be unique in Azure. The SamAccountName value, for all practical purposes, is ignored.
When an object is synchronized to Azure AD, the UserPrincipalName value is checked for uniqueness and, in the event of duplication with an existing object, special action is taken to transform that value. More information about this transformation process follows in the chapter; however, note that because UserPrincipalName is used for authentication with Azure AD, this transformation process renders the account unusable until the conflict is resolved.
Proxy addresses
Mail flow depends on proxy addresses, and just like the UserPrincipalName value, it is possible to have duplicate proxy addresses between objects in an on-premises Active Directory forest. Most commonly, proxy address conflicts appear during the initial synchronization implementation, but it is not uncommon for them to occur during the normal day-to-day administration of on-premises Exchange.
Like UserPrincipalName, when value duplication occurs between objects, Azure takes steps to remediate the duplication by using Duplicate Attribute Resiliency, as discussed in the following sidebar.
Duplicate attribute resiliency
Duplication of attribute values in the synchronization to Azure AD and the subsequent effort involved in the remediation of these scenarios has been a long-time issue in the synchronization of objects to Office 365. To help alleviate this problem, Microsoft introduced a feature in September 2016, Duplicate Attribute Resiliency.
Duplicate Attribute Resiliency operates in Azure AD, independent of the synchronization engine version, and is enabled by default on all new tenants. In fact, since its release, the feature has been enabled on all Office 365 tenants worldwide, and due to its success in remediation of sync issues, it is no longer a feature that you can turn off.
Previously, if an administrator tried to synchronize a user with a duplicate UserPrincipalName or duplicate proxy address when synchronizing users, groups, or contacts to Azure AD, the synchronization would fail, generate an error in the synchronization engine, and continue to retry the export of the object on every subsequent synchronization cycle.
This backlog of synchronization errors would increase each subsequent synchronization cycle’s duration and potentially slow down the export of on-premises Active Directory changes to Azure AD. Now, however, the tenant flags those conflict scenarios, an automated email report is sent to the tenant administrator from Office 365, and the object export is marked as successful.
Duplicate proxy addresses
If a user with a duplicate email address is synchronized to Office 365, the duplicated proxy address value is simply removed from the object being synchronized and placed in a quarantined state. The value remains in this state indefinitely until the conflict is resolved manually, or the offending address is removed from the object.
When Duplicate Attribute Resiliency is triggered for a proxy address conflict, a technical notification email is sent to the tenant administrator as part of the regularly scheduled export cycle, which contains a list of all errors that occurred during that synchronization cycle.
In Figure 4-2, UserPrincipalName identifies the user with the conflict, and the details of the conflict appear. In this example, another object already uses the finance@cohovineyard.us email address.
)
Figure 4-2 Email notification for duplicate proxy
Although the object has been successfully synchronized to Azure AD, and the offending proxy address conflict quarantined, you cannot assign an Exchange Online license to the user because of the quarantined value. Attempting to assign a license results in an error stating that the object currently has a uniqueness violation, as shown in Figure 4-3.
)
Figure 4-3 Attempt to license a user with a proxy address conflict
In this case, you can assign all the licenses beneath the SKU in question, except the Exchange Online license, until the proxy address conflict is resolved.
Duplicate UserPrincipalName
When a duplicate UserPrincipalName value is synchronized to Azure AD, Azure automatically quarantines the duplicate UserPrincipalName value, as it does for proxy addresses, and the resulting UserPrincipalName prefix for the user becomes the desired prefix, followed by a random four-digit number, and the suffix is replaced with @tenant.onmicrosoft.com, as shown in Figure 4-4.
Items remain in this state until they are manually remediated, and because the UserPrincipalName is used for authentication, this account remains unusable until the conflict is resolved.
)
Figure 4-4 Email notification for duplicate UserPrincipalName
Technical notification
Both UserPrincipalName and proxy address conflicts result in an email to the technical contact for your Office 365 tenant. Typically, this recipient is identified during tenant setup as the person who created the Office 365 subscription.
After you have successfully set up your tenant and before you have started synchronizing, review the technical notification setting and ensure that the email address is valid. Furthermore, it is typically recommended for the technical notification email setting to be configured to use the email address associated with a distribution list in your on-premises Exchange organization so that more than one administrator receives the notification emails from the synchronization process.
The technical notification email can be configured in the Office 365 Admin Center portal by selecting the company name (such as CohoVineyard) in the upper right corner of the main admin console page, as shown in Figure 4-5.
)
Figure 4-5 Selecting the company name to configure technical notification
This enables you to edit the organization profile for your Office 365 subscription, which includes the Technical Contact email address along with other settings such as Office 365 software release preferences, themes, and tile customizations.
If you prefer not to use the Office 365 portal to set the Technical Notification email preferences, they can also be updated by using Windows PowerShell.
The Get-MsolCompanyInformation command displays the current TechnicalNotificationEmails setting, which is a list of email addresses that receive service notifications and synchronization reports from the tenant.
You can use the Set-MsolCompanyContactInformation -TechnicalNotificationEmails command followed by a comma-separated list of email addresses that you wish to receive the updates, as shown in Figure 4-6.
)
Figure 4-6 Using Windows PowerShell to set the technical notification contacts
Locating objects with errors
After you have successfully configured the company information in your tenant, and you have started receiving technical notification email as part of the ongoing synchronization process, you can now use both the Office 365 Admin Center portal and Windows PowerShell to review the errors present in your tenant.
This chapter discusses how to remediate different types of errors later, but it’s important to understand where those errors can be located so that you don’t need to rely on keeping all the notification emails you receive from the tenant.
Locating error objects in the Office 365 Admin Center portal
Locating objects in an error state in the Office 365 Admin Center portal is a simple matter of logging on to Office 365 and selecting Users on the main admin page.
In the Views drop-down list at the top of the page, you can then select Users With Errors, as shown in Figure 4-7.
)
Figure 4-7 Filtering by Users With Errors
From the previous examples, you should be able to distinguish users with proxy address conflicts from those with UserPrincipalName conflicts.
Although the Office 365 Admin Center portal enables you to view the objects with errors, very little additional information appears when filtering for errors in the Users view. In fact, even selecting each user individually does not provide the root cause of the error.
To reveal the cause of the error, look at the identity synchronization error report that you received by email when the error occurred, use the DirSync Status Summary page, or use Windows PowerShell.
Locating error objects by using the DirSync Status Summary page
Although the Users view in the Office 365 Admin Center portal provides limited information by using a filter view about the objects with synchronization errors, it is not the ideal method for viewing error objects. Instead, you can use the Office 365 Admin Center portal DirSync status card on the admin center Home page, shown in Figure 4-8, to drill down into individual synchronization errors.
)
Figure 4-8 The Office 365 Admin Center DirSync Status card
Clicking DirSync errors displays a page listing each of the error objects along with the provisioning error for that object. You can then click each object and see the specific object error information you can use to remediate the error.
As shown in Figure 4-9, Azure AD detected a conflict in the finance@cohovineyard.us proxy address value; the dialog box displays both objects that were configured with that proxy address and the object whose conflicting value was removed, in this case, the second object to be synchronized to Azure AD with this value.
)
Figure 4-9 Office 365 Admin Center portal proxy address conflict report
Locating error objects by using Windows PowerShell
When locating conflict errors in Azure AD by using Windows PowerShell, you can use a special error category called PropertyConflict when viewing objects. This special error category aligns with the Duplicate Attribute Resiliency feature.
To view all users with a property conflict, you can use the Get-MsolDirSyncProvisioningError -ErrorCategory PropertyConflict command.
As shown in Figure 4-10, this command returns the same four objects viewed in the Office 365 Admin Center portal.
)
Figure 4-10 Using Windows PowerShell to view objects with provisioning errors
Two objects have provisioning errors on UserPrincipalName, and two have provisioning errors on ProxyAddresses.
If you prefer to sort objects based on the provisioning error type, you can use the Get-MsolDirSyncProvisioningError -ErrorCategory propertyconflict -PropertyName UserPrincipalName command to display only the UserPrincipalName errors, or PropertyName ProxyAddresses to display proxy address conflicts.
Summing up data uniqueness
A variety of methods are available for viewing provisioning and synchronization errors in your tenant. Each method provides certain conveniences when compared to the others.
For example, if you only have a few errors, you can easily navigate the portal, selecting each object in turn and identifying the root cause. When you have a larger number of errors, you can use Windows PowerShell to export a sorted list by provisioning error type to a comma-separated value (CSV) file that you can use to generate a detailed report.
In either case, understand how to access error details in the portal, and the root cause for some of the most common synchronization errors.
This chapter discusses more about detailed error tracking and remediation later; for now, it’s important to understand how the synchronization engine, AAD Connect, handles the synchronization of each object type and its underlying properties.