Skip to main content

This article applies to version 6.

Other available versions:

Cloud | Version 5 | Version 4icon.qnmark.png

Available in:

StandardPremiumEnterprise
Small Business
Code42 Support

User management with LDAP integration

This article applies to version 6.

Other available versions:

Cloud | Version 5 | Version 4icon.qnmark.png

Available in:

StandardPremiumEnterprise
Small Business

Overview

This article assumes you have already set up basic LDAP authentication and describes how to extend your Code42 environment integration with LDAP.

For information on configuring your Code42 environment to use LDAP for authentication, see Integrate with LDAP for user authentication.

Add LDAP scripts to the administration console

Add JavaScript to your LDAP Server Setup to read user attributes and group membership information from your LDAP environment.

  1. On your authority server, sign in to the administration console.
  2. Go to Settings > Security > LDAP.
  3. Select an existing or new LDAP server:
    • Click on an LDAP server name to select an existing LDAP server.
    • Click Add to create a new LDAP server.
  4. Add JavaScript to any of these three fields in LDAP Server Setup:
Do not use regular expressions (regex) in Code42 LDAP scripts
Use of regex syntax causes LDAP sync to take much longer to complete than using other string functions.

LDAP script triggers

Two kinds of server events trigger the scripts to run:

When the scripts run, they read users' LDAP attributes and group membership, and change your Code42 environment to match.

Capabilities at user creation

When users are created, the active, org name, and role name scripts are run. The scripts immediately affect the newly created users, placing them into the correct organization and granting them appropriate user roles based on their LDAP attributes and group membership.

Capabilities at LDAP sync

LDAP sync executes the active, org name and role name scripts each time it runs. By default, LDAP synchronization runs once every 12 hours, but this interval length can be configured.

Adding Code42 platform users
LDAP integration helps to manage users, but it does not create them on its own. Create users alongside LDAP integration in one of three ways:
  • Self-service: When users install the Code42 app and sign in as a new user, their accounts are automatically created. If their organizations are configured to use LDAP, then they must use their LDAP credentials, registration key, and Code42 server address to create their account.
  • Deploy custom installers: Deploy preconfigured custom installers with software like Microsoft System Center Configuration Manager or Jamf Pro (formerly Casper Suite).
  • Create users manually: Administrators can create users manually or by uploading a CSV list.

At each LDAP sync, the scripts apply to all users. Certain scripts behave slightly differently at LDAP sync than at initial user creation. Behavior for each script is individually described below.

Example use of LDAP scripts

Consider the following situation. Company X's org name script depends on the location LDAP attribute. If the location attribute for user jsmith changes from San Francisco to New York, then the LDAP sync process moves jsmith from the San Francisco org to the New York org.

Script assistance
The sections below contain sample scripts that you may use or modify. Assistance with scripts is beyond the scope of Customer Champions. For further assistance:
  • Contact your Customer Success Manager (CSM) at csmsupport@code42.com to engage the Code42 Professional Services team. They have access to a large library of existing scripts and can help tailor Code42 for Enterprise's LDAP integration as needed. 

  • Post your question to the Code42 community to get advice from fellow Code42 administrators.

Active script

By default, LDAP sync automatically deactivates any users that do not match the LDAP search filter. Deactivated accounts are no longer authorized to back up or restore, and associated device archives are automatically placed into cold storage.

The default Active script is:

function(entry) {return true;}

If the user is found in LDAP, the default JavaScript function returns the value true. The authority server then treats the user as active.

But what if your company policy requires that LDAP entries for users remain permanently in LDAP, and the user's employment status is maintained via an LDAP attribute? You can use an Active script to deactivate a user account based on an LDAP user attribute.

Active script examples

Deactivates users if the userAccountControl attribute within LDAP is set to disabled. 

function(entry) {
  return !(entry.userAccountControl & 0x2);
}

Another example script deactivates a user if the 'employeeType' attribute equals 'inactive', or activates a user if the 'employeeType' attribute equals any other value.

function(entry) { return entry.employeeType !="inactive" }

User deactivation and reactivation

When a user is deactivated, the user's devices are automatically deactivated. However, when a user is reactivated, the user's devices are not automatically reactivated. Devices can be reactivated in two ways:

  • The reactivated user may sign in to the Code42 app on the deactivated device
  • The administrator may activate the user's device from the administration console

In either case, the device's GUID remains the same. Data that was previously backed up is still available, if the data retention period has not expired. File selections and other settings also remain the same.

Users on legal hold cannot be deactivated

If a user is placed under legal hold, the user cannot be deactivated. Their data is retained for the legal hold process. 

Depending on your Code42 server version, Code42 responds in the following ways when you mark a user for deactivation (either during an LDAP sync or by manually deactivating a user from the administration console): 

  • Code42 version 6.5.x and later: Users are blocked instead of deactivated. Once the user is released from legal hold, they are automatically deactivated.
  • Code42 version 6.0.x and earlier: User is not deactivated. You must manually deactivate the user once they are released from legal hold. 

Reactivating a user: In version 6.5.2 and earlier, if you deactivate users while they are on legal hold, and then wish to reactivate those users, you must reactivate each user and reattach their deactivated archive. In 6.7.2 and later, unblock the user

Org name script

The org name script places a user into a specific organization. JavaScript is used to parse the user's LDAP entry and return a single value. The user is placed into an organization that matches the return value. The org name script is applied during user creation, as well as each time the LDAP sync process runs.

Org name script behavior at user creation

The org name script uses several parameters given to it, including the name of a target organization and an organization's registration key, to sort users into organizations.

Target organizations do not need to exist before the script runs. If a named target organization does not exist, the org name script creates an organization with that name as a child of the organization corresponding to the given registration key.

Any valid parsing can be performed on the DN (distinguished name) of the user's record with JavaScript, and in this way, LDAP OUs (organizational units) can map to Code42 environment organizations automatically.

Org name script behavior during LDAP sync

Unlike org name script behavior at user creation, organizations are not created by the org name script during regularly scheduled LDAP sync. This is because the org name script doesn't have the scope to determine your Code42 environment's organization structure in order to locate users and organizations.

LDAP OUs can still map automatically to your Code42 environment's organizations, but you will need to create the organizations in order for the org name script to sort your users during LDAP sync.

Org name script example

The org name script can place users into a Code42 environment organization based on the OU specified in each user's LDAP distinguished name. The script does the following:

  1. Parse the user's distinguished name.
  2. If the user is in the LDAP Staff OU, return the value “Staff” to place the user into the Code42 environment's Staff organization.
  3. If the user is in the LDAP Students OU, return the value “Students” to place the user into the Code42 environment's Students organization.
  4. If the user is in neither the Staff nor the Students OU, return the value “Default” to place the user in the Default organization.
function(entry) {
   var ou = entry.dn;
   if (ou != null){
       if ((ou.indexOf("Staff") >= 0 )){  
           return 'Staff';
       }
       else if ((ou.indexOf("Students") >= 0 )){
           return 'Students';  
       }
       else {
           return 'Default';  
       }  
   }
   else {
       return 'Default';  
   }  
}

Role name script

The role name script applies a set of user roles to a user account based on the user's LDAP attributes or security group membership.

Role name script example

This example analyzes an LDAP environment and grants Code42 for Enterprise user roles based on LDAP memberships.

  1. Determine which LDAP groups the user is a member of.
  2. Map the appropriate Code42 environment roles to the account:
    • If the user is a member of the Admins LDAP group, grant the SYSADMIN role.
    • If the user is a member of the Support LDAP group, grant the All Org Admin role.
    • If the user is a member of the Managers group, grant the All Org Manager role.
    • If the user is a member of the WorkstationAdmins group, grant the Server Administrator role.
function(entry) {
   var memberof = entry.memberOf;

   // Default user roles
   var myRoles=new Array("PROe User","Desktop User");

   // Loop over LDAP groups
   for (var x = 0; x < memberof.length; ++x) {
      if (memberof[x].indexOf("Admins") > -1) {
         myRoles.push("SYSADMIN");
      }
      if (memberof[x].indexOf("Support") > -1) {
         myRoles.push("All Org Admin");
      }
      if (memberof[x].indexOf("Managers") > -1) {
         myRoles.push("All Org Manager");
      }
      if (memberof[x].indexOf("WorkstationAdmins") > -1) {
         myRoles.push("Server Administrator");
      }
   }
   return myRoles;
}

Testing LDAP scipts

We recommend testing your LDAP scripts before applying them to your production environments. To simulate an LDAP sync: 

  1. Sign in to the administration console on your authority server.
  2. Go to Settings > Security > LDAP.
  3. Click Simulate Synchronize
  4. Click History to view the results of the simulated sync.

directory sync entry example

Simulated synchronization results are emailed to the addresses configured in Settings > Notifications.

The results are also stored in the authority server's log files. Review these results by searching for DIRSYNC in the log files. For example, on Linux:

root@omega:~# tail -f /var/log/proserver/com_backup42_app.log.0 | grep DIRSYNC
[07.10.14 13:27:33.207 INFO    jetty-web-3217       ore.directory.impl.sync.DirectorySyncCmd] DIRSYNC:: Submitting for orgs: , [2,3]
[07.10.14 13:27:33.217 INFO    jetty-web-3217       .directory.impl.sync.DirectorySyncOrgCmd] DIRSYNC:: Running for org:2/Default
[07.10.14 13:27:33.270 INFO    jetty-web-3217       .directory.impl.sync.DirectorySyncOrgCmd] DIRSYNC:: Completed for org:2/Default users:2, deactivated:1, activated:0, moved:0, rolesChanged:0
[07.10.14 13:27:33.271 INFO    jetty-web-3217       ore.directory.impl.sync.DirectorySyncCmd] DIRSYNC:: Summary for orgIds:, [2,3], users:2, deactivated:1, activated:0, moved:0, roleChanges:0, simulated:true
[07.10.14 13:27:33.271 INFO    jetty-web-3217       com.backup42.history.CpcHistoryLogger   ] HISTORY:: Subject[1/admin, orgId:1] DIRSYNC:: Blocking and deactivating user:5/jdoe@code42.com in org:2/Default simulated:true
[07.10.14 13:27:33.412 INFO    jetty-web-3217       ore.directory.impl.sync.DirectorySyncCmd] DIRSYNC:: summary email sent to:[todd+vm@code42.com], users:2, deactivated:1, simulated:true

Still unsure?

Please contact sales for information on our consulting options.