Cloud solutions have been around long enough now that migration scenarios are getting more exotic than simply moving data from the LAN to an Internet-based provider. What follows is a step-by-step guide for technical audiences attempting to migrate the Microsoft Azure Active Directory Sync Services (DirSync) tool from one on-premises AD domain to another.
I recently came across a situation where there was a need to move the DirSync from one local Active Directory domain to another, independent Active Directory domain. User accounts had migrated separately using the Active Directory Migration Tool (ADMT), however that tool actually copies accounts instead of moving them. There was some information on how to do this type of migration already available online—unfortunately though I ran into a bit of technical misinformation. This post should clear things up and contains some useful scripts to facilitate future migrations.
The following assumes that the reader is already acquainted with Microsoft’s Office 365 Cloud solution, that Office 365 is running Wave 15, and that Active Directory Federation Services (ADFS) are not used to facilitate authentication in the Cloud.
Understanding the Link between Office 365 and Active Directory
Users in an Office 365 solution always have at least one authentication provider; in the most basic of configurations the Windows Azure Active Directory (WAAD) provided with Office 365 will act as the authentication mechanism for users—their credentials existing exclusively in the Cloud. This approach is great for smaller organizations with little or no onsite technology infrastructure (i.e. Active Directory), but often does not accommodate mid-market and enterprise customers very well. These larger organizations typically have had years, possibly decades, of network and server history and may be conjoined with niche business applications that cannot readily be migrated to the Cloud.
This is where DirSync comes into the picture, which in its simplest of implementations is used to automatically copy user accounts and properties from Active Directory up to WAAD. This way users have the same account password on their Windows domain account and their Office 365 login ID. When the user changes their password on the Windows domain, their password in Office 365 is automatically updated. The key to all of this is how DirSync knows which Active Directory domain user account corresponds to which WAAD user in Office 365. It turns out there is a match established between an Active Directory account’s Object ID and an Office 365’s user’s Immutable ID. At a binary level they’re a perfect match—though the Active Directory Object ID is typically represented in a Globally Unique Identifier format GUID (hexadecimal) and the Immutable ID is displayed in Base64 (tetrasexagesimal) encoding.
So the trick is, in an Active Directory domain migration scenario, to make the Immutable ID in Office 365 match the Object ID GUID of our user accounts in the new Active Directory domain for our migration to be successful! So without further ado let’s look at how this is accomplished at a technical level.
There are several steps that need to be performed in order for our migration to happen. Here they are at a high level with a brief explanation of each step.
- Stop the existing DirSync replication. Stop the DirSync services from running on the local network and disable Active Directory Synchronization from the Office 365 console.
- Extract the new Immutable IDs. Connect to the new Active Directory domain to get each users Object GUID and convert from hexadecimal to a base64 encoding.
- Assign the new Immutable IDs to Office 365 user accounts. The list of users provided earlier will have their Immutable IDs set to their new values via PowerShell script.
- Configure the new DirSync Connection and Resume Synchronization. If the Immutable ID and Object ID GUID match password changes made by the user in the new Windows domain will automatically update to Office 365.
The process, conceptually, is as simple as that. There are specifics that will be uncovered in the following sections that will help guide you through the process which requires attention to the details.
Phase 1 – Stop the Replication
Our first step in the process is pretty straight forward and happens in two places. First, log on to the system on the source Active Directory domain as an administrator and stop the following services:
- Windows Azure Active Directory Sync Service
- Forefront Identity Manager Synchronization Service
For cautious admins among us, it would be advisable to set the service start-up setting to disabled at this point.Then wait until after the migration has completed successfully before uninstalling the Dirsync software.
Next, you’ll need to deactivate the current synchronization between the local AD and the WAAD for Office 365. To do this, log on to the Office 365 portal found at https://portal.office.com and navigate to the Active Users section of the Admin console. This can be found by navigating Admin → Users → Active Users on the Office 365 portal. Then click the Deactive link in the section labeled Active Directory synchronization. When prompted click the button to confirm this deactivation.
There are a couple items to note at this point;
- The first is that when you do this, all accounts that previously had a status of Synced with Active Directory will change to In Cloud.
- Second, note the console warning will state this conversion process could take up to 72 hours. experience have never seen it take this long, but it would still be best to plan for the worst. So assume that the deactivation of Active Directory synchronization could actually take that long. This behavior as a potential issue is mostly mitigated by the fact that the cloud account is still using the same password as set by DirSync and if appropriate prior steps were taken to set the users’ passwords not to expire then the gap is temporarily covered.
Phase 2 – Extract the Immutable IDs
Now it’s time to sit back, relax and let scripting do the hard work for us. First, this script requires an input of a simple Comma Separated Values (CSV) file named users.csv that should be placed in the same folder as the script file. That file should contain a list of the user log on names for all Active Directory users also in Office 365—each user log on name should appear on its own line in this file.
===========EXAMPLE CSV FILE FORMAT for users.csv ================
From a system on our new Active Directory domain, where presumably our new accounts have been configured, run the following PowerShell script. It is important to note that this script will use Active Directory modules for PowerShell, so be certain they’re installed before running this script.
$usersTable = New-Object system.Data.DataTable “UsersTable”
$column1 = New-Object System.Data.DataColumn userPrincipalName,([String])
$column2 = New-Object System.Data.DataColumn immutableId,([String])
$users=Import-Csv -Path users.csv -Header “userSamAccountName”
foreach($user in $users)
$adUser = Get-ADUser -Identity $user.userSamAccountName
$adUserGuid = $adUser.ObjectGUID
$byteArray = $adUserGuid.ToByteArray()
$immutableId = “”
$immutableId = [system.convert]::ToBase64String($byteArray)
$row = $usersTable.NewRow()
$row.userPrincipalName = $adUser.userPrincipalName
$row.immutableId = $immutableId
$usersTable | Export-Csv “userExportIds.csv”
What will result when the script is finished running is a new CSV file named userExportIds.csv that will contain each user’s userPrincipalName (UPN) and the base 64 encoded Object ID GUID. This file will be used in our next step so hold on to it.
===========EXAMPLE CSV FILE FORMAT for userExportIds.csv ================
Phase 3 – Assign the New Immutable IDs to Office 365 User Accounts
Commonly, with authentication for Office 365 an organization will set up a UPN Suffix in Active Directory Domains and Trusts that matches standard e-mail address formats. So if a user’s e-mail address is email@example.com, then that address can also be the user ID for their Active Directory and Office 365 logins. This further enhances the appearance that the local Windows AD domain and Office 365 are one and the same. If good fortune puts us in this situation then the output file from Phase 2 has a matching identity to that of the Office 365 deployment. If not, then it is a quick find and replace within the userExportIds.csv file may be in order in which @mydomain.int is replaced with @mydomain.com. What is important to the import process is that each user identity in this file matches the corresponding log on ID in Office 365.
That being understood, the following script will take our list of identities and set the corresponding Immutable ID in Office 365. This process will require admin credentials for the Office 365 organization. The script gathers admin credentials at the start and then imports the MSOnline module so the Azure AD Module for PowerShell and the Microsoft Online Services Sign-In Assistant for IT Professionals RTW should both be installed on the system that runs this script.
$objCredentials = Get-Credential
Connect-MsolService -Credential $objCredentials
$users = Import-Csv -Path “userExportIds.csv”
foreach($user in $users)
Set-MsolUser -UserPrincipalName $user.userPrincipalName -ImmutableId $user.immutableId
Phase 4 – Configure the new DirSync Connection and Resume Synchronization
The last step is to configure the DirSync tool in the new Active Directory domain. This is broken up into two steps similar to Phase 1; first we need to start up Active Directory synchronization in Office 365 and second, configure the DirSync tool.
To start up DirSync in Office 365:
- Login as admin again at https://portal.office.com.
- Then go to the Admin console.
- Navigate through Admin Users Active Users and look for the Set up link in the Active Directory synchronization section.
- Then click the Activate button under the Activate Active Directory Synchronization section.
- On that same page click the Download button under Install and configure Directory Sync tool to get the DirSync software package.
- Install this application on a server in the new domain that is not a Domain Controller—technically this will may work but is not a supported configuration—and use the Office 365 admin credentials to establish synchronization between the new Active Directory domain and Office 365.
If the synchronization was not successful for any reason, an e-mail message will be sent to the address of the Office 365 administrator. If there were failures to synchronize particular accounts, the UPN and Immutable ID of these problem accounts will be included in the message to the administrator. This can be very useful in troubleshooting particular user issues.
If everything has gone according to plan, users who have successfully been synchronized will see their status change from In Cloud back to Synced with Active Directory in the Office 365 admin portal indicating migration success and can now uninstall the DirSync software from the old domain.
This blog should provide you the process and tools to complete the whole process for migrating users to a new local AD domain and maintaining the sync with the Office 365 accounts. This really helps limit the impact on end users in these scenarios and leverages PowerShell to make many changes to accounts within a shorter period of time. This entire process can potentially take less than an hour if all goes well and no issues arise.. Should you run into any issues that are insurmountable, thethe entire process can be done in reverse from start to finish to put synchronization back into the original Active Directory domain. Really, a nice roll-out and roll-back plan together make a sort of palindrome.