👨‍💻 How to modify a 'Userprincipalname' from PowerShell in Microsoft 365 or Azure AD?

What is PowerShell?

PowerShell is a command-line interpreter and environment developed by Microsoft for configuring and managing systems. It is based on the .NET Framework and provides a comprehensive set of cmdlets (command-line tools) for performing a wide variety of tasks, such as managing user accounts, installing software, and managing network configurations. PowerShell is part of several Microsoft products, including Windows and Office 365, and can be used by system administrators and other advanced users.

What is a UserPrincipalName (UPN)

A User Principal Name (UPN) is a unique identity for a user in Microsoft 365. It is used to identify and authenticate users within the Microsoft 365 environment. The UPN consists of two parts: an account name and a domain name.

The account name is the name of the user used to log into Microsoft 365. For example, this can be the name of the user, such as "johndoe" or "janedoe."

The domain name is the name of the domain to which the user belongs. For example, this can be the name of the company or organization, such as "contoso" or "fabrikam."

The UPN is used to determine which resources a user can access and which policies apply to the user. For example, if a user is logged in with the UPN"johndoe@contoso.com,"the user has access to all resources available to users in the "contoso.com" domain.

In summary, a User Principal Name (UPN) is a unique identity for a user in Microsoft 365. It is used to identify and authenticate users and to determine which resources and policies apply to the user. The UPN consists of an account name and a domain name.

How to modify a 'Userprincipalname' from PowerShell in Microsoft 365 or Azure AD?

Customizing UPNs or UserPrincipalNames can be useful to perform manipulations at scale when, for example, companies merge or get a new domain name.

These adjustments are not possible today in a practical way in the Office 365 Portal.

Install the MSOnline module

Install-Module -Name MSOnline

Connect to Azure AD with these 2 commands

Connect-msolservice

Enter your username & password

Changing a UserPrincipalname (UPN) via PowerShell

Set-MsolUserPrincipalName -UserPrincipalName DebraB@oldUPN.com -NewUserPrincipalName DebraBerger@365tips.be

You can customize multiple UPNs with multiple lines:

Set-MsolUserPrincipalName -UserPrincipalName = The current UPN
NewUserPrincipalName = The new UPN.

Example after these adjustments of the userprincipalname

In this screenshot you can see the after UserPrincipalname change via PowerShell.

See also these PowerShell tips

Starting Powershell for managing Microsoft 365
How to install Azure AD preview module with PowerShell?
Tutorial: How to create and manage Microsoft Teams using PowerShell?
How to install and use PowerShell 7 ? - Administrator tools