Register the Azure AD Connect Health for ADDS Agent via Service Principal

Hi everyone!

Graeme Bray back with you for a new journey.  Today's adventure is to leverage an Azure AD Service Principal to register  the Azure AD Connect Health agent (ADDS or ADFS) with the portal, rather than utilizing a Cloud-only exempt account (specifically important for Core machines).

We'll be focusing around Azure AD Connect Health for ADDS in this post, but the same should apply to ADFS.

Requirements (Part 1):

  • A machine with the AZ commands (specifically Connect-AzAccount and New-AzAdServicePrincipal)

Initially, you will need to connect to Azure via Connect-AzAccount with an account that has appropriate permissions to create Service Principals in Azure AD.  This blog post is not discussing RBAC in Azure, so please go here for more details.

To create the service principal, I followed this set of commands in PowerShell.  Ensure you modify the script to suit your needs.

# Imports the PSADPasswordCredential object

Import-Module -Name Az.Resources

# Creates a Service Principal compatible Credential and creates the object.

$credentials = New-Object Microsoft.Azure.Commands.ActiveDirectory.PSADPasswordCredential -Property @{
EndDate=Get-Date -Year 2024;

New-AzAdServicePrincipal -DisplayName ServicePrincipalName -PasswordCredential $credentials

Source: Use Azure service principals with Azure PowerShell | Microsoft Docs

Option 1:

Verify your service principal has been created in one of two ways:

Get-AzAdServicePrincipal -DisplayNameBeginsWith ‘NAME'

Verify Service Principal was createdVerify Service Principal was created

Option 2:

Log into the Azure Portal – Select Azure Active Directory on the left

Select App Registrations

Select “All Applications” in the middle blade

Enter your application name (or part of it) in the search bar.


If you navigate into the App Registration, you can select “Certificates & secrets” and see your client secret you specified.  This can be stored in an Azure Key Vault or 3rd party password management solution.

Save the App Registration ApplicationID as you will need that for the next section.

** Note ** – Never save credentials in scripts.

This completes the App Registration section.  Next, we need to set permissions in Azure AD Connect Health for this Service Principal.

Search in the top bar for “Azure AD Connect” and select Azure AD Connect Health to launch the service blade.

Click on Role based access control (IAM) on the left side.

Click Add -> Role Assignment

On the Role Assignment window, select:

Role: Contributor

Select : 

Azure RBAC window for Azure AD Connect Health

Azure RBAC window for Azure AD Connect Health

Click .

Under Role Assignments, you should how see your Service Principal registered as a Contributor.

Connect Health only supports the following 3 built-in roles:

Owner, Contributor, Reader.

Source: Azure Active Directory Connect Health operations | Microsoft Docs

This completes the Service Principal registration and access delegation.

Requirements (Part 2):

The first thing that needs to be done is to copy the AAD Connect Health agent to the target machine.  Mine is in c:tempAdHealthAddsAgentSetup.exe.

Run the AADC Health installer (click )

Azure AD Connect Health agent installation window

Azure AD Connect Health agent installation window

Once the prompt to start the configuration of AADC launches, click and open an elevated PowerShell window.

You can obtain my script snippet from Github – Register-AADConnectHealthWithServicePrincipal.ps1

Ensure you modify the ServicePrincipal variable and the TenantID variable from the Requirements section.  The script should be smart enough to prompt you if your values don't match the GUID format.

Run the code and enter **just** the credential in the prompt.  This is meant to avoid you from hardcoding credentials.  In other instances, you store this in an Azure Key Vault and programmatically query for it.  In this case, we don't want to install the Az module on the DCs/ADFS just to query this.

Powershell credential prompt during registrationPowershell credential prompt during registration

** Note ** – Get-Credential is used for a more secure input method.  The “Username” field is not important and can be left alone.  The variable leveraging this is cleaned up post-run.

Here is the remaining part of the script run where you can see the onboarding to Azure AD Connect Health.

Azure AD Connect Health agent registration Powershell resultsAzure AD Connect Health agent registration Powershell results

You can see that before my install, I only had one environment onboarded into AAD Connect Health for ADDS:

Azure AD Connect Health pre-registration Azure Portal pageAzure AD Connect Health pre-registration Azure Portal page

After running the script, you see two environments:

Azure AD Connect Health post-registration Azure Portal pageAzure AD Connect Health post-registration Azure Portal page

It can take up to 5 minutes for a device to show up in the portal.

I ran this against a Windows Desktop Experience and a Windows Core .

That's all there is.  You can leverage this to register your machines without a “Service Account” cloud only account, without Global Admin, and enforce MFA via Conditional Access on all your interactive sign ins.

Until next time!

-Graeme “Monitor AD” Bray

The sample scripts are not supported under any Microsoft standard support program or service. The sample scripts are provided AS IS without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the sample scripts and documentation remains with you. In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the sample scripts or documentation, even if Microsoft has been advised of the possibility of such damages.


This article was originally published by Microsoft’s Failover Clustering Blog. You can find the original article here.