Script to link local AD users to Azure AD users if they were not matched correctly by Azure Connect

LinkImmutableID.ps1

<#

Description
-----------
This script can help you merge duplicate Azure AD users or match a local
AD user to an Azure AD user by copying the Azure AD Immutable ID to the
local user record.

This can be useful if Azure AD Connect has not correctly matched a local
user with an existing cloud user, leaving you with duplicate users.

This is all based on this guy's thread here:

https://community.spiceworks.com/how_to/122371-hard-link-ad-accounts-to-existing-office-365-users-when-soft-match-fails


Prerequisites
-------------
Install and load modules as needed.

- Powershell
- Microsoft365 Sign-On Assistant
  https://download.microsoft.com/download/7/1/E/71EF1D05-A42C-4A1F-8162-96494B5E615C/msoidcli_64bit.msi
- AzureAD Powershell module
  https://www.powershellgallery.com/packages/AzureAD/2.0.2.140
- RSAT: Active Directory tools (if you're not working from a domain
  controller)
  https://www.microsoft.com/en-us/download/details.aspx?id=45520


Before you begin
----------------
1. Before using this script, you must disable directory synchronization:

   Set-MsolDirSyncEnabled -EnableDirSync $false

   It may take hours for this to take effect. To check its status:

   (Get-MsolCompanyInformation).DirectorySynchronizationEnabled

   One this returns false, check the portal for the sync status of your
   affected users. Once they are all cloud-only instead of
   directory-synced, you can proceed.

2. If the mismatch you're correcting has resulted in duplicate user
   records in the cloud, you must first delete the extra record. For
   example, if you had john.smith@example.com in the cloud and
   jsmith@example.com in the local AD, after the first sync you would
   have both john.smith@example.com and jsmith@example.com in the cloud.
   To link the local 'jsmith' user to the cloud 'john.smith' user, you
   will need to first delete the cloud 'jsmith' user to avoid a conflict
   when you resume syncing. To do this, use either the Azure AD portal
   or Powershell to first delete the user, then delete the user
   permanently from "Deleted Users." 

With syncing disabled and your duplicate users completely deleted,
you're ready to run the script.

Note: You might also want to figure out why the users didn't match
correctly in the first place and correct that issue before you begin.
For example, you may need to set email addresses or proxyAddress
attributes in your local AD users to match your cloud users.

#>

# Prompt for login
Connect-MsolService

# Check sync status
$IsDirSyncEnabled = (Get-MsolCompanyInformation).DirectorySynchronizationEnabled

If($IsDirSyncEnabled -eq $false) {
    Write-Host "Office 365 Active Directory Sync Disabled - Good to go!"
} else {
    Write-Host "Please disable Active Directory Sync and Wait"
    Exit
} Start-Sleep -Seconds 5

# While loop, in case you have multiple users
do {

    # Prompt to select the local user record from the local directory
    $ADGuidUser = Get-ADUser -Filter * | Select-Object Name,ObjectGUID | Sort-Object Name | Out-GridView -Title "Select Local AD User" -PassThru

    # Convert the immutable ID to the byte array expected by the cloud
    $UserimmutableID = [System.Convert]::ToBase64String($ADGuidUser.ObjectGUID.tobytearray())

    # Prompt to select the cloud user that the local user should be linked to
    $OnlineUser = Get-MsolUser | Select-Object UserPrincipalName,DisplayName,ProxyAddresses,ImmutableID | Sort-Object DisplayName | Out-GridView -Title "Select The Office 365 Online User" -PassThru

    # Copy the local immutable ID to the cloud user record so that they will hard-match on the next sync
    Set-MSOLuser -UserPrincipalName $OnlineUser.UserPrincipalName -ImmutableID $UserimmutableID

    # Show the resultsd
    $Office365UserQuery = Get-MsolUser -UserPrincipalName $OnlineUser.UserPrincipalName | Select-Object DisplayName,ImmutableId
    Write-Host "Do the IDs Match? If not, something is wrong"
    Write-Host "AD Immutable ID Used $UserimmutableID"
    Write-Host "Office365 UserLinked $Office365UserQuery.ImmutableId"

    # Prompt to do another user
    $Repeat = Read-Host "Do you want to choose another user? Y or N"

} while ($Repeat -eq "Y")

# Show final output
Get-MsolUser | Select-Object DisplayName,ImmutableID | Sort-Object DisplayName | Out-GridView -Title "Office 365 User List With Immutableid Showing"

# Close session
Get-PSSession | Remove-PSSession