Sometimes, it is necessary to match an existing local Active Directory (AD) user through Entra Connect with an existing Entra ID user (formerly known as Azure AD). This process ensures that the account in both environments is aligned and maintains the same underlying configurations and settings across systems.
Table of Contents
- What is soft-matching?
- What is hard-matching?
- The process described
- Step 1: Fetching Active Directory GUID
- Step 2: Logging into Entra ID with Microsoft Graph
- Step 3: Set the new Immutable ID in Microsoft Entra
- Summary
📖 Estimated read time: 4 minutes
🔄 Page last updated on: August 19, 2025 🆔 Post ID: 813What is soft-matching?
Most of the time the system itself will match the users automatically using soft-matching. Here the service will be matching users in both Entra ID and Active Directory by using known attributes like UserPrincipalName and ProxyAddresses.
What is hard-matching?
In some cases, especially when you use different Active Directory and Entra ID domains, we need to give the final tip to match the users. We will tell Entra ID what the GUID of the on-premises user is by getting that value and encode it into Base64. Then we pass Entra ID this value so it understands what local user to link with what cloud user. This process is called “hard-matching“.
The process described
The steps to hard-match an Entra ID and Active Directory user are in short:
- Determine the local and cloud user you want to match
- On the on-premises Active Directory, run the command “Get-ADUser *username*”
- Copy the GUID value
- Run the command “[Convert]::ToBase64String([guid]::New(“*GUID*”).ToByteArray())” with *GUID* replaced by the GUID from step 3
- Copy the Base64 value
- Connect to Microsoft 365 by using “Connect-MSOLService”
- Run the command “Set-MsolUser -UserPrincipalName user@domain.com -ImmutableId *BASE64*
- Run a Entra Connect Sync
Step 1: Fetching Active Directory GUID
To merge an existing on-premises user and an existing cloud user into one unified user account under the hood, follow these steps:
- Log in to your Active Directory management server
- Open PowerShell.
- Execute the following command:
Get-ADUser -Identity *username*Replace *username* by the username of the user you want to match.
The output of the command above will be something like this:
DistinguishedName : CN=administrator,OU=Users,DC=justinverstijnen,DC=nl
Enabled : True
GivenName : Administrator
Name : administrator
ObjectClass : user
ObjectGUID : c97a6c98-ded8-472c-bfb6-87ed37d324f5
SamAccountName : administrator
SID : S-1-5-21-1534517208-3616448293-1356502261-1244
Surname : Administrator
UserPrincipalName : administrator@justinverstijnen.nlCopy the value of the ObjectGUID, in this case:
c97a6c98-ded8-472c-bfb6-87ed37d324f5Because Active Directory uses GUID for a unique identifier of the user and Entra ID uses a Base64 value for a unique identifier, we need to convert the GUID string to a Base64 string. We can do this very easy with Powershell too:
[Convert]::ToBase64String([guid]::New("c97a6c98-ded8-472c-bfb6-87ed37d324f5").ToByteArray())We get a value like this:
mGx6ydjeLEe/toftN9Mk9Q==Now we have the identifier Entra ID needs. We change the ID of the cloud user to this value. This way the system knows which on-premises user to sync with which cloud user.
Step 2: Logging into Entra ID with Microsoft Graph
To actually match the users, we need to login to Microsoft Graph in PowerShell, as we can there perform the actions. For installation instructions of the Microsoft Graph PowerShell module: https://www.powershellgallery.com/packages/Microsoft.Graph/2.24.0
Run the following command to login to Microsoft Entra ID with Microsoft Graph:
Connect-MgGraph -Scopes "User.ReadWrite.All"Login with your Microsoft Entra ID administrator account.
Step 3: Set the new Immutable ID in Microsoft Entra
After succesfully logging into Microsoft Graph, run the command to set a (new) Immutable ID for your cloud user:
Update-MgUser -UserId "administrator@justinverstijnen.nl" -OnPremisesImmutableId "mGx6ydjeLEe/toftN9Mk9Q=="Now the user is hard matched. You need to run a Entra Connect synchronization to finish the process.
Log in to the server with AD Connect/Entra Connect sync installed and run the command:
Start-ADSyncSyncCycle -PolicyType DeltaNow your on-premises user and cloud user have been matched!
Summary
Hardmatching users is relatively easy, but requires some steps that are good to know. After doing this around 3 times you will perform this completely on “auto-pilot”.
Sources
These sources helped me by writing and research for this post;
End of the page 🎉
You have reached the end of the page. You can select a category, share this post on X, LinkedIn and Reddit or return to the blog posts collection page. Thank you for visiting this post.
- Azure Master Class (12)
- Azure Virtual Desktop (20)
- Flying (15)
- Intune (5)
- Microsoft 365 (12)
- Microsoft Azure (29)
- Microsoft Defender XDR (4)
- Microsoft Entra (9)
- Networking (5)
- Powershell (19)
- Uncategorized (1)
- Windows 365 (3)
- Windows Server (12)
If you think something is wrong with this post or you want to know more, you can send me a message to one of my social profiles at: https://justinverstijnen.nl/about/
The terms and conditions apply to this post.
Page visitors: No page-counter data available yet.
0 Comments