Cloud Knowledge

Your Go-To Hub for Cloud Solutions & Insights

Advertisement
On Premise Active Directory

Azure AD Connect deep dive — setup, sync types (PHS/PTA/AD FS), troubleshooting PowerShell & Graph API examples.

Shivam Tiwari 1
Azure AD Connect deep dive — setup, sync types (PHS/PTA/AD FS), troubleshooting PowerShell & Graph API examples.

Azure AD Connect (Hybrid): Syncing on-prem Active Directory with Microsoft Entra ID

A comprehensive guide to installing, configuring, troubleshooting, and optimizing Azure AD Connect for hybrid identity (Password Hash Sync, Pass-Through Authentication, AD FS) — with PowerShell scripts, Microsoft Graph queries, FAQs and troubleshooting checklists.

What is Azure AD Connect?

Azure AD Connect (also called Microsoft Entra Connect or Entra Connect in recent docs) is Microsoft's on-prem tool that synchronizes your Active Directory Domain Services (AD DS) objects with Microsoft Entra ID (Azure AD) to enable a hybrid identity environment. It allows users to sign into cloud and on-prem apps with the same credentials and supports multiple authentication models to fit security and architecture needs.

Core Microsoft docs: Microsoft maintains the official overview and guidance for Entra Connect and Entra Cloud Sync.

Why hybrid identity?

  • Single identity across cloud and on-prem for seamless access control and user experience.
  • Supports lift-and-shift and phased cloud migrations while maintaining on-prem security controls.
  • Enables Conditional Access, Hybrid Azure AD Join, and device-based policies.

Key terms (linked)

Azure AD Connect — cloudknowledge.in | Hybrid identity — cloudknowledge.in | Password Hash Sync — cloudknowledge.in | Pass-Through Authentication — cloudknowledge.in.

Architecture & Core Components

Azure AD Connect includes several components and features that together provide directory synchronization and health monitoring:

Primary components

  • Synchronization Service — The engine that moves objects and attributes from AD DS to Microsoft Entra ID and applies sync rules.
  • AD FS (optional) — For federation-based authentication and Single Sign-On when required by policy.
  • Entra Connect Health — Monitoring and alerting (agent-based) for the AD Connect server, AD FS and AD DS. See Microsoft docs for Connect Health installation and features.
  • Entra Cloud Sync (Cloud Provisioning) — Lightweight agent-based provisioning alternative for distributed environments.

How synchronization works (high level)

  1. Connect reads object changes from on-prem AD based on configured connectors and filters.
  2. Sync rules map, transform, and project attributes to Microsoft Entra ID schema.
  3. Changes are staged and exported to Microsoft Entra ID via the Azure AD connector.
  4. Optional writeback features push certain changes (passwords, groups, devices) back to on-prem AD.

Keypoints

  • Sync runs on a schedule (default ≈ 30 minutes) but can be manually triggered with PowerShell.
  • Staging mode enables read-only testing or standby servers.
  • Filtering (Domain/OU/Attribute) controls what objects sync to the cloud.

Supported Synchronization & Authentication Types

Choose an authentication path based on security, complexity, and user experience needs.

Password Hash Synchronization (PHS)

PHS synchronizes a hash of the on-prem password to Entra ID so users can authenticate directly to the cloud without contacting on-prem AD at sign-in. It's simple, reduces infrastructure, and supports self-service password reset with password writeback.

Pass-Through Authentication (PTA)

PTA uses lightweight agents installed on on-prem servers to validate passwords against your AD DS at sign-in — passwords are not stored in Entra ID. PTA is useful when you need to avoid storing password hashes in the cloud but want less complexity than AD FS.

Federation — AD FS

AD FS provides true federation and SSO using existing on-prem authentication flows. Use when you require advanced on-prem authentication (e.g., legacy smartcard/CAC or complex claim rules).

Decision guide — keypoints

  • PHS: Low maintenance, best default for most organizations.
  • PTA: Good middle ground; no cloud password hashes stored.
  • AD FS: Highest control and complexity; required for certain legacy scenarios.

Installation Requirements & Best Practices

Before installing Azure AD Connect, gather prerequisites and follow these best practices:

System prerequisites

  • Windows Server 2016 or later (server OS on the machine hosting Azure AD Connect / Entra Connect).
  • .NET Framework (per Microsoft version requirements).
  • PowerShell (for module commands and remote triggering).
  • Administrative credentials for on-prem AD and Entra ID/tenant Global Administrator.
  • Proper network connectivity (firewall rules, DNS, proxy exceptions for Microsoft endpoints).

Account and permission model

The installation creates and uses service accounts such as the AD DS Connector account and the Azure AD Connector account. Grant only the minimal permissions recommended in Microsoft guidance.

High availability & staging

Use a secondary server in staging mode as a hot standby (read-only) to allow rapid failover and disaster recovery testing without exporting changes from the standby server.

Keypoints

  • Enable automatic upgrades to receive security and feature updates unless your change control requires manual updates. (Auto-upgrade is enabled by default.)
  • Use Connect Health to gain visibility into sync issues and service health.
  • Document and backup your configuration and service account credentials for disaster recovery.

Synchronization Rules, Filtering & Custom Attributes

Azure AD Connect provides a Synchronization Rules Editor to control which objects and attributes flow to the cloud and how they are transformed.

Filtering methods

  • Domain-based — Select domains to include/exclude.
  • OU-based — Common approach to limit sync to specific organizational units.
  • Attribute-based — Use attributes (e.g., extensionAttribute1, custom flags) to include/exclude accounts.

Custom attribute sync

Map extension attributes or custom AD attributes to Entra ID extension properties via custom rule mappings. Remember that to access certain attributes through Microsoft Graph you may need to request scopes or explicitly select them with $select.

Troubleshooting keypoints

  • Confirm attribute population in AD before mapping (use AD tools or Get-ADUser).
  • Use the Synchronization Service Manager (miisclient.exe) to inspect inbound/outbound flows and transformation rules.
  • Check for UPN or proxyAddress conflicts when emails or sign-in names are not behaving as expected.

Writeback Capabilities (Password, Group, Device)

Writeback allows cloud-initiated changes to be reflected back in your on-prem AD. Common writeback features:

  • Password Writeback: Supports SSPR (Self Service Password Reset) so users can reset cloud passwords and have them written to AD. Requires Azure AD Premium and appropriate configuration.
  • Group Writeback: Writes Microsoft 365 groups back to AD as distribution groups (requires configuration and understanding of group type mapping).
  • Device Writeback: Registers Azure AD-joined devices into on-prem AD to support Conditional Access and device based policies.

Keypoints & best practices

  • Ensure service accounts have required privileges for writeback features — Microsoft docs list exact permissions.
  • Monitor writeback operations via Connect Health and the Synchronization Service Manager.

Monitoring, Automation & Health

Monitoring is essential: use Microsoft Entra Connect Health, the Synchronization Service Manager, and Event Viewer to keep sync healthy. Install the Health agents for deeper telemetry and alerting.

Automatic upgrades

Automatic upgrades simplify maintenance by applying vendor updates. If you must control change windows, disable auto-upgrade and test new builds in staging.

Sync schedule & automation

By default, a delta sync runs approximately every 30 minutes. You can trigger syncs manually using PowerShell.

PowerShell: Triggering a manual sync

# Open an elevated PowerShell on the Azure AD Connect server
Import-Module ADSync
# Delta sync (only changes)
Start-ADSyncSyncCycle -PolicyType Delta

# Full sync (complete)
Start-ADSyncSyncCycle -PolicyType Initial

(You can run Start-ADSyncSyncCycle remotely via Enter-PSSession and then invoking the command on the Connect server.)

PowerShell: Check last sync

# Get the current status of Azure AD Connect sync
Get-ADSyncScheduler

# Example output fields: NextSyncCyclePolicyType, NextSyncCycleStartTime, etc.

Keypoints

  • Use Delta for most operations, Initial for full reconciliation (longer runtime).
  • Automate monitoring alerts from Connect Health into your ITSM or incident system.

Troubleshooting: Tools, Common Errors & Recovery

When sync fails or objects aren't appearing as expected, use the following tools and checks.

Primary troubleshooting tools

  • Synchronization Service Manager (miisclient.exe) — Inspect connector runs, queue, and rule transforms.
  • Event Viewer — Check Application and Operations logs for ADSync/MIIS events.
  • Azure Portal — Entra Connect Health dashboard and sync errors/alerts.
  • PowerShell — Start-ADSyncSyncCycle, Get-ADSyncScheduler, Get-ADSyncConnectorRunStatus (where available).

Common issues & quick checks

  1. Duplicate attributes: Duplicate proxyAddress or ImmutableID can block sync. Check attribute uniqueness in AD and Azure.
  2. Stale objects: Disabled or orphaned objects might not sync as expected.
  3. UPN conflicts: Ensure UPNs are routable and unique; mismatched UPN/email can cause sign-in failures.
  4. Service account misconfiguration: Validate AD Connector account permissions and Azure AD service principal permissions.

Sample Graph API checks

Use Microsoft Graph to verify which users exist in Entra ID and to inspect selected attributes. For programmatic queries use the v1.0 endpoints and specify $select for attributes you need. 

# Example: GET a user with selected fields using curl (replace  and )
curl -H "Authorization: Bearer " \
  "https://graph.microsoft.com/v1.0/users/?$select=id,displayName,userPrincipalName,onPremisesSyncEnabled,mail"

# List users (supports $filter, $select)
curl -H "Authorization: Bearer " \
  "https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName,onPremisesSyncEnabled&$top=50"

Troubleshooting checklist

  • Confirm sync scheduler is enabled (Get-ADSyncScheduler).
  • Run a delta sync and watch miisclient.exe for errors during export to Azure AD.
  • Check Connect Health for alerts and recommended remediations.
  • For writeback errors, validate on-prem AD permissions and that writeback features are enabled in the Entra admin center.

Microsoft Entra Cloud Sync (Lightweight Cloud Provisioning)

Entra Cloud Sync (sometimes referred to as Cloud Provisioning) is a cloud-managed provisioning alternative that uses lightweight agents on-prem to provision objects to Microsoft Entra ID. It's ideal for distributed environments where deploying a full Azure AD Connect server in every location is not practical. Microsoft documents the differences and guidance for when to choose Cloud Sync vs Connect.

Keypoints

  • Cloud Sync stores configuration in the cloud and uses small agents for on-prem connectivity.
  • Useful for organizations with many branch sites or limited central infrastructure.
  • Coexistence is possible in hybrid topologies, but design carefully to avoid overlapping object provisioning.

Advanced: Microsoft Graph API & PowerShell Scripts for Troubleshooting

Below are practical examples you can copy and adapt. They cover typical admin queries and actions for sync validation and remediation.

1) PowerShell: Force a remote delta sync (example)

# Run from a management workstation that can reach the Connect server
$session = New-PSSession -ComputerName "ADConnectServerFQDN" -Credential (Get-Credential)
Invoke-Command -Session $session -ScriptBlock {
    Import-Module ADSync
    Start-ADSyncSyncCycle -PolicyType Delta
}
Remove-PSSession $session

2) PowerShell: Export sync errors

# On the Azure AD Connect server, you can query the Synchronization Service DB
# NOTE: Use miisclient.exe for GUI inspection; advanced exports often use SQL/DB access which is unsupported without guidance.
# Instead, use Export-CSV patterns from miisclient or scheduled diagnostics exported by Connect Health.

3) Microsoft Graph: Get list of synced users (example with MSAL & PowerShell)

# PowerShell + MSAL (conceptual — requires MSAL.PS or AzureAD modules)
# Acquire token (using registered app / appropriate permissions)
# Then call Graph:
$token = ""
Invoke-RestMethod -Headers @{Authorization = "Bearer $token"} `
 -Uri "https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName,onPremisesSyncEnabled&$top=999" `
 -Method Get

Use the onPremisesSyncEnabled attribute to identify objects provisioned from AD. See Graph GET user docs for available properties.

4) Sample Graph query to detect mismatched UPN vs mail

# Example: filter users where UPN endsWith a domain and mail differs (pseudo-filter example)
# Note: Graph $filter supports limited operators; you may need post filtering via script
GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,userPrincipalName,mail,onPremisesImmutableId

Keypoints

  • Graph queries are powerful for inventory and forensics — always request least privilege permissions for apps used for diagnostics.
  • Use paging ($top and @odata.nextLink) when listing large directories.

Upgrading, Migration Paths & Coexistence

Upgrade from legacy DirSync or AADSync to Azure AD Connect (Entra Connect v2) following Microsoft guidance. Keep staging servers and backups to reduce risk during upgrades. The newer Entra Connect releases consolidate components and bring improved foundations.

Coexistence with Cloud Sync

Cloud Sync and Azure AD Connect can both exist in your estate for specific OU-based or location-based use cases, but ensure provisioning targets do not overlap to avoid duplicate objects.

Keypoints

  • Test upgrades in staging before production.
  • Document configuration, connectors, and sync rules for rollback.

Security Best Practices

  • Place the Connect server behind a firewall with controlled outbound access to Microsoft endpoints.
  • Use TLS for all communications and restrict administrative access to the server.
  • Apply least privilege to service accounts — only the permissions documented by Microsoft.
  • Enable Conditional Access / MFA for admin accounts and protect the Global Administrator role.

Keypoints

  • Monitor Connect server OS and patch it per your organization policy.
  • Rotate and securely store credentials for service accounts.

Disaster Recovery & Failover Strategy

Plan for failover with a staging server, documented steps to promote the staging server, and backups of configuration and connector details.

Recommended actions

  1. Maintain a documented runbook for recovery procedures.
  2. Keep a staging server configured and updated — periodically validate promotion procedures.
  3. Back up certificates, service account info, and relevant configuration.

Common Error Scenarios & How to Resolve Them

1) "Object not syncing" — checklist

  • Confirm the object is in a synced OU or not excluded by attribute filter.
  • Check miisclient for inbound import errors and transformation failures.
  • Verify the object is not filtered by connection rules or scoping filters.

2) Duplicate attribute error

  • Search Azure AD for conflicting attributes (proxyAddress, ImmutableId).
  • Correct duplicates on-prem or in the cloud; re-sync.

3) Password writeback failing

  • Ensure Azure AD Connect writeback feature is enabled and service account has rights to reset passwords in AD.
  • Check Connect Health and Event Viewer for specific writeback errors.

Keypoints

  • Diagnose with miisclient, Connect Health, Event Viewer, and Graph queries.
  • Prefer small, incremental changes when adjusting rules to reduce blast radius.

FAQs / FQUs (Frequently asked / useful questions)

Q: How often does Azure AD Connect sync?

By default, a Delta sync runs every ~30 minutes. You can trigger manual syncs via PowerShell using Start-ADSyncSyncCycle -PolicyType Delta or -PolicyType Initial for a full sync.

Q: Does Azure AD Connect store user passwords?

It depends: PHS stores a hash (not the cleartext) in Entra ID. PTA validates credentials against on-prem AD via agents (passwords not stored in the cloud). AD FS uses federation. Choose based on policy and compliance.

Q: Can I use Cloud Sync instead of Azure AD Connect?

Yes — Cloud Sync (Entra Cloud Provisioning) is a lightweight, cloud-managed option using agents for distributed environments. Evaluate based on scale, OU control needs, and feature parity.

Q: How do I identify objects created by sync?

Use Microsoft Graph attributes such as onPremisesSyncEnabled and onPremisesImmutableId to detect synced objects. Use $select to retrieve them in Graph queries.

Quick FQUs / Keypoints summary

  • PHS is simple, PTA avoids cloud-stored password hashes, AD FS provides legacy SSO capabilities.
  • Use staging servers for HA and testing (staging = read-only by default).
  • Monitor with Entra Connect Health and automate alerts into your incident platform.

SEO Notes & Suggested Keywords (for WordPress)

Include these keywords (hyperlinking to cloudknowledge.in) in headings, meta description, and content to improve discoverability:

Suggested keywords (comma separated):

Azure AD Connect, Microsoft Entra Connect, Hybrid Identity, Password Hash Synchronization, Pass-Through Authentication, AD FS, Entra Connect Health, Cloud Sync, Azure AD Connect troubleshooting, Start-ADSyncSyncCycle, Password Writeback, Device Writeback, Group Writeback, Synchronization Rules Editor, Staging Mode, Azure AD Connect upgrade

Meta description suggestion (<= 160 chars)

Azure AD Connect guide — install, sync types (PHS/PTA/AD FS), PowerShell & Graph API troubleshooting, monitoring with Entra Connect Health.

Suggestions for internal links

  • Link "Azure AD Connect" to a relevant page on cloudknowledge.in.
  • Use anchor text such as "Entra Connect Health" or "Password Hash Sync" for internal navigation.

Sample Troubleshooting Runbook (Step-by-Step)

  1. Identify the problem: Is it a sync failure, missing object, authentication failure, or writeback issue?
  2. Collect evidence: miisclient logs, Connect Health alerts, Event Viewer event IDs, recent config changes, and Graph inventory queries.
  3. Run a delta sync: Use PowerShell (Start-ADSyncSyncCycle -PolicyType Delta) and observe miisclient for errors.
  4. Inspect transformation rules: Look for attribute mapping or scoping issues in Synchronization Rules Editor.
  5. Resolve and validate: Fix the attribute/account issue on-prem, run sync, confirm object appears in Entra ID via Graph query.
  6. Document: Add the incident and root cause to your change log and update runbooks if a process change is needed.

Keypoints

  • Always test in staging if rule changes are significant.
  • Capture logs and timestamps to correlate across systems and services.

Summary & Recommended Next Steps

Azure AD Connect remains the core hybrid identity tool for enterprises integrating on-prem AD with Microsoft Entra ID. Use PHS for simplicity, PTA for reduced cloud password storage, and AD FS only when necessary for complex scenarios. Adopt Entra Connect Health and consider Cloud Sync for distributed estates. Use PowerShell & Graph API for diagnostics and automation. Keep staging servers and backups for recovery and enable auto-upgrade where possible to minimize security exposure.

Actionable checklist

  1. Install Connect on supported OS and enable Connect Health agents.
  2. Decide authentication model (PHS/PTA/AD FS) and implement accordingly.
  3. Configure OU/attribute filtering to avoid accidental sync of service accounts.
  4. Enable auto-upgrade or maintain a tested upgrade process.
  5. Implement monitoring and alerting into your incident management channel.

Related references: Microsoft docs on Microsoft Entra Connect (Azure AD Connect), Connect Health, and Microsoft Graph API (user endpoints).

Content supplied for technical guidance — adapt scripts and queries to your environment and follow organizational security policy. For more detailed tutorials and downloadable scripts, visit cloudknowledge.in.

Related Story

Leave a Reply

Your email address will not be published. Required fields are marked *