Azure Active Directory Synchronization: Object Matching

Reading Time: 5 minutes

This post is the fifth in a series about Azure Active Directory Synchronization and will cover Object Matching. Other posts have covered and will cover:

Object Matching and Joining

Object matching or joining is relevant if you have multiple Active Directory (AD) forests you want to use for Directory Synchronization to Azure Active Directory (Azure AD). Previously with DirSync, it wasn't possible (or supported) to connect more than one AD Forest. With AADSync multiple source AD forests are supported and it comes with some new considerations.

It's important to know whether the objects from those forest are unique across every AD forest or whether there are in essence duplicate accounts, for instance if you have a resource forest.

If objects are unique across every connected forest, you can leave the defaults settings during the initial setup of AADSync. You can configure which attribute is used for matching objects from different AD Forests. When the values of those attributes are identical, AADSync will then join those objects and sync a combined object to Azure AD.

However, it is very possible that objects aren't entirely identical and have different values on some attributes. Attributes that are not configured ($null) will be overwritten by objects that have a value. So, consider Object1 and Object2 and their attribute Department. The value from Object1 is $null (i.e. empty) and the value from Object2 is "Sales". We match on the mail attribute which is identical, which means the objects will be joined before synchronizing to AD Azure. The joined objects attribute Department will have the value "Sales". (unless there are other rules with Transformation configured, see previous Filtering posts explaining this)

But consider the following: ObjectA and ObjectB have attribute telephoneNumber with a different value, resp. 5551234 and 0201234. What will happen?  This is dependent on how the Precedence value of the Synchronization Rules is set from each forest. Rules with a higher precedence are implemented later than lower valued rules. If the forest from ObjectA was added in AADSync first and the one from ObjectB was added later (because we consider the ObjectA forest our "main" forest), the synchronization rules from the first forest have a lower precedence value. This means that those values have precedence above values from the forest ObjectB. In this scenario the joined and synchronized object will have telephoneNumber value 5551234. See Figure 1 for a view of the ordering of Synchronization Rules when two AD forests are added (ForestA is marked black, ForestB is blue).

AADSync Rule Precendence Two Forest

Figure 1. Example of the Precedence ordering of default Inbound Synchronization Rules when two forests are added in AADSync. The black bar corresponds with ForestA and the blue bar corresponds with ForestB. ForestA was added first during initial configuration and ForestB was added later. The latter one has per similar rule a higher precedence. (Connectors are redacted due to privacy)

Configuring Object Matching

Object matching is configured during the initial (first) configuration of AADSync.

  1. Install AADSync from MicrosoftAzureADConnectionTool.exe.
  2. After initial install the Welcome screen appears. Choose Installation Path or leave default, Accept Terms and press Install.
  3. Connect to Azure AD by entering a valid account and press Next.
  4. Connect to AD DS by entering the AD forest FQDN and it's corresponding correct synchronization account and press Add Forest.
  5. We will not be adding another forest at this time. Press Next.
  6. Now we can finally configure Uniquely identify your Users. Choose Match Using and select the way you want to identify you users. In our example (see figure 2) we choose to match using the mail attribute. Press Next
  7. Configure Optional Features. Press Next.
  8. Now AADSync is ready to configure. Press Configure.
  9. After a while the configuration is finished and you could start the Synchronization. In this case we will have to add another AD forest, so turn of Synchronization Now and press Finish.
  10. Rerun the DirectorySyncTool and add additional AD Forests.
AADSync User Matching Mail Attribute

Figure 2. Uniquely identifying your users. In this screen the option matching using the mail attribute is selected. This means that when the mail attribute from objects of different AD forest is the same, the objects will be matched and joined so that only one object is synchronized to Azure AD.

Things to take into account

You can only configure Object Matching during the initial setup of AADSync and you cannot change this setting afterwards. This is because the Metaverse will be filled with objects and will not retroactively match objects. If you need a change in Object Matching, easiest way is to uninstall AADSync and remove any lingering related files, install again, configure Object Matching according to you required specification and then run Synchronization again (after all previous custom settings are set).

Figure 3. You cannot change user matching from forests after the initial configuration. Options are greyed out.

Figure 3. You cannot change user matching from forests after the initial configuration. Options are greyed out.

Also, when you configure AADsync during the initial configuration, it's best not to add all forest at once. Just add the primary AD Forest, configure Object Matching and finish the initial wizard. Do not sync. Rerun the configuration wizard and add one AD forest at a time, in order of importance. If you add all forests immediately at initial configuration, AADSync will add the forest in a possible unexpected and unwanted order as stated earlier in this post.

For every AD forest Synchronization Rules are created with a specific precedence number. However, the order is not predictable when adding forests in bulk, which could mean the order in which the Synchronization Rules are triggered might not be the one you require. When two objects that have to be joined, both have different attribute values (obviously not the attribute used to match the object) the value that wins is dependent on the precedence of join rules as described in the previous section.

As stated in the previous posts about Filtering, if you require filtering of matched/joined objects, you will have to resort to Outbound Filtering. This is because joining is performed in the Metaverse right after Inbound Filtering. If Inbound filtering is not adequate in filtering unwanted objects, Outbound Filtering can limit objects before syncing it to Azure AD. See Filtering, Part 2 of this series for a more extensive explanation.

Object matching with the cloud

After objects are provisioned in Azure AD, in default situations the matching identifier between the on-premises AD object and the Azure AD object, will be the ObjectGUID. This will be converted to a ImmutableID, which is in this case the Base64 encoded ObjectGUID. Joe Palarchio has a great blog post explaining the concept.

You certainly don't want to make an error with precedence rules and objects provisioned in O365 from the wrong forest. That will result in having cloud objects with an ImmutableID from the wrong forest. You would have fix how objects are joined in AADSync, however the objects will not match anymore. If you do have issues with non matching objects, check my previous blog post about how to fix most common DirSync mismatches.


You can have multiple AD Forest with non-unique objects configured in AADSync and let them join depending on equal values on a configurable attribute. However, this can only be configured during the initial configuration of AADSync. Changes after AADSync is configured are not possible, you will have to perform a complete uninstall and re-install of AADSync.

While configuring, first configure matching requirements and add only the main AD forest. After configuration has finished, restart the wizard and add one AD forest at a time. This insures that the precedence of Synchronization Rules will be predictable.

In some cases only Outbound Filtering can be used to limit the (joined) objects synchronized to Azure AD.

Next to matching and joining objects from AD forest, there is also matching from objects in Azure AD. The ImmutableID is the common factor between the object in AD and in AzureAD. Errors with your AADSync configuration could lead to mismatches that require manual fixing.

One comment

  • Joshua Bines

    Hey Dave,

    Thanks heaps for this!!

    So I take it that preference is also object based, ie if:

    Object A (Primary Forest) is a MailContact with telephoneNumber of 5551234
    Object B (Added Forest) is a User with telephoneNumber of 0201234

    In Azure AD we should have User with telephoneNumber of 0201234

    Sorry I missed you in mains this year hopefully I'll be around next year 🙂



Leave a Reply

Your email address will not be published. Required fields are marked *

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