Skip to main content
Version: 8.6

Configure custom headers

Custom HTTP headers can be added to a component's Elasticsearch and OpenSearch HTTP clients by creating a new Java plugin, and adding the plugin to your Camunda 8 Self-Managed installation. Using custom HTTP headers may be helpful for adding authentication, tracking, or debugging to your database requests.

Create the Java plugin​

Add the dependency​

Add the following dependency to a new Java project:

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-search-client-plugin</artifactId>
  <version>${version.camunda-search-client-plugin}</version>
</dependency>

Write your custom header​

Once the dependency is added to your project, write your plugin by implementing the DatabaseCustomHeaderSupplier interface (provided by the camunda-search-plugins package).

The following example implements the DatabaseCustomHeaderSupplier interface, and uses it to return a custom authentication token and UUID:

package com.myplugin;

import io.camunda.plugin.search.header.CustomHeader;
import io.camunda.plugin.search.header.DatabaseCustomHeaderSupplier;
import java.util.UUID;

public class MyCustomHeaderPlugin implements DatabaseCustomHeaderSupplier {

  public static final String CUSTOM_TOKEN_PLUGIN = "X-Custom-Auth-Token";

  @Override
  public CustomHeader getSearchDatabaseCustomHeader() {
    return new CustomHeader(CUSTOM_TOKEN_PLUGIN, UUID.randomUUID().toString());
  }

}

Build your project​

Build your project with all dependencies included, and copy the resulting JAR file somewhere it can be easily accessed. This JAR file will be required by your Camunda installation.

Add the plugin to your self-managed installation​

To use your new plugin, it must be added to your Camunda 8 Self-Managed installation.

Mount the plugin​

For each container, mount your plugin's JAR file inside the container's file system. For more information, see the Docker or Kubernetes documentation.

Configure components​

Include the plugin parameters in each component's application.yaml, or pass them to the component as environment variables. For more information, see how to configure components using Helm charts.

The following examples add the new my-plugin JAR to the application.yaml for Zeebe, Operate, and Tasklist:

Configure Zeebe Exporter​

- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_0_ID=my-plugin
- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- ZEEBE_BROKER_EXPORTERS_ELASTICSEARCH_ARGS_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar

Configure Operate Importer​

- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_ID=my-plugin
- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- CAMUNDA_OPERATE_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar
- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_ID=my-plugin
- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- CAMUNDA_OPERATE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar

Configure Tasklist Importer​

- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_ID=my-plugin
- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- CAMUNDA_TASKLIST_ZEEBEELASTICSEARCH_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar
- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_0_ID=my-plugin
- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- CAMUNDA_TASKLIST_ELASTICSEARCH_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar

Configure Optimize Importer​

note

Due to technical limitations, Optimize currently allows registering up to 5 plugins.

- CAMUNDA_OPTIMIZE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_ID=my-plugin
- CAMUNDA_OPTIMIZE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_CLASSNAME=com.myplugin.MyCustomHeaderPlugin
- CAMUNDA_OPTIMIZE_ELASTICSEARCH_INTERCEPTORPLUGINS_0_JARPATH=/usr/local/plugin/plg.jar

Troubleshooting​

Exception: Unknown type of interceptor plugin or wrong class specified​

This exception means that the incorrect class was specified in the CLASSNAME property. There are several causes that might lead to this exception:

  1. The class with such name or package does not exist
  2. The class does not implement the required SDK interface
  3. The class is inner, static, or final

To solve this, make sure:

  1. You use the latest Search Plugins SDK
  2. Your classes implement correct SDK interfaces
  3. The plugin class is public and not final

Exception: Failed to load interceptor plugin due to exception​

Usually related to incorrect JAR loading. Please make sure that the path to your plugin JAR file is correct, and the application has access to read it. Also check that the JAR is correct and contains the required dependencies. To check the content of the JAR file, you can use the following command: jar xf <file-name>.jar.

Appendix​

Explore plugin examples in our official repository.