Using PowerShell to change the User Principal Name (UPN) for a user in Active Directory!

[TomWechsler]

Dear Windows Active Directory friends,

I am absolutely aware that there are probably already a lot of articles on this topic. Nevertheless, I would like to show you my steps how I did this in a small infrastructure.
But why would I want to change the User Principal Name (UPN)? Let's say you want to synchronize the
local Active Directory with the Azure Active Directory and you use in the local domain the DNS suffix e.g. tomrocks.local, then the accounts in Azure are created with the default DNS suffix e.g.
yourcompany.onmicrosoft.com.

In my case, I added a custom domain in Azure: tomrocks.ch. In order to create the accounts correctly
in Azure, the first step is to adjust the UPN of the users in the local Active Directory. I use the PowerShell ISE for this, but of course you may also work with another editor.

Please start with the following steps to begin the "journey" (the Hashtags are comments):

#The first two lines have nothing to do with the configuration but make some space at the bottom of the ISE.
Set-Location C:\
Clear-Host

#Get a list of the UPN suffixes
Get-ADForest | Format-List UPNSuffixes

#Let’s add the UPN suffix
Get-ADForest | Set-ADForest -UPNSuffixes @{add="tomrocks.ch"}

#Get a list of the UPN suffixes
Get-ADForest | Format-List UPNSuffixes

#List of all the AD Users in the organization
Get-ADUser -Filter * | Sort-Object Name | Format-Table Name, UserPrincipalName

#Change the UPN for all the AD users in the organization
$LocalUsers = Get-ADUser -Filter {UserPrincipalName -like '*tomrocks.local'} -Properties UserPrincipalName -ResultSetSize $null
$LocalUsers | foreach {$newUpn = $_.UserPrincipalName.Replace("tomrocks.local","tomrocks.ch"); $_ | Set-ADUser -UserPrincipalName $newUpn}

#Confirm that the UPN is changed
Get-ADUser -Filter * | Sort-Object Name | Format-Table Name, UserPrincipalName

I know this is nothing spectacular at all, but I wanted to share my findings and experiences with you.

Thank you for your attention. Kind regards, Tom Wechsler

P.S. All scripts (#PowerShell, Azure CLI, #Terraform, #ARM) that I use can be found on github! https://github.com/tomwechsler

[#2]

Thanks for sharing. I am sure that you know this more than I do.
It's all about communicating and sharing the knowledge and what we find and learn.
Thanks for sharing.

[#3]

It's always a pleasure! Regards, Tom Wechsler

[#4]

@TomWechsler 

I'm creating an AD User (on Prem) using Powershell.
I need to set the UPN name afterwards using P/S.
For ex.
How do I set TCutler's UPN suffix to pnl.com

[#5]

how can you change a username without affecting the domain name using a script?@TomWechsler 

[#6]

@jkariuki 

There's many ways to do this and your question does not provide enough information for us to provide a concise answer.

If you can provide more information on what you're trying to achieve, such as examples values for:

1. A current userPrincipalName;
2. The new format of userPrincipalName;
3. A description on how you anticipate getting from the current to new formats.

Then we can provide more concise advice.

Here's a generic example on how you can change the prefix (username) component of the userPrincipalName without changing - or even needing to know anything about - the suffix (domain) component.

# Get the Active Directory object to be changed.
$UserPrincipalName = ($User = Get-ADObject -Filter { userPrincipalName -eq "email address removed for privacy reasons" } -Properties userPrincipalName).userPrincipalName;

# Split it into it's separate components (i.e. username and FQDN.)
$Parts = $UserPrincipalName.Split("@");
$Username = $Parts[0].ToLowerInvariant();
$Domain = $Parts[1];

# Make some kind of change to the username component. In this case we're going to switch from the current [givenName].[sn] format to [givenName initial][surname].
$UsernameParts = $Username.Split(".");
$Username = $UsernameParts[0][0] + $UsernameParts[1];

# Set the new value of userPrincipalName. Remove the "-WhatIf" parameter to actually make the change (I'm clearly not interested in changing my userPrincipalName.)
$NewUserPrincipalName = "$Username@$Domain";
Write-Warning -Message "Changing userPrincipalName from $UserPrincipalName to $NewUserPrincipalName...";

Set-ADObject -Identity ($User.ObjectGUID) -WhatIf -Replace @{
    userPrincipalName = $NewUserPrincipalName;
}

Here's the output from that example script (noting I'm using -WhatIf to avoid effecting the change.)

Cheers,

Lain