Active Directory UPN Suffix: 4-Step Setup for Microsoft 365

An Active Directory UPN suffix is the part of a user principal name after the @, and adding a routable one such as contoso.com lets users sign in with the same name they use for e-mail and Microsoft 365. It is essential when the AD domain uses a non-routable name like contoso.local or corp.contoso.lan. This guide covers adding the suffix, changing user UPNs in bulk, the Microsoft 365 and Entra Connect implications, mail attributes and rollback.

Short answer: Run Set-ADForest -Identity contoso.local -UPNSuffixes @{Add='contoso.com'} as an Enterprise Admin, verify contoso.com in your Microsoft 365 tenant, then change each user’s UPN with Set-ADUser -UserPrincipalName. With Entra Connect, run a delta sync and the cloud UPN follows the on-premises value.

Which method to use

Task	GUI	PowerShell	Notes
Add a suffix to the forest	Active Directory Domains and Trusts	Set-ADForest -UPNSuffixes @{Add=…}	Forest-wide; Enterprise Admins
Change one user	ADUC » user » Account tab	Set-ADUser -UserPrincipalName	Fine for a few accounts
Change many users	ADUC multi-select (limited)	Get-ADUser | Set-ADUser loop	Back up old values first
Keep the UPN, sign in with e-mail	Entra Connect wizard	n/a	Alternate login ID; more moving parts

Prerequisites

• Membership of Enterprise Admins to add the suffix (it is stored in the configuration partition), and rights to write userPrincipalName on the user objects.
• A public domain you own. The Active Directory UPN suffix does not need DNS records in your AD DNS zones; it is a name, not a DNS zone.
• For Microsoft 365 hybrid: the same domain added and verified in the tenant, and access to the Entra Connect or Cloud Sync server.
• A list of applications that store UPNs: SaaS apps with SSO, VPN and RADIUS policies, certificate templates that put the UPN in the subject alternative name, and scripts.

Plan the change

Start with an inventory. This report shows which suffixes are actually in use in each domain, and how many accounts have no UPN at all:

foreach ($d in (Get-ADForest).Domains) {
    Get-ADUser -Filter * -Server $d -Properties UserPrincipalName |
        Group-Object { if ($_.UserPrincipalName) { $_.UserPrincipalName.Split('@')[-1] } else { '(none)' } } |
        Select-Object @{ n = 'Domain'; e = { $d } }, Name, Count
}

Then agree the rules before touching any account:

• Prefix format: first.last matching the e-mail address is the most common choice; decide how to handle duplicates and name changes.
• Several brands: a forest can hold several suffixes (contoso.com, fabrikam.com). Add each one, verify each in the tenant, and map users by company or OU.
• Pilot group: IT staff first, then one department, then everyone.
• Communication: tell users their sign-in name changes and that Office apps may ask them to sign in again.
• Provisioning: update onboarding scripts and templates so new accounts receive the new suffix from day one.

Step 1: Add the Active Directory UPN suffix

With Active Directory Domains and Trusts

1. Open Server Manager » Tools » Active Directory Domains and Trusts (domain.msc).
2. Right-click the top node, Active Directory Domains and Trusts, and choose Properties.
3. On the UPN Suffixes tab, type contoso.com under Alternative UPN suffixes, click Add and then OK.

With PowerShell

Set-ADForest -Identity contoso.local -UPNSuffixes @{ Add = 'contoso.com' }
Get-ADForest | Select-Object -ExpandProperty UPNSuffixes

Use Add, not Replace: @{Replace=…} overwrites the whole list and silently removes suffixes that other teams still use. The DNS name of every domain in the forest is always a valid suffix and does not appear in this list.

Once replication reaches the DC you are connected to, the new suffix appears in the drop-down next to User logon name on the Account tab in ADUC. If you have forest trusts, new suffixes also show up under Name Suffix Routing on the trust in the other forest, where they may need to be enabled before cross-forest authentication with that suffix works.

Adding an Active Directory UPN suffix changes nothing for existing users; it only makes the suffix available. You can add it days before the user migration.

Step 2: Verify the domain in Microsoft 365

If users are synchronised to Microsoft Entra ID, add and verify the domain before you change any UPN. In the Microsoft 365 admin center, go to Settings » Domains » Add domain, add the TXT record it gives you at your DNS host and complete verification.

This order matters. Microsoft documents that when the on-premises UPN suffix is verified in the tenant, the Entra UPN equals the on-premises UPN. When the suffix is not verified, Entra ID cannot use it and builds a UPN from the mailNickname value and the initial domain instead, for example jdoe@contoso.onmicrosoft.com. The same happens if the on-premises UPN contains invalid characters such as a space. That is why a .local suffix can never appear in the cloud.

A verified Active Directory UPN suffix is therefore the precondition for every step that follows. Check the domain status in the admin center, or with Get-MgDomain -DomainId contoso.com, whose IsVerified property must be True.

Step 3: Change user UPNs in bulk

For one user, open the Account tab, pick the new suffix from the drop-down and click OK. For many users, back up the current values and then change them with PowerShell:

$old = 'contoso.local'
$new = 'contoso.com'
$base = 'OU=Staff,DC=contoso,DC=local'
$users = Get-ADUser -Filter "UserPrincipalName -like '*@$old'" -SearchBase $base -Properties mail
# Backup for rollback
$users | Select-Object SamAccountName, UserPrincipalName, mail, DistinguishedName |
    Export-Csv C:\Scripts\upn-backup-$(Get-Date -Format yyyyMMdd).csv -NoTypeInformation -Encoding UTF8
foreach ($u in $users) {
    $newUpn = $u.UserPrincipalName -replace "@$([regex]::Escape($old))$", "@$new"
    if (Get-ADUser -Filter "UserPrincipalName -eq '$newUpn'") {
        Write-Warning "$newUpn is already in use, skipping $($u.SamAccountName)"; continue
    }
    Set-ADUser -Identity $u -UserPrincipalName $newUpn -WhatIf
}

ADUC can also change the suffix for a selection: select several users, open Properties, and on the Account tab tick UPN suffix and choose the new value. It keeps each prefix as it is, cannot check for duplicates and leaves no backup, so PowerShell is the better tool for more than a handful of accounts.

Remove -WhatIf when the output looks right. Start with a pilot OU of five to ten users, sync, and check sign-in before you change everyone.

Match the UPN to the e-mail address

If prefixes differ (UPN jdoe@contoso.local, e-mail john.doe@contoso.com), set the UPN from the mail attribute so users have one name for everything:

$users | Where-Object { $_.mail -like "*@$new" } | ForEach-Object {
    Set-ADUser -Identity $_ -UserPrincipalName $_.mail -WhatIf
}
# Accounts with no UPN at all (common for old accounts)
Get-ADUser -Filter 'UserPrincipalName -notlike "*"' -SearchBase $base |
    ForEach-Object { Set-ADUser -Identity $_ -UserPrincipalName "$($_.SamAccountName)@$new" -WhatIf }

The sAMAccountName does not change, so CONTOSO\jdoe logons, the SID, group memberships and Windows profiles are unaffected. Only sign-ins that use the UPN form change.

Step 4: Synchronise with Entra Connect or Cloud Sync

On the Entra Connect server, start a delta cycle rather than waiting for the scheduler:

Import-Module ADSync
Start-ADSyncSyncCycle -PolicyType Delta

What happens next, according to Microsoft’s documentation:

• Entra ID recalculates the cloud UPN only when an update to the on-premises UPN is synchronised. Changing only mail does not change the cloud UPN.
• The SynchronizeUpnForManagedUsers feature lets UPN changes flow to the cloud; Microsoft states it is on by default for newly created tenants and cannot be turned off once enabled; older tenants may need to enable it. Since March 2019, UPN changes for federated users also synchronise.
• If the new suffix is verified, the cloud UPN becomes identical to the on-premises value. If not, the user gets an onmicrosoft.com UPN.

Check the feature state from any machine with the Microsoft Graph PowerShell SDK:

Connect-MgGraph -Scopes 'OnPremDirectorySynchronization.Read.All' -NoWelcome
(Get-MgDirectoryOnPremiseSynchronization).Features.SynchronizeUpnForManagedUsersEnabled

With Microsoft Entra Cloud Sync the planning is the same: verify the domain first, change the UPN on-premises, and let the next provisioning cycle carry it to the cloud. After the change, users may be asked to sign in again in Outlook, Teams and OneDrive with the new name.

If you cannot change the on-premises UPN, for example because an application depends on it, Entra Connect supports an alternate login ID, such as the mail attribute, as the cloud sign-in name. It works, but you then maintain two identities per user, so changing the Active Directory UPN suffix is usually the cleaner choice.

Mail and proxyAddresses

A UPN change does not touch e-mail. Keep the three values consistent:

Attribute	Purpose	Example
userPrincipalName	Sign-in name	john.doe@contoso.com
mail	Primary e-mail shown in the directory	john.doe@contoso.com
proxyAddresses	All e-mail addresses; SMTP: in capitals marks the primary, smtp: marks aliases	SMTP:john.doe@contoso.com, smtp:jdoe@contoso.com

If an Exchange Server is still used to manage recipients (for example in an Exchange hybrid), change addresses with Exchange tools and e-mail address policies, not by editing attributes. Without on-premises Exchange, you can set the primary address with PowerShell and let Entra Connect sync it:

$addr = 'john.doe@contoso.com'
$u = Get-ADUser -Identity jdoe -Properties proxyAddresses
$list = @($u.proxyAddresses | Where-Object { $_.Substring(5) -ne $addr } |
    ForEach-Object { if ($_ -clike 'SMTP:*') { 'smtp:' + $_.Substring(5) } else { $_ } })
$list += "SMTP:$addr"
Set-ADUser -Identity jdoe -EmailAddress $addr -Replace @{ proxyAddresses = $list }

The script demotes the old primary to an alias, so mail sent to the old address still arrives.

What changes for users and applications

Area	Effect of a UPN change	Action
Windows sign-in with DOMAIN\user	None	None
Windows sign-in with the UPN	Users type the new UPN	Tell users; the old UPN stops working
Windows profile, groups, file permissions	None (SID-based)	None
Microsoft 365 apps	New sign-in name after sync	Users may need to sign in again
SaaS apps with SSO	Apps that match users by UPN may create a new profile or fail	Check the claim each app uses before the change
Certificates and smart cards	Certificates carrying the old UPN keep it until renewal	Review certificate mapping and reissue if needed
Scripts and service configuration	Hard-coded UPNs break	Search scripts for the old suffix

Verify it works

# On-premises
Get-ADUser -Filter "UserPrincipalName -like '*@contoso.com'" -SearchBase $base | Measure-Object
Get-ADUser -Filter "UserPrincipalName -like '*@contoso.local'" -SearchBase $base | Select-Object SamAccountName
# In the cloud, after a sync cycle
Connect-MgGraph -Scopes 'User.Read.All' -NoWelcome
Get-MgUser -UserId 'john.doe@contoso.com' -Property UserPrincipalName, Mail, OnPremisesUserPrincipalName |
    Select-Object UserPrincipalName, Mail, OnPremisesUserPrincipalName

Then sign in as a pilot user on a domain-joined PC with the new UPN, and at https://myaccount.microsoft.com. Check the Entra Connect Synchronization Service Manager for export errors on the pilot objects.

Troubleshooting

Symptom	Cause	Fix
New suffix missing from the ADUC drop-down	Not replicated yet, or ADUC opened before the change	Wait for replication; reopen ADUC
Cloud UPN became …@tenant.onmicrosoft.com	Suffix not verified in the tenant, or invalid characters	Verify the domain, fix the value, then change the on-premises UPN again so the update is synchronised
Cloud UPN did not change at all	No sync yet, or UPN sync feature not enabled	Run a delta sync; check SynchronizeUpnForManagedUsersEnabled
“UPN already in use” warning	Another account, or a contact in another domain, has the same UPN	Choose a different prefix; UPNs must be unique in the forest
An application login fails after the change	App stores the old UPN	Update the account mapping in the app, or roll back that user
Set-ADForest fails with access denied	Not an Enterprise Admin	Run as an Enterprise Admins member

Roll back

Restore the old UPNs from the backup CSV:

Import-Csv C:\Scripts\upn-backup-20260930.csv | ForEach-Object {
    Set-ADUser -Identity $_.SamAccountName -UserPrincipalName $_.UserPrincipalName -WhatIf
}

Be careful in hybrid setups: if the old suffix was .local or otherwise unverified, synchronising the rollback gives users an onmicrosoft.com cloud UPN, not their previous cloud name. Roll back only the affected users, and only after checking what their cloud UPN will become.

To remove an Active Directory UPN suffix that is no longer needed, first confirm no account uses it, then remove it without touching the rest of the list:

foreach ($d in (Get-ADForest).Domains) {
    Get-ADUser -Filter "UserPrincipalName -like '*@contoso.com'" -Server $d -ResultSetSize 5 | Select-Object UserPrincipalName
}
Set-ADForest -Identity contoso.local -UPNSuffixes @{ Remove = 'contoso.com' }

Removing a suffix does not change the UPNs of existing users, so always clean up the accounts first. With the suffix added, the domain verified and a tested bulk script, moving to a routable Active Directory UPN suffix is a low-risk change you can complete one OU at a time.

Active Directory UPN suffix at a glance

Official documentation: Set-ADForest (ActiveDirectory module), Microsoft Entra UserPrincipalName population, Microsoft Entra Connect Sync service features.

Related guides: Bulk create AD users from CSV with PowerShell · Get-ADUser PowerShell examples · Install Active Directory on Windows Server 2025: New Forest Step by Step.

Frequently asked questions

Maintenance record

This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.

Maintained by

srvScripts editorial team

Last full review

3 Oct 2026

Next review

1 Apr 2027

Sources

learn.microsoft.com/en-us/powershell/module/activedirectory/set-adforest
learn.microsoft.com/en-us/entra/identity/hybrid/connect/plan-connect-userprincipalname
learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-syncservice-features