Install the Azure AD Connect provisioning agent

This article walks you through the installation process for the Azure Active Directory (Azure AD) Connect provisioning agent and how to initially configure it in the Azure portal.

Important

The following installation instructions assume that you've met all the prerequisites.

Note

This article deals with installing the provisioning agent by using the wizard. For information about installing the Azure AD Connect provisioning agent by using a CLI, see Install the Azure AD Connect provisioning agent by using a CLI and PowerShell.

For more information and an example, view the following video:

Group Managed Service Accounts

A group Managed Service Account (gMSA) is a managed domain account that provides automatic password management, simplified service principal name (SPN) management, and the ability to delegate the management to other administrators. A gMSA also extends this functionality over multiple servers. Azure AD Connect cloud sync supports and recommends the use of a gMSA for running the agent. For more information, see Group Managed Service Accounts.

Update an existing agent to use the gMSA

To update an existing agent to use the Group Managed Service Account created during installation, upgrade the agent service to the latest version by running AADConnectProvisioningAgent.msi. Now run through the installation wizard again and provide the credentials to create the account when you're prompted to do so.

Install the agent

  1. In the Azure portal, select Azure Active Directory.
  2. On the left, select Azure AD Connect.
  3. On the left, select Cloud sync.

Screenshot of new UX screen.

  1. On the left, select Agent.
  2. Select Download on-premises agent, and select Accept terms & download.

Screenshot of download agent.

  1. Once the Azure AD Connect Provisioning Agent Package has completed downloading, run the AADConnectProvisioningAgentSetup.exe installation file from your downloads folder.
  2. On the splash screen, select I agree to the license and conditions, and then select Install.

Screenshot that shows the Microsoft Azure AD Connect Provisioning Agent Package splash screen.

  1. Once the installation operation completes, the configuration wizard will launch. Select Next to start the configuration. Screenshot of the welcome screen.
  2. On the Select Extension screen, select HR-driven provisioning (Workday and SuccessFactors) / Azure AD Connect Cloud Sync and click Next. Screenshot of the select extensions screen.

Note

If you are installing the provisioning agent for use with on-premsise app provisioning then select On-premises application provisioning (Azure AD to application).

  1. Sign in with your Azure AD global administrator account. If you have Internet Explorer enhanced security enabled, it will block the sign-in. If so, close the installation, disable Internet Explorer enhanced security, and restart the Azure AD Connect Provisioning Agent Package installation.

Screenshot of the Connect Azure AD screen.

  1. On the Configure Service Account screen, select a group Managed Service Account (gMSA). This account is used to run the agent service. If a managed service account is already configured in your domain, you might skip this screen. If prompted, choose either:
  • Create gMSA which lets the agent create the provAgentgMSA$ managed service account for you. The group managed service account (for example, CONTOSO\provAgentgMSA$) will be created in the same Active Directory domain where the host server has joined. To use this option, enter the Active Directory domain administrator credentials.
  • Use custom gMSA and provide the name of the managed service account.

To continue, select Next.

Screenshot of the Configure Service Account screen.

  1. On the Connect Active Directory screen, if your domain name appears under Configured domains, skip to the next step. Otherwise, type your Active Directory domain name, and select Add directory.

  2. Sign in with your Active Directory domain administrator account. The domain administrator account shouldn't have password change requirements. In case the password expires or changes, you'll need to reconfigure the agent with the new credentials. This operation will add your on-premises directory. Select OK, then select Next to continue.

Screenshot that shows how to enter the domain admin credentials.

  1. The following screenshot shows an example of contoso.com configured domain. Select Next to continue.

Screenshot of the Connect Active Directory screen.

  1. On the Configuration complete screen, select Confirm. This operation will register and restart the agent.

  2. Once this operation completes, you should be notified that Your agent configuration was successfully verified. You can select Exit.

Screenshot that shows the finish screen.

  1. If you still get the initial splash screen, select Close.

Verify the agent installation

Agent verification occurs in the Azure portal and on the local server that's running the agent.

Azure portal agent verification

To verify that the agent is being registered by Azure AD, follow these steps:

  1. Sign in to the Azure portal.
  2. Select Azure Active Directory.
  3. Select Azure AD Connect, and then select Cloud sync. Screenshot of new UX screen.
  4. On the cloud sync page, you'll see the agents you've installed. Verify that the agent is displayed and the status is healthy.

On the local server

To verify that the agent is running, follow these steps:

  1. Sign in to the server with an administrator account.
    1. Open Services either by navigating to it or by going to Start/Run/Services.msc.
  2. Under Services, make sure that Microsoft Azure AD Connect Agent Updater and Microsoft Azure AD Connect Provisioning Agent are present and the status is Running. Screenshot that shows the Windows services.

Important

After you've installed the agent, you must configure and enable it before it will start synchronizing users. To configure a new agent, see Create a new configuration for Azure AD Connect cloud sync.

Enable password writeback in Azure AD Connect cloud sync

To use password writeback and enable the self-service password reset (SSPR) service to detect the cloud sync agent, use the Set-AADCloudSyncPasswordWritebackConfiguration cmdlet and the tenant’s global administrator credentials:

 Import-Module "C:\\Program Files\\Microsoft Azure AD Connect Provisioning Agent\\Microsoft.CloudSync.Powershell.dll" 
 Set-AADCloudSyncPasswordWritebackConfiguration -Enable $true -Credential $(Get-Credential)

For more information about using password writeback with Azure AD Connect cloud sync, see Tutorial: Enable cloud sync self-service password reset writeback to an on-premises environment (preview).

Install an agent in the US government cloud

By default, the Azure AD Connect provisioning agent is installed in the default Azure environment. If you're installing the agent for US government use, make this change in step 7 of the preceding installation procedure:

  • Instead of selecting Open file, select Start > Run, and then go to the AADConnectProvisioningAgentSetup.exe file. In the Run box, after the executable, enter ENVIRONMENTNAME=AzureUSGovernment, and then select OK.

    Screenshot that shows how to install an agent in the US government cloud.

Password hash synchronization and FIPS with cloud sync

If your server has been locked down according to the Federal Information Processing Standard (FIPS), MD5 (message-digest algorithm 5) is disabled.

To enable MD5 for password hash synchronization, do the following:

  1. Go to %programfiles%\Microsoft Azure AD Connect Provisioning Agent.
  2. Open AADConnectProvisioningAgent.exe.config.
  3. Go to the configuration/runtime node at the top of the file.
  4. Add the <enforceFIPSPolicy enabled="false"/> node.
  5. Save your changes.

For reference, your code should look like the following snippet:

<configuration>
   <runtime>
      <enforceFIPSPolicy enabled="false"/>
   </runtime>
</configuration>

For more information about security and FIPS, see Azure AD password hash sync, encryption, and FIPS compliance.

Next steps