Describe the use case:

it is hard for Helm chart users to understand which values to set in values.yaml for the different Keycloak-related authentication scenarios. In particular, the following modes are not clearly separated in the chart configuration:

• Internal Keycloak (Bitnami Keycloak subchart managed by the chart).
• External Keycloak (Keycloak running outside the Helm chart deployment, managed by the customer).
• External OIDC provider (e.g. Entra, Okta), optionally brokering via internal Keycloak.

The result is that users need to reverse‑engineer how identityKeycloak, identity, and global.identity.auth.<COMPONENT> are meant to be combined for each scenario, and which values are required vs optional.

Describe the enhancement/feature:

Provide a clear, scenario‑driven configuration in values.yaml (and README/docs) for the three Keycloak/OIDC modes, so that users can reliably configure each option without guesswork.

1. Document the three auth modes explicitly

   explain, at a high level:

   • Mode A – Internal Keycloak (Bitnami subchart)

     • identityKeycloak.* configures the Bitnami Keycloak subchart.
     • identity.* configures Management Identity (realm bootstrap, first user, etc.).
     • global.identity.auth.<COMPONENT>.* configures OIDC for Orchestration Cluster, Optimize, Web Modeler, Console, etc.

   • Mode B – External Keycloak

     • identityKeycloak.enabled: false.
     • global.identity.keycloak.* and global.identity.auth.* used to point Camunda components to the external Keycloak and its realm.
     • identity.* configures Management Identity to use the external realm.

   • Mode C – External OIDC provider (Keycloak not required)

     • Internal Keycloak disabled.
     • global.identity.auth.* (issuer, token/jwks/auth URLs, client IDs, claims) used to connect to the external OIDC provider.
     • Make it clear when Management Identity is in use vs Orchestration‑only OIDC.

2. Add minimal end‑to‑end examples per mode

   For each of the three modes, add a small, self‑contained snippet in values.yaml (and/or README) that shows:

   • Which top‑level keys must be set:
     • identityKeycloak.*
     • identity.*
     • global.identity.auth.* and global.identity.keycloak.*
     • orchestration.security.authentication.*, connectors.security.authentication.*, etc.
   • How to:
     • Enable/disable the Bitnami Keycloak subchart correctly.
     • Point Management Identity and components at the right issuer/URLs.
     • Configure secrets via existingSecret/existingSecretKey for each scenario.

3. Clarify responsibilities of each key

   In values.yaml comments, clarify each child keys in above parent keys:

   • What they control (e.g. “admin credentials used by Management Identity to talk to Keycloak” vs “credentials passed into the Bitnami subchart at install time”).
   • Which modes they apply to (internal only, external only, or both).
   • How they interact with chart defaults and docs.camunda.io guides, so users can cross‑check.

Desired outcome and acceptance tests:

• For internal Keycloak, there is a tested sample values.yaml snippet that:
  • Deploys Bitnami Keycloak and Management Identity.
  • Configures Orchestration Cluster, Connectors, Optimize, Web Modeler, and Console to authenticate via internal Keycloak.
• For external Keycloak, there is a tested snippet that:
  • Disables the Bitnami subchart.
  • Configures Management Identity and components to use an external Keycloak realm.
• For external OIDC provider, there is a tested snippet that:
  • Disables internal Keycloak.
  • Configures components to authenticate against the external OIDC provider (with or without Management Identity).
• In each case, the required keys under:
  • identityKeycloak.*
  • identity.*
  • global.identity.auth.<COMPONENT>.*
  • global.identity.keycloak.*
    are clearly documented as “required for this mode” or “optional / advanced”.