Change UPN Suffix using PowerShell

A few weeks ago, I was implementing AD synchronization between an on-prem Active Directory and Office 365. One of the prerequisites is that the UPN (User Principal Name) suffix for the users which are synchronized to Office 365, has to be a public domain name. The domain I was working with, was a local domain (.local). So, I had to change the UPN suffixes for all users to the public domain name. Because I had to change thousands of users, I created a PowerShell script which does it for me. The script does a few checks before it actually tries to update the UPN:

  • It checks if the “ActiveDirectory” module is installed. We need this to interact with the objects in Active Directory. If it’s installed, it’s loaded automatically if not already loaded.
  • It checks if the new UPN suffix, which needs to be provided by means of a parameter, is registered as a UPN suffix in the domain.

The script has 4 parameters:

  • OldUPNSuffix : This is UPN Suffix which is going to be replaced with the new one.
  • NewUPNSuffix : This is the new UPN suffix
  • Filter : This is a filter which is used in the Get-ADUser cmdLet and is used to retrieve all user objects we are working with. For more information on the filters which can be specified, check the documentation for the Get-ADUser cmdLet.
  • Mode : I made the script to run in a “List” and “Modify” mode. When you specify “List” as value for this parameter, the actual change is not done but it’s only logged in a file. Comes in handy when you want to see the results before you actually unleash it with the “Modify” value. And yes, I know… you can do this with the -whatif also. But then again, I prefer my logfile output over a scrolling command console with a massive amount of output.

Now, for the script… here it is. Nothing to fancy really.