When the business decided every staff member was moving to a new email domain, mail flow was the least of my worries. That part is well documented and hard to get wrong. What kept me up was the list of SaaS platforms wired into single sign-on, and how many of them knew our people only by their email address.
This is how we planned the change in a hybrid environment, with on-premises AD synced to Entra ID through Entra Connect. It covers what we deliberately left alone, the one SAML setting that decides whether people can still log in the morning after cutover, and the scripts we used to do it in stages with a way back. Most of it applies to cloud-only tenants as well.
Your email address is an identity, not just a mailbox
Adding a domain to Microsoft 365 and making it primary is routine. You verify the domain, publish the DNS records, change the primary SMTP address and keep the old address as an alias. Mail sent to the old address still arrives and replies go out from the new one.
The catch is that the primary SMTP address doesn’t stay inside Exchange. In Entra ID it also populates the mail attribute, and any app set up to identify people by email reads that attribute every time someone signs in. Change the address and, as far as those apps are concerned, you’ve changed the person.
How SAML apps decide who you are
A SAML sign-in through Entra ID hands the app a token with a unique identifier for the user, called the NameID. Microsoft’s SAML claims documentation confirms the default is the user principal name (UPN), with email and name sent as separate claims.
Plenty of apps get switched to user.mail during setup anyway. Sometimes the vendor’s guide asks for it. Sometimes whoever configured it years ago assumed email and UPN would always match. Either way, the app stores that value and looks people up by it.
Now change everyone’s domain overnight. The app receives jane.smith@newdomain.com for someone it knows as jane.smith@olddomain.com.au, and one of three things happens:
- Sign-in fails with a “user not found” error.
- The app auto-provisions a brand new, empty account, and the user’s history, permissions and data are stranded on the old one.
- It works, because the vendor matches on something else. You only find that out by testing.
The second outcome is the dangerous one, because it looks like success. Nobody logs a ticket until someone notices their training records or project access have gone.
Why we left the UPN alone
The tempting move is to change the UPN at the same time so sign-in name and email stay identical. We chose not to.
The UPN is the sign-in name for all of Microsoft 365, and changing it has its own fallout. Microsoft notes that a user’s OneDrive URL is built from their UPN, so saved links and files people have already shared from OneDrive stop working. Every app keyed on UPN would also need the same scrutiny as the ones keyed on email.
Two identity changes on the same morning means that when something breaks, you can’t tell which one caused it. So this project changes the primary email address and the mail attribute only. The UPN stays on the old domain, sign-in names don’t change, and every old address stays on its mailbox as an alias. If the business wants matching UPNs later, that can be its own project with its own testing.
Move SAML apps to the UPN before cutover
For almost all of our users, the UPN and email address were identical on the old domain. That made one change possible ahead of time. We switched each affected app’s NameID from user.mail to user.userprincipalname weeks before the domain change. The value the app received didn’t change at all, so users never noticed.
On cutover day the email address changes, the NameID doesn’t, and the app carries on as if nothing happened.
We found five business-critical SAML apps matching on email. For each one we changed the NameID source attribute in the enterprise app’s Attributes & Claims blade, tested sign-in with a pilot account, and confirmed with the vendor that their side matched on the NameID rather than a separate email attribute. Some vendors can answer that from their documentation. Others need a support ticket, so start early, because their queue won’t move for your go-live date.
Before you flip the claim, check two things.
Users whose UPN and email already differ. Contractors, people who changed their name, accounts created before a naming standard existed. For them the switch isn’t invisible, because the app suddenly receives a value it has never seen. Find them first with a query against on-premises AD. PowerShell’s -ne is case-insensitive, so this only returns real mismatches:
Get-ADUser -Filter * -Properties mail |
Where-Object { $_.mail -and $_.mail -ne $_.UserPrincipalName } |
Select-Object SamAccountName, UserPrincipalName, mailCompare that list with each app’s user export, and have the vendor re-key anyone who appears in both before you change the claim.
Apps that read the email claim for something other than profile data. If an app only uses it to update the stored address on each sign-in, that’s fine and even helpful. If it uses it to find the user, switching the NameID alone won’t save you, and that app needs the vendor’s help.
Build an application impact register
SAML apps are the obvious risk, but the register needs to cover everything that knows a user’s email address. Ours had a row per system with the sign-in method, the identifier it matches on, who has to change what (us or the vendor), a test account and a status column.
The less obvious entries were:
- Apps using OpenID Connect that read the email claim instead of the object ID.
- Systems with their own local usernames that happen to be email addresses.
- Shared mailboxes and distribution groups, which need the new domain just like users do.
- Scanners and multifunction devices that send from a fixed address.
- Service accounts and scripts that reference mailboxes by address.
- Email signature tools, which will keep printing the old address until someone changes the template.
- External services staff signed up to with their work address, which only they can update.
The register doubles as your communications plan. When someone asks whether the change will affect a system, the answer is a row, not a guess.
Get the new domain ready first
Verify the new domain in the tenant before you touch a single user. Microsoft’s documentation on how proxyAddresses are populated says proxy addresses with an unverified domain are removed from users who hold an Exchange Online licence. Add the aliases on-premises before the domain is verified and they quietly fail to appear in the cloud.
Then set up mail authentication. The new domain needs its MX record, SPF, DKIM signing and a DMARC record before anyone sends from it as their primary address. We started DMARC at p=none and watched the aggregate reports for legitimate senders that were failing, before tightening the policy. If a third-party filter sits in front of Exchange Online, or a separate service manages your DMARC, set the domain up there as well. Signing and SPF have to match the path mail actually takes, not the path you assume it takes.
Back up before you change anything
In a hybrid environment, synced users’ addresses are mastered in on-premises AD, not in the Exchange admin centre. The primary address is the proxyAddresses entry with an uppercase SMTP: prefix, and aliases use lowercase smtp:. If you still run an on-premises Exchange server to manage recipients, make the changes through Exchange so email address policies don’t overwrite them.
Export every in-scope user’s current addresses first. It takes seconds and turns any mistake into a restore rather than a reconstruction:
$ou = "OU=EmailChange,DC=contoso,DC=local"
Get-ADUser -SearchBase $ou -Filter * -Properties mail, proxyAddresses |
Select-Object SamAccountName, mail, @{n = "proxyAddresses"; e = { $_.proxyAddresses -join ";" }} |
Export-Csv "proxy-backup-$(Get-Date -Format yyyyMMdd).csv" -NoTypeInformationPhase 1: add the new address as an alias
We split the rollout into two phases a week apart. Phase 1 adds firstname.lastname@newdomain to every user as a secondary address. Nothing visible changes, but you can prove that mail to the new domain lands in the right mailbox for everyone before it matters.
This reuses each user’s existing address prefix. Run it with -WhatIf first, then remove it to apply:
$newDomain = "newdomain.com"
Get-ADUser -SearchBase $ou -Filter * -Properties mail | Where-Object mail | ForEach-Object {
$new = $_.mail.Split("@")[0] + "@" + $newDomain
Set-ADUser $_ -Add @{proxyAddresses = "smtp:$new"} -WhatIf
}Users whose current prefix doesn’t follow the new naming standard should be handled by hand rather than by script.
Phase 2: make it primary
A week later, the new address becomes primary, the old one drops to an alias and mail is updated to match:
Get-ADUser -SearchBase $ou -Filter * -Properties mail | Where-Object mail | ForEach-Object {
$old = $_.mail
$new = $old.Split("@")[0] + "@" + $newDomain
Set-ADUser $_ -Remove @{proxyAddresses = "SMTP:$old", "smtp:$new"} -WhatIf
Set-ADUser $_ -Add @{proxyAddresses = "SMTP:$new", "smtp:$old"} -WhatIf
Set-ADUser $_ -Replace @{mail = $new} -WhatIf
}Removing before adding means an account never holds two uppercase SMTP: values at once, which is how you end up with the wrong primary address. Because the backup CSV holds every user’s original values, rolling back is the same swap in reverse.
Test on a pilot OU
We moved a handful of test accounts into a dedicated OU and ran both phases on them before anyone else. Entra Connect syncs every 30 minutes by default, so after each change we forced a delta sync on the Entra Connect server:
Start-ADSyncSyncCycle -PolicyType DeltaThen we confirmed the result in Exchange Online:
Get-EXOMailbox jane.smith@olddomain.com.au | Select-Object PrimarySmtpAddress, EmailAddressesThe last step matters most. Sign in to every app on the register as each test user, not only the SAML ones. This is where you find the apps nobody knew were matching on email.
What users notice
Because the UPN doesn’t change, nobody’s sign-in name changes. Mail to the old address still arrives, so external contacts don’t need to be told on day one. People see the new address on outgoing mail and in the address book. The follow-up work is mostly signatures, business cards and any external accounts staff registered with their work address.
Keep the old domain as an alias indefinitely. Removing it saves nothing, and it guarantees that one supplier, five years from now, sends an invoice into the void.
From my early days on the helpdesk through roles as a service desk manager, systems administrator, and network engineer, I’ve spent more than 25 years in the IT world. As I transition into cyber security, my goal is to make tech a little less confusing by sharing what I’ve learned and helping others wherever I can.