3.0 - Advanced LDAP Plugin

Plugin Version: 1.4.42 | Release Notes

Introduction

The Advanced LDAP/AD Sync plugin allows ProcessMaker users to login by authenticating directly in an LDAP server or Microsoft Active Directory server, unlike the LDAP community version that only imports users. It also enables synchronization with LDAP or Active Directory to update user information.

Requirements

• ProcessMaker Enterprise version 2.9 or higher with the corresponding license .

Supported Stacks

• Check this documentation to view the table of ProcessMaker supported stacks.

Browser Requirements

• To view the browsers supported check the following documentation.

How the plugin works

The Advanced LDAP/AD Sync plugin is used to compare the user's list in ProcessMaker against the user's list in LDAP or Active Directory. Users in Active Directory which haven't been imported or synchronized in ProcessMaker will not be created. However, if the option Enable automatic registration is activated, users will automatically be imported from Active Directory the first time they log into ProcessMaker.

The Lightweight Directory Access Protocol (LDAP) uses distinguished names (dn) to identify users, groups, and other types of entities. In LDAP and Active Directory, which is Microsoft's extension of LDAP, distinguished names are constructed hierarchically using:

• dn - domain components, such as: dc=acme,dc=com
• ou - organizational units, such as: ou=managers,ou=regionalbranch
• cn - common names, such as: cn=John Doe

Other naming attributes described in RFC 2253, such as o= for organization name and c= for country/region name, are not used in Active Directory, although they are recognized by LDAP.

The distinguished name describes entities starting from the specific and moving to the general in the hierarchy of entities.
For example: cn=John Doe,ou=managers,ou=regionalbranch,dc=acme,dc=com

Recommendations

• Verify that the file ldapadvanced.php, which is located at workflow/engine/bin/plugins/ldapadvanced/ldapadvanced.php, does NOT exist on the ProcessMaker server. If this file exists, it needs to be deleted. Otherwise, the ProcessMaker cron will execute it, and the task synchronization of the elements will be executed twice.

• If there are thousands of users to import, the max_page_size variable should be set in the Active Directory. If this setting is not configured, the Advanced LDAP plugin may not return all users. See this documentation.

• Due to security reasons, it is NOT recommended to use Anonymous connections.

Setup

• Import the Advanced LDAP plugin. See How to import plugins.

• Export the Directory CA Certificate. Follow these instructions to export the certificate from Active Directory
• Import the certificate to the following path in the server: /etc/openldap/cacerts/
• Create a TLS connection, by adding the following line to the Apache configuration file (which is generally named httpd.conf, but is named apache2.conf on Debian/Ubuntu systems):

This line tells Apache the path of CA certificate to verify the domain neonetda.org. After changing the Apache configuration file, restart Apache for the change to take effect.

Note: The TLS connection was tested with version 1.4.22 of the "ldapAdvanced" plugin and the Softerra LDAP Browser 4.5.

Note: When configuring the connection in ProcessMaker to the LDAP/Active Directory server, it is strongly recommended to use port 389 and not the 636. The PHP LDAP module creates a normal connection to the server through the default port and then executes a command that makes the connection secure via TLS (ldap_start_tls).

Finally, verify that the following directory has read and write permissions:

workflow/engine/xmlform/authSources

(If the normal installation procedure was followed, all subdirectories under workflow/engine/xmlform/ should be readable and writable by Apache.)

Authentication Sources

Go to ADMIN > Users and click on Authentication Sources

In the right panel, a list of existing authentication sources is displayed, with a button to create a new authentication source.

New Authentication Source

Click on New to create an authentication source. Then select the Provider, which can be the normal ldap importer or the ldapAdvanced plugin, which is recommended because it offers synchronization to update the user information and the ability to import groups and departments from Active Directory.

Then, define how to connect to the authentication source:

This new interface appears in version 1.4.40.

• Name: Enter a label which will identify the Authentication Source.
• Type: Select whether using LDAP or Active Directory. Moreover, if using version 1.4.40, there is the option to connect to 389 Directory Server
• Enable Automatic Register: If Yes is selected, when a new user tries to login, ProcessMaker will connect to the LDAP or Active Directory server and verify whether the user exists in the authentication source. Users which exist in LDAP or Active Directory will automatically by imported into ProcessMaker and be able to login.
• Server Address: Enter the IP address or domain name of the LDAP or Active Directory server. If located on the same machine, then enter "localhost".
• Port: Enter the port number for the LDAP or Active Directory service. By default, LDAP and Active Directory use port 389. If unsure, use the netstat -l and netstat -lnp commands in Linux/UNIX or netstat -a and netstat -ab commands in Windows to determine which port is being used.
• Enabled TLS: Select "Yes" if using Transport Security Layer (TLS) or Secure Socket Layer (SSL) to connect to the Authentication Source. Otherwise, select "No".
• Base DN: Enter the Distinguished Name from the Base object. In most cases this will be the domain components (dc) of the Distinguished Name. For example, the Base DN for processmaker.com would be "dc=processmaker,dc=com". For more information on constructing DN chains, see this LDAP guide.
• Anonymous: If the LDAP or Active Directory server accepts anonymous searches for users, then select "Yes". If a login is required, then select "No". It is not recommended to use this type connection in version 1.4.40.
  • Username: This field appears if not using anonymous logins. Enter a username to login to the LDAP or Active Directory server.
  • Password: This field appears if not using anonymous logins. Enter a password to login to the LDAP or Active Directory server.
• User identifier: Enter the object to identify users, which will be their username in ProcessMaker. For Active Directory, enter "samaccountname". For Open LDAP, enter "uid".
• User Identifier: Enter the object classes where ProcessMaker will look for users. By default, the object class for Active Directory is "user" and for Open LDAP is "inetOrgPerson". If unsure which object class to use, enter "*", which is slower because it will cause ProcessMaker to look in all object classes.

Note: In previous versions of the Advanced LDAP plugin, the User Identifier field was named Object Classes.

• Filter to search users Enter a filter which will be used when searching for users in the the authentication source.
• OU for retired Employees: Specify the DN of an Organizational Unit where users who have been removed or retired from the Authentication Source are placed.
• Match attributes to sync: Available on: ProcessMaker 1.4.29 and later. Mark this checkbox to map user attributes in the authentication source to fields in ProcessMaker's USERS table in the MySQL database. This option only supports existing fields in Active Directory.

Find the interface where the fields will be added:

Where:

• Add: Add a new field.

• Remove: Remove an existing field.

• LDAP Field: Pick a name for the field that will be synched.

• User Field: Choose a user field from the dropdown where the new LDAP field will be stored.

Note: This feature only works if the authentication source is Active Directory and ProcessMaker is version 2.5.0 or later. If using a previous version of ProcessMaker, elements in the User Field dropdown won't be listed, so it is recommended to update ProcessMaker to version 2.5.0 or later.

When done defining the new authentication source, click on Save to create it. To cancel the creation of a new authentication source (or discard any changes if editing an existing authentication source), click on Cancel. To check whether the configuration to connect to the authentication source is correct, click on Test Connection. If the configuration is correct, the following message will display:

Otherwise, the following message will appear:

When the new authentication source is created, it will be displayed on the list of existing Authentication Sources:

Authentication Sources list

This list displays the name, provider, server address and port for the authentication sources and provides the following options to use the authentication sources:

• New: Click this button to create a new authentication source.
• Edit: Select an authentication source in the list and then click this button to edit it.
• Delete: Select an authentication source in the list and then click this button to delete an authentication source.
• Import Users: Select an authentication source in the list and then click this button to import ussers from that authentication source.
• Synchronize Departments: This option is only enabled for Advanced LDAP. It imports new departments from the selected authentication source and synchronizes the information about existing departments.
• Synchronize Groups: This option is only enabled for Advanced LDAP. It imports new user groups from the selected authentication source and synchronizes the information about existing groups.

Note: Before doing synchronization users must be assigned to a group or a department in the authentication source.

Importing Users

After configuring the authentication sources, go to ADMIN > Users > Authentication Sources. Select an authentication source in the list and click on its Import Users button.

In the panel Search for user, enter text in the Keyword field to do a case-insensitive search for users in the full name, username, email or distinguished name (dn) of users in the authentication source. Use * (asterisk) to do a wildcard search for any number of characters (including zero characters). For instance jo*n would find johan@colosa.com, Joe Norris and Jonson. Enter * to return all users in the authentication source.

Importing users v. 1.4.29

Importing users v. 1.4.40

WARNING: If the LDAP server has a large number of users in the thousands, searches may not show any users if the search returns too many results. In this case, narrow the search. For example, searches for "*" (all users) or "e" (all users with the vowel "e") may not work, but narrowed searches such as "er" or "kat*e" may work.

The following information will be displayed about the users in the authentication source:

• Username:(Formerly named Name) This field shows the username.
• First Name: This fields show the user's first name.
• Last Name: This fields show the user's last name.
• E-Mail: This field shows the user's email.
• Distinguished Name: The DN is a chain of information needed to identify a user, such as the common name (cn=), organizational units (ou=) and domain components (dc=), etc.
• Status: Available on: ProcessMaker 1.4.40 on. It shows whether the user was IMPORTED or NOT IMPORTED:

After finding users, then select which ones will be imported by marking the checkbox next to their names.

To select all the users in the list, click on the [SELECT-ALL] button in version 1.4.29 or mark the checkbox in the upper left-hand corner in version 1.4.40:

Then click on the Import button to import the selected users into ProcessMaker.

After importing user(s), a confirmation message will be displayed. Click on Yes to import the user(s); otherwise, the importation of user(s) will be canceled.

When done importing users, click on the Back button to return to the list of Authentication Sources.

Synchronization

The Advanced LDAP plugin can be used to update the information about users which are imported from an authentication source. The plugin can also import both departments and groups into ProcessMaker from LDAP and Active Directory. After importing groups and departments, the Advanced LDAP plugin can be used to synchronize the information about the departments and groups and their users, so the information in ProcessMaker is the same as in the authentication source. The group and department names are immediately imported after selecting which groups and departments will be synchronized, but the members are only imported and synchronized when cron.php is executed in version 1.4.29 and earlier or when ldapcron.php is executed in version 1.4.40 and later.

Warning: The Advanced LDAP plugin will only import members of a group or an organizational unit from an LDAP server if those users were created as child objects under the group or organizational unit. (Note that ProcessMaker treats organizational units as departments). If the users were assigned to the group or organizational unit through its membersUid property, then the users will not be imported. Future versions of the Advanced LDAP plugin will fix this problem.

To configure which departments and groups will be synchronized, go to ADMIN > Users > Authentication Sources and select an authentication source in the list which uses Advanced LDAP. The Synchronize Departments and Synchronize Groups options will be enabled:

Note: In ProcessMaker both groups and departments can contain users, but groups are not hierarchical and users can be members of multiple groups. In contrast, departments are hierarchical with parent departments and child departments and a manager for each department. Users can only be members of one department.

Synchronizing Departments

To configure which departments will be synchronized when cron is executed, click to display a list of departments and their subdepartments. If the authentication source is LDAP, all organizational units (ou) are considered departments and will be listed.

Warning: If the LDAP server has a large number of records in the thousands, the first time ProcessMaker tries to show its list of departments, it may appear that there are no departments in the authentication source because ProcessMaker spends several minutes constructing the list.

Select the departments to import or synchronize if already imported. The department along with all its members will be imported and the information in ProcessMaker about the department and its members will be synchronized each time that cron is executed. Note that in order to select a department, all its parent departments must also be selected.

After selecting the departments and subdepartments to synchronize, then click on Save Changes. The Departments which were selected will immediately be created in ProcessMaker, but the members of the departments will not imported/synchronized until the cron is executed.

Note: If using LDAP, the Reports To field of imported users will be left blank and there will be no supervisors assigned for imported departments. If using Active Directory, the Advanced LDAP plugin will assign the manager for each user, by inserting the manager's UID in the wf_.USERS.USR_REPORTS_TO field in the MySQL database, but it doesn't assign supervisors to imported departments. After importing a department from LDAP or Active Directory, the supervisor must be manually assigned for the department.

Synchronizing Groups

To configure which groups will be synchronized when cron is executed, click to display a list of groups from the selected authentication source.

WARNING: If the LDAP server has a large number of records in the thousands, the first time ProcessMaker tries to show its list of groups, it may appear that there are no groups in the authentication source because ProcessMaker spends several minutes constructing the list.

Select the groups to synchronize and then click on Save Changes. The groups which were selected will immediately be created in ProcessMaker, but the members of the groups will not imported/synchronized until cron is executed.

Executing cron.php in version 1.4.29 and earlier

To synchronize the information about imported users and update the members of departments and groups in version 1.4.29 and earlier of the Advanced LDAP plugin, execute ProcessMaker's cron.php file, either from the command line or as a cron job in Linux/UNIX or as a Scheduled Task in Windows. For more information, see: Executing cron.php

When cron.php is executed, the managers assignments for departments will be displayed:

The cron.php file imports the users who are members of the selected groups and departments:

Note: When a user, who is inactive in Active Directory, is imported in ProcessMaker his status will be Active; however, if the user tries to login ProcessMaker, it will show a message that he is inactive and the status will be updated automatically.

Note: In order for the Advanced LDAP synchronization to work correctly when cron is run, make sure that the following files are present: /workflow/engine/bin/plugins/ldapadvanced.php and /rbac/engine/classes/plugins/class.ldap.php

Executing ldapcron.php in version 1.4.40 and later

Synchronize users, groups and departments by using the Advanced LDAP cron file, which is located at workflow\engine\plugins\ldapAdvanced\bin\ldapcron.php in version 1.4.40 and later. This file will be executed independently, meaning that the ProcessMaker cron file won't execute the LDAP synchronization.

To execute the ldpacron.php file from the command line:

Windows:

Linux/UNIX:

If the ldapcron.php script is executed without any options, the imported users and selected departments and groups will be synchronized for all workspaces.

Note: The Advanced LDAP plugin takes roughly an hour to import 20,000 new users from LDAP and 25 minutes to update 20,000 user profiles from LDAP, so it is recommended to use the +force option to prevent problems with large authentication sources if executing the ldapcron.php file as a cron job in Linux/UNIX or a Scheduled Task in Windows.

If executed from the command line, the following information is displayed about the users, departments and groups which were synchronized:

To see more detailed information about the synchronization, check the contents of the /shared/log/ldapAdvanced.log file.

Hint: ldapcron.php appends new information to the ldapAdvanced.log file each time the script is executed. If ldapcron.php will be executed periodically as a cron job or scheduled task, it is recommended to also periodically delete the ldapAdvanced.log file to save disk space on the ProcessMaker server and improve the processing time of the ldapcron.php script.

ldapcron.php Options

Options:

• +d Specify an alternative date and time for the script.

By default, the script will execute using the server's current system time. If may be useful to specify an alternative date and time when testing for past or future events. Remember to use 4 digits for specifying the year and 2 digits for specifying the month, day, hour, minute and seconds. The time is on a 24 hour clock.

Ex: php ldapcron.php +d"2011-09-25 07:05:59"

• +w Specify a workspace whose imported users and selected departments and groups will be synchronized.

By default, the pending activities in all workspaces are executed. To save processing, it can be useful to only execute the pending activities in a single workspace. Remember the workspace names are case sensitive.

Ex: php ldapcron.php +wworkflow

• +force This option ensures that the ldapcron.php file is executed by stopping the execution of any existing ldapcron job and deleting its temporary files, so the current ldapcron can be executed. Remember that only one instance of ldapcron can be executed at a time, so without the +force option, ldapcron.php will not be executed if another instance is already being executed.

Ex: php ldapcron.php +force

Note: If not using the +force option, to cancel the execution of ldapcron.php, press CTRL+C in the command line or use the kill command in Linux or the Task Manager in Windows to kill the process. Also delete the temporary file located at: /shared/ldapcron

• +debug Inserts more detailed information in the /shared/log/ldapadvance.log file. It lists the properties used to connect to the authentication sources and lists the users, groups and departments which were created, updated, moved or deleted. Use this option to investigate any errors that may occur during the synchronization.

Ex: php ldapcron.php +debug

Mapping user's information between Active Directory and ProcessMaker

Available on: AdvancedLDAP 1.4.29 and later; ProcessMaker 2.5.1 and later

When importing users, information about the user in Active Directory can be mapped to fields about the user in the ProcessMaker database. To map information between the authentication source and the ProcessMaker database, mark the Match attributes to sync checkbox and a section will appear to link fields in the authentication source to fields in the ProcessMaker database.

• LDAP Field: Enter an LDAP field name. The Softerra LDAP Browser can be used to find the LDAP field names. The field names must not contain spaces. For example, the field "Telephone Number" would be defined as "telephoneNumber" in LDAP.

• User field: Enter one of the following fields in the wf_.USERS table:

USR_FIRSTNAME: User's first name.

USR_LASTNAME: User's last name.

USR_DUE_DATE: The date when the user account is set to expire in YYYY-MM-DD format. Ex: 2020-12-31

USR_STATUS: The user's status, which can be: ACTIVE, INACTIVE, or VACATION

USR_ADDRESS: The user's address.

USR_PHONE: The user's phone number.

USR_FAX: The user's fax number.

USR_CELLULAR: The user's cellular phone number.

USR_ZIP_CODE: The user's zip or postal code.

USR_POSITION: The user's position, which can be any value such as "Accountant", "Human resources manager", etc.

USR_BIRTHDAY: The user's birthday in YYYY-MM-DD format. Ex: 1970-04-21.

As many fields as needed can be added to the list.

For example, inside your Active Directory server, choose a user to import. Go to his/her properties and add a job title inside Organization - Title:

After adding the field, login to ProcessMaker and go to ADMIN > Users > Authentication Sources. Select the Active Directory server and click on Edit and map the "Title" field in Active Directory to the USR_POSITION field in the ProcessMaker database.

Then, click on Import Users:

Search for the user who will be imported in ProcessMaker. Select the user and click Import:

Finally, go to ADMIN > Users and look for the imported user:

In this example, the position field has been updated with the title information added in Active Directory

Note: If the field in Active Directory or LDAP is greater in size than the field in the ProcessMaker database, then the value will be truncated to the maximum number of characters allowed for the field in ProcessMaker.

Changing user password after importing and synchronization

During login, the authentication of imported users occurs in Active Directory, not in ProcessMaker.

After users are imported from Active Directory, their passwords can NOT be changed in ProcessMaker, Instead, their passwords need to be changed inside Active Directory. Password must meet the following requirements:

• The password must be at least six characters long.
• The password must contain characters from at least three of the following five categories:
  • English uppercase characters (A - Z)
  • English lowercase characters (a - z)
  • Base 10 digits (0 - 9)
  • Non-alphanumeric (For example: !, $, #, or %)
  • Unicode characters
• Do NOT use spaces after and before the password

Warning: If the password is changed in ProcessMaker, the user cannot login.

To check whether a user was imported from Active Directory, go to ADMIN > Users. Select the user in the list and click on Authentication. If the Authentication Source option is an Active Directory connection, the password must be changed in Active Directory.

If the the Authentication Source option is "ProcessMaker (MYSQL)", the password must be changed in ProcessMaker: