How To Hard Match Users In Entra Connect Sync

This article will detail the steps to manually hard match users using the newest Microsoft Graph PowerShell module, and also the deprecated MSOnline module.

Microsoft doesn’t details on how to manually hard match users in case soft matching fails via Entra connect sync (Azure AD connect). When you sync with Entra connect sync, it checks each new object with existing objects to find a match.

This match is done using the following three attributes.

• userPrincipalName
• proxyAddresses
• sourceAnchor/immutableID

What is a soft match ?

A matching done on the attributes userPrincipalName or proxyAddresses is called soft-match.

What is a hard match ?

A matching done based on sourceAnchor or immutableID is called hard match.

Reference: Sync with existing users in Microsoft Entra ID-Microsoft Entra ID | Microsoft Learn

Hard matching can only be done via PowerShell on cloud only users. If the user’s sync status in cloud is ‘synced’ or ‘on-premise provisioned’, you will get an error when attempting the hard match using the commands below.

What if my users are still showing ‘synced’ ?

The users can still show ‘synced’ even after you uninstall Entra connect sync as uninstalling simply won’t cut ties with Entra connect sync. While it may not be technically syncing, Entra will still think it is.

The only way to change the sync status is to disable directory synchronization.

Use the following the Microsoft Graph powerless cmdlets to disable the turn off Directory synchronization on your tenant.

  # Install v1.0 and beta Microsoft Graph PowerShell modules 
  Install-Module Microsoft.Graph -Force
  Install-Module Microsoft.Graph.Beta -AllowClobber -Force 
  
  # Connect With Hybrid Identity Administrator Account
  Connect-MgGraph -scopes "Organization.ReadWrite.All,Directory.ReadWrite.All" 
  
  # Verify the current status of the DirSync Type
  Get-MgOrganization | Select OnPremisesSyncEnabled 
  
  # Store the Tenant ID in a variable named organizationId
  $organizationId = (Get-MgOrganization).Id 
  
  # Store the False value for the DirSyncEnabled Attribute
  $params = @{
  	onPremisesSyncEnabled = $false
  }
  
  # Perform the update
  Update-MgOrganization -OrganizationId $organizationId -BodyParameter $params 
  
  # Check that the command worked
  Get-MgOrganization | Select OnPremisesSyncEnabled

Reference: Turn off directory synchronization for Microsoft 365

You cannot do the above for a single user.

Find the value of ImmutableID of the user in local Active Directory

To perform a hard-matching on users, you will have to get the new value for immutableID of the user that needs to be matched with cloud only user.

You can either get it from the error message you had related to synchronization or you will have to go to the user properties on local AD > Attribute editor > ObjectGUID, and then convert the ObjectGUID to immutableID.

Make sure to enable ‘Advanced features’ option to view the ‘Attribute editor’

Grab the objectGUID value highlighted below

We need to convert the ObjectGuid to ImmutableId. The easiest way to convert this is to use any online tool to convert GUID value to base 64 string. My favourite online tool is GUID Converter – Tool Slick. You may use any online website for this.

Go to the online tool.

Paste the Hexadecimal value (or any format value you get from the objectGUID field) and choose ‘Convert‘.

The base64 value output will the be the immutableID that we will be using for the hard-matching.

Steps to manually hard match users in local AD to Entra ID using Microsoft Graph Module

Step 1: Install the Microsoft Graph module for PowerShell. Refer here if you are having trouble with the module installation.

Install-Module Microsoft.Graph

Step 2: Connect to Entra ID using global admin accounnt with correct scopes and consent to the permissions required(if you have already consent to the MS Graph powershell modules permissions you may not see a new consent request).

Connect-MgGraph -Scopes "User.ReadWrite.All","Domain.ReadWrite.All", "Directory.AccessAsUser.All"

Step 3: View the value of user’s current immutableID or sourceAnchor in Entra ID.

Get-MgUser  -UserId <affected user object ID> -Property OnPremisesImmutableId,UserPrincipalName,Id | Format-List UserPrincipalName,OnPremisesImmutableId,ID

Step 4: Null the immutable of the user if it has any value currently. Any user that was synced at any point to Entra ID will have a value for On Premises ImmutableId.

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/Users/<objectID of the user>" -Body @{OnPremisesImmutableId = $null}

Step 5: Verify that the immutableID is set to nothing for the user.

Get-MgUser  -UserId <affected user's object ID> -Property OnPremisesImmutableId,UserPrincipalName,Id | Format-List UserPrincipalName,OnPremisesImmutableId,ID

Step 6: Get the immutableID of the local AD user (jump to the steps above), and assign it to the cloud only user.

Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/Users/<objectID of the user>" -Body @{OnPremisesImmutableId ="new immutableID"}

Steps to manually hard-match users in local AD to Entra ID using MSOnline module

You can follow the MSOnline PowerShell module steps to match users using immutableID manually. Please note that MSOnline PowerShell is deprecated as of March 30,2024 so it is recommended to follow the MS Graph Powershell steps. MSOnline versions 1.1.166.0 (2017) and later are assured to function through March 30, 2025. Refer: Deprecation of Azure AD PowerShell and MSOnline PowerShell modules

1. Firstly let’s install the module if you haven’t already.
   Install-module Msonline
2. Connect-MsolService (Use Entra ID global admin credentials) 
3. Check the immutable id of the affected user on cloud
   • Get-MsolUser -UserPrincipalName | select immutableID, objectID
4. If there is immutable id then make it null
   • Set-MSOLUser -UserPrincipalName -ImmutableID “”
5. Use ImmutableId of the user got from the step to convert the ObjectGUID to immutableID (jump to the steps above), and set it to the matching user on cloud.
   Set-MSOLUser-UserPrincipalName <UPN of the cloud user> -ImmutableID “<immutableID value from above step>”
6. We can verify the new immutableID of the user.
   Get-MsolUser -UserPrincipalName select immutableID, objectID