Migration from Connect Sync

This quickstart covers migrating from Connect Sync to Cloud Sync. It includes the recommended OU-based pilot approach (manual), the programmatic approach via MS Graph API, and post-migration validation.

Pre-Migration Assessment

Before starting migration, confirm that Cloud Sync covers your scenario:

1. Review parity gaps. Check the Connect Sync vs Cloud Sync comparison. If you depend on device writeback, advanced sync rules, cross-forest references, or other Connect Sync-only features, you cannot fully migrate yet.
2. Check object counts. Cloud Sync supports up to 150,000 objects per domain and groups up to 50,000 members. Run Get-ADUser -Filter * | Measure-Object and Get-ADGroup -Filter * | Measure-Object to check.
3. Verify prerequisites. Ensure your environment meets the Cloud Sync prerequisites.
4. Back up Connect Sync configuration. Export your Connect Sync configuration before making any changes. Use the import/export feature in the Connect Sync wizard.

If parity gaps affect your environment, you can still do a partial migration using coexistence (see below). Migrate the OUs that only need basic sync, and leave the rest on Connect Sync until Cloud Sync closes the gaps.

OU-Based Pilot Migration

This is the recommended Microsoft approach. You migrate users OU by OU, so both engines coexist safely during the transition.

flowchart TD
    A[Back up Connect Sync config] --> B[Create or identify pilot OU]
    B --> C[Create Connect Sync exclusion rules]
    C --> D[Install Cloud Sync provisioning agent]
    D --> E[Configure Cloud Sync scoped to pilot OU]
    E --> F[Verify pilot users sync correctly]
    F --> G{All users migrated?}
    G -->|No| H[Move next OU batch to Cloud Sync]
    H --> C
    G -->|Yes| I[Disable Connect Sync scheduler]
    I --> J[Decommission Connect Sync server]

Step 1: Create or Identify a Pilot OU

Choose an OU with test users, or create a new one and move a handful of users into it.

# Count users in the pilot OU
Get-ADUser -Filter * -SearchBase "OU=CloudSyncPilot,DC=contoso,DC=com" | Measure-Object

Step 2: Exclude the Pilot OU from Connect Sync

You need two custom sync rules in Connect Sync to prevent it from syncing the pilot OU objects.

Stop the scheduler first:

Set-ADSyncScheduler -SyncCycleEnabled $false

Create the inbound exclusion rule:

1. Open the Synchronization Rules Editor.
2. Create a new Inbound rule with a precedence below 100 (e.g., 50).
3. Set the connector to your AD connector.
4. Scoping filter: dn CONTAINS OU=CloudSyncPilot (adjust to match your OU).
5. Link type: Join.
6. Add a transformation: Constant, target attribute = cloudNoFlow, value = True.

Create the outbound exclusion rule:

1. Create a new Outbound rule.
2. Scoping filter: cloudNoFlow EQUAL True.
3. Link type: JoinNoFlow (this prevents provisioning to Entra ID).

Re-enable the scheduler:

Set-ADSyncScheduler -SyncCycleEnabled $true

Wait for a sync cycle to complete. The pilot OU users should no longer be exported by Connect Sync.

Step 3: Install the Provisioning Agent

If you have not already installed the Cloud Sync agent, follow the configuration quickstart steps 1-2. If you already have an agent installed, skip to step 4.

Step 4: Configure Cloud Sync for the Pilot OU

1. In the Entra admin center, go to Cloud sync > New configuration.
2. Select AD to Microsoft Entra ID sync.
3. Under scoping filters, select Selected organizational units.
4. Enter the DN of your pilot OU: OU=CloudSyncPilot,DC=contoso,DC=com.
5. Configure attribute mappings (the defaults are usually fine for a pilot).
6. Test with on-demand provisioning on a specific user.
7. Enable the configuration.

Step 5: Verify Pilot Users

After enabling, check that pilot users sync correctly:

1. Provisioning logs. Verify successful sync events for pilot users.
2. Entra ID user properties. Confirm attributes match on-premises values.
3. Password hash sync. If enabled, verify users can sign in with cloud authentication.

You can use this PowerShell script to count users synced from the pilot OU:

Connect-MgGraph -Scopes "User.Read.All"
$users = Get-MgUser -All -Filter "onPremisesSyncEnabled eq true"
$pilotOU = "OU=CloudSyncPilot"
$count = ($users | Where-Object {
    $_.OnPremisesDistinguishedName -match $pilotOU
}).Count
Write-Host "Pilot users synced: $count"

Step 6: Expand and Decommission

Once the pilot succeeds:

1. Gradually expand. Move more OUs from Connect Sync to Cloud Sync by repeating steps 2-5 for each OU.
2. Disable Connect Sync. When all users are managed by Cloud Sync, stop the Connect Sync scheduler and leave the server in a disabled state for a verification period.
3. Decommission. After verifying everything works, uninstall Connect Sync.

Rollback

The OU-based approach is inherently safe for rollback:

1. Disable the Cloud Sync configuration.
2. Remove the exclusion sync rules from Connect Sync.
3. Run a full sync cycle on Connect Sync.

Users will be picked back up by Connect Sync on the next cycle.

Programmatic Migration via MS Graph API

For automated or large-scale migrations, you can configure Cloud Sync entirely through the MS Graph Synchronization API.

Create the Service Principal

The AD2AAD application template ID is 1a4721b3-e57f-4451-ae87-ef078703ec94. Instantiate it to create the service principal:

POST https://graph.microsoft.com/beta/applicationTemplates/1a4721b3-e57f-4451-ae87-ef078703ec94/instantiate
Content-Type: application/json

{
    "displayName": "contoso.com - Cloud Sync"
}

Note the objectId of the service principal in the response.

Create Sync Jobs

Create two jobs: one for user/group provisioning and one for password hash sync.

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs
Content-Type: application/json

{
    "templateId": "AD2AADProvisioning"
}

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs
Content-Type: application/json

{
    "templateId": "AD2AADPasswordHash"
}

Configure Domain Targeting

Set the target domain for the service principal:

PUT https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/secrets

{
    "value": [
        {
            "key": "Domain",
            "value": "{\"domain\":\"contoso.com\"}"
        }
    ]
}

Configure Attribute Mappings (Optional)

To customize attribute mappings, retrieve the current schema, modify it, and push it back:

GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema

Modify the attributeMappings array in the response, then:

PUT https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema

Start the Sync Job

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/start

Monitor Status

GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/

Check the status section in the response for sync progress, errors, and quarantine state.

Exchange Hybrid Writeback

If your environment uses Exchange hybrid, you can enable Exchange hybrid writeback as an additional sync job:

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs
Content-Type: application/json

{
    "templateId": "AAD2ADExchangeHybridWriteback"
}

Before creating this job, verify the Exchange schema is present in your AD by using schema discovery:

POST https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema/directories/{directoryId}/discover

Check that the mailNickName attribute is present in the response.

Post-Migration Validation

After migration, verify these areas:

Important: Keep the Connect Sync server in a disabled (not decommissioned) state for at least a week after full migration. This gives you a quick rollback path if issues surface.

Further Reading

For a higher-level overview of migration planning, pre-migration checklists, and rollback considerations, see the migration notes.