Monday, April 18, 2016

Drools 6.4.0.Final is available

The latests and greatest Drools 6.4.0.Final release is now available for download.

This is an incremental release on our previous build that brings several improvements in the core engine and the web workbench.

You can find more details, downloads and documentation here:




Read below some of the highlights of the release.

You can also check the new releases for:




Happy drooling.

Drools Workbench

New look and feel

The general look and feel in the entire workbench has been updated to adopt PatternFly. The update brings a cleaner, lightweight and more consistent user experience throughout every screen. Allowing users focus on the data and the tasks by removing all unnecessary visual elements. Interactions and behaviour remain mostly unchanged, limiting the scope of this change to visual updates.


Various UI improvements

In addition to the PatternFly update described above which targeted the general look and feel, many individual components in the workbench have been improved to create a better user experience. This involved making sure the default size of modal popup windows is appropriate to fit the corresponding content, adjusting the size of text fields as well as aligning labels, and improving the resize behaviour of various components when used on smaller screens.


New Locales

Locales ru (Russian) and zh_TW (Chineses Traditional) have now been added.

New Decision Server Management UI

The KIE Execution Server Management UI has been completely redesigned to adjust to major improvements introduced recently. Besides the fact that new UI has been built from scratch and following best practices provided by PatternFly, the new interface expands previous features giving users more control of their servers.


Core Engine


Better Java 8 compatibility

It is now possible to use Java 8 syntax (lambdas and method references) in the Right Hand Side (then) part of a rule.

More robust incremental compilation

The incremental compilation (dynamic rule-base update) had some relevant flaws when one or more rules with a subnetwork (rules with complex existential patterns) were involved, especially when the same subnetwork was shared among different rules. This issue required a partial rewriting of the existing incremental compilation algorithm, followed by a complete audit that has also been validated by brand new test suite made by more than 20,000 test cases only in this area.

Improved multi-threading behaviour

Engine's code dealing with multi-threading has been partially rewritten in order to remove a large number of synchronisation points and improve stability and predictability.


OOPath improvements

OOPath has been introduced with Drools 6.3.0. In Drools 6.4.0 it has been enhanced to support a number of new features.



Share/Bookmark

Oficial Wildfly Swarm #Drools Fraction

Oficial what? Long title for a quite small but useful contribution. Wildfly Swarm allows us to create rather small and self contained application including just what we need from the Wildfly Application Server. On this post we will be looking at the Drools Fraction provided to work with Wildfly Swarm. The main idea behind this fraction is to provide a quick way to bundle the Drools Server among with your own services inside a jar file that you can run anywhere.

Microservices World

Nowadays, while micro services are a trending topic we need to make sure that we can bundle our services as decoupled from other software as possible. For such a task, we can use Wildfly Swarm that allows us to create our services using a set of fractions instead of a whole JEE container. It also saves us a lot of time by allowing us to run our application without the need of downloading or installing a JEE container. With Swarm we will be able to just run java -jar <our services.jar> and we are ready to go.
In the particular case of Drools, the project provides a Web Application called Kie-Server (Drools Server) which offers a set of REST/SOAP/JMS endpoints to use as a service. You can load your domain specific rules inside this server and create new containers to use your different set of rules. But again, if we want to use it, we will need to worry about how to install it in Tomcat, Wildfly, Jetty, WebSphere, WebLogic, or any other Servlet Container. Each of these containers represent a different challenge while it comes to configurations, so instead of that we can start using the Wildfly Swarm Drools Fraction, which basically enables the Drools Server inside your Wildfly Swarm application. In a way you are bundling the Drools Server with your own custom services. By doing this, you can start the Drools Server by doing java -jar <your.jar> and you ready to go.
Imagine the other situation of dealing with several instances of Servlet Containers and deploying the WAR file to each of those containers. It gets worst if those containers are not all the same "brand" and version.
So let's take a quick look at an example of how you can get started using the Wildfly Swarm Drools Fraction.

Example

I recommend you to take a look at the Wildfly Swarm Documentation first, to get you started on using Wildfly Swarm. If you know the basics, then you can include the Drools Fraction.
I've created an example using this fraction here: https://github.com/Salaboy/drools-workshop/tree/master/drools-server-swarm
The main goal of this example is to show how simple is to get you started with the Drools Fraction, and for that reason I'm not including any other service in this project. You are not restricted by that, and you can expose your own endpoints.
Notice in the pom.xml file two things:
  1. The Drools Server Fraction: https://github.com/Salaboy/drools-workshop/blob/master/drools-server-swarm/pom.xml#L18 By adding this dependency, the fraction is going to be activated while Wildfly Swarm bootstrap.
  2. The wildfly-swarm plugin: https://github.com/Salaboy/drools-workshop/blob/master/drools-server-swarm/pom.xml#L25. Notice in the plugin configuration that we are pointing to the App class which basically just start the container. (This can be avoided, but I wanted to show that if you want to start your own services or do your own deployments you can do that inside that class)
If you compile and package this project by doing mvn clean install, you will find in the target/ directory a file called:
drools-server-swarm-1.0-SNAPSHOT-swarm.jar which you can start by doing
[code]

java -jar drools-server-swarm-1.0-SNAPSHOT-swarm.jar

[/code]
For this example, we will include one more flag when we start our project to make sure that our Drools Server can resolve the artefacts that I'm going to use later on, so it will be like this:
[code]

java -Dkie.maven.settings.custom=../src/main/resources/settings.xml -jar drools-server-swarm-1.0-SNAPSHOT-swarm.jar

[/code]
By adding the "kie.maven.setting.custom" flag here we are letting the Drools Server know that we had configured an external maven repository to be used to resolve our artefacts. You can find the custom settings.xml file here.
Once you start this project and everything boots up (less than 2 seconds to start wildfly-swarm core + less than 14 to boot up the drools server) you are ready to start creating your KIE Containers with your domain specific rules.
You can find the output of running this app here. Notice the binding address for the http port:
WFLYUT0006: Undertow HTTP listener default listening on [0:0:0:0:0:0:0:0]:8083
Now you can start sending requests to http://localhost:8083/drools to interact with the server.
I've included in this project also a Chrome's Postman project for you to test some very simple request like:
  • Getting All the registered Containers -> GET http://localhost:8083/drools/server/containers
  • Creating a new container - > PUT http://localhost:8083/drools/server/containers/sample
  • Sending some commands like Insert Fact + Fire All Rules -> POST http://localhost:8083/drools/server/containers/instances/sample
You can import this file to Postman and fire the requests against your newly created Drools Server. Besides knowing to which URLs to PUT,POST or GET data, you also need to know about the required headers and Authentication details:
Headers
Headers
Authentication -> Basic
User: kieserver
Password: kieserver1!
Finally, you can find the source code of the Fraction here: https://github.com/wildfly-swarm/wildfly-swarm-drools
There are tons of things that can be improved, helpers to be provided, bugs to be fixed, so if you are up to the task, get in touch and let's the Drools fraction better for everyone.

Summing up

While I'm still writing the documentation for this fraction, you can start using it right away. Remember that the main goal of these Wildfly Swarm extensions is to make your life easier and save you some time when  you need to get something like the Drools Server in a small bundle and isolated package that doesn't require a server to be installed and configured.
If you have any questions about the Drools Fraction don't hesitate to write a comment here.




Share/Bookmark

Wednesday, April 06, 2016

User and group management in jBPM and Drools Workbenches

Introduction

This article talks about a new feature that allows the administration of the application's users and groups using an intuitive and friendly user interface that comes integrated in both jBPM and Drools Workbenches.

User and group management
Before the installation, setup and usage of this feature, this article talks about some previous concepts that need to be completely understood for the further usage.

So this article is split in those sections:
  • Security management providers and capabilities
  • Installation and setup
  • Usage
Notes: 
  • This feature is included from version 6.4.0.Final.
  • Sources available here.


Security management providers

A security environment is usually provided by the use of a realm. Realms are used to restrict the access for the different application's resources. So realms contains information about the users, groups, roles, permissions and and any other related information.

In most of the typical scenarios the application's security is delegated to the container's security mechanism, which consumes a given realm at same time. It's important to consider that there exist several realm implementations, for example Wildfly provides a realm based on the application-users.properties/application-roles.properties files, Tomcat provides a realm based on the tomcat-users.xml file, etc. So keep in mind that there is no single security realm to rely on, it can be different in each installation.

The jBPM and Drools workbenches are not an exception, they're build on top Uberfire framework (aka UF), which delegates the authorization and authentication to the underlying container's security environment as well, so the consumed realm is given by the concrete deployment configuration.

 
Security management providers

Due to the potential different security environments that have to be supported, the users and groups management provides a well defined management services API with some default built-in security management providers. A security management provider is the formal name given to a concrete user and group management service implementation for a given realm.

At this moment, by default there are three security management providers available:
Keep updated on new security management providers on further releases. You can easily build and register your own security management provider if non of the defaults fits in your environment.

 
Security management providers's capabilities

Each security realm can provide support different operations. For example consider the use of a Wildfly's realm based on properties files,  The contents for the applications-users.properties is like:

admin=207b6e0cc556d7084b5e2db7d822555c
salaboy=d4af256e7007fea2e581d539e05edd1b
maciej=3c8609f5e0c908a8c361ca633ed23844
kris=0bfd0f47d4817f2557c91cbab38bb92d
katy=fd37b5d0b82ce027bfad677a54fbccee
john=afda4373c6021f3f5841cd6c0a027244
jack=984ba30e11dda7b9ed86ba7b73d01481
director=6b7f87a92b62bedd0a5a94c98bd83e21
user=c5568adea472163dfc00c19c6348a665
guest=b5d048a237bfd2874b6928e1f37ee15e
kiewb=78541b7b451d8012223f29ba5141bcc2
kieserver=16c6511893651c9b4b57e0c027a96075

As you can see, it's based on key-value pairs where the key is the username, and the value is the hashed value for the user's password. So a user is just defined by the key, by its username, it  does not have a name nor address, etc.

On the other hand, consider the use of a realm provided by a Keycloak server. The information for a user is composed by more user meta-data, such as surname, address, etc, as in the following image:

Admin user edit using the Keycloak sec. management provider

So the different services and client side components from the users and group management API are based on capabilitiesCapabilities are used to expose or restrict the available functionality provided by the different services and client side components. Examples of capabilities are:
  • Create user
  • Update user
  • Delete user
  • Update user attributes
  • Create group
  • Assign groups
  • Assign roles 
  • etc

Each security management provider must specify a set of capabilities supported. From the previous examples you can note that the Wildfly security management provider does not support the capability for the management of the attributes for a user - the user is only composed by the user name. On the other hand the Keycloak provider does support this capability.

The different views and user interface components rely on the capabilities supported by each provider, so if a capability is not supported by the provider in use, the UI does not provide the views for the management of that capability. As an example, consider that a concrete provider does not support deleting users - the delete user button on the user interface will be not available.

Please take a look at the concrete service provider documentation to check all the supported capabilities for each one, the default ones can be found here.

If the security environment is not supported by any of the default providers, you can build your own. Please keep updated on further articles about how to create a custom security management provider.

 
Installation and setup

Before considering the installation and setup steps please note the following Drools and jBPM distributions come with built-in, pre-installed security management providers by default:
  • Wildfly / EAP distribution - Both distributions use the Wildfly security management provider configured for the use of the default realm files application-users.properties and application-roles.properties
      
  • Tomcat distribution - It uses the Tomcat security management provider configured for the use of the default realm file tomcat-users.xml
If your realm settings are different from the defaults, please read each provider's documentation in order to apply the concrete settings.

On the other hand, if you're building your own security management provider or need to include it on an existing application, consider the following installation options:
  • Enable the security management feature on an existing WAR distribution
     
  • Setup and installation in an existing or new project (from sources)
NOTE: If no security management provider is installed in the application, there will be no available user interface for managing the security realm. Once a security management provider is installed and setup, the user and group management user interfaces are automatically enabled and accessible from the main menu.

Enable the security management feature on an existing WAR distribution
Given an existing WAR distribution of either Drools and jBPM workbenches, follow these steps in order to install and enable the user management feature:

  1. Ensure the following libraries are present on WEB-INF/lib:
    • WEB-INF/lib/uberfire-security-management-api-6.4.0.Final..jar
    •  WEB-INF/lib/uberfire-security-management-backend-6.4.0.Final..jar
        
  2. Add the concrete library for the security management provider to use in WEB-INF/lib:
    • Example: WEB-INF/lib/uberfire-security-management-wildfly-6.4.0.Final..jar
    • If the concrete provider you're using requires more libraries, add those as well. Please read each provider's documentation for more information.
        
  3. Replace the whole content for file WEB-INF/classes/security-management.properties, or if not present, create it. The settings present on this file depend on the concrete implementation you're using. Please read each provider's documentation for more information.
      
  4. If you're deploying on Wildfly or EAP, please check if the WEB-INF/jboss-deployment-structure.xml requires any update. Please read each provider's documentation for more information.

Setup and installation in an existing or new project (from sources)

If you're building an Uberfire based web application and you want to include the user and group management feature, please read this instructions.

Disabling the security management feature

he security management feature can be disabled, and thus no services or user interface will be available, by any of

  • Uninstalling the security management provider from the application

    When no concrete security management provider installed on the application, the user and group management feature will be disabled and no services or user interface will be presented to the user.
       
  • Removing or commenting the security management configuration file

    Removing or commenting all the lines in the configuration file located at WEB-INF/classes/security-management.properties will disable the user and group management feature and no services or user interface will be presented to the user.


Usage

The user and group management feature is presented using two different perspectives that are available from the main Home menu (considering that the feature is enabled) as:
User and group management menu entries
Read the following sections for using both user and group management perspectives.

User management

The user management interface is available from the User management menu entry in the Home menu.

The interface is presented using two main panels:  the users explorer on the west panel and the user editor on the center one:

User management perspective

The users explorer, on west panel, lists by default all the users present on the application's security realm:

Users explorer panel
In addition to listing all users, the users explorer allows:

  • Searching users


    When specifying the search pattern in the search box the users list will be reduced and will display only the users that matches the search pattern.

    Search patterns depend on the concrete security management provider being used by the application's. Please read each provider's documentation for more information.
  • Creating new users:



    By clicking on the Create new user button, a new screen will be presented on the center panel to perform a new user creation.
The user editor, on the center panel, is used to create, view, update or delete users. Once creating a new user o clicking an existing user on the users explorer, the user editor screen is opened. 

To view an existing user, click on an existing user in the Users Explorer to open the User Editor screen. For example, viewing the admin user when using the Wildfly security management provider results in this screen:

Viewing the admin user
Same admin user view operation but when using the Keycloak security management provider, instead of the Wildfly's one, results in this screen:

Using the Keycloak sec. management provider
As you can see, the user editor when using the Keycloak sec. management provider includes the user attributes management section, but it's not present when using the Wildfly's one. So remember that the information and actions available on the user interface depends on each provider's capabilities (as explained in previous sections),

Viewing a user in the user editor provides the following information (if provider supports it):
  • The user name
  • The user's attributes
  • The assigned groups
  • The assigned roles
In order to update or delete an existing user, click on the Edit button present near to the username in the user editor screen:

Editing admin user
Once the user editor presented in edit mode, different operations can be done (if the security management provider in use supports it):
  • Update the user's attributes



    Existing user attributes can be updated, such as the user name, the surname, etc. New attributes can be created as well, if the security management provider supports it.
  • Update assigned groups

    A group selection popup is presented when clicking on Add to groups button:



    This popup screen allows the user to search and select or deselect the groups assigned for the user currently being edited.
  • Update assigned roles

    A role selection popup is presented when clicking on Add to roles button:



    This popup screen allows the user to search and select or deselect the roles assigned for the user currently being edited.
  • Change user's password

    A change password popup screen is presented when clicking on the Change password button:

  • Delete user

    The currently being edited user can be deleted from the realm by clicking on the Delete button. 
Group management

The group management interface is available from the Group management menu entry in the Home menu.

The interface is presented using two main panels:  the groups explorer on the west panel and the group editor on the center one:

Group management perspective
The groups explorer, on west panel, lists by default all the groups present on the application's security realm:

Groups explorer
In addition to listing all groups, the groups explorer allows:

  • Searching for groups

    When specifying the search pattern in the search box the users list will be reduced and will display only the users that matches the search pattern.
    Groups explorer filtered using search
    Search patterns depend on the concrete security management provider being used by the application's. Please read each provider's documentation for more information.
  • Create new groups



    By clicking on the Create new group button, a new screen will be presented on the center panel to perform a new group creation. Once the new group has been created, it allows to assign users to it:
    Assign users to the recently created group
The group editor, on the center panel, is used to create, view or delete groups. Once creating a new group o clicking an existing group on the groups explorer, the group editor screen is opened. 

To view an existing group, click on an existing user in the Groups Explorer to open the Group Editor screen. For example, viewing the sales group results in this screen:


Viewing the sales group
To delete an existing group just click on the Delete button.



Share/Bookmark

Monday, April 04, 2016

Mastering #Drools 6 book is out!

Hi everyone, just a quick post to share the good news! The book is out and ready to ship! You can buy it from Packt or from Amazon directly. I'm happy to announce also that we are going to be presenting the book next week in Denmark, with the local JBug: http://www.meetup.com/jbug-dk/events/229407454/ if you are around or know someone that might be interested in attending please let them know!

Mastering Drools 6
The book covers a wide range of topics from the basic ones including how to set up your environment and how to write simple rules, to more advanced topics such as Complex Event Processing and the core of the Rule Engine, the PHREAK algorithm.


Share/Bookmark

Wednesday, March 23, 2016

Packt is doing it again: 50% off on all eBooks and Videos

Packt Publishing has another great promotion going: 50% off on all Packt eBooks and Videos until April 30th.

It is a great opportunity to grab all those Drools books as well as any others you might be interested in.

Click on the image bellow to be redirected to their online store:





Share/Bookmark

Monday, March 21, 2016

High Availability Drools Stateless Service in Openshift Origin

openshift-origin-logoHi everyone! On this blog post I wanted to cover a simple example showing how easy it is to scale our Drools Stateless services by using Openshift 3 (Docker and Kubernetes). I will be showing how we can scale our service by provisioning new instances on demand and how these instances are load balanced by Kubernetes using a round robin strategy.

Our Drools Stateless Service

First of all we need a stateless Kie Session to play around with. In these simple example I've created a food recommendation service to demonstrate what kind of scenarios you can build up using this approach. All the source code can be found inside the Drools Workshop repository hosted on github: https://github.com/Salaboy/drools-workshop/tree/master/drools-openshift-example
In this project you will find 4 modules:
  • drools-food-model: our business model including the domain classes, such as Ingredient, Sandwich, Salad, etc
  • drools-food-kjar: our business knowledge, here we have our set of rules to describe how the food recommendations will be done.
  • drools-food-services: using wildfly swarm I'm exposing a domain specific service encapsulating the rule engine. Here a set of rest services is exposed so our clients can interact.
  • drools-controller: by using the Kubernetes Java API we can programatically provision new instances of our Food Recommendation Service on demand to the Openshift environment.
Our unit of work will be the Drools-Food-Services project which expose the REST endpoints to interact with our stateless sessions.
Also notice that there is another Service that gives us very basic information about where our Service is running: https://github.com/Salaboy/drools-workshop/blob/master/drools-openshift-example/drools-food-services/src/main/java/org/drools/workshop/food/endpoint/api/NodeStatsService.java
We will call this service to know exactly which instance of the service is answering our clients later on.
The rules for this example are simple and not doing much, if you are looking to learn Drools, I recommend you to create more meaning full rules and share it with me so we can improve the example ;) You can take a look at the rules here:
As you might expect: Sandwiches for boys and Salads for girls :)
One last important thing about our service that is important for you to see is how the rules are being picked up by the Service Endpoint. I'm using the Drools CDI extension to @Inject a KieContainer which is resolved using the KIE-CI module, explained in some of my previous posts.
We will bundle this project into a Docker Image that can be started as many times as we want/need. If you have a Docker client installed in your local environment you can start this food recommendation service by looking at the salaboy/drools-food-services image which is hosted in hub.docker.com/salaboy
By starting the Docker image without even knowing what is running inside we immediately notice the following advantages:
  • We don't need to install Java or any other tool besides Docker
  • We don't need to configure anything to run our Rest Service
  • We don't even need to build anything locally due the fact that the image is hosted in hub.docker.com
  • We can run on top of any operating system
At the same time we get notice the following disadvantages:
  • We need to know in which IP and Port our service is exposed by Docker
  • If we run more than one image we need to keep track of all the IPs and Ports and notify to all our clients about those
  • There is no built in way of load balance between different instances of the same docker image instance
For solving these disadvantages Openshift, and more specifically, Kubernetes to our rescue!

Provisioning our Service inside Openshift

As I mention before, if we just start creating new Docker Image instances of our service we soon find out that our clients will need to know about how many instances do we have running and how to contact each of them. This is obviously no good, and for that reason we need an intermediate layer to deal with this problem. Kubernetes provides us with this layer of abstraction and provisioning, which allows us to create multiple instances of our PODs (abstraction on top of the docker image) and configure to it Replication Controllers and Services.
The concept of Replication Controller provides a way to define how many instances should be running our our service at a given time. Replication controllers are in charge of guarantee that if we need at least 3 instances running, those instances are running all the time. If one of these instances died, the replication controller will automatically spawn one for us.
Services in Kubernetes solve the problem of knowing all and every Docker instance details.  Services allows us to provide a Facade for our clients to use to interact with our instances of our Pods. The Service layer also allows us to define a strategy (called session affinity) to define how to load balance our Pod instances behind the service. There are to built in strategies: ClientIP and Round Robin.
So we need to things now, we need an installation of Openshift Origin (v3) and our project Drools Controller which will interact with the Kubernetes REST endpoints to provision our Pods, Replicator Controllers and Services.
For the Openshift installation, I recommend you to follow the steps described here: https://github.com/openshift/origin/blob/master/CONTRIBUTING.adoc
I'm running here in my laptop the Vagrant option (second option) described in the previous link.
Finally, an ultra simple example can be found of how to use the Kubernetes API to provision in this case our drools-food-services into Openshift.
Notice that we are defining everything at runtime, which is really cool, because we can start from scratch or modify existing Services, Replication Controllers and Pods.
You can take a look at the drools-controller project. which shows how we can create a Replication Controller which points to our Docker image and defines 1 replica (one replica by default is created).
If you log in into the Openshift Console you will be able to see the newly created service with the Replication Controller and just one replica of our Pod. By using the UI (or the APIs, changing the Main class) we can provision more replicas, as many as we need. The Kubernetes Service will make sure to load balance between the different pod instances.
Voila! Our Services Replicas are up and running!
Voila! Our Services Replicas are up and running!
Now if you access the NodeStat service by doing a GET to the mapped Kubernetes Service Port you will get the Pod that is answering you that request. If you execute the request multiple times you should be able to see that the Round Robin strategy is kicking in.
wget http://localhost:9999/api/node {"node":"drools-controller-8tmby","version":"version 1"}
wget http://localhost:9999/api/node {"node":"drools-controller-k9gym","version":"version 1"}
wget http://localhost:9999/api/node {"node":"drools-controller-pzqlu","version":"version 1"}
wget http://localhost:9999/api/node {"node":"drools-controller-8tmby","version":"version 1"}
In the same way you can interact with the Statless Sessions in each of these 3 Pods. In such case, you don't really need to know which Pod is answering your request, you just need to get the job done by any of them.

Summing up

By leveraging the Openshift origin infrastructure we manage to simplify our architecture by not reinventing mechanisms that already exists in tools such as Kubernetes & Docker. On following posts I will be writing about some other nice advantages of using this infrastructure such as roll ups to upgrade the version of our services, adding security and Api Management to the mix.
If you have questions about this approach please share your thoughts.

Share/Bookmark

Saturday, March 19, 2016

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:

Example scenario

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:

Settings for the kie client

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
Role mappings for 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 namerealm-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:


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>
  <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.




Share/Bookmark