Microsoft Entra Connect User Matching: Soft Match vs Hard Match Explained

In a Microsoft hybrid identity environment, keeping your on-premises Active Directory (AD) users in sync with Microsoft Entra ID (formerly Azure AD) is critical. But what happens when you already have cloud-only users and you need to link them to on-premises accounts — without deleting them and losing their data?

That’s where Soft Match and Hard Match come in. These are the two matching methods that Microsoft Entra Connect (formerly Azure AD Connect) uses to determine which on-premises user maps to which cloud user.

In this comprehensive guide, you’ll learn:

• What Soft Match and Hard Match are and how they work
• When to use each method
• Step-by-step PowerShell commands for both methods
• Common errors and how to troubleshoot them
• A detailed FAQ section

🔑 What Is User Matching in Entra Connect?

When you set up Microsoft Entra Connect and start synchronising on-premises AD users with Entra ID, the sync engine checks every incoming object and tries to find a matching existing object in the cloud. It uses three attributes for this process:

If a match is found, Entra Connect takes over the cloud-only object and converts it to an on-premises managed (synced) object. All attributes in Entra ID with a value in on-premises AD are overwritten with the on-premises values.

⬆ Back to Table of Contents

✅ What Is Soft Match?

Soft Match (also called SMTP Match) is the automatic matching process where Entra Connect links an on-premises AD user to an existing cloud user by comparing common identity attributes — primarily the primary SMTP address and userPrincipalName (UPN).

How Soft Match Works

When Entra Connect processes a new on-premises user object for the first time, it checks:

1. proxyAddresses — Specifically the primary SMTP address (prefixed with uppercase SMTP:)
2. userPrincipalName — The user’s logon name (e.g., user@contoso.com)

If the cloud user has the same primary SMTP address or UPN as the incoming on-premises user, Entra Connect automatically links (soft matches) them.

Attributes Required for Soft Match

⬆ Back to Table of Contents

🔒 What Is Hard Match?

Hard Match (also called ImmutableID Match) is a deterministic matching process that links an on-premises AD user to a cloud user using a unique identifier called the ImmutableID (also known as sourceAnchor).

How Hard Match Works

Every on-premises AD user has a unique attribute called ObjectGUID. When Entra Connect syncs a user for the first time, it converts this ObjectGUID to a Base64-encoded string and stamps it as the ImmutableID on the cloud object. This creates a permanent, unbreakable link between the two accounts.

For a hard match, you manually set the ImmutableID on the cloud user to match the on-premises user’s ObjectGUID (or ms-DS-ConsistencyGuid, depending on your Entra Connect configuration).

Key Attributes for Hard Match

⬆ Back to Table of Contents

⚖️ Soft Match vs Hard Match – Comparison

⬆ Back to Table of Contents

📋 When to Use Soft Match vs Hard Match

Use Soft Match When:

• You have cloud-only users created in Microsoft 365 before setting up Entra Connect
• The UPN and primary SMTP address already match between on-prem and cloud
• You’re doing a bulk migration of many users and want to minimise manual effort
• Users do not have admin roles assigned in Entra ID

Use Hard Match When:

• Soft match has failed — attributes don’t align or there are conflicts
• A previously synced user has become disconnected (e.g., account was soft-deleted and restored)
• You need to force-link a specific cloud account to a specific on-prem account
• You’re performing a tenant migration or domain consolidation
• The cloud user has admin roles assigned (soft match is blocked for privileged accounts)
• You’re recovering from a sync disaster or rebuilding the Entra Connect server

⬆ Back to Table of Contents

🛠️ How to Perform a Soft Match – Step-by-Step

Prerequisites

• Microsoft Entra Connect installed and configured
• On-premises AD user account created (or existing)
• Cloud-only user exists in Entra ID / Microsoft 365
• Access to Active Directory Users and Computers (ADUC)
• Exchange Online PowerShell (optional, for verifying SMTP addresses)

Step 1: Check the Cloud User’s Details

First, confirm the cloud user’s UPN and primary SMTP address.

Using Microsoft Graph PowerShell:

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read.All"

# Get the cloud user's UPN and proxy addresses
Get-MgUser -UserId "user@contoso.com" -Property UserPrincipalName, ProxyAddresses, Mail | 
    Select-Object UserPrincipalName, Mail, @{N='ProxyAddresses';E={$_.ProxyAddresses -join '; '}}

Using Exchange Online PowerShell:

# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName admin@contoso.com

# Get the user's email addresses
Get-Mailbox -Identity "user@contoso.com" | 
    Select-Object DisplayName, UserPrincipalName, PrimarySmtpAddress, @{N='EmailAddresses';E={$_.EmailAddresses -join '; '}}

Step 2: Configure the On-Premises AD User

Ensure the following three attributes on the on-prem AD user match the cloud user exactly:

2a. Set the UserPrincipalName (UPN)

# Set the UPN to match the cloud user
Set-ADUser -Identity "username" -UserPrincipalName "user@contoso.com"

2b. Set the Email Address

# Set the mail attribute
Set-ADUser -Identity "username" -EmailAddress "user@contoso.com"

2c. Set the ProxyAddresses

# Set the primary SMTP proxy address (note: uppercase SMTP for primary)
Set-ADUser -Identity "username" -Add @{proxyAddresses = "SMTP:user@contoso.com"}

# Verify the proxy addresses
Get-ADUser -Identity "username" -Properties proxyAddresses | Select-Object -ExpandProperty proxyAddresses

Step 3: Force an Entra Connect Delta Sync

# Run this on the Entra Connect server
Start-ADSyncSyncCycle -PolicyType Delta

Step 4: Verify the Sync Status

Check in Synchronisation Service Manager:

Open the Synchronisation Service Manager on the Entra Connect server. Look at the Export operation for your Entra ID connector. Check for Adds or Updates — the user should appear as an update (not an add) if the soft match succeeded.

Check in Microsoft 365 Admin Centre:

Navigate to Users > Active Users. The user’s sync status should now show “Synced from on-premises” instead of “In cloud”.

Verify with PowerShell:

# Check if the user is now synced
Get-MgUser -UserId "user@contoso.com" -Property OnPremisesSyncEnabled, OnPremisesImmutableId | 
    Select-Object UserPrincipalName, OnPremisesSyncEnabled, OnPremisesImmutableId

If OnPremisesSyncEnabled is True and OnPremisesImmutableId has a value, the soft match was successful.

⬆ Back to Table of Contents

🔧 How to Perform a Hard Match – Step-by-Step

Prerequisites

• Microsoft Entra Connect installed and configured
• On-premises AD user account created (place it in a non-syncing OU initially to avoid duplicates)
• Cloud-only user exists in Entra ID
• Microsoft.Graph PowerShell module installed (or legacy MSOnline module)
• ActiveDirectory PowerShell module installed

Step 1: Get the On-Premises User’s ObjectGUID

# Run this on a Domain Controller or machine with RSAT tools
Import-Module ActiveDirectory

# Get the ObjectGUID
$User = Get-ADUser -Identity "username"
$ObjectGUID = $User.ObjectGUID
Write-Host "ObjectGUID: $ObjectGUID"

Step 2: Convert ObjectGUID to Base64 (ImmutableID)

# Convert ObjectGUID to Base64 string
$ImmutableID = [System.Convert]::ToBase64String($ObjectGUID.ToByteArray())
Write-Host "ImmutableID (Base64): $ImmutableID"

# Example output: "xMf1FXx9RIcbcAbDlqeOA=="

# For ms-DS-ConsistencyGuid source anchor
$User = Get-ADUser -Identity "username" -Properties "ms-DS-ConsistencyGuid"
$ConsistencyGuid = $User.'ms-DS-ConsistencyGuid'

if ($ConsistencyGuid) {
    $ImmutableID = [System.Convert]::ToBase64String($ConsistencyGuid)
} else {
    # Fall back to ObjectGUID if ConsistencyGuid is not yet populated
    $ImmutableID = [System.Convert]::ToBase64String($User.ObjectGUID.ToByteArray())
}

Write-Host "ImmutableID: $ImmutableID"

Step 3: Set the ImmutableID on the Cloud User

Method A: Using Microsoft Graph PowerShell (Recommended)

# Install Microsoft Graph module (if not already installed)
Install-Module Microsoft.Graph -Scope CurrentUser -Force

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.ReadWrite.All"

# Set the ImmutableID on the cloud user
Update-MgUser -UserId "user@contoso.com" -OnPremisesImmutableId $ImmutableID

# Verify it was set
Get-MgUser -UserId "user@contoso.com" -Property OnPremisesImmutableId | 
    Select-Object UserPrincipalName, OnPremisesImmutableId

Method B: Using MSOnline PowerShell (Legacy — Being Retired)

# Connect to MSOnline
Connect-MsolService

# Set the ImmutableID
Set-MsolUser -UserPrincipalName "user@contoso.com" -ImmutableId $ImmutableID

# Verify
Get-MsolUser -UserPrincipalName "user@contoso.com" | Select-Object UserPrincipalName, ImmutableId

Step 4: Move the User to a Syncing OU (If Applicable)

If you created the on-prem user in a non-syncing OU to avoid duplicates, move them now to a synced OU.

# Move user to the synced OU
Move-ADObject -Identity $User.DistinguishedName -TargetPath "OU=Users,OU=Corp,DC=contoso,DC=com"

Step 5: Force an Entra Connect Delta Sync

# Run on the Entra Connect server
Start-ADSyncSyncCycle -PolicyType Delta

Step 6: Verify the Hard Match

# Check if the user is now synced
Get-MgUser -UserId "user@contoso.com" -Property OnPremisesSyncEnabled, OnPremisesImmutableId, DisplayName |
    Select-Object DisplayName, UserPrincipalName, OnPremisesSyncEnabled, OnPremisesImmutableId

If OnPremisesSyncEnabled is True, the hard match was successful. The cloud user is now linked to the on-premises AD account.

⬆ Back to Table of Contents

📦 Bulk Hard Match Using CSV – PowerShell Script

If you need to hard match multiple users at once, here’s a bulk approach using a CSV file.

CSV Format (users-to-hardmatch.csv)

SamAccountName,CloudUPN
jsmith,john.smith@contoso.com
jdoe,jane.doe@contoso.com
bwilson,bob.wilson@contoso.com

Bulk Hard Match Script

# ============================================================
# Bulk Hard Match Script - AD to Entra ID
# Author: core365.cloud
# ============================================================

# Import required modules
Import-Module ActiveDirectory
Import-Module Microsoft.Graph.Users

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.ReadWrite.All"

# Import CSV
$Users = Import-Csv -Path "C:\Scripts\users-to-hardmatch.csv"

# Process each user
foreach ($User in $Users) {
    try {
        # Get on-prem AD user ObjectGUID
        $ADUser = Get-ADUser -Identity $User.SamAccountName
        $ImmutableID = [System.Convert]::ToBase64String($ADUser.ObjectGUID.ToByteArray())

        # Set ImmutableID on cloud user
        Update-MgUser -UserId $User.CloudUPN -OnPremisesImmutableId $ImmutableID

        Write-Host "[SUCCESS] $($User.CloudUPN) - ImmutableID set to: $ImmutableID" -ForegroundColor Green
    }
    catch {
        Write-Host "[ERROR] $($User.CloudUPN) - $($_.Exception.Message)" -ForegroundColor Red
    }
}

# Trigger delta sync (run on Entra Connect server)
Write-Host "`nNow run this on the Entra Connect server:" -ForegroundColor Yellow
Write-Host "Start-ADSyncSyncCycle -PolicyType Delta" -ForegroundColor Cyan

⬆ Back to Table of Contents

📧 Verifying Addresses with Exchange Online PowerShell

Before attempting either match, it’s crucial to verify the email addresses on both sides. Here are useful Exchange Online commands:

# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName admin@contoso.com

# Get all email addresses for a specific user
Get-Mailbox -Identity "user@contoso.com" | Format-List DisplayName, PrimarySmtpAddress, EmailAddresses

# Check if a specific SMTP address is already in use (to avoid conflicts)
Get-Mailbox -Filter "EmailAddresses -eq 'SMTP:user@contoso.com'"

# Get recipient details (works for mailboxes, groups, contacts)
Get-Recipient -Identity "user@contoso.com" | Select-Object DisplayName, RecipientType, PrimarySmtpAddress

# Check for duplicate proxy addresses across all recipients
Get-Recipient -ResultSize Unlimited | 
    Where-Object { $_.EmailAddresses -like "*user@contoso.com*" } | 
    Select-Object DisplayName, RecipientType, PrimarySmtpAddress

# Disconnect when done
Disconnect-ExchangeOnline -Confirm:$false

⬆ Back to Table of Contents

🔄 How to Clear an ImmutableID (Unlinking a User)

Sometimes you need to clear the ImmutableID to unlink a cloud user from on-premises — for example, when converting a synced user back to cloud-only.

# Using Microsoft Graph PowerShell
Connect-MgGraph -Scopes "User.ReadWrite.All"

# Clear the ImmutableID (set to null)
Update-MgUser -UserId "user@contoso.com" -OnPremisesImmutableId ""

# Verify it's cleared
Get-MgUser -UserId "user@contoso.com" -Property OnPremisesImmutableId | 
    Select-Object UserPrincipalName, OnPremisesImmutableId

# Using MSOnline (Legacy)
Set-MsolUser -UserPrincipalName "user@contoso.com" -ImmutableId "$null"

⬆ Back to Table of Contents

❌ Common Errors and How to Troubleshoot Them

Error 1: InvalidSoftMatch

Cause: Another object (user, group, or contact) already has the same primary SMTP address or UPN.

Fix:

1. Identify the conflicting object using Exchange Online PowerShell:

   Get-Recipient -Filter "EmailAddresses -eq 'SMTP:user@contoso.com'" | 
       Select-Object DisplayName, RecipientType, PrimarySmtpAddress
   

2. Remove the duplicate address from the conflicting object or delete the conflicting object.
3. Re-run a delta sync: Start-ADSyncSyncCycle -PolicyType Delta

Error 2: InvalidHardMatch

Cause:

• Another cloud user already has the same ImmutableID set.
• The BlockCloudObjectTakeoverThroughHardMatchEnabled feature is enabled on the tenant.
• The cloud user has privileged admin roles assigned.

Fix:

1. Check if another user already has the same ImmutableID:

   Get-MgUser -All -Property OnPremisesImmutableId | 
       Where-Object { $_.OnPremisesImmutableId -eq $ImmutableID } | 
       Select-Object DisplayName, UserPrincipalName, OnPremisesImmutableId
   

2. If the cloud user has admin roles, temporarily remove them, perform the hard match, then re-assign the roles.
3. Check the hard match block feature:

   Connect-MgGraph -Scopes "OnPremDirectorySynchronization.Read.All"
   $OnPremSync = Get-MgDirectoryOnPremiseSynchronization
   $OnPremSync.Features | Format-List BlockCloudObjectTakeoverThroughHardMatchEnabled
   

Error 3: ObjectTypeMismatch

Cause: You’re trying to match a User with a Contact or Group, or vice versa. The object types must match.

Fix:

1. Delete the conflicting contact or mail-enabled object in Exchange Online:

   # Check the recipient type
   Get-Recipient -Identity "user@contoso.com" | Select-Object RecipientType
   
   # If it's a MailContact, remove it
   Remove-MailContact -Identity "user@contoso.com" -Confirm:$false
   

2. Wait for the deletion to replicate (or wait for the next sync cycle).
3. Re-run the sync.

Error 4: Identity Synchronisation Error — Orphaned Object

Cause: A previously synced user was deleted from on-prem AD but still exists in Entra ID’s recycle bin (soft-deleted state), and a new user with the same SMTP address is trying to sync.

Fix:

1. Find and permanently delete the soft-deleted user:

   # List deleted users
   Get-MgDirectoryDeletedItemAsUser -All | 
       Where-Object { $_.ProxyAddresses -like "*user@contoso.com*" } | 
       Select-Object DisplayName, UserPrincipalName, Id
   
   # Permanently delete the orphaned user
   Remove-MgDirectoryDeletedItem -DirectoryObjectId "object-id-here"
   

2. Wait a few minutes, then re-run a delta sync.

Error 5: Admin Role Blocking Soft Match

Cause: Entra ID will not soft match on-premises users with cloud users that have an admin role (e.g., Global Admin, Exchange Admin). This is a security measure to prevent accidental takeover of privileged accounts.

Fix:

1. Remove the directory roles from the cloud user.
2. Hard-delete any quarantined duplicate object in the cloud.
3. Perform a hard match instead (set the ImmutableID manually).
4. Trigger a sync cycle.
5. Re-assign the admin roles after the match is confirmed.

Error 6: FederatedDomainChangeError

Cause: The user’s UPN domain is federated, and the ImmutableID change conflicts with federation settings.

Fix:

1. Temporarily convert the domain from federated to managed.
2. Perform the hard match.
3. Convert the domain back to federated.
4. Alternatively, use a non-federated UPN suffix for the matching operation.

⬆ Back to Table of Contents

🔍 Troubleshooting Checklist

When a match (soft or hard) doesn’t work, follow this systematic checklist:

⬆ Back to Table of Contents

⚙️ How to Disable or Enable Soft Match Tenant-Wide

In some scenarios, you may want to disable soft matching entirely to prevent unintended account linking. Here’s how:

Disable Soft Match

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "OnPremDirectorySynchronization.ReadWrite.All"

# Get the current sync configuration
$OnPremSync = Get-MgDirectoryOnPremiseSynchronization

# Disable soft match
$OnPremSync.Features.BlockSoftMatchEnabled = $true

# Apply the change
Update-MgDirectoryOnPremiseSynchronization `
    -OnPremisesDirectorySynchronizationId $OnPremSync.Id `
    -Features $OnPremSync.Features

Re-Enable Soft Match

# Set BlockSoftMatchEnabled to false
$OnPremSync.Features.BlockSoftMatchEnabled = $false

Update-MgDirectoryOnPremiseSynchronization `
    -OnPremisesDirectorySynchronizationId $OnPremSync.Id `
    -Features $OnPremSync.Features

Check Current Sync Feature Settings

# View all sync features
$OnPremSync = Get-MgDirectoryOnPremiseSynchronization
$OnPremSync | Select-Object -ExpandProperty Features | Format-List

Key features to look for:

• BlockSoftMatchEnabled — True = soft match disabled
• SoftMatchOnUpnEnabled — True = UPN-based soft matching enabled
• BlockCloudObjectTakeoverThroughHardMatchEnabled — True = hard match takeover blocked

⬆ Back to Table of Contents

📊 Process Flow: Soft Match vs Hard Match Decision Tree

┌─────────────────────────────────────────┐
│   New on-prem user needs to sync        │
│   with existing cloud user?             │
└──────────────┬──────────────────────────┘
               │
       ┌───────▼───────┐
       │  Does UPN &    │
       │  SMTP match?   │
       └───┬───────┬───┘
          YES      NO
           │        │
   ┌───────▼──┐  ┌──▼──────────────────┐
   │ Does the │  │ Can you align the   │
   │ user have│  │ UPN & SMTP easily?  │
   │ admin    │  └──┬────────────┬─────┘
   │ roles?   │    YES           NO
   └──┬───┬──┘     │             │
     YES  NO    ┌──▼──┐    ┌─────▼──────┐
      │    │    │Align │    │  Use HARD  │
      │    │    │attrs │    │  MATCH     │
      │    │    │& run │    │(ImmutableID)│
      │    │    │SOFT  │    └────────────┘
      │    │    │MATCH │
      │    │    └──────┘
      │    │
      │  ┌─▼─────────┐
      │  │ Use SOFT   │
      │  │ MATCH      │
      │  │ (automatic)│
      │  └────────────┘
      │
  ┌───▼──────────────┐
  │ Remove admin     │
  │ roles → Hard     │
  │ Match → Re-add   │
  │ roles            │
  └──────────────────┘

⬆ Back to Table of Contents

❓ Frequently Asked Questions (FAQ)

Get-ADSyncGlobalSettings | Select-Object -ExpandProperty Parameters | 
    Where-Object { $_.Name -eq "Microsoft.SynchronizationOption.AnchorAttribute" }

Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes "User.ReadWrite.All"
Update-MgUser -UserId "user@contoso.com" -OnPremisesImmutableId "base64value"

⬆ Back to Table of Contents

📝 Summary

Published on https://core365.cloud — Practical guides for IT professionals managing Microsoft hybrid identity environments.

⬆ Back to Table of Contents