For organizations that are using synchronized identities for Office 365, the directory synchronization tool of choice these days is Azure AD Connect. To keep AAD Connect running you may eventually have the need to move it to another server. There are a variety of scenarios where this need arises, for example migrating to a new server provides the opportunity to safely upgrade to a newer underlying operating system without the risk of a lengthy outage.

For this demonstration, I’ll be migrating Azure AD Connect from a Windows Server 2012 R2 server to a newly installed Windows Server 2016 server. The new server has been configured with an IP address on the network, joined to the domain, updated from Windows Update, and is ready to go. Although it is supported to migrate between AAD Connect instances that are not the exact same build, it is recommended to use the same build on both servers so that the same features and options are available on both instances. In my case, the latest available build is already running on the source server.

The steps to migrate Azure AD Connect to a new server are:

  1. Review the configuration of the existing Azure AD Connect instance
  2. Install the new Azure AD Connect instance in staging mode
  3. Compare configurations of the old and new servers
  4. Swtich-over synchronization to the new server
  5. Decommission the old server

Reviewing the Configuration of the Existing AAD Connect Instance

Ideally you will already have a documented configuration for your AAD Connect instance. If you don’t, then you can use the AADConnectConfigDocumenter tool from MIcrosoft to create a HTML document of your existing configuration. Download their latest release and follow the instructions to generate the report.

Migrating Azure AD Connect to a New Server

If you prefer something simpler to look at, open Azure Active Directory Connect on your existing server, and from the Tasks list select View current configuration. This won’t tell you absolutely everything about the server configuration, but it’s a start. You can also choose Customize synchronization options from the Tasks list to see things like the OU filtering that is configured.

Migrating Azure AD Connect to a New Server

Personally, I prefer the HTML report as it contains everything, it’s just a little harder to read.

Install the New AAD Connect Instance in Staging Mode

On the new server that will be hosting the AADConnect instance, download the latest build of the AADConnect installer and launch it to begin the installation process.

Migrating Azure AD Connect to a New Server

At the Express Settings dialog, choose Customize so that you can fully customize the AADConnect install.

Migrating Azure AD Connect to a New Server

As you step through the custom setup you’ll be able to choose the same configuration options as your existing AADConnect instance. At the final stage, check the box to enable staging mode.

Migrating Azure AD Connect to a New Server

Microsoft Platform Migration Planning and Consolidation

Minimize the risk, time, cost and complexity associated with migration and consolidation projects, while ensuring seamless coexistence and easier platform management.

Compare Configurations of the Old and New Servers

The AADConnectConfigDocumenter script can compare configuration information from two different AADConnect instances so that you can find any differences and correct them. The documentation explains how to do it, which I’ll briefly summarize here as well.

First, on the old server I run Get-ADSyncServerConfiguration to export the server’s configuration. I’m placing the export files in the \Data\ESPNET\S1DC1 folder (ESPNET is the NETBIOS name of my domain, and S1DC1 is the old server’s name).

PS C:\Admin\AADConnectConfigDocumenter> Get-ADSyncServerConfiguration -Path C:\Admin\AADConnectConfigDocumenter\Data\ESPNET\S1DC1

Next, I copy the files to the new server, which is named AAD01, and run Get-ADSyncServerConfiguration again, this time placing the export files in the \Data\ESPNET\AAD01 folder.

PS C:\Admin\AADConnectConfigDocumenter> Get-ADSyncServerConfiguration -Path C:\Admin\AADConnectConfigDocumenter\Data\ESPNET\AAD01

Next, I edit the AzureADConnectSyncDocumenter.cmd file that is provided with the script, and supply the folder names of the two configurations that I want to compare.

Migrating Azure AD Connect to a New Server

Save the changes and run the file. It takes a few moments to analyze the data.

Migrating Azure AD Connect to a New Server

After the script has finished running, you’ll find the HTML report in the \Report folder. Open the report in a web browser and review it for any differences between the two configurations, which will be highlighted like the examples below.Migrating Azure AD Connect to a New Server

Correct any configuration differences (other than obvious ones like staging mode being enabled/disabled), then you’ll be ready to switch-over synchronization duties to the new AADConnect instance.

Switch-Over Synchronization to the New AADConnect Server

Currently the demonstration environment has the following servers installed with AADConnect:

  • S1DC1 (old server) – Synchronization enabled, staging mode disabled
  • AAD01 (new server) – Synchronization enabled, staging mode enabled

While the two servers are in this state, the new server AAD01 will stay up to date with the latest changes in the on-premises Active Directory and Azure AD. However, it will not export any changes to the directories until staging mode is disabled. Before taking the new server out of staging mode, we first need to place the old server into staging mode so that we don’t have two servers trying to export changes to the directories.

During the switch-over, which is a pretty quick process, there’ll be no synchronization of changes between directories. This might mean a delay in the synchronization of a recent change that one of your administrators made (e.g. a group’s membership) or synchronization of a changed password. Keep in mind though that most changes have a synchronization delay anyway, since the sync schedule runs every 30 minutes. Password changes sync nearly instantaneous though, so that’s got a slightly higher risk of being impacted. To reduce the likelihood of the switch-over impacting someone or something important, you might prefer to schedule the change to occur during a period of low usage in your environment, such as an evening or weekend.

On the old server, launch Azure AD Connect and choose Configure, then from the Tasks list choose Configure staging mode. Click Next, and follow the wizard to authenticate and configure staging mode to be enabled. At the final step you can decide whether to keep synchronization enabled or not, depending on whether you think you might need to switch back to this server again (e.g. if the switch-over is only for DR, testing or site maintenance purposes).

Migrating Azure AD Connect to a New Server

On the new server, launch Azure AD Connect and choose Configure, and again from the Tasks list choose Configure staging mode. Follow the same wizard as before to disable staging mode on the new server, and make sure to start the synchronization process.

Migrating Azure AD Connect to a New Server

Decommission the Old AADConnect Server

When you’re satisfied that the new AADConnect instance is successfully synchronizing your directories, you can decommission the old instance of AADConnect if you no longer have a need for it. The uninstall process can be initiated from the Control Panel in Programs and Features.

Migrating Azure AD Connect to a New Server

When you start the uninstall of Microsoft Azure AD Connect you’ll be prompted to also remove the additional components that were installed on the server for AADConnect, such as SQL instance and the Microsoft Online Services Sign-In Assistant. You can remove them if you no longer have a need for them (e.g. the sign-on assistant is still needed by some PowerShell modules, so if you’re going to keep using the server for admin tasks or scripts, either leave that component alone or reinstall it afterwards).

Migrating Azure AD Connect to a New Server

After the uninstall has finished you can go ahead with any server decommission tasks you need to complete for your environment.

[adrotate banner=”50″]

About the Author

Paul Cunningham

Paul is a former Microsoft MVP for Office Apps and Services. He works as a consultant, writer, and trainer specializing in Office 365 and Exchange Server. Paul no longer writes for


  1. Prakash

    In my organization Azure AD connect server deployed in AWS. Now we planned install new Azure AD Connect in local AD server. Is there any issues if new server went to live. Can any one share your thoughts

  2. James

    Thank you for the detailed steps, still relevant. IT helped me perform the cutover from old server to new server with new AD connect. I have removed old AD connect from old server, then proceeded to demote the old Domain controller. Immediately Synchronization failed on the new AD connect. That is when I noticed the Synchronization service manager in the new Domain controller AD connect is using the old Domain controller for connection and this connection failed with server down after demotion. Now I managed to get it working again by promoting back the Domain controller temporarily. Dont know why this happened that the connection didn’t change to the new domain controller. Could you please advice on how I can change this connection manually to connect from the new Domain controller

    1. notbatman

      Had you transferred any FSMO roles held by the DC before demoting it ?? Could explain some issues without knowing more.

  3. Angel

    I’ve completed my swing migration from old server running 2008 R2 to new one running server 2022 and everything on this article went smooth with the exception of putting the old server on staging mode via configuration because I wasn’t able to log into it. The new server was configured in staging mode.

    I then uninstalled the old server and successfully logged into the new server to disable staging mode. All synchronization rules are running fine, but I’m concerned about some rules showing (Stage Only).

    Here is the order that they are running:
    Local AD – Delta Import (Stage Only)
    Azure AD – Delta Import (Stage Only)
    Local AD – Delta Synchronization
    Azure AD – Delta Synchronization
    Azure AD – Export
    Local AD – Export

    Is this normal? If not, what do I need to do for Stage Only not to appear?

  4. sebus


    It does not give an option for staging mode during Express Install
    It was a mess, as I did not untick Start the sync after…

    It does have export/import settings, which I stupidly did not use (following the guide here)

    Really all needs to be updated

  5. Greg Neumarke

    So am I understanding this right, that there is no way to export the configuration and import it into the new install.
    The best we can do is manually configure everything again, but then you can use the configuration documenter tool to compare your work to the existing server and try again if you missed something?

    1. Alessandro Grano

      Hi! I actually have found that Once you start the ADConnect install wizard on the new server, under %programfiles%\Microsoft Azure AD Connect\Tools there will be a script named MigrateSettings.ps1. You can copy this on the old server and use it to export and import configurations, then you can go and still compare the 2 configurations as explained in the article. This is the MS article that explains it:

      I just followed this and the MS guide at the same time and everything worked out!

      1. Curtis Wright

        Yup! Can confirm this works as well! This is a new feature and a most welcome one. I missed a few settings when I had to do this manually, but it worked perfectly with this script.

      2. Lawes


        I have some confuse as I have a very old version using, the path upgrade to the latest AADC may not possible.

        if I skip the migration , said directly install a new AADC on new server, then import the config by the script. is that possible ? do I need to map the service account that being used in the old AADC ?

        thanks for help

      3. Anonymous Man

        Thanks for this note, a very welcome update indeed. Does anyone know or have had first hand experience of using AADC Export utility with PTA (Pass-Through Authentication) already enabled on their old AADC server? (We already have PTA enabled with current AADC server as the main agent and two exclusive PTA agents).

        MS doc for PTA installation suggests PTA agent could be installed on AADC either in primary or staging mode. But I am not sure if this preview export/import utility will handle that part of the AADC configuration.
        (I’ve tested the JSON config export and reviewed the file, it does not seem to have anything in it about Authentication or Sign-in options)

    2. SB

      They now have export/import in the AAD Connect app (Preview)

  6. Paul Graham

    This was the most helpful well put together article I have ever used.
    It was fantastic

  7. Luke Page

    Great guide thank you!

    Is this still current? Aware its been a while since this was written.

  8. Luke Page

    Great guide thank you!

    Is this still current? Aware its been a while since this was written.

    Thanks a lot!


  9. Jeff

    Hi there,

    Great article and just ran through this however I used the preview option where I could export my config off the old server to the new one. It seemed to work except the new server AD connect does not see my .com for its azure ad connection. It is looking at it like its instead. We run a .local domain but have our users all setup on prem with the .com of our domain. The older servers connector to azure AD is the .com but the new server with azure AD isn’t picking that up. Should I start over and not import the config?

    1. MD


      Had the same issue here.

      After completing the AAD Setup Wizard on the new server, just launch the “Synchronisation Service Manager”, then head to the “Connectors” Tabs, right click properties on the wrongly named connector, change the name, validate and go through the warning.

      Then export again the config on new server, and compare again, should be OK.


      1. ChappyChap

        Oh my I love your face! Thank you MD, I thought I was in for a world of hurt and this resolved it.

        I hope a random stranger gives you a high 5 today. (in a nice safe way because it’s 2021)

      2. ChappyChap

        Sadface, I had to run the config a couple of times as I got tripped up on a few details, now when I go to rename I get a “working directory already exists” error.

        That will teach me for making a change on a Friday.

      3. ChappyChap

        C:\Program Files\Microsoft Azure AD Sync\MaData


  10. Newsas

    Hi Paul,
    The production AAD Connect in running with ADFS.
    Now I am planning to migrate the AAD connect to new server and eliminate ADFS rather user passthrough authentication.
    Is it possible to build staging server with Passthrough Authentication and switchover to the new aad connect server with PTA?

    Or any other way to eliminate ADFS while building the staging server?

    Your suggestion will be helpful

    1. Christian Dekker

      Hi Newsas,

      The authentication type (ADFS, PTA) used is not part of the configuration of the AD Connect server. It’s part of the AzureAD authentication configuration.

      You can switch to PTA before or after you switch over to the new server.
      This are two distinct actions.


  11. Greg Rogge

    I have a unique problem. Azure AD Connect was installed on a 2008 R2 server. I recently did an in place upgrade on the 2008 R2 server. After doing so the Azure AD Connect still runs and functions but I am unable to access any of the configuration files or open the Azure AD Connect application.

    Since I can’t access the configuration I’m unable to move the AD Connect Service to a new computer or perform an other functions. Trying to run a repair on the Azure AD Connect errors and all powershell commands fail as if the commands are unavailable.

    Do you have a suggestion on how to get the configuration files or repair the install?
    Do you have a suggestion?
    At this point I find no way to compare version configurations.

  12. Luciano

    Currently, I’m running AD connect on a Windows Server 2008R2 (olddomain.local). How to migrate to a new Server 2019, with a new domain (newdomain.local) and keep all Office365 accounts synchronized with the new server/domain? I have migrated AD users from the old Domain Controller to the new one, using ADMT.

    1. Alex

      Were you able to transfer syncing to a new domain ? I was faced with the same task.

  13. Wim

    Hi Paul,
    I need to change the original account for the AD Connect Service on my AD Connect server. Also i need to upgrade this server to a new windows version. Is it possible to use a new, different account for the AD Connect Service on the new server?

  14. kbbtech

    Thanks for posting this. Came in handy. I’m in a situation where one of the mismatched values from my AD Server Sync Configuration Documenter Report is
    Microsoft.UserSignIn.SignOnMethod PasswordHashSync(onNewServer)/Undefined(onOldServer).

    I had performed an Azure AD Connect software upgrade on the old server before installing the software on the new server. My thinking is this is a value from the original install that the new software isn’t sure what to do with….but I’m not sure.

    Also of note, when I check both configurations using the GUI, both servers that Password Hash Sync is enabled.

    I’ve not swapped over the staging roles yet that would allow the new server to be the primary.

    Does anyone know if I need to correct the Undefined value on the old server before swapping the staging roles? Or, does anyone know if simply swapping back the staging roles is possible in the event something goes sideways?

    Thanks in advance.

  15. Shamim

    Hi Paul,

    Thanks for great article!!

    I had AD Connect Server Windows Server 2012 R2. Recently we found Azure Active Directory Connect (Sync) Alerts “Health service data is not up to date” in Azure AD. This error indicated “The AAD Connect Health Service is not receiving the latest data from the server(s) listed above. This may be due to connectivity issues or data collection issues on the server itself”. The Sync Service status was showing “Unhealthy” for this server. Then We upgrade AD Connect version to but Azure AD was showing older version AD Connect Finally did not resolve it. After that we migrate AD Connect server to new one Window server 2019 following this article and now Sync service status is showing “Healthy” for new server. Then I decommission old one, but it did not remove automatically from Azure AD and still showing unhealthy in Azure AD.

    What can I do now?


  16. Jim DeSantis

    @Paul, thanks for ALL the Great articles!
    I can always count and depend on your articles to be ‘correct’ and trustworthy!
    Just used this last night and didn’t know about the ConfigDocumenter.. great catch.

  17. Stefan Ridemar


    My problem are that I cant enable staging mode on the server since its orphaned and not recoverable. So my question, is it just to install Azure AD Connect to another DC in the domain?

  18. Rick

    Hello Paul,

    Your article es great. I just have some doubts. The report tells me in the global settings as follow: (all initial value are marked red for delettion)
    00:03:33 GMT
    Microsoft.Synchronize.ServerConfigurationVersion 1.1.880.
    Microsoft.Synchronize.StagingMode FalseTrue
    Microsoft.SystemInformation.MachineRole RolePrimaryDomainController
    Setting Configuration Encrypted?
    UserName No
    Synchronization Rules
    Out to AAD – Group Identity
    Tag Microsoft.OuttoAADGroupIdentity.004Microsoft.OuttoAADGroupIdentity.005

    And there is some other stuff. I have only 1 forest and to one.

    I dont really know if I need to change anything here or what can happen if I make the switch just like this without changing anything.

    I appreciate any light shed on this.

  19. Jann Kjeldsen

    Hi Paul

    Good walkthrough but i have run into a little of a pickle. We´re taking over a new customer which has already run AD synch in their local AD Environment. Now that AD is retired and we´re suppose to have a new AD synch running from a “NEW” AD. But the users won´t synch because of a related problem to the old AD synch. We´re talking 2 different domains here. The anchor seems to be frozen on the users who has gone from “synched” to “cloud only”. how do 1 get further in this pickle unless you want to take out pst files and make new users?

    1. prem

      do a hard match for the users in cloud

  20. Singh

    Hi Paul…Couple of questions. First one is about AAD Connect and ADFS. Do you know what steps needs to be performed with respect to ADFS when building a new staging server.

    Second question is about MFA requirement of AAD Connect sync account. Does the account that AAD Connect creates during installation process to sync to AAD requires MFA to be disabled.

  21. Jon

    The one thing I ran into with this that wasn’t covered here was that the next day I started getting alerts from the “Azure Active Directory Connect Health – Sync Services” about the fact that my “old” server was no longer syncronizing. I had to go in there and delete that old server to stop getting those notifications. Otherwise, this all worked great for me!

  22. Moe

    What’s the impact if a newly built AD Connect staging server using the default attributes settings and is cutover from staging to Production? But the old AD Connect Production server had customized attribute settings.

  23. Colin Safreed

    Great article!

    I’m faced with a a slightly different situation. Moving the enterprise to a new Forest, new datacenters, and new AD structure. We will migrate user and computer (desktops not servers) via ADMT, Quest or something else. Does your write hold true for my situation?

    Maybe a question for a different forum… curious how ADFS and WAPs play into this. Create new farms?

  24. kaifi siddiqui

    Can I migrate AAD connect from on-premise server to cloud

    1. Riaz

      Hey Paul,

      my rule Editor is not working ( shows blank ) , can I run the repair option from programes and features. will it keep all my custom rules ( running

  25. Markus

    HI, as the new Server 2019 is out for production and I am running my AAD Connect on Server 2016, is it possible to do a inplace upgrade to new version? Appologize if this question is inappropriate…I am a beginner.

  26. Sean

    Used this process, ended up deleting all of our users, had to revert back to old server to restore all the users.

    Back to the drawing board………

  27. SK


    Great article.
    You say:
    Correct any configuration differences (other than obvious ones like staging mode being enabled/disabled), then you’ll be ready to switch-over synchronization duties to the new AADConnect instance.

    Where do I go to correct these configuration differences?

  28. Jason Mabry

    Thanks for the detailed post. Extremely helpful!

    On the comparison report that was generated, all looks good with the exception of the new instance adding 4 new items under the Domain Connector Configuration:
    Under Outbound Conditional Join Rules, and under Outbound Synchronization Rules, it added
    Out to AD – Device STKKey
    Out to AD – User NGCKey

    I can’t find any place in the AAD Configuration Wizard that says anything about these. Does anybody have any idea what these are and if they will negatively affect our directory synchronization?

    1. Jason

      NGCKey seems to be for Windows Hello.
      STKKey I’m trying to figure out.

      1. Jason

        Actually, both are for Hello. Stumbled on it when reviewing the XML.In the XML files below they both seem to have links to AD attribute msDS-KeyCredentialLink.
        Out to AD – User NGCKey.xml
        Out to AD – Device STKKey.xml

        1. Jorge

          Hi Jason , you may have already figured this out but , just fYI – We had those 2 missing rules too , Those are indeed used for WHfB , the msDSKeyCredentialLink is part of the new attributes when you upgrade your Schema to ver 85 (2016 ) – In our case we forgot to Refresh the schema in the AAD Connect Server we were migrating too (it was installed before the schema was upgraded) –

          Once we did that and configured both the device writeback and Hybrid Join options we saw those 2 rules created. – Hope this helps

        2. Tyler

          So did this stop you from proceeding Jason? I have the same thing on my new ADConnect and didn’t wanna break everything.

  29. Mike Page

    Not too sure how often this article may still be looked at but just have a quick question.

    I worked through the process to install AD Connect on a new server and everything looks great. This article was amazing at making everything easy to understand. After a lot of hours I have the old install matching the new install as per the handy comparison tools.

    I am very new to Office 365 and AD Connect so despite everything looking ready I have a fear that once I put the new AD Connect live and remove the old one that it could potentially sync the wrong thing and remove all the current mailboxes. First of all, is this even possible? If I was syncing a container of 100 users on the old server and then accidentally sync a container with zero users on the new server would it then remove the 100 mailboxes? Secondly, is there anyway with AD Connect to do a test sync where it doesn’t actually synchronize but will show me what it would have synchronized? It would be great if I could produce a list on the staging server of the mailboxes and groups that would be synchronized to compare that to what is currently there.

    Any help is appreciated!

    1. Edward Huggett

      Yes, I had this happen with resources and shared mailboxes. You can restore them from Deleted users, however unless you fix the OU issue, it will keep deleting them.

  30. Sebastian

    Thank You for the great article!

    After migrating to a new server, I can see two On-Premises Directory Synchronization Service Accounts with different GUIDs in the O365 Cloud (the new one and the old one).

    Both users are shown as Active Directory synchronized.
    AD-Connect uses the correct account to synchronize with O365.

    Any sugestions to get rid of the old one?


  31. Chaz

    Hey Paul,

    I am working on a migration project for a client whom already have AD Connect installed. I need to enable one of the features under custom install;

    Uniquely identifying yours users
    -User identities exist across multiple directories
    –ObjectSID and msExchMasterAccountSID…

    Any tips on how best to perform this reinstall? Can I just disable sync, uninstall and reinstall?



  32. Rajiv

    Few queries:

    Can we use the same service account between the old AADConnect server or new server during the custom installation, as we have OKTA for SSO.

    Is there simple way to assign permission to new service account for custom installation (considering Exchange Hybrid and OKTA SSO) in environment

    Can we use parallel deployment between the old server and new staging? Export config with switch /forceexport and import config with switch /migrate as for DirSync upgrade

  33. Stacey

    Something has happened to the SQL instance on our server running AAD Connect and I cannot get the AADSync service to start. I have tried repairing SQL and nothing seems to help. The AADSync service says: A network-related or instance-specific error has occurred while establishing a connection to SQL Server. Server is not found or not accessible. I assume this is a SQL issue but I want to know is can I just uninstall and reinstall AAD Connect to have a new SQL instance created?

  34. Jon A

    thank you… that puts my mind at ease…… good book by the way, lot to read but very helpful information.

  35. Jon A

    the domain should be “” but there is also a “” domain listed as well. that is what is showing up in the sync manager screen for the connector names. “ – AAD” and “”. In the old server being retired, the sync manager shows the connectors as “ – AAD” and “”

    1. Avatar photo
      Paul Cunningham

      The domain is your tenant domain. Every tenant gets to choose a unique * domain when they sign up. You then add your custom domains like afterwards.

      My AAD Connect connector names have the tenant domain. It’s not a problem.

      1. jack

        I may be asking the same question, the original Server Azure AD Connector Report shows:
        domain.local Connector Configuration – AAD Connector Configuration

        On the Server to be migrated to, I’ve installed the Azure AD Connector, and the Report shows:
        domain.local Connector Configuration – AAD Connector Configuration (Create) – AAD Connector Configuration (Delete)

        Is this correct, is this supposed to happen, when migrating Azure AD Connect to another server? Is one AAD Connector supposed to be removed, and another one Added?

        1. Jim

          Did you ever get this solved? I am experiencing the same issue.

          1. Brett

            I’m seeing the same discrepancy between my old and new server for the tenant name. Were you ever able to figure out if this will cause any issues?

          2. somedude

            OP either doesnt know or doesnt care, from reddit–>

            Yes, you need to rename the connector on the new server (which should still be in staging mode) to the same name as what is on the current server. Open Synchronization Service Manager on the new server, click Connectors, select the connector you want to rename, and click Properties under the Actions window (will be off to the right). Then type in the name of the old connector.

            Now rerun the Azure AD Connect Configuration Documenter. Most of the red should be gone and the configs should be very similar. Double check to make sure the remaining differences are not going to break anything, and then you should be good to cut over to the new server.

            Technically I don’t think the connector names matter; it’s the rules themselves that impact the sync. However if the connector names are not the same the config comparison report is unreadable. Thus you’d be doing the cut over blind which could screw things up.

  36. Jon A

    Paul, the version that is currently installed on the server being retired is 1.1.647 and the new server is 01.1.649. I thought the versions were close enough so I didn’t bother doing an upgrade. As for the customizations, I didn’t do the original installation and I wasn’t left with any documentation. It was farmed out to an organization who is on the mainland (we’re in Honolulu) so I am relying on being able to make edits where necessary to bring everything up to par. I uninstalled from the new server, forced a complete resynchronization on the old server and ran the export program. Reinstalled the new server and ran it’s export and then created the report. The one thing I neglected to do and that was edit the xml connector files so the domain names matched and that is what generated all the Red, Blue & Green issues. Now I have only a couple small items with several precendence numbers that do not match. One is the User Name & Domain Name in the Connector Configuration, another is the mS-DS-ConsistencyGuid in the Connector Configuration Attribute setting.

    1. Avatar photo
      Paul Cunningham

      Ok sounds like you’ve got it worked out. If possible, avoid putting AADConnect on a DC though.

      1. Jon A

        i’m preparing to purchase your O365 for IT book when we get home later today. I still have one item to correct and that is when opening the Synchronization Service Manager, out of the two connectors, one of them is named wrong and that is the one I believe that sends information to the cloud… connector name on the new server is listed as – AAD but on the old server it is just – AAD. I believe this is what has created a second domain within the Setup/Domains in the O365 Admin center. How does this get set to the correct value since all of the MX, CNAME, SRV and TXT records at our registrar are set for plus the old server is syncing to Didn’t have a choice for installing onto the domain controller. Small company with small company budget….

          1. Jon A

            The “second domain” got created within the O365 Admin center under Setup/Domains. There used to only be one listed there. I can send you screen shots but don’t think it would work using this method. I’m assuming you have my email address since it has to be entered in the information box below. Send me a note and I’ll send you a couple screen shots. I promise, I won’t hound you,

          2. Avatar photo
            Paul Cunningham

            Just use obfuscated examples.

            Is the domain called “”, or “”?

      2. Martin

        Any particular reason for avoiding putting it on a DC?

        1. Avatar photo
          Paul Cunningham

          Performance. Ability to blow it away and rebuild it without worrying about the DC role. Just generally good practice to avoid loading extra stuff onto DCs.

  37. Jon A

    Paul, thanks for taking the time to post this procedure. It all seemed simple enough until I performed the installation. I’m migrating from an old 2008R2 server which is a AD DC to a 2016 server which will also be a AD DC. When I ran the AAD Documenter, the resultant set of Blue modifications/updates to values, Green “Creates” and Red strike throughs were pages and pages. I attempted to find where to make changes but the only thing I can find that will make changes is the Synchronization Rules Editor and it didn’t appear to match the changes that needed to be made. On our old server when you execute the Sync Service Manager, the domain names are different between the old and new. On the new server, the name will show AAD whereas the old shows AAD. This shows up in the O365 Admin console as well even though I have it configured in staging mode.

    1. Avatar photo
      Paul Cunningham

      Does the old server have an up to date version of Azure AD Connect installed?

      I can’t see your environment or the reports so I’m only guessing here, but it sounds like you made customizations on the original server and would now need to repeat those customizations on the new server. Hopefully you’ve got them documented from when they were originally made.

  38. MikeD


    I’m currently in the process of migrating Azure AD Connect to the server. Thanks for this article, it’s a great help.

    I don’t think it’s an issue, but the actual install was setup using one of the verified custom domain in the tenant. When I installed AADC on the new Server, I used the domain as the AAD Connector. Will this difference be an issue in the end ?

    Best regards,

  39. Fred

    Hi Everyone, just a question, because my company has the necessity to deploy another ADconnect server before in staging mode and later in production. We have deployed ADFS server with different endpoints (Not only Office 365). When I run the wizard to install AdConnect in the new server, that temporary will be a “stage mode AdConnect”, should I configure my ADFS farm? considering that later, the server that is in production will be a “stage mode adConnect” and the new one will be in production?

    Looking forward to hearing from you

    Kind regards


    1. Bryan

      Hi Fred/everyone,

      Wondering how you made out here regarding the ADFS part of this setup. I also have ADFS setup and am also deploying a second AD Connect server in staging mode, for now just to migrate AD Connect, but in the future may look at doing this for DR purposes. From the AD Connect install documentation it says “If you have existing federation trust with Azure AD configured on the selected AD FS farm, the trust will be re-created again from scratch by Azure AD Connect”. I hesitate to enter my existing ADFS farm settings from the “Staging” node installation, fearing that “the trust will be re-created from scratch” will cause unforeseen issues.


  40. Dominik

    Great article, very helpful!

  41. Ash Smith

    Hi, Thanks for the article. It is very helpful. I have a question about database used. I have NOT used SQL express. I have the AD connect database running on a separate SQL server. For the new server, do I point it at the same database, or at a brand new one (which will probably be on the same SQL instance).


    1. Avatar photo
      Paul Cunningham

      Not sure, but I assume it needs its own DB instance separate from the existing one. Maybe there’s some doco on TechNet/Docs that will answer that for you.

  42. Damon

    After running the comparison report between the two servers the ‘Legend’ at the top of the report indicates ‘Create’ in green, ‘Update’ in blue, and ‘Delete’ in red.

    Are these actions that I need to take or what will happen once I disable ‘staging mode’ on the new server?

    Thanks in advance.

    1. Avatar photo
      Paul Cunningham

      The report is telling you the differences between the two servers configs. If Server 1 has a config item configured to X, and Server 2 has the same config item configured to Y, when you flip over to Server 2 that setting will be Y. If you want it to actually be X, you need to make that change on Server 2 yourself.

  43. Fred

    Hello, thanks this Help
    i have a question about sourceanchor. In a previous installation, the sourceanchor was objectGUID. When i install ad connect (last download) on a new server, i let ad connect in customize installation choose the sourceAnchor, and at the end of the installation , the sourceanchor is : msDS-ConsistencyGuid.
    Do you think i can continue with this, or i must uninstall, upgrade the first server to the last ad connect installation, upgrade the sourceanchor and reinstall ad connect on the new server ?
    Thanks for your response.

  44. vince

    thanks for the step by step article exactly what I was looking for. taking it a step further. do you see if there is any issue to leaving the 2 X AADconnect running in parallel in a long term setup. like a primary and secondary connector in case the primary server fails. so you can bring up immediately?

    1. Avatar photo
      Paul Cunningham

      You can have a pre-configured server ready to switch on if the active one fails. You just can’t have both of them operational (i.e. running syncs) together.

  45. Jim Barr

    Forget it.. downloaded the code instead of the actual program. Thanks.

  46. Jim Barr

    I followed all instructions, but the script will not run because there is no *.exe file associated with the latest download. The CMD file refers to a program that isn’t included in this package download. This is really too bad, as I was getting excited to see the results. I hope someone can point out the issue with this and let me know if it’s me or if the script needs to be altered, or someone removed the program from the download.

  47. Jim Barr


    C:\AADConnectConfigDocumenter\src>AzureADConnectSyncDocumenterCmd.exe “domain\server1” “domain\server2”
    ‘AzureADConnectSyncDocumenterCmd.exe’ is not recognized as an internal or external command,
    operable program or batch file.
    Press any key to continue . . .

    I cannot get past this.. please help.

  48. Raymond Mestrandrea


    Thanks great article. Planning on migrating to O365 and my AD-connect is installed on my Exchange server which I am decommissioning. My question is my MSP is telling me I need to install it on a domain controller with Active Directory Services. I remember dirsync best practice was a member server. Which is it. I have a choice between my File Server which I would prefer or my domain controller.

    1. Avatar photo
      Paul Cunningham

      It is not best practice to put it on a domain controller. A member server is ideal. You definitely should not put it on the Exchange server.

  49. Mike Wells

    I plan to do something very similar to this… I have an older Azure AD Connect instance running on a Server 2018 R2 VM and plan to replace it with the latest version on a new Server 2016 VM. I’m curious why you don’t suggest using the “import/export server configuration” options.

    If I can live with the lack of synchronization during the work, what would be the downside of exporting up the old server configuration, shutting it down, importing the configuration to the new server and letting it rip?


    1. Avatar photo
      Paul Cunningham

      When I wrote this the export/import wasn’t available or supported (IIRC it is supported for full blown FIM installs only). If that’s changed since then, go for it. Otherwise, the technique I demonstrated works for me.

  50. Nima Jahanbin

    Great article. It has really helped me in what I am trying to do.

    My objective: Assure that DR (Staging) Azure AD connect server is configured exactly as the prod is.

    Would you be able to help me with the following:
    -Is there a way to configure the staging server to stay in sync with the prod server? Your article states “will stay up to date with the latest changes in the on-premises Active Directory and Azure AD. However, it will not export any changes to the directories until staging mode is disabled” . This doesn’t seem to be the case for me. Any idea why that may be?

    -I have ran the AADConnectConfigurationDocumenter tool and created a report. There is a discrepancy that seems to be causes by the rank of the connector within the metaverse. Any idea how i change the rank?

    -MS Support has indicated to me that the AADConnectConfiguraitonDocumenter can be used to generate PS commands that would mimic the configuration. Any guidance in how that is done?


    1. Avatar photo
      Paul Cunningham

      Not sure what you mean when you say “This doesn’t seem to be the case for me.”

      I haven’t seen the discrepancy you describe so I’m not sure what or why that’s happening.

      MS Support couldn’t provide you with more detail on that suggestion? I haven’t looked closely at it myself.

  51. Chris Parker

    I came across something that, at first glance, seemed alarming but ended up being cosmetic only.

    The O365 connector was given a different name on the new server than on the old one. This made the report look like everything had changed between the two installations.

    I renamed the connector on the new machine, grabbed the configuration again, and then rebuilt the report. There was another instance of an naming change in the new configuration (an Outbound Join Rule) but that too was just cosmetic. I left it alone.

    These naming changes were probably due to my originally having set this up a long time ago and a new install being slightly different than a new install from a previous version.

  52. Javier

    Thanks Paul for your article.
    I’m migrating from an express settings instalation, and then,nobody knows the password for the service account. Is ther eany way to reuse that account for synchronization without changing its password?

    Another option… with the express settings do I have the chance to set the staging mode before replication starts?

  53. Mark Levy

    Thanks for the terrific article. Just a question regarding a simpler migration… Our AAD Connect server is running on 2012R2 in a VMware VM, and we want to do a simple VtoV migration to a new vSphere infrastructure, with no other changes (IP address will remain the same, we can set the same MAC address in the NIC if need be.)

    Are there any problems we might encounter, with the server shutdown for the process, which we expect will take roughly 2 hours.



    1. Avatar photo
      Paul Cunningham

      I haven’t done it, so I don’t know, other than having no sync running for that period of time.

    2. Ben

      No problem with that. You could even switch from VtoP or VMWare to HyperV or the other way round, just make sure you suspend synchronization until you’re confident with the Operating System reconfiguration (drivers, network connectivity, etc.)

  54. Valentin


    I want to migrate Azure AD Connect to a new server in a new domain.
    I have to migrate my AD onpremise to a new forest-domain.
    What are the correct stepts to migrate Azure AD Connect to this new Forest-domain?

  55. yogesh sharma

    Very simple and self explanatory. thanks for putting it out.

    1. Erik

      SIMPLE??? It tool me 2 hours to get this documenter running. Documentation of this all is very lazy, and obviously for nerds the got born with azureadsync, made aad in preschool, made aad in school,… no way to follow this in an acceptable time for a “simple enterprise administrator”… Well, if you have 2 weeks to follow this, and learn everything you need, then maybe it’s simple.

Leave a Reply