Overview
Incydr User Directory Sync leverages your organization's existing directory services environment by enabling LDAP integration with Incydr. Every directory structure is different, so Incydr User Directory Sync allows you to add JavaScript to map your existing directory structure to Incydr organizations and roles for automated user management.
This article gives examples of how to use JavaScipt with Incydr User Directory Sync. For help with Incydr User Directory Sync, contact your Customer Success Manager (CSM) to engage the Professional Services team.
Considerations
- Incydr User Directory Sync is only available for customers in the Incydr cloud.
- To install Incydr User Directory Sync, see Configure Incydr User Directory Sync.
LDAP script capabilities
When you install Incydr User Directory Sync, it automatically creates basic JavaScript files in the installation directory. Configure these scripts with JavaScript functions to provision users to Incydr. We use three different scripts:
- Active script: Activate or deactivate users.
- Org script: Assign users to specified organizations.
- Role script: Assign roles to users.
Once you configure the scripts, they read user attributes and group membership information from your LDAP environment. When the scripts are run, the Incydr User Directory Sync places users into the correct Incydr organization and grants them appropriate user roles based on their LDAP attributes and group membership.
LDAP script triggers
A synchronization executes the active, org, and role scripts each time it runs. When the scripts run, they read users' LDAP attributes and group membership, and change your environment to match.
User management scope
Incydr User Directory Sync creates new users or assumes management of existing users in Incydr only if the users exist in the LDAP search results. These users are then processed by the active, org, and role scripts and updated in Incydr accordingly. User Directory Sync can only manage users that are returned in the LDAP search results. If users are moved outside of the scope of the filtering criteria, they cease to be managed by Incydr User Directory Sync.
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.
The sections below contain sample scripts. Assistance with scripts is beyond the scope of Technical Support Engineers. For further assistance:
-
See example scripts here: Example scripts for Incydr User Directory Sync.
-
Contact your Customer Success Manager (CSM) to engage the Incydr Professional Services team. They have access to a large library of existing scripts and can help tailor your LDAP integration as needed.
Active script
The active script determines what state users should have in Incydr. For those users that are returned by your LDAP search filter, the active script either marks them active or deactivated and relays that information to Incydr. For example:
- If the user does not exist in Incydr but is marked TRUE, the user is created in Incydr.
- If the user already exists in Incydr and is marked TRUE, the user is managed by User Directory Sync from that point forward.
- If the user does not exist in Incydr and is marked FALSE, the user is not created in Incydr.
- If the user already exists in Incydr and is marked FALSE, the user is deactivated in Incydr.
Should your user management workflow require that users be moved outside of the search filter results before they are deactivated, the User Directory Sync does not detect this change and the users remain active in Incydr. If this workflow is a requirement, please contact your Customer Success Manager (CSM) to engage the Professional Services team.
Default active script
The default active script code, which handles the default active script behavior, is:
function isActive(entry) {
return true;
}
If the user is found in LDAP, the default JavaScript function returns the value TRUE. The user is treated as active.
Active script example
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. This script deactivates a user if they are disabled in active directory (AD).
function isActive(entry) {
if (entry.userAccountControl & 0x2) {
return false;
} else {
return true;
}
}
The active script must return a Boolean (true or false).
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 administrator may activate the user's device from the Incydr console.
- Backup agent only: The reactivated user may sign in to the agent on the deactivated device.
In either case, the device's GUID remains the same.
Backup agent only: 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.
Reactivation of manually deactivated users
If you use the Incydr console to directly deactivate users from an organization with directory services enabled, these users will be reactivated when User Directory Sync detects another change and syncs the user.
To make sure a user stays deactivated, do one of the following:
- For all users and devices in Incydr organizations with directory services enabled, deactivate or remove the users from the directory service, rather than directly from the Incydr console.
- Create a new organization that is not linked to any directory service, and move users to that organization before deactivating them. They will not be reactivated by Incydr User Directory Sync.
- Change the user's username, or whatever attribute is mapped to the LDAP search filter. The user will no longer be affected by the Incydr User Directory Sync.
Users on legal hold cannot be deactivated
Backup agent only
Users placed under legal hold cannot be deactivated. Their data is retained for the legal hold process. If a user is deactivated in LDAP, Incydr blocks the user instead. Once the user is released from legal hold, they are automatically deactivated.
Reactivating a user: If you deactivate users while they are on legal hold, and then wish to reactivate those users, you must unblock the user in the Incydr console.
Org script
The org script places a user into a specific Incydr 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. Target organizations do not need to exist before the script runs. If a named target organization does not exist, the org script creates an organization with that name.
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 environment organizations automatically.
Org script example
The org script can place users into a environment organization based on the OU specified in each user's LDAP distinguished name. The script does the following:
- Parse the user's distinguished name.
- If the user is in the LDAP Staff OU, return the value “Staff” to place the user into the environment's Staff organization.
- If the user is in the LDAP Students OU, return the value “Students” to place the user into the environment's Students organization.
- 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 getOrgName(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';
}
}
The org script must return a string.
Role script
The role script applies a set of user roles to a user account based on the user's LDAP attributes or security group membership. Only roles that are added to the Role Mapping list within the Incydr console can be managed by Incydr User Directory Sync. Incydr does not add, update, or remove roles that are not in the Role Mapping list.
Role script example
This example analyzes an LDAP environment and grants user roles based on LDAP memberships.
- Determine which LDAP groups the user is a member of.
- Map the appropriate environment roles to the account:
- If the user is a member of the Admins LDAP group, grant the Org Security Viewer role.
- If the user is a member of the Support LDAP group, grant the Org Admin role.
- If the user is a member of the Managers group, grant the Org Manager role.
- If the user is a member of the WorkstationAdmins group, grant the Org Help Desk role.
The following example assigns roles for the backup agent.
function getRoles(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("Org Security Viewer");
}
if (memberof[x].indexOf("Support") > -1) {
myRoles.push("Org Admin");
}
if (memberof[x].indexOf("Managers") > -1) {
myRoles.push("Org Manager");
}
if (memberof[x].indexOf("WorkstationAdmins") > -1) {
myRoles.push("Org Help Desk");
}
}
return myRoles;
}
The role script must return an array.
Comments
Please sign in to leave a comment.