Hard Matching Identities with Office 365 ImmutableID

Office 365 Immutableid

Feb 11, 2016 by Ed Buford

Office 365 ImmutableidDisclaimer: I’m not going to actually do any Hard Matching in this blog post. I’m going to give you a tool so that you can do it if you need to.

With Office 365 there are sometimes instances where we need to match a user in Active Directory to a user in Office 365. For the most part this is done using the User Principal Name (UPN) of the user in Active Directory to the UPN of the user in Office 365; the term for this is Soft Matching or sometimes SMTP Matching.

This is particularly useful when users have been created in Office 365 and you are using Directory Synchronization to match users to their Office 365 counterpart.

There are times when you need to Hard Match a user from Active Directory to Office 365 either for troubleshooting, for Active Directory Migrations, or because you may be using a license that doesn’t allow the Primary SMTP address to be set.

In order to Hard Match a user, you need to get the objectGUID of the user account in Active Directory and convert it to the Office 365 ImmutableID that identifies an Active Directory user. There is certainly more than one way to go about this but since I use PowerShell every day, I use it to help me do this job.

The script below needs to be run on server with the Active Directory PowerShell Module installed on it (usually a Domain Controller).

When you run the script, it will give you three options:

  1. Get the ID for a single user and write it to the screen
  2. Get the ID for all users and write them to a CSV
  3. Cancel

If you choose the second option you need to enter a path for the CSV file to be created. I always choose to write my files to a folder, because depending on security settings, you may not be able to write a file straight to the C:\ drive.

Save the script below to a PowerShell script by copying the information below to a notepad file and saving it as Get-ImmutableID.PS1 (make sure you change the ‘Save As’ Type to All Files). Or you can click HERE to download the file.

[System.Console]::ForegroundColor = [System.ConsoleColor]::White


Import-module activedirectory


write-host This Script will Get the ObjectGUID for a user and convert

write-host it to the Immutuable ID for use in Office 365


write-host Please choose one of the following:


write-host ‘1) Get ID for a Single User’

write-host ‘2) Get IDs for all Users’

write-host ‘3) Cancel’ -ForegroundColor Red


$option = Read-Host “Select an option [1-3]”

switch ($option)



write-verbose “Option 1 selected”

$GetUser = Read-Host -Prompt ‘Enter UserName’

$Users = get-aduser $GetUser  | select samaccountname,userprincipalname,objectguid,@{label=”ImmutableID”;expression={[System.Convert]::ToBase64String($_.objectguid.ToByteArray())}}





Write-host Type the Path location to Export the results:   i.e. c:\source\ImmutableID.csv

$Path = Read-Host -Prompt ‘Enter Path’

$Users = get-aduser -filter * | select samaccountname,userprincipalname,objectguid,@{label=”ImmutableID”;expression={[System.Convert]::ToBase64String($_.objectguid.ToByteArray())}}


$users | export-csv $Path



write-verbose “Option 3 selected”




There you have it! If you have any questions about this process, your Office 365 or Active Directory environment, don’t hesitate to reach out. You can call us at 502-240-0404 or email us.

Press enter to search