AADConnect sync – local AD UPN cleanup

Prior to embarking on the synchronisation of any local AD user or group accounts into the office 365 cloud, it is essential to ‘clean up’ the objects.

2 key cleanup items spring to mind:

  • It is best practise to match the user account name to the user e-mail address
  • Run the idFix tool over your local AD user and group OUs to determine any issues with duplicate entries, invalid characters etc

By default, the Azure ActiveDirectory connect tool will use the local AD UPN attribute to assign an o365 username. However, many organisations have local AD domains and policies which result in naming conventions that don’t resemble user SMTP addresses (i.e. john.smith@internal.local or john.smith@production.local). These UPN formats are not desirable for o365 usernames.

To match the MS best practice of “username = e-mail address”, means that the UPN needs to be changed to the external facing SMTP address (i.e. john.smith@externalorganisationdomain.com). A UPN can be modified without affecting the user’s ability to login with their SAM.

Recently I had to develop a powershell script for a customer to programatically change their local AD UPN entries over to user primary SMTP details (for over 2000 users).

Additionally, the customer did not want the script to change all 2000 user accounts at once (they wanted to confirm with a ‘y’/’n’ option for each proposed change). They also wanted every changed UPN to be logged to a txt output file.

Here is what that script looks like (normally saved as script.ps1 and run in a Powershell window that has been launched to ‘run as administrator’):

foreach ($user in (Get-ADUser -SearchBase "OU=Users,DC=internal,DC=local" -LdapFilter ‘(proxyAddresses=*)’)) {
$address = Get-ADUser $user -Properties proxyAddresses | Select -Expand proxyAddresses | Where {$_ -clike "SMTP:*"}
$newUPN = $address.SubString(5)
$oldUPN = (Get-ADUser -Identity $user -Properties UserPrincipalName).UserPrincipalName

echo " "
echo "oldUPN: . $oldUPN"
echo "newUPN: . $newUPN"
echo " "

$confirmation = Read-Host "Are you sure you want to continue?"
if ($confirmation -eq ‘y’) {
Set-ADUser $user -UserPrincipalName $newUPN
$newUPN | Out-File "c:\temp\upnfix.txt" -Append

So what does the script do?

  • it interrogates AD-Users within a specific AD searchbase container, and focusses on their configured proxyAddresses
  • the $address variable is set for the users primary SMTP value (SMTP in capitals as opposed to alternate smtp values with are always lowercase)
  • the $newUPN variable is set to the $address
  • the $oldUPN variable is set to the users current UPN
  • both oldUPN and newUPN are displayed to the administrator
  • the administrator is asked to confirm “Are you sure you want to continue?”
  • if ‘y’ and enter is pressed, the user UPN is overwritten with the $newUPN variable
  • the $newUPN is written to a text file for reference

Happy and safe travels with your UPN cleanups!

Have you achieved this in a better/cleaner way? Let me know.

Leave a Reply

Your email address will not be published. Required fields are marked *