[Updated Version] Office 365: Script to bulk change the UserPrincipalName to match the Email Address

As I was seeing a lot of feedback in my original post, regarding how the scripts below had issues, I decided to post this new updated version. I will underline the updates  to be easier to follow, but if you never read the original post, please try not to skip any parts in this one.

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.

#If needed 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 | ? {$_.UserPrincipalName -notlike "DiscoverySearchMailbox*" -and $_.UserPrincipalName -notlike "HealthMailbox*" -and $_.UserPrincipalName -notlike "SystemMailbox*" -and $_.UserPrincipalName -ne $null} | Select-Object UserPrincipalName, Name, EmailAddress | Export-CSV -Path C:\MyADUsers.csv -NoTypeInformation
UPDATE: I’ve added some additional filtering in this cmdlet, specifically to filter out users that don’t have a UserPrincipalName, or users for some types of Exchange system mailboxes such as the discovery search or health mailboxes. You do not want to run the script to change UPNs for system users or any user which is not a regular user that will be syncing up to Office 365. Make sure you filter the output file appropriately before you use it to change the UPNs. Below some example of users that you might still need to filter out from the output CSV.
UPNUpdate1

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

ChangeUPN1

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 2.0 - 06/22/2018

#Author: Antonio Vargas - antonio.vargas@myexchangeltd.co.uk

#Disclaimer: All scripts and other powershell references on this blog are offered "as is" with no warranty. While these scripts are tested and working in my environment, it is recommended that you test these scripts in a test environment before using in your production environment.

#Import the AD Module

Import-Module ActiveDirectory

#Static properties (change where needed)

$CSVPath = "C:\MyADUsers.csv"

#Count variables

$usersprocessed = 0

$userswitherrors = 0

$usersskipped = 0

#Import CSV

Try {

$CSV = Import-Csv -Path $CSVPath -ErrorAction Stop

}

Catch {

Write-Host "ERROR: Cannot import the CSV file. The script will abort. '$($Error[0].Exception.Message)'" -foregroundcolor Red

Exit

}

Write-Host "INFORMATION: The CSV was imported and you have '$($CSV.count)' users to be processed." -foregroundcolor Green

ForEach ($line in $CSV) {

$UPN = $line.UserPrincipalName

$Email = $line.EmailAddress

if ($UPN -eq $Email) {

Write-host "SKIPPING: The UPN '$($UPN)' matches the email address" -foregroundcolor Yellow

$usersskipped++

}

Else {

try {

$ADUser = Get-ADUser -Filter {UserPrincipalName -eq $UPN -and Enabled -eq $true} -ErrorAction Stop

If ($ADUser -eq $null) {

write-host "SKIPPING: The user '$($UPN)' is disabled or cannot be found." -foregroundcolor Yellow

$usersskipped++

}

Else {

Write-Host "Working on User '$($AdUser.UserPrincipalName)'" -foregroundcolor Yellow

try {

$result = Set-ADUser -Identity $ADUser.SamAccountName -Userprincipalname $Email -ErrorAction Stop

$usersprocessed++

Write-Host "SUCCESS: UPN Changed from '$($AdUser.UserPrincipalName)' to '$($Email)'." -foregroundcolor Green

}

catch {

Write-Host "ERROR: Cannot change the UPN of the user '$($AdUser.UserPrincipalName)'. '$($Error[0].Exception.Message)'." -foregroundcolor Red

$userswitherrors++

}

}

}

Catch {

Write-Host "ERROR: Cannot retrieve user '$($UPN)'. '$($Error[0].Exception.Message)'." -foregroundcolor Red

$userswitherrors++

}

}

}

write-host "`n"

write-host "############################# REPORTS ####################################" -foregroundcolor Green

Write-Host "REPORT: Total number of users processed with success '$($usersprocessed)'" -foregroundcolor Green

Write-Host "REPORT: Total number of users that were skipped for not meeting the criteria '$($usersskipped)'" -foregroundcolor Yellow

Write-Host "REPORT: Total number of users that failed to process '$($userswitherrors)'" -foregroundcolor Red

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

Some changes done to the script from the original blog post:

  • Error handling added
  • the script imports the Active Directory module
  • added count for users done with success, skipped or failed
  • small report at the end
  • the entire logic of the code on when to process users was changed 

Disclaimer: All scripts and other PowerShell references on this blog are offered “as is” with no warranty. While these scripts are tested and working in my environment, it is recommended that you test these scripts in a test environment before using in your production environment.

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.

For large environments, if you want a version of the script that exports to CSV all the user results (i.e changed, skipped, failed) feel free to send me an email via the blog.

Go ahead and test the script with its new changes and let me know how that goes.

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

Advertisements

Azure AD Connect: A quick way to check (online) the last time the sync ran

I was just doing some work in a devops work tenant, that usually has a Hybrid setup created and Azure AD Connect installed and running, and I realized that I needed to check when was the last time that:

  • the Directory synchronized successfully
  • Passwords synchronized successfully

As this is a very simple process I thought I should write a 5min blog post about it.

All you have to do is connect to the Azure Active Directory of your tenant and execute the Get-MSOLCompanyInformation.

ADConnectSyncTime

The 3 parameters that you want to look at are:

  • DirectorySynchronizationEnabled (this one is not mentioned above. It shows if the tenant has the synchronization enabled or not)
  • LastDirSyncTime
  • LastPasswordSyncTime

Hope that this information is helpful.

Office 365: Some quick notes on the end of support for Dirsync and Azure AD Sync

Earlier this week Microsoft announced the end of support for the legacy Microsoft Dirsync and Microsoft Azure AD Sync tools. Millions of customers out there use one of those two tools, or the new Microsoft Azure AD Connect, to sync their users, groups, passwords, etc, from their On-Premises Active Directory to the Azure AD.

After quite a few name changes, it looks like the Azure AD Connect major version is here to stay, and now it’s time to end support to the two older major versions, and make sure that all of them are updated and replaced with the AD Connect.

If you haven’t done it already, it’s time to read the Microsoft announcement, and to start planning that upgrade.

Now let’s take the key points of the Microsoft announcement:

  • In April 13th 2016 Microsoft announced the deprecation of both Dirsync and Azure AD Sync
  • The end of support for both versions of the sync tool was planned to be April 13th 2017. That date is now official with the announcement this week and in that day the official support to those tools is gone
  • Azure AD will stop accepting connections from both tools in December 31st 2017

The most relevant thing to take into account is that, either you upgrade those instances, or they will stop working by the end of this year.

Now that you are probably more than convinced to update your instance(s) for your customers or your infrastructure, let’s bullet point some thoughts to have into account when planning the upgrade:

  • Make sure you read the official Microsoft document to upgrade Dirsync to Azure AD Connect
  • Or make sure you read the official Microsoft document to upgrade Azure AD Sync to Azure AD Connect
  • You can only do in place upgrade from Azure AD Sync to AD Connect or from an old to a more recent version of AD Connect. In place upgrades from Dirsync are not supported
  • Microsoft describes the migration done with a parallel server, to replace the existing, as “Swing migration”
  • On a standard Dirsync or AD Sync instance, there’s nothing that you need to backup and restore in the new version. The new Azure AD Connect instance will do a fresh full sync after the installation. That full sync will bring all data from the local and the Azure AD. Replacing a Dirsync or an AD Sync instance should not require restoring data
  • The only exception to the above statement is when you have some type of filtering. Filtering can be done at the AD OU, Domain or attribute level. In those cases you need to make sure you replicate the filtering you have in place, into the new instance.
  • To learn more about Dirsync filtering click here.
  • To learn more about AD Sync and AD Connect filtering click here.
  • If you are not doing an in place upgrade, you need to be aware that the “downtime” on your sync instance has impact in creating new account and replicating changes to the existing ones (that includes password changes, if you have password sync enabled)

And that’s it. As simple as that. Start downloading the AD Connect version and it’s upgrade time! 🙂

Let me know if you have questions.