There are several scenarios in a corporate environment that necessitate changing Sign-In names on a large scale. Unifying email addresses across all business units is one of those scenarios we recently encountered with a large (~13000 employees) Office 365 customer.
Changes like this are difficult because certain Office 365 services incorporate the UserPrincipalName into exposed URLs. Have a look at the parts of a Skype Meeting URL below:
URLs of shared files in Skype for Business are even more susceptible to changes. They will break if any part of the user’s UPN changes, not only the user name (local) part.
To manage this workload, we implemented a set of workers backed by message queues that perform the steps detailed below and handle failures within the workflow. For the sake of brevity, I omitted some of the more technical details and depending on your environment you might face additional or different steps. Nevertheless, I feel that this summary conveys the scope of what is required for a seemingly simple task as “changing an email address”.
It is important to note that this customer is using the Alternate Login ID method for sign-ins. Microsoft best practice however recommends using the same value for UPN and email address if possible.
Local Active Directory changes
We start by changing the mail attribute to [user]@newdomain.com and promote this address to primary SMTP address while we keep the existing address as a secondary smtp entry. Since we are using the mail value as alternate login ID we do not change the UPN (UserPrincipalName) in the local Active Directory.
Office 365 & Exchange Online Replication
This is one area that caused major issues while processing a larger batch of users. For the subsequent OneDrive for Business operations it is important that the UPN is correctly synced to Exchange Online. Usually, it takes Azure AD Connect about 30 minutes to sync the changes to Azure AD. The sync cycle between Azure AD and Exchange Online is not entirely documented but it shouldn’t take more than 15 minutes if everything goes well. In our case we processed 400 UPN changes and found that after 12 hours the changes were still not synced to Exchange Online.
The Microsoft Premier Support staff helped us to resolve the issue and we gained some interesting knowledge about the Exchange Online sync process. The MIM instance behind the scenes has a 15 minutes cycle and a limit of 3000 objects per cycle. All the changes are processed in a queue and if things go wrong one action may block the entire sync process. Premier Support resolved this issue with a script and commented on the workflow:
“What we use as a script looks for common errors and clears them up then pushes the sync to happen faster and on a higher priority; Therefore, just having one or two objects that we are able to run it against can likely clear up an issue for multiple objects.”
OneDrive for Business
All the shared files of a user’s OneDrive for Business will be migrated to the new UPN. This change is performed in the cloud without any further action on our part, but it takes some time, even more so if the user has a lot of files. Therefore we wait at least three hours after the changes in Exchange Online have completed successfully before our worker processes pick up the user again.
Although we do not have to migrate the actual URLs we do have to inform users who received shared file links about the changes. Our workers will load shared files and directories and email the appropriate recipient with a list of new share links.
Skype for Business Online
Email address changes affect a user’s meetings, thus we will use the Start-CsExMeetingMigration PowerShell Command to correct users’ entries. The Meeting Migration Service will perform the actual migration. This is only necessary if the user name part of the email address changed.
Windows Clients
We deployed a script to all Windows clients that will execute on startup as soon as we get confirmation that the UPN change has been replicated to Exchange Online. The script cleans up windows credentials and Office registry keys to improve end-user experience after the sign-in name change.
One notable exception that still requires user interaction is OneNote. Although it is possible to tweak its registry keys and cache it will loose non-synced changes and require a re-sync.