Get Started with the Active Directory Integration

JumpCloud is an open directory platform that allows admins to manage and secure user identities across multiple protocols, devices, and resources. JumpCloud can integrate with Active Directory (AD) using the Active Directory Integration (ADI). There are multiple variations for configuring AD and JumpCloud, depending on your company’s needs and objectives. 

This article presents the different workflows and frameworks for leveraging the ADI and JumpCloud based on your goals, environmental scenario and architecture in AD.

Prerequisites

Before getting started with the ADI, JumpCloud recommends going through this list and ensuring all items have been marked complete before continuing. 

  • Domain Admin credentials.
  • Access to all Domain Controllers (DCs) in your AD domain. 
  • DCs are running on a JumpCloud supported 64-bit Windows Server version (2012, 2016, 2019).

Note:

Windows Server 2022 coming soon. Most functionality has been validated.

  • DCs have networking access to the internet and are able to communicate outbound (only) to console.jumpcloud.com over HTTPS port 443. The JumpCloud AD Import and Sync Agent services use SSL/TLS for all communication. If no network connectivity exists to JumpCloud, the ADI will fail to sync and not work properly. 
  • JumpCloud Organization for your company.
  • JumpCloud Admin account.

JumpCloud Terminology & Glossary

Active Directory Integration (ADI)

The full integration between JumpCloud and AD. This is comprised of both the JumpCloud Import and Sync Agents. There are several options to configure the integrations as shown in the diagram below.

Import Agent

 JumpCloud’s lightweight agent that runs on all the DCs within an AD environment that imports user identities, passwords and certain security groups to JumpCloud from AD. This agent pushes or sends all user, password, and group changes that have occurred in AD since the last sync to JumpCloud from the DC(s) every 90 seconds.

Note:

There may be references to an older term, AD Bridge Agent, in some configurations and logs.

Sync Agent

JumpCloud’s lightweight agent that runs on one or more Domain Controllers (DCs) within an AD environment that pulls user identities, passwords, and user groups from JumpCloud to AD. This agent communicates to JumpCloud from the DC(s) every 90 seconds to get all changes that have occurred since the last sync, for any users and user groups connected to the ADI in JumpCloud.

Primary Identity Provider (IdP)

The directory will be considered as the source-of-truth or the primary or authoritative directory for credentials and user identities.

Forest

A stand–alone instance of AD that contains a collection of one or more domains and acts as the security boundary within an AD environment.

Domain

A single AD domain within a forest that contains a collection of users, security groups, and other AD objects that share a domain name.

Multiple/Sub Domains

Two or more AD domains within a single forest. 

Organizational Unit (OU)

Containers of objects within AD's logical structure in which security groups and users reside and can be nested. OUs are important within the ADI configuration as they are the search base used by the JumpCloud Import and Sync Agents. 

Security Group

User Groups within AD. They can be nested.

JumpCloud ADI Security Group

The Security Group created by you during the ADI Import installation process and used by the JumpCloud Import Agent to determine which users and groups to sync from AD to JumpCloud. This Security Group will be created in the Configuration article’s instructions. This is the primary group used for which all members are synced between AD and JumpCloud.

Root User Container

The main container or path for which all of your target users you’d like to integrate with JumpCloud reside. This can be a top-level OU, a sub-level OU, or the default “Users” container within JumpCloud. JumpCloud’s ADI is configured to reference this as the Root User Container for which all users integrated with JumpCloud should reside. The AD Import and Sync agents use this Root User Container as a search base by default. If users are outside of the root User container, or its sub-level OUs, but are bound to the “JumpCloud” Security Group, then user identity or credential issues may arise between JumpCloud and AD.

ADI Use Cases

JumpCloud’s ADI can be configured in a few different ways. In this article, we will cover the best practices and configurations for the following primary use cases. When integrating a domain(s) with JumpCloud, select a use case configuration from the below table and then proceed to the section covering your selected configuration and initial setup of ADI within your environment.

Use Case Workflow Configuration Install JumpCloud AD Import Agent on DCs Install JumpCloud AD Sync Agent on DCs Add users and security groups under the integration security group in AD Active Directory Migration Utility (ADMU)
AD as Primary IdP - extend AD to the Cloud and manage mixed OS device fleets User identities and passwords are managed solely in AD. Use import agent only
Flexible two-way sync between AD and JumpCloud User identities and passwords can be managed in either AD or JumpCloud Use both import and sync agents
JumpCloud as Primary IdP - extend AD to the Cloud and manage mixed OS device fleets User identities and passwords are managed solely in JumpCloud Install both import and sync agents but only use sync agent
Migrating device management from AD to JumpCloud Devices are managed solely in JumpCloud

AD as Primary IdP – Using the AD Import Agent Only

If your company is looking to extend your AD's user identities to the cloud or manage an environment mixed with Mac/Linux devices, this configuration allows AD to remain the primary IdP. Users that are imported to JumpCloud, are marked as externally managed and their passwords must be changed within AD.

Important:

Changing passwords in JumpCloud is not possible with this use case.

This use case is best used when: 

  • You plan to keep AD as the Primary IdP for your organization.
  • You do not want to manage users’ passwords in JumpCloud.
  • You are looking to extend AD user identities to the cloud and non-Windows devices. 

AD Import OnlySingle Domain Workflow

AD Import OnlyMultiple Domain Workflow

Import Only Workflow of User Identities and Credentials

When the JumpCloud ADI is configured for AD Import only, the following method is the general user identity workflow for any changes or passwords in this configuration. The below workflow is the expected behavior 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”).

Note:

In multi-domain environments, the security group must have a unique name within each domain (e.g., “JumpCloud (mydomain1)” and “JumpCloud (mydomain2)”)

  1. 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. 
  2. 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. 
  3. 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. 
  4. 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. 

Tip:

The behavior is controlled by the UserDissociationAction setting in the AD import configuration file. The default setting is remove, which deletes the user account.

Configurations Necessary for AD Import Only Workflow

For this use case and scenario, you will need to configure the following Agents and items within the ADI: 

  • JumpCloud’s AD Import Agent.
  • Security Group for the JumpCloud AD Integration.

Two-way Sync Between AD and JumpCloud – Using Both the AD Import and AD Sync Agents

If your company is looking to create a synchronous relationship between your AD’s user identities and JumpCloud user accounts, this configuration allows AD or JumpCloud to manage user credentials and attributes together in unison. Users are able to change passwords within either AD or JumpCloud.

This use case is best used when: 

  • You want users to be able to change passwords in either JumpCloud or JumpCloud managed devices and within AAD.
  • You are looking to extend user identities to cloud resources and non-AD bound devices. 
  • JumpCloud and AD share responsibility over the user identities.

Two-way SyncSingle Domain Workflow

Two-way SyncMultiple Domain Workflow

Two-way Sync Workflow of User Identities and Credentials

When the JumpCloud ADI is configured for AD Import and AD Sync, the following method is the user identity workflow for any changes or passwords in this configuration. The below workflow is the expected behavior after AD Import and Sync agents have been configured.

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

Note:

In multi-domain environments, the security group must have a unique name within each domain (e.g., “JumpCloud (mydomain1)” and “JumpCloud (mydomain2)”).

  1. To sync user identities from AD to JumpCloud, user identities must be either members of the JumpCloud ADI Security Group directly, or members of another Security Group that is a member of the JumpCloud ADI Security Group. 
  2. To sync user identities from JumpCloud to AD, users must be connected directly to the ADI in JumpCloud or members of one or more user groups connected to the integration.
  3. Passwords can be changed within AD, or JumpCloud, or JumpCloud-bound devices. After a password change, the new credential is then pushed to their corresponding directory user account within 90 seconds via the Import Agent or Sync Agent. 
  4. User Attribute changes can be updated within AD or JumpCloud. After any user attribute changes (i.e., First Name, Last Name, Username, E-mail, and Password), the JumpCloud Import or Sync Agent will sync these updates to the corresponding directory within 90 seconds. 
  5. Disabling or removing user Accounts will be dependent on the outcome needed and the UserDissociationAction setting in the AD import configuration file. The JumpCloud Import or Sync Agent will update the user-state for their correlating directory’s user account within 90 seconds.

Configurations Necessary for Two-way Sync Workflow

For this use case and scenario, you will need to configure the following Agents and items within the ADI: 

  • JumpCloud’s AD Import Agent.
  • JumpCloud’s AD Sync Agent.
  • Security Group for the JumpCloud AD Integration.

JumpCloud as Primary IdP – Using the AD Sync Agent Only

If your company is looking to extend your AD to cloud resources or non-AD bound resources, like Mac or Linux devices, and perform all user and password management from JumpCloud. This integration allows JumpCloud to be the primary IdP. 

This use case is best used when: 

  • JumpCloud is the sole authority for user identities and passwords. 
  • You want users to only change passwords from JumpCloud or JumpCloud managed devices 
  • You are looking to extend AD user identities to the cloud and non-Windows devices.
  • You want to reduce the role of AD in your environment OR you are in the final phase of your migration away from AD.

AD Sync Only – Single Domain Workflow

AD Sync OnlyMultiple Domain Workflow

AD Sync Only Workflow of User Identities and Credentials

When the JumpCloud ADI is configured for AD Sync only, the following method is the general user identity workflow for any changes or passwords in this configuration. The below workflow is the expected behavior after AD Import and Sync agents have been configured. 

  1. User identities can be created and managed within JumpCloud only.
  2. Users must be connected directly to the ADI in JumpCloud or members of one or more user groups connected to the integration.
  3. Passwords must be changed within JumpCloud. After a password change, the new password is pushed to AD via the Sync Agent immediately.
  4. User Attribute changes must be done within JumpCloud. After any supported user attribute changes (First Name, Last Name, Username, E-mail, Password, User State – Enabled or Disabled), the JumpCloud Sync Agent will export these updates to AD immediately. 
  5. Disabling User Accounts will be done by suspending users that are connected to the AD integration in JumpCloud. The JumpCloud Sync Agent will immediately disable the user in AD.
  6. Removing user accounts must be done manually in AD. 

Configurations Necessary for AD Sync Only Workflow

For this use case and scenario, you will need to configure the following Agents and items within the ADI: 

  • JumpCloud’s AD Import Agent.
  • JumpCloud’s AD Sync Agent.
  • Security Group for the JumpCloud AD Integration but do not add users or security groups to this Security Group.

Migration from AD

If your company is looking to migrate off of your AD domain to JumpCloud, we recommend you leverage our Active Directory Migration Utility (ADMU) to migrate Windows devices from AD-bound to JumpCloud-managed. 

There are several ways to get users into JumpCloud. For example, you do not have to use the ADI to get user identities into JumpCloud. You can import users from M365, Google Workspaces, CSV, or by manually creating users. If you’re looking to migrate user identities off of AD and into JumpCloud, and your company is going to migrate off of AD in phases, it is recommended to implement JumpCloud’s ADI and the ADMU. 

This process does not require the ADI and will not be covered in depth within this article. See more information on this tool and process below.

This use case is best used when: 

  • You are wanting to convert AD-bound Windows devices to JumpCloud Managed.
  • You are ultimately looking to migrate entirely off of AD.
  • You want JumpCloud to become the Primary IdP for all user identities.

To learn more on how to leverage the ADMU, please see our GitHub Wiki Page: JumpCloud ADMU for how to run the ADMU either locally on the device or remotely using JumpCloud Commands.

Want JumpCloud to do the AD Migration for you?

JumpCloud’s Professional Services team has service offerings dedicated to migrating away from AD and into JumpCloud. If you decide to elect and purchase this professional service, JumpCloud’s Professional Service Engineers will execute the migration for you. If interested we recommend reaching out on the following page: Professional Services - JumpCloud

Migration Workflow of User Identities and Credentials

When the ADMU is leveraged to migrate AD-bound devices to JumpCloud, the following method is the general workflow.

  1. User identities can be imported in any of the following methods: Microsoft365, Google Workspace, JumpCloud ADI, CSV Import, or Manually created.
  2. ADMU tool is run on the AD-bound Windows Device. This will convert the AD-bound device to a local WORKGROUP and an AD user Account to a local user account. 
  3. You would then bind the user to the newly added JumpCloud Device.

Ready to Configure?
Please check out the next article in this document series, Configure the ADI, based on the use case you’re wanting to implement within your AD Domain and environment. 

Want additional assistance from JumpCloud? 
If you’re having issues with getting JumpCloud’s ADI working, try the Troubleshoot: ADI.

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.

Still Have Questions?

If you cannot find an answer to your question in our FAQ, you can always contact us.

Submit a Case