How to Hard Match Office 365 Identities to On-Premise Users

Akins IT • January 8, 2020
GET MICROSOFT VIRTUAL DESKTOP FOR YOUR BUSINESS

When migrating from on-premise exchange to Office 365, IT administrators can experience failure when attempting to soft match identities. Soft matching (also known as "SMTP matching") can fail for many reasons, the common one being because Office 365 detects that the email is already associated with another object. In the case of a soft match failure, a hard match must be performed. The solution to this is to stamp the online identities immutable ID with the GUID from the on-premise user, which can be done on-premise on the Active Directory server.



This is a simple PowerShell solution to hard match an on-premise GUID to an immutable ID for an online user. This ensures that all on-premise identities are correctly matched and linked to the Office 365 identities, which allows for full Office 365 write-back functionality in an organization's environment.

Provided below is the step-by-step guide on how to carry out this solution:

  1. Remove on-premise Identity from syncing with O365
  2. Remove on-premise Identity from O365 and Remove from Recycle bin
  3. Launch Powershell and run the following Commands
  4. Set-ExecutionPolicy RemoteSigned
  5. $credential = Get-Credential
  6. Input admin credentials for Office 365 and run the following command
  7. Import-Module MsOnline
  8. Connect-MsolService -Credential $credential
  9. Run “$ADGuidUser = Get-ADUser -Filter * | Select Name,ObjectGUID | Sort-Object Name | Out-GridView”
  10. Select the on-premise user from the Grid
  11. Run “$UserimmutableID = [System.Convert]::ToBase64String($ADGuidUser.ObjectGUID.tobytearray())” in powershell to convert GUID to the immutable ID format
  12. Run $OnlineUser = Get-MsolUser | Select UserPrincipalName,DisplayName,ProxyAddresses,ImmutableID | Sort-Object DisplayName | Out-GridView -Title "Select The Office 365 Online User To HardLink The AD User To" -PassThru”
  13. Select the Online identity to match on-premise identity
  14. Run “Set-MSOLuser -UserPrincipalName $OnlineUser.UserPrincipalName -ImmutableID $UserimmutableID”
  15. Set the Online identity with the new immutable ID
  16. Run “Set-MSOLuser -UserPrincipalName $OnlineUser.UserPrincipalName -ImmutableID $UserimmutableID”
  17. Check the immutable id matches
  18. Run the following two lines and confirm IDs Match
    “Write-Host "AD Immutable ID Used" $UserimmutableID”
    “Write-Host "Office365 UserLinked" $Office365UserQuery.ImmutableId”
CONTACT US TO LEARN MORE ABOUT THIS TOPIC OR TO SCHEDULE A CALL
Data security needs layers of protection throughout its lifecycle.  Akins IT and Microsoft Purview
By Shawn Akins May 15, 2025
Strengthening Your Security Posture with Dynamic Access Control
By Shawn Akins May 15, 2025
Discover Affordable and Reliable Virtualization Platforms
By Shawn Akins May 13, 2025
Discover the Key Differences Between Mimecast and M365 Email Security Solutions and Learn Why Akins IT is Your Trusted Partner for Email Protection
More Posts