SSL

Product version:
7.2, 7.1, 7.0
Product edition:
  • Community
  • Teamwork
  • Efficiency
  • Performance
Get the PDF version

Configuring SSL for Bonita BPM 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 examples of how to set up SSL for Bonita BPM. This enables you to use secure HTTP (HTTPS) to access the portal.

Overview
Examples
JBoss with a keystore
Tomcat with OpenSSL
Tomcat with a keystore
Tomcat and SSL Offloading

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:

  1. Create a certificate for your system.
  2. Update your application server configuration to enable SSL.
  3. 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.

JBoss with keystore

This example shows how to configure SSL with a keystore for JBoss 5. For details of how to set up SSL with JBoss 7, see the SSL Configuration HOW-TO on the JBoss 7 web site.

  1. Run the Java keytool to create a certificate and store it in the keystore. (Note: if you are using Windows, you need to run keytool as administrator.)
  2. keytool -genkey -alias tomcat -keyalg RSA -keystore conf/ssl/keystore
  3. Answer the questions that keytool asks. When asked for your first name and last name, provide the hostname of your system.
  4. Edit server/default/deploy/jbossweb.sar/server.xml and include the following configuration for the Connector:
  5. <Connector port="8443"
    protocol="HTTP/1.1"
    SSLEnabled="true"
    maxThreads="150"
    scheme="https"
    secure="true"
    SSLVerifyClient="optional"
    SSLProtocol="TLSv1"
    URIEncoding="UTF-8"
    keyAlias="<HOST>"
    keystoreFile="<JRE_HOME>/lib/security/cacerts"
    keystorePass="<PASSWORD>"
    truststoreFile="<JRE_HOME>/lib/security/cacerts"
    truststorePass="<PASSWORD>"
    />
  6. Go to /server/default/deploy.
  7. Unzip the bonita-all-in-one-VERSION.ear EAR file.
  8. At the root, open the bonita.war WAR file.
  9. Edit /WEB-INF/web.xml and add the following security definition:
  10. <web-app>
       ...
       <security-constraint>
          <web-resource-collection>
             <web-resource-name>Bonita Portal 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>
  11. Rezip the WAR file, then rezip the EAR.
  12. Start JBoss:
  13. ./bin/run.sh
  14. 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 with APR and OpenSSL

This example show how to configure SSL with APR and OpenSSL for a Bonita BPM using Tomcat.

  1. Go to the TOMCAT_HOME/conf directory and create a directory called ssl to store certificate files.
  2. Create the self-signed certificate and its private key using openssl:
  3. openssl req -new -x509 -days 365 -nodes -out conf/ssl/test.bonitasoft.net.pem -keyout conf/ssl/test.bonitasoft.net.key
  4. Provide the information about your system that openssl requires.
  5. Edit conf/server.xml and add the following definition for the Connector:
  6. <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"></Connector>
  7. Install the Tomcat native library, which contains APR:
  8. sudo apt-get install libtcnative-1
  9. Edit TOMCAT_HOME/webapps/bonita/WEB-INF/web.xml and add the following security definition:
  10. <web-app>
       ...
       <security-constraint>
          <web-resource-collection>
             <web-resource-name>Bonita Portal 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>
  11. Start Tomcat:
  12. ./bin/startup.sh
  13. 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 BPM on Tomcat.

  1. Run the Java keytool to create a certificate and store it in the keystore. (Note: if you are using Windows, you need to run keytool as administrator.)
  2. keytool -genkey -alias tomcat -keyalg RSA -keystore conf/ssl/keystore
  3. Answer the questions that keytool asks. When asked for your first name and last name, provide the hostname of your system.
  4. Edit conf/server.xml and include the following configuration for the Connector:
  5. <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>
  6. Edit TOMCAT_HOME/webapps/bonita/WEB-INF/web.xml and add the following security definition:
  7. <web-app>
       ...
       <security-constraint>
          <web-resource-collection>
             <web-resource-name>Bonita Portal 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>
  8. Start Tomcat:
  9. ./bin/startup.sh
  10. 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).

  1. Make sure that your load balancer adds X-Forwarded-Proto and X-Forwarded-For headers. If you use HAProxy you can add following lines into your HAProxy configuration :
  2. option forwardfor
    reqadd X-Forwarded-Proto:\ https
  3. Edit conf/server.xml and include the RemoteIpValve configuration for the host:
  4. <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"
     />

    Note: 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")."

  5. If you use the AccessLogValve, edit conf/server.xml and set requestAttributesEnabled="true":
  6.         <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.
Get the PDF version
Last update on Jan, 21 2016