Edit

Share via

Install the Microsoft Entra provisioning Agent by using a CLI and PowerShell

  • Article

This article shows you how to install the Microsoft Entra provisioning agent by using PowerShell cmdlets.

Note

This article deals with installing the provisioning agent by using the command-line interface (CLI). For information on how to install the Microsoft Entra provisioning agent by using the wizard, see Install the Microsoft Entra provisioning agent.

Prerequisite

The Windows server must have TLS 1.2 enabled before you install the Microsoft Entra provisioning agent by using PowerShell cmdlets. To enable TLS 1.2, follow the steps in Prerequisites for Microsoft Entra Cloud Sync.

Important

The following installation instructions assume that all the prerequisites were met.

Install the Microsoft Entra provisioning agent by using PowerShell cmdlets

Tip

Steps in this article might vary slightly based on the portal you start from.

  1. Sign in to the Microsoft Entra admin center as at least a Hybrid Administrator.
  2. Browse to Identity > Hybrid management > Microsoft Entra Connect > Cloud sync. Screenshot of cloud sync home page.
  1. Select Manage.
  2. Click Download provisioning agent
  3. On the right, click Accept terms and download.
  4. For the purposes of these instructions, the agent was downloaded to the C:\temp folder.
  5. Install ProvisioningAgent in quiet mode. 
    $installerProcess = Start-Process 'c:\temp\AADConnectProvisioningAgentSetup.exe' /quiet -NoNewWindow -PassThru 
$installerProcess.WaitForExit()
  6. Import the Provisioning Agent PS module. 
    Import-Module "C:\Program Files\Microsoft Azure AD Connect Provisioning Agent\Microsoft.CloudSync.PowerShell.dll"
  7. Connect to Microsoft Entra ID by using an account with the hybrid identity role. You can customize this section to fetch a password from a secure store. 
    $hybridAdminPassword = ConvertTo-SecureString -String "Hybrid Identity Administrator password" -AsPlainText -Force 

$hybridAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("[email protected]", $hybridAdminPassword) 

Connect-AADCloudSyncAzureAD -Credential $hybridAdminCreds
  8. Add the gMSA account, and provide credentials of the domain admin to create the default gMSA account. 
    $domainAdminPassword = ConvertTo-SecureString -String "Domain admin password" -AsPlainText -Force 

$domainAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("DomainName\DomainAdminAccountName", $domainAdminPassword) 

Add-AADCloudSyncGMSA -Credential $domainAdminCreds
  9. Or use the preceding cmdlet to provide a precreated gMSA account. 
    Add-AADCloudSyncGMSA -CustomGMSAName preCreatedGMSAName$
  10. Add the domain. 
    $contosoDomainAdminPassword = ConvertTo-SecureString -String "Domain admin password" -AsPlainText -Force 

$contosoDomainAdminCreds = New-Object System.Management.Automation.PSCredential -ArgumentList ("DomainName\DomainAdminAccountName", $contosoDomainAdminPassword) 

Add-AADCloudSyncADDomain -DomainName contoso.com -Credential $contosoDomainAdminCreds
  11. Or use the preceding cmdlet to configure preferred domain controllers. 
    $preferredDCs = @("PreferredDC1", "PreferredDC2", "PreferredDC3") 

Add-AADCloudSyncADDomain -DomainName contoso.com -Credential $contosoDomainAdminCreds -PreferredDomainControllers $preferredDCs
  12. Repeat the previous step to add more domains. Provide the account names and domain names of the respective domains.
  13. Restart the service. 
    Restart-Service -Name AADConnectProvisioningAgent
  14. Go to the Microsoft Entra admin center to create the cloud sync configuration.

Provisioning agent gMSA PowerShell cmdlets

Now that you've installed the agent, you can apply more granular permissions to the gMSA. For information and step-by-step instructions on how to configure the permissions, see Microsoft Entra Connect cloud provisioning agent gMSA PowerShell cmdlets.

Installing against US government cloud

By default, the Microsoft Entra provisioning agent installs against the default Azure cloud environment. If you are installing the agent for use in the US government cloud do the following:

  • In step #8, add ENVIRONMENTNAME=AzureUSGovernment to the command line like the example. 
    $installerProcess = Start-Process -FilePath "c:\temp\AADConnectProvisioningAgent.Installer.exe" -ArgumentList "/quiet ENVIRONMENTNAME=AzureUSGovernment" -NoNewWindow -PassThru 
$installerProcess.WaitForExit()

Next steps