Skip to content

Clearing Immutable ID for Entra ID User Sync Issues

This guide explains how to clear the Immutable ID attribute for a user in Entra ID when experiencing synchronization issues from on-premises Active Directory.

When to Use This

Clear the Immutable ID when:

  • A user account does not sync properly from Active Directory
  • You need to re-match an on-premises user with an existing cloud account
  • The user's sync relationship is broken and needs to be re-established
  • You're troubleshooting duplicate or mismatched user accounts

Impact

Clearing the Immutable ID breaks the link between the on-premises AD user and the Entra ID user. The next sync cycle will attempt to automatically re-match the accounts based on attributes like UPN or email address.

Prerequisites

  • Microsoft Graph PowerShell SDK installed
  • Appropriate permissions in Entra ID (User Administrator or Global Administrator)
  • Connection to Microsoft Graph with required scopes

Steps

1. Connect to Microsoft Graph

# Connect with required permissions
Connect-MgGraph -Scopes "User.ReadWrite.All"

2. Retrieve the User Object

# Get the user by UPN or email
$user = Get-MgUser -UserId "user@domain.com"

# Verify you have the correct user
$user | Select-Object DisplayName, UserPrincipalName, Id, OnPremisesImmutableId

3. Clear the Immutable ID

# Send PATCH request to clear the Immutable ID
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/Users/$($user.Id)" -Body '{"OnPremisesImmutableId": null}'

4. Verify the Change

# Retrieve the user again to confirm
$user = Get-MgUser -UserId "user@domain.com"
$user.OnPremisesImmutableId
# Should return null or empty

5. Trigger Sync (Optional)

If you want to immediately trigger a sync cycle from Entra ID Connect:

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

Complete Script

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

# Get the user
$userUPN = "user@domain.com"
$user = Get-MgUser -UserId $userUPN

# Display current state
Write-Host "Current Immutable ID: $($user.OnPremisesImmutableId)"

# Clear the Immutable ID
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/Users/$($user.Id)" -Body '{"OnPremisesImmutableId": null}'

Write-Host "Immutable ID cleared successfully"

# Verify
$user = Get-MgUser -UserId $userUPN
Write-Host "New Immutable ID: $($user.OnPremisesImmutableId)"

Troubleshooting

Permission Denied Error

Problem: Error when executing the PATCH request.

Solutions: - Ensure you have User.ReadWrite.All permissions - Verify you're connected to Microsoft Graph: Get-MgContext - Check that you have appropriate admin role (User Administrator or higher)

User Not Found

Problem: Cannot retrieve user with Get-MgUser.

Solutions: - Verify the UPN is correct - Check if the user exists in Entra ID - Try searching by ObjectId instead of UPN - Ensure you have permission to read user objects

Immutable ID Still Present After Clearing

Problem: OnPremisesImmutableId is not null after clearing.

Solutions: - Wait a few minutes for the change to propagate - Verify the PATCH request completed successfully - Check for any error messages in the console - Try retrieving the user again with a fresh query

Sync Not Re-Matching User

Problem: After clearing Immutable ID, sync doesn't automatically match the user.

Solutions: - Verify the on-premises UPN matches the cloud UPN - Check ProxyAddresses match between on-premises and cloud - Ensure the on-premises user has a valid mailNickname attribute - Review Entra ID Connect sync errors in Synchronization Service Manager - Check matching rules in Entra ID Connect configuration

What Happens Next

After clearing the Immutable ID:

  1. Next Sync Cycle: Entra ID Connect will detect the user has no Immutable ID
  2. Automatic Matching: The sync engine will attempt to match based on:
  3. UserPrincipalName
  4. ProxyAddresses (email addresses)
  5. Other configured matching attributes
  6. Re-Establishment: If a match is found, the Immutable ID is set again, and the sync relationship is restored
  7. Ongoing Sync: Future sync cycles will update the cloud user from on-premises AD

This guide applies to Entra ID (formerly Azure AD) with Entra ID Connect synchronization.