HOWTO: Perform an Azure AD Connect Swing Migration - The things that are better left unspoken (2023)

Azure AD Connect is a crucial component in today’s Hybrid Identity strategies. This tool takes care of the synchronization of objects and their attributes from an on-premises Active Directory environment to Azure AD. In some scenarios, it also takes care of authentication when accessing Azure AD-integrated applications.

As with any system in a networking infrastructure, sometimes something bad happens to Azure AD Connect installations. And sometimes… you want to start over with Azure AD Connect. This blogpost details how to perform a swing migration for a current Azure AD Connect installation to a new Azure AD Connect installation.

We’ll be using the new Export and Import configuration functionality in Azure AD Connect to this purpose. This functionality was introduced in Azure AD Connect version 1.5.42.0.

You might ask yourself: “What is this guy talking about?”.

About Azure AD Connect

Azure AD Connect is a component that synchronizes between the on-premises Active Directory Domain Services environment (your Domain Controllers) and Azure AD, the cloud service. Through synchronization cycles, objects and their attributes are read from both identity stores and matched in its own database, dubbed the 'metaverse'. Through its synchronization rules, Azure AD Connect picks up on changes. It determines if an action is required, and if so, what action is required when an object appears in scope, disappears from scope, or is changed. Then, Azure AD Connect performs the changes.

About staging mode

For the purpose of this blogpost, we’ll use the Staging Mode feature in Azure AD Connect. This mode offers a second Azure AD Connect installation with a second metaverse. The Staging Mode server, however, is not instructed with actions; it doesn't perform changes to objects in AD or Azure AD (in terms of sync cycles, it only performs imports).

A swing migration of Azure AD Connect consists of these steps:

1. Getting ready
2. Upgrade Azure AD Connect
3. Inventory the current Azure AD Connect installation
4. Export the Azure AD Connect configuration
5. Prepare for the Staging Mode Azure AD Connect installation
6. Create the Staging Mode Azure AD Connect installation
7. Compare the Export to the Applied Synchronization Policy
8. Compare both metaverses
9. Switch the current Azure AD Connect installation into Staging Mode, too
10. Configure the Staging Mode server for active synchronization
11. Check the Synchronization Service
12. (Optionally) Optimize the Azure AD Connect database
13. (Optionally) Decommission the first Azure AD Connect installation
14. (Optionally) Remove the first Azure AD Connect installation’s SQL database
15. (Optionally) Remove lingering service accounts

Before you begin

There are a couple of challenges associated with Staging Mode and when implementing a new Azure AD Connect installation. It’s best to be aware of these before you begin:

• If the scope in terms of OU Filtering, App and Attribute Filtering or Group Filtering are not configured identical between the two installations, you will end up with different object and/or attribute scopes.
• If the organization made choices in terms of Alternate Login ID, authentication method or source anchor attribute, and you don't configure these settings identically between the two installations, authentication to Microsoft online services might break for your end-users.
• If you configure the service account to Active Directory manually, and you don't reuse this account and/or you setup a new account with different delegated privileges, synchronization may not be performed without errors. If the previous Azure AD Connect uses the built-in administrator account in Active Directory, you’re bound to encounter export errors with a properly delegated account on the first export.
• If you configure the new Azure AD Connect with different settings in terms of Optional Features, functionality like Exchange Hybrid, Exchange Hybrid Public Folders, Group Writeback and Password Writeback might break.

Luckily, a lot of Azure AD Connect settings have been synchronized to Azure AD in the last years of Azure AD Connect releases. This includes the source anchor and the export deletion threshold.

Recommended practices

Please try to adhere to the following recommended practices:

• With an Azure AD Connect Staging Mode installation in the networking environment, make sure to implement a life cycle management process for Azure AD Connect.
• Describe an owner for the Azure AD Connect installations, their service accounts and the functionality they offer within the organization.
• Delegate permissions in Active Directory based on groups and not on individual accounts.
• Do not reuse the service accounts to communicate with Active Directory between Azure AD Connect installations.
• Do not reuse the SQL database between Azure AD Connect installations.
• Provide the minimum required privileges to the Azure AD Connect service accounts that communicatie with Active Directory.
• Provide the minimum required network connectivity between Azure AD Connect installations, Domain Controllers, AD FS servers, Web Application Proxy servers, Pass-through Authentication agents and Azure Active Directory, respectively.
• Change the passwords for service accounts at least yearly.

Step 1, Getting ready

To be able to perform the next steps, take care of the following:

Required systems

This How-to features a pre-existing Azure AD Connect installation. This is the first and most important system in scope. Then, of course, there are Domain Controllers and there is an Azure AD tenant. This version of Azure AD Connect needs to run at least version 1.5.42.0.

There is one new system: a new Azure AD Connect installation. Make sure this system runs Windows Server 2012, or up. Intend to install Azure AD Connect version 1.5.42.0, or up, on it.

Note:
Windows Server 2012 and Windows Server 2012 R2 are currently in extended support. For best results, implement a new server running Windows Server 2016, or up.

Required Privileges

You must have access to credentials for accounts with the following privileges:

• An account in Azure Active Directory with the Global Administrator role.
• An account in Active Directory with a membership in the Enterprise Admins group.
• An account on the Windows Server hosting the existing Azure AD Connect installation that is a member of the ADSyncAdmins local group (can be a local account to the Windows Server, or an account from Active Directory).

Database

By default, Azure AD Connect is installed with local SQL Server Express. However, you can choose to use a database on a pre-existing SQL Server. If so, create a new database on the SQL Server. If the SQL Server features Always-on Availability groups, make the database highly-available after configuring Azure AD Connect on the new Azure AD Connect installation.

Service accounts

Azure AD Connect features three service accounts:

• A local account on the Windows Server installation running Azure AD Connect, used to run the he Microsoft Azure AD Sync service.

Note:
This account can be an automatically created virtual service account (VSA) or an Active Directory-based group Managed Service Account (gMSA).
If you use a Microsoft SQL database, you cannot use a VSA.

• A synchronization account in the Azure Active Directory tenant.
• One automatically created account or pre-configured account per Active Directory Domain Services environment.

For the second account, create the account in Active Directory before starting the configuration of Azure AD Connect on the second server.

Firewalls and proxies

Some networks are highly compartmentalized. In these networking environments, make sure both Azure AD Connect installations can communicate to the Domain Controllers and optionally a central SQL Server (cluster). Also make sure the required traffic to Azure AD is allowed for both servers through firewalls and via outbound proxies.

When using AD FS as the sign-in method, make sure Azure AD Connect can communicate to the AD FS servers and Web Application Proxy servers. When using Pass-through Authentication agents, allow these to communicate to Domain Controllers.

Step 2, Upgrade Azure AD Connect

First, we need to upgrade Azure AD Connect to version 1.5.42.0, or up. Overall, it is a recommended practice to upgrade Azure AD Connect to the latest stable version.

Perform these actions on the Windows Server running the existing Azure AD Connect installation:

• Sign in interactively to the Windows Server installation.
• Open a browser and download the latest version of Azure AD Connect.
• Run the downloaded AzureADConnect.msi.
  The Microsoft Azure Active Directory Connect wizard appears.
• On the Upgrade Azure Active Directory Connect page, click Upgrade.
• On the Connect to Azure AD page, enter the credentials of the Azure AD account with the Global administrator role. Click Next.
  Perform multi-factor authentication, when prompted.
• On the Ready to configure page, click Upgrade.

• On the Configuration complete page, click Exit.

Step 3, Inventory the current Azure AD Connect installation

Perform these steps on the Windows Server running the pre-existing Azure AD Connect installation:

• Sign in interactively to the Windows Server installation.
• Run the following line of Windows PowerShell in an elevated PowerShell window:

(Get-ADSyncGlobalSettingsParameter | Where-Object { $_.Name -eq 'Microsoft.Synchronize.ServerConfigurationVersion'}).Value

• Verify that the Azure AD Connect version is indeed version 1.5.42.0, or up.
• Next, run the following two lines of Windows PowerShell:

Import-Module "C:\Program Files\Microsoft Azure AD Sync\Bin\ADSync\ADSync.psd1"

Get-ADSyncDatabaseConfiguration

• If the returned value for SqlServerName is (localDB), then the Azure AD Connect installation uses a locally installed SQL Server Express installation to store the Azure AD Connect database. If, instead, a server name is used, it’s a good idea to contact the database admin for the server and see whether you’d want the new Azure AD Connect installation to use the server to host the new Azure AD Connect database, too. When you do, you’ll want to note the value for SqlServerDBName too, as two databases on the same SQL Server listener isn’t smart.
• Now, we’d want to know the specifics of the service account for the Active Directory connector(s). Use the following two lines of Windows PowerShell:

Import-Module "C:\Program Files\Microsoft Azure Active Directory Connect\AdSyncConfig\AdSyncConfig.psm1"

Get-ADSyncADConnectorAccount

• The output shows you the ADConnectAccountName per Active Directory environment in scope for Azure AD Connect. This gives you an idea about the current service account. When investigating this account, it’s good to know whether it’s an automatically created account (its name starting with MSOL_) or an account that was pre-created and perhaps has memberships in a group that provides the necessary permissions in Active Directory already. In the latter case, creating the Azure AD Connect service account in Active Directory is a relative breeze.
• Lastly, run the following line of Windows PowerShell to get a view of the four groups that are created by Azure AD Connect in Windows Server to delegate Azure AD Connect administrative privileges:

Get-LocalGroup -Name *Sync*

• This will give you an idea of the group names chosen, when the option was checked in Azure AD Connect to use custom group names. Looking at the memberships of these groups provides insights in the way Azure AD Connect is managed within the environment.
• Close the Windows PowerShell window.

Step 4, Export the Azure AD Connect configuration

The rest of the settings, we can get through the new functionality in Azure AD Connect to export and then import the Azure AD Connect configuration.

Through the wizard

You can export the configuration through the Azure AD Connect wizard. Perform these steps:

• Open Azure AD Connect from either the Desktop or the Start Menu. Alternatively, you can run C:\Program Files\Microsoft Azure Active Directory Connect\AzureADConnect.exe
• The Microsoft Azure Active Directory Connect window appears.
• On the Welcome to Azure AD Connect screen, click the Configure button.

• On the Additional Tasks screen, select the View or export current configuration task. Click Next.
• On the Review Your Solution page, click the Export Settings button.
  The Export Azure AD Connect Settings screen opens. It asks to save a json-formatted file into the default C:\ProgramData\AADConnect folder. Choose a folder and filename of your choosing and click the Save button when done.
• On the Review Your Solution page, click Exit. This closes the Microsoft Azure Active Directory Connect window and resumes synchronization.

Through Windows PowerShell

The option to export the configuration is also available in Windows PowerShell.

Run the following two lines of Windows PowerShell in an elevated PowerShell window to achieve this goal:

cd "C:\Program Files\Microsoft Azure Active Directory Connect\Tools"

MigrateSettings.ps1

The PowerShell script saves the json-formatted file, along with all the other relevant data of the Azure AD Connect installation into the C:\ProgramData\AADConnect folder.

Step 5, Prepare for the Staging Mode Azure AD Connect installation

Now, we have all the information we need to prepare for the Staging Mode Azure AD Connect installation.

Pre-create the group Managed Service Account and database

If the current Azure AD Connect installation uses a Microsoft SQL Server (cluster) to store the Azure AD Connect database, then you’ll want to pre-create the gMSA, pre-create the SQL Server database and set the right permissions on the database before installing the new Azure AD Connect installation.

Note:
Do not reuse service accounts or databases between Azure AD Connect installations.

Use the following lines of PowerShell on a system with the Active Directory Module for Windows PowerShell installed, while signed in with a user account that is a member of the Domain Admins group in the same Active Directory domain as where Azure AD Connect is going to be installed, supposing AADC01 is the hostname of the server intended to run Azure AD Connect:

Import-Module ActiveDirectory

New-ADServiceAccount AADC1gMSA -DNSHostName AADC1gMSA.domain.tld -PrincipalsAllowedToRetrieveManagedPassword "CN=AADC01,CN=Computers,DC=domain,DC=tld"

On the SQL Server, perform the following actions:

• Start Microsoft SQL Server Management Studio.
• Connect to your server in the Connect to Server dialog
  screen.
• In the left navigation pane, right-click on Databases
  and select New Database….
• In the New Database dialog screen, enter the name for
  the database.
• Click OK to create the database.
• In the left navigation pane, expand Security.
• Right-click the logins node and select New
  login….
  The Login – New dialog screen opens on the
  General page.
• Specify AADC1gmsa$ as the Login
  name:. and make sure Windows Authentication
  is selected as the login method.
• In the left navigation pane, click on User Mapping.
• On the User Mapping page, select the Azure AD Connect
  database you created in steps 3 through 5 from the list of databases in the
  Users mapped to this login:.
• In the Database role membership for:
  ADSyncAADC01 select db_owner.
• Click OK to create the login and set the database
  permissions.
• Close Microsoft SQL Server Management Studio.

Next, on the new Azure AD Connect installation, perform the following lines of Windows PowerShell to install the group Managed Service Account (gMSA):

Install-WindowsFeature RSAT-AD-PowerShell

Import-Module ActiveDirectory

Install-ADServiceAccount -Identity AADC1gMSA

Uninstall-WindowsFeature RSAT-AD-PowerShell

Pre-create the Active Directory connector account(s)

If the current Azure AD Connect installation uses a service account whose account name doesn’t start with MSOL_, then you might want to opt to pre-create a service account for the new Azure AD Connect installation, too.

Use the following lines of PowerShell on a system with the Active Directory Module for Windows PowerShell installed, while signed in with a user account that is a member of the Domain Admins group for the Active Directory domain(s) where the objects reside that will be in scope of Azure AD Connect:

New-ADUser -Name:"AADSync02" -Path:"CN=Users,DC=domain,DC=tld"

$Id = "CN=AADSync02,CN=Users,DC=domain,DC=tld"

Set-ADAccountPassword -Identity:$Id -NewPassword:"P@ssw0rd" -Reset:$true

Enable-ADAccount -Identity:$Id

Set-ADObject -Identity:$Id -ProtectedFromAccidentalDeletion:$true

Set-ADUser -ChangePasswordAtLogon:$false -Identity:$Id -SmartcardLogonRequired:$false

Then, add the new user account to the groups that provide Azure AD Connect permissions in Active Directory.

Repeat the steps for any other domains in scope for Azure AD Connect.

Step 6, Create the Staging Mode Azure AD Connect installation

Now, we’ve ticked all the prerequisites. It’s time to create the new Azure AD Connect installation in Staging Mode. Perform these steps:

• Sign in interactively to the Windows Server installation.
• Open Server Manager if it hasn’t started by default.
• In Server Manager‘s left navigation menu click on Local Server
• In Server Manager’s main pane turn off the IE Enhanced Security Configuration feature.
• Close Server Manager.
• Open a browser and download the latest version of Azure AD Connect.
• Run the downloaded AzureADConnect.msi.
  The
  Microsoft Azure Active Directory Connect wizard appears.
• On the Welcome to Azure AD Connect page, select the I agree to the license terms and privacy notice. option.
• Click Continue.
• On the Express Settings page, click Customize.
• On the Install required components page, make the following changes:
  • (Optionally) Select the Use an existing SQL Server option and specify values in the SERVERNAME, INSTANCE NAME and DATABASE NAME fields, if you want to use the pre-created database on the SQL Server.
  • (Optionally) Select the Use an existing service account option and specify the credentials of the pre-created service account.
  • (Optionally) Select the Specify custom sync groups option and specify the group names for the four built-in Azure AD Connect roles.

• • Select the Import synchronization settings option.
  • Click the Browse button.
    The Import Azure AD Connect Settings screen opens.
  • Navigate to the (network) folder where the *.json file is located and select it.
  • Click Open.
• Back in the Microsoft Azure Active Directory Connect screen, click Install.

Now, all the choices of the other Azure AD Connect installation will be prepopulated for you. If need be, you can change settings during the configuration of Azure AD Connect. If you don’t want to make changes, you can simple click Next on every page, with the following exceptions:

• You will need to enter the credentials of an account in Azure AD with Global Administrator privileges on the Connect to Azure AD page. You will need to perform multi-factor authentication when required, too.
• On the Connect your directories page, you will need to enter the credentials of the Active Directory Connector account for each Active Directory forest that you want to add, or the credentials of an account with membership to the Enterprise Admins group in each of the Active Directory forests to create the required accounts.
• In case of AD FS as the sign-in method, you will need to enter the credentials of an account with membership to the Domain Admins group in the Active Directory domain to which the AD FS implementation belongs.
• In case of AD FS as the sign-in method, you will need to specify the information of the existing AD FS farm and select the Azure AD domain to federate. The custom domain name will be updated with the settings of the AD FS implementation.

On the Ready to configure page, the Enable staging mode: When selected, synchronization will not export any data to AD or Azure AD option is selected by default. Click Install on this page to configure Azure AD Connect.

On the Configuration complete page, click Next (in case of AD FS as the sign-in method) or Exit.

Step 7, Compare the Export to the Applied Synchronization Policy

Azure AD Connect has created an Applied-SynchronizationPolicy-<date>–
<time>.json file in the folder C:\ProgramData\AADConnect. Compare this file to the Exported-SynchronizationPolicy-<date>-<time>.json file to see any differences in the configuration of both Azure AD Connect installations.

Step 8, Compare both metaverses

Before we switch the actively synchronizing Azure AD Connect installation, with the Staging Mode Azure AD Connect installation, I tend to compare the contents of the metaverses.

From the Start Menu, open Synchronization Service on both Azure AD Connect installations. Compare the number of objects in the metaverses between both Azure AD Connect installations and sample a couple of objects for their attributes.

Step 9, Switch the current Azure AD Connect installation into Staging Mode, too

As we can only have one actively synchronizing Azure AD Connect installation, we need to configure the current Azure AD Connect installation into Staging Mode, too. Perform these steps on the current Azure AD Connect installation:

• Start Azure AD Connect from the desktop.
• Acknowledge User Account Control by pressing Yes.
  The Microsoft Azure Active Directory Connect window appears.
• On the Welcome to Azure AD Connect screen, click Configure.
• From the list of Additional Tasks, choose Configure staging mode.
• Click Next.
• On the Connect to Azure AD screen, sign into Azure AD with
  an account that has the Global Administrator / Company administrator role in
  the connected Azure AD tenant. Perform multi-factor authentication and/or
  privileged identity management (PIM) steps, when needed.
• On the Configure Staging Mode screen, select the Enable staging mode option.
• Click Next.
• On the Ready to configure screen, click Configure.
• On the Configuration complete screen, click Exit.

Step 10, Configure the Staging Mode server for active synchronization

Perform these steps on the new Azure AD Connect installation:

• Start Azure AD Connect from the desktop.
• Acknowledge User Account Control by pressing Yes.
  The Microsoft Azure Active Directory Connect window appears.
• On the Welcome to Azure AD Connect screen, click Configure.
• From the list of Additional Tasks, choose Configure staging mode.
• Click Next.
• On the Connect to Azure AD screen, sign into Azure AD with
  an account that has the Global Administrator / Company administrator role in
  the connected Azure AD tenant. Perform multi-factor authentication and/or
  privileged identity management (PIM) steps, when needed.
• On the Configure Staging Mode screen, unselect the Enable staging mode option.

• Click Next.
• On the Ready to configure screen, click Configure.
• On the Configuration complete screen, click Exit.

The new Azure AD Connect installation will now perform a full synchronization cycle.

Step 11, Check the Synchronization Service

As the first synchronization cycle with the new AD Connector account puts the privileges of the account to the test, check the synchronization service for errors. Perform these steps on the new Azure AD Connect installation:

• From the Start Menu, open Synchronization Service.
  The Synchronization Service Manager window appears.
• In the main pane, check the Status column in the list of Connector Operations for errors. If there are errors, resolve these, so they don’t appear on the next run.
• Close the Synchronization Service Manager window.

Step 12, (Optionally) Optimize the Azure AD Connect database

If the Microsoft SQL Server is configured with the Always-On Availability Group feature, you can now make the Azure AD Connect database highly available. Perform these steps to do so:

• Start Microsoft SQL Server Management Studio.
• Connect to your server in the Connect to Server dialog
  screen.
• In the left navigation pane, expand Always On High Availability and right-click on Availability Groups. Select the New Availability Group Wizard… option from the context menu.
  The New Availability Group screen appears.
• On the Introduction page, click Next.
• Enter the name of the Availability Group in the Availability group name: field and click Next.
• On the Select Databases page, select the checkbox to the left of the Azure AD Connect database to include it in the Availability Group. Click Next.
• On the Specify Replicas page under the Replicas tab, select the other Microsoft SQL Servers to host the database.
• Under the Listener tab, select the Create an availability group listener option and specify a listener DNS name and port. Click Add… when done and provide an IP address.
• Click OK.
• Click Next.
• On the Select Initial Data Synchronization page, select the Full option.
• Click Next.
• On the Validation page, verify that all validation checks are successful.
• Click Next.
• On the Summary page, click Finish.
• On the Results page, verify that all tasks have been completed successfully.
• Click Exit.

Step 13, (Optionally) Decommission the first Azure AD Connect installation

The first Azure AD Connect installation is now a Staging Mode installation, that no longer performs exports to Active Directory or Azure AD. It can be decommissioned, by uninstalling Azure AD Connect from the system. Perform these steps to do so:

• Sign in interactively with an account that has local administrator privileges.
• Right-click the Start button and select Apps and Features from the context menu.
• In the list of Apps & features, select Azure AD Connect.
• Click the Uninstall button in the additional information field for the Azure AD Connect installation.

Step 14, (Optionally) Remove the first Azure AD Connect installation’s SQL database

On the Microsoft SQL Server, you can now safely delete the database for the original Azure AD Connect installation.

Step 15, (Optionally) Remove lingering service accounts

When the original Azure AD Connect installation used a service account, you can now safely remove it. Use the following line of Windows PowerShell to do so:

Remove-ADUser -Identity "CN=AADSync01,CN=Users,DC=domain,DC=tld"

Performing a swing migration of Azure AD Connect is more straight-forward using the new import/export configuration functionality in Azure AD Connect since 1.5.42.0.