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:
- Review the configuration of the existing Azure AD Connect instance
- Install the new Azure AD Connect instance in staging mode
- Compare configurations of the old and new servers
- Swtich-over synchronization to the new server
- 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).
|
1 |
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.
|
1 |
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.
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 Apps and Services and a Pluralsight author. He works as a consultant, writer, and trainer specializing in Office 365 and Exchange Server.
Didn’t know the ConfigDocumenter, very handy. One thing I miss in this article is the ‘verify the configuration’ steps when in Staging mode, described at this article https://docs.microsoft.com/en-us/azure/active-directory/connect/active-directory-aadconnectsync-operations#staging-mode
Very simple and self explanatory. thanks for putting it out.
Hi!
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?
Thanks.
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.
Thanks!
Mark
I haven’t done it, so I don’t know, other than having no sync running for that period of time.
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.)
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?
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.
Paul,
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?
Thanks,
Nima
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.
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?
Mike
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.
Paul,
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.
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.
Errors:
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.
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.
Forget it.. downloaded the code instead of the actual program. Thanks.
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?
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.
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.
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.
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.
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).
Thanks.
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.
Thanks Paul. Seems it’s only supported to have one “Sync Engine” pointing at a single database, and also one “Sync engine” pointing at a single database instance!
https://docs.microsoft.com/en-us/azure/active-directory/connect/active-directory-aadconnect-prerequisites
Great article, very helpful!
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
Fred
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.
Thanks,
Bryan
Hi
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 tenant.onmicrosoft.com domain as the AAD Connector. Will this difference be an issue in the end ?
Best regards,
Not sure exactly what you mean by that.
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 domain.onmicrosoft.com AAD whereas the old shows domain.com AAD. This shows up in the O365 Admin console as well even though I have it configured in staging mode.
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.
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.
Ok sounds like you’ve got it worked out. If possible, avoid putting AADConnect on a DC though.
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 domain.onmicrosoft.com – AAD but on the old server it is just domain.com – 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 domain.com plus the old server is syncing to domain.com? Didn’t have a choice for installing onto the domain controller. Small company with small company budget….
What is the “second domain” you’re referring to?
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,
Just use obfuscated examples.
Is the domain called “contoso.onmicrosoft.com”, or “contoso.com”?
Any particular reason for avoiding putting it on a DC?
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.
the domain should be “contoso.com” but there is also a “contoso.onmicrosoft.com” domain listed as well. that is what is showing up in the sync manager screen for the connector names. “contoso.onmicrosoft.com – AAD” and “contoso.com”. In the old server being retired, the sync manager shows the connectors as “contoso.com – AAD” and “contoso.com”
The contoso.onmicrosoft.com domain is your tenant domain. Every tenant gets to choose a unique *.onmicrosoft.com domain when they sign up. You then add your custom domains like contoso.com afterwards.
My AAD Connect connector names have the tenant domain. It’s not a problem.
thank you… that puts my mind at ease…… good book by the way, lot to read but very helpful information.
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?
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
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?
Thanks,
Chaz
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?
THX!
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!
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?