Organisations running Windows Server Active Directory on-premises routinely need to extend those identities to Microsoft 365, Intune, and Azure — without replacing the directory that line-of-business applications depend on. Microsoft Entra Cloud Sync is the modern answer to this challenge. This guide documents a complete deployment, including the four categories of failure I consistently encounter across client engagements and the precise resolution for each.

Understanding the two sync options

Microsoft offers two products under the Entra Connect umbrella. Choosing the wrong one for your environment adds unnecessary complexity. The decision comes down to topology and management preference.

For a single-forest deployment with standard user and group objects, Cloud Sync is the right choice. The operational simplicity and built-in resilience make it preferable to the full Connect Sync application for the majority of organisations I work with.

Architecture and network requirements

Before deployment begins, the network team needs to understand what the provisioning agent actually does — and more importantly, what it does not require. This is where many firewall change requests get over-engineered.

Pre-deployment checklist

In my experience, skipping this checklist accounts for roughly 80% of failed initial deployments. Each item is a dependency, not a preference. Verify every one before running the installer.

• ✓ Domain functional level is Windows Server 2012 R2 or higher
• ✓ Dedicated sync server is provisioned — never install on the domain controller itself
• ✓ Sync server is domain-joined to the target AD forest
• ✓ DNS on the sync server resolves the AD domain to the domain controller’s private IP — not a public address
• ✓ LDAP port 389 and Kerberos port 88 are reachable from the sync server to the domain controller
• ✓ All user UPN suffixes use the public domain (e.g. @contoso.com) — not .local or an internal suffix
• ✓ The domain is verified in Entra ID under Custom domain names
• ✓ The admin account used for agent setup is a cloud-only account — not synchronised from AD
• ✓ MFA is fully configured on the admin account before beginning setup
• ✓ Microsoft Edge is installed on the sync server
• ✓ Outbound HTTPS to *.msappproxy.net and *.microsoftonline.com is permitted

Preparing the on-premises directory

The most common pre-deployment misconfiguration I find is a mismatch between the UPN suffix used in Active Directory and the domain verified in Azure. Legacy environments frequently use a .local or internal suffix that has no public DNS presence and cannot be verified in Azure. This must be corrected before installation.

# Step 1 — Check what UPN suffixes currently exist in the forest
Get-ADForest | Select-Object UPNSuffixes

# Step 2 — Add your verified public domain as an accepted suffix
Set-ADForest -UPNSuffixes @{Add="contoso.com"}

# Step 3 — Update existing user accounts to use the correct UPN
# Scope to a specific OU in production to avoid updating service accounts
Get-ADUser -Filter * -SearchBase "OU=Corporate Users,DC=contoso,DC=com" |
ForEach-Object {
    Set-ADUser $_ -UserPrincipalName "$($_.SamAccountName)@contoso.com"
}

# Step 4 — Verify the change before proceeding
Get-ADUser -Filter * -SearchBase "OU=Corporate Users,DC=contoso,DC=com" |
Select-Object Name, UserPrincipalName | Format-Table -AutoSize

Installing the provisioning agent

The four errors you will encounter — and their resolutions

These are not edge cases. In over a dozen Entra Cloud Sync deployments I have led or reviewed, these four failure patterns appear consistently. Knowing them in advance turns a frustrating half-day into a 20-minute resolution.

# Point DNS directly at the domain controller's private IP
Set-DnsClientServerAddress -InterfaceAlias "Ethernet" -ServerAddresses "10.0.0.10"

# Flush the resolver cache
ipconfig /flushdns

# Verify — result must be a private RFC 1918 address, not a public IP
Resolve-DnsName contoso.com

# Confirm a domain controller is now locatable
nltest /dsgetdc:contoso.com

# Test the LDAP port directly
Test-NetConnection -ComputerName "10.0.0.10" -Port 389

# Retrieve the sync server's computer account from AD
$SyncServer = Get-ADComputer -Identity "SYNC-SERVER-01"

# Grant it permission to retrieve the gMSA password
Set-ADServiceAccount -Identity "provAgentgMSA$" `
    -PrincipalsAllowedToRetrieveManagedPassword $SyncServer

# Verify the assignment was applied
Get-ADServiceAccount -Identity "provAgentgMSA$" `
    -Properties PrincipalsAllowedToRetrieveManagedPassword |
    Select-Object -ExpandProperty PrincipalsAllowedToRetrieveManagedPassword

# Purge cached Kerberos tickets so the new permission takes effect
klist purge

# Restart the provisioning agent service
Restart-Service "AADConnectProvisioningAgent" -Force

# Confirm the gMSA test now passes
Import-Module ActiveDirectory
Test-ADServiceAccount -Identity "provAgentgMSA$"
# Expected: True

# Refresh the Entra portal — the domain should now appear in the dropdown

Creating the sync configuration

Installation of the agent does not start synchronisation. A configuration object must be explicitly created in the Entra admin center to define scope, attribute mappings, and which features — such as password hash sync — are active.

1. Navigate to Entra ID → Microsoft Entra Connect → Cloud Sync → New configuration
2. Select the AD domain from the dropdown — now populated after resolving the gMSA permission
3. Confirm Enable password hash sync is checked unless your security policy prohibits cloud-stored password hashes
4. Click Create to generate the configuration object
5. On the configuration overview page, set Provisioning Status to On and click Save

Validating the deployment

Do not treat the Active status indicator in the portal as confirmation that synchronisation is working correctly. Validate the full chain: agent health, sync cycle execution, and user object integrity in Entra ID.

# Confirm the agent service is running
Get-Service -Name "AADConnectProvisioningAgent" | Select-Object Status, DisplayName

# Create a test user in AD to verify end-to-end sync
New-ADUser `
    -Name "Sync Test User" `
    -SamAccountName "synctestuser" `
    -UserPrincipalName "synctestuser@contoso.com" `
    -AccountPassword (ConvertTo-SecureString "TempPass@2026!" -AsPlainText -Force) `
    -Enabled $true `
    -Path "OU=Corporate Users,DC=contoso,DC=com"

# Wait approximately 5 minutes, then verify in Entra ID

Connect-MgGraph -Scopes "User.Read.All", "Directory.Read.All"

# List all users with on-premises sync enabled
Get-MgUser -Filter "onPremisesSyncEnabled eq true" |
    Select-Object DisplayName, UserPrincipalName, AccountEnabled |
    Format-Table -AutoSize

# Verify a specific user synced correctly
Get-MgUser -UserId "synctestuser@contoso.com" |
    Select-Object DisplayName, OnPremisesDistinguishedName, OnPremisesSyncEnabled, AccountEnabled

Confirm the following in the Entra portal under Users → All Users:

• Synced users show source as Windows Server AD
• On-premises sync enabled is set to Yes
• A synced user can authenticate successfully at https://myapps.microsoft.com using their on-premises password

What to build on top of this foundation

A working identity sync is the prerequisite, not the destination. With users flowing from AD into Entra ID, the following workstreams become available and should be scoped into a phase-two engagement.

• Conditional Access policies — enforce MFA, compliant device requirements, and location-based controls across Microsoft 365 and third-party SaaS applications
• Hybrid Entra ID Join — register existing domain-joined Windows 10/11 devices with Entra ID for SSO to cloud resources without re-enrolment
• Microsoft Intune co-management — bring existing SCCM-managed devices under Intune policy management progressively, workload by workload
• Self-Service Password Reset with writeback — allow users to reset passwords from the cloud, with changes synchronised back to on-premises AD immediately
• Entra ID Protection — apply risk-based sign-in and user risk policies against the synchronised identity pool, with automatic remediation workflows
• Privileged Identity Management (PIM) — time-bound, approval-gated elevation for administrative roles, replacing standing privilege assignments