Azure AD Connect Health agent installation

In this article, you'll learn how to install and configure the Azure Active Directory (Azure AD) Connect Health agents. To download the agents, see these instructions.

Requirements

The following table lists requirements for using Azure AD Connect Health.

Requirement Description
There is an Azure AD Premium (P1 or P2) Subsciption. Azure AD Connect Health is a feature of Azure AD Premium (P1 or P2). For more information, see Sign up for Azure AD Premium.

To start a free 30-day trial, see Start a trial.
You're a global administrator in Azure AD. By default, only global administrators can install and configure the health agents, access the portal, and do any operations within Azure AD Connect Health. For more information, see Administering your Azure AD directory.

By using Azure role-based access control (Azure RBAC), you can allow other users in your organization to access Azure AD Connect Health. For more information, see Azure RBAC for Azure AD Connect Health.

Important: Use a work or school account to install the agents. You can't use a Microsoft account. For more information, see Sign up for Azure as an organization.
The Azure AD Connect Health agent is installed on each targeted server. Health agents must be installed and configured on targeted servers so that they can receive data and provide monitoring and analytics capabilities.

For example, to get data from your Active Directory Federation Services (AD FS) infrastructure, you must install the agent on the AD FS server and the Web Application Proxy server. Similarly, to get data from your on-premises Azure AD Domain Services (Azure AD DS) infrastructure, you must install the agent on the domain controllers.
The Azure service endpoints have outbound connectivity. During installation and runtime, the agent requires connectivity to Azure AD Connect Health service endpoints. If firewalls block outbound connectivity, add the outbound connectivity endpoints to the allow list.
Outbound connectivity is based on IP addresses. For information about firewall filtering based on IP addresses, see Azure IP ranges.
TLS inspection for outbound traffic is filtered or disabled. The agent registration step or data upload operations might fail if there's TLS inspection or termination for outbound traffic at the network layer. For more information, see Set up TLS inspection.
Firewall ports on the server are running the agent. The agent requires the following firewall ports to be open so that it can communicate with the Azure AD Connect Health service endpoints:
  • TCP port 443
  • TCP port 5671

  • The latest version of the agent doesn't require port 5671. Upgrade to the latest version so that only port 443 is required. For more information, see Hybrid identity required ports and protocols.
    If Internet Explorer enhanced security is enabled, allow specified websites. If Internet Explorer enhanced security is enabled, then allow the following websites on the server where you install the agent:
  • https://login.microsoftonline.com
  • https://secure.aadcdn.microsoftonline-p.com
  • https://login.windows.net
  • https://aadcdn.msftauth.net
  • The federation server for your organization that's trusted by Azure AD (for example, https://sts.contoso.com)

  • For more information, see How to configure Internet Explorer. If you have a proxy in your network, then see the note that appears at the end of this table.
    PowerShell version 5.0 or newer is installed. Windows Server 2016 includes PowerShell version 5.0.
    FIPS (Federal Information Processing Standard) is disabled. Azure AD Connect Health agents don't support FIPS.

    Important

    Windows Server Core doesn't support installing the Azure AD Connect Health agent.

    Note

    If you have a highly locked-down and restricted environment, you need to add more URLs than the ones the table lists for Internet Explorer enhanced security. Also add URLs that are listed in the table in the next section.

    Outbound connectivity to the Azure service endpoints

    During installation and runtime, the agent needs connectivity to Azure AD Connect Health service endpoints. If firewalls block outbound connectivity, make sure that the URLs in the following table aren't blocked by default.

    Don't disable security monitoring or inspection of these URLs. Instead, allow them as you would allow other internet traffic.

    These URLs allow communication with Azure AD Connect Health service endpoints. Later in this article, you'll learn how to check outbound connectivity by using Test-AzureADConnectHealthConnectivity.

    Domain environment Required Azure service endpoints
    General public
  • *.blob.core.windows.net
  • *.aadconnecthealth.azure.com
  • *.servicebus.windows.net - Port: 5671 (This endpoint isn't required in the latest version of the agent.)
  • *.adhybridhealth.azure.com/
  • https://management.azure.com
  • https://policykeyservice.dc.ad.msft.net/
  • https://login.windows.net
  • https://login.microsoftonline.com
  • https://secure.aadcdn.microsoftonline-p.com
  • https://www.office.com (This endpoint is used only for discovery purposes during registration.)
  • https://aadcdn.msftauth.net
  • https://aadcdn.msauth.net
  • Azure Germany
  • *.blob.core.cloudapi.de
  • *.servicebus.cloudapi.de
  • *.aadconnecthealth.microsoftazure.de
  • https://management.microsoftazure.de
  • https://policykeyservice.aadcdi.microsoftazure.de
  • https://login.microsoftonline.de
  • https://secure.aadcdn.microsoftonline-p.de
  • https://www.office.de (This endpoint is used only for discovery purposes during registration.)
  • https://aadcdn.msftauth.net
  • https://aadcdn.msauth.net
  • Azure Government
  • *.blob.core.usgovcloudapi.net
  • *.servicebus.usgovcloudapi.net
  • *.aadconnecthealth.microsoftazure.us
  • https://management.usgovcloudapi.net
  • https://policykeyservice.aadcdi.azure.us
  • https://login.microsoftonline.us
  • https://secure.aadcdn.microsoftonline-p.com
  • https://www.office.com (This endpoint is used only for discovery purposes during registration.)
  • https://aadcdn.msftauth.net
  • https://aadcdn.msauth.net
  • Install the agent

    To download and install the Azure AD Connect Health agent:

    Install the agent for AD FS

    Note

    Your AD FS server should be different from your Sync server. Don't install the AD FS agent on your Sync server.

    Before you install the agent, make sure your AD FS server host name is unique and isn't present in the AD FS service. To start the agent installation, double-click the .exe file that you downloaded. In the first window, select Install.

    Screenshot showing the installation window for the Azure AD Connect Health AD FS agent.

    After the installation finishes, select Configure Now.

    Screenshot showing the confirmation message for the Azure AD Connect Health AD FS agent installation.

    A PowerShell window opens to start the agent registration process. When you're prompted, sign in by using an Azure AD account that has permissions to register the agent. By default, the global admin account has permissions.

    Screenshot showing the sign-in window for Azure AD Connect Health AD FS.

    After you sign in, PowerShell continues. When it finishes, you can close PowerShell. The configuration is complete.

    At this point, the agent services should start automatically to allow the agent to securely upload the required data to the cloud service.

    If you haven't met all of the prerequisites, warnings appear in the PowerShell window. Be sure to complete the requirements before you install the agent. The following screenshot shows an example of these warnings.

    Screenshot showing the Azure AD Connect Health AD FS configure script.

    To verify that the agent was installed, look for the following services on the server. If you completed the configuration, they should already be running. Otherwise, they're stopped until the configuration is complete.

    • Azure AD Connect Health AD FS Diagnostics Service
    • Azure AD Connect Health AD FS Insights Service
    • Azure AD Connect Health AD FS Monitoring Service

    Screenshot showing Azure AD Connect Health AD FS services.

    Enable auditing for AD FS

    Note

    This section applies only to AD FS servers. You don't have to follow these steps on the Web Application Proxy servers.

    The Usage Analytics feature needs to gather and analyze data. So the Azure AD Connect Health agent needs the information in the AD FS audit logs. These logs aren't enabled by default. Use the following procedures to enable AD FS auditing and to locate the AD FS audit logs on your AD FS servers.

    To enable auditing for AD FS on Windows Server 2012 R2

    1. On the Start screen, open Server Manager, and then open Local Security Policy. Or on the taskbar, open Server Manager, and then select Tools/Local Security Policy.

    2. Go to the Security Settings\Local Policies\User Rights Assignment folder. Then double-click Generate security audits.

    3. On the Local Security Setting tab, verify that the AD FS service account is listed. If it's not listed, then select Add User or Group, and add it to the list. Then select OK.

    4. To enable auditing, open a Command Prompt window with elevated privileges. Then run the following command:

      auditpol.exe /set /subcategory:{0CCE9222-69AE-11D9-BED3-505054503030} /failure:enable /success:enable

    5. Close Local Security Policy.

      Important

      The following steps are required only for primary AD FS servers.

    6. Open the AD FS Management snap-in. (In Server Manager, select Tools > AD FS Management.)

    7. In the Actions pane, select Edit Federation Service Properties.

    8. In the Federation Service Properties dialog box, select the Events tab.

    9. Select the Success audits and Failure audits check boxes, and then select OK.

    10. To enable verbose logging through PowerShell, use the following command:

      Set-AdfsProperties -LOGLevel Verbose

    To enable auditing for AD FS on Windows Server 2016

    1. On the Start screen, open Server Manager, and then open Local Security Policy. Or on the taskbar, open Server Manager, and then select Tools/Local Security Policy.

    2. Go to the Security Settings\Local Policies\User Rights Assignment folder, and then double-click Generate security audits.

    3. On the Local Security Setting tab, verify that the AD FS service account is listed. If it's not listed, then select Add User or Group, and add the AD FS service account to the list. Then select OK.

    4. To enable auditing, open a Command Prompt window with elevated privileges. Then run the following command:

      auditpol.exe /set /subcategory:{0CCE9222-69AE-11D9-BED3-505054503030} /failure:enable /success:enable

    5. Close Local Security Policy.

      Important

      The following steps are required only for primary AD FS servers.

    6. Open the AD FS Management snap-in. (In Server Manager, select Tools > AD FS Management.)

    7. In the Actions pane, select Edit Federation Service Properties.

    8. In the Federation Service Properties dialog box, select the Events tab.

    9. Select the Success audits and Failure audits check boxes, and then select OK. Success audits and failure audits should be enabled by default.

    10. Open a PowerShell window and run the following command:

      Set-AdfsProperties -AuditLevel Verbose

    The "basic" audit level is enabled by default. For more information, see AD FS audit enhancement in Windows Server 2016.

    To locate the AD FS audit logs

    1. Open Event Viewer.

    2. Go to Windows Logs, and then select Security.

    3. On the right, select Filter Current Logs.

    4. For Event sources, select AD FS Auditing.

      For more information about audit logs, see Operations questions.

      Screenshot showing the Filter Current Log window. In the "Event sources" field, "AD FS auditing" is selected.

    Warning

    A group policy can disable AD FS auditing. If AD FS auditing is disabled, usage analytics about login activities are unavailable. Ensure that you have no group policy that disables AD FS auditing.

    Install the agent for Sync

    The Azure AD Connect Health agent for Sync is installed automatically in the latest version of Azure AD Connect. To use Azure AD Connect for Sync, download the latest version of Azure AD Connect and install it.

    To verify the agent has been installed, look for the following services on the server. If you completed the configuration, the services should already be running. Otherwise, the services are stopped until the configuration is complete.

    • Azure AD Connect Health Sync Insights Service
    • Azure AD Connect Health Sync Monitoring Service

    Screenshot showing the running Azure AD Connect Health for Sync services on the server.

    Note

    Remember that you must have Azure AD Premium (P1 or P2) to use Azure AD Connect Health. If you don't have Azure AD Premium, you can't complete the configuration in the Azure portal. For more information, see the requirements.

    Manually register Azure AD Connect Health for Sync

    If the Azure AD Connect Health for Sync agent registration fails after you successfully install Azure AD Connect, then you can use a PowerShell command to manually register the agent.

    Important

    Use this PowerShell command only if the agent registration fails after you install Azure AD Connect.

    Manually register the Azure AD Connect Health agent for Sync by using the following PowerShell command. The Azure AD Connect Health services will start after the agent has been successfully registered.

    Register-AzureADConnectHealthSyncAgent -AttributeFiltering $true -StagingMode $false

    The command takes following parameters:

    • AttributeFiltering: $true (default) if Azure AD Connect isn't syncing the default attribute set and has been customized to use a filtered attribute set. Otherwise, use $false.
    • StagingMode: $false (default) if the Azure AD Connect server is not in staging mode. If the server is configured to be in staging mode, use $true.

    When you're prompted for authentication, use the same global admin account (such as admin@domain.onmicrosoft.com) that you used to configure Azure AD Connect.

    Install the agent for Azure AD DS

    To start the agent installation, double-click the .exe file that you downloaded. In the first window, select Install.

    Screenshot showing the Azure AD Connect Health agent for AD DS installation window.

    When the installation finishes, select Configure Now.

    Screenshot showing the window that finishes the installation of the Azure AD Connect Health agent for Azure AD DS.

    A Command Prompt window opens. PowerShell runs Register-AzureADConnectHealthADDSAgent. When you're prompted, sign in to Azure.

    Screenshot showing the sign-in window for the Azure AD Connect Health agent for Azure AD DS.

    After you sign in, PowerShell continues. When it finishes, you can close PowerShell. The configuration is complete.

    At this point, the services should be started automatically, allowing the agent to monitor and gather data. If you haven't met all of the prerequisites outlined in the previous sections, then warnings appear in the PowerShell window. Be sure to complete the requirements before you install the agent. The following screenshot shows an example of these warnings.

    Screenshot showing a warning for the Azure AD Connect Health agent for Azure AD DS configuration.

    To verify that the agent is installed, look for the following services on the domain controller:

    • Azure AD Connect Health AD DS Insights Service
    • Azure AD Connect Health AD DS Monitoring Service

    If you completed the configuration, these services should already be running. Otherwise, they're stopped until the configuration finishes.

    Screenshot showing the running services on the domain controller.

    Quickly install the agent on multiple servers

    1. Create a user account in Azure AD. Secure it by using a password.

    2. Assign the Owner role for this local Azure AD account in Azure AD Connect Health by using the portal. Follow these steps. Assign the role to all service instances.

    3. Download the .exe MSI file in the local domain controller for the installation.

    4. Run the following script. Replace the parameters with your new user account and its password.

      AdHealthAddsAgentSetup.exe /quiet
      Start-Sleep 30
      $userName = "NEWUSER@DOMAIN"
      $secpasswd = ConvertTo-SecureString "PASSWORD" -AsPlainText -Force
      $myCreds = New-Object System.Management.Automation.PSCredential ($userName, $secpasswd)
      import-module "C:\Program Files\Azure Ad Connect Health Adds Agent\PowerShell\AdHealthAdds"
      
      Register-AzureADConnectHealthADDSAgent -Credential $myCreds
      
      

    When you finish, you can remove access for the local account by doing one or more of the following tasks:

    • Remove the role assignment for the local account for Azure AD Connect Health.
    • Rotate the password for the local account.
    • Disable the Azure AD local account.
    • Delete the Azure AD local account.

    Register the agent by using PowerShell

    After you install the appropriate agent setup.exe file, you can register the agent by using the following PowerShell commands, depending on the role. Open a PowerShell window and run the appropriate command:

        Register-AzureADConnectHealthADFSAgent
        Register-AzureADConnectHealthADDSAgent
        Register-AzureADConnectHealthSyncAgent
    
    

    Note

    To register against sovereign clouds, use the following command lines:

    Register-AzureADConnectHealthADFSAgent -UserPrincipalName upn-of-the-user
    Register-AzureADConnectHealthADDSAgent -UserPrincipalName upn-of-the-user
    Register-AzureADConnectHealthSyncAgent -UserPrincipalName upn-of-the-user
    

    These commands accept Credential as a parameter to complete the registration noninteractively or to complete the registration on a machine that runs Server Core. Keep in mind that:

    • You can capture Credential in a PowerShell variable that's passed as a parameter.
    • You can provide any Azure AD identity that has permissions to register the agents and that does not have multifactor authentication enabled.
    • By default, global admins have permissions to register the agents. You can also allow less-privileged identities to do this step. For more information, see Azure RBAC.
        $cred = Get-Credential
        Register-AzureADConnectHealthADFSAgent -Credential $cred
    
    

    Configure Azure AD Connect Health agents to use HTTP proxy

    You can configure Azure AD Connect Health agents to work with an HTTP proxy.

    Note

    • Netsh WinHttp set ProxyServerAddress is not supported. The agent uses System.Net instead of Windows HTTP Services to make web requests.
    • The configured HTTP proxy address is used to pass-through encrypted HTTPS messages.
    • Authenticated proxies (using HTTPBasic) are not supported.

    Change the agent proxy configuration

    To configure the Azure AD Connect Health agent to use an HTTP proxy, you can:

    • Import existing proxy settings.
    • Specify proxy addresses manually.
    • Clear the existing proxy configuration.

    Note

    To update the proxy settings, you must restart all Azure AD Connect Health agent services. Run the following command:

    Restart-Service AzureADConnectHealth*

    Import existing proxy settings

    You can import Internet Explorer HTTP proxy settings so that the Azure AD Connect Health agents can use the settings. On each of the servers that run the health agent, run the following PowerShell command:

    Set-AzureAdConnectHealthProxySettings -ImportFromInternetSettings
    

    You can import WinHTTP proxy settings so that the Azure AD Connect Health agents can use them. On each of the servers that run the health agent, run the following PowerShell command:

    Set-AzureAdConnectHealthProxySettings -ImportFromWinHttp
    

    Specify proxy addresses manually

    You can manually specify a proxy server. On each of the servers that run the health agent, run the following PowerShell command:

    Set-AzureAdConnectHealthProxySettings -HttpsProxyAddress address:port
    

    Here's an example:

    Set-AzureAdConnectHealthProxySettings -HttpsProxyAddress myproxyserver: 443

    In this example:

    • The address setting can be a DNS-resolvable server name or an IPv4 address.
    • You can omit port. If you do, then 443 is the default port.

    Clear the existing proxy configuration

    You can clear the existing proxy configuration by running the following command:

    Set-AzureAdConnectHealthProxySettings -NoProxy
    

    Read current proxy settings

    You can read the current proxy settings by running the following command:

    Get-AzureAdConnectHealthProxySettings
    

    Test connectivity to Azure AD Connect Health service

    Occasionally, the Azure AD Connect Health agent can lose connectivity with the Azure AD Connect Health service. Causes of this connectivity loss can include network problems, permission problems, and various other problems.

    If the agent can't send data to the Azure AD Connect Health service for longer than two hours, the following alert appears in the portal: "Health Service data is not up to date."

    You can find out whether the affected Azure AD Connect Health agent can upload data to the Azure AD Connect Health service by running the following PowerShell command:

    Test-AzureADConnectHealthConnectivity -Role ADFS
    

    The role parameter currently takes the following values:

    • ADFS
    • Sync
    • ADDS

    Note

    To use the connectivity tool, you must first register the agent. If you can't complete the agent registration, make sure that you have met all of the requirements for Azure AD Connect Health. Connectivity is tested by default during agent registration.

    Next steps

    Check out the following related articles: