Soft (SMTP) vs. Hard (immutableID) matching with Azure AD Connect

June 8, 2017

Soft (SMTP) vs. Hard (immutableID) matching with Azure AD Connect

If you are setting up Directory Synchronization from scratch (there are no users in the cloud yet), then Azure AD Connect will be pretty straightforward–the on-premises objects (and passwords if you choose that option) will be synchronized to the cloud, and you can assign services to the user accounts from there.

But what if you already have user accounts in the cloud which correspond to already existing user objects in the on-premises directory, and Directory Synchronization has not yet been configured between them? For example, if your organization previously migrated mailboxes to Office 365 using the cutover method or a third party tool. Or, if you had users provisioned for another Microsoft Online Service such as CRM, before you attempted mailbox migration.

In cases like these, you may need to create a matching mechanism between the on-premises accounts and the cloud-based ones, so that Azure AD Connect knows that they refer to the same user. There are two basic methods to create this “matching”:

Soft match (also known as SMTP matching)
Hard match (by immutableID).

Soft Matching using the SMTP address

To create soft matches, which will be adequate in 95% of situations, you will need to ensure first of all that your UPN suffixes match between on-premises and cloud-based accounts. What do we mean by this? It means that your users’ sign-in needs to be tied to the domain of your primary email address in both the local AD and in Azure AD.

In the On-premises Active Directory

First, when you open the properties of a user account object, this object should have the email address field filled out (the primary SMTP address for the user)–so be sure that is the case first. Now take a look under the Account tab, and you should see the user logon name followed by a suffix.

The goal is to have this logon name be [email protected]–that is, the email address–and not the local domain name [email protected]. Note that you can also bulk-select accounts and make this suffix change on many objects at once.

If you do not have the option to drop down your suffix and choose the alternative, you can easily and quickly add the suffix using the Active Directory Domains & Trusts MMC console. Right-click Active Directory Domains and Trusts, and select Properties. Enter your email domain name and click Add. Click OK.

In the Azure AD / Office 365 cloud

In Office 365, you will also want to make sure the sign-in name is the same as on-premises, using the correct UPN suffix for the email domain name. So the goal is to have this match [email protected] again, and not [email protected].

In the Office 365 Portal, find your Active Users, select a user, then edit the username.

In Exchange Online, you can also see that the primary SMTP address matches what we have listed in the on-premises account. Admin Centers > Exchange > recipients. Edit a recipient and click email addresses.

You can also export bulk lists for comparison from Active Directory as follows:

Get-ADUser -SearchBase “DC=company,DC=local” -Filter * -Properties * | Select-Object -Property Name,SamAccountName,EmailAddress | Sort-Object -Property Name | Export-Csv -path C:\export\ADUsers.csv

And from Office 365:

Get-MsolUser | select-object -property userprincipalname,displayname,islicensed | export-csv -path c:\export\365Users.csv

Now, assuming you have your UPN and email addresses all matching, you should be able to download & install Azure AD Connect. Upon running the first synchronization, SMTP matching should kick in, and figure out that the on-premises accounts already have cloud counterparts existing. When you login to the portal and view your active users again, you should see a field describing the synchronization status, and each account from the on-premises directory should read “Synced with Active Directory.”

Hard Match using the GUID / immutableID

In some circumstances, soft matching may fail, and the on-premises accounts are not properly matched. Sometimes a previously existing cloud account can have certain fields populated already (e.g. immutableID) that will confuse the Directory Synchronization tool, even if the SMTP addresses are matching.

In these scenarios, you can turn to a “hard match,” which is performed by taking the on-premises GUID, then converting this value into what is known in the Azure AD cloud as an “immutableID,” and then writing that converted value directly into Azure AD. When Directory Synchronization runs, it will have no question marks about whether this is the same object, because it is being told so explicitly.

Before you proceed with this, you will still want to ensure that the UPN suffixes match the primary email domain on-premises and in the cloud, just as we did above. Then, when you have identified any accounts that failed to sync up, you can run the following for each affected account (be sure to fill in the variables appropriately):

$credential = Get-Credential
Connect-MsolService -Credential $credential
$ADUser = "username" 
$365User = "[email protected]"
$guid =(Get-ADUser $ADUser).Objectguid
$immutableID=[system.convert]::ToBase64String($guid.tobytearray())
Set-MsolUser -UserPrincipalName "$365User" -ImmutableId $immutableID

And of course, this can also be generalized for bulk changes, for example if you use the variables as fields in a CSV file, and import the CSV, with a for-each loop. You could even do this with a single variable in some cases:

Param(
$username
)
$365User="[email protected]"
$guid=(get-ADUser $username).Objectguid
$immutableID=[system.convert]::ToBase64String($guid.tobytearray())
Set-MsolUser -UserPrincipalName "$365User" -ImmutableId $immutableID

The above would be saved as HardMatch.ps1, then you can run the for-each loop as follows:

Connect-MsolService
Import-Csv -Path C:\scripts\users.csv | ForEach { C:\scripts\HardMatch.ps1 -Username $_.Username }

No more mis-matches. That should pretty much take care of everyone who is having trouble getting matches made with Directory Synchronization (I’ve been getting a fair number of inquiries lately). A shout-out to my co-worker Lionel who put this script together for us–nice work, dude!

Technical Active Directory, Azure AD, Azure AD Connect, DirSync 24 Comments

Soft (SMTP) vs. Hard (immutableID) matching with Azure AD Connect