Office 365: Script to bulk change the UserPrincipalName to match the Email Address

UPDATE: See this link for the updated version of this blog post.

When you are preparing your local Active Directory, to be synced with Office 365, one of the things you should consider is to make the UserPrincipalName of each user you are syncing to match the user’s email address. Why? Because that is going to be his UserPrincipalName and his primary SMTP address on Office 365.

So there are different ways of achieving this, some more manual than others. The procedure I am going to outline today on this blog post is a two step procedure:

Step 1: Export all UserPrincipalNames and Email Addresses from the local AD to a CSV File.

Step 2: Use that CSV file to bulk change the UserPrincipalNames to match those Email Addresses.

Like I said there are different ways of doing this, and I will probably develop a more elaborated script that can do this in a single step. The reason I went for this two step process is because most of the times customers want to check the CSV generated on step 1, and remove all the users that they don’t want to change the UPN, because those users will not be synced to Office 365.

Before we detail the steps above, make sure that you’ve added additional UPN domain suffixes for all the primary SMTP domains that you will have. See the article “How to add UPN suffixes to a forest” for more information.

Also have a detailed read on the article “Prepare to provision users through Directory Synchronization to Office 365”, to fully understand all the tasks you have to do to prepare your local Active Directory.

Making the UPN’s match the email addresses and have a domain that is validated on Office 365 is just one of the several tasks you have to do.

Now back to the two step process to change those UPN’s.

Step 1:

On step one all you have to do is open a PowerShell module on your local AD, and run the cmdlet below.

#Make sure you Import the Active Directory Module into your PowerShell session before you run the cmdlet

Import-Module ActiveDirectory

#Run the cmdlet to export all the users to a CSV. Change the CSV name and path as appropriate

Get-AdUser -Filter * -Properties UserPrincipalName, Name, EmailAddress | Select-Object UserPrincipalName, Name, EmailAddress | Export-CSV -Path C:\MyADUsers.csv -NoTypeInformation

After you run the cmdlet you should get a CSV like the one shown below:


On the example above you can see that the UserPrincipalName does not match the user’s email address, and therefore needs to be changed.

Once you get the CSV check all users that you want to change and remove from that CSV the ones that you don’t.

Step 2:

Now that you have the CSV with all the users you want to change, all you have to do on step 2 is run the script below. The script will change all the UPN’s to match the email address, based on the CSV file you will use.

#Script to Change the UPN on the Active Directory#
#This script should run from an Active Directory Module for Windows PowerShell#
#Version 1.0 – 06/30/2015#
#Author: Antonio Vargas#

$UserCount = 0

Import-Csv -Path C:\MyADUsers.csv | ForEach-Object {

$UPN = $_.UserPrincipalName
Write-Host “Working on user:” $UPN
Get-ADUser -Filter {UserPrincipalName -Eq $UPN} | Set-AdUser -userprincipalname $_.EmailAddress
$usercount = $usercount +1
Write-Host “Number of users on your CSV: $UserCount”
Write-Host “UPN’s Changed”

Copy the entire content above into a notepad, and save it as a .ps1 file.

The script above is a very simple script that will read from the CSV. Before you run the script make sure you import the Active Directory module, as described on step 1, into your PowerShell session.

I highly recommend running the script first against a small group of up to 5 users, and then make sure that the changes were applied successfully. Also you need to take into account that you are changing the UserPrincipalName of the user on your local Active Directory, so make sure to test the access to all internal systems that rely on AD for authentication, before you replicate the change to all of your users.

As always, if you have any questions please let me know.


15 thoughts on “Office 365: Script to bulk change the UserPrincipalName to match the Email Address

  1. Narendra July 20, 2016 / 11:58 am

    I run the above script but user is not changing into the active directory.

    Kindly help us.

  2. Craig November 28, 2016 / 6:00 pm

    Not working for me either

  3. bas March 14, 2017 / 3:00 pm

    works like a charm from a domain controller.

  4. Ed Dunn July 27, 2017 / 7:19 pm

    does not work on Windows Server 2016 standard with AD role

    • Jack August 17, 2017 / 3:10 pm

      you probably need to add a -delimiter “chartomachyourcsv”

      • Jack August 17, 2017 / 3:12 pm

        try something like this first:
        $UserCount = 0
        Import-Csv -Path C:\yourfile.csv -delimiter “;” | ForEach-Object {
        $UPN = $_.UserPrincipalName
        Write-Host “Working on user:” $UPN
        this will only print out the upn:n, it does not change anything.. then you can apply the changes to your script…

  5. Gareth June 21, 2018 / 8:49 pm

    This does not work for me, whether on my machine via Powershell/SE run as admin or run on a DC. All it does is display the code in the script. Even removing the CSV and for each and setting the variables to static values doesn’t work

  6. boyinbilbao October 18, 2018 / 12:58 pm

    Just wanted to say this worked an absolute treat for me. Thanks a lot.

    • Antonio Vargas October 18, 2018 / 1:06 pm

      Great to know. Thanks!!

  7. Jorge July 16, 2019 / 3:07 pm

    Puedes ayudarme, necesito hacer esto pero par cambiar el atributo proxyAddresses (SMTP)

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s