How to Block Soft and Hard Match in Microsoft Entra ID for Enhanced Security

First, install the Microsoft.Entra PowerShell module, which is Microsoft's current recommended approach for managing directory synchronization features. This module replaces the legacy MSOnline module.

Install-Module Microsoft.Entra -Repository PSGallery -Force -AllowClobber

Import the module and connect to your Entra ID tenant with the required permissions:

Import-Module Microsoft.Entra
Connect-Entra -Scopes 'OnPremDirectorySynchronization.ReadWrite.All'

When prompted, authenticate with your Global Administrator or Directory Synchronization Administrator credentials. The connection will establish a session with your tenant.

Before making any changes, examine the current state of your directory synchronization features. This baseline check helps you understand what's currently enabled and provides a reference point.

Get-EntraDirSyncFeature

This command displays all directory synchronization features and their current enabled/disabled status. Look specifically for these two features:

• BlockSoftMatch - Controls soft matching based on userPrincipalName or primary SMTP address
• BlockCloudObjectTakeoverThroughHardMatch - Controls hard matching via source anchor (ImmutableID)

The output will show True if the blocking is enabled (secure) or False if matching is allowed (potential security risk).

Soft matching automatically links on-premises and cloud objects based on userPrincipalName or primary SMTP address. While convenient for migrations, it creates a significant security vulnerability where attackers can potentially take over cloud objects.

Get your tenant ID and block soft matching:

$tenantID = (Get-EntraContext).TenantId
Set-EntraDirSyncFeature -Features 'BlockSoftMatch' -Enable $true -TenantId $tenantID -Force

This command immediately disables soft matching across your entire tenant. The -Force parameter bypasses confirmation prompts, making it suitable for automation scripts.

Soft matching works by comparing these attributes between on-premises and cloud objects:

• userPrincipalName (primary matching attribute)
• Primary SMTP address from proxyAddresses
• Mail attribute (if present)

When blocked, Entra Connect will only establish object relationships through explicit hard matching or during initial synchronization.

Hard matching uses the ImmutableID (source anchor) to link objects. While more precise than soft matching, it can still be exploited if an attacker gains access to on-premises Active Directory and can manipulate source anchor values.

Block cloud object takeover through hard matching:

$tenantID = (Get-EntraContext).TenantId
Set-EntraDirSyncFeature -Features 'BlockCloudObjectTakeoverThroughHardMatch' -Enable $true -TenantId $tenantID -Force

This protection prevents scenarios where:

• An attacker compromises on-premises AD
• They create a new user with a source anchor matching an existing cloud object
• Entra Connect would normally link these objects, giving the attacker control over the cloud identity

With this block enabled, Entra Connect will reject synchronization attempts that would result in unauthorized object takeover through source anchor manipulation.

The enforcement logic verifies on-premises mapping attributes before allowing any source-of-authority remapping, effectively blocking suspicious remapping attempts.

After enabling both blocking features, perform a comprehensive verification to ensure your security configuration is active and functioning correctly.

Check the final status of all directory synchronization features:

Get-EntraDirSyncFeature | Where-Object {$_.FeatureName -like '*Block*'} | Format-Table FeatureName, Enabled -AutoSize

This filtered view shows only the blocking-related features for easy verification. Both should display True in the Enabled column.

If you have Entra Connect running, trigger a manual synchronization to test the new behavior:

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

Monitor the synchronization logs for any changes in behavior. With blocking enabled, you should see:

• No automatic soft matching of objects based on UPN or email
• Rejection of hard match attempts that would result in object takeover
• Clear error messages if legitimate matching attempts are blocked

Microsoft recommends keeping blocking enabled by default and only disabling it during specific migration windows. Here's how to safely manage temporary unblocking for legitimate business needs.

Create a script for temporary unblocking during migrations:

# Save current blocking status
$currentSoftMatch = (Get-EntraDirSyncFeature | Where-Object {$_.FeatureName -eq 'BlockSoftMatch'}).Enabled
$currentHardMatch = (Get-EntraDirSyncFeature | Where-Object {$_.FeatureName -eq 'BlockCloudObjectTakeoverThroughHardMatch'}).Enabled

Write-Host "Current BlockSoftMatch: $currentSoftMatch"
Write-Host "Current BlockCloudObjectTakeoverThroughHardMatch: $currentHardMatch"

# Temporarily disable for migration (use with extreme caution)
$tenantID = (Get-EntraContext).TenantId
Set-EntraDirSyncFeature -Features 'BlockSoftMatch' -Enable $false -TenantId $tenantID -Force
Set-EntraDirSyncFeature -Features 'BlockCloudObjectTakeoverThroughHardMatch' -Enable $false -TenantId $tenantID -Force

Write-Host "Blocking temporarily disabled for migration. Re-enable immediately after completion!"

After completing your migration tasks, immediately re-enable the blocking:

# Re-enable blocking after migration
$tenantID = (Get-EntraContext).TenantId
Set-EntraDirSyncFeature -Features 'BlockSoftMatch' -Enable $true -TenantId $tenantID -Force
Set-EntraDirSyncFeature -Features 'BlockCloudObjectTakeoverThroughHardMatch' -Enable $true -TenantId $tenantID -Force

Write-Host "Security blocking re-enabled successfully."

Establish ongoing monitoring to ensure your blocking configuration remains secure and compliant with Microsoft's security recommendations.

Create a monitoring script to regularly check blocking status:

# Monitoring script for blocking status
function Test-EntraMatchingBlocks {
    try {
        Connect-Entra -Scopes 'OnPremDirectorySynchronization.ReadWrite.All' -ErrorAction Stop
        
        $features = Get-EntraDirSyncFeature
        $softMatchBlocked = ($features | Where-Object {$_.FeatureName -eq 'BlockSoftMatch'}).Enabled
        $hardMatchBlocked = ($features | Where-Object {$_.FeatureName -eq 'BlockCloudObjectTakeoverThroughHardMatch'}).Enabled
        
        $result = @{
            'SoftMatchBlocked' = $softMatchBlocked
            'HardMatchBlocked' = $hardMatchBlocked
            'ComplianceStatus' = ($softMatchBlocked -and $hardMatchBlocked)
            'CheckDate' = Get-Date
        }
        
        if ($result.ComplianceStatus) {
            Write-Host "✓ COMPLIANT: Both soft and hard matching are blocked" -ForegroundColor Green
        } else {
            Write-Host "✗ NON-COMPLIANT: Matching blocks are not properly configured" -ForegroundColor Red
        }
        
        return $result
    }
    catch {
        Write-Error "Failed to check blocking status: $($_.Exception.Message)"
    }
}

# Run the compliance check
Test-EntraMatchingBlocks

For enterprise environments, consider implementing this check as part of your security compliance framework. The Maester security testing framework includes test MT.1073 specifically for verifying soft and hard match blocking.

Set up automated alerts for configuration drift:

# Example: Schedule this as a daily task
$complianceCheck = Test-EntraMatchingBlocks
if (-not $complianceCheck.ComplianceStatus) {
    # Send alert to security team
    Send-MailMessage -To "security@company.com" -Subject "Entra ID Matching Blocks Non-Compliant" -Body "Soft/Hard matching blocks are not properly configured. Immediate attention required."
}