Active Directory – Changing UPNs for all Domain Users

There are situations, specially if dealing with hybrid domain configurations, typically using Azure and on-premise Active Directory, where it will be needed to do a mass UPN suffix change for all domain users. A typical change in these cases it to change a domain name suffix which end with .local to a public domain name which ends with .com (usually): this change is necessary mainly for two reasons.

The first one is that Microsoft now tends, in business environments, to say to users to Log on with your Email Address, while usually users use the DOMAIN-NAME\USER-NAME logon type (when asked), so Microsoft is making the assumption that the domain user E-mail value and the UPN are the same.

The second one is that Azure, for example, does not allow, in hybrid environments, to use not-public suffix domains, such as .local, .loc, and so no.

However, for those who does not know what is a UPN, we can say that, in Active Directory Domain Services, the User Principal Name (UPN) attribute is a user identifier used for logging in, separate from a Windows domain login.

Usually, we can check the UPN value of a domain user by opening Active Directory Users and Computers administrative console on a domain controller (DC) machine.

We can check and change the UPN of a domain user by using the Account tab, in the User logon name section. An example is shown in the below screenshot:

A UPN consists of a UPN prefix (the user account name) and a UPN suffix (a DNS domain name). The prefix joins the suffix using the "@" symbol. So, basically, an UPN has the same structure (but not always the same meaning) of an e-mail address.

Users primary email addresses, or UPNs, might change for many reasons:

• Company rebranding.
• Employees moving to different company divisions.
• Mergers and acquisitions.
• Employee name changes.

An UPN address can also be set by using a PowerShell cmdlet:

import-module activedirectory
Get-ADUser -Filter * -SearchBase 'ou=<your ou>,dc=<your domain>,dc=' -Properties userPrincipalName | foreach { Set-ADUser $_ -UserPrincipalName ("{0}@{1}" -f $_.name,"<your UPN suffix>")}

The UPN address is also present in Microsoft 365 (ex Office 365), where it is assigned by default for any new user. We can check the UPN of an Microsoft 365 user by going in Users > Active users section in Microsoft 365 admin center (Office 365 admin center).

UPNs in Azure/Microsoft 365

Users sign in to Azure AD with the value in their userPrincipalName attribute.

When you use Azure AD in conjunction with your on-premises Active Directory, user accounts are synchronized by using the Azure AD Connect service. By default 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.

In Microsoft 365, you might stumble upon a problem where users' UPN suffixes are still in the domain.onmicrosoft.com format instead of your domain's suffixes (for example company.com). To solve this issue, you can edit the UPN addresses for Microsoft 365 users by using Azure Active Directory Module for Windows PowerShell:

Import Azure Active Directory Module for PowerShell:

Import-module MSOnline

Connect to Microsoft 365 by running this cmdlet:

$msolcred = get-credential
connect-msolservice -credential $msolcred

Change the UPN of the user:

Set-MsolUserPrincipalName -UserPrincipalName <current UPN> -NewUserPrincipalName <new UPN>

A possible way to change multiple users UPN is the following, on Microsoft 365 environment:

Import-module MSOnline
$msolcred = get-credential
Connect-msolservice -credential $msolcred

#Replace with the old suffix
$oldSuffix = 'old.suffix'

#Replace with the new suffix
$newSuffix = 'new.suffix'

Get-MsolUser | ForEach-Object {
$newUpn = $_.UserPrincipalName.Replace($oldSuffix,$newSuffix)
$_ | Set-MsolUserPrincipalName -NewUserPrincipalName $newUpn
}

Creating new UPN in Active Directory Domain

Before adding a new UPN suffix and changing it to our domain users, we need to make it available in the domain. This can be done by going in Administrative Tools > Active Directory Domains and Trusts and then right-clicking Active Directory Domains and Trusts > Properties > Add the new Suffix > Apply > OK.

We can add the UPN suffix in AD also with Powershell. Let's run PowerShell as administrator and get a list of the UPN suffixes.

PS C:\>Get-ADForest | Format-List UPNSuffixes

UPNSuffixes : {}

It’s not showing any UPN suffixes, this means that it’s empty. Let’s add the UPN suffix:

PS C:\>Get-ADForest | Set-ADForest -UPNSuffixes @{add="example.com"}

Confirm that the UPN suffix is added successfully:

PS C:\>Get-ADForest | Format-List UPNSuffixes

UPNSuffixes : {example.com}

What happens after UPN change?

The logon process of domain users on their systems will not change: usually, they will still log on with the DOMAIN-NAME\USER-NAME format, which uses the sAMAccountName property and not the User Logon Name value.

Another point to see is that the local cached copy of the profile is still named the same as the sAMAccountName, so users will be able still access their own data and files. Also for roaming profiles and home drive paths there will be no change on data and files side.

Pay attention that this change will affect users that were already logging into their machines with their pre-existing (default) UPN, so they would need to change their login names to the new UPN (or use the pre-Windows 2000 login name) before trying again to logon on their machine (Windows 10, for examples) again with the new UPN value.

Active Directory - Change UPN Suffix for All Users (Powershell)

In the following script code we will target a specific OU, but you can change the $ou parameter value to point at the root of the domain, and do all users at once.

Import-Module ActiveDirectory

$oldSuffix = "example.lan"
$newSuffix = "example.com"
$ou = "OU=test,DC=example,DC=lan"
$server = "DC01"

Get-ADUser -SearchBase $ou -filter * | ForEach-Object {
$newUpn = $_.UserPrincipalName.Replace($oldSuffix,$newSuffix)
$_ | Set-ADUser -server $server -UserPrincipalName $newUpn
}

The following Powershell code, an extended version of the above one, will also check if the new UPN we would like to add to the Domain already exists or not, and then will apply it to the users under a specific OU (this could be also the root domain path). It will also prepare before and after logs for the UPN changes and to which users it applied.

$ou = 'DC=example,DC=local'  
$newUPN = 'example.com'  
$Output = 'C:\Scripts\output\'  
  
# Output Logs
$before = 'Accounts_before_UPN_change.txt'  
$after = 'Accounts_after_UPN_Change.txt'  
  
$domain = Get-ADDomain  
$UPNsuffix = Get-ADforest $domain.dnsroot | Select UPNSuffixes  
$users = Get-ADUser -Filter * -SearchBase $ou -Properties userPrincipalName     
 
# Check if UPN already exist in domain, adding it if not.
if ($UPNsuffix.UPNSuffixes -eq $newUPN){  
Write-Host The UPN $newUPN is already know by domain -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
}  
Else{  
Set-ADForest $domain.dnsroot -UPNSuffixes @{Add=$newUPN}  
Write-host $newUPN is a new suffix. Adding now. -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
Write-Host $newUPN is now a available suffix in this domain -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
}  

Write-Host Accounts to process are $users.count -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
  
# Output Logs before the change.
Get-ADUser -Filter * -SearchBase $ou | select UserPrincipalName | Out-File -FilePath $Output$before  
Write-Host Writing $before with all accounts -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
Write-Host Starting to add the $newUPN to existing users in the defined OU -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
  
# Change UPN for all users
foreach ($user in $users){  
 Set-ADUser $user -UserPrincipalName "$($user.samaccountname)@$newUPN"   
 Write-Host Changing upn to "$($user.samaccountname)@$newUPN"  
 }  
   
# Output Logs after the change.
 Get-ADUser -Filter * -SearchBase $ou | select UserPrincipalName | Out-File -FilePath $Output$after  
 Write-Host Writing $after with all changed accounts -ForegroundColor Yellow  
    Start-Sleep -Seconds 2  
 Write-Host All accounts changed to suffix $newUPN -ForegroundColor Green