Configure Authentication
Composite Authentication
From version 2.0.0, the REST API ships with an implementation of Composite Authentication, allowing authentication providers to be combined seamlessly. By default, this is implemented as a combination of JWT-based authentication and HTTP Basic authentication, where JWT is the primary mechanism and HTTP Basic acts as a fallback.
This setup enables secure communication between the engine and the CIB seven web application. By default, it is switched off but can be activated by adding a servlet filter as follows:
<filter>
<filter-name>cibseven-composite-auth</filter-name>
<filter-class>
org.cibseven.bpm.engine.rest.security.auth.ProcessEngineAuthenticationFilter
</filter-class>
<async-supported>true</async-supported>
<init-param>
<param-name>authentication-provider</param-name>
<param-value>
org.cibseven.bpm.engine.rest.security.auth.impl.CompositeAuthenticationProvider
</param-value>
</init-param>
<init-param>
<param-name>rest-url-pattern-prefix</param-name>
<param-value></param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/process-definition/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/process-instance/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/history/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/execution/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/batch/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/decision-definition/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/deployment/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/filter/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/incident/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/job-definition/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/job/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/telemetry/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/metrics/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/authorization/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/group/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/user/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/message/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/event-subscription/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/variable-instance/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/task/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/engine/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>cibseven-composite-auth</filter-name>
<url-pattern>/identity/groups</url-pattern>
</filter-mapping>
As noted in the web.xml, the /identity/verify endpoint is the only one that should remain unfiltered, and therefore should be explicitly excluded from the authentication filter configuration. All other requests will be authenticated using the JWT provided in the request header.
JWT-based authentication requires a shared secret to validate the incoming tokens, so you must create a file named cibseven-webclient.properties on the classpath. This configuration file should define the following property with a 155-character alphanumeric secret value:
cibseven.webclient.authentication.jwtSecret=...
An alternative method for setting the JWR secret is to use the environment variable CIBSEVEN_WEBCLIENT_AUTHENTICATION_JWTSECRET. In this case, the value specified in the environment variable takes precedence over the value from the cibseven-webclient.properties file.
In the pre-built distributions, the engine authentication is switched off by default. You may have a look at the distribution’s web.xml file, comment out the cibseven-pseudo-auth filter and remove the comment markers from the above mentioned filter declaration to activate JWT-based authentication.
HTTP Basic Authentication
Please note that relying solely on HTTP Basic Authentication may have consequences when using the CIB seven web application. Therefore, it is strongly recommended to use Composite Authentication.
The REST API ships with an implementation of HTTP Basic Authentication. By default it is switched off, but can be activated by adding a servlet filter as follows:
<filter>
<filter-name>cibseven-auth</filter-name>
<filter-class>
org.cibseven.bpm.engine.rest.security.auth.ProcessEngineAuthenticationFilter
</filter-class>
<async-supported>true</async-supported>
<init-param>
<param-name>authentication-provider</param-name>
<param-value>org.cibseven.bpm.engine.rest.security.auth.impl.HttpBasicAuthenticationProvider</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>cibseven-auth</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
Any engine-specific request will then be authenticated against that engine’s identity service. The GET /engine request that supplies a list of all available process engines is the only request that does not require authentication. Any request that does not address a specific engine (i.e., it is not of the form /engine/{name}/...) will be authenticated against the default engine.
In the pre-built distributions, the engine authentication is switched off by default. You may have a look at the distribution’s web.xml file and, comment out the cibseven-pseudo-auth filter and add the above mentioned filter declaration to activate HTTP Basic authentication.
Note that HTTP Basic Authentication does not provide encryption and should be secured by an SSL connection.
The authentication provider is exchangeable. You can implement the interface org.cibseven.bpm.engine.rest.security.auth.AuthenticationProvider to provide another authentication method and change the filter’s initialization parameter accordingly.
RESTEasy Specifics
The authentication filter works fine whenever the JAX-RS application containing the REST API is deployed as a servlet. This is not necessarily the case. One such case we are aware of is with some types of RESTEasy deployments:
RESTEasy allows deployment of a JAX-RS application as a servlet filter (see the RESTEasy docs). If you choose this method to deploy the REST API application, which we also do in the Tomcat distribution, the authentication filter requires an extra init-param named rest-url-pattern-prefix. The value has to correspond to the servlet path (see HttpServletRequest#getServletPath()) as in the case that the JAX-RS application is deployed as a servlet.
Example: If the RESTEasy configuration is
<filter>
<filter-name>Resteasy</filter-name>
<filter-class>
org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
</filter-class>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>org.cibseven.bpm.engine.rest.impl.application.DefaultApplication</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Resteasy</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
the following init-param has to be set:
<init-param>
<param-name>rest-url-pattern-prefix</param-name>
<param-value></param-value>
</init-param>
In the example above the value is empty because the RESTEasy filter mapping is /\* and a servlet with that mapping would have an empty servlet path. Similarly, the filter mapping url /rest/\* maps to the init-param /rest and so on.