Using Keycloak for Wildfly Applications

Keycloak is a 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 and OAuth.

This is a short tutorial how to setup a Keycloak server and configure a wildfly web application to use keycloak to authenticate users.

Installation

First you can download the Keycloak server form here. It is recommended to run Keycloak as a standalone server. After you have unzipped the files you can start the server with:

/[KEYCLOAK_INSTALL]/bin/standalone.sh

To avoid port conflicts with another Wildfly instance running your application you can change the port-offset parameter in the standalone.xml file of your keycloak installation from ‘0’ to ‘1’:

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

Now the keycloak server will be accessible via http://localhost:8081

Install the Wildfly adapters

To connect your wildfly server with the keycloak server you first need to install the keycloak adapters for wildfly. The Adapters can be downloaded from here. Unzip the files into your wildfly installation root.

Next you need to activate the adapter in wildfly using the wildfly cli tool:

Change into /[WILDFLY_INSTALL]/bin/ directory and run the following command:

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

This will add the keycloak-adapter-subsystem into your 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 a Client

Now you can define a client configuration for your wildfly web application. Open the keycloak web interface and add a new client:

Make sure that your ‘valid Redirect URIs’ point to your application and ends with “/*”

Configure the Web Application

After you created the client configuration, you can setup your web application.  In the web.xml file of your war module add the following login configuration

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

In addition the 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 you need to add users to keycloak allowing to access your wildfly application. Typically you also should add roles to your client configuration needed by your wildfly application. These roles are later assigned automatically to the JAAS security context.

You can add the roles to a user by selecting the corresponding client configuration in the section ‘RoleMapping’ of a user definition:

That’s it. Now you application will use keycloak authentication.