This article is about the new and updated version of PowerShell module V2 used in changing UPN of federated user in Azure/O365. In case you are looking for steps in PowerShell V1, please refer to the article here nicely documented by my colleague.
The mandatory requirement for a user to authenticate to O365/Azure using UPN gives administrators a challenge in changing UPN when all domains are federated. To avoid complexity of login and SSO consideration, best practice is to keep users UPN matching with the User's Primary SMTP domain. This article will help you understand the workarounds needed with minimum service disruption.
Fundamentally, there are 2 ways to change the UPN of a user if the domain is already federated. We must follow these process to avoid the conventional way of changing UPN, which requires us to un-federate the domain with O365, change UPN and federate the domain back in O365. This will invite some service interruption and will affect all users belonging to the same domain
Install and configure AzureAD V2 PowerShell Module, Versioin 18.104.22.168
- To check if windows PowerShell has the Azure AD module installed, execute the below command in PowerShell and if it does not return any value, you need to proceed to the installation.
Get-Module –Name AzureAD
- Download and save the Azure AD module with the command
Save-Module -Name AzureAD -Path <path> -RequiredVersion 22.214.171.124
- Then install the module with the command
Install-Module -Name AzureAD -RequiredVersion 126.96.36.199
- Confirm the module type and version.
- Now, to connect to “AzureAD”, execute the command “connect-AzureAD”. Provide the credential of “Global Admin”.
Change UPN Method 1:
Execute the command to change the UPN of the target user to unfederated or o365 default domain and then change it back to the required UPN.
PS> Set-AzureADUser -ObjectId “user@currentUPN.com” -UserPrincipalName “email@example.com”
PS> Set-AzureADUser -ObjectId ““firstname.lastname@example.org” -UserPrincipalName “email@example.com”
An error with the tag line “Property passwordProfile.password value is required but is empty or missing” may occur if the user being synced by “Azure AD Connect” from on-premises AD and the password policies like “Password Complexity Policy” & “Password Expiration Policy” are applied.
Hence, to avoid those errors, ensure if there are any password policies for the organization before executing the command. In event of any such policies, then follow “Method 2”.
Change UPN Method 2:
- If all the domain suffix is federated in AD then we must add another additional UPN suffix
Use this suffix as an initial domain for the users whose UPN needs to be changed.
- Start the AD replication with the command “repadmin /syncall /a /p /e /d”
- Start full synchronization of your ADConnect tool with the command “Start-ADSyncSyncCycle -PolicyType Initial” in “Azure AD Connect”.
- Ensure the user's UPN has changed to O365 default domain. i.e. “firstname.lastname@example.org”
- Now change the UPN of the target user in AD into the required UPN.
- Start the replication with the command “repadmin /syncall /a /p /e /d”
- Start full synchronization to O365 with the command “Start-ADSyncSyncCycle -PolicyType Initial” in “Azure AD Connect”.
Ensure in O365 the UPN has changed for the users in new domain suffix.