How To Change UserPrincipalName with PowerShell

Imagine a scenario where you work for an organization that has just changed it name to something more user friendly. One of things that are asked of the SysAdmins is that they want to be able to change all UserPrincipalNames from the previous UPN Domain Suffix to the New UPN Suffix. This article will focus on how to change UserPrincipalName with PowerShell.

Requirements

If you’re wanting to change the UPN suffix for your users there are a couple of things needed to make that happen. Let’s list that down now.

• Permissions to modify AD Accounts
• The UPN Suffix is added to your Domain

Add A New UPN Suffix to Active Directory

As mentioned in one of the requirements, you’ll need to add the UPN suffix to be able to set it correctly. Seems pretty obvious right! We’ll walk through how to do that.

• Open Active Directory Domain and Trusts console
• Right click Active Directory Domain and Trusts -> Properties
• Add the domain you would like to use

As you can see from the screenshot above, I added the domain thesysadminchannel.com since this is what I want my users to login as. However, before we get to changing the UPN for our users, let’s first validate that the domain suffix is available and correctly added to Active Directory.

Get Domain Suffixes Currently In AD

As ironic as it seems, the Domains and Trust console is where we can confirm if the domain is added. Nonetheless, we’ll take it a step further and verify this action dynamically using PowerShell. This way if you want to automate your account creation, this will help get you started on the right track. Spoiler alert: This uses the Get-ADForest cmdlet.

#Get UPN Suffix using Powershell
Get-ADForest | select UPNSuffixes

Change UserPrincipalName with PowerShell

Now for the bread and butter where we cover exactly how to change UserPrincipalName with PowerShell. We’ll go over multiple ways of setting the UPN suffix for a single user, multiple users in bulk or through a csv file that you can run the script against. Seems to pretty awesome right?!?!

Set The UPN Suffix For A Single User

In order to get an idea of how the change the UserPrincipalName, let’s run through an example of changing a single user that way you’re not overwhelmed right out of the gate. This article is primarily focused on doing it the “PowerShell” way, but sometimes it’s honestly a lot quicker to do it using the GUI if it’s just a one time thing. No need to spend extra cycles.

• Open Active Directory Users and Computers (ADUC)
• Search the user and open properties
• Click on the Account tab
• Under User Logon Name, click the drop down to specify the UPN suffix

Ok now that we got that out of the way, let’s set ourselves up for success and essentially do the same thing using Powershell.

#Change UPN for a single user using Powershell
$Domain = 'thesysadminchannel.com'
$User = 'ajolie'
Get-ADUser $User | select Name, UserPrincipalName

Name           UserPrincipalName
----           -----------------
Angelina Jolie [email protected]


Get-ADUser $User | Set-ADUser -UserPrincipalName "$user@$domain"
Get-ADUser $User | select Name, UserPrincipalName

Name           UserPrincipalName
----           -----------------
Angelina Jolie [email protected]

Change The UserPrincipalName For Bulk Users

Needing to be able to change a single user is great and all, however, what if we needed to change 1,000 users? 10,000 users in bulk? As an exercise, we’ll change the UPN for all users in a specific OU. This will allow us to see how to dynamically query AD users and modify their UPN without too much effort.

As a reference point, we’ll use Get-ADUser and filter by Organizational Unit so we can scope the target base. Just for good measure, it’s always a good to take an export (backup) of the user’s current settings. The UserPrincipalName is a primary attribute in Active Directory so at the very least, practice on a few test users or even a test Domain so you know exactly what the outcome is going to be. Let’s get started.

#Specify UPN Domain
$Domain = 'thesysadminchannel.com'

#Get list of samaccountnames in our targeted OU
$UserList = Get-ADUser -Filter * -SearchBase 'OU=Excluded,DC=ad,DC=thesysadminchannel,DC=com' | `
select -ExpandProperty SamAccountName

#Change UPN Suffix from sub domain to primary domain
foreach ($User in $UserList) {
    Get-ADUser $User | Set-ADUser -UserPrincipalName "$User@$Domain"
}

Get-ADUser -Filter * -SearchBase 'OU=Excluded,DC=ad,DC=thesysadminchannel,DC=com' | select Name, UserPrincipalName

Name               UserPrincipalName
----               -----------------
Isabella Contreras [email protected]
Director of IT     [email protected]
Arya Stark         [email protected]
Angelina Jolie     [email protected]
Melissa Zuniga     [email protected]

Use PowerShell to Change UPN Suffix from Csv File

An alternative method to changing users in bulk is to use a csv. You can format the csv anyway you want to but essentially we’re looking to import it and change the users based off of that. Let’s create sample csv.

The headers will be samaccountname,userprincipalname,name,enabled but we’ll mainly be relying on the samaccountname for out input.

Here is the code to be able update that as we did in our previous steps.

#Specify UPN Domain
$Domain = 'thesysadminchannel.com'

#Import csv to a csvList variable.
$csvList = Import-Csv 'C:\Users\pcontreras\csvList.csv'

#Change UPN Suffix from sub domain to primary domain using the csv file
foreach ($User in $csvList.samaccountname) {
    Get-ADUser $User | Set-ADUser -UserPrincipalName "$User@$Domain"
}

Conclusion

So hopefully this article was able to give you a pretty idea for being able to change UserPrincipalName with Powershell. The ability to change a UPN suffix in Active Directory will definitely come in handy if you’re making changes to your org.

As always, be sure to check out our other content full of Powershell Wizardry. Articles such as Get Active Directory Account Lockout Source Using Powershell or even our Youtube Channel for amazing video content