I change the User Principal Name on the accounts I migrate to Office 365 to match the primary SMTP address for two main reasons:
- Office 365 requires that users have a valid, internet routable User Principal Name suffix, such as BlueSun.com instead of BlueSun.local.
- Email addresses are, by their very nature, internet routable.
- Changing the UPN solves many of the UPN validation problems like invalid characters, spaces, or even duplicate UPNs.
- Many times Office 365 services will ask for email address and password when it really wants a UPN.
- ActiveSync account setup on mobile devices asks for Email and password. ActiveSync then uses those credentials to retrieve Autodiscover information. If ActiveSync cannot authenticate and get an Autodiscover response, the user will have to go through a manual account setup
- Lync sign-in is easier when the UPN and email match
- If the email address and UPN match, it is one less thing users have to remember
The first step is to gather all of the user data. I use PowerShell and the Quest ActiveRoles AD cmdlets. I cannot always count on having a 2008 R2 or higher domain controller running the web AD role to handle the AD cmdlets now included in PowerShell, but I can always control what is installed on my admin workstation. Plus, I have many scripts written using the Quest AD cmdlets and I am not going to rewrite all of them. The output from this script includes more data than we need to change the UPNs. I collect all this data now so that I can use it later in the project to see which accounts are not managed using email address policies – usually because the user prefers a nickname over their full first name. These scripts were modified for a client that had multiple child domains. You can use the single domain scripts if you are in a single domain environment, but I am including the child domain scripts for those who are not so lucky. The domain controller input file was created from information in the ADTD.csv file generated by the Active Directory Topology Diagrammer.
Get Domain Users (Single Domain)
get-qaduser -sizelimit 0 -includeallproperties | where {$_.PrimarySMTPAddress -ne $null} | Select-Object samaccountname,givenname,sn,displayname,mailNickname,primarySMTPAddress,userprincipalname,EmailAddressPolicyEnabled | export-csv c:downloadscriptsoutputGISX-Users.csv –NoTypeInfo
Get Child Domain Users (Multiple Domains)
#Define Input File
#Required Fields in CSV (in any order): Domain, ServerDNSName
$DOMFile = “C:DownloadScriptsInputChildDomains-EditedInputFile.csv”
$DOMList = Import-Csv $DOMFile
Foreach ($NEXTDOM in $DOMList)
{
get-qaduser -service $($NEXTDOM.Domain+”.BlueSun.com”) -sizelimit 0 -includeallproperties | where {$_.PrimarySMTPAddress -ne $null} | Select-Object samaccountname,givenname,sn,displayname,mailNickname,primarySMTPAddress,userprincipalname,EmailAddressPolicyEnabled | export-csv $(“c:downloadscriptsoutput”+$NEXTDOM.Domain+”-Users.csv”)
}
Next, analyze the exported CSV to find the accounts whose UPN and email address do not match. Convert the CSV to an Excel file, add a column called UPNMatch and use this formula in the UPNMatch column to compare the PrimarySMTP and UserPrincipalName cell values. Adjust the formula so that it covers your full range of rows and copy the formula to the UPNMatch cells.
=IF(ISERROR(MATCH(F2,$G$2:$G$135,0)),””,F2)
If a user’s UPN and email match, that value will be written in the UPNMatch column. Otherwise the column will be blank. Here is an excerpt with a matched and mismatched account:
PrimarySMTPAddress | UserPrincipalName | EmailAddressPolicyEnabled | UPNMatch |
[email protected] | [email protected] | TRUE | |
[email protected] | [email protected] | TRUE | [email protected] |
Sort by UPNMatch and delete the rows that have values in the UPNMatch column. The remaining users are the only ones that need to be changed. Now I have a list that contains only the accounts that need to be changed, as well as the account values prior to the change. Your change control board may require this information before the change control request is approved. Save the file as UPNMismatch.csv and use it as the input file in the Set UPN script.
Set UPN
#Must have Quest AD cmdlets
#Define Input File
#Required Fields in CSV (in any order): SAMAccountName, PrimarySMTPAddress
$UserFile = “C:DownloadScriptsInputUPNMismatch-.csv”
$UserList = Import-Csv $UserFile
Foreach ($NEXTUser in $UserList)
{
set-qaduser -Identity $NEXTUser.SamAccountName -UserPrincipalName $NEXTUser.PrimarySMTPAddress
}
Set UPN Child Domain
#Must have Quest AD cmdlets
#Define Input File
#Required Fields in CSV (in any order): SAMAccountName, PrimarySMTPAddress
$UserFile = “C:DownloadScriptsInputUPNMismatch.csv”
$UserList = Import-Csv $UserFile
#Set domain controller for user scope
$DC = ‘DC.Child.BlueSun.com’
Connect-QADService -Service $DC
Foreach ($NEXTUser in $UserList)
{
set-qaduser -Identity $NEXTUser.SamAccountName -UserPrincipalName $NEXTUser.PrimarySMTPAddress
}
Allow Dirsync to update the user accounts in Office 365 if single sign-on has already been configured and the users can now log in to Office 365 using their email address (UPN) and password.
Changing the UPN is not without risks. A User Principal Name is a valid login method in Active Directory, so changing it can affect how your users log in. In my experience, users logging into Windows domains with their UPN is rare but there instances where it is more common. Service accounts can be configured though code or on the service itself to log in with a UPN. My method ignores accounts that do not have email addresses, so as long as the service account does not have a mailbox no changes will be made to the service account. Linux users running Thunderbird also use UPNs for mailbox authentication. Changing the UPN will require them to reconfigure their account in Thunderbird, but they were going to have to reconfigure Thunderbird as soon as they were migrated to Office 365 anyway. Changing the UPN can cause Directory Synchronization errors if email addresses are reassigned following an employee’s departure. An email address on one account will conflict with the UPN of another, requiring you to change the UPN of the departed employee. These few issues are worth the trouble to resolve in order to simplify the login experience for your users.