Plan and address principal user name changes in Azure Active Directory - Microsoft Entra (2023)

  • Article

The User Principal Name (UPN) attribute is an Internet communication standard for user accounts. A UPN consists of a prefix (user account name) and a suffix (DNS domain name). The prefix joins the suffix using the "@" symbol. For example, Ensure that the UPN is unique among security principals in a directory forest.


This article assumes that the UPN is the user ID. Addresses UPN change scheduling and recovery from issues that may arise from changes. For developers, we recommend using the userID objectID as an immutable identifier, rather than UPN or email addresses.

UPN and their changes

Login pages often ask users to enter an email address when the value is their UPN. Therefore, change the user UPN when their primary email address changes. The user's primary email address may change:

  • Rebranding
  • The employee moves to another department
  • Mergers and acquisitions
  • Change of employee name

UPN change types

Change the prefix, suffix, or both.

  • Change the prefix:
    • becomes
    • becomes
  • Change the suffix:
    • becomes or
    • becomes

We recommend that you change a user's UPN when their primary email address changes. During the initial synchronization from Active Directory to Azure AD, ensure that users' emails are identical to their UPNs.

UPN in Active Directory

In Active Directory, the default UPN suffix is ​​the DNS domain name where you created the user account. In most cases, you register this domain name as a corporate domain. If you create the user account in the domain, the default UPN is: However, you can add more UPN suffixes using Active Directory domains and trusted directory services. Learn more:Add your custom domain name using the Azure portal.

For example, if you add and change the user UPN and email address to reflect this, the result is:


If you change the suffix in Active Directory, add and verify a corresponding custom domain name in Azure AD.Add your custom domain name using the Azure Active Directory portal

Plan and address principal user name changes in Azure Active Directory - Microsoft Entra (1)

UPN in Azure Active Directory

Users are signed in to Azure AD with the value of the userPrincipalName attribute.

When you use Azure AD with your on-premises Active Directory, user accounts are synchronized using the Azure AD Connect service. The Azure AD login wizard uses the userPrincipalName attribute from the internal Active Directory as the UPN in Azure AD. You can change it to a different attribute in a custom installation.

(Video) Microsoft Entra / Azure AD 2 0 Explained with Full Demo


Define a process for updating a user principal name (UPN) for a user or for your organization.

When synchronizing user accounts from Active Directory to Azure AD, ensure that UPNs in Active Directory are mapped to verified domains in Azure AD.

Plan and address principal user name changes in Azure Active Directory - Microsoft Entra (2)

If the value of the userPrincipalName attribute does not correspond to a verified domain in Azure AD, sync replaces the suffix with

Mass UPN change available

Use our best practices to test bulk UPN changes. Have a tested recovery plan to reset UPNs if problems cannot be resolved. After running your pilot, target small sets of users, with organizational roles and sets of apps or devices. This process helps you understand the user experience. Include this information in your communications with stakeholders and users.

Learn more:Azure Active Directory deployment plans

Create a process to change UPNs for individual users. We recommend a process that includes documentation for known issues and workarounds.

Read the following sections for known issues and solutions when changing the UPN.

Implements known issues and solutions

Software as a service (SaaS) and line-of-business (LoB) applications often rely on UPNs to find users and store user profile information, including roles. Applications potentially affected by UPN changes use just-in-time (JIT) provisioning to create user profiles when users first log into the application.

Learn more:

  • What is SaaS?
  • What is Application Provisioning in Azure Active Directory?

Known issues

Changing the user UPN can break the relationship between the Azure AD user and the user profile in the application. If the application uses JIT provisioning, it may create a new user profile. The application administrator then makes manual changes to fix the relationship.


Use automated application provisioning in Azure AD to create, maintain, and remove user identities in supported cloud applications. Configure automated user provisioning in your applications to update UPNs in applications. Check applications to confirm they are not affected by UPN changes. If you are a developer, consider adding SCIM support to your application to enable automatic user provisioning.

Learn more:

  • What is Application Provisioning in Azure Active Directory?
  • Tutorial: Develop and design provisioning for a SCIM endpoint in Azure Active Directory

Managed known device issues and workarounds

Bringing your devices to Azure AD maximizes user productivity with single sign-on (SSO) across cloud and on-premises resources.

Learn more:What is Device ID?

(Video) Create a new user in Azure active Directory ||assign roles|| remove a role||Azure Active Directory

Azure AD connected devices

Azure AD connected devices connect to Azure AD. Users log in to the device using their organization's identity.

Learn more:Azure AD connected devices

Known issues and resolution

Users may experience single sign-on issues with applications that depend on Azure AD for authentication. This issue was fixed in Windows 10 May-2020 Update (2004).


Allow enough time for the UPN change to sync with Azure AD. After verifying that the new UPN appears in the Azure portal, have the user select the "Other User" tile to connect with their new UPN. You can verify using Microsoft Graph PowerShell. I see,Get-MgUser. After users log in with a new UPN, references to the old UPN may appearAccess to work or schoolWindows setup.

Plan and address principal user name changes in Azure Active Directory - Microsoft Entra (3)

Hybrid Azure AD joined devices

Hybrid Azure AD joined devices connect to Active Directory and Azure AD. You can implement Hybrid Azure AD connection if your environment has an on-premises Active Directory footprint.

Learn more:Hybrid Azure AD joined devices

Known issues and resolution

Windows 10 Hybrid Azure AD joined devices are likely to experience unexpected reboots and access issues. If users sign in to Windows before the new UPN is synced with Azure AD or continue to use a Windows session, they may experience single sign-on (SSO) issues with applications that use Azure AD for authentication. This condition occurs if conditional access is configured to force the use of hybrid connected devices to access resources.

Additionally, the following message may appear, which forces a restart after one minute:

Your computer will restart automatically in a minute. Windows has encountered a problem and needs to restart. You should close this message now and save your work.

This issue was fixed in Windows 10 May-2020 Update (2004).


  1. Disconnect the device from Azure AD and reboot.
  2. The device is joined to Azure AD.
  3. The user logs in by selecting itAnother usertile.

To disconnect a device from Azure AD, run the following command at a command prompt: dsregcmd /leave


The user is re-enrolled in Windows Hello for Business, if used.


(Video) Managed Identities with Azure AD (Active Directory) Tutorial

Windows 7 and 8.1 devices are not affected by this issue.

Mobile Application Manager Application Protection Policies

Known issues

Your organization can use Mobile Application Management (MAM) to protect corporate data in applications on user devices. MAM application protection policies are not resilient against UPN changes, which can break the connection between MAM registrations and active users in embedded MAM applications. This scenario could leave the data in an unprotected state.

Learn more:

  • Overview of application protection policies
  • Frequently asked questions about MAM and application protection


IT administrators can wipe data from affected devices after UPN changes. This forces users to re-authenticate and re-register with a new UPN.

Learn more:How to wipe only corporate data from apps managed by Intune

Microsoft Authenticator known issues and workarounds

Your organization may require the Microsoft Authenticator app to sign in and access apps and data. Although a username may appear in the application, the account is not a method of verification until the user completes registration.

Learn more:How to use the Microsoft Authenticator app

The Microsoft Authenticator app has four main functions:

  • Multi-factor authenticationwith push notification or verification code
  • Authentication brokeron iOS and Android devices fir SSO for apps that use mediated authentication
    • Enable cross-app SSO on Android using MSAL
  • Device registrationor workplace, join Azure AD, which is a requirement for Intune app protection and device enrollment/management
  • Phone input, which requires MFA and device registration

Multi-factor authentication with Android devices

Use the Microsoft Authenticator app for out-of-band verification. Instead of an automated phone call or SMS to the user at sign-in, MFA pushes a notification to the Microsoft Authenticator app on the user device. The user choosesApprove, or the user enters a PIN or biometric and selectsAuthenticate.

Learn more:How it works: Azure AD Multi-Factor Authentication

Known issues

When you change a user's UPN, the old UPN appears in the user's account and a notification may not be received. Use verification codes.

Learn more:Frequently asked questions about the Microsoft Authenticator app


If the notification appears, instruct the user to dismiss it, open the Authenticator app and selectCheck for notificationsand approves the MFA prompt. The UPN of the account is updated. Note that the updated UPN may appear as a new account. This change is due to other Authenticator features. For more information, see the known issues in this article.

Proxy authentication

On Android and iOS. brokers like Microsoft Authenticator enable:

  • SSO- Users are not logged in to every app
  • Device recognition- The broker accesses the device certificate created on the device when it was registered to the workplace
  • App authentication- When an application calls the broker, it passes its redirect URL and the broker verifies it

In addition, applications may participate in other features:

(Video) Azure Active Directory: Decommissioning ADFS

  • Azure AD conditional access documentation
  • Use Microsoft Authenticator or Intune Company Portal in Xamarin apps.

Known issues

Due to a mismatch between the login_hint passed by the application and the UPN stored in the broker, the user experiences more interactive authentication prompts in new applications that use broker-assisted login.


The user manually removes the account from Microsoft Authenticator and initiates a new sign-in from a broker-assisted application. The account is added after initial authentication.

Device registration

The Microsoft Authenticator app registers the device with Azure AD, which allows the device to authenticate to Azure AD. This registration is required for:

  • Intune app protection
  • Intune device enrollment
  • Phone input

Known issues

If you change the UPN, a new account with the new UPN appears in the Microsoft Authenticator app. The account with the old UPN remains in the list. Also, the old UPN is displayed in the Device Registration section of the app's settings. There is no change to Device Enrollment functionality or dependent scripts.


To remove references to the old UPN in the Microsoft Authenticator app, the user removes the old and new account from Microsoft Authenticator, re-enrolls in MFA, and reconnects the device.

Phone input

User phone sign-in to sign users in to Azure AD without a password. To enable this feature, the user enrolls in MFA using the Authenticator app and then enables dial-in to Authenticator. The device is registered to Azure AD.

Known issues

Users can't use dial-up because they don't get a notification. If the user choosesCheck for Notifications, an error appears.


The user selects the drop-down menu on the dial-in enabled account. The user then selectsTurn off dial-up connection. The dial-up connection can be reactivated.

Security key (FIDO2) known issues and workarounds

Known issues

When multiple users are registered to the same key, the login screen displays the account option where the old UPN is displayed. Connection with security keys is not affected by UPN changes.


To remove references to old UPNs, users reset the security key and register again.

Learn more:Enable security key login without password, Known issue, UPN changes

OneDrive known issues and solutions

OneDrive users have been known to experience issues after UPN changes.

Learn more:How UPN changes affect the OneDrive URL and OneDrive features

Teams Meeting Notes known issues and workarounds

Use team meeting notes to take and share notes.

Known issues

When a user UPN changes, meeting notes created with the old UPN are not accessible with Microsoft Teams or the Meeting Notes URL.


After changing the UPN, users can retrieve meeting notes by downloading them from OneDrive

  1. I'm going to youMy files.
  2. ChooseMicrosoft Teams data.
  3. ChooseWiki.

New meeting notes created after the UPN change are not affected.

(Video) Using Azure AD Join and Login with Microsoft Azure

Next steps

  • Azure AD Connect: Design concepts
  • Azure AD UserPrincipalName population
  • Microsoft Identity Platform Identifiers


Can I change the user principal name Azure? ›

The Azure AD Connect wizard uses the userPrincipalName attribute from the on-premises Active Directory as the UPN in Azure AD. You can change it to a different attribute in a custom installation.

What happens when you change a user's UPN? ›

After a UPN change, users will need to browse to re-open active OneDrive files in their new location. Any links to the files (including browser favorites, desktop shortcuts, and "Recent" lists in Office apps and Windows) will no longer work.

How do I change the principal name in Active Directory? ›

Changing the User Principal Name (UPN) in Active Directory

The easiest way to do it is to change UserPrincipalName in user properties in the ADUC console ( dsa. msc ). As you can see, all UPN suffixes of the domain are available in the list. Select the one you want and click OK.

What is the maximum length of user principal name in Azure AD? ›

The maximum length for an AAD username (without domain) is 64 characters. The maximum length for an AAD custom domain is 48 characters.

What is the difference between user name and user principal name? ›

Within Power BI Desktop, username() will return a user in the format of DOMAIN\User and userprincipalname() will return a user in the format of Within the Power BI service, username() and userprincipalname() will both return the user's User Principal Name (UPN). This looks similar to an email address.

How do I change my user name in Azure AD? ›

Go to Azure Active Directory > Users and select a user. There are two ways to edit user profile details. Either select Edit properties from the top of the page or select Properties. After making any changes, select the Save button.

Can you change a user logon name in Active Directory? ›

Open the Active Directory Users and Computers snap-in. In the left pane, right-click on the domain and select Find. Type the name of the user and click Find Now. In the Search Results, right-click on the user and select Rename.

How to change user name in Active Directory users and Computers? ›

In the Microsoft 365 admin center, select Users > Active users. Select the user from the list of active users. Select Manage contact information. Change the display name, and select Save changes.

What is the impact of renaming a user in Active Directory? ›

Using ADUS (Active Directory User Sycronizaiton) configured on a Domain Controller if you rename a User that is a member of the ADUS group it will cause the original user to be deleted and a new user created.

What is the user principal name in Active Directory? ›

In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. An example UPN is

How do I change the UPN for all the ad users in the organization? ›

On the Active Directory Domains and Trusts window, right-click Active Directory Domains and Trusts, and then choose Properties. On the UPN Suffixes tab, in the Alternative UPN Suffixes box, type your new UPN suffix, and then choose Add. Click OK when finished.

What is Azure principal user name? ›

In Microsoft's Active Directory the User Principal Name (UPN) is the unique sign in name or username, that uniquely identifies a user in the Directory. Microsoft uses Azure Active Directory (Azure AD) for all it's online business services (like Microsoft 365, Office 365, Dynamics 365, Power Apps, Azure, etc.)

What is the character limit for UPN name? ›

The maximum length of sAMAccountName is 20 characters due to pre-Windows 2000 restrictions, so if the account to be created has a long UPN or name, we will need to provide an alternative shorter name for sAMAccountName . Example: Name: over20charactersaccount. UPN: over20charactersaccount@ansible.local.

What is the length of UPN in Azure Active Directory? ›

Max length 64. The display name for the user. Max length 256. < > characters aren't allowed.

What are the three types of user accounts? ›

Standard User accounts are for everyday computing. Administrator accounts provide the most control over a computer, and should only be used when necessary. Guest accounts are intended primarily for people who need temporary use of a computer.

What is the difference between service principal name and managed identity? ›

Service principals can be used for automated processes like scripts, CI/CD pipelines, and other automation scenarios. The main difference between the two is that Managed Identity is tied to a specific Azure resource while Service Principal is a standalone identity.

What is the difference between service principal and user principal in Azure? ›

For a service, the security principal is called a service principal (and for a person, it is a user principal). This means that in order for a service to connect to resources in a subscription, it needs an associated service principal within that subscription's tenant.

What is entra Microsoft? ›

Microsoft Entra is the vision for identity and access that expands beyond identity and access management with new product categories such as cloud infrastructure entitlement management (CIEM) and decentralized identity.

Can a user name be changed? ›

Change username

In Settings, select Control Panel. Select User Accounts. In the User Accounts window, select Change your account name to change the username for your local Windows account.

How do I change my Azure AD user to local admin? ›

Browse to Azure Active Directory > Devices > Device settings. Select Manage Additional local administrators on all Azure AD joined devices. Select Add assignments then choose the other administrators you want to add and select Add.

How to change the user name and the logon name for a user record in Microsoft Dynamics CRM? ›

Open Microsoft Dynamics CRM as a System Administrator user. Select Settings, select Administration, select Users, and then open the user record that you want to change. In the Domain Logon Name box, type an Active Directory user account that is not used by a Microsoft Dynamics CRM user record.

Which of the following commands are used to rename a user? ›

usermod -l login-name old-name

We use the usermod command in Linux to rename user account.

What is the difference between AD user name and Displayname? ›

The Display Name is what shows up next to a user's comments, and does not need to be unique. The Username is a separate account identifier, and indicates the direct URL which can be used to visit a user's profile.

What are the user name attributes in Active Directory? ›

AD Attributes and JumpCloud
  • First name.
  • Last name.
  • Password.
  • Password expiration.
  • Email.
  • Username (logon name in AD)
  • User state.
Nov 29, 2022

How do I change the principal name of a user in Office 365? ›

In the Microsoft 365 admin center, select Users > Active users. Select the user from the list of active users. Select Manage contact information. Change the display name, and select Save changes.

What is the user principal name? ›

What is a User Principal Name (UPN)? In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. An example UPN is

What is Azure service principal account name? ›

An Azure service principal is an identity created for use with applications, hosted services, and automated tools to access Azure resources. This access is restricted by the roles assigned to the service principal, giving you control over which resources can be accessed and at which level.

How do I add a service principal name to a user? ›

To add an SPN, use the setspn -s service/name hostname command at a command prompt, where service/name is the SPN that you want to add and hostname is the actual host name of the computer object that you want to update.

What is the difference between UPN and logon name? ›

The userPrincipalName attribute is the logon name for the user. The attribute consists of a user principal name (UPN), which is the most common logon name for Windows users. Users typically use their UPN to log on to a domain. This attribute is an indexed string that is single-valued.

Where is UPN in Azure Active Directory? ›

New UPN in local AD domain

The setting cannot be found in the domain properties, but in the top node „Active Directory Domains and Trusts“.

What is service principal name format? ›

1. A service principal name (SPN) (2) is a string with the following format: serviceclass "/" hostname [":"port | ":"instancename] ["/" servicename] An SPN (2) consists of either two parts or three parts, each separated by a forward slash ("/").

What is the difference between Azure service principal and user account? ›

Service principals are special types of users that represent an Azure AD application. They have a system administrator role and use a client secret (a permanent password) to connect to data sources such as Dataverse. Service accounts are regular user accounts that have a username and password.

How do I create a service principal name in Azure? ›

App registration
  1. Navigate to the Azure portal.
  2. Select Azure Active Directory from the left-hand side menu.
  3. Select App registrations and + New registration.
  4. Enter a name for the application (the service principal name).
  5. Select Accounts in this organizational directory only.
  6. Then select Register.
Mar 24, 2023

What is the difference between Azure managed identity and service principal? ›

Managed Identity is suitable for scenarios where a single resource needs to access another Azure resource, while Service Principal is suitable for more complex scenarios where multiple resources need to access multiple Azure resources.


1. Azure AD App Registrations, Enterprise Apps and Service Principals
(John Savill's Technical Training)
2. Integrate Azure SQL with Azure Active Directory
3. Learn Microsoft Azure Active Directory in Just 30 Mins (May 2023)
(Andy Malone MVP)
4. Add custom domain in Azure Active Directory | add Company Branding for Azure AD tenant sign-in page
5. Syncing Users in Azure AD Connect: Master the Art of Seamless User & Group Integration
6. Microsoft Azure Active Directory Fundamentals Workshop | Azure AD | Dear Azure
(Kasam Shaikh)
Top Articles
Latest Posts
Article information

Author: Aron Pacocha

Last Updated: 06/18/2023

Views: 5765

Rating: 4.8 / 5 (68 voted)

Reviews: 91% of readers found this page helpful

Author information

Name: Aron Pacocha

Birthday: 1999-08-12

Address: 3808 Moen Corner, Gorczanyport, FL 67364-2074

Phone: +393457723392

Job: Retail Consultant

Hobby: Jewelry making, Cooking, Gaming, Reading, Juggling, Cabaret, Origami

Introduction: My name is Aron Pacocha, I am a happy, tasty, innocent, proud, talented, courageous, magnificent person who loves writing and wants to share my knowledge and understanding with you.