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.

keycloak-003

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

keycloak-004

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

2 thoughts on “Using Keycloak for Wildfly Applications

  1. Thanks for the post.

    In our use case (Wildfly 10 + Keycloak) , we need to authenticate both WEB users and remote ejb users.
    Just discover that for WEB users, we dont need specific related to Keycloak.

    For remote ejb users, the “KeycloakLoginMidule” doesn’t seem to work: no connection to Keyclaok. But by replacing it by “DirectAccessGrantsLoginModule” with appropriiate , it works as expected.

    On Keycloak web site, there is a documentation section on “DirectAccessGrantsLoginModule”, but nothing mentioned on “KeycloakLoginModule”. So not sure what should be set. Further more “DirectAccessLoginModule” documentation is in openid connect adapter section, not in saml adapter section, does it mean it is supported only for oidc protocol ?

  2. I have tested a web module with EJBs included. I don’t think the module type does matter at all. Why not deploy all together in an EAR?

Leave a Reply

Your email address will not be published. Required fields are marked *