Advanced Configurations for the Active Directory Import 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. 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 the ADI article.

To change default configurations for a domain controller:

1. Go to the JumpCloud folder where the AD Import agent is installed on a domain controller.
2. Open the jcadimportagent.config file. 
3. Edit the configurations in the “MainLoop” section of the file.

The following options are available for configuration:

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

This setting controls the behavior of syncing additional work-related user attributes from AD to JumpCloud.

The value can be either true or false; the default setting is true. When set to true, the additional attributes that import and sync from AD to JumpCloud are: Display Name, Description, JobTitle, Department, Company, Location, EmployeeType, PhoneNumbers, Addresses, and Manager will imported and synced from AD to JumpCloud. a user is deleted from JumpCloud if they are dissociated. When set to false, only First Name, Last Name, Username, and Email attributes import and sync from AD to JumpCloud.

UserDissociationAction

This setting controls the behavior of user dissociations - or what happens when a user is deleted, disabled, or removed from the JumpCloud integration security group in AD.

This can be set to either remove or unbind; the default setting is remove. When set to remove, a user is deleted from JumpCloud if they are dissociated. When set to unbind, a user is unbound from the AD instance, but remains in JumpCloud if they are dissociated, and JumpCloud continues to manage that user’s identity.

UserFieldMapping 

This setting 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

This setting 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. When set to deactivate, existing user accounts are placed into a Pending state after they are taken over from AD. Pending users are directed to reset their passwords in AD to ensure they are in sync between AD and JumpCloud. When set to retain, the user state remains the same for existing user accounts that are taken over from AD. 

UserDisableAction

This setting 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

This setting 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.