SSL configuration
It is possible to set up SSL in your Bonita server. This enables you to use secure HTTP (HTTPS) to access the Bonita Applications which is recommended.
Configuring SSL for Bonita is the same as configuring it for any other application. No changes are necessary to forms or to process definitions, just configuration. This page contains some configuration examples.
Overview
If you are using an HTTP load balancer, configure it to handle SSL connections. Otherwise, configure it in the application server.
To configure your system to use SSL:
-
Create a certificate for your system.
-
Update your application server configuration to enable SSL.
-
Update the Bonita web application to add the security definition.
The details of each step depend on your application server and SSL implementation. See your application server documentation for details.
There are some examples below. In these examples:
-
We use the default application server SSL port number, 8443, for connections. If you use this port number, it needs to be specified in the URL by users. If you use the default HTTPS port number, 443, users do not need to specify the port in the URL.
-
You must ensure that the SSL connector is configured with the parameter
URIEncoding="UTF-8"
. -
When the configuration is complete, the web application is only available through HTTPS. For other configuration, allowing both HTTP and HTTPS access, see your application server or SSL service documentation.
-
The operating system is Ubuntu.
-
The starting point is a bundle that has been installed and configured but not started.
Tomcat with APR and OpenSSL
This example show how to configure SSL with APR and OpenSSL for a Bonita using Tomcat.
-
Go to the
BUNDLE_HOME/conf
directory and create a directory calledssl
to store certificate files. -
Create the self-signed certificate and its private key using
openssl
:
openssl req -new -x509 -days 365 -nodes -out conf/ssl/test.bonitasoft.net.pem -keyout conf/ssl/test.bonitasoft.net.key
-
Provide the information about your system that
openssl
requires. -
Edit
conf/server.xml
and add the following definition for the Connector:<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" URIEncoding="UTF-8" SSLCertificateFile="${catalina.base}/conf/ssl/test.bonitasoft.net.pem" SSLCertificateKeyFile="${catalina.base} /conf/ssl/test.bonitasoft.net.key" SSLVerifyClient="optional" SSLProtocol="TLSv1.2"> </Connector>
-
Install the Tomcat native library, which contains APR:
sudo apt-get install libtcnative-1
-
Edit
BUNDLE_HOME/webapps/bonita/WEB-INF/web.xml
and add the following security definition:<web-app> ... <security-constraint> <web-resource-collection> <web-resource-name>Bonita Applications Secure URLs</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> </web-app>
-
Start Tomcat:
./bin/startup.sh
-
Check that everything is correctly configured, by opening
https://127.0.0.1:8443/bonita
in your browser. Your browser should warn you about the self-signed certificate used to perform the HTTPS connection. You can safely add this self-signed certificate to the exceptions allowed.
Tomcat with a keystore
This example shows how to configure SSL with a keystore for Bonita on Tomcat.
-
Run the Java
keytool
to create a certificate and store it in the keystore. (Note: if you are using Windows, you need to runkeytool
as administrator.)keytool -genkey -alias tomcat -keyalg RSA -keystore conf/ssl/keystore
-
Answer the questions that
keytool
asks. When asked for your first name and last name, provide the hostname of your system. -
Edit
conf/server.xml
and include the following configuration for the Connector:<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" URIEncoding="UTF-8" keystoreFile="${catalina.base}/conf/ssl/keystore" keystorePass="password!" SSLVerifyClient="optional" SSLProtocol="TLSv1"></Connector>
-
Edit
BUNDLE_HOME/webapps/bonita/WEB-INF/web.xml
and add the following security definition:<web-app> ... <security-constraint> <web-resource-collection> <web-resource-name>Bonita Applications Secure URLs</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> </web-app>
-
Start Tomcat:
./bin/startup.sh
-
Check that everything is correctly configured, by opening
https://127.0.0.1:8443/bonita
in your browser. Your browser should warn you about the certificate used to perform the HTTPS connection. You can safely add this certificate to the exceptions allowed.
Tomcat and SSL Offloading
This example shows you how to configure SSL if you run Tomcat behind a load balancer that features in SSL Accelerator or Offloading (sometimes called SSL Termination).
-
Make sure that your load balancer adds
X-Forwarded-Proto
andX-Forwarded-For
headers. If you use HAProxy you can add following lines into your HAProxy configuration :option forwardfor reqadd X-Forwarded-Proto:\ https
-
Edit
conf/server.xml
and include theRemoteIpValve
configuration for the host:<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"> <Valve className="org.apache.catalina.valves.RemoteIpValve" internalProxies="172\.31\.\d{1,3}\.\d{1,3}" remoteIpHeader="X-Forwarded-For" protocolHeader="X-Forwarded-Proto" />
Make sure that the regular expression set with internalProxies
matches your IP addresses.As explained by the RemoteIpValve documentation: "This valve replaces the apparent client remote IP address and hostname for the request with the IP address list presented by a proxy or a load balancer via a request headers (e.g. "X-Forwarded-For"). Another feature of this valve is to replace the apparent scheme (http/https) and server port with the scheme presented by a proxy or a load balancer via a request header (e.g. "X-Forwarded-Proto")."
-
If you use the AccessLogValve, edit
conf/server.xml
and setrequestAttributesEnabled="true"
:<Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log." suffix=".txt" requestAttributesEnabled="true" pattern="%a %{X-Forwarded-Proto}i %l %u %t "%r" %s %b" />
If you omit this, %a will log your load balancer’s IP address and not the client’s IP address.
Secure the CSRF protection cookie
The secure flag on the X-Bonita-API-Token
cookie should be set when using HTTPS.
Activating the secure flag can be done in the file security-config.properties
for the whole platform.
The default version of this file is located in setup/platform_conf/initial/platform_portal
. In order to change the configuration on an installation whose platform has already been initialized, use the platform setup tool to retrieve the current configuration and update the file in setup/platform_conf/current/platform_portal
. Then use the tool again to save your changes into to the database.
To activate the addition of the secure flag, edit the configuration file and change the security.csrf.cookie.secure
value to true.
For more information on this cookie see CSRF security.
Troubleshooting
Symptom:
The following stacktrace appears in the Bonita Runtime log:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
Cause:
This issue arises for one of these reasons:
-
You are using a self-signed certificate
-
You are using a certificate that has been issued by an internal certificate authority
-
Your certificate is outdated
Solutions:
-
Make sure you have imported the public certificate of the target instance into the truststore according to the Connecting to SSLServices instructions listed above
-
Make sure any certificates have been imported into the correct truststore; you may have multiple JRE/JDKs
-
Check to see that the correct truststore is in use. If
-Djavax.net.ssl.trustStore
has been configured, it will override the location of the default truststore, which will need to be checked -
Check if your Antivirus tool has "SSL Scanning" blocking SSL/TLS. If it does, disable this feature temporarily or, preferably, set exceptions for the target addresses
-
Verify that the target server is configured to serve SSL correctly. This can be done with an SSL Server Test tool
-
Make sure you used keytool to install the new certificate. More info online.
-
Make sure your truststore is not out of date