Systems Admin

Prep a Non-Routable AD Domain for Entra Connect: UPN Suffix Bulk Update

8 min read Part of pathway: Hybrid Identity →

Your internal AD domain is something like infotechninja.local or corp.internal. Microsoft can’t verify those domains in the cloud because they’re not real internet domains. If you sync as-is, every user lands in Entra ID with the ugly user@yourtenant.onmicrosoft.com suffix — which is functional but a pain to migrate away from later, breaks email-based sign-in, and confuses users who expected their normal address. The fix is to add a UPN suffix matching your real verified external domain (e.g. infotechninja.com), change every user’s logon name to use it, and sync. This post walks the prep work end-to-end.

Why .local doesn’t work for cloud sync

Microsoft Entra ID requires a “verified domain” for synced users. Verification means proving you own the domain via a DNS TXT record. .local, .internal, .lan, and other non-routable suffixes can’t be verified because they don’t exist in public DNS — nobody can prove ownership of something that doesn’t exist.

What happens if you sync without fixing this:

  • Each on-prem user (e.g. jdoe@infotechninja.local) lands in Entra ID with their UPN re-mapped to your tenant’s default domain: jdoe@yourtenant.onmicrosoft.com.
  • Users sign into Microsoft 365, OneDrive, Teams, etc. with the .onmicrosoft.com address — not their normal email address.
  • Migrating away later (changing user UPNs in the cloud after they’ve been used) is a major operation: existing licences may need to be reassigned, OneDrive personal sites need to be moved, third-party SSO integrations need to be reconfigured.

Better path: do this right BEFORE the first sync. Once a user’s identity exists in the cloud with a particular UPN, changing it later is more work than getting it right upfront.

The plan

Three operations on the on-prem AD side, then one verification:

  1. Add an alternative UPN suffix to AD that matches your verified external domain.
  2. Change each user’s UPN to use the new suffix — one user at a time for small environments, or via a PowerShell loop for any non-trivial size.
  3. Run the IdFix tool to catch any other sync-blocking errors (invalid characters, duplicates, malformed proxy addresses).

The example throughout this post: internal domain infotechninja.local, verified external domain infotechninja.com. Substitute your own domain names.

Step 1 — add the UPN suffix to AD

Open the Active Directory Domains and Trusts MMC. Two ways:

  • Server Manager: Tools menu > Active Directory Domains and Trusts.
  • Run dialog: Win+R > domain.msc > Enter.

In the MMC:

  1. Right-click the root node (Active Directory Domains and Trusts at the top) > Properties.
  2. In the Alternative UPN suffixes field, type your verified external domain: infotechninja.com.
  3. Click Add. The new suffix appears in the list below.
  4. Apply, OK.

This adds the suffix as an OPTION in AD — it doesn’t change any existing users yet. The next steps actually apply it per-user.

Step 2 — per-user UPN change (small environments)

For a handful of users, the GUI is fine. Open Active Directory Users and Computers (dsa.msc):

  1. Find the user (e.g. jdoe).
  2. Right-click > Properties.
  3. Account tab > User logon name field > the dropdown next to it shows the available UPN suffixes.
  4. Click the dropdown > pick @infotechninja.com instead of @infotechninja.local.
  5. OK.

Result: jdoe’s UPN is now jdoe@infotechninja.com instead of jdoe@infotechninja.local. The user can still sign in with the old infotechninja.local address (the legacy SAM-style logon still works), but the UPN — the thing that syncs to the cloud — is now the new value.

Test on one user before doing many. Sign in to the user’s desktop with the new UPN format and confirm everything works. Some applications (rare but exists) cache UPN values; those caches may need to clear.

Step 3 — bulk PowerShell update (any non-trivial size)

For more than ~10 users, PowerShell is faster and less error-prone than clicking through ADUC. On the Domain Controller (or any host with the AD module), open elevated PowerShell.

First: see who would be affected

Get-ADUser -Filter {UserPrincipalName -like "*infotechninja.local"} -Properties UserPrincipalName |
    Format-Table Name, UserPrincipalName

Output is a list of every user whose UPN ends in infotechninja.local. Eyeball the list. If anything unexpected shows up (service accounts you don’t want to change, a test user from a previous experiment), narrow the filter before the next step.

Then: bulk update

$LocalUsers = Get-ADUser -Filter {UserPrincipalName -like "*infotechninja.local"} -Properties UserPrincipalName

foreach ($User in $LocalUsers) {
    $NewUPN = $User.UserPrincipalName.Replace("infotechninja.local", "infotechninja.com")
    Set-ADUser $User -UserPrincipalName $NewUPN
}

The script:

  1. Pulls every user whose UPN ends in infotechninja.local.
  2. Computes the new UPN by string-replace.
  3. Calls Set-ADUser with the new value.

It runs in seconds. Verify by running the Get-ADUser query again with the new domain and confirming the count matches.

Reverting if needed

If you need to roll back (e.g. someone caught a problem), run the same script with the strings swapped:

$Users = Get-ADUser -Filter {UserPrincipalName -like "*infotechninja.com"} -Properties UserPrincipalName
foreach ($User in $Users) {
    $OldUPN = $User.UserPrincipalName.Replace("infotechninja.com", "infotechninja.local")
    Set-ADUser $User -UserPrincipalName $OldUPN
}

Reverts everyone back to the original suffix.

Step 4 — run IdFix

Even after fixing UPNs, AD may have other problems that block sync: invalid characters in displayName, duplicate proxyAddresses, malformed mail attributes. Microsoft’s IdFix tool finds and helps fix these.

  1. Download IdFix from Microsoft’s GitHub: github.com/microsoft/idfix (search “Microsoft IdFix tool” if the URL has changed).
  2. Launch the IdFix.exe portable app (no install needed).
  3. Click Query at the top. The tool scans your directory.
  4. If you see a warning about “attributes not marked for replication,” click Yes to continue.
  5. Review the results pane. Empty list = clean AD, ready to sync. Non-empty list = errors that need fixing.

For each error IdFix finds, it suggests a fix in the Action column. You can either:

  • Apply IdFix’s suggested fix directly via the tool.
  • Or fix the underlying object manually (in ADUC or via PowerShell), then re-run Query.

Iterate until Query returns nothing. Then proceed to install Entra Connect.

Things that bite people

Forgetting that the verified domain must already be verified in Entra

You add infotechninja.com as a UPN suffix in AD, change every user’s UPN, install Entra Connect, kick off sync — and it fails because infotechninja.com isn’t actually verified in your Entra tenant. Verify the domain in the Entra admin centre BEFORE doing anything in AD. Otherwise you’ve done all this prep against a domain the cloud doesn’t recognise.

Mixing matched and unmatched users in one sync

You have 100 users. You change UPNs for 80 of them and install Entra Connect before finishing the rest. The first sync pulls all 100; the 80 land cleanly with @infotechninja.com UPNs; the other 20 land with @yourtenant.onmicrosoft.com. Now you have a mixed environment and need to either change the remaining 20 (which forces a re-sync that may have other side effects) or accept the inconsistency. Finish ALL UPN changes before installing Entra Connect.

Service accounts caught in the bulk update

Your Get-ADUser query catches service accounts that you don’t want changed. The bulk update changes them; some service somewhere starts failing because its account’s UPN changed. Always run the Get query first and eyeball the list before running the Set-ADUser loop. Filter to exclude service-account OUs if needed: Get-ADUser -SearchBase "OU=Users,DC=lab,DC=local" -Filter ....

UPN change breaks Outlook profile

Some old Outlook profiles cache the user’s UPN and stop working when the UPN changes. The user has to re-create their Outlook profile pointing at the new UPN. Communicate the change to users beforehand; have a runbook for fixing Outlook profiles.

Application-layer dependencies on UPN format

Some line-of-business applications use the UPN as a primary key. Changing UPNs breaks those apps’ user mapping. Inventory your apps before the change; for the affected ones, plan a migration path (database update, etc.) in parallel.

IdFix Query times out on huge directories

For directories with 100K+ users, IdFix Query can take a long time. It’s not hung; it’s scanning. Let it complete. If you genuinely need to abort, the tool handles SIGINT cleanly.

IdFix “attributes not marked for replication” warning

The first Query click triggers a warning about attributes that are not marked for replication. This is informational — some of the attributes IdFix wants to scan aren’t replicated to all DCs by default. Click Yes; the scan proceeds against the DC you’re connected to.

Forgetting to plan for new users

You change all existing users to @infotechninja.com. New users created later, by default, get the domain’s default UPN suffix — which is still @infotechninja.local. New users land with the wrong UPN unless you change ADUC’s default. Either: (a) train your help desk to change the UPN suffix when creating users, or (b) change the default suffix at the OU level via templates, or (c) script the change as part of a user-provisioning workflow.

What’s next

With UPN suffixes done and IdFix clean, the AD side is ready. Part 5 covers the actual Entra Connect install — running the MSI, choosing the install mode (Express vs Custom), authenticating to the cloud, and kicking off the first sync. Full series in the Hybrid Identity pathway.

Tags: #Active Directory #Entra Connect #Hybrid Identity #Microsoft Entra ID #PowerShell #UPN

Leave a Reply