You are currently viewing Active Directory Migration: Fundamentals Pt 5 — userPrincipalName suffix considerations |  by Rick Gregson |  Coinmonks |  Oct, 2022

Active Directory Migration: Fundamentals Pt 5 — userPrincipalName suffix considerations | by Rick Gregson | Coinmonks | Oct, 2022

Change is never easy, but with proper planning and execution, it can be smoother. userPrincipalName (UPN) changes are no different. In this blog post, we will discuss the importance of UPN suffixes, benefits of UPN matching user email address, changing a UPN, as well as adding a UPN suffix. We will also present the relationship between the userPrincipalName suffix and the M365 Tenet as well as providing tips for common issues when UPN names are changed.

The userPrincipalName is an Internet-style login name for a user based on the Internet standard RFC 822. The UPN consists of the user’s logon name plus “@” plus the domain name where the user account resides. This gives the user a unique identity within their domain.

For example, the userPrincipalName “” would refer to the Active Directory user account for Prince. Prince’s sAMAccountName may be “Prince” and his email address may be “”.

As you can see, in most implementations, the userPrincipalName will match the email address.

The userPrincipalName may be used to sign in to on-premises as well as cloud-based services.

There are several benefits of changing your userPrincipalName to match your email address. First, it makes it easier for users to remember their login name. Second, it allows for a more seamless experience when accessing resources, both on-premises and in the cloud. Finally, it eliminates the need to update email addresses in multiple locations.

If you need to change a userPrincipalName, you can do so using the Set-User cmdlet. For example, to change Prince’s UPN from “” to “ theartistformerly”, you would use the following command:

Set-User -Identity “Prince” -userPrincipalName “”

You can also use this cmdlet to change the userPrincipalName for multiple users at once. To do this, you will need to create a CSV file with the following headers:



For example:

Create a CSV file containing the following:



You can then use the Import-CSV cmdlet to import the CSV file and pipe it into the Set-User cmdlet:

Import-CSV userprincipalnamechange.csv | Set-User -userPrincipalName {$_.userprincipalname}

Changing UPN suffixes can be more complicated and often comes into play during rebranding or some sort of M&A (merger/acquisition/divestiture) activity. One consideration that comes into play — UPN suffixes must be unique to a single forest throughout a Federated environment. This requirement for uniqueness often calls for creative interim solutions, such as using temporary UPN Suffixes during a migration, then cutting over to the desired suffix as the migration effort comes to an end.

Since this approach usually requires end users to re-establish Single Sign-On (SSO) credentials twice over a number of weeks or months, some end users may find it confusing and trying. While this approach can frustrate those users in the near-term, it allows for things to be stabilized and standardized for the long-term, improving the overall user experience, and meeting whatever business and technical requirements were deemed necessary at project onset.

Glad you asked!

userPrincipalName suffixes can be added to a Domain in the Active Directory Domains and Trusts console. To do this, open the console and select the Domain. Right-click on the Domain and select Properties. In the UPN Suffixes section, click Add and type in the desired userPrincipalName suffix. Click OK when finished.

You can also use powershell to add a new userPrincipalName suffix to a Forest. For example, to add “” as a UPN Suffix to a Forest, you could use the following commands:

Check present UPNSuffixes in the Forest

Get-ADForest | Format-List UPNSuffixes

Add a UPN Suffix to a Forest

Get-ADForest | Set-ADForest -UPNSuffixes @{add=””}

Then, of course, rerun your check to validate that the UPN Suffix was added successfully.

If it fails to add, ensure that it does not exist on any Trusted Domain or Forests already.

As we have indicated, the UPN suffix often matches the M365 Tenet Domain name. The M365 Tenet Domain name is the domain used in the primary SMTP address for user accounts and resources in an M365 or Exchange Online environment. This domain is also used to authenticate users when they sign-on to services such as Outlook, SharePoint Online, and OneDrive for Business.

A Vanity Domain is a custom domain that you add to your Microsoft 365 tenant to make it easier for your users to find and sign in to your services with a different email domain. For example, if you add the vanity domain to your tenant, you can give your users email addresses at

There are a number of issues that can crop up when userPrincipalName values ​​are changed. Here are some tips to help you avoid or resolve these issues:

1) If you change the userPrincipalName value for an account, you will need to update the UPN via Azure AD Connect to make sure the change is present in AAD. You can rely on Active Directory convergence and the Azure AD Connect synchronization cycle, or you can manually push the changes along.

2) Be aware that changing a user’s userPrincipalName can impact SharePoint Online, OneDrive, Teams, MS Authenticator, as well as other applications and resources where those users may have been granted access. Be sure to test and vet your process for impact. Have a tactical plan for remediation and execute to it.

3) When changing a user’s userPrincipalName, it is a good idea to do a full export of your user list beforehand. That way, you can reference the old UPNs if any issues come up during or after the change.

4) Changes such as these may impact user associations to Azure-joined devices as well as devices falling under Mobile Access Management (MAM). You may need to remove and rejoin devices to Azure AD as well as wipe device data and sign-on with updated credentials.

userPrincipalName changes are not to be taken lightly but can offer a number of benefits and may be required to achieve the desired outcome for the business. Plan and execute these changes with care, paying close attention to project requirements as well as user experience. Test, test, test! Have a solid plan for remediation in place in the event that something does go wrong.

Thank you for reading; we hope you found this article helpful! Please feel welcome to share this article as well as post any questions or comments here.

New to trading? Try crypto trading bots or copy trading

Leave a Reply