UPN Matching for Office 365

This past month I was tasked with integrating an on premises Active Directory (AD) and Exchange environment with an existing Office 365 tenant.  The difference between this project and all of the others I’d previously performed is that the customer’s Office 365 tenant only had a subscription for Office 365 ProPlus and the default domain was being used for the Office 365 user names (username@domain.onmicrosoft.com).

The plan was to use the existing tenant, with the existing “cloud-only” users, for continuity and sync the AD users to Office 365 to transfer the source of authority to the local AD.  Luckily, there were only 60 or so cloud-only users out of a total of 300+ AD users.

The initial directory sync created a “duplicate” user for each of the existing cloud-only users.  This was anticipated but I probably could have done better with preparing the existing users in Office 365.  Unfortunately, at the beginning of the project, I was instructed not to change the existing Office 365 user names.

In an attempt to resolve, I added the domain used in Office 365 (domain.onmicrosoft.com) as a UPN suffix to the AD forest and updated each of the affected users in AD so their UPN was now username@domain.onmicrosoft.com.  However, the subsequent directory syncs stated that a user with that name already existed.

Then, I removed the affected users from the OU that was being synchronized and purged the AD-synced users from Office 365.  After, I moved the AD users back into the syncing OU however additional directory syncs stated that a user with that name already existed.  What?!

I found an article that ended up being the key to my plan for transferring the source of authority for the cloud-only users to the on premises AD.

How to use UPN matching for identity synchronization in Office 365, Azure, or Intune


As it turns out, which was contrary to my understanding, soft-matching (at least for UPNs) needs to be enabled.  The following command, run while connected to Office 365 via PowerShell, enables soft-matching for UPN for the tenant.

Set-MsolDirSyncFeature -Feature EnableSoftMatchOnUpn -Enable $True


Once this command was run, I was able to move the users from the synchronized OU, purge any “duplicate” users in Office 365, confirm the AD users’ UPN is set to username@domain.onmicrosoft.com, move the users back to the synchronized OU, and lastly force a sync to Office 365.

The last sync allowed the soft-match of the UPNs to successfully transfer the source of authority from cloud to on premises.  This left us with one synced Office 365 account for every AD user.

Finally, I made the last change to the UPN suffix for each AD user (username@domain.com) to complete the task of marrying the AD user to the existing Office 365 users.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s