This article provides suggestions for troubleshooting problems with Code42 User Directory Sync.
If you use Active Directory as your directory service, you should use the Code42 app in Azure AD to provision users to Code42 instead of Code42 User Directory Sync. For more information, see How to provision users to Code42 from Azure AD.
- If you need help with Code42 User Directory Sync, contact our Customer Champions for support, or contact your Customer Success Manager (CSM) to engage the Professional Services team.
- To perform troubleshooting as described in this article, you must be authorized to access and manage the directory service used at your company (for example, Active Directory).
Before you begin
- Double-check that you have correctly:
- Installed the Code42 User Directory Sync tool to a dedicated host computer or virtual machine.
- Configured scripts to control how synchronization provisions users from your directory service to your Code42 environment.
- Configured properties in the config.properties file to control how synchronization processing occurs.
- Carefully review log files in the \logs directory where the Code42 User Directory Sync tool is installed.
Use the following checklists to help you troubleshoot problems with Code42 User Directory Sync.
Setup and configuration
If you are having problems setting up Code42 User Directory Sync for the first time, or suspect the problems are configuration-related, use the checklist below to help you troubleshoot them.
For configuration instructions, see Configure Code42 User Directory Sync.
Use a supported version of Microsoft Active Directory
Code42 User Directory Sync is supported for use only with Microsoft Active Directory versions 2003 through 2019.
Make sure you deploy to a dedicated server
Make sure that the host server where the Code42 User Directory Sync tool is installed is a dedicated bare metal server or virtual machine. Other services running on the host could interfere with synchronization.
Ensure the ldap.baseurl property isn't pointed to a load balancer
When you installed the Code42 User Directory Sync tool, you should have entered the address of your directory service server to the ldap.baseurl property. The User Directory Sync tool uses LDAP paging for larger search results, so load balancers may cause a paged request to go to a different directory server, which isn't supported by Active Directory's paging implementation. To fix the problem, change the property's value in your configuration.properties file.
Ensure the ldap.baseurl property uses the correct port
When you installed the Code42 User Directory Sync tool, you should have included a port number in the ldap.baseurl property along with the address of your directory service server, and the port needs a firewall rule to ensure access. If you did not include a port number, the port defaults to 389, or in the case of Secure LDAP, to port 636. If you have problems with port access, ensure your firewall rules are set correctly and set the correct port number in the ldap.baseurl property in your configuration.properties file.
Ensure the LDAP bind username is in the correct format
When you installed the Code42 User Directory Sync tool, you entered the username of the authorized service account for your directory server to the ldap.bind.user configuration property. You must use the format of
"cn=user,dc=domain,dc=com" (the default value is "cn=read-only-admin"). If the username is not in a format that complies with your directory server settings, LDAP authorization may fail. We suggest configuring the firstname.lastname@example.org format for service accounts in the config.properties file.
If you have problems running synchronization, use the checklist below to help you troubleshoot them.
For synchronization instructions, see Run synchronization for Code42 User Directory Sync.
Make sure that passwords are correct
When you installed the Code42 User Directory Sync tool, you may have been prompted to enter the LDAP bind user and the Code42 SCIM user passwords. You may have also updated these passwords by running the
--scim-password flags in the command prompt.
These passwords are then encrypted and stored in the config.properties file under the ldap.bind.password property and the scim.password property, respectively. If passwords are not set using the command prompt, or are not the correct passwords for the LDAP or SCIM user, synchronization fails.
Following are some of the error messages that can occur if these passwords are not correct:
- LDAP: Error Code 49*, data 52e*
- LDAP Service, SCIM Service failed to start
- A failure occurred with exit code 2
- A failure occurred with exit code 3
The passwords can be incorrect for many reasons, for example:
- You moved the Code42 User Directory Sync tool to a new host.
- You changed to a new LDAP bind user or changed their password.
- You regenerated the password for the SCIM user.
- You attempted to run User Directory Sync under a different user in Windows.
To fix incorrect passwords, reconfigure the passwords with the following commands:
- LDAP bind password:
- SCIM password:
Passwords are encrypted in a specific manner
Code42 User Directory Sync encrypts passwords entered through the command prompt. The encrypted password is then stored in the config.properties file. The mechanism to encrypt these passwords is specific to the operating system:
- Encryption is specific to the user in Windows
To successfully decrypt the password, the account used at the command prompt to set the password must also be used when running Code42 User Directory Sync manually or as a scheduled task.
- Encryption is specific to the machine in Linux
If the Code42 User Directory Sync tool is transferred to a different host, the new host is not able to decrypt the stored password, and you must reset the password.
Check the Sync Log to make sure users are provisioned as expected
When you run a synchronization with Code42 User Directory Sync, updates made to your Code42 environment from the provisioning are shown in the Sync Log. Check the log to ensure that users are provisioned as expected to Code42. The Sync Log shows the results from Code42 User Directory Sync as well as SCIM provisioning providers.
The Sync Log is different from the files in the \logs directory where the Code42 User Directory Sync tool is installed. Files in the \logs directory record Code42 User Directory Sync processes. For errors and exit codes that can appear in the log files, see Logs below.
Check that your LDAP bind user has the correct permissions
If the LDAP bind user defined by the ldap.bind.user configuration property doesn't have the correct permissions in your Active Directory server, the following issues may occur:
- Large numbers of users aren't found by the Code42 User Directory Sync tool.
- User attributes are missing.
- Logs list this error for multiple users: last modified timestamp is null.
The LDAP bind user must have permissions in Active Directory to view the following components:
Check that the user running synchronization has the correct permissions
You can perform a synchronization either manually or with a scheduled service. In either case, there is a user who performs the synchronization, and that user must have the correct permissions to run the synchronization. If they don't, the synchronization fails with an Access is denied error message or other issues.
The user running the synchronization must have the following permissions:
- Manual or scheduled task: Permission to log in to the server hosting the Code42 User Directory Sync tool
- Scheduled task: Permission to log on as a batch job to run the scheduled task
Run a full sync
Typically when you run synchronization, you perform an incremental run that only looks for the changes made since the last synchronization. However, the incremental synchronization may have problems reconciling changes since the last run.
If you are having problems with an incremental synchronization, perform a refresh of the synchronization process by running a test full synchronization in dry-run mode:
After resolving any problems uncovered by the dry-run test, run a full synchronization:
C42UserDirectorySync --sync-now --full-sync
To help determine why your scripts don't work, back up the scripts and create new test scripts that point to a specific user and that contain the minimum processing desired. Then run synchronization in dry-run mode to try out the test scripts. If the test scripts run, add in other desired elements until you uncover possible scripting problems.
Don't attempt to provision users in nested groups by provisioning only the parent group
If you provision a parent group, users in that group are provisioned, but not the users in nested groups. To provision users in nested groups, you must include each nested group in your LDAP script search filtering.
Submit files to support
If you need help with Code42 User Directory Sync, contact our Customer Champions for support, or contact your Customer Success Manager (CSM) to engage the Professional Services team. Provide copies of the following:
To view synchronization logs, see the \logs directory in the location where the Code42 User Directory Sync tool is installed.
The files in in the \logs directory record Code42 User Directory Sync processes, and are separate from the Sync Log, which shows the updates made to your Code42 environment from provisioning.
Common error messages
Following are some of the most common error messages that can appear in logs when running synchronization.
|Access is denied||The user running the synchronization doesn't have the proper access rights to log files.||Ensure that the service user is properly configured for read/write permissions in the directory where the Code42 User Directory Sync tool is installed.|
|Directory service did not return any users when checking for missing users. Skipping deactivation step.||
There is a problem when checking for missing users in the directory service, and as a result, the deactivation in Code42 of users no longer visible in the directory is skipped.
|Unique index or primary key violation||
This error occurs during a synchronization following an upgrade from Code42 User Directory Sync version 1.1.0 or earlier. The cause is that a user's UID (
|LDAP: Error Code 49*, data 52e*||The username and password are not accepted by the LDAP server. This may be due to the values being entered incorrectly, containing symbols, or the username not being readable (due to spaces or incorrect specification of the DN).||
Configure the ldap.bind.user property in the config.properties file to be the FQDN of the LDAP service's user account. You may also need to include in the property the domain with the username, for example:
If you still receive the error after attempting this solution, ensure the LDAP service account's password does not contain any of the following characters:
|LDAP Service, SCIM Service failed to start||
Both the SCIM and LDAP services failed to start simultaneously. This occurs typically after an upgrade to a newer version of Code42 User Directory Sync.
This typically happens after an upgrade because:
|Ensure that the SCIM and LDAP passwords are configured with the
java.security.cert.CertificateException: No subject alternative DNS name matching
You do not have the hostname of the domain controller in your SSL certificate. Typically this error appears in the log at the initial synchronization.
Update your internal certificate with the hostname of the domain controller in the SAN.
If this is not possible, set synchronization to ignore this error by adding the
|Unable to Access JAR file||The Code42 User Directory Sync tool is installed in a directory with spaces in the file path.||Upgrade to Code42 User Directory Sync version 1.3.0 or later.|
Following are exit codes that occur when a synchronization terminates without completing.
|1||An error message specific to the validation failure is displayed.||Invalid arguments||Double-check that the arguments you used with the
A failure occurred with exit code 2.
There was an issue with the SCIM and LDAP URLs, usernames, or passwords.
Verify usernames and the URLs are set in the config.properties file. Also ensure the passwords for the SCIM and LDAP users have been configured using the
If you still encounter issues, run synchronization with the
A failure occurred with exit code 3.
The Base DN is invalid or the passwords could not be decrypted properly.
Ensure the Base DN exists and is properly set in the
A failure occurred with exit code 4.
Invalid logic in the active, org, or role scripts.
|Ensure the scripts are entered and formatted properly.|