Office 365 migration pre-requisites -
One of the many pre-requisites for Office 365 email migrations, is matching the user's User Princial Name (UPN) to their email address. The UPN / email address is what Office 365 uses to authenticate and is what the SIP address is set to, so it is very important to get this right to ensure a smooth experience for the end client during a migration, especially in a hybrid migration scenario.
Many Exchange environments, especially Enterprise environments, have mismatched UPNs and primary SMTP email addresses. This may be due to many different reasons, for example a company may use the payroll ID for login (UPN), which is different to the user's email address. Plus many environments have inherited an 'old school' Active Directory structure with a local domain name like .internal or .local - which was very common five to ten years ago.
Whatever the reason, it is important to update the UPN to match the user's email address as part of the migration. During a hybrid migration, you will most likely be migrating batches of users, and as this is over a period of time, it is important that you only target and update the users that are migrating at that time. Many Enterprise environments may have the user's UPN tied to a business application (for example Mobile Iron), and if care is not taken, changing the UPN can cause disruption to the end client.
To make this process as painless as possible, I have created two different scripts to update bulk user's UPN to match their email address,
- one via targeting members of a group.- one via targeting members of an Active Directory Organizational Unit.
To enable rollback if needed, I have also created two different scripts to run before you update the UPNs. These scripts document and export the current configuration of the user's UPN and email address, for either the members of a group or the members of an OU. Note the group type must be either an Exchange DL or a mail enabled security group.
Known Issue - Getting the UPN report of members of a security group that is not email enabled.
If you want to run the script to get the UPNs of a security group, you will need to convert the group to a mail enabled security group - Link
Step 1 - In Active Directory - Change the group type to Universal
Step 2 - In EMS - run the following cmdlet - Enable-DistributionGroup "SecurityGroupName"
Once converted, the script will be able to export the user details and UPNs of that group.
Note - It is HIGHLY RECOMMENDED that you run the Get-UPN scripts to have a record of the old UPN if they need to be rolled back.
==========================================================
Pre-requisites -
In preparation of running these scripts, please ensure you have prepared the computer you are running them on.
The 'Get' scripts use the Exchange Management Shell for exporting the current config.
- Run these scripts on a management computer with the Exchange Tools installed
The bulk 'Update' scripts use Active Directory PowerShell to update the UPN.
- Run these scripts on a management computer with the RSAT tools installed.
Next, decide on how you plan to segment and update your user's UPN.
This tutorial and the related scripts refer to segmenting and updating the UPNs via targeting either members of an Active Directory Organizational Unit, or members of a Group.
==========================================================
Reviewing the current configuration -
First you need to determine which users need their UPN updated.
In the examples below, you can see that in Active Directory Users and Computers that I have multiple users with their UPN (User Logon Name) - not matching the E-Mail Address (PrimarySMTPAddress).
Note that I have added the User Logon Name and Email Address column in my view in Active Directory Users and Computers.
This can also be viewed by reviewing the properties of the local AD user -
Local AD user properties -
Email Address - User01@teamterry365.com
User logon (UPN) - asdsdgesd@internal.teamterry365.com
User Logon - internal\user01
To get a record of the current configuration of your target users, run one of the following scripts which best suits the way you are targeting your users.
Script 1 - Get-UPN-SMTP-GroupMember.ps1 - targets users in an Active Directory Group
or
Script 2 - Get-UPN-SMTP-OU.ps1 - targets users in an Active Directory Organizational Unit
======================================================
Preparation for Running the 'Get' scripts and creating the pre-update report
Edit log path if needed
Edit both scripts if needed to point to your preferred log path. By default, both scripts will generate the csv output files to the location c:\reports.
Update the variable - $logpath = "c:\reports" - if you need to output to a different file location.
Note that the script will fail if the location - c:\reports - does not exist.
Preparation for running the Get scripts -
As both of the 'Get' scripts use EMS - Exchange Management Shell, you will need to run them from a Management server or workstation with the Exchange Tools installed, or an appropriate Exchange server.
Note that both scripts will prompt you for input - either to input the OU or the name of the Group.
Have the following information ready -
Targeting the group - The name of the group being targeted
This is in the Active Directory properties of the DL - as below
Copy and paste the Group Name to notepad in preparation for the UPN update.
Save the notepad file for when you actually update the UPN.
Targeting the OU - The Distinguished Name of the OU being targeted -
The Distinguished Name of the OU can be found in the Attribute Editor tab of the properties of the OU. To see the Attribute Editor tab, you must first enable the 'Advanced Features' - in the View section of Active Directory Users and Computers.
Once this is enabled, select the OU you are targeting, right click and select properties.
Select the 'Attribute Editor' tab.
Select the 'distinguishedName' property field.
Double click that field.
When you double click that field, the String Attribute Editor dialog box will appear.
You can then copy and paste the DN to notepad in preparation for the UPN update.
Save the notepad file for when you actually update the UPN.
============================================================
Running the 'Get' scripts -
Reminder -
As both of the 'Get' scripts use EMS - Exchange Management Shell, you will need to run them from a Management server or workstation with the Exchange Tools installed, or an appropriate Exchange server.
When prompted for the 'OrganizationalUnit' - copy and paste the value from notepad that you got and saved earlier.
No quotation marks are needed, even if you have a space in the names -
Running the Group script - Get-UPN-SMTP-GroupMember.ps1
When prompted for the 'GroupName' - copy and paste the value from notepad that you got earlier
Once the scripts have successfully run, you will have your reports in the log path you stipulated - by default - c:\reports
============================================================
Reviewing the csv files.
Keep the csv file for reference if you need to roll back the user's UPN for any reason.
The images below have been highlighted to show the mismatched UPNs.
Results from - Get-UPN-SMTP-GroupMember.ps1
- The report file name will be - Users-UPNs-Group.csv
Note that user01 has a different UserPrincipalName to it's PrimarySmtpAddress.
Results from - Get-UPN-SMTP-OU.ps1
- The report file name will be - Users-UPNs-OU.csv
Note that four users have a different UserPrincipalName to their PrimarySmtpAddress.
==============================================================
Preparation for running the scripts to update the user's UPN.
Once you have captured the original UPN configuration, you can start preparing to update the UPNs to match the email address.
The update scripts use Active Directory PowerShell, so ensure you are running the scripts from a computer that has RSAT installed. The scripts will automatically import the Active Directory module so you can actually run the script from the standard PowerShell window or PowerShell ISE.
Open the notepad files you created earlier so that you can copy and paste the Group Name or the Distinguished Name of the OU when prompted.
===============================================================
Running the Update scripts -
Once you are ready, run the appropriate script to update the UPN.
Running the OU Update script - UpdateUPNviaOU.ps1
When prompted for the 'OrganizationalUnit' - copy and paste the value from notepad that you got earlier.
Running the Group Update script - UpdateUPNviaGroup.ps1
When prompted for the 'GroupName' - copy and paste the value from notepad that you got earlier.
Results -
The OU view shows all users that were previously mismatched now have a UPN that matches their email address.
For the testing of the script for the Group, I reset user01 and user04 to mismatched UPNs and then ran the Update script for groups.
This script successfully updated user01 and user04 to having matched UPN.
Congratulations -
You have now updated your UPNs to match the user's email address.
===============================================================
Acknowledgements -
Special thanks to Simon Payne for assistance with the script targeting the Group -
===============================================================
Related Tutorials and Articles
Configure your Administration PC or Server
- How to configure your desktop PC for Office 365 Administration - including MFA - Link
- How to configure Server 2012 R2 for Office 365 Administration - including MFA - Link
- How to configure your desktop PC for Hybrid Exchange - Office 365 - Azure Administration - Link
Connection Scripts
- How to connect to Office 365 and Azure via PowerShell - Link
- How to connect to Hybrid Exchange - Office 365 - Azure AD and Local AD via PowerShell - Link
- How to connect to Office 365 via PowerShell with MFA - Multi-Factor Authentication - Link
Office 365 Migrations
How to configure Exchange 2013 - 2016 for Office 365 Hybrid - Link
Daily Administration and Reports
How to create a basic document of the Exchange Online environment - Link
How to document the local Exchange Organization for As Built documents and auditing - Link
PowerShell scripts to report on Mailbox permissions in Exchange Online and Exchange On-Prem - Link
Enterprise Management
- How to manage Enterprise environments - Part 1 - Filtering queries - LinkHow to create a basic document of the Exchange Online environment - Link
How to document the local Exchange Organization for As Built documents and auditing - Link
PowerShell scripts to report on Mailbox permissions in Exchange Online and Exchange On-Prem - Link
Enterprise Management
- How to manage Enterprise environments - Part 2 - Creating scripts with a filtered query - Link
- How to manage Enterprise environments - Part 3 - Bulk management using multiple filters - Link
PowerShell
- How to create basic PowerShell scripts - Link
- How to create basic PowerShell scripts with Export-CSV - Link
- How to create basic PowerShell scripts with Import-CSV - Link
- PowerShell modules and resources for Office 365 - Link
Downloads -
All my PowerShell TechNet Downloads - Link
Tips and Tricks -
How to use Chrome browser for concurrent multiple connections to different Office 365 tenancies- Link
General Tips and Tricks for better Office 365 Administration - Link
How to extend your Office 365 Trial - Link
How to get a 180 day trial tenant in Office 365 for testing - Link
PowerShell modules and resources for Office 365 - Link
Thanks for this article. If we have completly different users like DOMAIN\lastname-f and mailadress is fristname.lastname@dom.ain would you recommend of keeping pre2k Login on the old and update only the UPN? Windows Login would keep the same then right? Is it a problem having them different? Today we look really close on having pre2k and upn exactly the same. We have about 3k users and I fear a little on make this change. Do you know more limitations like outlook asking for e-mail and you need to enter the UPN?
ReplyDeleteWhat about security - at least if the upn is not the mailadress it is not much but a little more complicated to even find out the username of that user.
Thanks for you thoughts!
Every organisation has different needs and you need to find the solution that suits these needs best. I have contracted in many Enterprise environments and they usually had a pre-Windows 2000 login that was different to the UPN. In all my years of migrations, I have never needed to update the pre-Windows 2000 login.
DeleteMost organisations I have migrated had updated the UPN to match the email address for client experience. I have had some organisations that have a mis-matched UPN and the end users simply used their alias to log on to the domain and UPN (email address) in Office 365.
It becomes more complicated with hybrid and ADFS as some organisations the client has to use their alias for ADFS, even when logging into Office 365 as redirects back to ADFS for authentication.
This is very hard to explain to the end clients and leads to more support calls, but at the end of the day, there are usually reasons why the business chooses an authentication path.
As far as security goes, there is always a trade off. Look at protecting the endusers with MFA when they are offsite. There are many options, and a lot of time it depends on budgets versus risk.