Configure the Active Directory Integration

JumpCloud’s Active Directory Integration (ADI) uses two agents: an Import agent and a Sync agent. As covered in Get Started: Active Directory Integration, there are three primary use-cases and configurations: AD Extension with AD as the Primary IdP, Synchronous integration (two-way sync), and AD Extension with JumpCloud as the Primary IdP. This article details all of the absolute requirements for configuring both AD Import & Sync, along with configurations and objects needed within Active Directory (AD) to support each of these use cases.

Prerequisites

• You’ve read Get Started: Active Directory Integration.

Considerations

• If you opt to employ password expiration in JumpCloud, users synced with AD will not receive notifications from JumpCloud. You’ll need to manage expiration messaging directly for AD synced users. This can be done by going to users » select expiring users » resend email. This will send an email request to users to reset their password.
• The following user attributes are supported:
  • First Name
  • Last Name
  • Username
  • Email

ADI Prerequisite Checklist

Before configuring any of the ADI Agents, JumpCloud recommends completing each item on the following checklist before continuing. 

• AD Domain Admin credentials.
• Access to all Domain Controllers (DCs) in the AD domain.
• Your DCs are running on a JumpCloud supported 64-bit Windows Server version (2012, 2016, 2019, 2022**).
  • The AD import agent has been validated on 64-bit Windows Server version 2022.
  • The AD Sync requires some additional changes to support 64-bit Windows Server version 2022. A new version will be released that will have support for this Server version.
• DCs have networking access to the internet and are able to communicate outbound to console.jumpcoud.com over HTTPS port 443. The JumpCloud AD Import and Sync Agent services uses SSL/TLS for all communication. If no network connectivity exists to JumpCloud, the ADI will fail to sync and will not work properly. 
• JumpCloud Organization for your company.
• JumpCloud Admin account.

Installing the AD Import Agent

To import and update user identities, attributes, passwords, and user groups from AD into JumpCloud, install the Import Agent on all DCs within your AD domain. 

You can download the AD Import Agent in the JumpCloud Admin Portal from Directory Integrations > Active Directory. Please follow the directions below to properly Install the AD Import Agent. 

System Requirements

• Supported only on 64-bit Windows Server version (2012, 2016, 2019)
• 15MB disk space
• 10MB RAM

Prerequisites for the AD Import Agent

• Scheduled Downtime – installation requires server reboot! 
• Internet connectivity and able to communicate over port 443 to console.jumpcloud.com
• A dedicated Administrator account that is specifically for 3rd party services that require an API token (API tokens are specific to each Admin account).

• Your JumpCloud Admin API Key and your JumpCloud Organization ID from your JumpCloud tenant.

Considerations

• Users you wish to import or export between JumpCloud and AD must have defined <First Name> and <Last Name> attributes, i.e., the first name and last name fields cannot be empty.
• We recommend that all users you plan to import into JumpCloud live in a single OU or be nested underneath a chosen OU (Root user container) in AD. This can be the default CN=Users container in AD or an alternate custom OU in the directory. 
• The AD Import agent requires a specific Security Group to be created to identify users and groups for import into your JumpCloud organization. We will refer to this as the JumpCloud Integration Security Group.

• You can manage users in 2 ways
  • Individually by adding them to the security group created for this integration, located in the designated OU. 
  • Using groups located in or nested in the designated Root user container by adding those groups as a member of the JumpCloud Integration Security Group.
• Removing users from the JumpCloud integration Security Group within AD will either delete those users in JumpCloud and deprovision them from all bound resources or disconnect them from the AD integration, leaving them active in JumpCloud and allowing them to be managed in JumpCloud directly. The behavior is controlled by the UserDissociationAction setting in AD Import Agent configuration file. 
• If you relocate users in AD outside of the Root User Container, you could disrupt password synchronization, or remove users and groups from your JumpCloud instance, along with any associated data and resource associations.
• Importing privileged user accounts into your JumpCloud tenant (such as Domain Admins in AD) isn’t supported. AD flags privileged accounts with “adminCount=1” in the AD. The JumpCloud ADI Agents are not able to effectively manage those privileged accounts, thus causing errors and issues with User, attribute, and Password updates to JumpCloud. 
• We recommend that you align password complexity requirements between AD and JumpCloud as closely as possible. Otherwise, passwords may not replicate if they’re rejected by the destination directory’s complexity requirements.
• We recommend that a JumpCloud Administrator Service Account be created to supply the API key so that the import is not tied to an individual administrator’s account. 

To prepare your JumpCloud tenant for integration with AD

1. Log in to the JumpCloud Admin Portal.
2. Go to Directory Integrations > Active Directory.

3. Click ( + ), then select Active Directory Domain.

4. Enter the name of an Active Directory domain that you want to integrate with your JumpCloud tenant. For example, “DC=contoso;DC=com”. 

5. Click Create.
6. Under AD Import, click Install a new Import Agent. This is the AD Import agent installer.

7. After downloading the agent, you’re given your API key and your Org ID. These two values will be required during the Installation Wizard of the Import Agent.

8. Repeat these steps on all write capable DCs in your domain.

To prepare for the AD Import Agent Installation on your DCs

Before you install the Import Agent on your DC, you must first prepare your DCs and your AD domain. We’ve outlined some of the items you’ll need to complete before the installation below: 

1. Determine your Root User Container
2. Create a Security Group for the integration (e.g., “JumpCloud” for single domain environments or “JumpCloud (Domain)” for multi-domain environments).

3. Create a User with Read-Only Delegated Auth with the username of jcimport.

Determine Root User Container

The JumpCloud AD Import agent is designed to integrate with AD’s default ‘Users’ container (CN=Users) which is pre-populated in the AD Users and Computers (ADUC) interface and labeled as “Users” as shown in the following image. (This is a default domain with no custom containers. In this use-case the Root Container is CN=Users;DC=contoso;DC=com)

The installation wizard assumes that this is the Root User container and uses this path in your AD Import agent configuration file. During installation, you’re prompted for the domain components (DC) used in your AD Domain (i.e., DC=contoso;DC=com). The installation wizard uses this base level domain information to construct the following Root user container DN (Distinguished Name).

EXAMPLE: CN=Users;DC=contoso;DC=com

Create the JumpCloud ADI Integration Security Group

A Security Group for the integration must be created within the Root User Container you’ve defined in the previous step. This Security Group is required. Any member of this group will be exported to your JumpCloud tenant.

1. Open the ADUC Menu:
   1. Click the Start button, type “dsa” and click the Active Directory Users and Computers icon.

2. Find your Root User Container
3. Right Click on the Root User Container’s folder and select New > Group.
   1. Ensure the Security Group is a Global Security Group.
   2. Give the Security Group a name that helps identify it as the group used by the integration (e.g., “JumpCloud” for single domain environments, “JumpCloud (Domain)” for multi-domain environments).
   3. Click OK.

Create the AD Import Service Account

After you identify the ‘Root user DN’ that you want to use with your JumpCloud integration, you proceed by creating a new AD-based service account (standard user account) that allows the JumpCloud AD Import agent to manage users and groups.

1. Open the ADUC Menu.
   1. Click the Start button, type “dsa” and click the Active Directory Users and Computers icon.
      
2. Find your Root User Container.
3. Right click on the container and click New > User.

4. Enter the following values for the JumpCloud Import Service Account user:
   1. First Name: JumpCloud
   2. Last Name Import
   3. User logon name: jcimport 

5. Enter a password for the jcimport user and ensure that it is set to Never Expire since this will be a service account for the Import Agent. 
6. Click Save.

Delegate read-only control for the JumpCloud import account

1. Navigate to the Root User Container in ADUC that you have selected, right-click the container and select Delegate Control. This launches the Delegation of Control Wizard.
2. Click Next.
3. Add the JumpCloud Import Agent account to the Delegation of Control Wizard. 

4. Click Next, then select Read all user information.

5. Click Next, then click Finish at the final screen.

To install the AD Import Agent

Once all of the above pre-requirements have been completed, the JumpCloud Import Agent must be installed on all of the write capable DCs within the domain.

1. Browse to where you saved the AD Import installer file on your DC. Right-click the file, then select Run as administrator.
2. The Install Wizard will start and should ask for your AD DN of the domain. Enter the name of your Domain in Distinguished Name format separated by semicolons, then click Next.

3. Enter the jcimport account and password, then click Next. Be sure to use the NetBIOS domain format and not the full DNS name. (For example, contoso\jcimport and the user password)

4. Enter your JumpCloud API Key, then click Next.

5. Enter your JumpCloud Organization ID, then click Next.

6. On Selecting the File Destination, leave the defaults and click Next.

7. Click Install.

8. This will take about 1 to 2 minutes to install. Upon Completion, click Finish. 
9. Select Yes, restart the computer now to reboot your DC.

Once your DC has been restarted, review that the service started by confirming display name: “JumpCloud AD Bridge Agent” ; service name: “adint”; is running in services.msc. If the service fails to start, you can review the agent logs at C:\Windows\Temp\JumpCloud_AD_Integration.log. 

To configure AD Import

Once the AD Import Agent has successfully installed, there are several configuration options that you should implement post-install. We’ll cover the recommended configuration updates as follows: 

• Update LDAPS configuration file
• Modify the Root User Container Used by AD Import
• Additional Advanced Configurations

To change any of the configuration options, start by opening the AD Import Agent configuration file: 

1. Open the following file in a text editor: C:\Program Files\JumpCloud AD Bridge\adint.config.json

To update LDAPS in the AD Import Agent configuration file:

We’re updating our ADI Import and Sync Agents in response to Microsoft’s proposed change to enforce LDAP signing requirements. On February 27, 2020, both of JumpCloud’s AD integration agents have been updated to support Secure LDAP / LDAP over SSL (LDAPS). 

To avoid a service disruption after the AD Integration agents are updated, you need to do the following for each AD DC you’ve integrated with JumpCloud:

2. Make the following config changes:
   1. The ServerIP must be changed to the DC’s FQDN.
   2. SSLPort must be set to 636.
3. Here’s an example config, by default, the Server IP is the local host address of 127.0.0.1. This will need to be changed to the FQDN. For example: dc01.contoso.com.

Modify the Root User Container used by AD Import

If you’re using a different Root user container for managing AD resources with the AD Import agent, follow the steps below to modify the User container location in the agent configuration json file. If your Root User Container is the default CN=Users;DC=company;DC=com, you can skip this section.

1. Verify the full LDAP path for the chosen Root user container you have selected in ADUC:
   1. From the ADUC panel’s View menu, enable Advanced Features. 
   2. Right-click the container and select Properties. 
   3. Select the Attribute Editor tab. 
   4. Select the “distinguishedName” attribute, then click View.

2. In the AD Import Agent configuration file, edit the following reference in the LDAP section of the json output.

3. Enter the “distinguishedName” value in the DN section, leaving the CN=JumpCloud security group reference in place.

4. You must create or relocate the JumpCloud security group to this Root user container and grant delegated control to the service account for AD Import agent integration. The LDAP values noted in this DN specify the explicit path to the location of the JumpCloud security group in your AD environment.
   1. An example of the configuration file that has been changed from the Defaults to match what’s actually the true Root User Container. In the below example config, Contoso’s Root User Container needs to be, CN=JumpCloud;OU=Corporate Users;DC=contoso;DC=com.

Modify the Security Group used by AD Import

You will need to update the security group name in the AD import configuration file to match the name you gave the JumpCloud integration Security Group in the pre-requisites section.

1. Update the security group reference in the DN, CN=JumpCloud, to match the name you gave the JumpCloud integration security group.

Once all configuration changes have been made in the AD Import Agent configuration file, save and restart the service

2. Save the adint.config.json file.
3. Restart the JumpCloud AD Bridge Agent service using the Windows Service Manager.

Additional Advanced Configurations for AD Import

If you’re looking to implement more advanced configurations with AD Import, please see Advanced Configurations for AD Import for information such as: 

• Attribute Mappings
• Suspension and Disablement Actions
• User Expiry Actions
• and more!

To verify AD Import

Once you’ve installed and configured AD Import within your environment, you can easily verify that the JumpCloud AD Import Agent is working. Please ensure the following are present and visible: 

• The JumpCloud AD Import Agent should be shown as green and active within the Admin Portal under Directory Integrations > Active Directory > Domain Integration > Domain Agents tab.

• JumpCloud User Group is now within your JumpCloud tenant. The JumpCloud User Group should have a User Group icon with an AD badge in the User Group Details pane. See the example below:
  • Navigate to User Management > User Groups. You should see the JumpCloud User Group with a Microsoft badge next to it. Click on the User Group to open up its details.
  • When opened, you can see that the User Group does not only have a Microsoft Badge, but is also bound to AD on the Directories tab.

AD Import Next Steps

The next steps for the ADI will depend on the use-case you are looking to implement. 

If your use-case is an asynchronous connection from AD to JumpCloud only, then you may move on to the next article, Using the ADI. 

If you’re wanting a two-way sync between JumpCloud and AD or a one-way sync from JumpCloud to AD, then proceed with the next steps of Installing AD Sync. 

Installing the AD Sync Agent

To import and update user identities, attributes, passwords, and user groups from JumpCloud to AD, you’ll need to additionally install the Sync Agent on your AD domain’s DCs. 

You can download the AD Sync Agent in the JumpCloud Admin Portal from Directory Integrations > Active Directory. Please follow the directions below to properly Install the AD Sync Agent. 

System Requirements

• Supported only on 64-bit Windows Server version (2012, 2016, 2019)
• 15MB disk space
• 10MB RAM

Prerequisites

• Internet connectivity
• You must install the AD Import agent before you install the AD Sync agent.
• Your JumpCloud AD Sync Connect Key provided during agent download.
• We recommend a dedicated Administrator account that is specifically for 3rd party services.
• A standard domain user with the required delegated controls must be present for the AD Sync agent to work properly. These permissions may be added to the existing domain user account setup during AD Import installation or a separate service account may be created for this purpose.

Recommendations 

• We recommend that you install the AD Sync agent on your Primary DC and any DC impacted by extended replication delays. 
• We recommend that you set the password of the service agent used to authorize AD Sync’s access to your directory not to expire.
• If you cannot set the service account password to not expire, then we recommend scheduled maintenance to uninstall and reinstall the AD sync agent with the new password every time it is changed.

Considerations

• The AD Sync agent requires that the AD Import agent be installed and running. 
• The AD Domain and Root User container DN that you entered when you installed the AD Import agent needs to match the Domain and Root User container configured for AD Sync.
• To validate the AD Import agent Root User container DN before you install the AD Sync Agent, see Installing the AD Import Agent: How to modify the Root User container used by AD Import. 
• Each time you install the AD Sync agent, you receive a new Connect Key for that installation. Connect Keys are one-time use keys.
• The AD Sync agent installation does not require a reboot of the DC.
• Managing privileged user accounts, such as Domain Admins in AD, isn’t supported. AD flags privileged accounts with “adminCount=1” in the directory, which results in any inherited permissions granted to the JumpCloud AD agent services to be removed. This prevents JumpCloud from being able to effectively manage those privileged accounts.

To prepare for the AD Sync Agent Installation on your DCs

Before you install the Sync Agent on your DCs, you must first prepare your DCs and your AD domain. We’ve outlined some of the items you’ll need to complete before the installation below: 

• The AD Import should already be configured and operating properly. The AD Import Agent must be installed and running on all DCs before installing the AD Sync Agent. 
• Your Root User Container should already be appropriately configured, if configured differently than the default of: CN=Users;DC=company;DC=com.

• Create a User with Read-Only Delegated Auth with the username of jcsync

To create the AD Sync Service Account

After you identify the Root User Container that you want to use with your JumpCloud integration and completed the installation and configuration of the AD Import Agents, you will proceed by creating a new AD-based service account (standard user account) that allows the JumpCloud AD Sync agent to manage users and groups.

1. Open the ADUC Menu.
   1. Click start button and type “dsa” and click the Active Directory Users and Computers icon.
      

2. Right click on the container and click New > User.

3. Enter the following values for the JumpCloud Import Service Account user:
   1. First Name: JumpCloud
   2. Last Name Sync
   3. User logon name: jcsync 

4. Enter a password for the jcsync user and ensure that it is set to Never Expire since this will be a service account for the Sync Agent.
5. Click Save.

To delegate control for the AD Sync Service Account

1. Navigate to the Root User Container in ADUC that you have selected, right-click the container and select Delegate Control. This launches the Delegation of Control Wizard.
2. Click Next.
3. Add the newly created service account user to the Delegation of Control Wizard. 

4. Click Next, then select the following tasks:
   1. Create, delete, and manage user accounts
   2. Reset user passwords and force password change at next logon
   3. Read all user information
   4. Create, delete, and manage groups
   5. Modify the membership of a group

5. Click Next, then click Finish at the final screen.

To install the AD Sync Agent

The next step once all of the pre-requirements have been completed is to install the JumpCloud Sync Agent on your Primary DC and any DC within the domain impacted by extended replication delays.

1. Download the JumpCloud AD Sync Agent from the Admin Portal. 

2. Once you’ve clicked on the Install a new Sync Agent button, you will be presented with the AD Sync Agent Installation Connect Key. This is the unique key that is required to connect the Sync Agent to your JumpCloud Org and this AD Integration within JumpCloud. You will input this key during the AD Sync Agent install in the steps below. 

3. Browse to where you saved the AD Integration Sync installer file on your DC. Right-click the file, then select Run as administrator.
4. Once the Installer Wizard appears, click Next.

5. On the Destination Folder screen, click Next.

6. On the User Root DN screen, enter in the Root User Container you have configured for the Import Agent. This will be the same value as defined during the install of the AD Import Agent. If you’ve left the default Root User Container, this would be CN=Users;DC=company;DC=com. If you’ve changed this by modifying the Root User Container within the AD Import configuration file, then input that value instead.
   1. In this example, we’ve modified the Root User Container. This modification was covered in the Modifying the Root User Container Used by AD Import section earlier in this document.
      1. Example: OU=Corporate Users;DC=contoso;DC=com.

7. On the LDAP Credentials screen, you will be prompted to type in the AD Sync Agent’s Service Account you’ve created. This should be the jcsync User Account you created in the previous section. Click Next once you’ve entered in the User info and password.

8. The next section will ask for the Connect Key that has been presented to you within the JumpCloud Admin Portal after downloading the AD Sync Agent. Enter in the Connect Key and click Next.

9. Finally, click the Install button to install the AD Sync Agent. This could take up to 3 minutes. 

10. Once completed, you will be presented with the Completed Installation screen. Click Finish to close out the Installation Wizard. 

Congratulations! You’ve installed the AD Sync Agent. Please continue through this document to ensure that the AD Sync Agent is communicating properly and update the configurations where necessary. 

To configure AD Sync

Once the AD Sync Agent has successfully installed there are several configuration options that you should implement post-install. We’ll cover the recommended configuration updates as follows: 

• Update LDAPS configuration file
• Modify the Root User Container Used by AD Sync
• Additional Advanced Configurations

Update LDAPS configuration file

We have updated our ADI Import and Sync Agents in response to Microsoft’s proposed change to enforce LDAP signing requirements. As of February 27, 2020, both of JumpCloud’s AD integration agents have been updated to support Secure LDAP / LDAP over SSL (LDAPS). 

To avoid a service disruption after the AD Integration agents are updated, you need to do the following for each AD DC you’ve installed the AD Sync Agent on:

1. Make the required Sync Agent config changes:
   1. Open Registry Editor by Clicking the Start Button and typing in regedit. Click on the Registry Editor icon.

2. Next, Navigate to the following Registry Folder: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\JumpCloud\AD Sync
3. There should be a Key (looks like a folder) named ldap. If there is not, please create this Key in the registry and name it ldap.
4. Open the ldap Key.
5. Next, right-click in the right hand pane. Select New > String Value.

6. Next, name this key: ssl_address.
7. Then, you’ll need to enter a Value for the key. Double-Click on the newly created ssl_address Key. You will be presented an Edit String menu. Enter in the FQDN of your DC and append :636 at the end of the FQDN address. Click OK to save. Please see the example below.

8. Once you’ve entered it in successfully, your Registry Keys should look like the example below. 

9. You will then need to Restart the JumpCloud AD Integration Sync Agent service within services.msc.

Modify the Root User container used by AD Sync

If you’re using a different Root user container for managing AD resources then you will want to modify or validate the configured Root User container location for the AD Sync agent.

If your AD Integration is currently running, we recommend that you stop both the AD Import and AD Sync agents before you make changes. These changes should coincide with relocating the JumpCloud security group in AD, as well as using the Delegation Wizard to set the associated agent service accounts.

1. Make the required Sync Agent config changes:
   1. Open Registry Editor by Clicking the Start Button and typing in regedit. Click on the Registry Editor icon.

2. Navigate to the following Registry Folder: Computer\HKEY_LOCAL_MACHINE\SOFTWARE\JumpCloud\AD Sync.
3. There should be a Key (looks like a folder) named ldap. If there is not, please create this Key in the registry and name it ldap.
4. Open the ldap Key.

5. You should see a Key labeled user_root_dn. You should also see the value with the targeted Root User Container you specified during install of the AD Sync Agent. If the user_root_dn value does not look correct, you can update it by double-clicking the key and updating the value to match your Root User Container. 
6. Once updated, you need to start the JumpCloud AD integration Sync Agent service within services.msc. 

To verify AD Sync

Once you’ve installed and configured AD Sync within your environment. You can easily verify that the JumpCloud AD Sync Agent is working. Please ensure the following are present and visible: 

• The JumpCloud AD Sync Agent should be shown as green and active within the Admin Portal under Directory Integrations > Active Directory > Domain Integration > Domain Agents tab.

Next Steps

Now that you’ve successfully configured the ADI, the next step is understanding the different workflows on how to use the ADI. We’ll cover how to properly use the AD Import and Sync functionalities from within JumpCloud and AD. 

Please continue reading the next article in this series, Use the Active Directory Integration.
Want additional assistance from JumpCloud? 

If you’re having issues with getting JumpCloud’s ADI working, try the Troubleshooting Guide.

JumpCloud now offers myriad professional services offerings to assist customers with implementing and configuring JumpCloud. If you’re looking for assistance with Migrating from AD, or to integrate AD with JumpCloud, we recommend you reach out to JumpCloud’s Professional Services team on the following page: Professional Services - JumpCloud.