Microsoft Entra Connect Health watches the on-premises half of your hybrid identity (the Connect Sync server, AD FS and your domain controllers) and raises alerts in Microsoft Entra ID when something stops working. In this post I'll cover licensing and network prerequisites, getting each agent registered, sending alerts to people who will act on them, and a short playbook for the sync alerts you're most likely to see.
Errors this guide fixes
Export to Microsoft Entra ID was Stopped. Accidental delete threshold was reachedMicrosoft Entra Connect HealthHealth Service data is not up to dateMicrosoft Entra Connect HealthPassword Hash Synchronization has stopped workingMicrosoft Entra Connect HealthConnection to Microsoft Entra ID failed due to authentication failureMicrosoft Entra Connect HealthThe sync service isn't runningMicrosoft Entra Connect Health
Prerequisites and licensing#
- Licensing: Connect Health is a Microsoft Entra ID P1/P2 feature. Microsoft's Connect Health FAQ also ties the licence count to the number of registered agents across all roles: one P1/P2 licence for the first agent and 25 more for each additional agent. Ten agents therefore need 226 licences, so decide deliberately which servers you monitor.
- Roles: a Global Administrator or Hybrid Identity Administrator installs and registers agents. Everyone else gets access through Azure RBAC on Connect Health.
- Servers: Windows Server 2016, 2019, 2022 or 2025 with PowerShell 5.0 or later. Server Core isn't supported for the agent installation.
- Network: outbound TCP 443 to the Connect Health endpoints, including
*.aadconnecthealth.azure.com,*.adhybridhealth.azure.com,*.blob.core.windows.net,*.servicebus.windows.net,management.azure.comand the Microsoft sign-in URLs. Older agents also used TCP 5671; current agents need only 443. TLS inspection of this traffic can break registration and uploads, so exempt it. - Sync server version: the Health agent for sync ships with Microsoft Entra Connect Sync 2.5.79.0 or later. Older servers need upgrading first; see keeping Connect Sync supported.
Step 1: Confirm the sync agent is registered#
On the Connect Sync server, the Connect wizard installs and registers the agent for you. Two services should be running; they stay stopped until registration completes.
Get-Service -DisplayName "Microsoft Entra Connect Health Agent", "Microsoft Entra Connect Agent Updater" |
Select-Object DisplayName, Status, StartTypeIf Connect installed fine but the health registration failed, and only then, register manually. Use -AttributeFiltering $true only if you customised the synced attribute set, and pass the server's real staging state:
Register-MicrosoftEntraConnectHealthAgent -AttributeFiltering $false `
-StagingMode (Get-ADSyncScheduler).StagingModeEnabledSign in with the same Global Administrator or Hybrid Identity Administrator account that configured Connect Sync. The services start once registration succeeds.
Step 2: Add agents for AD FS and domain controllers#
- Pick the scope. For AD FS, the agent goes on every AD FS server and every Web Application Proxy server. For AD DS, it goes on each domain controller you want monitored.
- Download and install. In the Microsoft Entra admin center, open Entra ID › Entra Connect, select Connect Health, download the AD FS or AD DS agent and run it as a local administrator.
- Register. Sign in when prompted. If Internet Explorer Enhanced Security Configuration blocks the sign-in window, allow the Microsoft sign-in URLs (and your federation server URL), or register afterwards with
Register-MicrosoftEntraConnectHealthAgentfrom an elevated PowerShell window. - AD FS auditing. The AD FS reports are built from AD FS audit events, so enable auditing as described on Microsoft's AD FS agent page.
Behind a proxy, configure the agent itself. It uses .NET networking rather than WinHTTP, so a netsh winhttp proxy alone isn't picked up, and authenticated (Basic) proxies aren't supported:
Get-MicrosoftEntraConnectHealthProxySettings
Set-MicrosoftEntraConnectHealthProxySettings -HttpsProxyAddress proxy.contoso.com:8080
# Alternative: copy the machine's WinHTTP settings
# Set-MicrosoftEntraConnectHealthProxySettings -ImportFromWinHttp
Restart-Service AzureADConnectHealthAgent*Step 3: Send alerts to people who will act on them#
Open the sync service in Connect Health, go to its alerts and select Notification settings. Check that email notifications are on and add a monitored address, such as a shared operations mailbox or your ticketing system, as an additional recipient. Admin-role mailboxes alone are easy to miss. You get mail when an alert is raised and again when it's resolved.
For visibility without handing out Microsoft Entra admin roles, use Connect Health's Azure RBAC: Reader for the operations team, Owner only for whoever registers agents.
Step 4: Act on the common sync alerts#
Each alert shows the affected server, a description and resolution links. Alerts resolve themselves once the agent stops detecting the condition, and the resolved list keeps the history.
| Alert | Typical cause | First move |
|---|---|---|
| Health Service data is not up to date | The agent hasn't uploaded for more than two hours: services stopped, a proxy change, blocked endpoints or TLS inspection | Check both services, run Test-MicrosoftEntraConnectHealthConnectivity -Role Sync, then fix the proxy or firewall |
| The sync service isn't running | The ADSync service stopped: database (LocalDB/SQL) problem, service account issue, failed restart after patching | Check Get-Service ADSync and the Application log, start the service, then watch the next cycle |
| Export to Microsoft Entra ID was Stopped. Accidental delete threshold was reached | More deletes pending than the threshold (500 by default), usually after an OU, filter or scope change | Review the pending deletes before anything else; see filtering without deleting users |
| Password Hash Synchronization has stopped working | Sync service trouble, connectivity, or the active server switched to staging mode | Run Invoke-ADSyncDiagnostics -PasswordSync on the server and follow its findings |
| Connection to Microsoft Entra ID failed due to authentication failure | The credential Connect uses no longer works, or Conditional Access blocks it | Read the failed run on the Microsoft Entra connector in Synchronization Service Manager and check the sign-in logs for the sync identity |
Object-level problems such as duplicate attributes, data mismatches and oversized attributes are listed per object in the Connect Health sync errors report. To fix them, see my sync errors guide.
Verify#
- Both agent services are running on every monitored server.
Test-MicrosoftEntraConnectHealthConnectivity -Role Sync(or-Role ADDS/-Role ADFS) completes without errors. If PowerShell doesn't recognise the cmdlet, runImport-Module "C:\Program Files\Microsoft Azure AD Connect Health Agent\Modules\AdHealthConfiguration"first.- Each server appears in the portal with recent data, and no "Health Service data is not up to date" alert appears over the next few hours.
- The owner of the notification mailbox confirms they receive the next alert. Don't assume it.
Tips and gotchas#
- Agents update themselves when Microsoft releases a new version. Keep the Agent Updater service running and the documented endpoints reachable.
- Prefer interactive registration. The
-Credentialoption only works with an identity that doesn't need MFA, which doesn't fit a sound admin baseline. - Microsoft's page on its autoupgrade security hardening lists several of these alerts, including the authentication-failure and accidental-delete alerts, as impacted when you're below its minimum versions. Keep both Connect Sync and the agent current.
- If you customised the synced attribute set, the sync agent uploads less error detail, so some sync alerts can only be evaluated in a limited way.
- Connect Health tells you something broke; it doesn't fix it. Treat upgrades and filtering changes as change-controlled work.
