Dirsync soft matching vs hard matching

I recently was asked to advise on how cloud identities can be converted to federated identities such that when Azure AD Connect is run for the first time, the on-premises Active Directory takes over as the source of authority. The benefit of doing this is the user would have a single username and password, eliminating the need to have a different password for Office 365 when they already have one for Active Directory. This becomes complicated when an existing tenant exists and users have adopted various things like Teams. In my experience, a license bundle is assigned to the user which includes an Exchange Online license, which then creates a mailbox in the cloud, when the user already has one on-premises.

So how do we merge identities between Active Directory and Azure AD? In some cases, Azure AD will automatically match things (this is known as soft match).  However, when attributes do not line up then what ends up happening is a duplicate account gets created during the first synchronization. This is preventable through a technique known as hard matching, where we force the two objects to merge during the first synchronization.

Azure AD Connect will attempt a soft match if the primary email address attribute exists on both sides AND (the immutable ID matches the ObjectGUID on-premises OR the cloud immutableID is empty) <- see note below for an explanation why this matters. This is best documented on MS KB 2641663 and on Stephanie Kahlam’s blog (here).

However, what if the cloud identity is not enabled for Exchange Online? In that case, there is no primary address for a cloud identity to use for soft matching. For example, if the user was only configured for CRM Online or another O365 service. You could then make the UPN the same on both sides, Azure AD Connect will soft match on UPN too. This is explained in Microsoft documentation (here). This is performed in Windows Azure Powershell for Office 365 with this command:
Set-MsolUserPrincipalName -UserPrincipalName [email protected] -NewUserPrincipalName [email protected]

In scenarios where neither of those options work, then the only remaining option is to either blow away the cloud account or force the cloud account to use the same Immutable ID as the on-premises AD ObjectGUID (after it is converted into the proper format). This is known as a “hard match.”

In one case, I don’t know why, I had to make the UPN match on both sides, and the hard match too, otherwise I found a duplicate object was getting created in the cloud.

Hard Match “How TO”

To update the immutableID value of the Office365 object to match the on-prem ObjectGUID, you use the get-Aduser powershell command (this is installed on most Domain Controllers and can be installed on member servers). The format of the ObjectGUID must be converted to Base64. You can download the script I use to perform this (here).

Then once you get the ObjectGUID converted, you can run this in Azure AD PowerShell to perform the hard match:
install-module msonline
connect-msolservice
Set-MsolUser -UserPrincipalName [email protected] -ImmutableId RDHiRneDPkiofrZ2nbYu7Q==

Then force Azure AD Connect to run and that should convert the cloud identity to be sourced from on-premises Active Directory.

If the cloud identity ever pre-existed from a previous synced existence (for example, if prior to an ADMT migration, if the account originated from a separate AD forest than where the account exists presently) then soft match will never work – it will throw a bogus error about duplicate proxy addresses in the MIIS GUI. The only solution is to hard match by updating the cloud identity with the new on-prem ObjectGUID (following conversion from the steps above]

Another tip: if the account was being used heavily for Teams, SharePoint, OneDrive, PowerBI, or other cloud workloads, you may want to only remove the Exchange license, however, that still leaves the MailboxGUID from the account left on the object. The only way to clear that from the cloud user is to connect to Exchange Online PowerShell and run this command:

install-module exchangeonlinemanagement
connect-exchangeonline

Set-User [email protected]PermanentlyClearPreviousMailboxInfo