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 “” and “”, 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

Microsoft - The Essential Guide to Microsoft Teams End-User Engagement
The Essential Guide to Microsoft Teams End-User Engagement

We take you through 10 best practices, considerations, and suggestions that can enrich your Microsoft Teams deployment and ensure both end-user adoption and engagement.

Get the Guide

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 like the image below:
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.
To resolve the issue, we need to use the “Set-MsolUserPrincipalName” cmdlet to change the UPN to the non-federated “” 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 “” 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


  • 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 “” 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.

About the Author

More from this Author

Thoughts on “Office 365 – Script to Change UPN between Federated Domains”

  1. You are a beautiful man! Thank you so much for your help with worked perfectly for me!

  2. Thank you for this script. I just wanted to point out that i’ve noticed that when running this with the _temp_ the mailbox alias + a corresponding smtp address get added to the user with the _temp_ at the start. As a fix, I removed the _temp_. My users wont overlap anyway, plus I’m not running this all at once. Just in batches as I migrate. Upon changing it back to the federated domain via aadconnect sync it does not revert the changes (ie update alias or remove smtp).

  3. Hi Joe, Thanks for your script! This solved a lot for us. But how can you use this script in bulk with foreach parameter. Thanks in advance!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Subscribe to the Weekly Blog Digest:

Sign Up