Set up an external IdP with internal Keycloak

This guide explains how to configure the internal Keycloak instance as an identity broker that delegates authentication to an external identity provider (IdP), such as an 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 OIDC integration
• Manage user authorization in Camunda identity components

Prerequisites

• A Camunda 8 deployment with internal Keycloak enabled. For setup instructions, see Configure internal Keycloak for Helm deployments.
• Access to your external IdP's configuration (client credentials, endpoints, etc.)

Configure the external identity provider

Complete the following steps:

1. Add your external IdP to Keycloak
2. Configure identity provider mappers
3. Configure Orchestration Cluster Identity
4. Configure Management Identity access (optional)

Add your external IdP to Keycloak

Configure Keycloak to use your external identity provider by following the Configure an external IdP using Keycloak 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.

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 authenticate, but still 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.
2. 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
User task	*	UPDATE_USER_TASK

info

For more details, see Configure Orchestration Cluster authorizations.

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.

Verify or create groups

1. In Keycloak Admin Console, navigate to Groups.
2. 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.
2. 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.
2. 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 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.
• To learn more about mapping rules, see Mapping rules.
• To configure additional authorizations, see Orchestration Cluster authorization.
• To use an external IdP without the internal Keycloak, see Set up the Helm chart with an external OIDC provider.