Disclaimer: 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:
- Get the ID for a single user and write it to the screen
- Get the ID for all users and write them to a CSV
- 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 download the file.
[System.Console]::ForegroundColor = [System.ConsoleColor]::White
clear-host
Import-module activedirectory
write-host
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
write-host Please choose one of the following:
write-host
write-host ‘1) Get ID for a Single User’
write-host ‘2) Get IDs for all Users’
write-host ‘3) Cancel’ -ForegroundColor Red
write-host
$option = Read-Host “Select an option [1-3]”
switch ($option)
{
‘1’{
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())}}
$Users
}
‘2’{
Write-host
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
$users | export-csv $Path
}
‘3’{
write-verbose “Option 3 selected”
break
}
}