Tech Tip: Step-By-Step guide to Hard Match a user on Office 365 or Azure AD
By David Romano
Often we see errors like attribute value must be unique when we try to sync a user to the cloud service like Azure AD or Office 365 and despite we update the primary SMTP address or mail attribute in the AD we get to see an error something like this.
No matter how hard we try, we can’t sync the user across. There might also be situations where the UPN that you setup on the cloud differed from the the local UPN and you have a duplicate object with the same proxy address or UPN and the sync either fails, or creates an user account with .onmicrosoft.com domain because yu are using a non-routable domain like “.local” and had created a cloud account with a vanity domain and now you sync the user without changing the UPN or you have a situation when a user account was deleted on local AD and the same occurred in Azure AD or Office 365 due to the sync for some reasons you recreate the same object on local AD now you restore the account on Azure AD/Office 365 and you start getting the above error.
To fix such issues you might have to hard match an object. By the term hard match, we mean to explicitly stamp the source anchor for a user account. If I had to say this in simpler terms I would say Hard Match is a process where you stamp the on-prem object GUID (as Base64 value) on a cloud user so that the DirSync or AD Connect tool is able to identify the right account and sync or make changes to it. If you have some concept of RDBMS systems you can relate the above process with the indexing. Every cloud user has an ObjectID that acts as primary key on Azure AD, and when you run a sync the tool identifies the correct user base upon proxy addresses and UPN and it stamps the Base64 value of the object GUID from local AD. Note that this is a single time operation and this Base64 value acts as foreign key. This process helps the tool to identify the correct user on Azure AD so that next time the sync tool does not have to start the entire identification from scratch.
Now, let’s have a look at the process to hard match a user:
- On the Domain Controller open a powershell window and run the command Import-Module ActiveDirectory
- Run the command Get-ADUser -Identity “Enter Local AD logon ID in these quotes” once you
run the above command you should be able to see an output like this:
- Now copy the object GUID from the output and open the website http://guid-convert.appspot.com/ and paste the same on the textbox as shown in the image and click on convert, you should be getting the B64 value and copy the same. Make sure that there are no spaces when you paste the value in the textbox. (Although, there are other ways to get the Base64 value from a GUID I recommend this approach as it is simple, you can get the same results from LDIFDE and Powershell.
- Now run the command Import-Module MSOnline
- Then run the command Connect-MSOLService you should be seeing a prompt to enter credentials, enter the office 365 global admin credentials here.
- Now before we proceed further make sure you get rid of the duplicate account from Office 365/Azure AD. Make sure you remove it from the Deleted Users as well. To remove the user from the deleted users container run the command Remove-MsolUser -UserPrincipalName email@example.com -RemoveFromRecycleBin -Force , you need to enter the Signin address or UPN of the deleted user here, for the purpose of showing an example I have used firstname.lastname@example.org. This command would permanently remove the user, so make sure you remove the right account.
- Once you remove the account run the command Set-MsolUser -UserPrincipalName email@example.com -ImmutableId QX00ApTUDEiiEm5kX0WP2w== , here you need to enter the UPN /Signin address of office 365/azure AD against which you wish to perform a hard match and after the -immutableID flag enter the B64 value that you copied from http://guid-convert.appspot.com/
- Once this is done run a delta sync the issue will be fixed.
For more information email firstname.lastname@example.org