Change an Object’s UPN Between Federated Domains in Office 365

I wanted to share a quick script that can help make a nuisance of a task easier. There’s been a long-standing issue with Office 365 where you cannot change a user’s userPrincipalName (UPN) from one federated domain to another. As an example, if you have federated the domains mycompany-a.com and mycompany-b.com, changing a user’s UPN suffix between the two will fail.

Given the practice of matching the user’s UPN to their primary email address, it’s feasible that you’ll run across this change at some point, especially in larger environments with many federated domains and people that move between business units.

When trying to make the UPN change, the tenant’s technical contact will receive a “Directory Synchronization Error Report” email which contains the new userPrincipalName and the user’s immutableID.

In order to remediate the issue, we need the user’s old userPrincipalName. The script below helps with getting the proper value and making the necessary change.

What We Know

This issue and the necessary resolution isn’t anything new; I believe it’s existed going back to the beginning of Office 365.

Microsoft has a Knowledge Base article describing the issue: “Changes aren’t synced by the Azure Active Directory Sync tool after you change the UPN of a user account to use a different federated domain.”

The Issue

As stated above, when trying to change the UPN between federated domains, you’ll receive an error report via email.

The error will state:

Unable to update this object in Windows Azure Active Directory, because the attribute [FederatedUser.UserPrincipalName], is not valid. Update the value in your local directory services.

The report will look like the image below:

To resolve the issue, let’s use the “Set-MsolUserPrincipalName” cmdlet to change the UPN to the non-federated tenant.onmicrosoft.com domain. This requires the user’s current UPN, which unfortunately is not what is provided in the error report (another issue altogether).

Scripting the Change

The script Update-FederatedUPN.ps1 takes the immutableID (provided in the email as “On-premises object ID”) as an argument. Assuming you’re already connected to Azure Active Directory via PowerShell, it looks up the user’s current UPN and changes it to the tenant.onmicrosoft.com suffix. Upon the next directory synchronization, the user’s UPN will be changed to the new federated domain.

At the recommendation of Microsoft MVP Dave Stork, the new UPN is prefixed with “_temp_” to avoid potential conflicts with existing cloud accounts and to make it easy to search.

If you have a large number of objects that need to be corrected, you can copy the column of immutableIDs out of the email and drop them into a simple text file. Then use a “foreach” to quickly cycle through all of them.

The script for this post can be found in the Microsoft Script Center at the following link: Update-FederatedUPN.ps1

Hopefully this has been helpful! If you have comments or feedback, please share!

To contact an Office 365 ninja, email info@credera.com or call 972.692.0010. For more information on Microsoft Windows Server 2012 R2 and Office 365, please visit our blog or follow us at @Credera.

• Microsoft Azure
• Office 365
• Microsoft Solutions
• UserprincipalName
• UPN
• Microsoft Script Center