LDAP authentication configuration
Bonita can be configured to perform user authentication against an LDAP server such as Active Directory, Apache Directory Server, or OpenLDAP.
For Subscription editions only. |
The configuration steps detailed in this page include some modifications to the Tomcat configuration. This is not compliant with the Application deployment mode introduced with Bonita 2023.2. If you want your application container to work with an Active Directory/LDAP authentication, you will need to build the docker image of the application first and then configure the container (using a volume for example). |
Important notes:
-
This documentation applies to an existing and working Bonita installation (see the installation instructions).
-
In order to have functioning Active Directory/LDAP authentication, the user login (username) must exist both in the LDAP directory and in the Bonita database (user password is checked against the LDAP server but user information is read from Bonita database). We recommend that you use the LDAP synchronizer to create Bonita users in a Bonita database.
Overview
This type of configuration relies on a specific implementation of the Bonita Engine authentication service that delegates the actual user name and password verification to a JAAS service configured with an LDAP specific Login Module.
Before you start
In order to configure LDAP successfully, make sure you have the following information:
-
LDAP server type: Active Directory (AD), Apache Directory Server, or OpenLDAP
-
LDAP server address
-
LDAP listening port (e.g. 389 by default)
-
Is it possible to build the user distinguished name with user name that the user specifies when logging in?
For example, if the user name is:john.smith
and the user DN is:CN=John Smith,CN=Users,DC=MyDomain,DC=com
, it’s not possible to build the DN dynamically. But it’s possible to do so if the DN is:uid=john.smith,ou=people,dc=example,dc=com
.
If it’s not possible to build the DN using the user name you will need the following extra information:-
The DN of the LDAP entry under which all users are located (e.g.
CN=Users,DC=MyDomain,DC=com
) -
The user entry objectClass (the most restrictive one). E.g. usually
user
on AD,inetOrgPerson
ororganizationalPerson
for other LDAP servers. -
The user entry attribute used for authentication (e.g.
userPrincipalName
on AD, value:john.smith@mydomain.com
oruid
on other LDAP servers, value:john.smith
)
-
-
Does the LDAP server allow anonymous search?
-
Does the LDAP server allow search for all users that can possibly log in?
-
If search can only be performed by a limited number of "technical" accounts you will need the user name and password of such an account.
-
If SSL security is required, ldaps server address FQDN, port and the certificate if provided
Create a JAAS configuration file
This section explains how to put together all the LDAP server information you have to create or edit a JAAS configuration file compatible with your JEE application server.
Login context name
The JAAS configuration can include one or several login contexts. The Bonita login context must be named BonitaAuthentication-<TENANT_ID>
(where <TENANT_ID>
is your tenant id).
LdapLoginModule attributes to set
It’s important to identify which LdapLoginModule
attributes you need to set.
This will be at least one of authIdentity
, userFilter
, tryFirstPass
, java.naming.security.principal
or java.naming.security.credentials
.
Based on the information described in the "Before you start" section, you can identify which of the following cases applies:
-
If you can build the user DN by directly injecting the user name => set only the
authIdentity
attribute -
If you cannot build the DN and anonymous search is allowed => set only the
userFilter
attribute -
If you cannot build the DN and anonymous search is disallowed and authenticated users can search => set the
userFilter
andauthIdentity
attributes -
If you cannot build the DN and anonymous search is disallowed and authenticated users cannot search => set the
userFilter
,authIdentity
,tryFirstPass
,java.naming.security.principal
andjava.naming.security.credentials
attributes
Values for LdapLoginModule attributes
In this section we explain how to set LdapLoginModule
attributes values. (For further information, check the LdapLoginModule
javadoc page.)
userProvider
: set this to ldap://<ldap server address>:<ldap server port>/<DN of the LDAP entry under which all users are located>
.
Spaces in the distinguished name (DN) component of the URL must be escaped using the standard mechanism of percent character ('%') followed by two hexadecimal digits: replace them with '%20'. Query components must also be omitted from the URL. |
For example, if your users are under CN=Bonita Users,DC=MyDomain,DC=com
: ldap://localhost:389/CN=Bonita%20Users,DC=MyDomain,DC=com
userFilter
(only if needed): the value must be a search request that will find your users in the LDAP server. The search request can be for example: (&(objectClass=user)(userPrincipalName={USERNAME}@mydomain.com))
.
Use an LDAP tool (such as Apache Directory Studio) to validate that the request returns the expected result if you replace {USERNAME} with an actual username.
authIdentity
(only if needed): there are two cases:
If you can build the user DN, set the attribute value with the user DN and {USERNAME}
tag. For example uid={USERNAME},ou=users,dc=example,dc=com
.
If you use a userFilter
and users are allowed to search, set the value with {USERNAME}@mydomain.com
for AD and user the DN (same as above) for other LDAP servers.
tryFirstPass
(only if needed): set this to true
.
java.naming.security.principal
(only if needed): specify the username (AD) or the user DN (other LDAP servers) of a user that can perform searches on the server.
java.naming.security.credentials
(only if needed): specify the password of a user that can perform searches on the server.
useSSL
Set this to true
if SSL is required, false
otherwise.
Create or edit the configuration file for your application server
All configuration files are case sensitive. You can find more examples in the JAAS configuration files examples section of this page. |
The JAAS configuration file follows the default JVM syntax.
Here is an example of JAAS configuration file:
BonitaAuthentication-1 { com.sun.security.auth.module.LdapLoginModule sufficient userProvider="ldap://localhost:389/ou=people,dc=example,dc=com" authIdentity="uid={USERNAME},ou=people,dc=example,dc=com" useSSL=false; };
We recommend that you name your JAAS configuration file jaas.cfg
and that you add the file under <BUNDLE_HOME>/server/conf
folder.
Configuration steps
Changing Bonita authentication service
The default Bonita installation comes with an authentication service implementation based on the Bonita Engine database. In
order to activate Active Directory/LDAP authentication the service implementation needs to be changed. To do this, edit bonita-tenant-sp-custom.properties
.
You will need to perform following changes:
-
Comment out the
authenticationService
line -
Add this new line:
authentication.service.ref.name=jaasAuthenticationService
Configure JAAS
To define the JAAS configuration file location you need to set a JVM property, java.security.auth.login.config
.
If you’re using a custom deployment into existing Tomcat
installation, you need to edit the setenv
script provided with Bonita and located in <BUNDLE_HOME>/server/bin
folder.
If you’re using the tomcat bundle
installation, you need to edit the setenv
script provided with Bonita and located in <BUNDLE_HOME>/setup/tomcat-templates
folder.
For Linux and Mac OS
-
Edit this file:
<BUNDLE_HOME>/setup/tomcat-templates/setenv.sh
-
Locate the line that starts:
#SECURITY_OPTS
-
Uncomment this line, i.e. remove the # sign and set property value to:
${CATALINA_HOME}/conf/jaas.cfg
-
Locate the line that starts:
CATALINA_OPTS=
-
Add the tag
${SECURITY_OPTS}
after the tag${PLATFORM_SETUP}
-
Push into database the changes:
./setup.sh push
For Windows
-
Edit this file:
<BUNDLE_HOME>/setup/tomcat-templates/setenv.bat
-
Locate the line that starts:
rem set SECURITY_OPTS
-
Uncomment it, i.e. remove "rem" keyword and set property value to:
%CATALINA_HOME%\conf\jaas.cfg
-
Locate the line that starts:
set CATALINA_OPTS=
-
Add the tag
%SECURITY_OPTS%
after the tag%PLATFORM_SETUP%
-
Push into database the changes:
.\setup.bat push
Configure SSL (optional)
It’s possible to allow authentication to ldap over SSL (ldaps).
First of all in the <BUNDLE_HOME>/server/conf/jaas.cfg
file you should use ldaps FQDN and port, and set useSSL
to true.
Then the following operations are required:
Create the keystore
You should have a certificate from the ldaps server (i.e. certificate.pem).
-
Create the following folder:
${CATALINA_HOME}/conf/SSL
. -
Put the certificate.pem file into this folder.
-
Move to this directory and create a keystore with the keytool command (keytool is part of JDK):
keytool -importcert -alias yourAlisaName -file certificate.pem -keystore certificateStore.jks
-
Choose a password for your keystore (here we call it keyStorePassword)
-
Answer to the questions and at the end verify that the truststore (i.e. certificateStore.jks) has been created correctly
Share the truststore with Tomcat
-
Edit this file:
<BUNDLE_HOME>/setup/tomcat-templates/setenv.sh
(Linux) or<BUNDLE_HOME>/setup/tomcat-templates/setenv.bat
(Windows) -
Add the following line after the one that starts with set
SECURITY_OPTS
:Linux: SSL_OPTS="-Djavax.net.ssl.trustStore=pathToTruststore -Djavax.net.ssl.trustStorePassword=keyStorePassword" Windows: set SSL_OPTS="-Djavax.net.ssl.trustStore=pathToTruststore -Djavax.net.ssl.trustStorePassword=keyStorePassword"
-
Replace the
pathToTruststore
andkeyStorePassword
with the proper values -
Locate the line that starts with CATALINA_OPTS (Linux) or set CATALINA_OPTS (Windows)
-
(Linux) Add the tag
${SSL_OPTS}
after the tag${INCIDENT_LOG_DIR}
-
(Windows) Add the tag
%SSL_OPTS%
after the tag%INCIDENT_LOG_DIR%
JAAS configuration files examples
Remember to remove the debug flag for production. |
These examples use the JAAS standard syntax (as used by Tomcat). |
Active Directory
Search allowed for all users
In this example, the user name is john.smith:
BonitaAuthentication-1 { com.sun.security.auth.module.LdapLoginModule sufficient userProvider="ldap://localhost:389/CN=Users,DC=MyDomain,DC=com" userFilter="(&(objectClass=user)(userPrincipalName={USERNAME}@mydomain.com))" authIdentity="{USERNAME}@mydomain.com" debug=true useSSL=false; };
In this example, the user name is john.smith@mydomain.com
:
BonitaAuthentication-1 { com.sun.security.auth.module.LdapLoginModule sufficient userProvider="ldap://localhost:389/CN=Users,DC=MyDomain,DC=com" userFilter="(&(objectClass=user)(userPrincipalName={USERNAME}))" authIdentity="{USERNAME}" debug=true useSSL=false; };
Search allowed only for a technical users
In this example, the user name is john.smith:
BonitaAuthentication-1 { com.sun.security.auth.module.LdapLoginModule sufficient userProvider="ldap://localhost:389/CN=Users,DC=MyDomain,DC=com" userFilter="(&(objectClass=user)(userPrincipalName={USERNAME}@mydomain.com))" tryFirstPass=true java.naming.security.principal="technical.user@mydomain.com" java.naming.security.credentials="technical_user_password" debug=true useSSL=false; };
Known limitations
The Active Directory configuration has been tested in single domain configuration. If you a running with multiple domains it’s likely that the user will have to type a username including domain name when logging in.
Troubleshooting
If necessary, you can edit your configuration to have additional logs (please note, a server restart will be required for the new configuration to be taken into account, though):
-
Enable JAAS debug mode by editing your JAAS configuration file (e.g.
<TOMCAT_HOME>/server/conf/jaas.cfg
) and adding the following line:debug=true
-
Enable java’s SSL/TLS connection debug mode by editing your application server’s environment setting file (e.g.
<TOMCAT_HOME>/setup/tomcat-templates/setenv.sh(.bat)
) and adding the following system property to the java options:-Djavax.net.debug=all