Configure ADI: Manage users, security groups, and passwords in AD

The JumpCloud Active Directory Integration (ADI) enables the syncing of users, groups, and passwords between JumpCloud and on-premise or off-premise AD. As covered in Get Started: Active Directory Integration, the ADI uses two agents: an Import Agent and a Sync Agent that can be installed in three (3) configurations which are based on where you want to manage users, groups, and passwords.

1. Manage users, groups, and passwords in AD.
2. Manage users, groups, and passwords in JumpCloud.
3. Manage users and passwords in either system, or both.

This article provides a step-by-step guide for configuring ADI to manage users, security groups, and passwords in AD. This configuration is typically used when you want to extend AD to the cloud for additional functionality, plan to keep AD as your primary user, group, and password authority, and want minimal changes to your existing AD environment. 

This configuration supports organizations looking to extend AD to the cloud for additional functionality with minimal changes to their existing AD environment.

Important Considerations

• The import agent must be installed on all Domain Controllers.
• Downtime will need to be scheduled because the installation requires a server reboot.
• Changing passwords in JumpCloud is not possible with this use case.
• API tokens are specific to each Admin account. Create a separate account for this integration to prevent the possibility of breaking the ADI connectivity to your JumpCloud organization when an Admin account is deleted.
• Password complexity requirements in AD and JumpCloud should be as closely aligned as possible to avoid passwords being rejected and failing to sync due to not meeting the complexity requirements.
• Groups sync automatically from JumpCloud to AD when one or more sync agents are installed. This sync cannot be disabled.
• Importing privileged user accounts, such as Domain Admins, into JumpCloud from AD isn’t supported.
• We STRONGLY recommend installing and using LDAPS for the ADI. Configuring and using LDAPS on the Domain Controller that the Jumpcloud ADI agents will connect to secures any sensitive information that is exchanged between the Jumpcloud agents and the Domain Controller and protects against malicious users.

Configuration

• Use ADI import agent only.
• Install import agent on all domain controllers (DCs).
• Add users and security groups under the ADI security group in AD.

Use Cases

• Keep AD as the Primary Identity Provider (the source of truth) for user data, passwords, and security groups and provide access to Cloud resources.
• Manage users’ passwords in AD only.
• Extend user access to the Cloud for one or more of the following:
  • Access to SaaS applications using industry standard protocols SAML 2.0, and OIDC, for SSO, and SCIM for provisioning, syncing and deprovisioning. 
  • Access to Cloud RADIUS for Wifi and VPN.
  • LDAP based user auth for NAS drive mappings, networking gear, or logins to things such as kubernetes clusters.
  • User provisioning, syncing, deprovisioning and access control to other Cloud Directories such as M365/ Entra ID and Google Workspace in real-time.
• Add support for a mixed OS device fleet.

Workflow for Managing Users, Groups, and Passwords in AD

AD Import Agent Only – Single Domain Workflow

AD Import Agent Only – Multiple Domain Workflow

When the JumpCloud ADI is configured for AD Import only, the following is the general user identity workflow and expected behavior for any user, group, and password changes after AD Import has been configured. 

1. User identities must be created and managed within AD. 
2. An integration specific Security Group is configured within the root user container or root OU (e.g., “JumpCloud”).

3. To sync user identities from AD to JumpCloud, user identities must be either members of the Security Group created for the integration, or members of a Security Group under that Security Group. 
4. Passwords must be changed within AD. After a password change, the new credential is then pushed to their corresponding JumpCloud user account within 90 seconds via the Import Agent. 
5. User Attribute changes must be made within AD. After any supported user attribute changes (First Name, Last Name, Username, E-mail, Password, User State – Enabled or Disabled), the JumpCloud Import Agent will export these updates to JumpCloud within 90 seconds. 
6. Disabling or Removing user accounts must be done from within AD. After being disabled or removed in AD, the JumpCloud Import Agent will either delete the user account in JumpCloud or leave the user active in JumpCloud and disconnect them from the AD integration instance within 90 seconds. 

System Requirements

• 64-bit Windows Server (versions 2012, 2016, 2019, 2022)
  • Server Core installation is also supported for Windows Server versions 2016, 2019, and 2022. You will need to include the /msiexec parameter when running the agent installer.
• 15MB disk space
• 10MB RAM

Considerations

• When the import agent is installed, users who are synced from AD to JumpCloud will be marked as externally managed by AD. Password management must be managed in AD for these users.
  • If you set a password expiration policy in JumpCloud, these users will not receive password expiration notifications automatically. You can send notifications manually by going to users » select expiring users » resend email. Sending notifications from JumpCloud is not recommended. Users marked as externally managed are restricted from changing their password in JumpCloud, with the exception of the link from the password expiration notification.

• The user attributes that sync are:
  • First Name
  • Last Name
  • Username
  • Email
• Users you wish to import from AD into JumpCloud must have defined <First Name> and <Last Name> attributes, i.e., the first name and last name fields cannot be empty.
• Non-standard ASCII characters are not supported in the Root User DN. 
• Demoting a DC installation to a member server and promoting a member server installation to a DC aren’t supported. The agent(s) must be uninstalled first and then installed on the other type of server.
• A reinstall of the same ADI import agent is treated as an update.
• We recommend rotating the passwords for the jcimport user accounts periodically.
• As of ADI import agent 2.x, the following changes were made:
  • The default location for all agent related installation, configuration, and log files is C:\Program Files\JumpCloud\AD Integration\.
  • All references to AD Bridge changed to AD Import.
  • The jcimport username & password and the API key are stored in the registry instead of the ADI Import Agent configuration file. Both the password and API key are encrypted and the values in the registry are replaced with the encrypted value when the import agent starts.
• The JumpCloud ADI import agent services use TLS for all communication. If no network connectivity exists to JumpCloud, the ADI will fail to sync and will not work properly. 
• 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.

Installation Steps Overview

The main steps you will take to install and configure AD for this use case are:

1. Complete the prerequisite checklist.
2. Determine the Root User Container in AD. 
3. Create the JumpCloud ADI Integration Security Group in AD.
4. Create the AD Import Service Account.
5. Delegate read-only control for the JumpCloud import account.
6. Create an ADI domain instance in JumpCloud.
7. Select your configuration and download the import agent installer.
8. Run the the AD Import Agent installation wizard on all DCs.
9. Reboot each DC.
10. Verify the Import Agent Service started on each DC.
11. Complete post-installation AD import agent configuration on each DC.
12. Verify the AD import.

Prerequisite Checklist

Before installing the ADI import agent, we recommend completing each item in the following checklist before continuing. 

1. Know your AD Domain Admin credentials.
2. Verify you have access to all Domain Controllers (DCs) in the AD domain.
3. Ensure your DCs are running on a JumpCloud supported 64-bit Windows Server version (2012, 2016, 2019, 2022).
4. DCs have networking access to the internet and are able to communicate outbound to console.jumpcoud.com over HTTPS port 443. 
5. Schedule Downtime – installation requires a server reboot! 
6. Create a dedicated Administrator account in JumpCloud that is specifically for the ADI.

7. Generate and securely store the API key for the ADI dedicated Administration account.
8. Verify all users to be synced from AD to JumpCloud have a value for first name and last name in AD.
9. 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.
10. [Recommended] Verify 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. 
11. Review Advanced Configurations for the Active Directory Import Agent to understand the configuration settings available for the import agent and note any default values that need to be changed as part of the installation. 
12. [STRONGLY recommended] Install LDAPS.

Prepare for Installing the Agent

To import and update user identities, attributes, passwords, and user groups from AD into JumpCloud, you'll need to install a JumpCloud AD import agent on your AD domain’s non-DC Domain Member Servers (member servers) or all Domain Controllers (DCs) within your domain.  Complete the steps below to prepare for installing the agents on your servers.

Prepare for the AD Import Agent Installation in AD

Determine the Root User Container in AD

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=example;DC=com).

The import agent 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=example;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=example;DC=com

Create the JumpCloud ADI Integration Security Group in AD

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 by clicking Start, typing dsa and clicking 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.
   • Ensure the Security Group is a Global Security Group.
   • Give the Security Group a name that helps identify it as the group used by the ADI (e.g., “JumpCloud” for single domain environments, “JumpCloud (Domain)” for multi-domain environments).
   • Click OK.

Create the AD Import Service Account

1. Open the ADUC Menu by clicking Start, typing dsa and clicking 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 > User.

4. Enter the following values for the JumpCloud Import Service Account user:
   • First Name: JumpCloud
   • Last Name Import
   • 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.

Install the AD Import Agent

Create an ADI domain instance in JumpCloud

Create a new ADI domain instance in JumpCloud if one does not already exist

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

3. Click ( + Add ADI Domain )
4. Enter the name of an Active Directory domain that you want to integrate with your JumpCloud tenant. For example, “DC=example;DC=com”.

5. Click Save.

Select your configuration

1. Expand the Manage user and passwords in AD section
2. Click the checkbox for This is my use case

Download the agent

1. Click Download Import Agent.

4. After downloading the agent, two values are needed for its installation:
   • Your API key
   • Your Org ID

5. Save the downloaded installer to all AD DCs

Install the AD Import Agent on your DCs

Run the AD Import Agent Installation Wizard on all DCs

Now you are ready to install the JumpCloud AD import agent. The AD 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. 
2. Right-click the file, then select Run as administrator.
3. The Install Wizard will start and prompt you to agree to the C++ license terms and conditions.

4. Select Domain Controller as your Server Type and click Next.

7. Enter the AD Distinguished Name (DN) of the domain and click Next.

8. 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, example\jcimport and the user password).

9. Enter the JumpCloud API Key for the dedicated Admin account created for the ADI, then click Next.

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

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

12. Click Install. The import agent will take about 1 to 2 minutes to install.

13. Select Yes, restart the computer now to reboot your DC and click Finish.

Verify the JumpCloud AD Import Agent Service Started

Once your DC restarted, verify that the service started by confirming display name: “JumpCloud AD Import Agent” ; service name: “JCADImportAgent”; is running in services.msc. If the service fails to start, you can review the agent logs at C:\Program Files\JumpCloud\AD Integration\JumpCloud_AD_Import.log.

Configure AD Import Agent

There are several configuration options that you should implement post-installation of the AD import agent. The recommended configuration updates are: 

• Update LDAPS configuration file.
• Modify the Root User Container Used by AD Import.
• Update the security group name if your environment has multiple domains.

Verify and update default import settings described in Advanced Configurations for AD Import.

Modify the Root User Container used by AD Import

If your Root User Container is the default CN=Users;DC=company;DC=com, you can skip this section.

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. 

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, replace the CN=Users;DC=company;DC=com reference in the LDAP section of the json configuration file with the “distinguishedName” value from ADUC, leaving the CN=JumpCloud security group reference in place. See the example below:

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, Example’s Root User Container needs to be, CN=JumpCloud;OU=Corporate Users;DC=example;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 Create the JumpCloud ADI Integration Security Group in AD above.

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

Modify default Advanced Configuration settings for AD Import

Adjust the default configuration settings to control how the import works and what happens to users in JumpCloud when certain actions are taken in AD. These settings are considered advanced configurations. See Advanced Configurations for AD Import for more information.

Save the configuration changes and restart the AD import agent service

Once all configuration changes have been made save them and restart the service.

1. Save the jcadimportagent.config.json file.
2. Restart the JumpCloud AD Import Agent service using the Windows Service Manager.

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 organization. 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 has a Microsoft Badge and is also assigned to AD on the Directories tab.

Next Steps

Please read the Using and Managing the ADI article next.

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.