Change a UserPrincipalName (UPN) in Microsoft 365 and Entra ID

The UserPrincipalName (UPN) is a user's sign-in name in Microsoft 365, such as ann.peeters@contoso.com. You change it after a merger, a new domain name, a name change or a typo. For one user you can do that in the admin center; for dozens or hundreds of users you use PowerShell. This article covers both, with the current Microsoft Graph PowerShell module, and what to check first.

Check this first

• The new domain must be verified in your tenant.
• If the user is synced from Active Directory with Entra Connect, change the UPN in on-premises AD. You can't change it in the cloud.
• The email address doesn't change automatically. Update the primary SMTP address too if it should stay the same.
• The user's OneDrive URL changes. Shared links usually keep working, but shortcuts to the old address don't.

One user: in the admin center

1. Go to the Microsoft 365 admin center > Users > Active users and select the user.
2. Under the name, select Manage username and email.
3. Select the pencil next to the primary username, change the name and pick the domain.
4. Select Done and then Save changes.

With Microsoft Graph PowerShell

Install the module once, in PowerShell 7 or Windows PowerShell 5.1:

Install-Module Microsoft.Graph.Users -Scope CurrentUser

Connect with the right permissions. You need the User Administrator role or higher:

Connect-MgGraph -Scopes "User.ReadWrite.All"

Change the UPN of one user:

Update-MgUser -UserId "debra.b@oldcompany.com" -UserPrincipalName "debra.berger@contoso.com"

Check the result:

Get-MgUser -UserId "debra.berger@contoso.com" | Select-Object DisplayName, UserPrincipalName, Mail

Many users at once

Put the old and new names in a CSV file upn.csv:

OldUPN,NewUPN
ann.peeters@oldcompany.com,ann.peeters@contoso.com
tom.maes@oldcompany.com,tom.maes@contoso.com

And run:

Import-Csv .\upn.csv | ForEach-Object {
    try {
        Update-MgUser -UserId $_.OldUPN -UserPrincipalName $_.NewUPN -ErrorAction Stop
        Write-Host "OK: $($_.OldUPN) -> $($_.NewUPN)"
    } catch {
        Write-Warning "Failed: $($_.OldUPN) - $($_.Exception.Message)"
    }
}

To move all users of one domain, fetch them with Get-MgUser -All -Filter "endswith(userPrincipalName,'@oldcompany.com')" -ConsistencyLevel eventual -CountVariable n and replace the domain in the name.

After the change

• Users sign in with the new name from now on. Tell them Outlook, Teams and OneDrive may ask them to sign in again.
• On mobile devices and in the Authenticator app the old name can linger until the user signs in again.
• Applications that use the UPN as a fixed key, such as some SaaS apps with single sign-on, need the new name too.
• Preferably make the change outside office hours and test with one account first.

Read also

How to check your PowerShell version in Windows
How to create a distribution list in Microsoft 365 and use it in Teams
Which Microsoft 365 licence do I have? How to check

Nederlandstalige versie: De UserPrincipalName (UPN) wijzigen in Microsoft 365 en Entra ID

More in English