This post details how to make Azure AD Connect “Hard Match” an on-premises AD user object to an Azure AD user object using the ImmutableID. The vast majority of the time there’s no need to do this, as a “Soft Match” (SMTP matching) will be successful.
Hard Match
First we need to get the GUID of the on-premises AD user object using the following PowerShell commands:
Import-Module ActiveDirectory
$strUPN = "steve.bush@x500.co.uk"
$strGUID = Get-ADUser -LDAPFilter "(userPrincipalName=$strUPN)"
$strGUID = $strGUID.ObjectGUID
We now take the GUID (a 16 byte value, e.g. fcc7e67f-fec6-4a65-b821-2f40a292d185), and convert it to a Base64 value to be used as the ImmutableID (e.g. f+bH/Mb+ZUq4IS9AopLRhQ==).
$strImmID = [System.Convert]::ToBase64String($strGUID.ToByteArray())
Now write this value to the Azure AD user object.
Set-MsolUser -UserPrincipalName steve.bush@x500.co.uk -ImmutableID $strImmID
If you’re using two different PowerShell sessions, simply take the value of $strImmID and specify it as the value, e.g.
Set-MsolUser -UserPrincipalName steve.bush@x500.co.uk -ImmutableID "f+bH/Mb+ZUq4IS9AopLRhQ=="
Wait for the next Azure AD Connect Sync cycle, or force it (see here), and fingers crossed the on-prem AD & Azure AD user objects will be matched.
LDIFDE
Note it’s also possible to get the GUID of the on-premises AD user object in Base64 by using LDIFDE.
ldifde -f ImmutableID.txt -r "(UserPrincipalName=sbush@x500.co.uk)" -l "objectGuid,UserPrincipalName"
This will be saved out to a text file. If you’re needing to do bulk modifications, you can easily extract GUID for all users by specifying * against UPN, e.g.
ldifde -f ImmutableIDs.txt -r "(UserPrincipalName=*)" -l "objectGuid,UserPrincipalName"
Uniqueness Violation
When it comes to stamping ImmutableID onto the Azure AD user object, it’s possible it’s already been stamped onto another object created when Soft Matching didn’t work.
Set-MsolUser -UserPrincipalName steve.bush@x500.co.uk -ImmutableId "f+bH/Mb+ZUq4IS9AopLRhQ=="
Set-MsolUser : Uniqueness violation. Property: SourceAnchor.
At line:1 char:1
+ Set-MsolUser -UserPrincipalName steve.bush@x500.co.uk -ImmutableId "f+bH ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : OperationStopped: (:) [Set-MsolUser], MicrosoftOnlineException
+ FullyQualifiedErrorId : Microsoft.Online.Administration.Automation.UniquenessValidationException,Microsoft.Online.Administration.Automation.SetUser
Find the object in question & delete it. It’ll end up in the Azure AD Recycle Bin, and you’ll need to permanently remove it.
To show items in the Azure AD Recycle Bin:
Get-MsolUser -All -ReturnDeletedUsers
To remove the relevant object:
Remove-MsolUser -UserPrincipalName steve.bush@x500.co.uk -RemoveFromRecycleBin