Keycloak SSO Integration into jBPM and Drools Workbench

Introduction

Single Sign On (SSO) and related token exchange mechanisms are becoming the most common scenario for the authentication and authorization in different environments on the web, specially when moving into the cloud.

This article talks about the integration of Keycloak with jBPM or Drools applications in order to use all the features provided on Keycloak. Keycloak is an integrated SSO and IDM for browser applications and RESTful web services. Lean more about it in the Keycloak’s home page.

The result of the integration with Keycloak has lots of advantages such as:

• Provide an integrated SSO and IDM environment for different clients, including jBPM and Drools workbenches
• Social logins – use your Facebook, Google, Linkedin, etc accounts
• User session management
• And much more…

Next sections cover the following integration points with Keycloak:

• Workbench authentication through a Keycloak server: It basically consists of securing both web client and remote service clients through the Keycloak SSO. So either web interface or remote service consumers ( whether a user or a service ) will authenticate into trough KC.
• Execution server authentication through a Keycloak server: Consists of securing the remote services provided by the execution server (as it does not provides web interface). Any remote service consumer ( whether a user or a service ) will authenticate trough KC.
• Consuming remote services: This section describes how a third party clients can consume the remote service endpoints provided by both Workbench and Execution Server.

Scenario

Consider the following diagram as the environment for this article’s example:

Keycloak is a standalone process that provides remote authentication, authorization and administration services that can be potentially consumed by one or more jBPM applications over the network.

Consider these main steps for building this environment:

• Install and setup a Keycloak server
• Create and setup a Realm for this example – Configure realm’s clients, users and roles
• Install and setup the SSO client adapter & jBPM application

Notes:

• The resulting environment and the different configurations for this article are based on the jBPM (KIE) Workbench, but same ones can also be applied for the KIE Drools Workbench as well.
• This example uses latest 6.4.0.CR2 community release version

Step 1 – Install and setup a Keycloak server

Keycloak provides an extensive documentation and several articles about the installation on different environments. This section describes the minimal setup for being able to build the integrated environment for the example. Please refer to the Keycloak documentation if you need more information.

Here are the steps for a minimal Keycloak installation and setup:

1. Download latest version of Keycloak from the Downloads section. This example is based on Keycloak 1.9.0.Final.
2. Unzip the downloaded distribution of Keycloak into a folder, let’s refer it as $KC_HOME
3. Run the KC server – This example is based on running both Keycloak and jBPM on same host. In order to avoid port conflicts you can use a port offset for the Keycloak’s server as:

   $KC_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100

4. Create a Keycloak’s administration user – Execute the following command to create an admin user for this example:

   $KC_HOME/bin/add-user.sh -r master -u 'admin' -p 'admin'

The Keycloak administration console will be available at http://localhost:8180/auth/admin (use the admin/admin for login credentials).

Step 2 – Create and setup the demo Realm

Security realms are used to restrict the access for the different application’s resources.

Once the Keycloak server is running next step is about creating a realm. This realm will provide the different users, roles, sessions, etc for the jBPM application/s.

Keycloak provides several examples for the realm creation and management, from the official examples to different articles with more examples.

You can create the realm manually or just import the given json files.

Creating the realm step by step

Follow these steps in order to create the demo realm used later in this article:

1. Go to the Keycloak administration console and click on Add realm button. Give it the name demo.
2. Go to the Clients section (from the main admin console menu) and create a new client for the demo realm:
   • Client ID: kie
   • Client protocol: openid-connect
   • Access type: confidential
   • Root URL: http://localhost:8080
   • Base URL: /kie-wb-6.4.0.Final
   • Redirect URIs: /kie-wb-6.4.0.Final/*

The resulting kie client settings screen:

Note: As you can see in the above settings it’s being considered the value kie-wb-6.4.0.Final for the application’s context path. If your jbpm application will be deployed on a different context path, host or port, just use your concrete settings here.

Last step for being able to use the demo realm from the jBPM workbench is create the application’s user and roles:

• Go to the Roles section and create the roles admin, kiemgmt and rest-all.
• Go to the Users section and create the admin user. Set the password with value “password” in the credentials tab, unset the temporary switch.
• In the Users section navigate to the Role Mappings tab and assign the admin, kiemgmt and rest-all roles to the admin user

Importing the demo realm

Import both:

• Demo Realm – Click on Add Realm and use the demo-realm.json file
• Realm users – Once demo realm imported, click on Import in the main menu and use the demo-users-0.json file as import source

At this point a Keycloak server is running on the host, setup with a minimal configuration set. Let’s move to the jBPM workbench setup.

Step 3 – Install and setup jBPM workbench

For this tutorial let’s use a Wildfly as the application server for the jBPM workbench, as the jBPM installer does by default.

Let’s assume, after running the jBPM installer, the $JBPM_HOME as the root path for the Wildfly server where the application has been deployed.

Step 3.1 – Install the KC adapter

In order to use the Keycloak’s authentication and authorization modules from the jBPM application, the Keycloak adapter for Wildfly must be installed on our server at $JBPM_HOME. Keycloak provides multiple adapters for different containers out of the box, if you are using another container or need to use another adapter, please take a look at the adapters configuration from Keycloak docs. Here are the steps to install and setup the adapter for Wildfly 8.2.x:

1. Download the adapter from here
2. Execute the following commands:

   cd $JBPM_HOME/
   unzip keycloak-wf8-adapter-dist.zip // Install the KC client adapter
   
   cd $JBPM_HOME/bin
   ./standalone.sh -c standalone-full.xml // Setup the KC client adapter.
   
   // ** Once server is up, open a new command line terminal and run:
   cd $JBPM_HOME/bin
   ./jboss-cli.sh -c --file=adapter-install.cli

Step 3.2 – Configure the KC adapter

Once installed the KC adapter into Wildfly, next step is to configure the adapter in order to specify different settings such as the location for the authentication server, the realm to use and so on.

Keycloak provides two ways of configuring the adapter:

• Per WAR configuration
• Via Keycloak subsystem

In this example let’s use the second option, use the Keycloak subsystem, so our WAR is free from this kind of settings. If you want to use the per WAR approach, please take a look here.

Edit the configuration file $JBPM_HOME/standalone/configuration/standalone-full.xml and locate the subsystem configuration section. Add the following content:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="kie-wb-6.4.0-Final.war">
    <realm>demo</realm>
    <realm-public-key>MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2Q3RNbrVBcY7xbpkB2ELjbYvyx2Z5NOM/9gfkOkBLqk0mWYoOIgyBj4ixmG/eu/NL2+sja6nzC4VP4G3BzpefelGduUGxRMbPzdXfm6eSIKsUx3sSFl1P1L5mIk34vHHwWYR+OUZddtAB+5VpMZlwpr3hOlfxJgkMg5/8036uebbn4h+JPpvtn8ilVAzrCWqyaIUbaEH7cPe3ecou0ATIF02svz8o+HIVQESLr2zPwbKCebAXmY2p2t5MUv3rFE5jjFkBaY25u4LiS2/AiScpilJD+BNIr/ZIwpk6ksivBIwyfZbTtUN6UjPRXe6SS/c1LaQYyUrYDlDpdnNt6RboQIDAQAB</realm-public-key>
    <auth-server-url>http://localhost:8180/auth</auth-server-url>
    <ssl-required>external</ssl-required>
    <resource>kie</resource>
    <enable-basic-auth>true</enable-basic-auth>
    <credential name="secret">925f9190-a7c1-4cfd-8a3c-004f9c73dae6</credential>
    <principal-attribute>preferred_username</principal-attribute>
  </secure-deployment>
</subsystem>

If you have imported the example json files from this article in step 2, you can just use same configuration as above by using your concrete deployment name . Otherwise please use your values for these configurations:

• Name for the secure deployment – Use your concrete application’s WAR file name
• Realm – Is the realm that the applications will use, in our example, the demo realm created on step 2.
• Realm Public Key – Provide here the public key for the demo realm. It’s not mandatory, if it’s not specified, it will be retrieved from the server. Otherwise, you can find it in the Keycloak admin console -> Realm settings ( for demo realm ) -> Keys
• Authentication server URL – The URL for the Keycloak’s authentication server
• Resource – The name for the client created on step 2. In our example, use the value kie.
• Enable basic auth – For this example let’s enable Basic authentication mechanism as well, so clients can use both Token (Baerer) and Basic approaches to perform the requests.
• Credential – Use the password value for the kie client. You can find it in the Keycloak admin console -> Clients -> kie -> Credentials tab -> Copy the value for the secret.

For this example you have to take care about using your concrete values for secure-deployment name, realm-public-key and credential password. You can find detailed information about the KC adapter configurations here.

Step 3.3 – Run the environment

At this point a Keycloak server is up and running on the host, and the KC adapter is installed and configured for the jBPM application server. You can run the application using:

$JBPM_HOME/bin/standalone.sh -c standalone-full.xml

You can navigate into the application once the server is up at: http://localhost:8080/kie-wb-6.4.0.Final

Use your Keycloak’s admin user credentials to login: admin/password

Securing workbench remote services via Keycloak

Both jBPM and Drools workbenches provides different remote service endpoints that can be consumed by third party clients using the remote API.

In order to authenticate those services thorough Keycloak the BasicAuthSecurityFilter must be disabled, apply those modifications for the the WEB-INF/web.xml file (app deployment descriptor)  from jBPM’s WAR file:

1. Remove the filter:

   < filter >
   <filter-name>HTTP Basic Auth Filter</filter-name>
     <filter-class>org.uberfire.ext.security.server.BasicAuthSecurityFilter</filter-class>
     <init-param>
       <param-name>realmName</param-name>
       <param-value>KIE Workbench Realm</param-value>
     </init-param>
   </filter>
   
   <filter-mapping>
     <filter-name>HTTP Basic Auth Filter</filter-name>
     <url-pattern>/rest/*</url-pattern>
     <url-pattern>/maven2/*</url-pattern>
     <url-pattern>/ws/*</url-pattern>
   </filter-mapping>

2. Constraint the remote services url patterns as:

   <security-constraint>
     <web-resource-collection>
       <web-resource-name>remote-services</web-resource-name>
       <url-pattern>/rest/*</url-pattern>
       <url-pattern>/maven2/*</url-pattern>
       <url-pattern>/ws/*</url-pattern>
     </web-resource-collection>
     <auth-constraint>
       <role-name>rest-all</role-name>
     </auth-constraint>
   </security-constraint>

Important note: The user that consumes the remote services must be member of role rest-all. As on described on step 2, the admin user in this example it’s already a member of the rest-all role.

Execution server

The KIE Execution Server provides a REST API than can be consumed for any third party clients,. This this section is about how to integration the KIE Execution Server with the Keycloak SSO in order to delegate the third party clients identity management to the SSO server.

Consider the above environment running, so consider having:

• A Keycloak server running and listening on http://localhost:8180/auth
• A realm named demo with a client named kie for the jBPM Workbench
• A jBPM Workbench running at http://localhost:8080/kie-wb-6.4.0-Final

Follow these steps in order to add an execution server into this environment:

• Create the client for the execution server on Keycloak
• Install setup and the Execution server ( with the KC client adapter  )

Step 1 – Create the client for the execution server on Keycloak

As per each execution server is going to be deployed, you have to create a new client on the demo realm in Keycloak.

1. Go to the KC admin console -> Clients -> New client
2. Name: kie-execution-server
3. Root URL: http://localhost:8280/
4. Client protocol: openid-connect
5. Access type: confidential ( or public if you want so, but not recommended )
6. Valid redirect URIs: /kie-server-6.4.0.Final/*
7. Base URL: /kie-server-6.4.0.Final

In this example the admin user already created on previous steps is the one used for the client requests. So ensure that the admin user is member of the role kie-server in order to use the execution server’s remote services. If the role does not exist, create it.

Note: This example considers that the execution server will be configured to run using a port offset of 200, so the HTTP port will be available at localhost:8280

Step 2 – Install and setup the KC client adapter and the Execution server

At this point, a client named kie-execution-server is ready on the KC server to use from the execution server. Let’s install, setup and deploy the execution server:

1. Install another Wildfly server to use for the execution server and the KC client adapter as well. You can follow above instructions for the Workbench or follow the official adapters documentation.
2. Edit the standalone-full.xml file from the Wildfly server’s configuration path and configure the KC subsystem adapter as:

   <secure-deployment name="kie-server-6.4.0.Final.war">
       <realm>demo</realm>
       <realm-public-key>
           MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCrVrCuTtArbgaZzL1hvh0xtL5mc7o0NqPVnYXkLvgcwiC3BjLGw1tGEGoJaXDuSaRllobm53JBhjx33UNv+5z/UMG4kytBWxheNVKnL6GgqlNabMaFfPLPCF8kAgKnsi79NMo+n6KnSY8YeUmec/p2vjO2NjsSAVcWEQMVhJ31LwIDAQAB
       </realm-public-key>
       <auth-server-url>http://localhost:8180/auth</auth-server-url>
       <ssl-required>external</ssl-required>
       <resource>kie-execution-server</resource>
       <enable-basic-auth>true</enable-basic-auth>
       <credential name="secret">e92ec68d-6177-4239-be05-28ef2f3460ff</credential>
       <principal-attribute>preferred_username</principal-attribute>
   </secure-deployment>

Consider your concrete environment settings if different from this example:

• Secure deployment name -> use the name of the execution server war file being deployed
• Public key -> Use the demo realm public key or leave it blank, the server will provide one if so
• Resource -> This time, instead of the kie client used in the WB configuration, use the kie-execution-server client
• Enable basic auth -> Up to you. You can enable Basic auth for third party service consumers
• Credential -> Use the secret key for the kie-execution-server client. You can find it in the Credentials tab of the KC admin console.

Step 3 – Deploy and run an Execution Server

Just deploy the execution server in Wildfly using any of the available mechanisms.

Run the execution server using this command:

$EXEC_SERVER_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.socket.binding.port-offset=200 -Dorg.kie.server.id=<ID> -Dorg.kie.server.user=<USER> -Dorg.kie.server.pwd=<PWD> -Dorg.kie.server.location=<LOCATION_URL>  -Dorg.kie.server.controller=<CONTROLLER_URL> -Dorg.kie.server.controller.user=<CONTROLLER_USER> -Dorg.kie.server.controller.pwd=<CONTOLLER_PASSWORD>  

Example:

 $EXEC_SERVER_HOME/bin/standalone.sh -c standalone-full.xml -Djboss.socket.binding.port-offset=200 -Dorg.kie.server.id=kieserver1 -Dorg.kie.server.user=admin -Dorg.kie.server.pwd=password -Dorg.kie.server.location=http://localhost:8280/kie-server-6.4.0.Final/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb-6.4.0.Final/rest/controller -Dorg.kie.server.controller.user=admin -Dorg.kie.server.controller.pwd=password  

Important note: The users that will consume the execution server remote service endpoints must have the role kie-server assigned. So create and assign this role in the KC admin console for the users that will consume the execution server remote services.

Once up, you can check the server status as (considered using Basic authentication for this request, see next Consuming remote services for more information):

curl http://admin:password@localhost:8280/kie-server-6.4.0.Final/services/rest/server/

Consuming remote services

In order to use the different remote services provided by the Workbench or by an Execution Server, your client must be authenticated on the KC server and have a valid token to perform the requests.

NOTE: Remember that in order to use the remote services, the authenticated user must have assigned:

• The role rest-all for using the WB remote services
• The role kie-server for using the Execution Server remote services

Please ensure necessary roles are created and assigned to the users that will consume the remote services on the Keycloak admin console.

You have two options to consume the different remove service endpoints:

• Using basic authentication, if the application’s client supports it
• Using Bearer ( token) based authentication

Using basic authentication

If the KC client adapter configuration has the Basic authentication enabled, as proposed in this guide for both WB (step 3.2) and Execution Server, you can avoid the token grant/refresh calls and just call the services as the following examples.

Example for a WB remote repositories endpoint:

curl http://admin:password@localhost:8080/kie-wb-6.4.0.Final/rest/repositories

Example to check the status for the Execution Server :

curl http://admin:password@localhost:8280/kie-server-6.4.0.Final/services/rest/server/

Using token based authentication

First step is to create a new client on Keycloak that allows the third party remote service clients to obtain a token. It can be done as:

• Go to the KC admin console and create a new client using this configuration:
  • Client id: kie-remote
  • Client protocol: openid-connect
  • Access type: public
  • Valid redirect URIs: http://localhost/
    
• As we are going to manually obtain a token and invoke the service let’s increase the lifespan of tokens slightly. In production access tokens should have a relatively low timeout, ideally less than 5 minutes:
  • Go to the KC admin console
  • Click on your Realm Settings
  • Click on Tokens tab
  • Change the value for Access Token Lifespan to 15 minutes ( That should give us plenty of time to obtain a token and invoke the service before it expires )

Once a public client for our remote clients has been created, you can now obtain the token by performing an HTTP request to the KC server’s tokens endpoint. Here is an example for command line:

RESULT=`curl --data "grant_type=password&client_id=kie-remote&username=admin&passwordpassword=<the_client_secret>" http://localhost:8180/auth/realms/demo/protocol/openid-connect/token`


TOKEN=`echo $RESULT | sed 's/.*access_token":"//g' | sed 's/".*//g'`

At this point, if you echo the $TOKEN it will output the token string obtained from the KC server, that can be now used to authorize further calls to the remote endpoints.  For exmple, if you want to check the internal jBPM repositories:

curl -H "Authorization: bearer $TOKEN" http://localhost:8080/kie-wb-6.4.0.Final/rest/repositories

Do you want to know how to develop your skillset to become a Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you our best selling eBooks for FREE!

1. JPA Mini Book

2. JVM Troubleshooting Guide

3. JUnit Tutorial for Unit Testing

4. Java Annotations Tutorial

5. Java Interview Questions

6. Spring Interview Questions

7. Android UI Design

and many more ....

I agree to the Terms and Privacy Policy

Sign up

Thank you!

We will contact you soon.