Using PowerShell to change the UPN Suffix

For decades, it’s been a best practice to configure your corporate domain with a non-internet-rotatable .local domain (e.g. example.local instead of example.com). But in the modern everything-is-connected-to-the-internet age, this appears to be falling out of fashion.

When “Preparing to provision users through directory synchronization to Office 365,” you’ll eventually realize that you’ll need to follow “How to prepare a non-routable domain (such as .local domain) for directory synchronization.”

As the KB states, you can use Windows PowerShell to change the UPN suffix for all users. In addition to the cmdlets Microsoft suggests using to change all example.local suffixes to example.com, I added a few PowerShell one liners of my own.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Get users with example Exchange mailboxes whose UPN suffix is example.local
Get-ADUser -Filter 'UserPrincipalName -like "*example.local" -AND Mail -like "[email protected]*"'
 
# Get users with example Exchange mailboxes whose UPN suffix is example.org
Get-ADUser -Filter 'UserPrincipalName -like "*example.org" -AND Mail -like "[email protected]*"'
 
# Count how many users with example Exchange mailboxes whose UPN suffix is example.local
Get-ADUser -Filter 'UserPrincipalName -like "*example.local" -AND Mail -like "[email protected]*"' | Measure-Object
 
# Count how many users with example Exchange mailboxes whose UPN suffix is example.org
Get-ADUser -Filter 'UserPrincipalName -like "*example.org" -AND Mail -like "[email protected]*"' | Measure-Object
 
# Change 10 random users with example Exchange mailboxes whose UPN suffix is example.local to example.org
Get-ADUser -Filter 'UserPrincipalName -like "*example.local" -AND Mail -like "[email protected]*"' | Get-Random -Count 10 | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.org" }
 
# Change 10 random users with example Exchange mailboxes whose UPN suffix is example.org to example.local
Get-ADUser -Filter 'UserPrincipalName -like "*example.org" -AND Mail -like "[email protected]*"' | Get-Random -Count 10 | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.local" }
 
# Change all users with example Exchange mailboxes whose UPN suffix is example.local to example.org
Get-ADUser -Filter 'UserPrincipalName -like "*example.local" -AND Mail -like "[email protected]*"' | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.org" }
 
# Change all users with example Exchange mailboxes whose UPN suffix is example.org to example.local
Get-ADUser -Filter 'UserPrincipalName -like "*example.org" -AND Mail -like "[email protected]*"' | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.local" }
 
# Change all users whose UPN suffix is example.local to example.org
Get-ADUser -Filter 'UserPrincipalName -like "*example.local"' | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.org" }
 
# Change all users whose UPN suffix is example.org to example.local
Get-ADUser -Filter 'UserPrincipalName -like "*example.org"' | foreach { Set-ADUser $_ -UserPrincipalName "$($_.samaccountname)@example.local" }

Since I was a little hesitant how this change might effect our users and environment, I chose to create a scheduled task that ran one an hour to select and change 10 random user accounts. Once comfortable, I simply changed everyone.