External User Authentication

From version 1.2-2261 on, ProcessMaker supports the authentication of external users from LDAP or Active Directory. With external authentication, users' profiles can be imported, so users can use the same username and password in ProcessMaker as they use for their other applications. ProcessMaker supports multiple authentication sources, so that one user may be verified by ProcessMaker, another by LDAP, another by Active Directory, etc.

ProcessMaker Community Edition only offers manual import of LDAP and Active Directory users and doesn't support importing departments. For organizations needing better integration with LDAP or Active Directory, the Enterprise Edition includes an Advanced LDAP plugin, which supports departments, one-click synchronization of departments and/or subdepartments, and automatic import of new users at login.

Configuring Authentication Sources

Go to ADMIN > Users menu, the option Authentication Sources displays a list of the available authentication sources.

To add a new Authentication Source, click on "New", then define the properties how to access the Authentication Source.

Define the following fields:

• Name: Enter a label which will identify the Authentication Source.
• Type: Select whether using LDAP or Active Directory.
• Server Name: 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".
• Version: Select whether using version 2 or 3 of the LDAP protocol.
• 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".
  • Search User: Field appears if not using anonymous logins. Enter a username to login to the LDAP or Active Directory server.
  • Password: Field appears if not using anonymous logins. Enter a password to login to the LDAP or Active Directory server.
• Identifier for a imported user: Enter the object to identify users, which will be their username in ProcessMaker. For Active Directory, enter "samaccountname". For Open LDAP, enter "uid".
• Object Classes: 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.
• Attributes: Define the attributes for search operations. Separate each attribute with a new line. At a minimum, it should include the "cn" (common name).
  For example:

cn
samaccountname
givenname
sn
userprincipalname
telephonenumber

After filling in the fields, click on Save to create the new Authentication Source.

Importing External Users

After configuring the Authentication Sources, go to the USERS menu and select Authentication Sources. In the list that appears, find an authentication source and click on its Import Users link. A search box will appear to search for users.

To search for all available users from the Authentication Source, leave the Keyword search box empty and click on Search. To search for specific users, enter text that appears in one of the search Attributes for the Authentication Source. The search is case insensitive and the wildcard "*" can be used to search for any number of characters (including zero characters). For instance, a search for "jo*n" would find users "jon", "John Doe" and "jOannE".

A list of users will be returned by the search. Users whose usernames already exist in ProcessMaker can not be imported. All other users will have a checkbox next to them which can be marked to import them. To select all available users, click on the [SELECT-ALL] link at the top. After selecting the users to be imported, then click the Import button at the bottom.

After being imported, users should be able to login to ProcessMaker using their usernames and passwords from LDAP or Active Directory. If the external authentication source changes its address or goes offline, its users will not be able to login to ProcessMaker, so it is a good idea to convert those users to another authentication source or to ProcessMaker's internal authentication.

Note that it is not possible to change an imported user's password from inside ProcessMaker. Their passwords will have to be changed inside LDAP or Active Directory, however, their other information like email, address, telephone, etc. can be changed in ProcessMaker and is not synchronized with the external authentication source.

Assigning Authentication Sources to Existing Users

The Authentication Source can be changed for an existing user in ProcessMaker. It may be necessary to change a user's authentication source if their LDAP or Active Directory server moves to a new location or goes offline. Likewise, if a user's account gets deleted in the LDAP or Active Directory server, authentication should be switched from the external Authentication Source to ProcessMaker's internal authentication, so the user can continue to login to ProcessMaker.

To switch a user's authentication source, go to USERS > USERS LIST and find the user in the list. Click on the Authentication link for the user.

In the dialog that appears, select a Authentication Source from the dropdown box.

The default option is "ProcessMaker", which is the way that users are internally verified by ProcessMaker. When users are first imported into ProcessMaker, their passwords are also imported and stored in ProcessMaker's databases, so the users will revert to using their original password at the time of import.

Otherwise, select from one of the available external authentication sources. In the DN text field, which appears for external authentication sources, enter the LDAP "Distinguished Name" for the user. The DN is a chain of information needed to validate a user, which depends upon the configuration of your LDAP or Active Directory, but generally consists of a cn (common name) or uid (user ID), ou (organizational unit) and dc (domain component). This chain should be written as if walking up the Directory Information Tree (DIT), starting from the specific user and going to the general domain name. For instance, if John Doe has a user ID of "johndoe" and is found in the organizational unit of "staff" at the domain of "example.com", then his DN chain would be "uid=johndoe,ou=staff,dc=example,dc=com". See this LDAP guide for more information about constructing DN chains.

After selecting the Authentication Source (and defining the DN), click on Save to change a user's authentication source.

Users can also be found by entering a search string into the DN text field and clicking Save. All users which match the search string will be displayed (however, their authentication source can only be changed individually). The search is case insensitive and the wildcard * can be used to match any number of characters. For instance a search for "jo*n" would find users "jon", "John Doe" and "jOannE". If the DN text box is left blank, then a list will be displayed of all the users found in an authentication source.

Converting Users' Authentication Source in Batches

The ProcessMaker interface offers a way to convert a individual user's authentication source, so a single user can be easily be moved from one authentication source to another or converted from an external authentication source to internal verification by ProcessMaker. However, ProcessMaker doesn't offer an easy way to change large numbers of users from one authentication source to another.

To change a large batch of users to another authentication source, write to the database to change the information about those users in the rb_<WORKSPACE>.USERS table in MySQL, which is used by ProcessMaker to determine how to authenticate users.

Switching to a Different Authentication Source

If users' accounts have been transferred to a different LDAP or Active Directory server, then first create a new Authentication Source in ProcessMaker for the different LDAP or Active Directory server. Then, copy the unique ID (UID) for the new Authentication Source, by either clicking on its UID button in the list of Authentication Sources or by examining the rb_<WORKSPACE>.AUTHENTICATION_SOURCE.AUTH_SOURCE_UID field.

Then, enter ProcessMaker's MySQL database and find the records for the users in the rb_<WORKSPACE>.USERS table. Set the value of their rb_<WORKSPACE>.USERS.UID_AUTH_SOURCE field to the unique ID for the new Authentication Source. If the distinguished name (DN) chain for the users or their supervisors have changed, then also change the value of the USR_AUTH_USER_DN and USR_AUTH_SUPERVISOR_DN fields.

Note that the AUTH_SOURCE_PROVIDER field should always be set to "ldap" (or "ldapadvanced" for the Advanced LDAP plugin), regardless of whether using LDAP or Active Directory.

For example, the following SQL query could be used to convert all the users who were formerly using an LDAP server at myldap.com with the unique ID of "4715841884d653cf55cb807002425054" to newldap.net with the unique ID of "21232f297a57a5a743894a0e4a801fc3":

UPDATE rb_workflow.USERS SET UID_AUTH_SOURCE = '21232f297a57a5a743894a0e4a801fc3', 
   USR_AUTH_USER_DN = REPLACE(SR_AUTH_USER_DN, 'dc=myldap,dc=com', 'dc=newldap,dc=net'), 
   USR_AUTH_SUPERVISOR_DN = REPLACE(SR_AUTH_USER_DN, 'dc=myldap,dc=com', 'dc=newldap,dc=net')
   WHERE UID_AUTH_SOURCE = '4715841884d653cf55cb807002425054';

Converting to ProcessMaker's Internal Authentication

If users' accounts have been deleted in LDAP or Active Directory or the Authentication Source is no longer available, then the users' accounts in ProcessMaker have to be converted to use ProcessMaker's internal authentication. The users' records in the wf_<WORKSPACE>.USERS table and the rb_<WORKSPACE>.USERS table will need to be altered for internal authentication.

Enter ProcessMaker's MySQL database and find the records for users in the rb_<WORKSPACE>.USERS table. Set the value of their USR_AUTH_TYPE, UID_AUTH_SOURCE, USR_AUTH_USER_DN and USR_AUTH_SUPERVISOR_DN fields to "" (empty strings).

Then, set the new passwords for the users. One option is to insert an MD5 hash for the new passwords in the rb_<WORKSPACE>.USERS.USR_PASSWORD and wf_<WORKSPACE>.USERS.USR_PASSWORD fields. Alternatively, login to ProcessMaker as the "admin" (or any user with the PM_USERS permission in his role) and go to USERS > USERS LIST and edit the users' profiles to set new passwords.

For example, the following SQL query could be used to convert all the users who were formerly using an LDAP server at myldap.com with the unique ID of "4715841884d653cf55cb807002425054" to ProcessMaker's internal authentication:

UPDATE rb_workflow.USERS SET USR_AUTH_TYPE = '', UID_AUTH_SOURCE = '', USR_AUTH_USER_DN = '', 
   USR_AUTH_SUPERVISOR_DN = '' WHERE UID_AUTH_SOURCE = '4715841884d653cf55cb807002425054';

In ProcessMaker, the passwords for users are stored as MD5 hashes in the rb_<WORKSPACE>.USERS.USR_PASSWORD field. To convert all the users to ProcessMaker's internal authentication and make them all use the password "sample" (which can be useful for testing purposes), first find the MD5 hash, which is '5e8ff9bf55ba3508199d22e984129be6', then issue the SQL command:

UPDATE rb_workflow.USERS SET USR_PASSWORD = '5e8ff9bf55ba3508199d22e984129be6', USR_AUTH_TYPE = '', UID_AUTH_SOURCE = '', 
   USR_AUTH_USER_DN = '', USR_AUTH_SUPERVISOR_DN = '' WHERE UID_AUTH_SOURCE = '4715841884d653cf55cb807002425054';

Adding a Customized Authentication Source

In order to add customized authentication source type, such as OpenID, it is necessary to include:

• a php class that has the method that does the authentication validation in the following directory:

INSTALL-DIRECTORY/rbac/engine/classes/plugins

• An xml form where the information needed by the authentication method is defined:
  

INSTALL-DIRECTORY/workflow/engine/xmlform/authSources

For more details about the PHP class and the XML form please review the related files for LDAP:

INSTALL-DIRECTORY/rbac/engine/classes/plugins/class.ldap.php

INSTALL-DIRECTORY/workflow/engine/xmlform/authSources/ldapEdit.xml