How to Integrate Imixs-Workflow with Single-Sign On

Blog: Imixs Workflow Blog

Imixs-Workflow can now be easily combined with the Open Source Identity and Access Management solution Keycloak. Keycloak is an Open Source Identity and Access Management Server which can be used together with Wildfly to authenticate users with a modern authentication mechanism based on OpenID Connect SAML and OAuth. This is a short tutorial how to setup the Single-Sign On Server Keycloak and configure the Imixs-Workflow to authenticate users.

Installation

Keycloak can be downloaded form here. It is recommended to run Keycloak as a standalone server. After installation the server can be started :

/[KEYCLOAK_INSTALL]/bin/standalone.sh

To avoid port conflicts with another Wildfly instance running Imixs-Worklfow the port-offset parameter can be changed in the standalone.xml file of the keycloak installation:

 <socket-binding-group name="standard-sockets" default-interface="public" port-offset="${jboss.socket.binding.port-offset:1}">

Wildfly adapters

To connect the Wildfly server with the Keycloak server the additional keycloak adapters for wildfly need to be installed. The adapters can be downloaded from here and installed into the wildfly installation root. With the following cli command the adapter can be activated:

./jboss-cli.sh --connect --file="adapter-install.cli"

This command will add the keycloak-adapter-subsystem into the wildfly standalone.xml file.

<server xmlns="urn:jboss:domain:4.0>
<extensions>
    ...
    <extension module="org.keycloak.keycloak-adapter-subsystem"/>
</extensions>
 ...
 <security-domain name="keycloak">
 <authentication>
 <login-module code="org.keycloak.adapters.jboss.KeycloakLoginModule" flag="required"/>
 </authentication>
 </security-domain>
...
 <profile>
    <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
    ...

Define the Imixs-Workflow Client Application

After Keycloak is up and running, a new client configuration for the Imixs-Workflow server can be added by using the keycloak web interface:

Configuration of Imixs-Worklfow

After the client configuration is added, the Keycloak realm can be added into the web.xml file of Imixs-Workflow:

...
<login-config>
   <auth-method>KEYCLOAK</auth-method>
   <realm-name>Master</realm-name>
</login-config>

In addition the Workflow Application need to know the keycloak server information which can be added either into the standalone.xml or into a json file “keycloak.json” added into the /WEB-INF/ folder. The information can be generated by the keycloak admin client from the corresponding client configuration:

Configure Users and Roles

Finally new users can be granted by the Keycloak server to access the Imixs-Workflow application. The following role need to be defined in the client configuration: