Insights Change User Principal Names to Match Email Addresses for Office 365 Migration

Change User Principal Names to Match Email Addresses for Office 365 Migration

Office 365 customers of a sufficient size will need to use Directory Synchronization and Active Directory Federation Services to make Office 365 both manageable and convenient for the end users.  When AD FS is used users will access Office 365 resources using their User Principal Names.  Microsoft recommends that User Principal names match users’ email addresses in order to make everything simpler for the average worker.  Instead of remembering different user names and formats for logging into different resources, users can be told to just log into resources with their email address and password.  Even if the Active Directory forest and domain use a .local domain suffix, you can still add additional suffixes for use with User Principal Names.  So, your user’s old login could be CONTOSOuser1, but their UPN could also be  Both formats will function equivalently when accessing AD and Office 365 resources. The problem with this is if you have a large environment and user principal names don’t match email addresses for hundreds or thousands of users currently in Active Directory.  Luckily, if you have Exchange 2007, 2010, or 2013 in your environment you can use PowerShell to quickly modify the UPNs of your users.  (If you have Exchange 2003 or earlier then you are out of luck; you’ll need to change the UPNs by hand or find some other way to script it.)  However, the first thing we need to do is verify that the SMTP domain your users use is available for use as a UPN suffix.

  • Start by opening Active Directory Domains and Trusts
  • Right click on the top level of the tree in the left pane and select properties
  • On the next menu make sure that every SMTP suffix used in your environment is included in the list of Alternative UPN suffixes
  • If any SMTP domains are missing from the list add them and click OK

Run the following command in the Exchange Management Shell to change the UPNs to match users email addresses:

Get-User | Where { -Not [string]::IsNullOrEmpty($_.WindowsEmailAddress) } | ForEach { Set-User -Identity $_.Guid.ToString() -UserPrincipalName $_.WindowsEmailAddress.ToString() }

When the command has completed you can verify if it was successful using Active Directory Users and Computers.  In my lab environment the user’s UPN originally looked like this:  

After running the script the User logon name field will be updated so that it matches the email address.  The User logon name field draws from the userPrincipalName attribute in AD.  

This should make the change for all the users, greatly simplifying the process of preparing AD for an Office 365 migration.