Directory Synchronisation / Hybrid Setup Problems — Troubleshooting Microsoft Entra Connect & On-Prem Identity Sync

Directory Synchronisation / Hybrid Setup Problems — A Practical Troubleshooting Playbook

Diagnose and fix Microsoft Entra Connect (Azure AD Connect) and hybrid identity sync failures — connectivity, duplicate UPNs, OU filters, provisioning, and cross-tenant sync. Includes PowerShell and Microsoft Graph scripts you can run today.

Author: CloudKnowledge • Updated: Oct 24, 2025 • Read time: ~22 minutes

Why hybrid identity sync still breaks in 2025

Hybrid identity remains the backbone of enterprise authentication. When your on‑premises directory and Microsoft Entra ID (formerly Azure AD) get out of sync, users can't sign in, SSO fails, automation breaks, and help desks get swamped. Common causes in real-world environments include network/proxy misconfiguration, misapplied OU filters, duplicate userPrincipalName (UPN) collisions, schema mismatches, unexpected attribute flows, and cross‑tenant provisioning complexities.

High-level symptoms to watch for

Sync status shows errors in Azure AD Connect or Microsoft Entra admin center → Identity → Connect.
Users missing in Entra ID or present with Sync Error status.
Authentication failures and password writeback failing.
Duplicate UPN errors: "Multiple objects have the same userPrincipalName".
Provisioning failures for applications that depend on TE and group membership changes not propagating.

Core failure categories and root causes

1. Connectivity issues — Entra Connect can't reach Microsoft Entra ID

Connectivity is foundational. If the sync server can't talk to Microsoft Entra ID endpoints or Graph APIs, the sync cycle fails. Typical problems:

Outbound proxy blocking required endpoints (e.g., login.microsoftonline.com, graph.microsoft.com, service‑specific endpoints).
Machine.config or .NET settings preventing TLS 1.2/1.3.
Time drift or incorrect system clocks causing token validation errors.
Intermittent DNS resolution issues.

Troubleshooting checklist — connectivity

From the sync server, test DNS and HTTP reachability using nslookup and curl/Invoke-WebRequest.
Validate proxy configuration for the service account and machine account — Entra Connect may use the computer account for certain operations.
Confirm TLS and .NET settings: ensure .NET framework supports TLS 1.2; set [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 in troubleshooting sessions.
Check system clock and NTP.

# Test reachability from the sync server
nslookup login.microsoftonline.com
Invoke-WebRequest -Uri https://login.microsoftonline.com -UseBasicParsing -TimeoutSec 15

# Force TLS 1.2 in the current PowerShell session
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

2. Duplicate UPNs and identity collisions

Duplicate UPN problems happen when two objects sync with the same userPrincipalName or when a cloud-only account already exists with the same UPN as an on-premises user. The results include partial provisioning, writeback failures, and authentication issues.

How duplicates appear

Migration projects where users are staged in the cloud first and then on‑prem accounts are synchronized later.
Manually created cloud users (portal-created) whose UPNs collide with on‑prem UPNs.
Sync rules that change UPN suffixes or map attributes incorrectly.

PowerShell checks for duplicates

Use PowerShell with the Microsoft Graph or MSOnline modules to find collisions. Below examples use the Microsoft Graph PowerShell module (recommended).

# Install if not present
Install-Module Microsoft.Graph -Scope CurrentUser -Force

# Sign in (interactive or with service principal)
Connect-MgGraph -Scopes "User.Read.All","Directory.Read.All"

# Example: find cloud users whose userPrincipalName matches an on-prem list
$onPremUPNs = Get-Content -Path .\onprem-upns.txt
$matches = @()
foreach($upn in $onPremUPNs){
  $u = Get-MgUser -Filter "userPrincipalName eq '$upn'" -ConsistencyLevel eventual -All
  if($u){ $matches += $u }
}
$matches | Select Id, UserPrincipalName, DisplayName | Format-Table -AutoSize

3. OU filters and domain/OU scoping mistakes

Incorrect OU filtering is a very common cause of "missing users". Entra Connect can be configured to include or exclude specific OUs. If your AD restructure or GPO changes move users into a non-synced OU, they stop syncing.

How to verify OU filter configuration

Open the Azure AD Connect tool on the sync server and inspect the OU filtering settings.
Use PowerShell to enumerate which OUs are currently included in the configuration.

# Example: check Azure AD Connect current configuration (module: ADSync)
Import-Module ADSync
Get-ADSyncConnector | Format-Table Name, Type, ConnectorType

# Get connector config (this returns XML/JSON on some versions)
(Get-ADSyncConnector -Name "Contoso On-Prem Connector").ConnectorRunStatus

4. Provisioning and cross-tenant sync issues

Cross-tenant provisioning or B2B/B2B direct connect scenarios introduce complexity: attribute transformation, provisioning status, and inbound provisioning endpoints can fail due to permissions or tenant-level settings.

Common failure modes

Missing application permissions for the service principal used by provisioning.
Attributes blocked by policy or conditional access preventing service principal tokens.
Graph API rate limits or throttling interfering with bulk operations.

5. Password writeback and authentication errors

Password writeback, PTA (Pass-through Authentication), and AD FS can be affected by network middleboxes, account permissions, or malformed domain controller responses. Ensure the writeback account has the required privilege (reset password).

Logs, reports & built-in health checks

Leverage these in order of increasing fidelity:

Azure AD Connect Health / Identity Secure Score — checks sync agent health, CPU, connectivity.
Entra admin center: Identity → Audit logs and Provisioning reports.
Local event logs on the sync server under Applications and Services Logs → AD FS / Directory Synchronization.
Synchronization Service Manager (miisclient.exe) logs and exportable CSV error details.

# Synchronization Service Manager: export errors
# On sync server, open: C:\Program Files\Microsoft Azure AD Sync\UIShell\miisclient.exe
# Use the Operations tab -> Export the current run details

Actionable troubleshooting recipes

Recipe A — Sync server can't authenticate to Entra ID (proxy/TLS)

Check proxy settings in Internet Explorer / WinHTTP for the machine: netsh winhttp show proxy.
Ensure machine account and service account use proper proxy bypass rules when required.
Temporarily bypass proxy to test direct connectivity to https://login.microsoftonline.com.
Confirm TLS 1.2: update registry or .NET config if older frameworks are involved.

Recipe B — Resolving duplicate UPN collisions

Identify cloud-only accounts with the same UPN as on‑prem. Use the earlier Graph PowerShell snippet.
Decide whether to convert the cloud-only account to a synchronized object (hard-match using ImmutableID) or rename the cloud account and merge attributes.
If converting: set immutableId on the cloud user to match the on‑prem object and then let the sync merge the accounts. This requires careful planning and often a staged migration window.

# Example: set immutableId on cloud user (Base64 of on-prem objectGUID)
# Convert objectGUID to base64
$guid = (Get-ADUser -Identity "onpremuser" -Properties objectGUID).objectGUID
$immutable = [System.Convert]::ToBase64String($guid.ToByteArray())
# Set immutableId via Microsoft Graph
Update-MgUser -UserId user@contoso.com -OnPremisesImmutableId $immutable

Recipe C — OU-filtered users suddenly missing

List included OUs in Azure AD Connect and compare to current AD structure.
Check if users were moved by GPO, scripts, or automation into an excluded OU.
Re-add the OU to the sync configuration or move objects back to a synced OU and run a delta sync.

PowerShell and Graph API toolbox

Below are practical scripts and Graph API sequences for diagnosing key problems. Run from an elevated PowerShell session. Replace placeholder values with your tenant and object identifiers.

1. Quick health checks (PowerShell)

# Connect to Microsoft Graph
Import-Module Microsoft.Graph
Connect-MgGraph -Scopes "Directory.Read.All","User.Read.All","Group.Read.All"

# Get tenant details
Get-MgOrganization | Select Id, DisplayName, VerifiedDomains

# Check sync errors summary
Get-MgDirectorySynchronization -All | Select-Object *@{Name='SyncTime';Expression={Get-Date}},ErrorMessage,Status | Format-Table -AutoSize

2. Export sync errors from Synchronization Service Manager (miisclient) via PowerShell

There is no supported public API to query the MIIS database directly; however you can export error CSV via UI or parse local logs under C:\ProgramData\AADConnect. Example to find recent error files:

Get-ChildItem -Path 'C:\ProgramData\AADConnect' -Recurse -Include *.log,*.txt | Where-Object { $_.LastWriteTime -gt (Get-Date).AddDays(-7) } | Sort-Object LastWriteTime -Descending | Select-Object FullName,LastWriteTime

3. Find objects with duplicate UPNs or soft-deleted cloud users

# Find duplicate UPNs in cloud
$all = Get-MgUser -All
$dups = $all | Group-Object -Property userPrincipalName | Where-Object { $_.Count -gt 1 }
$dups | ForEach-Object { $_.Group | Select Id, UserPrincipalName, DisplayName }

# Find soft-deleted users in Entra (for restoring collisions)
Get-MgUser -Filter "accountEnabled eq false" -All | Where-Object { $_.UserPrincipalName -like '*@contoso.com' } | Select Id,UserPrincipalName,DeletionTimestamp

4. Using Microsoft Graph REST API (curl examples)

When automating checks from an external system, use client credentials and the https://graph.microsoft.com/v1.0 endpoints. Ensure your app has Directory.Read.All and User.Read.All application permissions and admin consent.

# Obtain token (example using OAuth2 client credentials)
# POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
# body: client_id, client_secret, scope=https://graph.microsoft.com/.default, grant_type=client_credentials

# Example: list users
curl -X GET -H "Authorization: Bearer {access_token}" "https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName&$top=50"

Remediation playbook — step-by-step

Follow this pragmatic playbook when you have a broken sync pipeline:

Isolate & snapshot: export current sync config and MIIS run history. Snapshot AD objects involved (CSV export).
Check connectivity: validate proxy, TLS, DNS, and NTP.
Collect logs: Synchronization Service run details, Entra provisioning logs, local event logs.
Identify collisions: run the duplicate UPN and immutableId checks.
Apply targeted fixes: example — correct OU inclusion, set immutableId, rename cloud-only users, update sync rules.
Force a delta or full sync: use Start-ADSyncSyncCycle -PolicyType Delta or -PolicyType Initial for full import (use with caution).

# Trigger Delta or Full sync
Import-Module ADSync
# Delta
Start-ADSyncSyncCycle -PolicyType Delta
# Full (use only when necessary)
Start-ADSyncSyncCycle -PolicyType Initial

Preventive hardening & best practices

Use a dedicated sync server with well-defined maintenance windows; avoid running other heavy workloads there.
Document OU filters and use descriptive naming for sync connectors.
Use service principals with the minimum required permissions and rotate client secrets/certificates with automation.
Keep Azure AD Connect and underlying Windows/.NET up to date; enforce TLS 1.2+.
Implement monitoring and alerting on sync failures and threshold-based alerts for delta sync duration.

Security considerations

Always perform the least-privilege model for service accounts and application permissions. For production tenants, prefer certificate-based credentials for confidential clients over long-lived secrets. Rollback plans are critical when changing immutableId or performing object merges.

Troubleshooting examples (real world scenarios)

Case study 1 — Proxy silently blocking token endpoint

Symptoms: Sync server intermittently failing with token errors, machine event logs show unauthorized_client errors. Root cause: corporate transparent proxy injecting headers, breaking token flow. Fix: add proxy bypass for sync server to Microsoft endpoints and configure WinHTTP proxy correctly.

Case study 2 — Migration left cloud stubs causing duplication

Symptoms: After cutover, 5% of users had duplicate accounts. Analysis: Cloud accounts were created manually during pilot and never hard-matched with on-prem users. Fix: convert cloud accounts by setting onPremisesImmutableId to base64(objectGUID) and allow sync to link the accounts.

Quick reference: useful commands

Start-ADSyncSyncCycle -PolicyType Delta — run delta sync
Start-ADSyncSyncCycle -PolicyType Initial — full sync
Get-MgUser -Filter "userPrincipalName eq 'user@domain'" — find user with Graph
Update-MgUser -UserId id -OnPremisesImmutableId $immutable — set immutableId

SEO & publishing notes for WordPress (Edge News / Google Discover / Bing)

This HTML is structured for publishing to WordPress. A few notes to improve visibility:

Use inline schema where appropriate for article & author (WordPress SEO plugins often handle this).
Feature image: choose a high-resolution royalty-free hero (Cloud + Lock) and set alt text with keywords.
Social preview: craft a 120-character summary (see top of the article for a shareable line).
Hyperlinking: we've hyperlinked important keywords back to cloudknowledge.in to satisfy your internal link preference. Replace or add more anchors as needed within WordPress editor.

Appendix — Scripts & snippets

Sample: Export on-prem UPNs to check collisions

# Export users from AD in scope
Import-Module ActiveDirectory
Get-ADUser -Filter * -SearchBase "OU=Employees,DC=contoso,DC=com" -Properties userPrincipalName |
  Select-Object SamAccountName,UserPrincipalName,DistinguishedName | Export-Csv -Path C:\temp\onprem-upns.csv -NoTypeInformation

Sample: Convert objectGUID to base64 for immutableId

$adUser = Get-ADUser -Identity 'jsmith' -Properties objectGUID
$guid = $adUser.objectGUID
$immutable = [System.Convert]::ToBase64String($guid.ToByteArray())
Write-Host "ImmutableId (Base64): $immutable"

Sample: Minimal Graph script to list recent provisioning errors

# Requires app with Directory.Read.All application permissions
$token = Get-Content .\token.txt
Invoke-RestMethod -Method Get -Uri "https://graph.microsoft.com/v1.0/auditLogs/directoryAudits?$top=50" -Headers @{ Authorization = "Bearer $token" }

Checklist when escalating to Microsoft Support

Before opening a support ticket, gather:

Sync server name, AD Connect version, Windows build, .NET version.
Export of the last MIIS synchronization run and the Operations tab CSV.
Relevant event log extracts (Application, System, Directory Synchronization logs).
Exact error messages and timestamps (UTC) and the correlation IDs if available.

Closing: When to consider re-architecting hybrid identity

For organizations with frequent identity collisions, complex multi-domain AD forests, or heavy cross-tenant needs, consider moving to a managed identity strategy: consolidate UPN suffixes, standardize provisioning using SCIM/Graph APIs, and consider Entra External ID or B2C for customer identities. These changes reduce operational toil and lower incident rates.