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.
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.
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
Edit the configuration file $JBPM_HOME/standalone/configuration/standalone-full.xml
and locate the subsystem configuration section. Add the following content:
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
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:
|jBPM & SSO - Login page |
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>
<param-value>KIE Workbench Realm</param-value>
<filter-name>HTTP Basic Auth Filter</filter-name>
2.- Constraint the remote services url patterns as:
: 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
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.
- Go to the KC admin console -> Clients -> New client
- Name: kie-execution-server
- Root URL: http://localhost:8280/
- Client protocol: openid-connect
- Access type: confidential ( or public if you want so, but not recommended )
- Valid redirect URIs: /kie-server-6.4.0.Final/*
- 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:
Consider your concrete environment settings if different from this example:
Step 3 - Deploy and run an Execution Server
- 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.
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>
$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):
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
- Using basic authentication, if the application's client supports it
- Using Bearer ( token) based 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:
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