Explained: User Hard Matching and Soft Matching in Azure AD Connect

Reading Time: 5 minutes

Azure AD Connect

In Hybrid Identity implementations, where objects and their attributes are synchronized between on-premises Active Directory environments and Azure AD tenants, integrity is key; When user objects on both sides have different attributes, or exist multiple times at one side, information security drops to critical levels fast.

To avoid this situation, Azure AD Connect matches user objects from the on-premises Active Directory to Azure AD.

Upon provisioning an object from on-premises Active Directory to Azure AD, Azure AD performs additional actions one time, when compared to updating a user object. These two action are named:

  1. Hard Matching
  2. Soft Matching

The actions are performed in the above sequence; Hard matching is attempted, before soft matching is attempted. If there’s no match, a new user object is created in Azure AD to correspond to the user object in the on-premises Active Directory environment.


Hard Matching

To definitively match an on-premises Active Directory user object to an Azure AD user object, Azure AD Connect looks at the source anchor attribute.

During normal synchronization cycles, this attribute is already used to provide the end-to-end connection between the on-premises Active Directory user object and the Azure AD user object through Azure AD Connect’s connector spaces and metaverse, so it’s an ideal way to match.

The Azure Active Directory Connect wizard, used to configure Azure AD Connect installations provides options to choose the source anchor attribute:

Azure AD Connect's Uniquely identifying your users page (click for original screenshot)

The above screenshot is a screenshot of a recent versions of Azure AD Connect. It provides the default option to Let Azure AD manage the source anchor and a list of available attributes to use as an alternative through the Choose a specific attribute option.

Let Azure AD manage the source anchor

When the Let Azure AD manage the source anchor option is selected, Azure AD Connect checks if there is a previous (older) Azure AD Connect installation connected to the Azure AD tenant. If there is, it will default to the objectGUID attribute . If this is the first Azure AD Connect installations, or all other Azure AD Connect installations have already been migrated to use mS-DS-ConsistencyGUID as the source anchor attribute for user objects, the mS-DS-ConsistencyGUID attribute is automatically selected as the source anchor attribute.

Choose a specific attribute

When you Choose a specific attribute it is important to choose an attribute that:

  1. Does not exceed 60 characters in length
  2. Does not contain special characters like \ ! # $ % & * + / = ?  and ^
  3. Is globally unique throughout your organization
  4. Is either a string, integer or binary

A good source anchor  attribute is not based on a person’s name, because this may change, however some organizations still choose to do so, based on the mail attribute…

The source anchor attribute chosen is stored in the configuration of the Azure AD tenant.

When upgrading or changing settings, Azure AD Connect reports that the Azure AD Connect installation for this tenant still uses objectGUID to synchronize user objects.

Hard matching occurs, based on the following data:

Azure AD Connect Hard Matching Table

An example for writing the immutableID attribute to an Azure AD object, based on an Active Directory user’s objectGUID attribute using Windows PowerShell is:

$user = jos.haarbos@domain.tld

$guid = [guid]((Get-ADUser -Identity "$user").objectGuid)

$immutableId = [System.Convert]::ToBase64String($guid.ToByteArray())


Set-AzureADUser -UserPrincipalName $user -ImmutableId $immutableID


When hard matching provides a match, soft matching is not attempted. However, the non-matching rules still apply.


Soft Matching

When hard matching doesn’t provide a match, soft matching is attempted. Soft matching is little more straight-forward than hard matching as it’s based on the following data:

Azure AD Connect Soft Matching Table

Through soft matching, an on-premises Active Directory user object is matched to an Azure AD user object, when:

  1. The userPrincipalName attributes match
  2. The userPrincipalName attribute for the on-premises user object matches with the e-mail address denoted with SMTP: in the proxyAddresses attribute of the Azure AD user object
  3. The primary SMTP address (denoted with SMTP: in the proxyAddresses attribute) matches the userPrincipalName of the Azure AD user object

When soft matching provides a match, hard matching is established at the first synchronization cycle by setting the immutableID attribute for the Azure AD user object, based on the source anchor configuration. This is done for disaster recovery purposes: When the (only) Azure AD Connect installation fails, a replacement Azure AD Connect installation can pick up synchronization for end users by accurate hard matching.



To avoid information security-related incidents, like the one pointed out by Dirk-Jan Mollema at Troopers 19, Azure AD Connect no longer attempts to hard match or soft match Active Directory user accounts to Azure AD-based user objects with privileged roles, like the Global Administrator role.



Now, the above explanation is straight-forward. There are a couple of caveats, though, that you should take into account:

  1. When you delete an object in Azure AD and then synchronize an object from on-premises to Azure AD within 30 days, hard matching and soft matching may not be triggered. Instead the previously deleted object is matched and reanimated. This is because the object was deleted, but not purged from the Azure AD Recycle Bin. Perform the following steps to get the result you want: Delete the object, purge the object, perform a sync cycle.
  2. In environments without existing Exchange Online-deployments, when you really don’t want an object in Azure AD to be matched with an on-premises AD object, assign the Azure AD object the tenant-specific userPrincipalName suffix (@*.onmicrosoft.com) and clear the immutableID attribute.
  3. When the Azure AD Connect installation fails and a replacement Azure AD Connect installation takes over, synchronized user objects in Active Directory matched to Azure AD privileged roles will not be matched. For this scenario:
    1. Make sure at least one non-synchronized Global Admin account exists with the @*.onmicrosoft.com userPrincipalName suffix
    2. Make sure you have Password Hash Synchronization (PHS) deployed



Hard matching is useful in both on-premises and cloud migration scenarios and to pinpoint a specific on-premises user object to an Azure AD object.

When things are slightly less difficult, soft matching provides the right amount of flexibility and speed to finish an Azure AD Connect implementation as part of a Hybrid Identity project within the allotted time.

Just remember you can’t synchronize admins anymore…

Further reading

Azure AD Connect: When you have an existent tenant
Soft (SMTP) vs. Hard (immutableID) matching with Azure AD Connect
How to use SMTP matching to match on-premises accounts to Office 365 accounts
Azure AD Connect soft- vs. hard matching explained

3 Responses to Explained: User Hard Matching and Soft Matching in Azure AD Connect


    Nice writeup, Sander!


    Soft matching also doesn't work if the Online user is member of a Role like Global admin


    Thanks so much. This is the only place I've seen mention that global admin role will stop the soft matching from happening. Seems even MS support techs don't know this.

leave your comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.