How to use UPN matching for identity synchronization in Office 365, Azure, or Intune


In some scenarios, you may have to transfer the source of authority for a user account if that account was originally authored by using Microsoft cloud services management tools. These tools include the Office 365 portal, Microsoft Azure Active Directory Module for Windows PowerShell, Azure Management portal, and Intune portal. You can transfer the source of authority so that the account can be managed through your local directory service when using identity synchronization with Azure Active Directory (Azure AD).

This article discusses how to perform this transfer of source of authority by using a process known as UPN matching. This process uses the user principal name (UPN) to match the on-premises user account to a work or school account in Azure AD.


UPN matching limitations

The UPN matching process has the following technical limitations:

  • UPN matching can be run only when SMTP matching fails. For more information about SMTP matching, see the following Microsoft Knowledge Base article:
    2641663 How to use SMTP matching to match on-premises user accounts to Office 365 user accounts for directory synchronization
    For UPN matching to work, make sure that there are no primary SMTP address matches between on-premises user accounts and user accounts in Azure AD.
  • UPN matching can be used only one time for user accounts that were originally authored by using Office 365 management tools. After that, the work or school account is bound to the on-premises user by an immutable identity value instead of the UPN.
  • The cloud user’s UPN can't be updated during the UPN matching process because the UPN is the value that's used to link the on-premises user to the cloud user.
  • UPNs are considered unique values. Make sure that no two users have the same UPN. Otherwise, the sync process fails, and you may receive an error message that resembles the following:
    Unable to update this object in Microsoft Online Services because the user principal name that is associated with this object in the local Active Directory is already associated with another object. To resolve this error, remove the associated object in your local Active Directory.

How to use UPN matching to match an on-premises user to a cloud identity

To start the UPN matching process, follow these steps:

  1. If you started syncing to Azure AD before March 30, 2016, run the following Azure AD PowerShell cmdlet to enable UPN soft match for your organization only:
    Set-MsolDirSyncFeature -Feature EnableSoftMatchOnUpn -Enable $True 
    Note UPN soft match is automatically enabled for organizations that started syncing to Azure AD on or after March 30, 2016.
  2. Obtain the UPN from the user account in Azure AD. To do this, use one of the following methods:

    Method 1: Use the Office 365 portal
    1. Sign in to the Office 365 portal ( as a global admin.
    2. Go to the users management page.
    3. Find and then click the user.
    4. Note the user name. This is the UPN.
    Method 2: Use the Azure Management Portal
    1. Sign in to the Azure Management Portal ( as a global admin.
    2. Click the Active Directory extension, and then select your directory.
    3. Go to the users management page.
    4. Find and then click the user.
    5. Note of the user name. This is the UPN.
  3. On a domain controller or a computer that has the Remote Server Administration Tools installed (RSAT), open Active Directory Users and Computers, and then create a user account or update an existing user account by using a user name/UPN that matches the target user account in Azure AD.

    For more information about how to do this, see Create a User Account in Active Directory Users and Computers.
  4. Force directory synchronization. For more information about how to do this, see Force directory synchronization.


For more information about UPN soft match, see Azure AD Connect sync service features.

Still need help? Go to Microsoft Community or the Azure Active Directory Forums website.

Article ID: 3164442 - Last Review: Dec 21, 2016 - Revision: 1