Subscribe to Help Center RSS FeedImport Agent
Configuration options are available after you install the Active Directory Integration (ADI) import agent. These configuration options are in a JSON config file named jcadimportagent.config.json. You can find the config options in the file’s "MainLoop" section.
Prerequisites
- The AD Import agent is installed per that section of the Configure ADI article
Changing default configurations for a domain controller
- Go to the JumpCloud folder where the AD Import agent is installed on a domain controller.
- Open the jcadimportagent.config.json file.
- Edit the configurations in the "MainLoop" section of the file.
You’ll need to edit the jcadimportagent.config.json file for every server on which the ADI import agent is installed.
Optional Configurations
This is the amount of time the agent waits before attempting to reconnect to the password filter DLL when there was an error.
We don’t recommend changing this setting without direction from JumpCloud support.
Controls the behavior of syncing additional work-related user attributes from AD to JumpCloud. The value can be true or false; the default is true.
- true (Default): Syncs Display Name, Description, JobTitle, Department, Company, Location, EmployeeType, PhoneNumbers, Addresses, and Manager
- false: No additional attributes are synced. Only the core attributes: First Name, Last Name, Username, and Email
This setting overrides the UserDisableAction configuration if their values are not identical.
Controls the behavior of user dissociations - or what happens when a user is deleted, disabled, or removed from the JumpCloud ADI security group in AD. The value can be remove or unbind; the default is remove.
- remove (Default): the user's JumpCloud account will be deleted.
- unbind: the user's JumpCloud account will remain but will be disconnected from the AD domain within JumpCloud. JumpCloud will continue to manage the user's identity.
Controls the mapping of JumpCloud’s username field from AD on import. This can be set to either map JumpCloud usernames to “sAMAccountName” or “userPrincipalName”. The default setting for all new installations of AD Import is to map the JumpCloud username to “sAMAccountName”.
Controls the behavior of user take over - or what happens when an existing JumpCloud user account is taken over from AD. This can be set to deactivate or retain. The default setting is deactivate.
- deactivate (Default): the password status for the user's JumpCloud account is changed to "Password Pending". These users are directed to reset their passwords in AD to ensure their passwords are in sync between AD and JumpCloud
- retain: the password status for the user's JumpCloud account remains unchanged
Password Reset Required for Existing JumpCloud Users in Two-Way Sync
AD requires a password to be set upon user creation. In a two-way sync deployment, passwords for existing JumpCloud users cannot be synced as part of this process. A system-generated password will be set for these users in AD, which will overwrite the user's existing JumpCloud password on the sync back from AD to JumpCloud. As a result, these users must reset their password in either JumpCloud or AD to regain access regardless of what this setting is.
The UserDissociationAction setting will override this configuration if their values are not identical.
Controls the behavior in JumpCloud when a user is disabled in AD and the behavior in AD when a user is suspended in JumpCloud. Learn about suspending users in JumpCloud.
For this setting to control what happens to a user in JumpCloud after the user is disabled in AD, the user must be a member of the JumpCloud Integration Security Group.
UserDisableAction can be set to the following:
- suspend: when a user is disabled in AD, the corresponding JC user is suspended
- remove: when a user is disabled in AD, the corresponding JumpCloud user is deleted
- unbind: when a user is disabled in AD, the corresponding user is no longer managed externally
About UserDisableAction’s default settings:
- For new installs of the Import agent, the default setting for this option is suspend
- An upgrade of the Import agent retains the UserDisableAction setting
- An upgrade of the Import agent with a value for UserDissociateAction will have UserDisableAction set to the same value
- An upgrade of the Import agent without a value for userDissociateAction will have UserDisableAction set to remove
- The value for userDisableAction takes precedence over the value for UserDissociateAction
Suspend Actions on the Sync Agent
- When an active JumpCloud user with a corresponding AD user is suspended in JumpCloud, the user is disabled in AD. The JumpCloud user remains suspended
- When an active JumpCloud user without a corresponding AD user is suspended, the user is created and then disabled in AD. The user remains suspended in JumpCloud
Suspend Actions on the Import Agent
- When the AD Import agent has no UserDisableAction property, or has UserDisableAction set to suspend, and a user is disabled in AD:
- If a user doesn’t exist in JumpCloud, a user is created in JumpCloud according to current AD Import rules
- If a user exists in JumpCloud: unsuspend the existing or created user if the AD user isn’t disabled
- When the AD Import agent has UserDisableAction set to unbind and a user is disabled in AD:
- If a user doesn’t exist, or isn’t owned by this AD Import agent, a new user isn’t created in JumpCloud
- If a user owned by this AD Import agent exists in JumpCloud, externally managed fields are cleared
- When the AD Import agent has UserDisableAction set to remove and a user is disabled in AD:
- If a user doesn’t exist in JumpCloud, or isn’t owned by this AD Import agent, a user isn’t created in JumpCloud
- If a user owned by this AD Import agent exists in JumpCloud, the user is deleted from JumpCloud
The following tables describe the actions taken in AD and JumpCloud for existing and new users for UserDisableAction settings.
| UserDisableAction Setting | Action in AD | Action in JumpCloud |
|---|---|---|
| suspend | Disabled | Suspend |
| Enabled | Not suspended / active | |
| remove | Disabled | Deleted from JumpCloud |
| Enabled | N/A | |
| unbind | Disabled | Externally managed fields are cleared, user is removed from groups |
| Enabled | N/A |
| UserDisableAction Setting | Action in AD | Action in JumpCloud |
|---|---|---|
| suspend | Disabled | Suspended |
| Enabled | Not suspended / active | |
| remove | Disabled | N/A |
| Enabled | User is created | |
| unbind | Disabled | N/A |
| Enabled | User is created |
Disable Scenarios
The following scenarios describe the UserDisableAction setting you should apply to achieve a desired behavior when a user is disabled in AD.
Import Only
- If you want disabled users to be retained and suspended in JumpCloud, set UserDisableAction to suspend.
- If you want disabled users to be removed from JumpCloud and all associated AD groups and external directories, set UserDisableAction to remove.
- If you want disabled users to be removed from the domain in JumpCloud and all associated AD groups, set UserDisableAction to unbind.
Suspend Scenarios
The following scenarios describe the UserDisableAction setting you should apply to achieve a desired behavior when a user is suspended in JumpCloud.
Sync and Import Agents
- If you want users that are suspended in JumpCloud to remain in JumpCloud with all associated group and directory associations, set UserDisableAction to suspend
- If you want users that are suspended in JumpCloud to be removed from JumpCloud and all associated groups and external directories, set UserDisableAction to remove
- If you want users that are suspended in JumpCloud to be removed from all associated groups and external directories, but remain in JumpCloud, set UserDisableAction to unbind
Controls the behavior in JumpCloud when an AD user’s password expires.
UserExpireAction can be set to the following:
- expire: when an AD user’s password expires, the corresponding JumpCloud user’s password is expired
- maintain: when an AD user’s password expires, the corresponding JumpCloud user’s password remains active
About UserExpireAction’s default settings:
- For new installs of the Import agent, the default setting for this option is expire
- An upgrade of the Import agent retains the UserExpireAction setting, if it is set
- An update of the Import agent without a setting for UserExpireAction sets this option to maintain
Expire actions on the Sync Agent
- If a user’s password expires in JumpCloud, their password expires in AD
Expire Actions on the Import Agent
- When the Import agent has no specified setting for UserExpireAction, or has UserExpireAction set to expire:
- An existing JumpCloud user with an expired password in AD immediately expires in JumpCloud
- JumpCloud’s external_password_expiration_date field is set to the value in AD
- If a user doesn’t exist in JumpCloud and isn’t owned by the AD Import agent, a new user is created in JumpCloud and then expires
- When the AD Import agent has UserExpireAction set to maintain:
- Nothing happens in JumpCloud; the user’s password stays active
- JumpCloud’s external_password_expiration_date field is cleared
- If a user doesn’t exist in JumpCloud and isn’t owned by the AD Import agent, a new user is created in JumpCloud
Sync Agent
Active Directory (AD) Sync provides one-way synchronization of passwords and other attributes from JumpCloud to AD. This agent allows password updates to be written back to AD from the JumpCloud Admin Portal, the JumpCloud User Portal, or any JumpCloud-managed device. Full bidirectional synchronization is facilitated by the use of both the AD Import and AD Sync agents.
Prerequisites
- Domain Controllers are prepared for Active Directory Integration (ADI):
- A JumpCloud ADI group has been created and is located in your designated Root User container in AD. This is needed for full bidirectional synchronization and management. This group is synced to your JumpCloud Administrator Portal and is indicated with an AD Integration icon
- An AD service account (standard domain user account) named "jcimport" has been created and has been granted Read all user information permissions using the Delegation of Control Wizard on the selected Root User container, or inherited from an OU further up in the hierarchy. This user cannot be a domain admin, have the user name of "JumpCloud" or be a member of the above-mentioned JumpCloud ADI security group
- See Configure ADI for this information
- The AD Import agent is installed. See Configure ADI
Recommendations
- We recommend creating a security group named JumpCloud Admins. This group isn’t synced to the JumpCloud Administrator Portal, but is used to identify any accounts that you want to be Global Administrators or Sudo users in JumpCloud. Any user that is a member of this group and also a member of the JumpCloud group will be granted Admin/Sudo privileges on all device associations to which they are bound by default. This function doesn't support members of nested groups
- For full bidirectional synchronization, we recommend that all Users and Groups be synchronized with JumpCloud, live under a single OU (Root User Container) in Active Directory. This can be the default CN=Users container in AD or an alternate custom OU within the directory
- To manage users in different OUs, we recommend that these OUs be located underneath the primary Root User container. Users or groups located in these containers that are made members of the JumpCloud ADI security group allow AD Sync to properly synchronize passwords and attributes associated with those users
- 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 you set the service account you use to authorize AD Sync's access to AD with a password that doesn't expire if your security requirements allow this. If this isn't permissible with your security compliance levels, then we recommend scheduling a maintenance window to reinstall the AD sync agent every time the service account password changes
Considerations
- If you relocate users in AD, you could disrupt password synchronization
- If you remove users or groups from the JumpCloud ADI security group in AD they’re removed from the JumpCloud Admin Portal per the default AD Sync configuration options
- Managing privileged user accounts such as Domain Admins in AD isn't supported, see AdminSDHolder, Protected Groups and Security Descriptor Propagator. Active Directory 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.
- Synchronization runs at approximately 90 second intervals
- If the password of the service account that is used to Authorize AD Sync's access to AD is changed, the AD Sync agent will need to be uninstalled and reinstalled with the updated password
- When using both AD Sync and AD Import agents, password expiration notifications are not sent to the end user or administrator. This can be counterintuitive due to the fact that AD Sync gives JumpCloud control over the user attributes and password
User Attribute Synchronization
JumpCloud AD Sync can manage the following data fields in AD:
- Password
- First Name
- Last Name
- Windows UserAccountControl flag for ACCOUNTDISABLE - this field is used for syncing the JumpCloud account status. Currently, JumpCloud only writes back a suspend status to AD. When a user is suspended in JumpCloud, JumpCloud disables the user in AD through the Sync agent. Learn more about Configure ADI.
- MemberOf - this field is used to track group membership in AD. For this field to be synced, you need to install Sync agent v 2.26.0 or later. Learn how to Configure ADI.
JumpCloud Users are associated with Active Directory Users based on the alignment of the Username and Email fields of users in JumpCloud and Active Directory. See Configure ADI for UserFieldMapping settings configured in the AD Import agent that define the username field of the AD User.
Group Attribute Synchronization
JumpCloud syncs the following data fields with AD Sync for groups:
- Group Name
User and Group Management
To provision users to AD
The JumpCloud ADI security group that’s created during AD Import installation is the primary management group for AD integration. This group is used to define the scope of user management with AD and allows full bidirectional synchronization between AD and JumpCloud.
User Creation
You can create users in JumpCloud and connect them to an AD Domain using AD Sync. You can connect users to an AD Domain from the following places in the Admin Portal:
- User panel Directories tab
- Directories panel User tab
When you connect a user to an AD Domain, JumpCloud determines if a user with the same username exists on the domain. If a user with the same username doesn't exist, JumpCloud creates a user with the JumpCloud username on the AD Domain and generates a random password for the user. If a user with the same username exists on the domain, JumpCloud takes over the account, but doesn't generate a random password for the user.
To add a user to an AD Domain from the Users panel
- Go to USER MANAGEMENT > Users.
- Select a user to view their details.
- Select the Directories tab.
- Select the AD Domain you want to connect the user to.
- Click save user.
To add a user to an AD Domain from the Directories panel
- Go to DIRECTORY INTEGRATIONS > Active Directory.
- Select an AD Domain to view its details.
- Select the Users tab.
- Select a user to connect to the AD Domain.
- Click save.
Group Synchronization: Managing Groups from AD
- Groups added to the JumpCloud ADI security group in AD are replicated to the JumpCloud Admin Portal along with all of the users that are a member of that group. Because JumpCloud doesn’t support nested groups directly, any groups in AD that are nested in another group are traversed recursively and their structure is flattened. Users are made a member of their primary group in JumpCloud and a member of the group in which they’re nested in in AD. For example, in AD, Group1 is a member of the JumpCloud group with members User1, User2 and Group2. Group2 is a member of Group1 and contains members User3 and User4. In JumpCloud, Group2 is mirrored and User3 and User4 are bound. Group 1 is mirrored and User1, User2, User3 and User4 are bound
- To manage group membership from JumpCloud to AD, and assign the memberOf attribute to a user account in AD, the AD bound groups in JumpCloud are required to live under the configured Root User container as configured during AD Sync agent installation with the proper delegated controls and permissions
- Users that only exist in JumpCloud may also be bound to these groups in your JumpCloud Administrator Portal.
- For alternate authoritative scenarios or more details regarding synchronization use cases, see use cases in Get Started: ADI or contact JumpCloud for additional support
Service Details
The agent is registered as a service to start automatically.
- Display name: JumpCloud AD Sync Agent
- Service name: JCADSyncAgent
- Log located at C:\Program Files\JumpCloud\AD Sync\adsync.log
User Experience
Flow for Active Users
An active user is a user in an 'active' user state, has a password, and that password status is 'active'. After an administrator binds an active user to an external directory, the user receives an email telling them the directory they’ve been added to, and to sync their password by logging into their User Portal.
Users That are Bound to More Than One External Directory
They will receive a new email for each individual external directory that they are bound to. The flow for users bound to more than one external directory is the same as for active users.
Flow for New Users
A new user is a user in an 'active' user state with a password status of 'password pending'. After an administrator binds a new user without a password to an external directory, the user receives a Welcome to JumpCloud (activation) email that takes them through how to register their new account. After the user registers their account, creates an account password, and logs in to their User Portal, their password is sent to the directories they’re bound to, and JumpCloud will manage their password.
Integration with Entra Connect
When AD Sync and/or AD Import tools are installed on the Windows Server that also has Entra Connect or Entra Connect cloud sync installed, your JumpCloud tenant can NOT be bound to your Entra ID or Microsoft O365 tenant. If Entra ID Connect is the only AD tool installed on the Windows Server this too will NOT work with an Entra ID tenant bound to a JumpCloud tenant.
When JumpCloud is bound to an Entra ID tenant, password syncing will not correctly propagate from JumpCloud to Entra ID. Additionally, it will cause unintended interference with Microsoft’s Entra ID password policy, which will prevent Microsoft users from resetting their own passwords using Microsoft’s Self Service Password Reset (SSPR) portal. Lastly, there will be two password authorities, (on-prem) Active Directory & JumpCloud, constantly in conflict with one another—trying to write the same changes to Entra ID.
Bearing all of this in mind, you may have Microsoft and JumpCloud AD tools concurrently installed on a Windows Server on the premise JumpCloud is NOT bound to an Entra ID tenant.
If a Microsoft user and/or admin changes their Entra ID user password, the complexity of this password must match the password policy created in your JumpCloud Admin portal for the Entra ID or (on-prem) Active Directory initiated write back to be read and applied to your JumpCloud user’s password.
Lastly, we have confirmed that enabling both ‘Password writeback’ and ‘Sync password hashes’ in Entra Connect & Entra Connect Cloud Sync tools does not prevent our AD Integration tools from updating passwords for user identities managed both in your on-prem AD domain and JumpCloud tenant.
Step 4
In this Article
Learn More