For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (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. When Elasticsearch/OpenSearch is configured as your secondary storage backend, custom headers can help with authentication, tracking, or debugging for those requests. See Elasticsearch/OpenSearch.

This page applies to both the Orchestration Cluster and Optimize when they connect to Elasticsearch or OpenSearch.

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​

Unknown type of interceptor plugin or wrong class specified​

Observed behavior: Startup fails with Unknown type of interceptor plugin or wrong class specified.

Why this happens: The class configured in the CLASSNAME property is incorrect. Possible causes include:

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

How to fix:

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

Failed to load interceptor plugin due to exception​

Observed behavior: Startup fails with Failed to load interceptor plugin due to exception.

Why this happens: This error usually indicates an issue with JAR loading, either the path is wrong, the file isn't readable, or the JAR is missing required dependencies.

How to fix:

  1. Confirm the path to your plugin JAR file is correct and that the application has permission to read it.
  2. Confirm the JAR is valid and contains all required dependencies. Check its contents with: 
    jar xf <file-name>.jar

References​