Edit

Migrate to Microsoft Entra Cloud Sync for an existing synced AD forest

  • Article

This tutorial walks you through how you would migrate to cloud sync for a test Active Directory forest that is already synced using Microsoft Entra Connect Sync.

Note

This article provides information for a basic migration and you should review the Migrating to cloud sync documentation before attempting to migrate your production environment.

Diagram that shows the Microsoft Entra Cloud Sync flow.

Considerations

Before you try this tutorial, consider the following items:

  1. Ensure that you're familiar with basics of cloud sync.

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

  3. When piloting, you'll be removing a test OU or group from Microsoft Entra Connect Sync scope. Moving objects out of scope leads to deletion of those objects in Microsoft Entra ID.

    • User objects, the objects in Microsoft Entra ID are soft-deleted and can be restored.
    • Group objects, the objects in Microsoft Entra ID are hard-deleted and can't be restored.

    A new link type has been introduced in Microsoft Entra Connect Sync, which will prevent the deletion in a piloting scenario.

  4. Ensure that the objects in the pilot scope have ms-ds-consistencyGUID populated so cloud sync hard matches the objects.

Note

Microsoft Entra Connect Sync does not populate ms-ds-consistencyGUID by default for group objects.

  1. This configuration is for advanced scenarios. Ensure that you follow the steps documented in this tutorial precisely.

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 the pilot. We recommend starting with a small set of objects.
  • A server running Windows Server 2016 or later that will host the provisioning agent.
  • Source anchor for Microsoft Entra Connect Sync should be either objectGuid or ms-ds-consistencyGUID

Update Microsoft Entra Connect

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

Back up your Microsoft Entra Connect configuration

Before making any changes, you should back up your Microsoft Entra Connect configuration. This way, you can roll back to your previous configuration. See Import and export Microsoft Entra Connect configuration settings for more information.

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 making the changes. To stop the scheduler, use the following steps:

  1. On the server that is running Microsoft Entra Connect Sync open PowerShell with Administrative Privileges.
  2. Run Stop-ADSyncSyncCycle. Hit Enter.
  3. Run Set-ADSyncScheduler -SyncCycleEnabled $false.

Note

If you are running your own custom scheduler for Microsoft Entra Connect Sync, then please disable the scheduler.

Create custom user inbound rule

In the Microsoft Entra Connect Synchronization Rules editor, you need to create an inbound sync rule that filters out users in the OU you identified previously. The inbound sync rule is a join rule with a target attribute of cloudNoFlow. This rule tells Microsoft Entra Connect not to synchronize attributes for these users. For more information, see Migrating to cloud sync documentation before attempting to migrate your production environment.

  1. Launch the synchronization editor from the application menu in desktop as shown below:

    Screenshot of the synchronization rule editor menu.

  2. Select Inbound from the drop-down list for Direction and select Add new rule.

    Screenshot that shows the "View and manage your synchronization rules" window with "Inbound" and the "Add new rule" button selected.

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

    • Name: Give the rule a meaningful name
    • Description: Add a meaningful description
    • Connected System: Choose the AD connector that you're writing the custom sync rule for
    • Connected System Object Type: User
    • Metaverse Object Type: Person
    • Link Type: Join
    • Precedence: Provide a value that is unique in the system
    • Tag: Leave this empty

    Screenshot that shows the "Create inbound synchronization rule - Description" page with values entered.

  4. On the Scoping filter page, enter the OU or security group that you want the pilot based off. To filter on OU, add the OU portion of the distinguished name. This rule will be applied to all users who are in that OU. So, if DN ends with "OU=CPUsers,DC=contoso,DC=com, you would 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.

    Screenshot that shows the Create inbound synchronization rule - Scoping filter page with a scoping filter value entered.

  5. On the Join rules page, select Next.

  6. On the Transformations page, add a Constant transformation: flow True to cloudNoFlow attribute. Select Add.

    Screenshot that shows the Create inbound synchronization rule - Transformations page with a Constant transformation flow added.

Same steps need to be followed for all object types (user, group and contact). Repeat steps per configured AD Connector / per AD forest.

Create custom user outbound rule

You'll also 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 not to synchronize attributes for these users. For more information, see Migrating to cloud sync documentation before attempting to migrate your production environment.

  1. Select Outbound from the drop-down list for Direction and select Add rule.

    Screenshot that shows the Outbound Direction selected and the Add new rule button highlighted.

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

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

    Screenshot that shows the Description page with properties entered.

  3. On the Scoping filter page, choose cloudNoFlow equal True. Then select Next.

    Screenshot that shows a custom rule.

  4. On the Join rules page, select Next.

  5. On the Transformations page, select Add.

Same steps need to be followed for all object types (user, group and contact).

Install the Microsoft Entra provisioning agent

If you're using the Basic AD and Azure environment tutorial, it would be CP1. To install the agent, follow these steps:

  1. In the Azure portal, select Microsoft Entra ID.
  2. On the left, select Microsoft Entra Connect.
  3. On the left, select Cloud sync.

Screenshot of new UX screen.

  1. On the left, select Agent.
  2. Select Download on-premises agent, and select Accept terms & download.

Screenshot of download agent.

  1. Once the Microsoft Entra Connect Provisioning Agent Package has completed downloading, run the AADConnectProvisioningAgentSetup.exe installation file from your downloads folder.

Note

When installing for the US Government Cloud use:
AADConnectProvisioningAgentSetup.exe ENVIRONMENTNAME=AzureUSGovernment
See "Install an agent in the US government cloud" for more information.

  1. On the splash screen, select I agree to the license and conditions, and then select Install.

Screenshot that shows the Microsoft Entra Connect Provisioning Agent Package splash screen.

  1. Once the installation operation completes, the configuration wizard will launch. Select Next to start the configuration. Screenshot of the welcome screen.
  2. On the Select Extension screen, select HR-driven provisioning (Workday and SuccessFactors) / Microsoft Entra Connect cloud sync and click Next. Screenshot of the select extensions screen.

Note

If you are installing the provisioning agent for use with on-premsise app provisioning then select On-premises application provisioning (Microsoft Entra ID to application).

  1. Sign in with your Microsoft Entra Global Administrator or Hybrid Identity Administrator account. If you have Internet Explorer enhanced security enabled, it will block the sign-in. If so, close the installation, disable Internet Explorer enhanced security, and restart the Microsoft Entra Connect Provisioning Agent Package installation.

Screenshot of the Connect Microsoft Entra ID screen.

  1. 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 are installing a second agent, select Create gMSA because the system will detect the existing account and add the required permissions for the new agent to use the gMSA account. When prompted, choose either:
  • Create gMSA which lets the agent create the provAgentgMSA$ managed service account for you. The group managed service account (for example, CONTOSO\provAgentgMSA$) will be created in the same Active Directory domain where the host server has joined. To use this option, enter the Active Directory domain administrator credentials (recommended).
  • Use custom gMSA and provide the name of the managed service account that you have manually created for this task.

To continue, select Next.

Screenshot of the Configure Service Account screen.

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

  2. Sign in with your Active Directory domain administrator account. The domain administrator account shouldn't have an expired password. In case the password is expired or changes during the agent installation, you'll need to reconfigure the agent with the new credentials. This operation will add your on-premises directory. Select OK, then select Next to continue.

Screenshot that shows how to enter the domain admin credentials.

  1. The following screenshot shows an example of contoso.com configured domain. Select Next to continue.

Screenshot of the Connect Active Directory screen.

  1. On the Configuration complete screen, select Confirm. This operation will register and restart the agent.

  2. Once this operation completes, you should be notified that Your agent configuration was successfully verified. You can select Exit.

Screenshot that shows the finish screen.

  1. If you still get the initial splash screen, select Close.

Verify agent installation

Agent verification occurs in the Azure portal and on the local server that's running the agent.

Azure portal agent verification

To verify that the agent is being registered by Microsoft Entra ID, follow these steps:

  1. Sign in to the Azure portal.
  2. Select Microsoft Entra ID.
  3. Select Microsoft Entra Connect, and then select Cloud sync. Screenshot of new UX screen.
  4. On the cloud sync page, you'll see the agents you've installed. Verify that the agent is displayed and the status is healthy.

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. Open Services either by navigating to it or by going to Start/Run/Services.msc.
  3. Under Services, make sure that Microsoft Entra Connect Agent Updater and Microsoft Entra Connect Provisioning Agent are present and the status is Running. Screenshot that shows the Windows services.

Verify the provisioning agent version

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

  1. Navigate to 'C:\Program Files\Microsoft Azure AD Connect Provisioning Agent'
  2. Right-click on 'AADConnectProvisioningAgent.exe' and select properties.
  3. Click the details tab and the version number will be displayed next to Product version.

Configure Microsoft Entra Cloud Sync

Use the following steps to configure provisioning:

  1. Sign in to the Microsoft Entra admin center as at least a Hybrid Administrator.
  2. Browse to Identity > Hybrid management > Microsoft Entra Connect > Cloud sync. Screenshot of cloud sync home page.
  1. Select New configuration. Screenshot of adding a configuration.
  2. On the configuration screen, select your domain and whether to enable password hash sync. Click Create.

Screenshot of a new configuration.

  1. The Get started screen will open.

  2. On the Get started screen, click either Add scoping filters next to the Add scoping filters icon or on the click Scoping filters on the left under Manage.

Screenshot of scoping filters.

  1. Select the scoping filter. For this tutorial select:
    • Selected organizational units: Scopes the configuration to apply to specific OUs.
  2. In the box, enter "OU=CPUsers,DC=contoso,DC=com".

Screenshot of the scoping filter.

  1. Click Add. Click Save.

Start the scheduler

Microsoft Entra Connect Sync synchronizes changes occurring in your on-premises directory using a scheduler. Now that you've modified the rules, you can restart the scheduler. Use the following steps:

  1. On the server that is running Microsoft Entra Connect Sync open PowerShell with Administrative Privileges
  2. Run Set-ADSyncScheduler -SyncCycleEnabled $true.
  3. Run Start-ADSyncSyncCycle, then press Enter.

Note

If you are running your own custom scheduler for Microsoft Entra Connect Sync, then please enable the scheduler.

Once the scheduler is enabled, Microsoft Entra Connect will stop exporting any changes on objects with cloudNoFlow=true in the metaverse, unless any reference attribute (such as manager) is being updated. In case there's any reference attribute update on the object, Microsoft Entra Connect will ignore the cloudNoFlow signal and export all updates on the object.

Something went wrong

In case the pilot doesn't work as expected, you can go back to the Microsoft Entra Connect Sync setup by following the steps below:

  1. Disable provisioning configuration in the portal.
  2. Disable all the custom sync rules created for Cloud Provisioning using the Sync Rule Editor tool. Disabling should cause full sync on all the connectors.

Next steps