The UserPrincipalName attribute value
is the Azure AD username for the user accounts.
A UPN consists of a UPN prefix (the
user account name) and a UPN suffix (a DNS domain name). The prefix is joined
with the suffix using the "@" symbol.
For example,
"someone@example.com". A UPN must be unique among all security
principal objects within a directory forest.
The UPN is used by Azure AD to allow
users to sign-in. The UPN that a user can use, depends on whether the domain
has been verified. If the domain has been verified, then a user with that
suffix will be allowed to sign-in to Azure AD.
Important:
UPN in Azure AD is unique across the
Azure AD Tenant and no two users can have the same UPN.
UPN for the users syncs only once via
directory sync process (MIM and Azure AD Connect). Subsequent changes to UPN
attribute for any users must be repeated in the Azure AD / Office 365
separately via GUI or PowerShell.
To get a list of the users with their
UPNs, you can connect to Office 365 via PowerShell using M365 admin accounts and
run the following cmdlets.
Import-Module MSONLINE
Connect-MSOLSERVICE
Get-msoluser -All | Select-Object
DisplayName, FirstName, LastName, UsageLocation, UserPrincipalName, UserType,
@{L = "ProxyAddresses"; E = { $_.ProxyAddresses -join ";"}}
| Export-Csv -Path E:\Temp\MSOL_Users_25OCT2021.csv -NoTypeInformation
The script generates the following output
file ‘E:\Temp\MSOL_Users_25OCT202.csv’.
The cmdlets assume ‘E:\Temp\’ directory exists, and the user has ‘write’
access to the location. You can change this path to suit your preferences.
To check a single user, just run one simple
cmdlet (after connecting to PowerShell):
Get-msoluser -UserPrincipalName <username>
| Select-Object DisplayName, FirstName, LastName, PreferredLanguage,
UsageLocation, UserPrincipalName
Changing UPN for users synced from
the local AD is a two-step process. Changes done to UPN in the local AD cannot
be synced automatically to the cloud via directory synchronization services
like Microsoft Identity Manager or Azure AD Connect.
- Change the UPN in the
local AD
- Change the UPN in the
Azure AD
Changing UPN in the Local AD is can
be done from AD management tools such as Active Directory Administration
Center, Active Directory Users and Computers (dsa.msc) or ADSI Edit.
Changing Single user:
To change a single user, update the AD
attribute via the GUI tools or PowerShell.
To change multiple uses at once, PowerShell
is recommended.
· Note: Following the change in
the local AD, continue to step 2 to make change in the Azure AD too. If the
users you are changing are ‘in-cloud’, skip directly to step 2.
Changing multiple users (in bulk): There are multiple methods
are doing this in bulk. Two have been included for this guide.
Method 1: By CSV file
1. Prepare CSV file of users
in the below format. Save the file as ‘Change-UPN-AD-Users.csv’. You can use any other file name. Just remember
to use it in the next step if you change it.
Example CSV format:
|
SamAccountName
|
NewUserprincipalname
|
|
sandeep.verma
|
Sandeep.verma.NEWUPN@domain.com
|
2. Type
the following and hit enter when completed:
Import-Module
ActiveDirectory
Import-Csv .\Change-UPN-AD-Users.csv | foreach-object {
Write-host “Changing UPN for user $($_.SamAccountName) to $($_.NewUserPrincipalName)”
-Foregroundcolor Cyan
Set-ADUser -identity $_.SamAccountName -userprincipalname
$_.Newuserprincipalname }
3. Verify by GUI or
PowerShell.
Import-Csv .\Change-UPN-AD-Users.csv |
foreach-object {Get-ADUser -identity $_.SamAccountName | Select SamAccountName,
UserPrincipalName
Method 2: By OU
You can also make changes to UPNs at
OU level i.e. all users in the OU you select will get changed to a new domain
name you specify. For example, all users un the test OU ‘TestOU’ have
‘vermasandeep.local’ as the UPN suffix and need to be changed to the UPN suffix ‘vermasandeep.in’.
1. Open PowerShell ISE with
appropriate admin permissions.
2. Type the following and hit
enter when completed (change $ou and $server as your OU and Server names):
Import-Module
ActiveDirectory
$oldSuffix = "vermasandeep.local"
$newSuffix = "vermasandeep.in"
$ou = "OU = TestOU, DC=VERMASANDEEP,
DC=local"
$server = "DCM1"
Get-ADUser -SearchBase $ou -filter * |
ForEach-Object {
$newUpn =
$_.UserPrincipalName.Replace($oldSuffix,$newSuffix)
$_ | Set-ADUser -server $server -UserPrincipalName
$newUpn
}
Note: $oldSuffix represents the old domain
UPN suffix. $newSuffix represents the new UPN suffix. $ou represents the search
path in which and IT professional can use a specific OU or an entire domain.
3. Verify by GUI or
PowerShell.
$ou =
"OU=TestOU,DC=VERMASANDEEP,DC=local"
Get-ADUser
-SearchBase $ou -filter * | Select SamAccountName, UserPrincipalName
To change a single user’s UPN in the
Azure AD, you can use the following cmdet.
Import-Module MSONLINE
Connect-MSOLSERVICE
Set-MsolUserPrincipalName -UserPrincipalName <Current UPN>
-NewUserPrincipalName <New UPN>
For bulk changes, below mentioned
PowerShell script is recommended.
1. Prepare CSV file of users
in the below format. Save the file as ‘Change-UPN-AzureAD-Users.csv’. You can use any other file name. Just remember to use it in the next
step if you change it.
Example CSV format:
|
SamAccountName
|
NewUserprincipalName
|
|
sandeep.verma
|
Sandeep.verma.NEWUPN@domain.com
|
2. Type
the following and hit enter when completed:
Import-Module MSONLINE
Connect-MSOLSERVICE
Import-Csv .\Change-UPN-AzureAD-Users.csv | foreach-object {
Write-host “Changing UPN for user $($_.UserPrincipalName) to $($_.NewUserPrincipalName)”
-Foregroundcolor Cyan
Set-MsolUserPrincipalName -UserPrincipalName $_.UserPrincipalName -NewUserPrincipalName
$_.NewUserPrincipalName }
3. Verify by GUI or
PowerShell.
Import-Csv .\Change-UPN-AD-Users.csv |
foreach-object {Get-ADUser -identity $_.SamAccountName | Select SamAccountName,
UserPrincipalName
Note:
If you try changing the UPN from a
managed domain to a federated domain, the following error will appear.
Set-MsolUserPrincipalName : You must provide a
required property: Parameter name: FederatedUser.SourceAnchor
If you have such a scenario, leave a comment for help.
Once the script
above has been run successfully, use the following PowerShell cmdlets to check
the new UPNs.
Import-Module MSONLINE
Connect-MSOLSERVICE
Get-msoluser -All | Select-Object
DisplayName, FirstName, LastName, UsageLocation, UserPrincipalName, UserType,
@{L = "ProxyAddresses"; E = { $_.ProxyAddresses -join ";"}}
| Export-Csv -Path E:\Temp\MSOL_Users_25OCT2021.csv -NoTypeInformation
