How to Set Immutable ID to Null Using MS Graph
When managing users in a hybrid setup, one attribute you’ll often hear about is the Immutable ID. This value acts as the unique bridge between your on-premises Active Directory (AD) account and its corresponding Microsoft Entra ID (Azure AD) cloud account.
There may be various scenarios where you want to set a user’s immutable ID to null, such as when migrating from a hybrid setup to a fully cloud-only environment. Therefore, knowing how to manage it is important. The good news is, with the Microsoft Graph PowerShell SDK, you can easily clear the Immutable ID when needed.
In this blog, we’ll walk through what the Immutable ID is, why you might need to reset it, and how to do it with Graph cmdlets.
The Immutable ID (also called SourceAnchor) is the attribute used by directory synchronization tools (like Azure AD Connect) to match on-premises user accounts with their cloud counterparts. It makes sure that when users are synced between on-premises and the cloud, they are recognized as the same person in both places. This attribute is crucial for directory synchronization, ensuring that changes made to a user in one directory are correctly reflected in the other.
- In on-prem AD, a user has a unique value called ms-DS-ConsistencyGuid or ObjectGUID.
- When the account syncs to Entra ID, this value becomes the Immutable ID, so Entra knows which cloud account belongs to which on-premises account.
Normally, the Immutable ID in Azure AD should never change, but in some cases, clearing it becomes necessary:
- Migrating to a new on-premises AD: During mergers or restructures, user accounts may be moved to a different AD. Clearing the old Immutable ID ensures accounts can be re-linked properly.
- Switching from hybrid to cloud-only identity: If the organization decides to stop syncing on-prem users without deleting them from cloud, the Immutable ID is no longer useful. Clearing it prevents accidental re-sync with the old directory.
- Fixing sync issues: Misconfigurations can cause mismatches between accounts. Resetting the Immutable ID lets admins re-establish the correct link.
⚠️ Note: You can only set a user’s OnPremisesImmutableId property in Entra ID to null when the user is not actively synced from on-premises AD. This is determined by the property called OnpremisesSyncEnabled.
If the user’s OnPremisesSyncEnabled property is True, Graph will block the change. In that case, you must either:
- Move the user out of the sync scope, or
- Disable sync temporarily.
You can reset the ImmutableID only after setting OnPremisesSyncEnabled to False.
Before clearing the Immutable ID, it’s best to first verify the user’s OnPremisesSyncEnabled value. To do this, you need to install and connect to Microsoft Graph PowerShell either interactively or using a certificate with the User.ReadWrite.All permission. Once connected, you can run the following command to check the user’s OnPremisesSyncEnabled value.
|
1 |
Get-MgUser -UserId [email protected] | Select-Object DisplayName, UserPrincipalName, OnPremisesImmutableId, OnPremisesSyncEnabled |
This shows whether the user is still linked to on-prem (OnPremisesSyncEnabled=True) and whether the Immutable ID has a value.
To Fetch all users and list their Immutable IDs and OnPremisesSyncEnabled value, run the following cmdlet.
|
1 |
Get-MgUser -All | Select-Object DisplayName, UserPrincipalName, OnPremisesImmutableId, OnPremisesSyncEnabled |
Traditionally, admins used Set-MsolUser or Set-AzureADUser cmdlets to clear Immutable IDs. Since the MSOL and Azure AD PowerShell modules are deprecated, it’s recommended to use the Microsoft Graph PowerShell SDK instead:
- Set a single user’s OnPremisesImmutableId to null
- Bulk update OnPremisesImmutableId to null
- Clear OnPremisesImmutableId for all users
To unlink a user from their on-premises AD, remove their Immutable ID using:
|
1 |
Update-MgUser -UserId "[email protected]" -OnPremisesImmutableId $null |
This directly updates Immutable ID with Microsoft Graph and clears it successfully. This method is often used when you want to convert AD synced user to a cloud only account without deleting the account.
To reset Immutable IDs for multiple users, prepare a CSV file (users.csv) with a column named UserPrincipalName. Then run:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
$users = Import-Csv -Path "C:\Path\To\users.csv" foreach ($user in $users) { try { $userDetails = Get-MgUser -UserId $user.UserPrincipalName -Property OnPremisesImmutableId,OnPremisesSyncEnabled if ($userDetails.OnPremisesSyncEnabled -eq $true) { Write-Warning "Skipping $($user.UserPrincipalName) - still synced from on-prem." } else { Update-MgUser -UserId $user.UserPrincipalName -OnPremisesImmutableId $null Write-Host "Cleared ImmutableId for $($user.UserPrincipalName)" -ForegroundColor Green } } catch { Write-Warning "Failed to update $($user.UserPrincipalName): $_" } } |
This script resets Immutable ID for all users in the CSV.
Run the following script to fetch all users, check if they’re cloud-only, and clear their OnPremisesImmutableId.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
$allUsers = Get-MgUser -All -Property UserPrincipalName,OnPremisesImmutableId,OnPremisesSyncEnabled foreach ($user in $allUsers) { try { if ($user.OnPremisesSyncEnabled -eq $true) { Write-Warning "Skipping $($user.UserPrincipalName) - still synced from on-prem." } else { if ($null -ne $user.OnPremisesImmutableId) { Update-MgUser -UserId $user.UserPrincipalName -OnPremisesImmutableId $null Write-Host "Cleared ImmutableId for $($user.UserPrincipalName)" -ForegroundColor Green } else { Write-Host "ImmutableId already null for $($user.UserPrincipalName)" -ForegroundColor Yellow } } } catch { Write-Warning "Failed to update $($user.UserPrincipalName): $_" } } |
This script clears the ImmutableId for all users with a non-null value, while skipping those still synced from on-premises.
Points to Remember:
- Always check the user’s OnPremisesSyncEnabled status before attempting to clear the Immutable ID.
- By clearing the Immutable ID, you disable on-premises sync for a single user and unlink their account from AD. However, if Azure AD Connect is still running, this action may result in a duplicate user being created instead of re-linking the existing one.
- Resetting Immutable ID without planning can cause sign-in issues, loss of licenses, or disruption in Teams/Outlook.
- Clear Immutable ID when absolutely required such as during migrations, fixing sync errors, or switching to cloud-only users.
- Always back up user properties (Immutable ID, Object ID, UPN, licenses) before making changes.
- Test the process on a non-critical user before applying it in bulk.
- If you run into problems with sync or identity mismatches, sometimes performing a hard match on-premises users with Microsoft Entra is a better alternative than wiping the Immutable ID.
I hope this blog helped you understand how to set Immutable IDs to null using Microsoft Graph PowerShell SDK. Thanks for reading! If you have any questions or run into issues, feel free to drop them in the comments below.
