Keycloak

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

/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

Additional Information

Find more information about Keycloak and Wildfly here:

• https://wildfly-security.github.io/wildfly-elytron/blog/securing-wildfly-apps-openid-connect/
• https://auth0.com/blog/jakarta-ee-oidc/
• https://blogs.nologin.es/rickyepoderi/