PasswordChangeListener – PollTimeMillis

This is the amount of time the agent waits before attempting to reconnect to the password filter DLL when there was an error. 

SyncAdditionalAttributes

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

UserDissociationAction

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.

UserFieldMapping

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”.

UserTakeoverAction

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

UserDisableAction

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.

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

UserExpireAction

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

SyncAccountLockedOutStatus

This setting enables the JumpCloud AD Import Agent to detect when a user's account is locked AD such as, after too many incorrect login attempts in AD. When enabled, this "locked" status from AD is then synced and reflected on the corresponding user's account in JumpCloud.

Allowed values

• true:  If an ADI-connected account is detected as locked, the corresponding JumpCloud user account will also be updated to reflect a locked status. 
• false (Default): The locked status of an AD account is not synced to JumpCloud. Even if a user's AD account becomes locked, their JumpCloud user account status will remain unchanged.

Key Considerations

• Matching settings between import and sync agent: If ADI is deployed in a two-way sync, it is recommended that the value for this setting match in both configuration files. 
• Visibility into AD Lockouts: Setting this to true gives you visibility within JumpCloud when an integrated user's AD account is locked, which can help in diagnosing access problems.
• Effect on JumpCloud Access: If a JumpCloud user account is marked as locked because its AD counterpart is locked (due to this setting being true), this may impact the user's access to JumpCloud-managed resources.
• Unlocking Procedure: If an account is locked in AD and this status is synced to JumpCloud:
  • If ADI is deployed in a one-way AD to JumpCloud sync, the primary action to unlock the account should typically be taken directly in Active Directory.

If ADI is deployed in a two-way sync AD, the account can be unlocked in either JumpCloud or AD. We recommend setting the value to true in the ADI sync agent setting to avoid any unintended unlocks.

sync_group

This setting lets you choose an existing Active Directory (AD) group to act as a central "parent" group. Any new AD security groups that JumpCloud creates through the integration will be neatly organized as sub-groups under this designated parent group. This helps you easily identify all JumpCloud-managed AD groups and keep them organized in one main location within your AD structure.

Allowed values

• The Distinguished Name (DN) of the security group.
  • Default Settings: Default values are used for the new configuration settings if they are not present in the config file, ensuring continuous operation.

Key Considerations

• Group Must Exist: You must create this security group in AD yourself before you start using the integration. The sync agent will not create this parent group for you.
• Group Organization vs. Storage Location: This setting is about how new groups are organized or nested under a parent group. It does not change the main storage location (the  Organizational Unit or OU, referred to as the "User Root DN") where the actual user and the group objects are created in AD.
  • Note: That primary storage location, the “User Root DN” is defined during your initial sync agent setup.
• Deletion Guard: The security group you designate for this setting is automatically protected; it cannot be deleted by the sync agent. This safeguard ensures the stability of your group organization and the overall integration.
• Interaction with group_membership_sync_type: 
  • Changes that could impact syncing behavior: The group specified for this setting is considered the root group for group nesting. If this parent group is changed to be one of the children of the original parent security group the following will occur:
    • New memberships will continue to sync from JumpCloud to AD but the sync will become a match sync type regardless of the setting for group_membership_sync_type.  
    • Membership removals in the former parent security group cannot be performed even if the user_disconnection_action is set to remove. 

user_disconnection_action

This setting determines what happens to a user's Active Directory (AD) account when that user is either deleted from JumpCloud while still connected to ADI or when they are completely disconnected (all direct and indirect connections are removed) from ADI in the JumpCloud admin portal.

Allowed values

• remove: The user's AD account is permanently deleted.
• disable (Default): The user's AD account is disabled (but remains in AD).
• retain: The user's AD account is left active in AD and 

Key Considerations

• Offboarding and Security:Think about your organization's offboarding procedures and security policies when choosing a value for this setting. For example, disable or remove might be preferred for security reasons, while retain might be used in specific temporary disconnection scenarios.
• Group Disconnection Impact on Users: Be aware that if a user's only connection to the AD Integration is through their membership in a specific group (an indirect connection), disconnecting that group from the AD Integration in JumpCloud will also effectively disconnect the user. This, in turn, will trigger this setting as well as the group_disconnection_action setting.

membership_disconnection

This setting controls what happens to a user's memberships in JumpCloud-managed AD security groups. This action takes effect when a user is deleted or completely disconnected from ADI in  the JumpCloud admin portal.

Allowed values

• remove (Default): The user is removed from all AD security groups that were being managed for them by JumpCloud.
• retain: The user remains a member of the AD security groups that were being managed for them by JumpCloud (their memberships are unchanged in AD).

Key Considerations

• Impact on Access Rights:
  • Choosing remove helps ensure that a disconnected user immediately loses access previously granted through JumpCloud-managed AD groups.
  • Selecting retain means the user keeps these specific group memberships. Any future changes to this access would then need to be managed directly in AD.
• Interaction with user_disconnection_action: This setting works together with  user_disconnection_action (which determines what happens to the user's AD account itself). Consider how these two settings combine to meet your organization's offboarding and security policies. For instance, you might choose to retain a user's AD account (using user_disconnection_action:retain) but remove their memberships from JumpCloud-managed groups (using membership_disconnection: remove).

group_disconnection_action

This setting controls what happens to a JumpCloud-managed AD security group if it is disconnected from ADI in the JumpCloud admin portal.  

Allowed values

• remove: The security group is permanently deleted in AD.
• retain (Default): The security group remains in AD, and its existing memberships are unchanged. It will no longer be managed or updated by the sync agent. (any future modifications must be made directly in AD).

Key Considerations

• sync_group Protection: This setting does not apply to the AD security group you have set in the sync_group configuration setting. That specific group is protected and will not be deleted by this action, even if remove is selected here.
• Consider Group Usage:
  • Before choosing remove, consider the access these groups provide and the implications of that access being removed automatically. 
  • If you select retain, be prepared to manage the group and its memberships manually within Active Directory from that point forward.
• Interaction with user_disconnection_action: An action that triggers this setting can also trigger the user_disconnection_action if a user's only connection to the AD Integration is through their membership in the group that was disconnected  (an indirect connection).

SyncAccountLockedOutStatus

This setting gives you precise control over when an unlock action syncs to a user’s  AD account. Its main purpose is to prevent accidental unlocks in AD that might have previously occurred due to general user updates synced from JumpCloud.

Allowed values

• true:  The user's AD account will be unlocked by the sync agent only if their JumpCloud account is specifically unlocked. This offers more deliberate control over the AD account's locked status. 
• false (Default): The user's AD account may be unlocked by the sync agent whenever any user attribute update is synced from their JumpCloud account. (This reflects the behavior before this more granular control was available.)

Key Considerations

• AD Lock Behavior: Active Directory typically locks accounts due to incorrect password attempts and doesn't allow external applications to programmatically "lock" an account. Therefore, this setting focuses on how JumpCloud initiates an unlock in AD.
• Preventing Unintended Unlocks: Setting this to true is recommended to ensure AD accounts are only unlocked intentionally (by an unlock action in JumpCloud, rather than as a side effect of other profile changes).

group_membership_sync_type

This setting defines how JumpCloud manages a user's membership in AD when there is an AD nested group structure (groups within groups). 

Allowed values

• minimal (Inheritance):
  • Users are added only to the most specific (leaf) AD group in a nested structure. Any membership in parent groups is then handled by AD's standard inheritance.
  • Default setting for: Two-way AD sync deployments.
• match (Mirroring):
  • Users are added to all AD security groups in the nested structure, creating an exact match of their JumpCloud group memberships within AD.
  • Default setting for: One-way JumpCloud-to-AD sync deployments.

Key Considerations

• How it Works (Example): Imagine an AD structure where "ChildGroup" is a member of "ParentGroup." A user needs to be in "ChildGroup."
  • With minimal: JumpCloud makes the user a member of "ChildGroup" in AD. AD's inheritance then automatically makes them appear as a member of "ParentGroup."
  • With match: JumpCloud directly makes the user a member of "ChildGroup" AND also directly a member of "ParentGroup" in AD.
• Interaction if sync_group is Changed to a Former Sub-Group:
  • There's a specific behavior if you change your main sync_group (the AD group organizing all JumpCloud-synced groups) to a new AD group that was previously nested under the old sync_group.
  • In this complex scenario, users previously associated with the old sync_group structure will have their memberships synced to that previous parent using a match behavior, regardless of the current group_membership_sync_type setting.

Recommendation: Due to the nuanced nature of this interaction, if you're planning such a specific sync_group reconfiguration, it's advisable to consult with JumpCloud support to ensure a predictable outcome.

Configuration Settings Outcomes in a Two-way Sync

The sections below provide a summary of what happens when changes are made in either JumpCloud or AD based on the value of the configuration settings. 

Sync Unlock Status

SyncAccountLockedOutStatus setting plays a crucial role in how account lockouts are handled between JumpCloud (JC) and Active Directory (AD). Since changes can originate in either directory, we'll look at JumpCloud-initiated changes and AD-initiated changes separately

The tables describing AD-initiated changes will assume that the SyncAccountLockedOutStatus setting is configured with the same value for both the AD Import Agent (AD to JC sync) and the AD Sync Agent (JC to AD sync).

Scenario 1: JumpCloud-Initiated Changes & Lock/Unlock Behavior (2-Way Sync)
This table describes what happens when an action is taken in JumpCloud that affects a user's locked status, focusing on how the SyncAccountLockedOutStatus setting on the Sync Agent influences the user's state in Active Directory.

Scenario Context: The AD account's initial locked status may have occurred due to AD's internal mechanisms. The JumpCloud account may or may not reflect this AD lock, depending on the SyncAccountLockedOutStatus setting for the Import Agent.

Key Points for JC-Initiated Changes:

• If the Sync Agent's SyncAccountLockedOutStatus is true, only an explicit "unlock" action in JumpCloud will unlock the AD account. Other profile updates from JumpCloud will not affect an AD-locked account.
• If the Sync Agent's SyncAccountLockedOutStatus is false (Default), any user update synced from JumpCloud to an AD-locked account may result in the AD account being unlocked.

AD-Initiated Changes & Lock/Unlock Behavior (2-Way Sync)

This table describes what happens when a user's account is locked or unlocked directly in Active Directory, and how these changes are reflected in both AD and JumpCloud. This assumes the SyncAccountLockedOutStatus setting is matched for both the Import Agent (AD to JC) and the Sync Agent (JC to AD).

Scenario 2.1: Recommended Configuration: SyncAccountLockedOutStatus = true (for both Import & Sync Agents)

Scenario 2.2: Default Configuration: SyncAccountLockedOutStatus = false (for both Import & Sync Agents)

Key Considerations for 2-Way Sync:

• Matching Settings: As highlighted in your provided notes, for consistent behavior in a 2-way sync, it's recommended that the SyncAccountLockedOutStatus value is the same for both the Import Agent and the Sync Agent configuration files.
• true for Predictable Unlocks: Setting SyncAccountLockedOutStatus to true for both agents provides the most predictable and deliberate control over account unlocks, preventing unintended unlocks in AD from general JumpCloud updates and ensuring lock status consistency between AD and JumpCloud.

User End States Based on Disconnection Settings 

The scenarios and tables below shows the end state of a user's account and their memberships after a disconnection or disablement action in either JumpCloud or AD. The scenarios are not exhaustive. They focus on the most direct outcomes and illustrate how the settings can interact.
 
Part 1: JumpCloud-Initiated User Disconnection (2-Way Sync)
This table outlines what happens when a user is explicitly disconnected from the AD Integration service by an action taken within JumpCloud. This could be an administrator unbinding the user from the AD Integration service in the JumpCloud portal, or a synced JumpCloud user being deleted. The Sync Agent settings (user_disconnection_action, membership_disconnection) dictate the outcome in AD.

Triggering Event from JumpCloud:

• User is disconnected from AD Integration by an admin in the JumpCloud portal.
• A synced JumpCloud user account is deleted by an admin in the JumpCloud portal.
• A user's only connection to AD Integration (an indirect connection via a group) is severed because that group is disconnected from AD Integration in JumpCloud.

Part 2: AD-Initiated Changes & Typical 2-Way Sync Impact
This section describes common changes initiated directly within Active Directory that affect a synced user's status or their inclusion in the synchronization scope. The end state in JumpCloud is primarily governed by the AD Import Agent settings (like UserDissociationAction and UserDisableAction). The Sync Agent's user_disconnection_action and membership_disconnection settings have limited direct impact on the initial reaction in JumpCloud or on AD objects that AD itself has already modified or removed from scope.

¹Note on AD-Initiated Changes & Import Agent Settings:
The exact behavior and end state of the JumpCloud user account following an AD-initiated change depend heavily on your specific AD Import Agent settings (UserDissociationAction, UserDisableAction) and overall 2-way synchronization policies configured for your JumpCloud tenant.

• UserDissociationAction (Import Agent): Controls if a JC user is deleted or just disconnected when the AD user is deleted or removed from sync scope.
• UserDisableAction (Import Agent): Controls if a JC user is suspended, deleted, or disconnected when the AD user is disabled. (Note the override behavior mentioned with UserDissociationAction).

The Sync Agent settings (user_disconnection_action, membership_disconnection) come into play primarily when JumpCloud initiates the disconnection or when it processes a state that it interprets as a need to enforce a disconnection policy on the AD side for an object it still considers within its management purview.

This detailed breakdown should help clarify how these settings operate in various 2-way sync scenarios, highlighting which set of agent settings is most influential for different types of change.

Configuration Settings Outcomes in a JumpCloud to AD One-way Sync

The sections below provide a summary of what happens in AD when changes are made in JumpCloud based on the value of the new sync agent configuration settings. 

Sync Unlock Status

The table below illustrates the behavior when a user's AD account is currently locked, and actions are taken in JumpCloud for that user (assuming the JumpCloud user account itself is active or being actively unlocked by an admin):

User End States in AD Based on Disconnection Settings 

This table shows the end state of a user's account and their memberships in JumpCloud-managed groups within Active Directory (AD) when they are disconnected from the JumpCloud AD Integration. This applies to a one-way JumpCloud to AD sync environment and depends on the combination of the user_disconnection_action and membership_disconnection settings in your ADI sync agent configuration.

Triggering Event for an AD User: User is disconnected from the JumpCloud AD Integration. This occurs if:

• The user is deleted in JumpCloud.
• The user is explicitly unbound from the AD Integration service in their JumpCloud account.
• The user's only link to AD Integration was via a group, and that group is disconnected from AD Integration.

The results shown below assume all nested groups are nested under the Security Group (SG) specified as the sync_group in the sync agent configuration file. 

User and User Membership Disconnection Settings 

Important considerations: 

• If the sync_group is changed to be one of the child groups of the previously defined sync_group, the following will occur:
  • The users will continue to sync to the parent group(s) of the new sync_group, but they will sync in a match type, regardless of the group_membership_sync_type setting. 
  • Users will not be removed from the parent group(s) regardless of the membership_disconnection_action setting. 
• Automatic Default Settings: Default values are used for the new configuration settings if they are not present in the config file, ensuring continuous operation. 
• Sync Group Deletion Guard: The group defined as the sync_group in the sync agent configuration file cannot be deleted by the integration. If actions in JumpCloud cause such a request to be made, the action is not performed and an error is logged. 
• Groups Shared Across Multiple Domain

Group Membership Sync Type Settings 

Important considerations: 

• Minimal group sync type is the current sync type for ADI