Installing Keycloak Client adapters on WildFly

This article covers how to install Keycloak Client Adapters on WildFly so that you can let Keycloak manage the whole authentication/authorization of your applications running on WildFly.

There are mainly three options for patching WildFly with Keycloak Client adapters:

1) Download Keycloak Client Adapters and run the install scripts

The most common option is to download Keycloak client adapters and install them on the top of your WildFly distribution.

Follow these steps:

  • Download the WildFly distribution and extract it from the compressed file into a directory on your machine.
  • Download the WildFly OpenID Connect adapter distribution from https://www.keycloak.org/downloads.html.
  • Extract the contents of this file into the root directory of your WildFly distribution.

When done, run the appropriate script for your platform:

WildFly 10

$ cd bin
$ ./jboss-cli.sh --file=adapter-install-offline.cli

Wildfly 11 and newer

$ cd bin
$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli

Start the application server.

$ cd bin
$ ./standalone.sh

An example application, running on the top of a patched WildFly installation, is shown in this tutorial: Introduction to Keycloak

2) Install Keycloak layer with Galleon

The keycloak-client-oidc Galleon layer brings the OIDC keycloak subsystem (and associated JBoss modules) and configures the server security. To install it, you need to download the Galleon tool from https://github.com/wildfly/galleon/releases

Once downloaded, unzip and move to the ‘bin’ folder. From there, launch the galleon script:

$ ./galleon.sh

At first, provision a basic WildFly distribution. For example a distribution which contains the web-server layer:

install wildfly:current --layers=web-server --dir=wildfly-keycloak

On the top of that, install the keycloak-adapter-galleon-pack:

install org.keycloak:keycloak-adapter-galleon-pack:12.0.2 --layers=keycloak-client-oidc --dir=wildfly-keycloak

Please notice that, unlike the WildFly feature pack, the Keycloak feature pack is not part of a Galleon universe and so a fully qualified group:artifact:version reference to the feature pack is required.

That’s it. You can now start the application server.

$ cd wildfly-keycloak/bin
$ ./standalone.sh

3) Running your application as Bootable JAR with Keycloak layer

This approach also uses Galleon under the hoods. However, we will be able to run our application as Bootable Jar. Just as a recap, to turn your application as Bootable Jar, it is required to include the wildfly-jar-maven-plugin in your pom.xml file. Within its configuration, we will include the keycloak-adapter-galleon-pack:

    <build>
        <finalName>simple-webapp</finalName>
        <plugins>
            <plugin>
                <groupId>org.wildfly.plugins</groupId>
                <artifactId>wildfly-jar-maven-plugin</artifactId>
                <configuration>
                    <feature-packs>
                        <feature-pack>
                            <location>wildfly@maven(org.jboss.universe:community-universe)#${version.wildfly}</location>
                        </feature-pack>
                        <feature-pack>
                            <groupId>org.keycloak</groupId>
                            <artifactId>keycloak-adapter-galleon-pack</artifactId>
                            <version>12.0.2</version>
                        </feature-pack>
                    </feature-packs>
                    <layers>
                        <layer>web-server</layer>
                        <layer>keycloak-client-oidc</layer>
                    </layers>
                    <context-root>false</context-root>
                    <cli-sessions>
                        <cli-session>
                            <script-files>
                                <script>configure-oidc.cli</script>
                            </script-files>
                        </cli-session>
                    </cli-sessions>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>package</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

Also notice, to enable Keycloak secure deployments, we need to add a reference to the Keycloak Realm to our deployment. This is done by the configure-oidc.cli script that will be launched on our Bootable WildFly server:

/subsystem=keycloak/secure-deployment=simple-webapp.war:add(realm=wildfly-realm, resource=simple-webapp, public-client=true, auth-server-url=http://localhost:8180/auth/, ssl-required=EXTERNAL)

The full example, forked from WildFly Bootable Jar repository, is available here: https://github.com/fmarchioni/mastertheboss/tree/master/bootable-jar/keycloak

In this repository I have added a script for creating a Keycloak Realm so that you can test it against a Docker image of Keycloak. Let’s see how to test it. First start Keycloak Docker image to run on port 8180:

docker run --rm     --name keycloak    -e KEYCLOAK_USER=admin    -e KEYCLOAK_PASSWORD=admin     -p 8180:8180    -it quay.io/keycloak/keycloak    -b 0.0.0.0    -Djboss.http.port=8180    

Now copy the script.sh available in the root folder in the folder /opt/jboss/keycloak/bin of your Keycloak server:

docker cp script.sh keycloak:/opt/jboss/keycloak/bin

Then, set execution permissions and run the script:

docker exec -it keycloak chmod 755 /opt/jboss/keycloak/bin/script.sh
docker exec -it keycloak /opt/jboss/keycloak/bin/script.sh

The script we have just run, creates a Keycloak Realm named “wildfly-realm” with a Role named “Users”, one User (demo/demo) and a Client application to which we will redirect after login:

#!/bin/bash

cd /opt/jboss/keycloak/bin

./kcadm.sh config credentials --server http://localhost:8180/auth --realm master --user admin --password admin
./kcadm.sh create realms -s realm=wildfly-realm -s enabled=true -o
./kcadm.sh create users -r wildfly-realm -s username=demo -s enabled=true
./kcadm.sh set-password -r wildfly-realm --username demo --new-password demo
./kcadm.sh create clients -r wildfly-realm -s clientId=simple-webapp -s publicClient="true"  -s "redirectUris=[\"http://localhost:8080/simple-webapp/*\"]" -s enabled=true
./kcadm.sh create roles -r wildfly-realm -s name=Users
./kcadm.sh add-roles --uusername demo --rolename Users -r wildfly-realm

That’s it. Now start the Bootable jar:

$ mvn install; java -jar target/simple-webapp-bootable.jar

Reach the secured Servlet at http://localhost:8080/simple-webapp/secured

The Keycloak Login for the Realm will prompt:

install keycloak on WildFly

Enter demo/demo. You will be able to access the secured Servlet.

That’s it! Enjoy Keycloak with WildFly.