Office 365 – Script to Change UPN between Federated Domains

Nothing too fancy in this post, just 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 “company-a.com” and “company-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 attempting 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 KB 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“. Back in 2013, my peer Erik Enger even wrote a post on this issue: “Changing UPN for Office 365 account between two SSO domains“.

The Issue

Revolutionize Your Business With Generative AI

From product design and software development to virtual agents, content creation, and reporting, GenAI is transforming business. Our AI experts help you unlock GenAI’s full potential and drive growth.

Let’s Get Started

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

The report will like the image below:

To resolve the issue, we need to 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.

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 on.
If you have a large number of objects needing corrected, you can copy the column of immutableIDs out of the email and drop them into a 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

Summary

• Changing UPNs between federated domains will result in an error
• An error report will be emailed but the report does not contain the required attribute to resolve the issue
• Running “Update-FederatedUPN.ps1” will reset the UPN suffix to the “tenant.onmicrosoft.com” domain
• The subsequent directory synchronization will change the UPN to the desired federated domain

Did you find this article helpful?
Leave a comment below or follow me on Twitter (@JoePalarchio) for additional posts and information on Office 365.
Looking to do some more reading on Office 365?
Catch up on my past articles here: Joe Palarchio.