Tutorial: Migrate to Microsoft Entra Cloud Sync for a synced Active Directory forest

This tutorial walks you through how to migrate to Microsoft Entra Cloud Sync for a test Active Directory forest that was synced by using Microsoft Entra Connect Sync.

This article provides information for a basic migration. Review the Migrate to Microsoft Entra Cloud Sync documentation before you attempt to migrate your production environment.

In this tutorial, you learn how to:

Considerations

Before you try this tutorial, consider the following items:

• Ensure that you're familiar with the basics of Microsoft Entra Cloud Sync.

• Ensure that you're running Microsoft Entra Connect Sync version 1.4.32.0 or later and that you configured the sync rules as documented.

• During the pilot or coexistence phase, don't remove the pilot organizational unit (OU), group, domain, or any related referenced objects from Microsoft Entra Connect Sync scope. Keep the objects in scope and use the custom cloudNoFlow inbound rule and JoinNoFlow outbound rule described in this tutorial to prevent Microsoft Entra Connect Sync from exporting object adds, object deletes, and non-reference attribute updates.

  Removing objects from Microsoft Entra Connect Sync scope removes them from the Active Directory connector space, metaverse, and Microsoft Entra connector space. This removal can remove references in the connector space and cause reference deletes, such as group membership removals, to be exported to Microsoft Entra ID.

• Ensure that the objects in the pilot scope have ms-ds-consistencyGUID populated so that Microsoft Entra Cloud Sync hard matches the objects.

  Microsoft Entra Connect Sync doesn't populate ms-ds-consistencyGUID by default for group objects.

• Follow the steps in this tutorial precisely. This configuration is for advanced scenarios.

Plan scope removal from Microsoft Entra Connect Sync

Don't remove OUs, groups, or domains from Microsoft Entra Connect Sync scope during the coexistence or pilot phase. Do this only after migration for that scope is complete and you've verified that Cloud Sync is authoritative for the objects and their references.

Before you remove a scope from Microsoft Entra Connect Sync, verify that:

• All objects in that scope are included in the appropriate Cloud Sync configuration.
• Related referenced objects, such as group members and managers, are also migrated or no longer depend on Microsoft Entra Connect Sync for reference maintenance.
• There are no remaining cross-scope or cross-domain references that Microsoft Entra Connect Sync might delete from its connector space and export as reference removals.

Remove a domain from Microsoft Entra Connect Sync only after migration for that domain is complete and you're certain there are no remaining cross-domain references.

Prerequisites

The following are prerequisites required for completing this tutorial

• A test environment with Microsoft Entra Connect Sync version 1.4.32.0 or later
• An OU or group that is in scope of sync and can be used during the pilot. We recommend starting with a small set of objects.
• A server that runs Windows Server 2022, Windows Server 2019, or Windows Server 2016 to host the provisioning agent.
• Source anchor for Microsoft Entra Connect Sync should be either objectGuid or ms-ds-consistencyGUID

Update Microsoft Entra Connect

At a minimum, you should have Microsoft Entra Connect 1.4.32.0. To update Microsoft Entra Connect Sync, follow the steps in Microsoft Entra Connect: Upgrade to the latest version.

Back up your Microsoft Entra Connect configuration

Before you make any changes, back up your Microsoft Entra Connect configuration. This way, you can roll back to your previous configuration. For more information, see Import and export Microsoft Entra Connect configuration settings.

Stop the scheduler

Microsoft Entra Connect Sync synchronizes changes occurring in your on-premises directory using a scheduler. In order to modify and add custom rules, you want to disable the scheduler so that synchronizations won't run while you're working and making the changes. To stop the scheduler, use the following steps:

1. On the server that's running Microsoft Entra Connect Sync, open PowerShell with administrative privileges.
2. Run Stop-ADSyncSyncCycle. Select Enter.
3. Run Set-ADSyncScheduler -SyncCycleEnabled $false.

Create a custom user inbound rule

In the Microsoft Entra Connect Synchronization Rules Editor, create an inbound sync rule that sets the cloudNoFlow attribute to True for users in the OU or group that you identified for the pilot. This attribute is used with the JoinNoFlow outbound rule later in this tutorial to prevent Microsoft Entra Connect Sync from exporting object adds, object deletes, and non-reference attribute updates for these users. Reference attribute updates, such as member and manager, can still flow for reference resolution.

1. Open the Synchronization Rules Editor from the application menu on the desktop.

   

2. Under Direction, select Inbound from the dropdown list. Then select Add new rule.

   

3. On the Description page, enter the following values and select Next:

   • Name: Give the rule a meaningful name.
   • Description: Add a meaningful description.
   • Connected System: Choose the Microsoft Entra connector for which you're writing the custom sync rule.
   • Connected System Object Type: Select user.
   • Metaverse Object Type: Select person.
   • Link Type: Select Join.
   • Precedence: Provide a value that's unique in the system.
   • Tag: Leave this field empty.

   

4. On the Scoping filter page, enter the OU or security group on which you want to base the pilot. To filter on OU, add the OU portion of the distinguished name. This rule applies to all users who are in that OU. So, if the distinguished name (DN) ends with OU=CPUsers,DC=contoso,DC=com, you add this filter. Then select Next.

   Rule	Attribute	Operator	Value
   Scoping OU	DN	ENDSWITH	Distinguished name of the OU.
   Scoping group		ISMEMBEROF	Distinguished name of the security group.

   

5. On the Join rules page, select Next.

6. On the Transformations page, add a Constant transformation: Source value of True for the cloudNoFlow attribute. Select Add.

   

Follow the same steps for all object types (user, group, and contact). Repeat the steps according to the configured Active Directory connector or Active Directory forest.

Create a custom user outbound rule

You need an outbound sync rule with a link type of JoinNoFlow and the scoping filter that has the cloudNoFlow attribute set to True. This rule tells Microsoft Entra Connect Sync not to export object adds, object deletes, or non-reference attribute updates for these users. Reference attribute updates, such as member and manager, can still flow for reference resolution.

1. Under Direction, select Outbound from the dropdown list. Then select Add rule.

   

2. On the Description page, enter the following values and select Next:

   • Name: Give the rule a meaningful name.
   • Description: Add a meaningful description.
   • Connected System: Choose the Microsoft Entra connector for which you're writing the custom sync rule.
   • Connected System Object Type: Select user.
   • Metaverse Object Type: Select person.
   • Link Type: Select JoinNoFlow.
   • Precedence: Provide a value that's unique in the system.
   • Tag: Leave this field empty.

   

3. On the Scoping filter page, for the Attribute, select cloudNoFlow. For Value, select True. Then select Next.

   

4. On the Join rules page, select Next.

5. On the Transformations page, select Add.

Follow the same steps for all object types (user, group, and contact).

Install the Microsoft Entra provisioning agent

If you're using the Basic Active Directory and Azure environment tutorial, use CP1. To install the agent, follow these steps.

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.

2. On the left pane, select Entra Connect, and then select Cloud Sync.

   

3. On the left pane, select Agents.

4. Select Download on-premises agent, and then select Accept terms & download.

   

5. After you download the Microsoft Entra Connect Provisioning Agent Package, run the AADConnectProvisioningAgentSetup.exe installation file from your downloads folder.

6. On the screen that opens, select the I agree to the license terms and conditions checkbox, and then select Install.

   

7. After the installation finishes, the configuration wizard opens. Select Next to start the configuration.

   

8. Sign in with an account with at least the Hybrid Identity administrator role. If you have Internet Explorer enhanced security enabled, it blocks the sign-in. If so, close the installation, disable Internet Explorer enhanced security, and restart the Microsoft Entra Provisioning Agent Package installation.

   

9. On the Configure Service Account screen, select a group Managed Service Account (gMSA). This account is used to run the agent service. If a managed service account is already configured in your domain by another agent and you're installing a second agent, select Create gMSA. The system detects the existing account and adds the required permissions for the new agent to use the gMSA account. When you're prompted, choose one of two options:

   • Create gMSA: Let the agent create the provAgentgMSA$ managed service account for you. The group managed service account (for example, CONTOSO\provAgentgMSA$) is created in the same Active Directory domain where the host server joined. To use this option, enter the Active Directory domain administrator credentials (recommended).
   • Use custom gMSA: Provide the name of the managed service account that you manually created for this task.

   

10. To continue, select Next.

11. On the Connect Active Directory screen, if your domain name appears under Configured domains, skip to the next step. Otherwise, enter your Active Directory domain name, and select Add directory.

    

12. Sign in with your Active Directory domain administrator account. The domain administrator account shouldn't have an expired password. If the password is expired or changes during the agent installation, reconfigure the agent with the new credentials. This operation adds your on-premises directory. Select OK, and then select Next to continue.

13. Select Next to continue.

14. On the Configuration complete screen, select Confirm. This operation registers and restarts the agent.

    

15. After the operation finishes, you see a notification that your agent configuration was successfully verified. Select Exit. If you still get the initial screen, select Close.

Verify the agent installation

Agent verification occurs in the Azure portal and on the local server that runs the agent.

Verify the agent in the Azure portal

To verify that Microsoft Entra ID registers the agent, follow these steps:

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.

2. Select Entra Connect, and then select Cloud Sync.

   

3. On the Cloud Sync page, click Agents to see the agents that you installed. Verify that the agent appears and that the status is active.

Verify the agent on the local server

To verify that the agent is running, follow these steps:

1. Sign in to the server with an administrator account.

2. Go to Services. You can also use Start/Run/Services.msc to get to it.

3. Under Services, make sure that Microsoft Azure AD Connect Agent Updater and Microsoft Azure AD Connect Provisioning Agent are present and that the status is Running.

   

Verify the provisioning agent version

To verify the version of the agent that's running, follow these steps:

1. Go to C:\Program Files\Microsoft Azure AD Connect Provisioning Agent.
2. Right-click AADConnectProvisioningAgent.exe and select Properties.
3. Select the Details tab. The version number appears next to the product version.

Configure Microsoft Entra Cloud Sync

To configure provisioning, follow these steps:

1. Sign in to the Microsoft Entra admin center as at least a Hybrid Identity Administrator.

2. Browse to Entra ID > Entra Connect > Cloud sync.

   

3. Select New configuration.

   

4. On the configuration screen, select your domain and whether to enable password hash sync. Then select Create.

   

5. On the Get started screen, select Add scoping filters next to the Add scoping filters icon. Or on the left pane under Manage, select Scoping filters.

   

6. Select the scoping filter. For this tutorial, select Selected organizational units. This filter scopes the configuration to apply to specific OUs.

7. In the box, enter OU=CPUsers,DC=contoso,DC=com.

   

8. Select Add > Save.

Start the scheduler

Microsoft Entra Connect Sync synchronizes changes that occur in your on-premises directory by using a scheduler. Now that you modified the rules, you can restart the scheduler.

1. On the server that's running Microsoft Entra Connect Sync, open PowerShell with administrator privileges.
2. Run Set-ADSyncScheduler -SyncCycleEnabled $true.
3. Run Start-ADSyncSyncCycle. Then select Enter.

After the scheduler is enabled, Microsoft Entra Connect Sync stops exporting object adds, object deletes, and non-reference attribute updates for objects where cloudNoFlow=true in the metaverse and the outbound rule uses JoinNoFlow. Reference attributes are handled differently. Updates to reference attributes, such as member and manager, can still be exported for reference resolution.

If an object is removed from Microsoft Entra Connect Sync scope, its connector space and metaverse objects are removed. Any references to or from that object can be dropped in the Microsoft Entra connector space and exported as reference deletes. This behavior can cause group membership removals or other reference changes in Microsoft Entra ID.

Troubleshooting

If the pilot doesn't work as expected, go back to the Microsoft Entra Connect Sync setup.

1. Disable provisioning configuration in the portal.
2. Use the Sync Rule Editor tool to disable all the custom sync rules that you created for cloud provisioning. Disabling causes a full sync on all the connectors.

Removed group memberships or manager references

This issue can happen if objects are removed from Microsoft Entra Connect Sync scope while related groups, users, contacts, or other referenced objects are still in coexistence. When objects are removed from scope, Microsoft Entra Connect Sync removes the corresponding connector space and metaverse objects. This removal can drop references in the Microsoft Entra connector space and export reference deletes to Microsoft Entra ID.

To recover, readd the affected objects to Microsoft Entra Connect Sync scope and run a full synchronization to rebuild the connector space and metaverse references. Before you attempt to remove the scope again, verify that Microsoft Entra Cloud Sync is provisioning all affected objects and that references, such as group memberships and manager relationships, remain intact after a Cloud Sync provisioning cycle.

Related content

• What is provisioning?
• What is Microsoft Entra Cloud Sync?