Installing Keycloak OIDC adaptor using the Galleon CLI

By Darran Lofthouse | July 01, 2021
#galleon #oidc #keycloak

Traditionally to install WildFly you would download a complete archive of the application server distribution, unzip it locally and run it directly from where it was unzipped. Subsequently to install the Keycloak adaptor for WildFly a second archive would be downloaded and unzipped on top of the WildFly installation and a CLI script executed to complete the installation.

Although this approach has certainly stood the test of time it does have a couple of limitations. Firstly these steps need to be repeated each time a new version of the application server or Keycloak adaptors are released. Secondly the installed application server contains all of the various supported subsystems even if only a small subset are required. The Galleon project provides an alternative installation approach addressing both of these limitations.

This blog post illustrates how a slimed WildFly installation can be performed with the addition of the Keycloak client adaptors using the Galleon command line tools.

Galleon

This blog post is not intended to be a replacment for the already published Galleon documentation, more information can be found in the Galleon Provisioning Guide.

This blog post assumes you already have Java 8 or Java 11 installed locally, the first step is to download and unzip the latest release from the Galleon project to make the CLI tools available. The latest version can be downloaded from the Galleon Releases page.

Installing the "web-server" layer.

Using the Galleon CLI is a two step process to install a slimmed WildFly server followed by the Keycloak adaptors.

The Galleon CLI can be used both in an interactive and non-interactive mode, both of which are covered in more detail in the Galleon documentation, the examples in this blog post will just be using non-interactive mode.

$GALLEON_HOME/bin/galleon.sh install wildfly:current --dir=wildfly --layers=web-server
Feature pack installed.d.
======= ============ ==============
Product Build        Update Channel
======= ============ ==============
wildfly 24.0.0.Final current

This command will have provisioned a slimed WildFly server which can be used to deploy simple servlet based web applications, this installation does not have the management interfaces defined so the server can not be configured using the jboss-cli. However the installation does have the deployment scanner active so deployments can be added by placing them into the $WILDFLY_HOME/standalone/deployments directory.

Installing the "keycloak-client-oidc" layer.

The next step is to add the keycloak-client-oidc layer on top of the WildFly installation, for the Keycloak specific layers we need to use the fully qualified Maven group, artifact and version to reference the Keycloak feature pack.

$GALLEON_HOME/bin/galleon.sh install org.keycloak:keycloak-adapter-galleon-pack:14.0.0 --dir=wildfly --layers=keycloak-client-oidc
Feature-packs resolved.
Feature-packs resolved.
Packages installed.
JBoss modules installed.
Configurations generated.
Feature pack installed.

In addition to adding the required modules to the WildFly installation this second command will have also added the WildFly Elytron subsystem to secure deployments by default, the Keycloak adapter subsystem and configuration to make the Keycloak OpenID Connect authentication mechanism available for deployments.

Starting WildFly

At this stage the installation and configuration of WildFly is now complete and the application server can be started.

cd $WILDFLY_HOME
bin/standalone.sh -Djboss.socket.binding.port-offset=10

If you are familiar with the usual output when starting the application server you should now see the boot process leads to less output, this is because only the subsystems required for securing a servlet based web application with Keycloak are now installed so the subsystems which are not required are not even present.

Deploying a web application

Finally a web application can now be deployed to WildFly.

There are two different approaches that can be taken to configure a web application to use the Keycloak OpenID Connect authentication mechanism as described in JBoss SSO.

Note: The preceding section in the Keycloak documentation is skipped as Galleon has replaced the installation steps described there.

As the installed server does not have the management interfaces enabled the easiest approach to configuration is to embed the configuration within the deployment, for the Keycloak authentication mechanism this can be achieved by adding a keycloak.json descriptor to the WEB-INF directory of a web application:

{
    "realm" : "WildFly",
    "resource" : "simple-webapp",
    "public-client" : "true",
    "auth-server-url" : "http://localhost:8080/auth/",
    "ssl-required" : "EXTERNAL"
}

The authentication mechanism is activate by setting the auth-method in the web.xml to KEYCLOAK:

    <login-config>
        <auth-method>KEYCLOAK</auth-method>
        <realm-name>Simple Realm</realm-name>
    </login-config>

After a web application with these changes is built it can be copied to the standalone\deployments directory of the WildFly installation where it will be automatically deployed, the application will be secured by Keycloak using the embedded configuration.

Additional configuration options are also described in the Keycloak documentation in the Java Adapter Config section, also instead of using the keycloak.json descriptor the configuration could have been contained in the urn:jboss:domain:keycloak:1.1 subsystem as described in Securing WARs via Adapter Subsystem but overall the purpose of this blog post was to illustrate how to get started installing the Keycloak client adapters and WildFly using Galleon.