A quite common occurrence for IT admins is that people change their names, and thus need their username to reflect this change.

In the good ol’ days, this wasn’t an issue, just change their name in AD in 15 different places, and your done. However, these days it also needs to sync to Azure AD, and this is where things gets complicated.

You wouldn’t be wrong for thinking that this can’t be an issue. However, it’s almost not an issue, everything synchronises just fine from you Active Directory to Azure, except one thing, the User Principal Name.

This UPN value is set when the user account is first synchronised to Azure AD, and after that this value never changes. This also happens to be the value that’s shown as the user name in the O365 portal.

Additionally, you can only set this value through PowerShell, which is also rather annoying.

Now, if you go about googling this issue, you’ll find a lot of old posts about some convoluted way that you need to use to connect to Exchange Online to do this change. However, most of those I couldn’t get to work when I had to make this change for a user a couple of days ago, and even if you could get it to work Microsoft is also helpfully going to deprecate the Basic authentication mechanism that is used in that specific tutorial.

So here’s my way of getting this whole thing set up, in it’s entirety, with all the gory details.

Setting Up Your PowerShell Environment

Starting off you’ll need to download and install the 64-bit version of the Microsoft Online Services Sign-in Assistant

After that, you need to launch PowerShell as an Administrator, and set the execution policy to RemoteSigned

Set-ExecutionPolicy RemoteSigned

Then we’ll need to install the Microsoft Azure Active Directory Module for Windows PowerShell

Install-Module MSOnline

It might, depending on your environment, ask you to install the NuGet provider, as well as installing a module from the PSGallery. Answer Y to both these questions if you encounter them.

After all this is done, we can move on to actually do what we set out to do, changing the UPN for our user.

Changing the User Principal Name

You’ll need to connect to Azure AD for your Office 365 subscription using the following command (except in a few edge cases, see below). Note that this command doesn’t need to be run from an elevated PowerShell console.

Connect-MsolService

If your O365 is operated by 21 Vianet, use the following command

Connect-MsolService -AzureEnvironment AzureChinaCloud

Office 365 Germany

Connect-MsolService -AzureEnvironment AzureGermanyCloud

Office 365 U.S. Government DoD and Office 365 U.S. Government GCC High

Connect-MsolService -AzureEnvironment USGovernment

Whichever command applies to your environment, you’ll get a new pop-up Window where you can log onto O365 as an administrator. This authentication method also supports MFA if you have that enabled.

Finally, we can change the user’s UPN by issuing the following command

Set-MsolUserPrincipalName -UserPrincipalName mary.osgood@contoso.onmicrosoft.com -NewUserPrincipalName mary.smith@contoso.com

Resources

Microsoft TechNet Article on how to connect to Office 365 PowerShell – Section “Connect with the Microsoft Azure Active Directory Module for Windows PowerShell”

Categories: Tech

Tags: Active Directory, AD, Azure, Azure AD, Microsoft, o365, office 365, powershell, UPN, User Principal Name