LDAPSynchronizer & LDAPAuthenticator
for BonitaBPM Community

In most cases when you implement business processes in your organization you want to integrate it with your LDAP server for users authentication. Unfortunately, BonitaBPM Community edition doesn't support such integration out of the box. That's why I decided to provide this module for you! It consists of one process responsible for synchronization of users accounts with LDAP and additional library which authenticates users in LDAP when they log into BonitaBPM Portal (it is necessary because user password is stored only in LDAP). This module is really easy to implement (and modify if needed).
LDAPSynchronizer and LDAPAuthenticator are designed to bring LDAP integration into BonitaBPM Community Version. Together they provide periodical synchronization of users between LDAP and BonitaBPM and allows users to log into BonitaBPM Portal using LDAP password. Both modules can be also used separately if it is desirable from business point of view (to get more information about that please contact me).
To implement this module in BonitaBPM you need to follow these steps:
1. Download and unpack module files.
2. Import .bos file into your BonitaBPM Studio workspace.
3. Configure process parameters (LDAP connection data, mapping data and so on...)
4. Change execution schedule (optional).
5. Export process (build .bar file).
6. Upload process to your BonitaBPM system.
7. Set BonitaBPM to use LDAPAuthenticator class.
Warning: Always remember to test processes first on your developement environment!

Step 1 - Download and unpack module files.

This module was tested with BonitaBPM 7.8.4 version but should work fine with all BonitaBPM 7.x versions.

Step 2 - Import .bos file into your BonitaBPM Studio workspace.

1. Open BonitaBPM Studio (process designer).
2. Click 'File' -> 'Import' -> 'BOS archive'.
3. Browse for unpacked .bos file.
4. Click 'Import'. Import status dialog should be shown when finished.

Step 3 - Configure process parameters.

1. Click on LDAPSynchronizer pool or lane.
2. Click 'Configure' icon on top of the window and select 'Parameters' on the left side.
3. Set all parameters according to your needs. Below you can find description for all parameters.
Administrator notifications parameters:
admin_notify_on_success - Required. Determines whether to send notification email after successful synchronization or not.
admin_notify_on_error - Required. Determines whether to send notification email after failure or not.
SMTP parameters (required if 'admin_notify_on_success' or 'admin_notify_on_error' is set to 'true'):
smtp_host - Optional. SMTP server address.
smtp_port - Optional. SMTP server port.
smtp_use_ssl - Optional. Determines whether to use SSL when connecting to SMTP server.
smtp_use_starttsl - Optional. Determines whether to use STARTTSL when connecting to SMTP server.
smtp_user - Optional. SMTP server user.
smtp_pass - Optional. SMTP server user password.
smtp_notification_sender - Optional. Email sender (shown in 'from' field in email).
smtp_notification_receiver - Optional. Email receiver.
BonitaBPM parameters:
bonita_default_userprofile - Required. Determines which profile should be connected with created users. Each user must be mapped with profile to be able to login. In Bonita Community there is one profile predefined for standard users and it is named 'user'.
bonita_default_usergroup - Required. Determines which group should be connected with created users. It is good practice to have one group containing all users (for easy use in administration and processes).
bonita_default_grouprole - Required. Determines the name of role that will be set when user is added to the group. You can also specify other roles by mapping them from LDAP (see 'ldap_mapping_roles' parameter).
bonita_nonexisting_users_deactivate - Required. Determines whether to deactivate users that does not exists in LDAP but are already created in BonitaBPM.
bonita_nonexisting_groups_delete - Required. Determines whether to delete groups that does not exists in LDAP but are already created in BonitaBPM.
bonita_synchronization_excluded_users - Optional. Users (usernames separated by comma) that exists in BonitaBPM but should not be synchronized with LDAP (for example administrator account).
bonita_synchronization_excluded_groups - Optional. Groups (names separated by comma) that exists in BonitaBPM but should not be synchronized with LDAP (for example administrators group).
bonita_fake_userpassword - Required. Password that will be stored in BonitaBPM database for each created user. If you also configure LDAPAuthenticator it is only technical value. Otherwise it will be used by users as default password (to change after first login!)
bonita_override_user_password - Required. Determines whether to override user password with the one stored in 'bonita_fake_userpassword'. If you want to use LDAPAuthenticator set it to 'true', otherwise to 'false'.
LDAP connection parameters:
ldap_connection_host - Required. LDAP server address.
ldap_connection_port - Required. LDAP server port.
ldap_connection_user - Required. LDAP user uid (user must have sufficient privileges in LDAP).
ldap_connection_pass - Required. LDAP user password.
LDAP search and mapping parameters:
ldap_groups_search_dn - Required. Root element of LDAP tree to search for groups (DN).
ldap_groups_search_filter - Required. LDAP query string to filter only valid group entries.
ldap_groups_name_attribute - Required. LDAP attribute that stores group name (will be used as BonitaBPM group name).
ldap_groups_member_attribute - Required. LDAP attribute that stores group members (will be used to map users into groups and to create groups hierarchy if needed).
ldap_users_search_dn - Required. Root element of LDAP tree to search for users (DN).
ldap_users_search_filter - Required. LDAP query string to filter only valid user entries.
ldap_mapping_username - Required. LDAP attribute that stores username (will be used as BonitaBPM username).
ldap_mapping_firstname - Optional. LDAP attribute that stores first name (will be used as BonitaBPM user first name).
ldap_mapping_lastname - Optional. LDAP attribute that stores last name (will be used as BonitaBPM user last name).
ldap_mapping_manager - Optional. LDAP attribute that stores manager (will be used to map supervisor in BonitaBPM).
ldap_mapping_jobtitle - Optional. LDAP attribute that stores job title (will be used as BonitaBPM user job title).
ldap_mapping_title - Optional. LDAP attribute that stores user title (will be used as BonitaBPM user title).
ldap_mapping_pro_email - Optional. LDAP attribute that stores user email (will be used as BonitaBPM user professional data).
ldap_mapping_pro_address - Optional. LDAP attribute that stores user address (will be used as BonitaBPM user professional data).
ldap_mapping_pro_zipcode - Optional. LDAP attribute that stores user zipcode (will be used as BonitaBPM user professional data).
ldap_mapping_pro_city - Optional. LDAP attribute that stores user city (will be used as BonitaBPM user professional data).
ldap_mapping_pro_state - Optional. LDAP attribute that stores user state (will be used as BonitaBPM user professional data).
ldap_mapping_pro_country - Optional. LDAP attribute that stores user country (will be used as BonitaBPM user professional data).
ldap_mapping_pro_building - Optional. LDAP attribute that stores user building (will be used as BonitaBPM user professional data).
ldap_mapping_pro_room - Optional. LDAP attribute that stores user room (will be used as BonitaBPM user professional data).
ldap_mapping_pro_phone - Optional. LDAP attribute that stores user phone (will be used as BonitaBPM user professional data).
ldap_mapping_pro_mobil - Optional. LDAP attribute that stores user mobile (will be used as BonitaBPM user professional data).
ldap_mapping_pro_fax - Optional. LDAP attribute that stores user fax (will be used as BonitaBPM user professional data).
ldap_mapping_pro_website - Optional. LDAP attribute that stores website email (will be used as BonitaBPM user professional data).
ldap_mapping_perso_email - Optional. LDAP attribute that stores user email (will be used as BonitaBPM user personal data).
ldap_mapping_perso_address - Optional. LDAP attribute that stores user address (will be used as BonitaBPM user personal data).
ldap_mapping_perso_zipcode - Optional. LDAP attribute that stores user zipcode (will be used as BonitaBPM user personal data).
ldap_mapping_perso_city - Optional. LDAP attribute that stores user city (will be used as BonitaBPM user personal data).
ldap_mapping_perso_state - Optional. LDAP attribute that stores user state (will be used as BonitaBPM user personal data).
ldap_mapping_perso_country - Optional. LDAP attribute that stores user country (will be used as BonitaBPM user personal data).
ldap_mapping_perso_building - Optional. LDAP attribute that stores user building (will be used as BonitaBPM user personal data).
ldap_mapping_perso_room - Optional. LDAP attribute that stores user room (will be used as BonitaBPM user personal data).
ldap_mapping_perso_phone - Optional. LDAP attribute that stores user phone (will be used as BonitaBPM user personal data).
ldap_mapping_perso_mobile - Optional. LDAP attribute that stores user mobile (will be used as BonitaBPM user personal data).
ldap_mapping_perso_fax - Optional. LDAP attribute that stores user fax (will be used as BonitaBPM user personal data).
ldap_mapping_perso_website - Optional. LDAP attribute that stores website email (will be used as BonitaBPM user personal data).
ldap_mapping_roles - Optional. LDAP attribute that stores user roles (will be used to set user roles in groups that he belongs to, in addition to default role set in 'bonita_default_grouprole' parameter).

Step 4 - Change execution schedule (optional).

1. Click on process start event.
2. Go to "General" properties tab.
3. Click 'Edit' on the right of 'Timer Condition' field. Predefined value sets the synchronization time on 23:15 every day.
4. Click 'Finish' when new Timer Condition is ready.

Step 5 - Export process.

1. Click 'Server' -> 'Build'.
2. Select LDAPSynchronizer process, choose destination folder and click 'Finish'.
3. Build finish dialog dialog should be shown when finished.

Step 6 - Upload process to your BonitaBPM system.

1. Log into BonitaBPM Portal as an administrator user.
2. Go to 'BPM' -> 'Processes' -> and click '+INSTALL'.
3. Browse for exported .bar file and click 'Install'
4. To activate process click on 'Disabled' switcher next to 'Activation state' field.

Step 7 - Set BonitaBPM to use LDAPAuthenticator class.

1. Change parameters in LDAPAuthenticator.config file and move it into some location on the server. Then set environmental variable called "BONITA_LDAPSYNCHRONIZER_CONFIG" with value "PATH_ON_SERVER/LDAPAuthenticator.config"*. 2. Copy .jar file to your BonitaBPM server libs folder (for example on Tomcat server copy .jar file to 'TOMCAT_BASE_DIR\webapps\bonita\WEB-INF\lib\').
3. Use BonitaBPM platform setup tool to change default authentication manager implementation to the one provided in this library:
    - In command line go to 'BONITABPM_BASE_FOLDER/setup/'.
    - Run setup program with pull option to get current config.
    - Open file 'BONITABPM_BASE_FOLDER/setup/platform_conf/current/tenants/1/tenant_portal/authenticationManager-config.properties'.
    - Change current value 'auth.AuthenticationManager=org.bonitasoft.console.common.server.auth.impl.standard.StandardAuthenticationManagerImpl' to 'auth.AuthenticationManager=help.bpms.bonita.authentication.ldap.LdapAuthenticationManagerImpl'.
    - Run setup program with push option to save changed config.
    - Restart BonitaBPM server.
* Alternatively you can store config file directly inside jar library (it already contains LDAPAuthenticator.config file with default values). The best way to edit config file inside .jar library is to use application that allows to edit compressed files 'on fly' (for example Total Commander). But you can also do it manually, by changing file extansion to zip, unpack, modify config file, pack again to zip and change extension back to .jar.

Congratulations - you have finished the configuration!