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

Set up the Helm chart with an in-cluster Keycloak instance

For an in-cluster Keycloak that acts as the identity management service for authentication and authorization, deploy Keycloak with the Keycloak operator and connect the Camunda Helm chart to it. The Management Identity component configures Keycloak automatically on startup with a realm and several entities to simplify setup and reduce the learning curve.

Use this setup if you don’t have an external identity provider (IdP) and want to run Keycloak inside your cluster, together with additional Camunda components (Console, Web Modeler, Optimize, Management Identity) that are disabled by default in the Helm chart.

If you prefer to connect to a Keycloak instance you manage elsewhere, see Set up the Helm chart with an external Keycloak instance.

Keycloak deployment changed in Camunda 8.10

Earlier releases bundled an internal Keycloak through the identityKeycloak Bitnami subchart (identityKeycloak.enabled: true). As of Camunda 8.10 (Helm chart 15.x), the bundled Bitnami subcharts are removed. Deploy Keycloak in-cluster with the Keycloak operator and its database with the CloudNativePG operator (or use a managed database), then wire Camunda to it as shown below. For releases up to 8.9, see the 8.9 internal Keycloak guide.

Configuration​

This guide shows you how to:

  • Deploy an in-cluster Keycloak with the Keycloak operator and connect the Helm chart to it.
  • Configure the Helm chart with a custom secret for accounts used across all components.
  • Enable the application components you want to include in the release.
  • Access all components from your local environment.

To use an in-cluster Keycloak instance, complete the following steps:

  1. Create a secret
  2. Deploy Keycloak and connect Camunda
  3. Configure Management Identity
  4. Configure components using OIDC

See the full configuration example for the complete setup.

Create a secret​

Create a secret that contains the Camunda application credentials. For example, the following command creates a camunda-credentials secret:

kubectl create secret generic camunda-credentials \
  --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-firstuser-password: Password for the initial user account in Keycloak (default username demo), used to log in to the Camunda web apps.
  • identity-connectors-client-token: Client secret for the Keycloak OIDC client connectors used by Connectors.
  • identity-optimize-client-token: Client secret for the Keycloak OIDC client optimize used by Optimize.
  • identity-orchestration-client-token: Client secret for the Keycloak OIDC client orchestration used by the Orchestration Cluster.

The Keycloak administrator credentials and the PostgreSQL credentials for Keycloak, Identity, and Web Modeler are no longer part of this secret. They are provided by the operators that deploy those services, such as the operator-generated keycloak-initial-admin secret and the pg-*-secret database secrets. See Operator-based infrastructure for how these are created.

Deploy Keycloak and connect Camunda​

Deploy an in-cluster Keycloak with the Keycloak operator and a PostgreSQL database with the CloudNativePG operator. The operator-based guide creates the Keycloak service (keycloak-service), the operator-generated keycloak-initial-admin secret, and the pg-keycloak database cluster.

Then connect the Camunda Helm chart to that Keycloak instance through global.identity.keycloak:

global:
  identity:
    auth:
      type: KEYCLOAK
      publicIssuerUrl: http://keycloak-service:18080/auth/realms/camunda-platform
      issuerBackendUrl: http://keycloak-service:18080/auth/realms/camunda-platform
    keycloak:
      url:
        protocol: http
        host: keycloak-service
        port: "18080"
      contextPath: /auth
      realm: /realms/camunda-platform
      auth:
        adminUser: temp-admin
        secret:
          existingSecret: keycloak-initial-admin
          existingSecretKey: password

The host, port, admin user, and secret name above match the defaults created by the operator-based Keycloak deployment. Adjust them if you customized that deployment.

Configure Management Identity and global defaults​

Management Identity configures the Keycloak instance during startup. For example, it creates the Camunda realm and other required Keycloak entities. If the Camunda realm doesn’t appear in Keycloak after deployment, the setup process did not complete successfully.

Management Identity stores its data in a dedicated PostgreSQL database. Connect it to the pg-identity cluster created by the CloudNativePG operator (or a managed database):

global:
  identity:
    auth:
      enabled: true
  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

identity.firstUser defines the first user created in Keycloak. By default, this user is named demo. You can override this by setting identity.firstUser.username.

Configure components using OIDC​

Once Management Identity is configured, you can set up OAuth and OIDC for the remaining components. You can skip components you don’t plan to run. By default, the Orchestration Cluster and Connectors are enabled and must be explicitly disabled if not required.

Configure Orchestration Cluster​

The Orchestration cluster treats the in-cluster Keycloak as any other external IdP and connects through OIDC.

Orchestration Cluster configuration:

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

Configure Connectors​

Connectors must be configured in a similar fashion with OIDC client secret to access the Orchestration Cluster APIs.

Connectors component configuration:

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

Configure Optimize​

Optimize component configuration:

global:
  identity:
    auth:
      optimize:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-optimize-client-token"

optimize:
  enabled: true

Add the section under global.identity.auth to the existing section you created when configuring Management Identity.

Configure Camunda Hub​

In Camunda 8.10, Console and Web Modeler are deployed together as sub-components of Camunda Hub. Enable both by setting camundaHub.enabled: true. This replaces the former console.enabled and webModeler.enabled flags and takes precedence over them.

Web Modeler connects to its own PostgreSQL database and requires a redirect URL for OIDC authentication. Console is a public client and needs no additional OIDC configuration.

Web Modeler component configuration:

global:
  identity:
    auth:
      webModeler:
        redirectUrl: "http://localhost:8070" # Change this when using a domain

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
Redirect URL configuration

The redirectUrl parameter is required for Web Modeler authentication. The default value is http://localhost:8070, which works for local port-forwarding setups.

If you're using a domain or Ingress to expose Web Modeler, you must update this value to match your Web Modeler URL:

  • With Ingress: https://your-domain.com/modeler (if using a context path)
  • Without context path: https://modeler.your-domain.com

Mismatched redirect URLs will cause authentication failures that are difficult to debug.

You can update camundaHub.restapi.mail.fromAddress with an address suitable for your environment. This address appears as the sender in emails sent by Web Modeler. For more details on configuring email delivery, see the Camunda Hub section in Enable additional Camunda components.

Configure Console​

Console is deployed as part of Camunda Hub, which you enabled with camundaHub.enabled: true in the previous step. Since Console is a public client, it does not need to be defined under global.identity.auth and requires no additional configuration.

Full configuration example​

The following example shows a complete configuration for deploying Camunda with an in-cluster, operator-managed Keycloak and operator-managed PostgreSQL databases:

global:
  identity:
    auth:
      enabled: true
      type: KEYCLOAK
      publicIssuerUrl: http://keycloak-service:18080/auth/realms/camunda-platform
      issuerBackendUrl: http://keycloak-service:18080/auth/realms/camunda-platform
      optimize:
        secret:
          existingSecret: "camunda-credentials"
          existingSecretKey: "identity-optimize-client-token"
      webModeler:
        # Default: http://localhost:8070
        # Update this when using a domain/Ingress, e.g., https://your-domain.com/modeler
        redirectUrl: "http://localhost:8070"
    keycloak:
      url:
        protocol: http
        host: keycloak-service
        port: "18080"
      contextPath: /auth
      realm: /realms/camunda-platform
      auth:
        adminUser: temp-admin
        secret:
          existingSecret: keycloak-initial-admin
          existingSecretKey: 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

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
    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"

In this setup, Keycloak and PostgreSQL are deployed and managed by their operators, while the Camunda Helm chart handles the application-side Keycloak configuration automatically, including creating OIDC or OAuth clients and linking components. Your values file primarily connects to the operator-managed services, enables components, and defines client secrets.

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​

Local access with port forwarding​

After applying this configuration, use the following kubectl port-forward commands to access the APIs and UIs from your localhost. Because Keycloak runs as a separate operator-managed service, also port-forward the Keycloak service:

# Keycloak Operator service
kubectl port-forward svc/keycloak-service 18080:18080

# 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

Once port forwarding is active, access each component through http://localhost:<port>. For example:

  • Web Modeler: http://localhost:8070
  • Orchestration Cluster: http://localhost:8080

Reach Keycloak at http://keycloak-service:18080/auth rather than through localhost. The configuration above sets the token issuer to http://keycloak-service:18080/auth/realms/camunda-platform, so your browser is redirected to that hostname during login and must resolve it to the forwarded port. Map it to the loopback address first:

echo "127.0.0.1  keycloak-service" | sudo tee -a /etc/hosts

Log in with username demo and the password you defined under identity-firstuser-password.

Default URLs and port forwarding

The configuration shown above uses a default redirectUrl of http://localhost:8070 for Web Modeler, which matches the port-forwarding setup. The Keycloak issuer stays on the in-cluster service name and needs the /etc/hosts entry above.

If you don't use port forwarding and instead expose components via Ingress or a domain, you must update the redirectUrl parameters under global.identity.auth to match your actual URLs. See Ingress setup for domain-based configuration examples.

Domain-based access with Ingress​

If you're using Ingress to expose components via a domain (instead of port forwarding), update the redirect URLs in your Helm values:

global:
  identity:
    auth:
      webModeler:
        redirectUrl: "https://your-domain.com/modeler" # Or https://modeler.your-domain.com
      # Update other component URLs as needed

For complete Ingress configuration, see Ingress setup.

External identity provider​

Instead of using an in-cluster Keycloak instance, you can configure Camunda to connect to an external IdP, such as an external Keycloak, Microsoft Entra ID, or Okta.

See Set up the Helm chart with an external OIDC provider for details.