Camunda client fails with TLS certificate validation error while starting a process

Camunda 8 Topics
, , , ,
1

When attempting to start a Camunda process instance from the dev-template Spring Boot application, the request fails during authentication.
The application is unable to apply OAuth credentials due to a TLS certificate trust issue.

Environment Details

  • Application: Spring Boot (dev-template)

  • Java Version: JDK 21

  • Camunda Client: camunda-client-java 8.8.0

  • Runtime: Local / Dev

  • Camunda Setup:

    • OAuth authentication enabled

    • TLS enabled

    • Custom certificates configured (server.crt, server.key)

  • Network: Internal IPs (192.168.x.x) / Corporate network

    JVM does not trust the SSL certificate presented by the target endpoint

  • Possible reasons:

    • Certificate chain is incomplete

    • Root / Intermediate CA is missing from JVM truststore

    • Self-managed TLS certificates are configured while OAuth (Camunda SaaS Identity) is still active

    • Mixing Camunda SaaS OAuth with **self-managed Zeebe TLS configuration
      **
      OAuth authentication always connects to Camunda Identity

    • JVM must trust the certificate authority of the Identity endpoint

    • Configuring server.crt / server.key does not make the JVM trust the server

    • Trust must be established via JVM truststore

2

Hi @VARUNKUMAR_K_M,

This is a common issue when mixing Camunda SaaS OAuth with self-managed TLS configuration. The problem occurs because your JVM doesn’t trust the certificate authority used by the Camunda Identity service for OAuth authentication.

Root Cause Analysis

You’ve correctly identified the core issue: when using OAuth authentication, the Java client must connect to Camunda Identity (even in self-managed setups), and your JVM doesn’t trust the certificate presented by the Identity endpoint. Simply configuring server.crt/server.key for your Zeebe gateway doesn’t establish trust - that needs to be done via the JVM truststore.

Solutions

Option 1: JVM Truststore Configuration (Recommended)

Configure the JVM to trust the certificate authority:

JVM Arguments:

-Djavax.net.ssl.trustStore=/path/to/truststore.jks
-Djavax.net.ssl.trustStorePassword=yourpassword

Spring Boot application.yaml:

camunda:
  client:
    zeebe:
      grpc-address: https://<your-host>:26500

Note: When using JVM properties, you do not need to specify the ca-certificate-path property.

Option 2: Camunda-Specific Certificate

Provide a PEM-formatted CA certificate directly:

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

This property expects a PEM format file (.pem, .crt, or .cer), not a JKS truststore.

Option 3: OAuth-Specific Truststore

If your Identity Provider also requires custom certificates for OAuth token requests:

camunda:
  client:
    auth:
      method: oidc
      truststore-path: /path/to/truststore.jks
      truststore-password: password

These camunda.client.auth.* properties take precedence over javax.net.ssl.* global properties for the authentication flow.

Certificate Format Conversion

If you need to extract a PEM certificate from an existing JKS truststore:

keytool -exportcert -alias your-alias -file cert.pem -keystore truststore.jks -rfc

Key Points

  1. OAuth always connects to Camunda Identity - your JVM must trust the Identity endpoint’s certificate
  2. Zeebe gateway TLS ≠ Identity TLS - these are separate certificate requirements
  3. Trust must be established via JVM truststore - configuring server certificates doesn’t create client trust

Try Option 1 first as it’s the most straightforward approach. Let me know if you need help with certificate extraction or truststore creation!

References: