Add User Principal Names in Active Directory via PowerShell

Summary: Microsoft Scripting Guy, Ed Wilson, shows how to use Windows PowerShell to add user principal names to users in Active Directory.

Hey, Scripting Guy! Question Hey, Scripting Guy! We are planning for our Active Directory migration, and as part of that, I am reviewing users. The problem is that I found out that whoever set up our original installation did not assign values for user principal names (UPN). This will cause us a problem as we move to a federated environment. Can you offer an easy way to populate this value?


Hey, Scripting Guy! Answer Hello CG,

Microsoft Scripting Guy, Ed Wilson, is here. This morning I am sitting on our lanai and checking my email on my Microsoft Surface RT. I received an email from one of my friends in Hawaii. He was telling me about a Hukilau he went to over the weekend. From his description, it makes me want to grab the Scripting Wife and head out west on the next available flight. The big problem right now, is the weather. I prefer August in Australia to August in Hawaii—it is really hot there.

In Active Directory Users and Computers, the UPN shows up as the user logon name. It displays the UPN in two different fields, as shown in the following image.

Image of menu

To find the actual Active Directory attribute name, I add a bunch of AAAs to the user logon name, and select a domain from the drop-down list. I then go into ADSI edit and look up the value. I see the following:

Image of menu

Searching for existing values

I use the Get-ADUser cmdlet to look for existing values for the UserPrincipalName attribute. To find the value of the UserPrincipalName attribute, I have to specify it for the –Properties parameter. I specify the SearchBase of the organizational unit (OU), and I use the * filter. This is shown here:

Get-ADUser -Filter * -SearchBase 'ou=testou,dc=iammred,dc=net' -Properties userPrincipalName

The command and associated output are represented in the following image.

Image of command output

Setting the UPN value

I use the Get-ADUser cmdlet to retrieve all the users to set. I pipe the resulting user objects to the Foreach-Object cmdlet, and in the script block, I use the Set-ADUser cmdlet. The Set-ADUser cmdlet has a –userPrincipalName parameter that makes it easy to set the UPN.

To create the UPN, I use a hardcoded domain name, and I get the user’s name from the Name attribute. I use parameter substitution and the –f format specifier to concatenate the user principal name. The command is shown here (this is a single-line command that I broke at the pipe for readability):

Get-ADUser -Filter * -SearchBase 'ou=testou,dc=iammred,dc=net' -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName ("{0}@{1}" -f $,"")}

CG, that is all there is to using Windows PowerShell to add the UPN for user accounts. Active Directory Week will continue tomorrow when I will talk about more cool Windows PowerShell stuff.

I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.

Ed Wilson, Microsoft Scripting Guy 

Comments (18)

  1. Anonymous says:

    Thank you for good article. And I thought somebody might find it useful for updating the suffix but leaving the left side as is. So for userPrincipalName construct i use this to change from @old.domain to @new.domain:
    foreach { Set-ADUser $_ -UserPrincipalName (“{0}@{1}” -f $_.userPrincipalName.Split(“@”)[0],”new.domain”)

  2. Anonymous says:

    Good call @WalterFMB 🙂

  3. Anonymous says:

    Hi Ed,

    is it really a dot between {0} and {1} when concatenating the UPN?

    I'd think it should be a "@"


  4. David Grand says:

    Ed, can you please confirm or reply to the comment from WalterFMB – I think Walter makes a good point about this:  ("{0}.{1}" -f $,"")} being ("{0}@{1}" -f $,"")}

    Or do we both have a misunderstanding about what is happeing in the part about {0}.{1}

    Thanks in advance.

  5. mredwilson says:

    @WalterFMB and @David Grand. Yes it is an @ sign.

    I have corrected the post, thanks for catching that typo.   Have a wonderful day!

  6. Adam Drayer says:

    I would also recommend using the sAMAccountName instead of Name.  The Name field may contain spaces and such and it makes more sense to use the windows login for the firstpart of the UPN.

  7. Tim says:

    What would the command look like if you chose to use the SamAccountName instead of the name field?

  8. Tilo Boehme says:

    Yes please update the text as people might screw up if not reading and thinking.
    sAMAccountName is the better bet
    Get-ADUser -Filter * -SearchBase ‘OU=Business,OU=TSO DEV System,DC=DEVAD002,DC=tsosolutions,DC=com’ -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName (“{0}@{1}” -f $_.sAMAccountName,””)}

  9. Stevenism says:

    How should the left side of the @ sign be coded if the UPN convention is

  10. Related Issue says:

    Hello everyone,

    I need to populate UPN names and the file where the domain name should be is blank. I was able to add in a new domain name and the drop down has two domain names. Now, I’m guessing prior to my addition of the second domain name, the field was blank. Could this be the reason? Second, is there a way to auto populate the field with my new domain name? I don’t want to have to use the drop down to select the new domain name.

    Can anyone help me out?

    Thank you,


  11. Lupe mejia says:

    I want to do all the affected users in the domain all at once. Not just specific OUs. Do I just leave out the searchbase parameter? Also, does this command change everything? or just the individuals which fields are empty?

  12. Pedro Henrique says:

    Guys, I want change this but change only after "@"
    Ex.: >>> to

    I don’t want change user logon name, only change domain. It’s possible?

  13. Dominic Irrcher says:

    I hate necro posting, but someone asked how to change the script if your upn format is firstname.lastname@, here it is: Get-ADUser -Filter * -SearchBase ‘dc=domain,dc=com’ -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName ("{0}.{1}@{2}"
    -f $_.givenname, $_.surname, "")}

  14. Inderjit says:

    Thanks a ton, this helped!!!

  15. Inderjit says:

    Changing only the domain name

    ***Replace ‘’ with your domain name

    Get-ADUser -Filter * -SearchBase ‘ou=nonAdmins,ou=User,ou=Administration,dc=do,dc=local’ -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@DOMAIN.COM"}

  16. Steven Yurgelevic says:

    How could this been done but add the SMTP: and smtp: in front of the names for the proxy address?

  17. Behrang says:

    Thanks for this awesome explanation. I want to change the UPNs to be same as their email addresses but when I change the “name” attribute to “mail” or “proxyAddresses” attribute in the Powershell command it doesn’t work. Can anyone let me know why those attributes doesn’t work?

Skip to main content