Change Users UPN with PowerShell

Overview

You want to synchronize your on‐premises users with Office 365. Before you do that, ensure you configure the UPN of the users in Active Directory (AD). In this article, you will learn how to add a UPN suffix and how to change AD users’ UPN with PowerShell.

Information

Any UPN that contains a non‐routable domain — for example john.doe@local — will be synchronized to a .onmicrosoft.com domain like john.doe@infotechninja.onmicrosoft.com. That is not how it should be.

If you currently use a .local domain for your user accounts in Active Directory, it’s recommended that you change them to use a verified domain. For example john.doe@infotechninja.com, to properly sync with your Office 365 domain.

Add UPN in AD

The first step is to add the UPN suffix in Active Directory.

1. Click Start and search for Active Directory Domains and Trusts, and click on it. You can also press Windows key + R to open the Run dialog, type domain.msc, and then choose OK.

2. On the Active Directory Domains and Trusts window, right‐click Active Directory Domains and Trusts at the root of the console, and then choose Properties.

3. On the UPN Suffixes tab, in the Alternative UPN Suffixes box, type your new UPN suffix, and then choose Add. Click OK when finished.

The UPN is added successfully.

Add UPN in AD with PowerShell

We can add the UPN suffix in AD with PowerShell.

Run PowerShell as administrator. Get a list of the UPN suffixes.

PS C:\> Get-ADForest | Format-List UPNSuffixes

UPNSuffixes : {}

It’s not showing any UPN suffixes. This means that it’s empty. Let’s add the UPN suffix.

PS C:\> Get-ADForest | Set-ADForest -UPNSuffixes @{add="infotechninja.com"}

Confirm that the UPN suffix is added successfully.

PS C:\> Get-ADForest | Format-List UPNSuffixes

UPNSuffixes : {infotechninja.com}

Change UPN for all AD Users

Now that we have set the UPN suffix in AD, we’d like to change the UPN for all the users in AD.

Let’s start by getting a list of all the AD users in the organization.

PS C:\> Get-ADUser -Filter * | Sort-Object Name | Format-Table Name, UserPrincipalName

Name           UserPrincipalName
----           -----------------
Administrator  administrator@infotechninja.local
Amanda Morgan  Amanda.Morgan@infotechninja.local
Amelia Nash    Amelia.Nash@infotechninja.local

Change the UPN for all the AD users in the organization. Run the commands one by one.

PS C:\> $LocalUsers = Get-ADUser -Filter {UserPrincipalName -like '*infotechninja.local'} `
            -Properties UserPrincipalName -ResultSetSize $null

PS C:\> $LocalUsers | foreach {
            $newUpn = $_.UserPrincipalName.Replace("infotechninja.local","infotechninja.com")
            $_ | Set-ADUser -UserPrincipalName $newUpn
        }

Confirm that the UPN is changed by running the Get-ADUser cmdlet.

PS C:\> Get-ADUser -Filter * | Sort-Object Name | Format-Table Name, UserPrincipalName

Name           UserPrincipalName
----           -----------------
Administrator  administrator@infotechninja.com
Amanda Morgan  Amanda.Morgan@infotechninja.com
Amelia Nash    Amelia.Nash@infotechninja.com

The UPN is successfully changed for all the users in the organization. If you’d like to change the UPN back to infotechninja.local, swap the arguments to Replace in the previous commands.

You may have a long list of users and want to verify there are no .local addresses left in AD. Get a list of all users with the .local UPN suffix — the output should be empty.

PS C:\> Get-ADUser -Filter {UserPrincipalName -like '*local'} | Sort-Object Name | Format-Table Name, UserPrincipalName

Change UPN for AD Users in a specific OU

You don’t have to change the UPN for every user. It’s possible to change the UPN for a specific OU.

Let’s start by getting a list of the AD users in a specific OU. We have an OU named Finance.

PS C:\> Get-ADUser -Filter * `
            -SearchBase "OU=Finance,OU=Users,OU=Company,DC=infotechninja,DC=local" |
        Format-Table Name, UserPrincipalName

Name              UserPrincipalName
----              -----------------
Madeleine Fisher  Madeleine.Fisher@infotechninja.local
Sebastian Nolan   Sebastian.Nolan@infotechninja.local
Irene Springer    Irene.Springer@infotechninja.local
Amelia Nash       Amelia.Nash@infotechninja.local
Jasmina Wilson    Jasmina.Wilson@infotechninja.local

Change the UPN for the AD users in the Finance OU. Run the commands one by one.

PS C:\> $LocalUsers = Get-ADUser -Filter {UserPrincipalName -like '*infotechninja.local'} `
            -SearchBase "OU=Finance,OU=Users,OU=Company,DC=infotechninja,DC=local" `
            -Properties UserPrincipalName -ResultSetSize $null

PS C:\> $LocalUsers | foreach {
            $newUpn = $_.UserPrincipalName.Replace("infotechninja.local","infotechninja.com")
            $_ | Set-ADUser -UserPrincipalName $newUpn
        }

Confirm that the UPN is changed by running the Get-ADUser cmdlet.

PS C:\> Get-ADUser -Filter * `
            -SearchBase "OU=Finance,OU=Users,OU=Company,DC=infotechninja,DC=local" |
        Format-Table Name, UserPrincipalName

Name              UserPrincipalName
----              -----------------
Madeleine Fisher  Madeleine.Fisher@infotechninja.com
Sebastian Nolan   Sebastian.Nolan@infotechninja.com
Irene Springer    Irene.Springer@infotechninja.com
Amelia Nash       Amelia.Nash@infotechninja.com
Jasmina Wilson    Jasmina.Wilson@infotechninja.com

The UPN is successfully changed for the Finance users. If you’d like to change the UPN back to infotechninja.local, swap the arguments to Replace in the previous commands.

You may have a long list of users in the OU — verify there are no .local addresses left. The output should be empty.

PS C:\> Get-ADUser -Filter {UserPrincipalName -like '*local'} `
            -SearchBase "OU=Finance,OU=Users,OU=Company,DC=infotechninja,DC=local" |
        Sort-Object Name | Format-Table Name, UserPrincipalName

Conclusion

You learned how to change users’ UPN with PowerShell — either across all of Active Directory or only inside a specific OU. Remember to verify your work when done.