Skip to main content
Version: 8.9 (unreleased)

Configure custom HTTP headers for database clients

You can add custom HTTP headers to the Elasticsearch or OpenSearch clients used by Camunda components by creating a Java plugin and adding it to your Camunda 8 Self-Managed installation. Custom headers can help with adding authentication, tracking, or debugging to your database requests.

Prerequisites​

  • A deployed Camunda 8 Self-Managed Helm chart installation
  • Access to modify container configurations
  • Basic knowledge of Java development
  • Maven or Gradle build environment

Configuration​

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>
  <scope>provided</scope>
</dependency>

Write your custom header​

After adding the dependency, create your plugin by implementing the DatabaseCustomHeaderSupplier interface provided by the camunda-search-client-plugin package.

The following example implements the DatabaseCustomHeaderSupplier interface, and returns 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 to a location accessible by your Camunda installation. This JAR file will be required later during configuration.

note

When building the project, the camunda-search-client-plugin dependency must have a scope of provided, otherwise there will be a class loader conflict between camunda-search-client-plugin classes loaded from different class paths.

The JVM treats ClassA loaded by ClassLoaderA as completely different from ClassA loaded by ClassLoaderB. Without a provided scope, this causes does not implement or ClassCastException errors.

Add the plugin to your self-managed installation​

To use your new plugin, add it to your Camunda 8 Self-Managed installation.

  • Mount the plugin: For each container, mount your plugin 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.

Example usage​

The following examples add the new my-plugin JAR to the application.yaml for the Orchestration Cluster and Optimize:

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

Optimize Importer​

note

Due to technical limitations, Optimize currently allows registering up to five 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. Possible causes include:

  • The class name or package does not exist.
  • The class does not implement the required SDK interface.
  • The class is defined as inner, static, or final.

To fix this:

  • Use the latest Search Plugins SDK.
  • Ensure your class implements the correct SDK interface.
  • Verify that the plugin class is public and not final.

Exception: Failed to load interceptor plugin due to exception​

This error usually indicates an issue with JAR loading.

  • Make sure that the path to your plugin JAR file is correct and that the application has permission to read it.
  • Also confirm that the JAR is valid and contains all required dependencies.

To check the contents of your JAR file, run the following command:

jar xf <file-name>.jar

References​