Configuration

You can configure the connector runtime environment in the following ways:

• Specify the Zeebe instance to connect to.
• Define the connector functions to run.
• Provide the secrets that should be available to the connectors.

note

Starting from version 8.8, the connector runtime no longer requires a connection to Operate. It now depends only on the Orchestration Cluster REST API and Zeebe.

To connect to the Orchestration Cluster, the connector runtime uses the Camunda Spring Boot Starter. Any configuration available in the Spring Boot Starter can also be applied to the connector runtime environment.

Below are some of the most common configuration options for the connector runtime. For a complete list, see the Camunda Spring Boot Starter configuration reference.

note

This guide presents configuration properties as environment variables, while the Camunda Spring Boot Starter documentation uses Java configuration properties. The two formats are interchangeable. You can also use Java configuration properties in the connector runtime environment.

For example, the Java configuration property camunda.client.grpc-address can be set as the environment variable CAMUNDA_CLIENT_GRPCADDRESS in the connector runtime.

Configure the Orchestration Cluster connection for Self-Managed

Connection URL

To connect to the Orchestration Cluster, provide the following configuration:

Environment variables

CAMUNDA_CLIENT_MODE=self-managed
CAMUNDA_CLIENT_GRPCADDRESS=http://localhost:26500
CAMUNDA_CLIENT_RESTADDRESS=http://localhost:8080

Application properties

camunda:
  client:
    mode: self-managed
    grpc-address: http://localhost:26500
    rest-address: http://localhost:8080

HTTPS configuration

If using an HTTPS connection, you may need to provide a certificate to validate the Zeebe Gateway's certificate chain.

Environment variables

CAMUNDA_CLIENT_CACERTIFICATEPATH=/path/to/certificate.pem

Application properties

camunda:
  client:
    ca-certificate-path: /path/to/certificate.pem

Authentication methods

Choose the authentication method for your environment:

No Authentication

By default, no authentication will be used.

Environment variables

CAMUNDA_CLIENT_AUTH_METHOD=none

Application.yaml

camunda:
  client:
    auth:
      method: none

Basic Authentication

To activate basic authentication:

Environment variables

CAMUNDA_CLIENT_AUTH_METHOD=basic
CAMUNDA_CLIENT_AUTH_USERNAME=<your username>
CAMUNDA_CLIENT_AUTH_PASSWORD=<your password>

Application.yaml

camunda:
  client:
    auth:
      method: basic
      username: <your username>
      password: <your password>

OIDC-based Authentication

To activate OIDC-based authentication:

Environment variables

CAMUNDA_CLIENT_AUTH_METHOD=oidc
CAMUNDA_CLIENT_AUTH_CLIENTID=xxx
CAMUNDA_CLIENT_AUTH_CLIENTSECRET=xxx
CAMUNDA_CLIENT_AUTH_TOKENURL=http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
CAMUNDA_CLIENT_AUTH_AUDIENCE=<your client id of Orchestration Cluster or configured audience>
CAMUNDA_CLIENT_AUTH_SCOPE=<your client id of Orchestration Cluster or configured audience>

Application.yaml

camunda:
  client:
    auth:
      method: oidc
      client-id: <your client id>
      client-secret: <your client secret>
      token-url: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
      audience: <your client id of Orchestration Cluster or configured audience>
      scope: <your client id of Orchestration Cluster or configured audience>

Notes for Microsoft Entra ID

• Instead of scope: CLIENT_ID_OC, use: scope: CLIENT_ID_OC + "/.default".
• The token-url is typically formatted as: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token.

Audience validation

If you have configured the audiences property for the Orchestration Cluster (camunda.security.authentication.oidc.audiences), the Orchestration Cluster will validate the audience claim in the token against the configured audiences. Ensure your token has the correct audience from the Orchestration Cluster configuration, or add your audience in the configuration. This is often the client ID you used when setting up the Orchestration Cluster.

See the Camunda Spring Boot Starter documentation for more information on authentication properties.

Configure the Orchestration Cluster connection for SaaS

To use Camunda 8 SaaS, specify the connection properties:

Environment variables

CAMUNDA_CLIENT_MODE=saas
CAMUNDA_CLIENT_AUTH_CLIENTID=xxx
CAMUNDA_CLIENT_AUTH_CLIENTSECRET=xxx
CAMUNDA_CLIENT_CLOUD_REGION=bru-2
CAMUNDA_CLIENT_CLOUD_CLUSTERID=xxx

Application properties

camunda:
  client:
    mode: saas
    auth:
      client-id: xxx
      client-secret: xxx
    cloud:
      region: bru-2
      cluster-id: xxx

If you are connecting a local connector runtime to a SaaS cluster, you may want to review our guide to using connectors in hybrid mode.

Manual discovery of connectors

By default, the connector runtime picks up outbound connectors available on the classpath automatically. To disable this behavior, use the following environment variables to configure connectors explicitly:

Environment variable	Purpose
CONNECTOR_{NAME}_FUNCTION (required)	Function to be registered as job worker with the given NAME
CONNECTOR_{NAME}_TYPE (optional)	Job type to register for worker with NAME
CONNECTOR_{NAME}_INPUT_VARIABLES (optional)	Variables to fetch for worker with NAME
CONNECTOR_{NAME}_TIMEOUT (optional)	Timeout in milliseconds for worker with NAME

Through this configuration, you define all job workers to run.

Specifying optional values allows you to override @OutboundConnector-provided connector configuration.

CONNECTOR_HTTPJSON_FUNCTION=io.camunda.connector.http.rest.HttpJsonFunction
CONNECTOR_HTTPJSON_TYPE=non-default-httpjson-task-type

Disabling Individual Connectors

To disable individual connectors you can provide a comma separated list to CONNECTOR_INBOUND_DISABLED and CONNECTOR_OUTBOUND_DISABLED respectively. These list must contain the connector type (e.g. io.camunda:http-json:1). To disable two outbound connectors, you can set the environment variable as follows:

CONNECTOR_OUTBOUND_DISABLED=io.camunda:example:1,com.acme:custom-connector:2

This can be found as the <zeebe:taskDefinition type="io.camunda:http-json:1"/> in the BPMN XML, the zeebe:taskDefinition property in the element template or in the OutboundConnector annotation for outbound connectors. The inbound connector type can be found as <zeebe:property name="inbound.type" value="io.camunda:webhook:1" />, the inbound.type property in the element template or in the InboundConnector annotation.

Disabling connector discovery

warning

We do not guarantee that all the Camunda provided connectors will be discovered via SPI. If you want to have a connector runtime without out-of-the-box connectors, we recommend building a custom runtime with only the connectors you want to use.

To disable the discovery of connectors via SPI or environment variables as explained in this section, set the following environment variables: CONNECTOR_INBOUND_DISCOVERY_DISABLED and CONNECTOR_OUTBOUND_DISCOVERY_DISABLED.

Note that this does not prevent the registration of connectors via Spring Beans or other mechanisms.

Secrets

Providing secrets to the runtime environment can be achieved in different ways, depending on your setup.

Default secret provider

Starting with Camunda 8.9, the environment-based secret provider applies the prefix SECRET_ by default when resolving secrets. Only environment variables that start with this prefix are available as connector secrets.

This improves security by preventing all environment variables from being exposed as connector secrets. Existing secrets that do not use the configured prefix will no longer resolve until you update either the environment variables or the prefix configuration.

Configure a custom prefix

To use a custom prefix, configure it via the Java property or environment variable and name your secrets accordingly:

export CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_PREFIX='SUPER_SECRETS_'
export SUPER_SECRETS_MY_SECRET='foo'   # Resolved via {{ secrets.MY_SECRET }}

Restore the previous behavior (unsafe)

To restore the previous behavior where all environment variables can be used as connector secrets, set the prefix to an empty value:

camunda.connector.secret-provider.environment.prefix=

warning

When no prefix is configured, the connector runtime logs a warning that this mode is unsafe because all environment variables are exposed as connector secrets. Camunda does not recommend this mode for production environments.

The following environment variables can be used to configure the default secret provider:

Name	Description	Default value
CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_ENABLED	Whether the default secret provider is enabled.	true
CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_PREFIX	Prefix applied to the secret name before lookup. Only environment variables starting with this prefix are available as secrets. Set to empty to disable (unsafe).	SECRET_
CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_TENANTAWARE	Whether the secret provider should be tenant-aware.	false

If the secret provider is set to be tenant-aware, the secret format will change to ${prefix}${tenantId}_${secretName}:

Example with empty prefix:

export CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_TENANTAWARE=true
export tenant1_MY_SECRET='foo' # This will be resolved by using {{ secrets.MY_SECRET }} from tenant1

Example with prefix set:

export CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_TENANTAWARE=true
export CAMUNDA_CONNECTOR_SECRETPROVIDER_ENVIRONMENT_PREFIX='SUPER_SECRETS_'
export SUPER_SECRETS_tenant1_MY_SECRET='foo' # This will be resolved by using {{ secrets.MY_SECRET }} from tenant1

Secrets in Helm charts

Connector secrets can be used in Helm charts, for example by referencing a Kubernetes secret:

connectors:
  envFrom:
    - secretRef:
        name: camunda-connector-secrets

apiVersion: v1
kind: Secret
metadata:
  name: camunda-connector-secrets
stringData:
  MY_SECRET: foo

Review the documentation on managing secrets in Helm charts for additional details.

Secrets in Docker images

To inject secrets into the Docker images of the runtime, they must be available in the environment of the Docker container.

For example, you can inject secrets when running a container:

docker run --rm --name=connectors -d \
  -v $PWD/connector.jar:/opt/app/ \  # Add a connector jar to the classpath
  -e MY_SECRET=secret \              # Set a secret with value
  -e SECRET_FROM_SHELL \             # Set a secret from the environment
  --env-file secrets.txt \           # Set secrets from a file
  camunda/connectors-bundle:latest

The secret MY_SECRET value is specified directly in the docker run call, whereas the SECRET_FROM_SHELL is injected based on the value in the current shell environment when docker run is executed. The --env-file option allows using a single file with the format NAME=VALUE per line to inject multiple secrets at once.

Secrets in manual installations

In the manual setup, inject secrets during connector execution by providing them as environment variables before starting the runtime environment. You can, for example, export them beforehand as follows:

export MY_SECRET='foo'

Reference the secret in the connector's input in the prefixed style {{secrets.MY_SECRET}}.

Custom secret provider

Create your own implementation of the io.camunda.connector.api.secret.SecretProvider interface that comes with the SDK.

Package this class and all its dependencies as a JAR, for example my-secret-provider-with-dependencies.jar. This needs to include a file META-INF/services/io.camunda.connector.api.secret.SecretProvider that contains the fully qualified class name of your secret provider implementation. Add this JAR to the runtime environment, depending on your deployment setup. Your secret provider will serve secrets as implemented.

To use this JAR with Camunda Helm charts, build an init container to create a volume with your secret provider, and mount it into the connectors pod.

For example, use the following file as input for your helm install command:

connectors:
  extraVolumes:
    - name: workdir
      emptyDir: {}
  extraVolumeMounts:
    # Mount the secret provider
    # The Connectors pod will pick up the secret provider from /opt/app during startup
    - name: workdir
      mountPath: /opt/app/file-secret-provider-2.1.2.jar
      subPath: file-secret-provider-2.1.2.jar
  initContainers:
    - name: install
      image: busybox:1.36.1
      command: ["sh", "-c"]
      args:
        # Download a the custom secret provider into the volume
        - |
          wget -O /work-dir/file-secret-provider-2.1.2.jar https://artifacts.camunda.com/artifactory/camunda-consulting/com/camunda/consulting/connector/file-secret-provider/2.1.2/file-secret-provider-2.1.2.jar
      volumeMounts:
        - name: workdir
          mountPath: "/work-dir"
      securityContext:
        runAsUser: 1000
        # redundant as 1000 is not root but good to have
        # as the runtime will do verification that no process will
        # run as root within the container
        runAsNonRoot: true

For Docker images, you can add the JAR by using volumes, for example:

docker run --rm --name=connectors -d \
  -v $PWD/my-secret-provider-with-dependencies.jar:/opt/app/my-secret-provider-with-dependencies.jar \  # Specify secret provider
  -e CAMUNDA_CLIENT_ZEEBE_GRPCADDRESS=http://ip.address.of.zeebe:26500 \ # Specify grpc Zeebe address
  camunda/connectors:latest

In manual installations, add the JAR to the -cp argument of the Java call:

java -cp 'connector-runtime-application-VERSION-with-dependencies.jar:...:my-secret-provider-with-dependencies.jar' \
    io.camunda.connector.runtime.ConnectorRuntimeApplication

Secret filter

note

The secret filter requires connector runtime 8.9.7+.

The secret filter restricts connectors to resolving only the secrets they declare in their own configuration. This prevents a connector from resolving secrets that are available in the runtime environment but not referenced by that connector.

How the allow-list is built

Every field you configure in a connector's properties panel is implemented as a Zeebe input mapping under the hood, whether it's an authentication field or a functional field like an email body, an HTTP header, or a query parameter. If a field contains a literal {{secrets.NAME}} reference, the filter allow-lists NAME for that specific field, identified by its field path — not for the connector element as a whole.

The allow-list is built once per element, from the deployed BPMN model, by scanning the literal text of that element's own fields for {{secrets.NAME}} references and recording which field each reference belongs to:

• It's static, not dynamic. The filter looks at what's literally written in the model, not at what a process variable resolves to at runtime. If a secret value already resolved by one connector task later flows into a different task's field as a plain process variable (for example, = myVariable), that's just data at that point. There's no {{secrets.*}} placeholder left for the filter to check, so the filter has no say over it either way.
• It's scoped to the field, not just the element. A secret declared on one field (for example, authentication.password = {{secrets.AUTH}}) doesn't become resolvable on a different field of the same task, such as an email body. If that other field's runtime value happens to contain the literal text {{secrets.AUTH}} — for example, because it evaluates a process variable crafted to contain that string — the filter checks it against that field's own allow-list entry, not authentication.password's, and leaves it unresolved.
• One exception: fields the model itself chains together. If one field's FEEL expression assigns from a name that another field's expression also references (for example, url = baseUrl + "/path", where baseUrl is itself another input on the same element), the secret declared on the first field is also allowed on the second — the model author's own expressions connect them. This is still resolved statically, from the deployed model's FEEL expressions, not from arbitrary runtime process-variable content.
• It's still per element, not per process. A secret referenced only on task A never becomes available to task B: task B's allow-list is built only from task B's own fields.

This closes the gap an element-wide allow-list would leave open: declaring a secret anywhere on a task no longer makes it resolvable from every field on that task — only from the field it was declared on (and fields the model explicitly chains to it).

note

For inbound connectors, the allow-list comes from data already held in memory on the deployed element, so there's no remote lookup that can fail. As a result, LAX and STRICT behave identically for inbound connectors: both enforce the allow-list unconditionally. The distinction between LAX and STRICT described below only affects outbound connectors, where building the allow-list requires a lookup against the process definition.

Modes

Configure the secret filter with the camunda.connector.secret-resolver.secret-filter.mode property:

Mode	Behavior
STRICT	Enforces the allow-list unconditionally. If the process definition cannot be retrieved, the Zeebe job fails and retries are triggered. This is the default. Choose this mode when strict secret isolation is required.
LAX	Enforces the allow-list when the process definition is available. Falls back to allowing all secrets if the process definition cannot be retrieved (for example, due to an API outage or an eventual-consistency delay). Choose this mode when uninterrupted job processing matters more than strict secret isolation.
DISABLED	All secrets resolve freely, matching the behavior before this feature was introduced. Choose this mode only for troubleshooting, or if a custom secret provider needs unrestricted access.

The allow-list is derived automatically from the fields of the deployed connector element. No manual configuration of individual secrets is required.

Environment variables

CAMUNDA_CONNECTOR_SECRETRESOLVER_SECRETFILTER_MODE=LAX

Application properties

camunda:
  connector:
    secret-resolver:
      secret-filter:
        mode: LAX

Configure the mode in the Helm chart

The Helm chart has no dedicated value for the secret filter. Set the mode through the generic connectors.env value:

connectors:
  env:
    - name: CAMUNDA_CONNECTOR_SECRETRESOLVER_SECRETFILTER_MODE
      value: LAX

Cache configuration

The secret filter caches process definition lookups to avoid repeated API calls. You can configure the cache with the following properties:

Property	Environment variable	Description	Default
camunda.connector.secret-resolver.secret-filter.cache.enabled	CAMUNDA_CONNECTOR_SECRETRESOLVER_SECRETFILTER_CACHE_ENABLED	Whether caching is enabled.	true
camunda.connector.secret-resolver.secret-filter.cache.max-size	CAMUNDA_CONNECTOR_SECRETRESOLVER_SECRETFILTER_CACHE_MAXSIZE	Maximum number of process definitions to cache.	1000

Secure secret usage best practices

• Keep the mode at STRICT (the default) in production environments. Reserve LAX for cases where a temporary process definition API outage must not block connector jobs, and reserve DISABLED for troubleshooting only.
• Reference only the secrets a connector task actually needs, in the fields that need them. A task that references fewer secrets has a smaller allow-list, which limits what that task can resolve even when its other field values come from untrusted process variables.
• Scope secrets narrowly, for example one API key per integration or tenant, instead of reusing a single broad-access secret across multiple connector tasks.
• Under STRICT, you don't need to design BPMN diagrams defensively to keep a secret out of a task's other fields. The runtime enforces the allow-list per field: a secret declared on one field of a task isn't resolvable from a different field on that same task, or from a different task, unless the model itself chains them together with a FEEL expression.

Troubleshooting a secret that stops resolving under STRICT

If a secret that previously resolved now comes back unresolved, or the connector job fails, under STRICT mode, check the following:

• For outbound connectors, the element is a supported BPMN type (ServiceTask, SendTask, ScriptTask, BusinessRuleTask, SubProcess, IntermediateThrowEvent, or EndEvent) with a zeebe:input mapping that contains the secret reference. Unsupported element types and supported elements without such an input mapping are treated as declaring no secrets and deny all resolution under STRICT.
• The secret is referenced using the {{secrets.NAME}} syntax in the same field where you expect it to resolve. A reference declared on one field doesn't resolve on a different field, unless the model chains the two fields together with a FEEL expression.
• The {{secrets.NAME}} reference sits inside a JSON string, like any other field value. An unquoted placeholder on a non-string field (for example, "count": {{secrets.MAX}}) is never substituted.
• The process definition is available to the connector runtime. Under STRICT, a Zeebe job fails and retries if the process definition can't be retrieved.

If you need to keep jobs processing while you investigate, switch to LAX temporarily. It falls back to allowing all secrets when the process definition lookup fails.

HTTP proxy configuration

You can configure connectors to route HTTP requests through a proxy server. See HTTP proxy configuration for details.

Truststore

If your connector runtime needs to connect to external systems over HTTPS, you might need to provide a custom truststore.

To configure the truststore, use the following environment variables:

• JAVAX_NET_SSL_TRUSTSTORE: Path to the truststore file (e.g., /path/to/truststore.jks)
• JAVAX_NET_SSL_TRUSTSTOREPASSWORD: Password for the truststore

Multi-tenancy

The Connector Runtime supports multiple tenants for inbound and outbound connectors. These are configurable in Orchestration Cluster Admin.

A single Connector Runtime can serve a single tenant or can be configured to serve multiple tenants. By default, the runtime uses the tenant ID <default> for all Zeebe-related operations like handling jobs and publishing messages.

info

Support for outbound connectors with multiple tenants requires a dedicated tenant job worker config (described below). Inbound connectors automatically work for all tenants the configured Connector Runtime client has access to. This can be configured in Admin via the application assignment.

Environment variables

The Connector Runtime uses the following environment variables to configure multi-tenancy:

Name	Description	Default value
CAMUNDA_CLIENT_TENANTID	The default tenant ID used to communicate with Zeebe. Changing this value will set a new default tenant ID used for fetching jobs and publishing messages.	<default>
CAMUNDA_CLIENT_WORKER_DEFAULTS_TENANTIDS	The default tenant IDs (comma separated) used to activate jobs. To run the Connector Runtime in a setup where a single runtime serves multiple tenants, add each tenant ID to this list.	<default>

If you are using an embedded version of the Connector Runtime, you can specify the tenant information in your Spring configuration like in this example application.properties file:

camunda.client.tenant-id=myTenant
camunda.client.worker.defaults.tenant-ids=myTenant

Outbound connector config

The Connector Runtime uses the default tenant for outbound connector-related features. If support for a different tenant or multiple tenants should be enabled, the tenants need to be configured individually using the following environment variables.

If you want to use outbound connectors for a single tenant that is different from the default tenant, you can specify a different default tenant ID using:

CAMUNDA_CLIENT_TENANTID=myTenant

This will change the default tenant ID used for fetching jobs and publishing messages to the tenant ID myTenant.

It is possible to adjust the polling interval of connectors polling process definitions to Operate by setting the environment variable CAMUNDA_CONNECTOR_POLLING_INTERVAL. This variable allows you to control how often connectors fetch the process definitions, with the interval specified in milliseconds. For example, setting CAMUNDA_CONNECTOR_POLLING_INTERVAL=20000 will configure the connectors to poll every 20 seconds.

Example:

CAMUNDA_CONNECTOR_POLLING_INTERVAL=10000

note

Inbound connectors will still be enabled for all tenants the Connector Runtime client has access to.

To run the connector Runtime in a setup where a single runtime serves multiple tenants, add each tenant ID to the list of the default job workers:

CAMUNDA_CLIENT_ZEEBE_DEFAULTS_TENANTIDS=`myTenant, otherTenant`

In this case, the CAMUNDA_CLIENT_TENANTID will not be used for the configuration of job workers.

Inbound Connector configuration

The Connector Runtime fetches process definitions from the Orchestration Cluster REST API, and executes all inbound connectors within those processes independently of the outbound connector configuration without any additional configuration required from the user.

To restrict the Connector Runtime inbound connector feature to a single tenant or multiple tenants, use Admin and assign the tenants the connector application should have access to.

Troubleshooting

To ensure seamless integration and functionality, the multi-tenancy feature must also be enabled across all associated components if not configured in Helm so users can view any data from tenants for which they have authorizations configured in Admin.

Find more information (including links to component-specific configuration pages) on the multi-tenancy concepts page.

Logging

Changing the log level

The log level can be changed globally by setting the environment variable LOGGING_LEVEL_IO_CAMUNDA_CONNECTOR=DEBUG. This changes the default log level for the io.camunda.connector package to DEBUG.

You can use this package based log level approach also with custom connectors by providing your package (my.package) via this variable: LOGGING_LEVEL_MY_PACKAGE=DEBUG.

To change the log level for all packages, change it for the root logger: LOGGING_LEVEL_ROOT=DEBUG.

Google Stackdriver (JSON) logging

To enable Google Stackdriver compatible JSON logging, set the environment variable CONNECTORS_LOG_APPENDER=stackdriver on the Connector Runtime.