Setting Up AD Connect Without Creating Duplicate Users or Dirsync Errors

Almost every painful AD Connect problem, duplicate users, wrong logins, mailboxes that refuse to provision, is decided before the first sync runs. The fix is not troubleshooting after the fact; it is a disciplined pre-sync checklist around attributes, OUs, and whether the tenant already has users. Work through these six steps in order and the sync comes up clean.

1. Check prerequisites and compatibility first#

Before any configuration or planning, go over the prerequisites to see what limitations you are working with, or whether your environment is even compatible with AD Connect. For instance, Windows Server 2012 R2 Essentials is not compatible with the tool; if you try to install, you get an error saying your OS is not compatible. Always check the AD Connect prerequisites article (opens in new tab) first.

2. Add and verify your domain in Office 365#

You need a "verified" domain in Office 365 to complete the setup wizard. Go to Setup > Domains > Add Domain to add your domain to the portal and verify it with a TXT record.

3. Prepare the Active Directory environment#

This is where most of the prevention happens.

Make sure there is a routable domain#

In your local directory, go to Active Directory Domains and Trusts and add an alternative UPN if the listed domain is non-routable, such as .local or .lan. If you do not add an alternative UPN, all users populate in Office 365 with the .onmicrosoft.com domain. Follow the Microsoft article How to prepare a non-routable domain for directory synchronization (opens in new tab).

Audit user attributes in Active Directory#

By default, AD Connect uses the UPN attribute to map users to the cloud, so their AD UPN becomes their Office 365 login ID. Sometimes the formatting is wrong. For example, Jim Smith is listed in AD as j.smith for his UPN, but you want his login and primary SMTP to be jsmith@domain.com. You need to change the default attribute being synced.

If you do not want to use UPN as the default sync attribute, use custom settings in the AD Connect setup wizard. You can change the default attribute at the "Azure AD sign-in configuration" step. We prefer the "Mail" attribute in most cases when not using UPN.

Determine the OUs you will sync to the cloud#

In the setup wizard, you can drill into your directory and select specific OUs to sync. If your users are not already in one or two OUs, consolidate and clean this up before syncing. It is fine to have unlicensed users in Office 365, but the environment is far cleaner if you only sync the OUs you want in the cloud. Keep in mind that once the sync is in place, users cannot be deleted in the 365 portal; they have to be moved out of a synced OU or removed via PowerShell.

4. Account for an existing 365 tenant vs. net new#

If you are starting fresh in Office 365, there are fewer aspects of the sync to audit. If a tenant already has active users, do some prep work to avoid dirsync errors or duplicate users.

When you install Azure AD Connect and start synchronizing, the Azure AD sync service checks every new object and tries to find an existing match:

• Azure AD matches the incoming object using the sourceAnchor attribute to the immutableId attribute of objects in Azure AD. This is called a hard match.
• By default, if you already have users in 365, this will not match, so it falls back to the ProxyAddresses and UserPrincipalName attributes. This is called a soft match.
• The soft match is designed to match objects already present in Azure AD (sourced in Azure AD) with the new objects being added or updated during synchronization that represent the same entity (users, groups) on premises.
• If the soft match recognizes the same UPN or proxy address of a user, but that user has a different immutableID in Office 365 than in AD, the sync fails and that user is listed under "dirsync errors."

For this reason, use the "Mail" attribute again instead of the default UPN. You can also update your 365 users' ImmutableID to match the ObjectGUID in AD with the following cmdlets:

Connect-MSOLService
Set-MSOLUser -UserPrincipalName user@domain.com -ImmutableID (Insert ID from ObjectGUID attribute in AD)

5. Validate with staging mode or one test user#

Avoid syncing everyone at once only to discover wrong attributes or many dirsync errors. Always use staging mode or one test user before moving into full production.

Staging mode#

On the final page of the AD Connect setup wizard, you can select staging mode. In staging mode, you can make changes to the configuration and preview them before making the server active. This is useful to test synchronization without exporting any data to 365, and to remove certain attributes from the sync by editing them in the Synchronization Service Manager.

Using one test user#

Make the first sync with one test user who has a mailbox in your Exchange environment, to confirm they provision in 365 the way you want. Check:

• UPN
• Primary SMTP address
• Aliases
• Successful mailbox creation in Office 365

This shows whether all users will populate successfully with the correct attributes, error free. It is easy to remove that test user, either through PowerShell or by moving them out of a test OU, rather than your entire directory.

6. Set msExchMailboxGuid to NULL when it blocks mailboxes#

The deadly attribute#

In some environments, when you sync users to the cloud and license them, you get an error that prevents any user from getting a mailbox created in 365. This is tedious to fix. Follow the steps below to avoid it.

Run the Synchronization Rules Editor as an administrator#

Edit the inbound rule#

Click "In from AD - User Exchange" to edit the Inbound rule type.

Null out the attribute#

Select Transformations, find the msExchMailboxGuid attribute, and change it to the following:

Expression - msExchMailboxGuid - NULL - Checkmark Apply Once - Click on Update

Sync with test users#

Start the sync with test users and confirm each user's mailbox propagates without error.

Done in this order, the prep work front-loads every decision that would otherwise surface as a dirsync error or a duplicate account weeks later. The harder truth is that identity configuration does not stay put; attributes get edited, OUs get reorganized, and the sync that came up clean can drift, which is exactly the kind of slow reversion worth checking for on a schedule.