How to change UPNs in Active Directory and Office 365 in bulk with PowerShell Script

What is UserPrincipalName?

The UserPrincipalName attribute value is the Azure AD username for the user accounts.

A UPN consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). The prefix is joined with the suffix using the "@" symbol.

For example, "someone@example.com". A UPN must be unique among all security principal objects within a directory forest.

The UPN is used by Azure AD to allow users to sign-in. The UPN that a user can use, depends on whether the domain has been verified. If the domain has been verified, then a user with that suffix will be allowed to sign-in to Azure AD.

Important:

UPN in Azure AD is unique across the Azure AD Tenant and no two users can have the same UPN.

UPN for the users syncs only once via directory sync process (MIM and Azure AD Connect). Subsequent changes to UPN attribute for any users must be repeated in the Azure AD / Office 365 separately via GUI or PowerShell.

How to find UPNs for users in Office 365?

To get a list of the users with their UPNs, you can connect to Office 365 via PowerShell using M365 admin accounts and run the following cmdlets.

Import-Module MSONLINE

Connect-MSOLSERVICE

Get-msoluser -All | Select-Object DisplayName, FirstName, LastName, UsageLocation, UserPrincipalName, UserType, @{L = "ProxyAddresses"; E = { $_.ProxyAddresses -join ";"}} | Export-Csv -Path E:\Temp\MSOL_Users_25OCT2021.csv -NoTypeInformation

The script generates the following output file ‘E:\Temp\MSOL_Users_25OCT202.csv’. The cmdlets assume ‘E:\Temp\’ directory exists, and the user has ‘write’ access to the location. You can change this path to suit your preferences.

To check a single user, just run one simple cmdlet (after connecting to PowerShell):

Get-msoluser -UserPrincipalName <username> | Select-Object DisplayName, FirstName, LastName, PreferredLanguage, UsageLocation, UserPrincipalName

How to Change UPN for users

Changing UPN for users synced from the local AD is a two-step process. Changes done to UPN in the local AD cannot be synced automatically to the cloud via directory synchronization services like Microsoft Identity Manager or Azure AD Connect.

1. Change the UPN in the local AD
2. Change the UPN in the Azure AD

Step 1: Change the UPN in the local AD

Changing UPN in the Local AD is can be done from AD management tools such as Active Directory Administration Center, Active Directory Users and Computers (dsa.msc) or ADSI Edit.

Changing Single user:

To change a single user, update the AD attribute via the GUI tools or PowerShell.

To change multiple uses at once, PowerShell is recommended.

·     Note: Following the change in the local AD, continue to step 2 to make change in the Azure AD too. If the users you are changing are ‘in-cloud’, skip directly to step 2.

Changing multiple users (in bulk): There are multiple methods are doing this in bulk. Two have been included for this guide.

Method 1: By CSV file

1.      Prepare CSV file of users in the below format. Save the file as ‘Change-UPN-AD-Users.csv’. You can use any other file name. Just remember to use it in the next step if you change it.
Example CSV format:

SamAccountName	NewUserprincipalname
sandeep.verma	Sandeep.verma.NEWUPN@domain.com

 

2.  Type the following and hit enter when completed:

Import-Module ActiveDirectory

Import-Csv .\Change-UPN-AD-Users.csv | foreach-object {
Write-host “Changing UPN for user $($_.SamAccountName) to $($_.NewUserPrincipalName)” -Foregroundcolor Cyan

Set-ADUser -identity $_.SamAccountName -userprincipalname $_.Newuserprincipalname }

3.   Verify by GUI or PowerShell.

Import-Csv .\Change-UPN-AD-Users.csv | foreach-object {Get-ADUser -identity $_.SamAccountName | Select SamAccountName, UserPrincipalName

Method 2: By OU

You can also make changes to UPNs at OU level i.e. all users in the OU you select will get changed to a new domain name you specify. For example, all users un the test OU ‘TestOU’ have ‘vermasandeep.local’ as the UPN suffix and need to be changed to the UPN suffix ‘vermasandeep.in’.

1.      Open PowerShell ISE with appropriate admin permissions.

2.      Type the following and hit enter when completed (change $ou and $server as your OU and Server names):

Import-Module ActiveDirectory

$oldSuffix = "vermasandeep.local"

$newSuffix = "vermasandeep.in"

$ou = "OU = TestOU, DC=VERMASANDEEP, DC=local"

$server = "DCM1"

Get-ADUser -SearchBase $ou -filter * | ForEach-Object {

$newUpn = $_.UserPrincipalName.Replace($oldSuffix,$newSuffix)

$_ | Set-ADUser -server $server -UserPrincipalName $newUpn

}

Note: $oldSuffix represents the old domain UPN suffix. $newSuffix represents the new UPN suffix. $ou represents the search path in which and IT professional can use a specific OU or an entire domain.

3.      Verify by GUI or PowerShell.

$ou = "OU=TestOU,DC=VERMASANDEEP,DC=local"

Get-ADUser -SearchBase $ou -filter * | Select SamAccountName, UserPrincipalName

 

 Step 2: Change the UPN in the Azure AD

To change a single user’s UPN in the Azure AD, you can use the following cmdet.

Import-Module MSONLINE

Connect-MSOLSERVICE

Set-MsolUserPrincipalName -UserPrincipalName <Current UPN> -NewUserPrincipalName <New UPN>

For bulk changes, below mentioned PowerShell script is recommended.

1.      Prepare CSV file of users in the below format. Save the file as ‘Change-UPN-AzureAD-Users.csv’. You can use any other file name. Just remember to use it in the next step if you change it.
Example CSV format:

SamAccountName	NewUserprincipalName
sandeep.verma	Sandeep.verma.NEWUPN@domain.com

 

2.     Type the following and hit enter when completed:

        Import-Module MSONLINE

 Connect-MSOLSERVICE

 Import-Csv .\Change-UPN-AzureAD-Users.csv | foreach-object {

Write-host “Changing UPN for user $($_.UserPrincipalName) to $($_.NewUserPrincipalName)” -Foregroundcolor Cyan

Set-MsolUserPrincipalName -UserPrincipalName $_.UserPrincipalName -NewUserPrincipalName $_.NewUserPrincipalName }

3. Verify by GUI or PowerShell.

Import-Csv .\Change-UPN-AD-Users.csv | foreach-object {Get-ADUser -identity $_.SamAccountName | Select SamAccountName, UserPrincipalName

 

Note:

If you try changing the UPN from a managed domain to a federated domain, the following error will appear.

Set-MsolUserPrincipalName : You must provide a required property: Parameter name: FederatedUser.SourceAnchor

If you have such a scenario, leave a comment for help.

Checking results

Once the script above has been run successfully, use the following PowerShell cmdlets to check the new UPNs.

Import-Module MSONLINE

Connect-MSOLSERVICE

Get-msoluser -All | Select-Object DisplayName, FirstName, LastName, UsageLocation, UserPrincipalName, UserType, @{L = "ProxyAddresses"; E = { $_.ProxyAddresses -join ";"}} | Export-Csv -Path E:\Temp\MSOL_Users_25OCT2021.csv -NoTypeInformation