Home » Identity » Migrating Azure AD Connect to a New Server

Migrating Azure AD Connect to a New Server

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.

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.

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.

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

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.

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).

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.

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.

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

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.

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).

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.

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.

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).

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

Paul is a Microsoft MVP for Office Servers and Services. He works as a consultant, writer, and trainer specializing in Office 365 and Exchange Server. Paul is a co-author of Office 365 for IT Pros and several other books, and is also a Pluralsight author.
Category: Identity


  1. Valentin says:


    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?

  2. Mark Levy says:

    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.



    • Ben says:

      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.)

  3. Javier says:

    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?

  4. Chris Parker says:

    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.

  5. Nima Jahanbin says:

    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?


    • 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.

  6. Mike Wells says:

    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?


    • 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.

Leave a Reply

Your email address will not be published. Required fields are marked *