Migrating Your DirSync Domain for Office 365

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.

Process Overview

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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;

  1. 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.
  2. 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 ================
jsmith, 000xD801xSU09
jdoe, 001xG841xSUHH
sscott, 123x5334xVDS3
aneidermeier, 199x34HHxT58S


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 username@mydomain.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
Import-Module MSOnline
Connect-MsolService -Credential $objCredentials
$users = Import-Csv -Path “userExportIds.csv”
foreach($user in $users)
Write-Output $user.userPrincipalName
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:

  1. Login as admin again at https://portal.office.com.
  2. Then go to the Admin console.
    1. Navigate through Admin  Users  Active Users and look for the Set up link in the Active Directory synchronization section.
  3. Then click the Activate button under the Activate Active Directory Synchronization section.
  4. On that same page click the Download button under Install and configure Directory Sync tool to get the DirSync software package.
  5. 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.


  • Dan Sukoneck July 16, 2015 3:40 pm


    This is a fantastic overview of the challenges you faced and the solutions you implemented. The level of detail is extremely helpful and I appreciate the inclusion of your scripts.

    Great work!

  • Kevin March 10, 2016 2:43 pm

    Hi Ryan,

    Thank you for this article, I am about to do a similar project for a client for the first time.. certainly easier than an exchange coexistence/migration… I was wondering if the info here still is valid with the newer Azure Sync tool.. if it still uses the same identifiers or not.

    Thanks for the great post!

    • Ryan Kellerman April 11, 2016 3:00 pm

      Yes, this is still the case. The GUID in Active Directory Users and Computers still maps to the Immutable ID in Office 365.

  • Philip March 24, 2016 6:25 am

    Could I use a 3rd party tool in advance to transfer email from Office 365 to a new AD domain and on site exchange server, then use this process to disconnect dirsync and reconnect with new AD with scripts provided? Then remove mailboxes in Office 365 so that its just has the user account synced from new AD domain?

    • Ryan Kellerman April 11, 2016 3:22 pm

      Yes, I’ve seen mail pre-staged multiple ways. One method I’ve used mail pre-staged for a migration used using a third party tool (BitTitan’s MigrationWiz was the specific tool I used). In another instance an ExMerge style export of mail data to PST files was created that covered all user mail data up to a certain point in time. Then used Office 365 Import Service was used to upload the pre-staged e-mail data to user mailboxes. Then at cutover MX records were updated so delivery goes to Office 365 and another ExMerge is imported to catch-up messages delivered between the original pre-stage date and when mail delivery changes were made.

      If you’re interested at all I’ve written another blog post on how to use the Office 365 Import Service here: http://lwmpartnerblog.wpengine.com/using-the-office-365-import-service/

  • Chris July 29, 2016 10:34 pm

    Worked Great! Even with AD Connect. Thank you. I only had issues with 2 users. Not bad. Was able to correct the 2 users by setting the ImmutableID again and changing the default proxy address. We had several domains so it was a little difficult. But, over all worked great! 2 users isn’t bad. Great script!

Phone: 312-602-4000
Email: marketing@westmonroepartners.com
222 W. Adams
Chicago, IL 60606
Show Buttons
Share On Facebook
Share On Twitter
Share on LinkedIn
Hide Buttons