Configure the Full Distribution for Tomcat

This page explains how to configure the full distribution for Tomcat Application Server.

LDAP

In order to setup LDAP for the Tomcat distribution, you have to perform the following steps:

Add the LDAP Library

Make sure the camunda-identity-ldap-$PLATFORM_VERSION.jar is present in the $TOMCAT_DISTRIBUTION/lib/ folder.

Adjust the Process Engine Configuration

Edit the file bpm-platform.xml located inside the folder $TOMCAT_HOME/conf and add the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform xmlns="http://www.camunda.org/schema/1.0/BpmPlatform"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.camunda.org/schema/1.0/BpmPlatform http://www.camunda.org/schema/1.0/BpmPlatform ">
  ...
  <process-engine name="default"> ...
    <properties>...</properties>
    <plugins>
      <plugin>
        <class>org.cibseven.bpm.identity.impl.ldap.plugin.LdapIdentityProviderPlugin</class>
        <properties>

          <property name="serverUrl">ldap://localhost:4334/</property>
          <property name="managerDn">uid=jonny,ou=office-berlin,o=camunda,c=org</property>
          <property name="managerPassword">s3cr3t</property>

          <property name="baseDn">o=camunda,c=org</property>

          <property name="userSearchBase"></property>
          <property name="userSearchFilter">(objectclass=person)</property>

          <property name="userIdAttribute">uid</property>
          <property name="userFirstnameAttribute">cn</property>
          <property name="userLastnameAttribute">sn</property>
          <property name="userEmailAttribute">mail</property>
          <property name="userPasswordAttribute">userpassword</property>

          <property name="groupSearchBase"></property>
          <property name="groupSearchFilter">(objectclass=groupOfNames)</property>
          <property name="groupIdAttribute">ou</property>
          <property name="groupNameAttribute">cn</property>

          <property name="groupMemberAttribute">member</property>

        </properties>
      </plugin>
      <plugin>
        <class>org.cibseven.bpm.engine.impl.plugin.AdministratorAuthorizationPlugin</class>
        <properties>
          <property name="administratorUserName">admin</property>
        </properties>
      </plugin>
    </plugins>
  </process-engine>
</bpm-platform>

The administratorUserName property should contain the user id of the LDAP user you want to grant administrator authorizations to. You can then use this user to log in to the web application and grant authorizations to additional users.

See our user guide for complete documentation on the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

HAL Resource Caching

If you use LDAP as Indentity Provider, you should consider activating caching of Users and Groups in the Camunda webapplication. In order to activate this, add the following configuration to the web.xml file of Camunda webapplication (camunda-webapp-tomcat-$PLATFORM_VERSION.war/WEB-INF/web.xml):

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <!-- ... -->

  <listener>
    <listener-class>org.cibseven.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>

  <context-param>
    <param-name>org.cibseven.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "org.cibseven.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "org.cibseven.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.cibseven.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          }
        }
      }
    </param-value>
  </context-param>

  <!-- ... -->

</web-app>

Composite authentication for REST API and CIB seven Webapp

The REST API ships with an implementation of Composite Authentication, allowing authentication providers to be combined seamlessly. It is configured as a combination of JWT-based authentication and HTTP Basic authentication, where JWT is the primary mechanism and HTTP Basic acts as a fallback.

By default it is switched off, but you can activate it by adding a servlet filter under WEB-INF/web.xml as described in the Authentication section.

Additionally, as explained in the referred section, a JWT secret must be defined. By default, it is defined in a cibseven-webclient.properties file placed on the classpath, which in Tomcat means the $CATALINA_HOME/lib folder. The start-cibseven.sh / start-cibseven.bat script of the CIB seven Tomcat distribution generates this file on the first start, with a random secret. On a vanilla Tomcat, you have to create it yourself, or use one of the alternatives described in the referred section.

CIB seven Webapp fine-tuning

CIB seven webapp properties can be configured by editing the application.yaml file. In a packaged WAR deployment, this file is located under WEB-INF/classes.

However, you do not need to modify the WAR file. The webapp also reads the files cibseven-webclient.properties and cibseven-webclient.yaml from the Tomcat classpath, and properties passed as JVM system properties or environment variables override the ones defined in the application.yaml file. This means that you can set the properties in any of the following ways:

• Place a cibseven-webclient.yaml file in the $CATALINA_HOME/lib folder.

• Add the properties to the cibseven-webclient.properties file in the $CATALINA_HOME/lib folder. This file also holds the JWT secret by default, as described in the Composite authentication section.

• Pass the properties as -D options in CATALINA_OPTS, for example in bin/setenv.sh:

  CATALINA_OPTS="$CATALINA_OPTS -Dcibseven.webclient.sso.active=true"
  

  or in bin/setenv.bat:

  set "CATALINA_OPTS=%CATALINA_OPTS% -Dcibseven.webclient.sso.active=true"
  

• Set environment variables, for example CIBSEVEN_WEBCLIENT_SSO_ACTIVE=true.

Session Cookie in legacy Camunda Webapp

To configure the Session Cookie, you can adjust the deployment descriptor of the Web applications. You can find it in the WEB-INF/web.xml in the following section:

...
<session-config>
  <cookie-config>
    <secure>false</secure>
    <http-only>true</http-only>
  </cookie-config>
</session-config>
...

Please note that security-related configurations for the Session Cookie can only be applied with the Deployment Descriptor (web.xml) version set to 3.0.

To customize the SameSite attribute of the session cookie, you can adjust the SessionCookieFilter. You can find it in the WEB-INF/web.xml as well in the following section:

...
<filter>
  <filter-name>SessionCookieFilter</filter-name>
  <filter-class>org.cibseven.bpm.webapp.impl.security.filter.SessionCookieFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>SessionCookieFilter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>
...

By default, the SameSite flag will be set to LAX by the filter. You can change the default behavior by adding configuration parameters to the servlet filter configuration:

...
<filter>
  <filter-name>SessionCookieFilter</filter-name>
  <filter-class>org.cibseven.bpm.webapp.impl.security.filter.SessionCookieFilter</filter-class>
  <init-param>
    <param-name>sameSiteCookieValue</param-name>
    <param-value>Strict</param-value>
  </init-param>
</filter>
...

Note that the filter only adds the SameSite attribute to the cookie if this attribute is not present yet. It does not alter any existing value that has been set prior to the filter execution.

The servlet filter accepts several initialization parameters besides the one describes above. The following list describes all possible parameters you can use for the filter configuration:

Please also see the detailed overview about the Cookie Security.

Security-related HTTP headers in legacy Camunda Webapp

To customize the configuration of security-related HTTP headers in the web applications its deployment descriptor needs to be adjusted. You can find it under WEB-INF/web.xml.

Please watch out for the following section:

...
<filter>
  <filter-name>HttpHeaderSecurity</filter-name>
  <filter-class>
    org.cibseven.bpm.webapp.impl.security.filter.headersec.HttpHeaderSecurityFilter
  </filter-class>
</filter>

<filter-mapping>
  <filter-name>HttpHeaderSecurity</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>
...

You can change the default behavior by adding configuration parameters to the servlet filter configuration:

...
<filter>
  <filter-name>HttpHeaderSecurity</filter-name>
  <filter-class>
    org.cibseven.bpm.webapp.impl.security.filter.headersec.HttpHeaderSecurityFilter
  </filter-class>
  
  <init-param>
    <param-name>contentSecurityPolicyValue</param-name>
    <param-value>
      base-uri 'self';
      default-src 'self' 'unsafe-inline'
    </param-value>
  </init-param>
  
</filter>
...

Please also see the detailed overview about the HTTP Header Security configuration settings.