KB - MS001: How to Perform Soft Match or Hard Match for Hybrid Identity Sync Between Microsoft Entra ID and Multiple On-Premises Domain Controllers (DCs).

It is not as difficult as you would have imagined ^_-.

KB ID

MS001

Overview

Managing hybrid identities across multiple on-premises Domain Controllers (DCs) synced to a single Microsoft Entra ID can be challenging.

In a recent scenario, an object had to be moved between two separate on-premises DCs syncing to the same Microsoft Entra ID. This resulted in identity duplication, leading to conflicting passwords and policies, as the existing hybrid identity and the new on-premises object were treated as separate entities.

This guide provides a step-by-step walkthrough for seamlessly moving an on-premises object between two DCs while correctly linking the existing cloud hybrid identity to the new on-premises object using Soft Match or Hard Match techniques.

1. Goals

   • What is Hybrid Identity?
   • What is Soft Match and Hard Match?

2. UAT Scenario

3. Expected downtime for user

4. Prerequisites

5. Solution 1: Softmatch via UserPrincipalName

   • Step 1: Information Gathering (Microsoft Entra ID)
   • Step 2: Modify synchronisation setting for the respective Entra Connect Servers
   • Step 3: Move object1 to the unsynchronised OU in DC1 and DC2 respectively.
   • Step 4: Run first delta sync in DC1 and DC2 respectively
   • Step 5: Restore the deleted user [email protected] from Microsoft Entra ID and verify the current configuration.
   • Step 6: Remove [email protected]’s ImmutableID via MSOnline Powershell.
   • Step 7: Perform Soft Match
   • Step 8: Run second delta sync in DC1
   • Step 9: Verify that the user’s On-Premise ImmutableID and On-premise Domain Name is now changed.

6. Solution 2: Hardmatch by forcefully modifying the On-premise ImmutableID attribute to the correct one.

   • Step 1: Information Gathering (Microsoft Entra ID)
   • Step 2: Replace [email protected]’s ImmutableID from miLlmU1fMk2U8Mnd2lKzHg== to jWmHz8UnMkCgcoJF/Rl5Xw== via MSOnline Powershell.
   • Step 3: Run delta sync in DC1
   • Step 4: Verify that the user’s On-Premise ImmutableID and On-premise Domain Name is now changed.

7. Conclusion

8. Resources

Goals

You need to ensure that their on-premise AD account is linked correctly to the existing cloud hybrid identity using Soft Match or Hard Match techniques.

By doing so, we can preserve the data, role permission, audit logs etc. for the user in the cloud.

What is Hybrid Identity?

Hybrid identity enables users to access resources seamlessly across on-premises and cloud environments. It relies on synchronisation between Microsoft Entra ID (formerly Azure AD) and on-premises Active Directory (AD).

What is Soft Match and Hard Match?

• Soft Match: Matches objects based on the UserPrincipalName, Email, or the primary proxyAddress attribute.
• Hard Match: Matches objects by explicitly setting an immutableID (sourceAnchor) in Microsoft Entra ID to match the on-premises object.

UAT Scenario

Refer to the architecture diagram at the top of this page for additional details.

In this scenario:

• Object1 ([email protected]) is currently linked to Location 2 (represented by DC2) and exists as DC2\[email protected].

• Object1 needs to be moved to Location 1 (represented by DC1), where IT administrators have already created an AD account for it.

• As a result of this move, a duplicate entry is created in Microsoft Entra ID because Object1’s cloud identity (with Entra ObjectID aabbcc-aabbcc-aabbcc) remains linked to DC2 in Location 2.

• 

To preserve Object1’s data, role permissions, audit logs, and other configurations in the cloud, we need to link the existing cloud account to the newly created AD account in Location 1.

We will first attempt a Soft Match approach, as it is the simplest method. If Soft Matching does not work, we will proceed with a Hard Match to explicitly associate the cloud and on-premises objects.

Expected downtime for user.

1 Hour (Depends on how quickily IT Admins perform the steps)

Prerequisites

• Access to a x64 bit Windows 10/11 host and have local admin access (x32 bit, ARM devices are NOT supported.)
• Domain Admin access to the respective primary DCs.
• Local Admin access to the respective Entra Connect Servers
• Global Administrator OR Hybrid Identity Administrator and User Administrator
• Install MSOnline Powershell Module

Solution 1: Softmatch via UserPrincipalName

Step 1: Information Gathering (Microsoft Entra ID).

1a. Log in to the Microsoft Entra ID admin portal with your admin credentials.

1b. Navigate to Users > AllUsers blade and look for the 2 objects: [email protected] and [email protected]

1c: Navigate to each object, and under properties, record down the following (The value is editable, so you can edit it here and copy to your notes, this is client-side processsing, data is NOT sent to my server for processing).:

[email protected]

[email protected]

Step 2: Modify synchronisation setting for the respective Entra Connect Servers.

You will only need to perform this step if your Entra Connect Server is set to “Sync all domains and OUs” because you will need to move the user to an unsynced OU. Skip to Step 3: Move object1 to the unsynchronised OU in DC1 and DC2 respectively. if your Entra Connect Server is not under this setting.

2a: Remote to the respective Entra Connect Servers with your Adminstrator Account via rdp, bastion or https.

2b: Launch the Azure AD Connect application.

2c: Click “Configure”.

2d: Click “Customise synchronization options” and click “Next”.

2e: Enter your Microsoft Entra ID Admin credentials, login, and click “Next”.

2f: Leave all the settings as default and Click “Next” (No image here).

2g: Change the option from “Sync all domains and OUs” to “Sync selected domains and OUs” and untick the OU that you do not wish to synchronise.

2h: Leave all the settings as default and Click “Next” (No image here).

2i: Tick the option “start the synchronization process when configuration completes” and click “Configure”

2j: Click “Exit” - IMPORTANT

Step 3: Move object1 to the unsynchronised OU in DC1 and DC2 respectively.

3a. Just move them how you usually does (No image here)

Step 4: Run first delta sync in DC1 and DC2 respectively.

This deletes [email protected] and [email protected], flipping their “On-premises sync enabled” to “false”.

Launch Powershell as administrator, and run the following command.

Start-ADSyncSyncCycle -PolicyType Delta

The users, [email protected] and [email protected] are now DELETED in Microsft Entra ID

Step 5: Restore the deleted user [email protected] from Microsoft Entra ID and verify the current configuration.

5a. Log in to the Microsoft Entra ID admin portal with your admin credentials.

5b. Navigate to Users > DeletedUsers blade and restore the object [email protected].

5c: Once restored, navigate to [email protected], and under properties, ensure that it is the following (The value is editable, so you can edit it here and copy to your notes, this is client-side processsing, data is NOT sent to my server for processing).:

[email protected]

Step 6: Remove [email protected]’s ImmutableID via MSOnline Powershell.

6a. Run powershell as Administrator, and run the following:

Set-ExecutionPolicy bypass
Install-Module -Name MSOnline
Import-Module -Name MSOnline

6b. Connect to MSOLservice with your admin credetials.

connect-msolservice

6c. Run the following and remove the existing ImmutableID from [email protected].

Get-MsolUser -UserPrincipalName [email protected] | Set-MsolUser -ImmutableId "$null"

6d: Navigate to [email protected], and under properties, ensure that it is the following (The value is editable, so you can edit it here and copy to your notes, this is client-side processsing, data is NOT sent to my server for processing).:

[email protected]

Step 7: Perform Soft Match.

7a. Navigate to DC1\[email protected] object on your AD, and update its UPN, email, SMTP: address to match [email protected] on Microsoft Entra ID.

You may have a different attribute for synchronising UPN, for example, ExtensionAttribute. Update that accordingly.

Step 8: Run second delta sync in DC1.

This action will replace the ImmutableID to the current user in Location A and linking it to the right user.

Launch Powershell as administrator, and run the following command.

Start-ADSyncSyncCycle -PolicyType Delta

The users [email protected] is now synchronised with DC1 instead of DC2.

Step 9: Verify that the user’s On-Premise ImmutableID and On-premise Domain Name is now changed.

Please compare the table recprded in the previous step.

[email protected]

Solution 2: Hardmatch by forcefully modifying the On premise ImmutableID attribute to the correct one.

This is not recommended as forcefully matching may result in unexpected behaviours.

Step 1: Information Gathering (Microsoft Entra ID).

1a. Log in to the Microsoft Entra ID admin portal with your admin credentials.

1b. Navigate to Users > AllUsers blade and look for the 2 objects: [email protected] and [email protected]

1c: Navigate to each object, and under properties, record down the following (The value is editable, so you can edit it here and copy to your notes, this is client-side processsing, data is NOT sent to my server for processing).:

[email protected]

[email protected]

Step 2: Replace [email protected]’s ImmutableID from miLlmU1fMk2U8Mnd2lKzHg== to jWmHz8UnMkCgcoJF/Rl5Xw== via MSOnline Powershell.

2a. Run powershell as Administrator, and run the following:

Set-ExecutionPolicy bypass
Install-Module -Name MSOnline
Import-Module -Name MSOnline

2b. Connect to MSOLservice with your admin credetials.

connect-msolservice

2c. Run the following and remove the existing ImmutableID from [email protected].

Get-MsolUser -UserPrincipalName [email protected] | Set-MsolUser -ImmutableId "jWmHz8UnMkCgcoJF/Rl5Xw=="

2d: Navigate to [email protected], and under properties, ensure that it is the following (The value is editable, so you can edit it here and copy to your notes, this is client-side processsing, data is NOT sent to my server for processing).:

[email protected]

Step 3: Run delta sync in DC1.

This action will replace the rebase to the current user in Location A and linking it to the right user.

Launch Powershell as administrator, and run the following command.

Start-ADSyncSyncCycle -PolicyType Delta

The users [email protected] is now synchronised with DC1 instead of DC2.

Step 4: Verify that the user’s On-Premise ImmutableID and On-premise Domain Name is now changed.

Please compare the table recorded in the previous step.

[email protected]

Conclusion.

By carefully following the steps outlined above, you can successfully move an on-premises object between Domain Controllers while preserving its hybrid identity in Microsoft Entra ID. Choose Soft Match for non-intrusive updates or Hard Match for scenarios requiring explicit matching.

Resources.

• Microsoft Entra ID Documentation
• Azure AD Connect Troubleshooting Guide