Let’s take a look at how we can update a users UPN (User Principal Name) in Office 365 using PowerShell. There are certain times when you may need to use PowerShell to complete this task, such as when you are using Active Directory sync and you need to change the users UPN after the initial sync has taken place.
In this post we are going to look at what the UPN is, in relation to a users account and how we can achieve said task of changing the UPN with PowerShell.
What is the UPN (User Principal Name)?
In Office 365, the UPN is the key attribute that defines the identity of a user account. The UPN (commonly referred to as the account username), is the address a user will use to sign in to their Office 365 account both in the web portal and client side applications. The UPN is defined in the cloud for in-cloud user account, or in your on-premise active directory if you are using Azure Active Directory Sync.
Should the UPN be the same as the primary email address?
In short, yes. It is good practice to ensure the UPN is the same as the users primary email address. If they are not the same it will cause confusion for both administrators and end users.
For users, they will be familiar with their primary email address as it is what they will be providing to people as it is what recipient will see when receiving emails. It will also show up in their Outlook and be visible to them at all times. If the user need to authenticate in the web or for a new activation, they may get confused as to what their login username should be.
For admins, it is likely that they will be administering more that one Microsoft 365 environment. This is common for managed IT providers with multiple clients. To simplify management and to ease the burden on the support team who did not do the initial configuration, the UPN and primary email address should be the same.
How to change a users UPN in Office 365 with PowerShell
Now let’s take a look at how we can make this change using the Microsoft Online PowerShell module!
Prerequisites
2. Ensure you allow the running of scripts in PowerShell. The following command will allow scripts to run in your current user context
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted 3. Install the Microsoft Online module
Install-Module -Name MSOnlineConnect to Microsoft Online
- Run the following command to connect to Microsoft Online. You will be prompted to sign-in on a new pop-up window. Ensure you log in with an account with the necessary permissions to make this change, the required permissions are User Admin or Global Admin.
Connect-MSOLserviceChanging the UPN for a single user
- Firstly identify the UPN you wish to change. In this scenario, we will change the UPN of user1 from [email protected] to [email protected].
Set-MsolUserPrincipalName -UserPrincipalName "[email protected]" -NewUserPrincipalName "[email protected]"2. Now check your change has worked. For this will use the get-msoluser command with the -SearchString parameter.
get-msoluser -SearchString "User-1"How to change a users UPN in Office 365 with Microsoft Graph PowerShell
1. Start by installing the Microsoft Graph PowerShell module, you can follow my quick guide here How To Install the Microsoft Graph PowerShell Module
2. Use the following command to change the UPN of a user.
Update-MgUser -UserId #OLDUPN '
-UserPrincipalName "#NEWUPN"You can use the above command to either change the prefix, domain or both
For more details scenarios on updating a single or multiple users UPN, see my guide on How to use Update-MgUser with Microsoft Graph PowerShell.
Summary
Thank you for taking the time to read my post on how to change a users UPN in Office 365 with PowerShell!
Be sure, if you have queries, to leave them in the comments below and I will respond as quick as I can.
