Keycloak

The following section describes how to run Imixs-Office-Workflow with Keycloak in a local dev environment.

To start the environment including a Keycloak server and Imixs-Office-Workflow run :

$ docker-compose -f docker/docker-compose-keycloak up

Also it is necessary for a local test to create the local hostname keycloak.imixs.local pointing to the host loopback interface 127.0.0.1

You can access the keycloak server via

http://keycloak.imixs.local:8084

For a first login use the userid admin with the password adminadmin. You can change these user settings in the docker-compose.yaml file.

Setup a Client Realm

First you need to setup a new client Realm within the keycloak server.

Create a new realm with the name imixs-office-workflow

This generates a new realm within keycloak to manage users and groups.

Setup a Client

Next you need to create a client with the name imixs:

The client will be be used by Imixs-Office-Workflow to login the user. The client-id is the client identifier for the application.

Click ‘Next’ and activate the option ‘Client authentication’. This will generate a client secret.

Click ‘Next’ and add the redirect URI http://localhost:8080/*

To test the OIDC provider capabilities you can request the configuration URL in your web browser:

http://keycloak.imixs.local:8084/realms/imixs-office-workflow/.well-known/openid-configuration

Create Roles

Next create the following Realm Roles

  • org.imixs.ACCESSLEVEL.READERACCESS
  • org.imixs.ACCESSLEVEL.AUTHORACCESS
  • org.imixs.ACCESSLEVEL.AUTHORACCESS
  • org.imixs.ACCESSLEVEL.MANAGERACCESS

Create Users

Now you can create new User Accounts

and assign these users to one of the roles:

Also don’t forget to set the password for the new user via the tab ‘Credentials’.

Add a Role Group Mapper

The OpenID Client expects the roles in the scope ‘groups’. This scope is not activated by default in Keycloak. To do this you just need to create a group mapper

Choose the menue ‘Client Scopes’ and select the scope named ‘roles’ from the list:

Next click on the tab ‘Mappers’ and add a new Mapper from the predefined mappers and choose ‘groups’

Thats it, now the roles are provided in the scope ‘groups’.

Use OIDC with Keycloak and Imixs-Office-Workflow

OpenID Connect is an identity layer on top of the OAuth 2.0 protocol. OpenID Connect makes it possible for a client to verify a user’s identity based on authentication that’s performed by an OpenID provider.

WildFly 25, which is used by the latest version of Imixs-Office-Workflow, added the ability to secure applications using OpenID Connect, without needing to make use of the Keycloak client adapter. To integrate Keycloak, WildFly 25 introduced a new elytron-oidc-client subsystem that scans deployments to check if the OpenID Connect (OIDC) authentication mechanism is needed. If the subsystem detects that the OIDC mechanism is required for a deployment, the subsystem will activate this authentication mechanism automatically. This feature makes it easy to connect Imixs-Office-Workflow with Keycloak.

Aktivating the OIDC Module

To activate OIDC in Imixs-Office-Workflow you need to build the application with the maven profile ‘oidc’

$ mvn clean install -Pauth-oidc

This will build a version including the library imixs-office-workflow-oidc-*.jar. This optional module provides the OIDC Security bean with the corresponding ‘@OpenIdAuthenticationMechanismDefinition’.

Note: Make sure that the application deployment descriptor jboss-web.xml did not set the <security-domain>! This will overwrite the OIDC setting and will break the authentication flow.

The configuration of the OpenID Provider Endpoint and the client secret can be done by setting the following environment variables in your Docker image:

      OIDCCONFIG_ISSUERURI: "http://keycloak.imixs.local:8084/realms/imixs-office-workflow"
      OIDCCONFIG_CLIENTID: "imixs"
      OIDCCONFIG_CLIENTSECRET: "<YOUR-CLIENT-SCRET>"   

The IssuerURI is the endpoint of your Keycloak sever. The client secret can be copied form the ‘credentials’ tab in your client configuration.

Finally redeploy your application.

Thats it.

Wildfly - Disable JASPIC

One tricky point is that by default the elytron subsystem enforces the logged user to be in the default other domain (by default application users are placed in the application-users.properties file in wildfly). The integrated-jaspi option can be set to false to avoid that.

Note: The default Docker Image form Imixs-Office-Workflow already have deactivated this option, so no changes are necessary in most cases.

If you want to set this option manually, this can be done by either editing the standalone.xml file:

 ....
 .........
        <subsystem xmlns="urn:jboss:domain:undertow:13.0" default-server="default-server" default-virtual-host="default-host" default-servlet-container="default" default-security-domain="other" statistics-enabled="${wildfly.undertow.statistics-enabled:${wildfly.statistics-enabled:false}}">
           .......
           .............
            <application-security-domains>
                <!-- Disable integrated jaspic -->
                <application-security-domain name="other" security-domain="ApplicationDomain" integrated-jaspi="false"/>        
            </application-security-domains>
        </subsystem>
    .....

or with the cli-commandline tool:

$ ./jboss-cli.sh --connect --controller=remote+http://localhost:9990
$ /subsystem=undertow/application-security-domain=other:write-attribute(name=integrated-jaspi, value=false)
$ relaod

Trouble Shooting

Disable SSL

Since version 24.x Keycloak increased the security to demand configured HTTPS / SSL, even when starting locally for testing. If you test keycloak locally in a docker container, you may possible run into problem when trying to login. You will see a message during login like this in your browser window:

This is caused by the increased security. To disable this new security feature open a bash inside the local container and run the following commands:

/opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE --server http://localhost:8080 --realm master --user admin --password adminadmin
/opt/keycloak/bin/kcadm.sh update realms/imixs-office-workflow -s sslRequired=NONE --server http://localhost:8080 --realm master --user admin --password adminadmin

This will disable HTTPS for the master realm and the realm ‘imixs-office-workflow’. The update is done inside the sql database. Restart your docker container after this change.

Additional Information

Find more information about Keycloak and Wildfly here: