feat(helm-chart): add IdP via internal keycloak guide

docs/self-managed/deployment/helm/configure/authentication-and-authorization/external-idp-via-internal-keycloak.md

@@ -0,0 +1,154 @@
+---
+id: external-idp-via-internal-keycloak
+sidebar_label: External IdP via Internal Keycloak
+title: Set up the Helm chart with an external IdP through the internal Keycloak
+description: Learn how to configure an external identity provider to authenticate users while using the internal Keycloak as an identity broker.
+---
+
+This guide shows you how to configure the internal Keycloak instance to act as an identity broker, delegating authentication to an external identity provider (IdP) such as a corporate OIDC provider, SAML, LDAP, or Active Directory.
+
+This setup allows you to:
+
+- Use your organization's existing identity provider for user authentication
+- Retain the internal Keycloak for Camunda's OIDC integration
+- Manage user authorization through Camunda's identity systems
+
+## Prerequisites
+
+- A Camunda 8 deployment with internal Keycloak enabled. See [Set up the Helm chart with the internal Keycloak instance](/self-managed/deployment/helm/configure/authentication-and-authorization/internal-keycloak.md).
+- Access to your external IdP's configuration (client credentials, endpoints, etc.)
+
+## Configure the external identity provider
+
+Complete the following steps to integrate your external IdP:
+
+1. [Add your external IdP to Keycloak](#add-your-external-idp-to-keycloak)
+1. [Configure identity provider mappers](#configure-identity-provider-mappers)
+1. [Configure Orchestration Cluster Identity](#configure-orchestration-cluster-identity)
+1. [Configure Management Identity access](#configure-management-identity-access-optional) (optional)
+
+### Add your external IdP to Keycloak
+
+Configure Keycloak to use your external identity provider by following the [Configure an external IdP using Keycloak](/self-managed/components/management-identity/configuration/configure-external-identity-provider.md) guide.
+
+### Configure identity provider mappers
+
+After adding the identity provider, configure mappers in the **Camunda realm** (default: `camunda-platform`) to import user attributes and assign users to a group for authorization.
+
+:::tip
+For details on Keycloak identity provider mappers, see the [Keycloak documentation on identity broker mappers](https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers).
+:::
+
+#### Create attribute mappers
+
+Attribute mappers import user profile information from the external IdP into Keycloak user accounts.
+
+In Keycloak Admin Console, navigate to **Identity Providers** > select your IdP > **Mappers** tab.
+
+Create attribute mappers to import user profile information:
+
+| Name        | Mapper Type        | Claim         | User Attribute |
+| ----------- | ------------------ | ------------- | -------------- |
+| `email`     | Attribute Importer | `email`       | `email`        |
+| `firstName` | Attribute Importer | `given_name`  | `firstName`    |
+| `lastName`  | Attribute Importer | `family_name` | `lastName`     |
+
+#### Create username mapper
+
+The username mapper determines how Keycloak assigns usernames to federated users based on claims from the external IdP.
+
+Create a username mapper:
+
+- **Name**: `username`
+- **Mapper Type**: Username Template Importer
+- **Template**: `${CLAIM.preferred_username}`
+
+#### Create group for external IdP users
+
+Navigate to **Groups** > **Create group** and create a group:
+
+- **Name**: `external-idp-users`
+
+#### Assign users to the group
+
+The hardcoded group mapper automatically assigns all users authenticating through this IdP to a specified group. This group membership is then included in the user's access token.
+
+Create a mapper to assign federated users to this group:
+
+- **Name**: `assign-external-idp-group`
+- **Mapper Type**: Hardcoded Group
+- **Group**: `external-idp-users`
+
+### Configure Orchestration Cluster Identity
+
+External IdP users can now authenticate, but require authorization to access Camunda components.
+
+Log in to **Orchestration Cluster Identity** as an administrator.
+
+#### Grant component access
+
+Grant access to Orchestration Cluster components for the external IdP users group:
+
+1. Navigate to **Authorizations** > select **Component** > **Create authorization**.
+1. Configure the authorization:
+   - **Owner type**: `Group`
+   - **Owner ID**: `external-idp-users`
+   - **Resource ID**: `*`
+   - **Permissions**: `ACCESS`
+
+#### Grant additional permissions (optional)
+
+Grant additional permissions as needed. For example, to allow users to view processes and complete tasks:
+
+| Resource Type      | Resource ID | Permissions                                                          |
+| ------------------ | ----------- | -------------------------------------------------------------------- |
+| Process Definition | `*`         | `READ_PROCESS_DEFINITION`, `READ_PROCESS_INSTANCE`, `READ_USER_TASK` |
+| Process Definition | `*`         | `UPDATE_USER_TASK`                                                   |
+
+:::info
+For more details on authorizations, see [Orchestration Cluster authorization](/components/concepts/access-control/authorizations.md).
+:::
+
+### Configure Management Identity access (Optional)
+
+For access to Console, Web Modeler, and Optimize, external IdP users need the corresponding realm roles assigned in Keycloak. The recommended approach is to assign users to groups that have these roles.
+
+:::note
+The hardcoded group mappers in this section grant access to **all users** authenticating through the external IdP. For more granular access control based on groups or attributes from your external IdP, see the [Keycloak documentation on identity provider mappers](https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers).
+:::
+
+#### Verify or create groups
+
+1. In Keycloak Admin Console, navigate to **Groups**.
+1. Verify that groups exist for each component (e.g., `Console`, `Optimize`, `Web Modeler`). If not, create them.
+
+#### Assign roles to groups
+
+Ensure each group has the corresponding realm role assigned:
+
+1. Select the group > **Role Mappings** tab.
+1. Click **Assign role** and add the role with the same name (e.g., `Console`).
+
+#### Create group mappers
+
+Create mappers to assign federated users to these groups:
+
+1. Navigate to **Identity Providers** > select your IdP > **Mappers** tab.
+1. Click **Add mapper** for each component:
+
+| Mapper Name               | Mapper Type     | Group         |
+| ------------------------- | --------------- | ------------- |
+| `assign-console-group`    | Hardcoded Group | `Console`     |
+| `assign-optimize-group`   | Hardcoded Group | `Optimize`    |
+| `assign-webmodeler-group` | Hardcoded Group | `Web Modeler` |
+
+:::tip
+You can also assign roles directly to users in Keycloak, or use [mapping rules in Management Identity](/self-managed/components/management-identity/mapping-rules.md) to map token claims to roles.
+:::
+
+## Next steps
+
+- To understand the differences between Orchestration Cluster Identity and Management Identity, see [Identity types in Camunda 8](/components/concepts/access-control/access-control-overview.md#identity-types-in-camunda-8).
+- To learn more about mapping rules, see [Mapping rules](/components/concepts/access-control/mapping-rules.md).
+- To configure additional authorizations, see [Orchestration Cluster authorization](/components/concepts/access-control/authorizations.md).
+- To use an external IdP without the internal Keycloak, see [Set up the Helm chart with an external OIDC provider](/self-managed/deployment/helm/configure/authentication-and-authorization/external-oidc-provider.md).

docs/self-managed/deployment/helm/configure/authentication-and-authorization/index.md

@@ -12,11 +12,12 @@ By default, Camunda uses basic authentication with predefined demo users. Altern
 
 ### Authentication options
 
-| Method                                                | Description                                                                                         | Recommended for                                                           |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| [Basic authentication](./basic-authentication.md)     | Default authentication with preconfigured demo users. No external identity provider (IdP) required. | Local development and testing, as well as smaller scale production setups |
-| [Internal Keycloak](./internal-keycloak.md)           | Deploys a Keycloak pod with the Helm release, preconfigured by Management Identity.                 | Small teams or self-contained environments                                |
-| [External OIDC provider](./external-oidc-provider.md) | Integrates Camunda with external IdPs such as Microsoft Entra ID or Okta via OpenID Connect.        | Existing enterprise identity infrastructure                               |
+| Method                                                                        | Description                                                                                         | Recommended for                                                               |
+| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| [Basic authentication](./basic-authentication.md)                             | Default authentication with preconfigured demo users. No external identity provider (IdP) required. | Local development and testing, as well as smaller scale production setups     |
+| [Internal Keycloak](./internal-keycloak.md)                                   | Deploys a Keycloak pod with the Helm release, preconfigured by Management Identity.                 | Small teams or self-contained environments                                    |
+| [External IdP via Internal Keycloak](./external-idp-via-internal-keycloak.md) | Uses internal Keycloak as identity broker, delegating to external IdPs like SAML, LDAP, or AD.      | Organizations with existing identity infrastructure wanting Keycloak benefits |
+| [External OIDC provider](./external-oidc-provider.md)                         | Integrates Camunda with external IdPs such as Microsoft Entra ID or Okta via OpenID Connect.        | Existing enterprise identity infrastructure                                   |
 
 ### Limitations of OIDC setups
 
@@ -27,6 +28,7 @@ front channel single sign out is not supported. This means that when a user logs
 
 - [Basic authentication guide](./basic-authentication.md)
 - [Internal Keycloak guide](./internal-keycloak.md)
+- [External IdP via Internal Keycloak guide](./external-idp-via-internal-keycloak.md)
 - [External Keycloak guide](./external-keycloak.md)
 - [Microsoft Entra guide](./microsoft-entra.md)
 - [Generic OIDC provider](./generic-oidc-provider.md)

docs/self-managed/deployment/helm/configure/authentication-and-authorization/react-components/_card-data.js

@@ -7,6 +7,13 @@ import IconGear from "../../../../../../components/assets/icon-orchcluster.png";
 
 // Backup and Restore overview cards data
 export const overviewCards = [
+  {
+    link: "../external-idp-via-internal-keycloak",
+    title: "External IdP via Internal Keycloak",
+    image: IconGear,
+    description:
+      "Use internal Keycloak as identity broker, delegating authentication to external IdPs like SAML, LDAP, or Active Directory.",
+  },
   {
     link: "../external-keycloak",
     title: "External Keycloak",

sidebars.js

@@ -1492,6 +1492,7 @@ module.exports = {
                         "self-managed/deployment/helm/configure/authentication-and-authorization/external-keycloak",
                         "self-managed/deployment/helm/configure/authentication-and-authorization/microsoft-entra",
                         "self-managed/deployment/helm/configure/authentication-and-authorization/generic-oidc-provider",
+                        "self-managed/deployment/helm/configure/authentication-and-authorization/external-idp-via-internal-keycloak",
                         "self-managed/deployment/helm/configure/authentication-and-authorization/troubleshooting-oidc",
                       ],
                     },

versioned_docs/version-8.8/self-managed/deployment/helm/configure/authentication-and-authorization/external-idp-via-internal-keycloak.md

@@ -0,0 +1,154 @@
+---
+id: external-idp-via-internal-keycloak
+sidebar_label: External IdP via Internal Keycloak
+title: Set up the Helm chart with an external IdP through the internal Keycloak
+description: Learn how to configure an external identity provider to authenticate users while using the internal Keycloak as an identity broker.
+---
+
+This guide shows you how to configure the internal Keycloak instance to act as an identity broker, delegating authentication to an external identity provider (IdP) such as a corporate OIDC provider, SAML, LDAP, or Active Directory.
+
+This setup allows you to:
+
+- Use your organization's existing identity provider for user authentication
+- Retain the internal Keycloak for Camunda's OIDC integration
+- Manage user authorization through Camunda's identity systems
+
+## Prerequisites
+
+- A Camunda 8 deployment with internal Keycloak enabled. See [Set up the Helm chart with the internal Keycloak instance](/self-managed/deployment/helm/configure/authentication-and-authorization/internal-keycloak.md).
+- Access to your external IdP's configuration (client credentials, endpoints, etc.)
+
+## Configure the external identity provider
+
+Complete the following steps to integrate your external IdP:
+
+1. [Add your external IdP to Keycloak](#add-your-external-idp-to-keycloak)
+1. [Configure identity provider mappers](#configure-identity-provider-mappers)
+1. [Configure Orchestration Cluster Identity](#configure-orchestration-cluster-identity)
+1. [Configure Management Identity access](#configure-management-identity-access-optional) (optional)
+
+### Add your external IdP to Keycloak
+
+Configure Keycloak to use your external identity provider by following the [Configure an external IdP using Keycloak](/self-managed/components/management-identity/configuration/configure-external-identity-provider.md) guide.
+
+### Configure identity provider mappers
+
+After adding the identity provider, configure mappers in the **Camunda realm** (default: `camunda-platform`) to import user attributes and assign users to a group for authorization.
+
+:::tip
+For details on Keycloak identity provider mappers, see the [Keycloak documentation on identity broker mappers](https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers).
+:::
+
+#### Create attribute mappers
+
+Attribute mappers import user profile information from the external IdP into Keycloak user accounts.
+
+In Keycloak Admin Console, navigate to **Identity Providers** > select your IdP > **Mappers** tab.
+
+Create attribute mappers to import user profile information:
+
+| Name        | Mapper Type        | Claim         | User Attribute |
+| ----------- | ------------------ | ------------- | -------------- |
+| `email`     | Attribute Importer | `email`       | `email`        |
+| `firstName` | Attribute Importer | `given_name`  | `firstName`    |
+| `lastName`  | Attribute Importer | `family_name` | `lastName`     |
+
+#### Create username mapper
+
+The username mapper determines how Keycloak assigns usernames to federated users based on claims from the external IdP.
+
+Create a username mapper:
+
+- **Name**: `username`
+- **Mapper Type**: Username Template Importer
+- **Template**: `${CLAIM.preferred_username}`
+
+#### Create group for external IdP users
+
+Navigate to **Groups** > **Create group** and create a group:
+
+- **Name**: `external-idp-users`
+
+#### Assign users to the group
+
+The hardcoded group mapper automatically assigns all users authenticating through this IdP to a specified group. This group membership is then included in the user's access token.
+
+Create a mapper to assign federated users to this group:
+
+- **Name**: `assign-external-idp-group`
+- **Mapper Type**: Hardcoded Group
+- **Group**: `external-idp-users`
+
+### Configure Orchestration Cluster Identity
+
+External IdP users can now authenticate, but require authorization to access Camunda components.
+
+Log in to **Orchestration Cluster Identity** as an administrator.
+
+#### Grant component access
+
+Grant access to Orchestration Cluster components for the external IdP users group:
+
+1. Navigate to **Authorizations** > select **Component** > **Create authorization**.
+1. Configure the authorization:
+   - **Owner type**: `Group`
+   - **Owner ID**: `external-idp-users`
+   - **Resource ID**: `*`
+   - **Permissions**: `ACCESS`
+
+#### Grant additional permissions (optional)
+
+Grant additional permissions as needed. For example, to allow users to view processes and complete tasks:
+
+| Resource Type      | Resource ID | Permissions                                                          |
+| ------------------ | ----------- | -------------------------------------------------------------------- |
+| Process Definition | `*`         | `READ_PROCESS_DEFINITION`, `READ_PROCESS_INSTANCE`, `READ_USER_TASK` |
+| Process Definition | `*`         | `UPDATE_USER_TASK`                                                   |
+
+:::info
+For more details on authorizations, see [Orchestration Cluster authorization](/components/concepts/access-control/authorizations.md).
+:::
+
+### Configure Management Identity access (Optional)
+
+For access to Console, Web Modeler, and Optimize, external IdP users need the corresponding realm roles assigned in Keycloak. The recommended approach is to assign users to groups that have these roles.
+
+:::note
+The hardcoded group mappers in this section grant access to **all users** authenticating through the external IdP. For more granular access control based on groups or attributes from your external IdP, see the [Keycloak documentation on identity provider mappers](https://www.keycloak.org/docs/latest/server_admin/index.html#_mappers).
+:::
+
+#### Verify or create groups
+
+1. In Keycloak Admin Console, navigate to **Groups**.
+1. Verify that groups exist for each component (e.g., `Console`, `Optimize`, `Web Modeler`). If not, create them.
+
+#### Assign roles to groups
+
+Ensure each group has the corresponding realm role assigned:
+
+1. Select the group > **Role Mappings** tab.
+1. Click **Assign role** and add the role with the same name (e.g., `Console`).
+
+#### Create group mappers
+
+Create mappers to assign federated users to these groups:
+
+1. Navigate to **Identity Providers** > select your IdP > **Mappers** tab.
+1. Click **Add mapper** for each component:
+
+| Mapper Name               | Mapper Type     | Group         |
+| ------------------------- | --------------- | ------------- |
+| `assign-console-group`    | Hardcoded Group | `Console`     |
+| `assign-optimize-group`   | Hardcoded Group | `Optimize`    |
+| `assign-webmodeler-group` | Hardcoded Group | `Web Modeler` |
+
+:::tip
+You can also assign roles directly to users in Keycloak, or use [mapping rules in Management Identity](/self-managed/components/management-identity/mapping-rules.md) to map token claims to roles.
+:::
+
+## Next steps
+
+- To understand the differences between Orchestration Cluster Identity and Management Identity, see [Identity types in Camunda 8](/components/concepts/access-control/access-control-overview.md#identity-types-in-camunda-8).
+- To learn more about mapping rules, see [Mapping rules](/components/concepts/access-control/mapping-rules.md).
+- To configure additional authorizations, see [Orchestration Cluster authorization](/components/concepts/access-control/authorizations.md).
+- To use an external IdP without the internal Keycloak, see [Set up the Helm chart with an external OIDC provider](/self-managed/deployment/helm/configure/authentication-and-authorization/external-oidc-provider.md).