1. Code42 Support
  2. Incydr
  3. Incydr administration
  4. Monitoring and managing
  5. Code42 User Directory Sync resources

Configure Code42 User Directory Sync

Updated

Overview

Code42 User Directory Sync allows you to automatically manage users in your cloud Code42 environment. Once configured, it connects your directory service (for example, Active Directory) to your Code42 environment and automatically creates users, updates their organization and role assignments, and deactivates users in Code42 based on changes made within your directory service. 

This article explains how to install the Code42 User Directory Sync tool to a dedicated host server and how to configure Code42 User Directory Sync in the Code42 console.

Alternatively, if you use a SCIM provisioning provider, we suggest configuring your provisioning provider to manage users. See How to configure SCIM provisioning. If Okta is your provisioning provider, see How to provision users to Code42 from Okta.

Considerations

  • To perform these steps, you must be authorized to access and manage the directory service used at your company (for example, Active Directory).
  • Code42 User Directory Sync is only available for customers in the Code42 cloud.
    • New Code42 cloud environments: Code42 User Directory Sync is configured as part of your implementation. 
    • Existing Code42 cloud environments: Your Professional Services contact provides you with a link to download the Code42 User Directory Sync installation file. Contact your Customer Success Manager (CSM) to learn more. 
  • The Code42 User Directory Sync tool:
    • Runs on a dedicated host computer or virtual machine. Run it on a different host computer than your directory service.
    • Is supported for use with Microsoft Active Directory versions 2003 through 2019.
    • Is packaged with a stand-alone Java Runtime Environment (JRE) and is updated with future releases of the tool. The tool can be configured to use a system JRE if needed. 
  • If you need help with Code42 User Directory Sync, contact your Customer Success Manager (CSM) to engage the Professional Services team.

Password management 

  • Encryption of the LDAP and SCIM passwords on Linux hosts is specific to the machine used to set the password. If moving the Code42 User Directory Sync to a new host, reset the passwords as described in Re-configure LDAP and SCIM passwords below. 
  • Encryption of the LDAP and SCIM passwords on Windows hosts is specific to the user used to set the password. If moving the Code42 User Directory Sync to a new host or running the tool as a different user/service, reset the passwords as described in Re-configure LDAP and SCIM passwords below. 

Before you begin

Obtain the Code42 User Directory Sync tool installation file

As part of this configuration process, you must install the Code42 User Directory Sync tool to a dedicated host computer or virtual machine.

Contact your Customer Success Manager (CSM) to engage the Professional Services team, who in turn will provide you a link to download the Code42 User Directory Sync tool installation file. You will install the tool in Step 2 below.

 

Prepare the host server

The Code42 User Directory Sync tool runs on a dedicated host server computer or virtual machine. Before you install the tool, you must prepare the server.

System requirements

Requirements for the host running Code42 User Directory Sync:

  • Hardware
    • Dual-core CPU or vCPU at 1.8 GHz or better
    • 2 GB RAM or VRAM
    • NIC with 100 Mbps or faster speed
    • More than 20 GB of disk space
  • Operating system
    • Windows
      • Microsoft Windows Server Standard 2012 R2 to 2019 (64-bit)
    • Linux
      • Red Hat Enterprise 6.6 (64-bit) or later
      • Ubuntu 14.04 (64-bit) or later
  • Java runtime environment
    • Java 8u181 (included). Java 9 is unsupported.
      When you install the Code42 User Directory Sync tool, the JRE is extracted into a directory as opposed to fully installed on the operating system, and as a result it runs as an intermittent process, not a service.
The JRE for the Code42 User Directory Sync tool 
The Code42 User Directory Sync tool is packaged with a stand-alone Java Runtime Environment (JRE). This JRE is specific to Code42 User Directory Sync and will be updated with future releases of the tool.
  • Deployment: The JRE is extracted into a directory as opposed to fully installed on the operating system. As a result it will run as an intermittent process, not a service.
  • Patch Management: As this is a bundled JRE, keep this server updated with standard patch management best practices.

Create firewall rules

Create outbound firewall rules on the host server to allow access to your directory services server and the Code42 cloud.

Rule

Destination

Direction

Ports
Directory services server IP address of your directory services server Outbound 389, 636
Code42 cloud IP address of your authority in the Code42 cloud Outbound 443, 4285

Harden the server

Before installing the Code42 User Directory Sync tool to the host computer, implement additional layers of security. See Code42 User Directory Sync server hardening.

Create organizations

When users are provisioned from your directory service to organizations in your Code42 environment using org scripts, Code42 User Directory Sync automatically creates organizations if they don't already exist. Rather than having Code42 User Directory Sync create new organizations for you, create organizations yourself before running synchronization. Having organizations already in place can dramatically improve synchronization performance. 

For instructions about how to create organizations, see Add organizations for user management.

Install Code42 User Directory Sync

Step 1: Add Code42 User Directory Sync in the Code42 console

  1. In the Code42 console, navigate to Administration > Integrations > Identity Management. 
  2. Select the Provisioning tab. 
  3. Click Add Provisioning Provider.
  4. Select Add Code42 User Directory Sync from the dropdown menu.
  5. Enter a username and click Next. 
    The Code42 User Directory Sync Created dialog appears. (This username will also be used as the display name in the Code42 User Directory Sync provisioning provider details.)
  6. Copy the base URL, username, and password to a temporary location.
    You need this information when you install the Code42 User Directory Sync tool in Step 2. 
  7. Only click Done after you have saved the information. 
    User directory sync details

Step 2: Install the Code42 User Directory Sync tool

  1. Ensure you have done the following as described in Before you begin above:
    1. Obtained the Code42 User Directory Sync tool from a download link provided by your Professional Services team representative. 
    2. Set up a dedicated host computer for installation of the Code42 User Directory Sync tool.
  2. Log in to the host computer where you will install the Code42 User Directory Sync tool.
  3. Copy the Code42 User Directory Sync tool installation file to the host computer.
  4. Extract the installation file to the directory on the host computer where you want the Code42 User Directory Sync tool to reside.
  5. Open a command prompt.
  6. Navigate to the \bin folder of the extracted Code42 User Directory Sync tool.
  7. Run the executable c42UserDirectorySync file.
  8. Complete the following prompts to populate configuration properties:
    1. ldap.baseurl – Enter the address of your directory service server with a dedicated port that has firewall access (see Create firewall rules above). Use this format: ldap://<host>:<port>. For example, ldap://ad.example.myco.com:389. Either use port 389 for normal LDAP, or port 636 for Secure LDAP (see Configure Secure LDAP below).
    2. ldap.baseDn – Enter the LDAP base DN to use.
      The format will differ depending on the setup of your directory service. For example, OU=UDS,OU=Users,dc=example,dc=myco,dc=com .
    3. ldap.bind.authtype – Enter the type of authentication binding to use, SIMPLE for basic authentication (see ldap.bind.authtype below) or NONE (anonymous). 
    4. ldap.bind.user – Enter the username of the authorized service account for your directory server (for example, "username", "domain\username", "username@domain.com", or "cn=user,ou =org,dc=myco,dc=com"). 
    5. ldap.bind.password – Enter the password for the authorized user of your directory services (for example, Active Directory user). The password does not appear on screen. Enter it twice when prompted.
    6. scim.baseurl – Enter the base URL from the Code42 User Directory Sync Created dialog in Step 1 above.
    7. scim.username – Enter the username from the Code42 User Directory Sync Created dialog in Step 1 above.
    8. scim.password – Enter the password from the Code42 User Directory Sync Created dialog in Step 1 above. 
      The password does not appear on screen. Enter it twice when prompted.
  9. Press Enter.
    Code42 User Directory Sync saves the configuration to the config.properties file and creates empty active, org, and role scripts in the installation directory. Those scripts are configured in Step 3. The following is an example of the resulting message:
[INFO main] Writing configuration properties to config.properties
[INFO main] Creating new config file: C:\C42UserDirectorySync-<ver>\config.properties
[INFO main] Created default script for SCRIPT_ACTIVE_FILE in file C:\C42UserDirectorySync-<ver>\activescript.js
[INFO main] Created default script for SCRIPT_ORG_FILE in file C:\C42UserDirectorySync-<ver>\orgscript.js
[INFO main] Created default script for SCRIPT_ROLE_FILE in file C:\C42UserDirectorySync-<ver>\rolescript.js

Step 3: Configure scripts

After you complete the initial configuration prompts in Step 2, Code42 User Directory Sync automatically creates basic active, org, and role scripts in the installation directory. The desired location of these scripts can be configured in the config.properties file as described in Configure properties in the config.properties file below.

Configure these scripts with JavaScript functions to provision users to Code42 based on user attributes returned from the search base of your directory service:

  • ActiveScript.js
    Determines when a user is considered active. If the user is new and marked as active, the user is provisioned in Code42.
  • OrgScript.js
    Determines how to assign users to organizations. If a user is provisioned to an organization that doesn't previously exist in Code42, the organization is created and that user is assigned to it. (You should create organizations first to improve synchronization performance.) If a user is provisioned without an organization specified in a script, they will be assigned to the organization defined in the Edit Organization Mapping Method dialog.
  • RoleScript.js
    Determines how a user is assigned roles in Code42 based on information for that user from your directory service. A user can be provisioned with one or more roles. If a user is provisioned without any roles specified, the user is created using the default roles configured for their organization in Code42. Ensure the roles you want to manage with the roles script are allowed for use in the Select Roles dialog as described in Change role mapping below.

For more information about these scripts, see User management with Code42 User Directory Sync. For example scripts, see Example scripts for Code42 User Directory Sync.

If you need help configuring these scripts, contact your Customer Success Manager (CSM) to engage the Professional Services team.

Step 4: Test your configuration

Run the C42UserDirectorySync executable to test your configuration. For more information about the C42UserDirectorySync executable, see Run synchronization for Code42 User Directory Sync.

To test your configuration for the first time:

  1. Open a command prompt on the host computer where Code42 User Directory Sync tool is installed.
  2. Navigate to the \bin folder of the Code42 User Directory Sync tool.
  3. To check the configuration and preview the provisioning results for users, run C42userDirectorySync without any flags.
    If any errors are reported, address the errors before proceeding. For additional commands to run tests, see Commands to test Code42 User Directory Sync below.
  4. To perform a synchronization for the first time between your active directory service and Code42, run  C42UserDirectorySync --sync-now
    The system performs a synchronization between your active directory service and Code42 using the scripts you created in Step 3. If any errors are reported, address the errors before attempting another synchronization. 

After you run the tool with the --sync-now command, review the provisioning changes in the sync log.

Commands to test Code42 User Directory Sync

You can test Code42 User Directory Sync in any of the following ways:

  • C42UserDirectorySync (no flags)
    Executes Code42 User Directory Sync in dry-run mode. This performs a connection check between the LDAP server and the Code42 cloud. It then queries for users that have changed since the last successful synchronization and outputs the username, active, org, and roles that would be provisioned to Code42 during a live incremental synchronization (via --sync-now flag).

  • C42UserDirectorySync --full-sync
    Executes Code42 User Directory Sync in dry-run mode. This performs a connection check between the LDAP server and the Code42 cloud. It then queries for all users in the search base or filter (if using a --filter file) and outputs the username, active, org, and roles that would be provisioned to Code42 during a live full synchronization (using the --sync-now--full-sync flags together).
  • C42UserDirectorySync --debug
    Executes Code42 User Directory Sync in verbose dry-run mode. This mode outputs network results and user details, as well as additional logging detail for each processing step. Can be used with --full-sync for a full synchronization test.
  • C42UserDirectorySync --trace
    Executes Code42 User Directory Sync in dry-run mode which includes all logging information. This should only be used for debugging complicated configuration or run-time problems.
Get help
To see all available flags for the executable, run C42UserDirectorySync -help. For more information about the C42UserDirectorySync executable, see Run synchronization for Code42 User Directory Sync.

Next steps

After Code42 User Directory Sync is configured, run the C42UserDirectorySync --sync-now command when you want to synchronize your active directory service with Code42. For more information, see Run synchronization for Code42 User Directory Sync.

Review the sync log for the provisioning changes that result from the sync.

To schedule the sync to run on a repetitive basis, use a scheduler. When configuring a scheduler on a Windows host, ensure the task is scheduled to run as the same user who set the LDAP and SCIM passwords. 

Use a scheduler such as:

  • Windows Task Scheduler
  • cron job
  • Third-party scheduling tools

Additional configuration

After you install Code42 User Directory Sync, you can configure it to fit your needs.

Change organization mapping and role mapping

In the Code42 console when you click Done in the Code42 User Directory Sync Created dialog in installation Step 1, the Code42 User Directory Sync details display.

The following is set by default:

Change the organization mapping method

By default, users in your directory service (also known as the "provisioning provider") are mapped to Code42 organizations based on the Code42 User Directory Sync org script.

If you want to change the mapping method:

  1. Click the edit button to the right of the Organization Mapping heading.
    The Edit Organization Mapping Method dialog appears.
  2. Select either:
    • Create new users in the organization below and do not map users based on the User Directory Sync's org script.

      Assigns new users to the same Code42 organization and does not map new users based on the Code42 User Directory Sync org script. If you choose this option, you must add an organization in the Code42 console for the users to be assigned to.

      Use this option if you want to manage new users in the Code42 console. All users that are provisioned from Code42 User Directory Sync are added to the same organization. You can then move the users from that single organization to additional organizations in the Code42 console. 

      Users that are placed in organizations by deployment policies or are assigned to organizations prior to the Code42 User Directory Sync configuration will remain in those organizations.

    • (Default) Map users to organizations based on the User Directory Sync's org script. Unmapped users will be created in the organization below.

      By default, Code42 User Directory Sync assigns users to organizations based on the Code42 User Directory Sync org script. Use this method if you want to manage users in Code42 User Directory Sync (and not in the Code42 console). Code42 creates new organizations or assigns users to existing organizations based on the org script. Users that are not mapped to an organization by the Org script will be automatically assigned to the selected org.

      Changes to the organization mappings will only update users going forward. Run a --full-sync  to re-process organization mappings for all target users in your directory service.

Change role mapping

Role mapping allows you to automatically assign Code42 roles to users provisioned from your directory service based on the Code42 User Directory Sync role script. Use the Select Roles button at the bottom of the Code42 User Directory Sync details page to select the roles you want to be able to manage with the roles script. This creates an allowed list of roles that can be managed by the role script. No role can be managed by the role script until it has first been selected in the Select Roles dialog. 

Users that are assigned roles by the roles script which are not enabled on the allowlist are ignored when running a synchronization. If a user is not assigned any roles in the allowlist, they are assigned their organization's default roles.

Changes to the role allowlist will only update users going forward. Run a --full-sync  to re-process role mappings for all target users in your directory service.

  1. Click the Select Roles button in the Role Mapping section.
    The Select Roles dialog appears.
  2. Select the roles to managed in the role script.
  3. Click Save.

To learn more about Code42 roles, see the Roles reference. 

Basic roles
  • If the insider risk agent is deployed to users in this group, include the Agent User role.
  • If the backup agent is deployed to users in this group, include the Desktop User and PROe User roles. These roles allow users to sign in to the Code42 agent and Code42 console to manage their backups and restore their files. If you are giving external groups access to your Code42 environment (for example, outside legal council) they do not need these roles.

Re-configure LDAP and SCIM passwords

In the event the password is updated for your LDAP directory service user, or regenerated for the Code42 User Directory Sync, the new passwords must be entered using the commands as indicated below. These commands write the encrypted versions of the passwords to the config.properties file. 

  1. Open a command prompt on the host computer where the Code42 User Directory Sync tool is installed.
  2. Navigate to the \bin folder of the Code42 User Directory Sync tool.
  3. Run C42UserDirectorySync --ldap-bind-password
    Enter the password for the LDAP directory service user. You will be prompted only once.
  4. Run C42UserDirectorySync.bat --scim-password
    Enter the password for the Code42 User Directory Sync user. You will be prompted only once.

When the commands run, the passwords are verified against the respective service and a network connection is tested between the LDAP server and the Code42 cloud. If errors are reported, address the errors before proceeding. 

Configure properties in the config.properties file

When you first run the User Directory Sync tool during installation, a config.properties file is created with the values provided in the prompts. It is then saved in the location where the tool is installed.

Configure the additional properties in this file to control advanced aspects of how users are provisioned from your directory service to Code42. If you need help setting values for these properties, contact your Customer Success Manager (CSM) to engage the Professional Services team.

All the available properties and their default values are documented in comments in the config.properties file. Following are some of the more important properties to configure.

Property name

Default value

Description
deactivate.user.threshold  5

The number of times a user can be absent from the search base before they are deactivated automatically in Code42 when missed.user.check = true. This property requires a value of 2 or higher.
driver.files.attribute.name sAMAccountName If the --files  flag is included during a synchronization run, the file's list of usernames will be looked up by this attribute when searching LDAP.
ldap.attrib.<attributeType> See config.properties file

A mapping of the desired LDAP user attribute to the Code42 attribute type. These values provide context around who a user is and how they are provisioned into Code42.
 

The following are supported attribute types:

  • Common name (First Name)
  • Country code
  • Department
  • Direct reports
  • Division
  • Employee type
  • Given name
  • Last name
  • Locality (City)
  • Manager
  • Region (State)
  • Search UID
  • Title
  • Username
ldap.attrib.dateformat uuuuMMddHHmmss[.S]X The format of time values, which are based on Java's java.time.format.DateTimeFormatter. This value is used to read the date time value returned from the "ldap.attrib.lastmodified" attribute.
ldap.attrib.lastmodified whenChanged The LDAP attribute used for identifying the last time the user's information was changed in the directory when running an incremental sync.
ldap.attrib.username format %s

The format of username values based on Java's string formatter. This value applies formatting to the value returned by the "ldap.attrib.username" attribute.

 

An example might be "%s@code42.com" which appends the "@code42.com" email domain to the username returned from ldap.attrib.username, represented by %s.

ldap.baseDn

 DC=example,DC=com

The LDAP search base defined by a fully distinguished name.
ldap.baseurl ldap://

The LDAP or LDAPS URL to your LDAP server. (Escaping of characters occurs automatically during the synchronization run.)

ldap.bind.authtype

 SIMPLE

The type of bind request made by LDAP authentication.

 

Valid values:

  • SIMPLE
    Binds with a bind user. Base DN as well as username and password are required. Provides basic authentication. To use this setting, ensure the base DN exists and is set in the ldap.baseDn property. 
  • NONE
    Binds anonymously. To use this setting, you must configure your LDAP service to accept anonymous binding. 
ldap.bind.password  NA

The LDAP bind password (encrypted) that must be set by running the synchronization with --ldap-bind-password.

 

Passwords saved directly to the config.properties file are not preserved.

ldap.bind.user

 cn=read-only-admin

The LDAP bind user that can be specified in user@domain.com, domain\user, or cn=user,dc=domain,dc=com format.
ldap.connection.allowunsafecerts false Allow loose validation of certificates for LDAP over SSL (LDAPS) connections by setting the property to true. This property allows for the use of self-signed certificates.

ldap.connection.pool

 false

Sets whether LDAP connection pooling is used.

ldap.connection.timeout.period

 5000

The time in milliseconds allowed to wait for a connection response by the LDAP server before timing out.
ldap.delay.between.attempts 1000 The delay between LDAP connection retries in milliseconds.
ldap.max.attempts 10 The maximum number of LDAP connection attempts before failing to connect and closing the process.

ldap.paging.size

 500

The maximum number of search results to request from LDAP server at a time.

ldap.read.timeout.period

 5000

The time in milliseconds allowed to search for a user in the LDAP directory before timing out.
ldap.referral THROW

When a referral is detected for a user pointing to another LDAP record.

 

Valid values:

  • IGNORE: Ignore referrals.
  • FOLLOW: Automatically follow any referrals.
  • THROW: Throw a ReferralException for each encountered referral.

Support of FOLLOW is limited and referrals may vary depending on your directory forest structure.
ldap.schema.attributes.returnattributes *,+ The specific attributes to be returned for a user in the LDAP results. The default of a wildcard ( * ) returns the entire LDAP record. This field can be defined as a comma-separated array of attributes or wildcards.
ldap.schema.attributes.sensitive userPassword,unixUserPassword,
msSFU30Password,unicodepwd,userCertificate		 A list of attributes that should be ignored for scripting and omitted in logs (like password).
missed.user.check false Sets whether the Code42 User Directory Sync tracks the number of times a user is absent from the search base, automatically deactivating them in Code42 after meeting the "deactivate.user.threshold" value.
missing.user.scrub.enabled false

Determines whether to remove users from mapping when the missing.user.scrub.threshold value is exceeded and missed.user.check = true.
missing.user.scrub.push true Determines whether empty user data should be pushed to Code42 when performing the user removal authorized by the missing.user.scrub.enabled setting. This effectively removes (or scrubs) the user's data that had previously been sent to Code42.
missing.user.scrub.threshold 10 Determines how many times a user must be absent from the directory service before removing the user from mapping. The properties missing.user.scrub.push = true and missed.user.check = true must be set. The value must be higher than the deactivate.user.threshold.

scim.baseurl

 https://<Code42 cloud URL>/scim/v2

The URL provided by the Code42 console when configuring a new provisioning provider. (Escaping of characters occurs automatically during the synchronization run.)

scim.password

 NA

The password (encrypted) provided by the Code42 console when configuring a new provisioning provider. This password must be set by running the synchronization with --scim-password. Passwords saved directly to the config.properties file are not preserved.
scim.client.threads 1

Maximum number of concurrent connections to the Code42 cloud. Set to a value higher than 1 to improve performance.
 

Use this property only in situations where your search base is greater than 10,000 users, and to increase the setting by 1 thread per additional 10,000 users. 

 

If you want to set this property to a value higher than 1, you must create all the organizations needed by users before running a synchronization. If you run a synchronization with the value set higher than 1 and rely on org scripts to automatically create new organizations in Code42, a new organization will be created for each thread, resulting in duplicate organizations.  
scim.username provider_id@cloud.code42.com The username provided by the Code42 console when configuring a new provisioning provider.

script.active.location

 activescript.js

The relative or absolute path to the file containing the "Active" JavaScript function.

script.org.location

 orgscript.js

The relative or absolute path to the file containing the "Org" JavaScript function.

script.role.location

 rolescript.js

The relative or absolute path to the file containing the "Role" JavaScript function.
workqueues.size 500 The number of user entries queued by the Code42 User Directory Sync at a time.

Configure Secure LDAP

Secure LDAP (LDAPS) is a protocol that uses a Transport Layer Security (TLS) connection to communicate with the LDAP server. Code42 User Directory Sync requires that a TLS certificate be configured within your target LDAP server. Although you can use a self-signed certificate, you should use a certificate-authority (CA) signed certificate to secure connections. 

Use the following configuration properties to set up Secure LDAP to work with Code42 User Directory Sync:

  • ldap.baseurl
    Set this property to point to the Secure LDAP server over a dedicated port. For example: 
    ldap.baseurl=ldaps\://192.0.2.0\:636  
    If you do not include the port with this property, the LDAPS port defaults to 636.  
  • ldap.connection.allowunsafecerts 
    Set this property to true or false depending on your needs. For example: ldap.connection.allowunsafecerts=true 
    Valid values are:
    • true
      Performs "loose" validation. Use when you have a self-signed certificate, an expired or invalid certificate, or connection problems such as a handshake error. 
    • false
      Performs strict validation (the default setting). Use when you have a certificate-authority (CA) signed certificate.

Secure LDAP most commonly fails when the ldap.connection.allowunsafecerts  configuration property is set to its default of false and there is a problem with the certificate, such as a self-signed certificate, expired certificate, or no certificate on the LDAP server. If the Secure LDAP connection fails, you may see an error similar to the following:

[ERROR   LdapService] Unable to contact LDAP source at ldaps://192.0.2.0:636, reason: 'javax.naming.CommunicationException: 192.168.0.64:636 [Root exception is java.net.SocketException: Connection reset]'