1. CrashPlan Help Center
  2. CrashPlan
  3. Cloud administration
  4. Monitoring and managing
  5. User Directory Sync resources

Configure CrashPlan User Directory Sync

Updated

Overview

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

This article explains how to install the CrashPlan User Directory Sync tool to a dedicated host server and how to configure CrashPlan User Directory Sync in the CrashPlan 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 CrashPlan 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).
  • CrashPlan User Directory Sync is only available for customers in the CrashPlan cloud.
    • New CrashPlan cloud environments: CrashPlan User Directory Sync is configured as part of your implementation. 
    • Existing CrashPlan cloud environments: Your Professional Services contact provides you with a link to download the CrashPlan User Directory Sync installation file. Contact your Customer Success Manager (CSM) to learn more. 
  • The CrashPlan 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 CrashPlan 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 CrashPlan 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 CrashPlan 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 CrashPlan User Directory Sync tool installation file

As part of this configuration process, you must install the CrashPlan 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 CrashPlan User Directory Sync tool installation file. You will install the tool in Step 2 below.

Prepare the host server

The CrashPlan 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 CrashPlan 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 CrashPlan 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 CrashPlan User Directory Sync tool

The CrashPlan User Directory Sync tool is packaged with a stand-alone Java Runtime Environment (JRE). This JRE is specific to CrashPlan 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 CrashPlan cloud.

Rule

Destination

Direction

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


Harden the server

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

Create organizations

When users are provisioned from your directory service to organizations in your CrashPlan environment using org scripts, CrashPlan User Directory Sync automatically creates organizations if they don't already exist. Rather than having CrashPlan 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 in CrashPlan.

Install CrashPlan User Directory Sync

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

  1. In the CrashPlan console, navigate to Administration > Integrations > Identity Management. 
  2. Select the Provisioning tab. 
  3. Click Add Provisioning Provider.
  4. Select Add CrashPlan User Directory Sync from the dropdown menu.
  5. Enter a username and click Next. 
    The CrashPlan User Directory Sync Created dialog appears. (This username will also be used as the display name in the CrashPlan 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 CrashPlan User Directory Sync tool in Step 2. 
  7. Only click Done after you have saved the information.UDS_details_Jan_8_2020.png

Step 2: Install the CrashPlan User Directory Sync tool

  1. Ensure you have done the following as described in Before you begin above:
    1. Obtained the CrashPlan 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 CrashPlan User Directory Sync tool.
  2. Log in to the host computer where you will install the CrashPlan User Directory Sync tool.
  3. Copy the CrashPlan 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 CrashPlan User Directory Sync tool to reside.
  5. Open a command prompt.
  6. Navigate to the \bin folder of the extracted CrashPlan 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 CrashPlan User Directory Sync Created dialog in Step 1 above.
    7. scim.username – Enter the username from the CrashPlan User Directory Sync Created dialog in Step 1 above.
    8. scim.password – Enter the password from the CrashPlan User Directory Sync Created dialog in Step 1 above. 
      The password does not appear on screen. Enter it twice when prompted.
  9. Press Enter.
    CrashPlan 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, CrashPlan 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 CrashPlan 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 CrashPlan.
  • OrgScript.js
    Determines how to assign users to organizations. If a user is provisioned to an organization that doesn't previously exist in CrashPlan, 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 CrashPlan 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 CrashPlan. 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 CrashPlan User Directory Sync . For example scripts, see Example scripts for CrashPlan 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 CrashPlan User Directory Sync .

To test your configuration for the first time:

  1. Open a command prompt on the host computer where CrashPlan User Directory Sync tool is installed.
  2. Navigate to the \bin folder of the CrashPlan 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 CrashPlan User Directory Sync below.
  4. To perform a synchronization for the first time between your active directory service and CrashPlan, run  C42UserDirectorySync --sync-now
    The system performs a synchronization between your active directory service and CrashPlan 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 CrashPlan User Directory Sync

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

  • C42UserDirectorySync

    Executes CrashPlan User Directory Sync in dry-run mode (with no flags). This performs a connection check between the LDAP server and the CrashPlan 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 CrashPlan during a live incremental synchronization (via --sync-now flag).

  • C42UserDirectorySync --full-sync
    Executes CrashPlan User Directory Sync in dry-run mode. This performs a connection check between the LDAP server and the CrashPlan 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 CrashPlan during a live full synchronization (using the --sync-now--full-sync flags together).
  • C42UserDirectorySync --debug
    Executes CrashPlan 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 CrashPlan 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 CrashPlan User Directory Sync .

Next steps

After CrashPlan User Directory Sync is configured, run the C42UserDirectorySync --sync-now command when you want to synchronize your active directory service with CrashPlan. For more information, see Run synchronization for CrashPlan 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 CrashPlan User Directory Sync, you can configure it to fit your needs.

Change organization mapping and role mapping

In the CrashPlan console when you click Done in the CrashPlan User Directory Sync Created dialog in installation Step 1, the CrashPlan 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 CrashPlan organizations based on the CrashPlan 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 CrashPlan organization and does not map new users based on the CrashPlan User Directory Sync org script. If you choose this option, you must add an organization in the CrashPlan console for the users to be assigned to.

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

      Users that are placed in organizations by deployment policies or are assigned to organizations prior to the CrashPlan 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, CrashPlan User Directory Sync assigns users to organizations based on the CrashPlan User Directory Sync org script. Use this method if you want to manage users in CrashPlan User Directory Sync (and not in the CrashPlan console). CrashPlan 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 CrashPlan roles to users provisioned from your directory service based on the CrashPlan User Directory Sync role script. Use the Select Roles button at the bottom of the CrashPlan 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 CrashPlan roles, see the Roles reference . 

Basic roles

Include the Desktop User and PROe User roles for all users who are backing up their computers to CrashPlan. These roles allow users to sign in to the CrashPlan app and CrashPlan console. If you are giving external groups access to your CrashPlan 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 CrashPlan 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 CrashPlan User Directory Sync tool is installed.
  2. Navigate to the \bin folder of the CrashPlan 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 CrashPlan 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 CrashPlan 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 CrashPlan. 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 CrashPlan 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 CrashPlan attribute type. These values provide context around who a user is and how they are provisioned into CrashPlan.
 

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 CrashPlan User Directory Sync tracks the number of times a user is absent from the search base, automatically deactivating them in CrashPlan 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 CrashPlan 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 CrashPlan.
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://<CrashPlan cloud URL>/scim/v2

The URL provided by the CrashPlan 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 CrashPlan 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 CrashPlan 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 CrashPlan, 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 CrashPlan 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 CrashPlan 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. CrashPlan 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 CrashPlan 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]'
Was this article helpful?
0 out of 0 found this helpful

Articles in this section