Modify UPN to match Primary SMTP address


You may have read a previous blog I wrote in which I explained a new feature in AADSync which allows you to use the Primary SMTP address as a username in Office 365, therefore allowing you to leave the UPN value unchanged. However this method is not without it’s problems, and during a recent Hybrid Deployment of Office 365 it was decided to instead change the UPN prefix and suffix to match the users Primary SMTP address.

The risk to be aware of here is that if one of your LOB applications or a Service Account is using the UPN for authentication, you will break authentication for this app/service.The customer in question was confident that this wasn’t the case, but just to be sure we changed the UPN for a few test users prior to rolling this change out.

To clarify, the users Pre-Windows 2000 and UPN logon prefixes were firstinitialsurname, for example, ECoates, whereas the Primary SMTP address was, for example, We wanted users to be able to login to Office 365 using their ’email address’, so we decided to change all UPNs to match. There are 2 commands that could be used to accomplish this. The end result of the commands was that the users UPN would be changed from ddixon@contoso.local to We also only wanted to change to be made to user accounts with a Primary SMTP address specified.


Either of the two below commands can be run to achieve this goal. However, before either of these commands are run, it is important to make sure that the UPN suffix you wish to be populated exists in AD Domains and Trusts. To do this, open AD Domains & Trusts, and right click on Properties.


Then enter the required domain, such as and click Add and Apply. This makes the alternate UPN suffix available for use in the domain.

Alternate UPN Suffix

The below commands need to be run from an elevated Exchange Management Shell prompt. It is up to you which to run.

Command 1

This command finds all users who have a Primary SMTP address and then sets the UPN to be identical to this. It will ignore any user who does not have a Primary SMTP Address.

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

I found this command to be a little hit or miss, but this may be due to the size of the user base I was working with.

Command 2

This command finds all users who have the specified UPN suffix (such as a non-routable suffix like contoso.local) and changes their UPN to match their Primary SMTP address. If a user has no Primary SMTP address, it will not change the properties of that user.

$users = Get-User –Filter {(UserPrincipalName –like '*@contoso.local')} 
$users | ForEach {Set-User –Identity $_.Guid.ToString() –UserPrincipalName $_.WindowsEmailAddress.ToString()}

My personal preference is to use Command 2 as I had the most success with it, however I would love to hear your feedback on which one worked best for you!

Once you have run the command you can then use the following command to discover if any users were not successfully modified:

Get-User –Filter {(UserPrincipalName –like '*@contoso.local')}


I have also used the following command after having some problems with command 2 on Exchange 2013 (errors regarding the filter expression):

$mbxs = Get-Mailbox | Where {$_.UserPrincipalName -like '@contoso.local'}
$mbxs | ForEach {Set-User –Identity $_.Guid.ToString() –UserPrincipalName $_.WindowsEmailAddress.ToString()}


Purge a user account from Office 365

Today I made a mistake and accidentally linked together a standalone Office 365 account with an account synchronised from Active Directory. The ‘in cloud’ user became linked to the AD account and became ‘synchronised with Active Directory’. This wouldn’t usually be a problem and is done by design if the two UPNs match each other. My main problem was that the ‘in cloud’ user already had a mailbox, and so did the user in AD. This leads to a split-brain scenario whereby both systems believe to be hosting the mailbox. As I was about to configure a Hybrid Deployment, this is not a good thing.

Luckily the Office 365 account did not hold any required information in Exchange Online or SharePoint/OneDrive. In order to clean up the objects I moved the affected user into an OU which was not being synchronised and then performed a delta sync. This moved the object in Office 365 into the Deleted Users container. A deleted user in Office 365 remains in this container for 30 days before it is removed, however I did not have the luxury of waiting this long.

In order to purge the user account from Office 365 completely, I went into Office 365 powershell and ran the following command:

Remove-MsolUser -UserPrincipalName –RemoveFromRecycleBin –Force

This purges the item from the Deleted Users container. In Active Directory, I then moved the user object back into it’s original OU, and forced a sync. This provisioned a new user in Office 365. When applying the license to said user, I was correctly informed that the on premise mailbox had not been migrated to Exchange Online. Success!

Allow login to Azure AD/Office 365 using Primary SMTP address

The new Directory Synchronisation tool from Microsoft, AAD Sync, went into General Availability a few weeks back. This new tool is toting new features such as Password Write-back, AD Attribute Filtering and multi-forest synchronisation. All in all it is a great replacement to the now defunct DirSync product.

One issue which AAD Sync allows you to solve is the use of UPNs for usernames in Azure Active Directory. A UPN appears as if it is an email address, and often AD user accounts have different UPNs to their Primary SMTP addresses. This can cause confusion for users who expect to be able to login using their email address, just like they would in any cloud service out there. You could change the users UPN to match this, however in some situations this is not possible, either due to existing applications which use the UPN or due to Security policies which do not permit internet routable UPN suffixes.

Before I explain how this works, I must say that this process should only be done on initial synchronisation as you could cause issues if you change this parameter on existing Azure AD instances. More information on the limitations and risks of doing this can be found here:

When you configure AAD Sync, you can select which username your AAD users receive based on particular AD attributes, for example, the Primary SMTP address. This allows us to give users with strange/non-conformed AD usernames (such as 17047dd) a useable and memorable AAD username which is the same as their Primary SMTP address (David.Dixon). This configuration is performed in the User Matching section of the configuration, and you must change the userPrincipalName attribute to use the mail attribute.

UPN Matching in AAD Sync

If your organisation is planning to use ADFS, this poses a problem as the authentication is performed on premise, and your users cannot authenticate using their SMTP address if their UPN is different! To get around this, we can configure ADFS to use the mail attribute for authentication, as per the article below.

There are a couple of issues with this concept of user provisioning and authentication in Office 365, particularly when hybrid deployments are in use. The first is that when users authenticate against ADFS internally using IWA, the UPN will be the authentication mechanism. For domain joined machines this is not a problem (as long as the ADFS hostname eg. is added to Trusted Sites in IE) however if a machine is non domain joined or outside of the internal LAN, the user will receive 2 authentication prompts, one against Exchange Autodiscover (using the UPN) and another to Office 365 once the Autodiscover redirection has taken place (using the Primary SMTP). The second issue is that ActiveSync devices cannot support double authentications and will need to be manually reconfigured to use when the users mailbox is moved.

For these reasons it is generally good practice to only implement this solution for migrations with no autodiscover redirection in place, such as pure Office 365 or cutover/staged migrations. It can be successfully used with either AADSync/DirSync w/ Password Sync or ADFS.

Quite often, a users UPN will be different from their Primary SMTP address, and this is a way to allow your Azure AD users to login using their Primary SMTP address without changing the User Principal Name, reducing confusion for the users and creating a more consistent experience.