For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Set up the Helm chart with an external Keycloak instance

Admin access required

The external Keycloak setup requires administrative access to the Keycloak server.

Bitnami subcharts removed in Camunda 8.10

Earlier releases provided Web Modeler's database through the webModelerPostgresql Bitnami subchart. As of Camunda 8.10 (Helm chart 15.x), the bundled Bitnami subcharts are removed: provide PostgreSQL with the CloudNativePG operator or a managed database, as shown in the examples below.

The Camunda Helm chart can connect to an external Keycloak instance that acts as the identity management service for authentication and authorization.
With minimal configuration for administrative access, the Management Identity component can automatically configure the Keycloak realm and required entities on startup—simplifying setup and reducing the learning curve.

Use this guide if you already have an existing Keycloak instance and want Camunda to automatically configure the required Keycloak entities.

If you prefer to run Keycloak inside your cluster and deploy it with the Keycloak operator, see the internal Keycloak guide.

Private or internal CA

If your external Keycloak instance presents a certificate signed by a private or internal certificate authority, Camunda components won't trust it by default. Configure TLS trust before or alongside this guide to avoid PKIX path building failed errors.

Before you begin, ensure you’re running a Keycloak version that’s supported by your Camunda release. See supported environments.

Configure Keycloak​

Before setting up the Camunda Helm chart, prepare your Keycloak instance.
For the Keycloak realm, you have two options:

Option 1: Prepare an existing realm​

If you choose this option, configure your Keycloak realm following the Management Identity configuration guide.

Take note of the following values:

  • Realm name (<realm>)
  • Client ID for Management Identity (<identity_client_id>)
  • Administrative Keycloak username and password (<keycloak_admin_username>, <keycloak_admin_password>)

Option 2: Let Management Identity create a realm​

If you choose this option, Management Identity will create a realm named camunda-platform on startup.
Ensure this realm doesn’t already exist before starting for the first time.

Take note of the following values:

  • Realm name: camunda-platform (<realm>)
  • Client ID generated for setup: camunda-identity (<identity_client_id>)
  • Administrative Keycloak username and password (<keycloak_admin_username>, <keycloak_admin_password>)

Configure the Helm chart​

Next, prepare your Kubernetes cluster and install the Camunda Helm chart.

Perform the following steps:

  1. Create a secret
  2. Prepare global configuration
  3. Configure Management Identity
  4. Configure components using OIDC

You can also view the full configuration example.

Create a secret​

Create a secret containing all required credentials.
For example, the following command creates a camunda-credentials secret:

kubectl create secret generic camunda-credentials \
  --from-literal=identity-keycloak-admin-password=<set to admin password> \
  --from-literal=identity-firstuser-password=CHANGE_ME \
  --from-literal=identity-connectors-client-token=CHANGE_ME \
  --from-literal=identity-optimize-client-token=CHANGE_ME \
  --from-literal=identity-orchestration-client-token=CHANGE_ME

This secret includes the following keys:

  • identity-keycloak-admin-password: Password for an administrative Keycloak account (<keycloak_admin>).
  • identity-firstuser-password: Password for the initial Camunda user (default username: demo).
  • identity-connectors-client-token: Client secret of the Keycloak OIDC client connectors used by Connectors.
  • identity-optimize-client-token: Client secret of the Keycloak OIDC client optimize used by Optimize.
  • identity-orchestration-client-token: Client secret of the Keycloak OIDC client orchestration used by the Orchestration Cluster.

The PostgreSQL credentials for Management Identity and Camunda Hub are no longer part of this secret. They are provided by the operator (or managed database) that hosts each database, such as the pg-identity-secret and pg-hub-secret created by the CloudNativePG operator.

For additional options on how to create and reference Kubernetes secrets (for example using YAML manifests or consolidated secrets), see External Kubernetes secrets.

Prepare global configuration​

Start with the following global configuration, which provides shared defaults across the deployment:

global:
  identity:
    auth:
      enabled: true
      publicIssuerUrl: <KEYCLOAK_URL>/realms/<realm>
      issuerBackendUrl: <KEYCLOAK_URL>/realms/<realm>
      authUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/auth
      tokenUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/token
      jwksUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/certs
  security:
    authentication:
      method: oidc

Replace KEYCLOAK_URL with your Keycloak base URL (in the format <protocol>://<host/ip>:<port>/<context-path>).

info

In some setups, Keycloak is accessible through different URLs from within the cluster and from the user’s browser. This can happen, for example, if you deployed Keycloak inside your Kubernetes cluster but didn’t expose it under a domain name that’s accessible both internally and externally.

In this case:

  • Set global.identity.auth.publicIssuerUrl and global.identity.auth.authUrl to the URL reachable from users' browsers.
  • Set the remaining values to the URL reachable from within the cluster.

Configure Management Identity​

Configure Management Identity to access the realm and use the initial OIDC client. On startup, Management Identity creates the realm (if needed), sets up the OIDC clients, and creates the initial user account.

If no clients appear in the Keycloak realm after startup, the configuration was not successful.

Management Identity configuration:

global:
  identity:
    keycloak:
      url: # this URL must be reachable from within the cluster
        protocol: <keycloak_protocol>
        host: <keycloak_hostname>
        port: <keycloak_port>
      contextPath: <keycloak_context_path> # set to "/" for the root context path
      realm: /realms/<realm>
      auth:
        adminUser: <keycloak_admin>
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-keycloak-admin-password"
    auth:
      identity:
        clientId: <identity_client_id>

identity:
  enabled: true
  firstUser:
    secret:
      existingSecret: "camunda-credentials"
      existingSecretKey: "identity-firstuser-password"
  externalDatabase:
    enabled: true
    host: pg-identity-rw
    port: 5432
    database: identity
    username: identity
    secret:
      existingSecret: pg-identity-secret
      existingSecretKey: password
  env:
    - name: KEYCLOAK_REALM
      value: <realm>
    - name: IDENTITY_CLIENT_ID
      value: <identity_client_id>

Add the section under global.identity to the global configuration you created in the previous step.

Management Identity stores its data in a dedicated PostgreSQL database. Connect it to the pg-identity cluster created by the CloudNativePG operator, or to a managed database. Chart 15.x no longer bundles the identityPostgresql subchart, so this connection has to be configured explicitly.

note

Chart 15.x (Camunda 8.10) rejects the flat global.identity.keycloak.auth.existingSecret and auth.existingSecretKey form used by earlier charts. Use the nested auth.secret.* form shown above. In charts 14.x (Camunda 8.8 and 8.9) the flat form still works but logs a deprecation warning. For the full list of values removed in 8.10, see Remove keys rejected by chart 15.x.

The identity.firstUser field defines the initial user that Management Identity creates in Keycloak with full access to all Camunda components. By default, this user is named demo. To use a different name, set identity.firstUser.username.

For additional Keycloak-specific variables you can define under identity.env, see Management Identity environment variables.

Configure components using OIDC​

To configure Orchestration Cluster and management components with OIDC, follow the steps in the Configure components using OIDC section of the internal Keycloak setup guide.

Assign each component its own resource audience by default. Keycloak does not enforce this for you, and a shared value lets a token issued for one component be accepted by another. Only configure this trust for a supported integration. See Assign a unique audience to each component.

Full configuration example​

The following example shows a complete configuration for connecting to an external Keycloak instance:

global:
  identity:
    auth:
      enabled: true
      publicIssuerUrl: <KEYCLOAK_URL>/realms/<realm>
      issuerBackendUrl: <KEYCLOAK_URL>/realms/<realm>
      authUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/auth
      tokenUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/token
      jwksUrl: <KEYCLOAK_URL>/realms/<realm>/protocol/openid-connect/certs
      identity:
        clientId: <identity_client_id>
      optimize:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-optimize-client-token"
    keycloak:
      url: # this URL must be reachable from within the cluster
        protocol: <keycloak_protocol>
        host: <keycloak_hostname>
        port: <keycloak_port>
      contextPath: <keycloak_context_path> # set to "/" for the root context path
      realm: /realms/<realm>
      auth:
        adminUser: <keycloak_admin>
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-keycloak-admin-password"
  security:
    authentication:
      method: oidc

identity:
  enabled: true
  firstUser:
    secret:
      existingSecret: "camunda-credentials"
      existingSecretKey: "identity-firstuser-password"
  externalDatabase:
    enabled: true
    host: pg-identity-rw
    port: 5432
    database: identity
    username: identity
    secret:
      existingSecret: pg-identity-secret
      existingSecretKey: password
  env:
    - name: KEYCLOAK_REALM
      value: <realm>
    - name: IDENTITY_CLIENT_ID
      value: <identity_client_id>

optimize:
  enabled: true

connectors:
  security:
    authentication:
      oidc:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-connectors-client-token"

camundaHub:
  enabled: true # Deploys both Console and Web Modeler
  restapi:
    mail:
      fromAddress: noreply@example.com
    # Connect Camunda Hub to the operator-managed PostgreSQL cluster (pg-hub)
    externalDatabase:
      host: pg-hub-rw
      port: 5432
      database: hub
      username: hub
      secret:
        existingSecret: pg-hub-secret
        existingSecretKey: password
orchestration:
  security:
    authentication:
      oidc:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-orchestration-client-token"

To review how each component is configured and which OIDC clients are used:

  • Run kubectl get pods and kubectl get configmap, then use kubectl describe to inspect component configurations.
  • Log into Keycloak (using your administrative user) to review the OIDC client setup

Connect to the cluster​

After applying this configuration, use the following kubectl port-forward commands to access the APIs and UIs from your localhost:

# Management Identity
kubectl port-forward svc/camunda-identity 8084:80

# Orchestration Cluster
kubectl port-forward svc/camunda-zeebe-gateway 8080:8080
kubectl port-forward svc/camunda-zeebe-gateway 26500:26500

# Connectors
kubectl port-forward svc/camunda-connectors 8086:8080

# Optimize
kubectl port-forward svc/camunda-optimize 8083:80

# Web Modeler
kubectl port-forward svc/camunda-web-modeler-restapi 8070:80
kubectl port-forward svc/camunda-web-modeler-websockets 8085:80

# Console
kubectl port-forward svc/camunda-console 8087:80

After port forwarding, access the UIs through http://localhost:<port>.

For example:

  • Orchestration Cluster UI: http://localhost:8080
  • Management Identity: http://localhost:8084

Log in with the username demo and the password stored in the secret key identity-firstuser-password.

Troubleshooting​

For issues common to any OIDC provider, see Troubleshoot OIDC authentication. The following are specific to external Keycloak:

Management Identity pod restarts once during first startup A single restart during the very first deployment is expected. Immediately after creating the realm, Management Identity can briefly hit 403 Forbidden while disabling Keycloak's default system clients. This is a timing issue between realm creation and Keycloak's permission propagation, not a misconfiguration, and the automatic pod restart resolves it. Investigate further only if the pod keeps crash-looping past the first retry.

Management Identity fails to connect to the Keycloak admin API The global.identity.keycloak.* settings configure the admin API connection used for provisioning, which is separate from the OIDC login flow. Verify url.protocol, url.host, url.port, and contextPath together form a URL reachable from inside the cluster:

kubectl run -it --rm curl --image=curlimages/curl --restart=Never -- \
  curl https://<keycloak-internal-url>/realms/<realm>/.well-known/openid-configuration

A valid response confirms the realm is reachable at that URL. If this fails, double check issuerBackendUrl from the global configuration step, since it should resolve to the same host.

Realm already exists, but clients aren't created If the realm already existed when Management Identity started, Management Identity doesn't re-create it, but it does still attempt to create any missing clients. If clients are still missing after startup, check the Management Identity logs for provisioning errors. The most common cause is that the admin credentials lack permission to create clients in the existing realm.

Demo user can't log in The identity-firstuser-password secret value is only applied when the demo user is first created. If this user already exists from a previous deployment with a different password, changing the secret has no effect on it. Reset the user's password directly in the Keycloak admin console.