Camunda Platform 7 - Keycloak Identity Provider Plugin

Keycloak™ (https://www.keycloak.org/) is an Open Source Identity and Access Management platform including advanced features such as User Federation, Identity Brokering and Social Login.

Camunda™ (https://camunda.com/) Platform 7 is perfectly suited to carry out BPM projects in the cloud. Identity management in the cloud, however, often differs from classical approaches. Camunda already provides a generic sample for Single Sign On when using Spring Boot. See https://github.com/camunda-consulting/code/tree/master/snippets/springboot-security-sso. Specific instructions on how to use Spring Boots OAuth2 SSO in combination with this Keycloak Identity Provider Plugin can be found below.

Why this plugin? SSO is sufficient in case you only want authentication but have no further advanced security roles. If one needs to use Camundas IdentityService APIs or wants to see actual Users and Groups show up in Cockpit, a custom IdentityProvider needs to be implemented as well.

This plugin provides the basis for using Keycloak as Identity Management solution and will provide a ReadOnlyIdentityProvider. What you will get is a fully integrated solution for using Keycloak as an Identity Provider in Camunda receiving users and groups from Keycloak. The authorization of these users and groups for Camunda resources itself remains within Camunda. This plugin allows the usage of Keycloak as Identity Provider even without SSO.

Beware: in case you want to use Keycloak's advanced login capabilities for social connections you must configure SSO as well. Password grant exchanges are only supported for Keycloak's internally managed users and users of an LDAP / Keberos User federation. Hence without SSO you will only be able to login with users managed by such connections.

Current version: 7.19.0
Latest tests with: Keycloak 21.1.1, 19.0.3-legacy, Camunda 7.19.0, 7.19.0-ee

Features

Changes in version 7.19.0

• Updated samples to Camunda Platform 7.19 and Keycloak 21.1

New in version 7.18.0

• Fixed a bug for userId's containing a plus sign.
• Updated samples to Camunda Platform 7.18 and Keycloak >= 18
• Alternative for client side JWT authentication in Camunda Cockpit (incubation status)

Changes in Version 7.17.0

• Renamed the extension from camunda-bpm-identity-keycloak to camunda-platform-7-keycloak
• Updated samples to Camunda Platform 7.17
• Introduced new version which reflects the Camunda Version used in samples and tests.

New in Version 2.2.3:

• Optional Keycloak Login Cache - helps you to minimize password check requests to Keycloak and thus improve performance. Not applicable in SSO scenarios, but useful e.g. when using External Task Clients with Basic Auth.

New in Version 2.2.2:

• Optimized user / group queries when using single items in userIdIn(...) / groupIdIn(...) selections

New in Version 2.2.1:

• Fixed a bug where "like" filters in combination with missing Keycloak attributes (e.g. users without email) may cause a NullPointerException

New in Version 2.2.0:

• Optional Keycloak Query Cache - helps you to minimize requests to Keycloak and thus improve performance.
• Minor optimization of refresh token handling in case it is missing at all.

New in Version 2.1.0:

• Auto retry with refreshed new token in case of Keycloak HTTP 401 responses (more stability in case of misconfigurations).

New in Version 2.0.0:

• Support for Camunda Platform 7 Run
• New options proxyUri, proxyUser, proxyPassword for optional proxy support.
• Usage of com.google.code.gson for JSON (de)serialization.
• Further internal refactorings and preparations for future enhancements.

New in Version 1.5.0:

• New option maxResultSize for configuring the maximum result size of queries against the Keycloak REST API.

New in Version 1.4.0:

• Corrected rare problems with group queries of a single user in case the Keycloak Client name is similar to this username and config property useUsernameAsCamundaUserId=true

New in Version 1.3.0:

• Provided additional fat camunda-platform-7-keycloak-all.jar including transitive dependencies for easier installation e.g. on Apache Tomcat distribution with shared engine.

New in Version 1.2.0:

• Optimized and correct searches in Keycloak mass data
• Add missing paging functionality to queries

New in Version 1.1.0:

• Ability to read group hierarchies.
• New option useGroupPathAsCamundaGroupId for readable group IDs. Helps when configuring authorizations.

Version 1.0.0:

• ReadOnlyIdentityProvider
• Broad support for user and group queries
• Compatible with Spring Boot OAuth2 SSO

Known limitations:

• A strategy to distinguish SYSTEM and WORKFLOW groups is missing. Currently only the administrator group is mapped to type SYSTEM.
• Some query filters are applied on the client side - the Keycloak REST API does not allow full criteria search in all required cases.
• Sort criteria for queries are implemented on the client side - the Keycloak REST API does not allow result ordering.
• Tenants are currently not supported.

Prerequisites in your Keycloak realm

1. Keycloak docker images can be found on Keycloak Docker Hub.

2. Create a new client named camunda-identity-service with access type confidential and service accounts enabled: Please be aware, that beginning with Keycloak 18, you do not only have to configure a valid redirect URL, but a valid post logout redirect URL as well. To keep things easy values can be the same.

3. In order to use refresh tokens set the "Use Refresh Tokens For Client Credentials Grant" option within the "OpenID Connect Compatibility Modes" section (available in newer Keycloak versions):

   

4. Add the roles query-groups, query-users, view-users to the service account client roles of your realm (choose realm-management or master-realm, depending on whether you are using a separate realm or master):

5. Your client credentials can be found here:

6. Once you're done with the basic setup you're now ready to manage your users and groups with Keycloak. Please keep in mind, that in order to make the Keycloak Identity Provider work, you will need at least one dedicated Camunda admin group or Camunda admin user in your realm. Whether you create this group/user manually or import it using the LDAP user federation or any other Identity Provider is up to you.

Usage with Camunda Spring Boot

Maven Dependencies:

<dependency>
    <groupId>org.camunda.bpm.extension</groupId>
    <artifactId>camunda-platform-7-keycloak</artifactId>
    <version>7.18.0</version>
</dependency>

Add the following class to your Camunda Spring Boot application in order to activate the Keycloak Identity Provider Plugin:

package <your-package>;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.camunda.bpm.extension.keycloak.plugin.KeycloakIdentityProviderPlugin;

@Component
@ConfigurationProperties(prefix="plugin.identity.keycloak")
public class KeycloakIdentityProvider extends KeycloakIdentityProviderPlugin {
}

Configuration in application.yaml will then look as follows:

camunda.bpm:
  ...
  authorization:
    enabled: true

plugin.identity.keycloak:
  keycloakIssuerUrl: https://<your-keycloak-server>/auth/realms/<realm-name>
  keycloakAdminUrl: https://<your-keycloak-server>/auth/admin/realms/<realm-name>
  clientId: camunda-identity-service
  clientSecret: 42aa42bb-1234-4242-a24a-42a2b420cde0
  useEmailAsCamundaUserId: true
  administratorGroupName: camunda-admin

Hint: the engine must not create a user upon startup - the plugin is a ReadOnlyIdentityProvider. Hence you must not configure an admin-user for camunda.bpm in your application.yaml. The following configuration will likely cause errors upon startup:

camunda.bpm:
# DON'T DO THIS
  admin-user:
    id: demo
    password: demo
    firstName: Camunda

The admin-user part must be deleted in order to work properly. The recommended procedure for creating the admin user and admin group in Keycloak is to have the deployment pipeline do this during the environment setup phase.

A list of configuration options can be found below:

Caching options

This is a ReadOnlyIdentityProvider which translates all queries against the Camunda IdentityService in REST queries against Keycloak. Under high load it makes sense to not request the same things again and again, especially since the data of users and groups do not change every second. Therefore this plugin provides an optional cache feature.

User and group query caching

In order to activate caching of user and group queries you have the following options available:

Besides caching of user and group queries there is another scenario where caching could make sense.

Login caching

Imagine a setup with lots of External Task Clients using HTTP Basic Auth against the Camunda REST API (e.g. set camunda.bpm.run.auth.enabled: true when using Camunda Run). Your External Task Clients then might trigger the IdentityProvider's checkPassword function at high frequency. This function requests a token from Keycloak each time it is called. In case of a successful response the login is treated as valid. High frequency then means requesting lots of tokens - in the worst case all for the same user and before an already delivered token has timed out. Therefore this plugin provides an optional login cache feature as well.

In order to activate the login cache you have the following options available:

On the downside this feature bypasses the password grant exchange function of Keycloak until the configured timeout expires. So the choice is yours. Please be aware that the login cache is not applicable for SSO scenarios.

Activating Single Sign On

In this part, we’ll discuss how to activate SSO – Single Sign On – for the Camunda Web App using Spring Boot and Spring Security 5.2.x OAuth 2.0 Client capabilities in combination with this plugin and Keycloak as authorization server.

In order to setup Spring Boot's OAuth2 security add the following Maven dependencies to your project:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-oauth2-client</artifactId>
</dependency>

What we need is a bridge between Spring Security and Camunda. Hence insert a KeycloakAuthenticationProvider as follows:

/**
  * OAuth2 Authentication Provider for usage with Keycloak and KeycloakIdentityProviderPlugin. 
  */
public class KeycloakAuthenticationProvider extends ContainerBasedAuthenticationProvider {

    @Override
    public AuthenticationResult extractAuthenticatedUser(HttpServletRequest request, ProcessEngine engine) {

        // Extract user-name-attribute of the OAuth2 token
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        if (!(authentication instanceof OAuth2AuthenticationToken) || !(authentication.getPrincipal() instanceof OidcUser)) {
            return AuthenticationResult.unsuccessful();
        }
        String userId = ((OidcUser)authentication.getPrincipal()).getName();
        if (StringUtils.isEmpty(userId)) {
            return AuthenticationResult.unsuccessful();
        }

        // Authentication successful
        AuthenticationResult authenticationResult = new AuthenticationResult(userId, true);
        authenticationResult.setGroups(getUserGroups(userId, engine));

        return authenticationResult;
    }

    private List<String> getUserGroups(String userId, ProcessEngine engine){
        List<String> groupIds = new ArrayList<>();
        // query groups using KeycloakIdentityProvider plugin
        engine.getIdentityService().createGroupQuery().groupMember(userId).list()
            .forEach( g -> groupIds.add(g.getId()));
        return groupIds;
    }

}

Last but not least add a security configuration and enable OAuth2 SSO:

/**
* Camunda Web application SSO configuration for usage with KeycloakIdentityProviderPlugin.
*/
@ConditionalOnMissingClass("org.springframework.test.context.junit.jupiter.SpringExtension")
@Configuration
@Order(SecurityProperties.BASIC_AUTH_ORDER - 10)
public class WebAppSecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
        .csrf().ignoringAntMatchers("/api/**")
        .and()
        .requestMatchers().antMatchers("/**").and()
          .authorizeRequests(authorizeRequests ->
            authorizeRequests
            .antMatchers("/app/**", "/api/**", "/lib/**")
            .authenticated()
            .anyRequest()
            .permitAll()
          )
        .oauth2Login()
        ;
    }

    @SuppressWarnings({ "rawtypes", "unchecked" })
    @Bean
    public FilterRegistrationBean containerBasedAuthenticationFilter(){

        FilterRegistrationBean filterRegistration = new FilterRegistrationBean();
        filterRegistration.setFilter(new ContainerBasedAuthenticationFilter());
        filterRegistration.setInitParameters(Collections.singletonMap("authentication-provider", "org.camunda.bpm.extension.keycloak.showcase.sso.KeycloakAuthenticationProvider"));
        filterRegistration.setOrder(101); // make sure the filter is registered after the Spring Security Filter Chain
        filterRegistration.addUrlPatterns("/app/*");
        return filterRegistration;
    }

    @Bean
    @Order(0)
    public RequestContextListener requestContextListener() {
        return new RequestContextListener();
    }
}

Finally configure Spring Security with your Keycloak Single Page Web App client-id and client-secret in application.yaml as follows:

# Spring Boot Security OAuth2 SSO
spring.security.oauth2:
  client:
    registration:
      keycloak:
        provider: keycloak
        client-id: camunda-identity-service
        client-secret: yyy2121abc21def2121ghi212132121abc21def2121ghi2121eyyy
        authorization-grant-type: authorization_code
        redirect-uri: "{baseUrl}/{action}/oauth2/code/{registrationId}"
        scope: openid, profile, email
    provider:
      keycloak:
        issuer-uri: https://<your-keycloak-server>/auth/realms/camunda
        authorization-uri: https://<your-keycloak-server>/auth/realms/camunda/protocol/openid-connect/auth
        user-info-uri: https://<your-keycloak-server>/auth/realms/camunda/protocol/openid-connect/userinfo
        token-uri: https://<your-keycloak-server>/auth/realms/camunda/protocol/openid-connect/token
        jwk-set-uri: https://<your-keycloak-server>/auth/realms/camunda/protocol/openid-connect/certs
        # set user-name-attribute one of: 
        # - sub                -> default; using keycloak ID as camunda user ID
        # - email              -> useEmailAsCamundaUserId=true
        # - preferred_username -> useUsernameAsCamundaUserId=true
        user-name-attribute: email

Beware: You have to set the parameter user-name-attribute of the spring.security.oauth2.client.provider.keycloak in a way that it matches the configuration of your KeycloakIdentityProviderPlugin:

• useEmailAsCamundaUserId: true - set user-name-attribute: email
• useUsernameAsCamundaUserId: true - set user-name-attribute: preferred_username
• neither of the above two, using Keycloak's ID as default - set user-name-attribute: sub

Keep in mind that Keycloak's email attribute might not always be unique, depending on your setup. Email uniqueness can be configured on a per realm level depending on the setting Login with email.

Quickstart

As a quickstart into using and configuring the plugin we recommend to have a look at the Installation on Camunda Platform Run. You'll find a chapter "Docker Sample Setup" at the end of the README. This is a simple starting point.

If your intention is a complete SSO setup on Kubernetes you'll be more happy with the next reference.

Sample Spring Boot Project with SSO on Kubernetes

A sample project using this plugin including a basic SSO and Kubernetes setup can be found under Camunda Showcase for Spring Boot & Keycloak Identity Provider. See directory examples.

Installation on Apache Tomcat with Shared Process Engine

Even if from an architectural point of view Spring Boot is currently the most recommended approach for cloud scenarios, it is of course possible to install the plugin in other Camunda distributions as well. A description on how to install the plugin on an Apache Tomcat full distribution can be found under Installation on Tomcat. See directory examples.

Installation on Camunda Platform Run

A description on how to install the plugin on Camunda BPM Run can be found under Installation on Camunda BPM Run. See directory examples.

Installation on JBoss/Wildfly

A description on how to install the plugin on a JBoss/Wildfly can be found under Installation on JBoss/Wildfly. See directory examples.

Unit testing the plugin

In order to run the unit tests I have used a local docker setup of Keycloak with docker-compose.yml as follows:

version: "3.9"

services:
  jboss.keycloak:
    image: quay.io/keycloak/keycloak:21.1.1
    restart: always
    environment:
      TZ: Europe/Berlin
      DB_VENDOR: h2
      KEYCLOAK_ADMIN: keycloak
      KEYCLOAK_ADMIN_PASSWORD: keycloak1!
      KC_HTTP_RELATIVE_PATH: /auth
    ports:
      - "8443:8443"
      - "8080:8080"
    command:
      - start-dev
      - --features admin-fine-grained-authz

For details see documentation on Running Keycloak in a container.

Maven test setup

Running unit tests from Maven requires configuring the details of a running Keycloak server. This can be achieved by setting the following environment variables:

In case you choose Keycloak in the new Quarkus distribution, please be aware that /auth has been removed from the default context path. Hence, it is required to change the KEYCLOAK_URL for the tests. Tests also run successfully against the Quarkus distribution, in case you start Keycloak in Development mode.

That's it. Have a happy Keycloak experience and focus on what really matters: the core processes of your customer.

Brought to you by:

Gunnar von der Beck, Accso - Accelerated Solutions GmbH

Resources

• Issue Tracker
• Contributing

Maintainer

• Gunnar von der Beck

License

License: Apache License 2.0