[Updated with the latest release of Keycloak]

Keycloak is an Identity and Access Management Server for Modern Applications and Services. In this tutorial we will learn how to delegate a bash Web application authentication (running on WildFly) to a KeyCloak server.

First of all, download the latest stable build of Keycloak from http://keycloak.jboss.org/keycloak/downloads

Also, we will need to patch our WildFly server in order to enable the keycloak subsystem, so download as well the keycloak adapter from https://www.keycloak.org/downloads.html

Starting Keycloak

Keycloak ships bundled in a WildFly installation. We will start it with an offset of 100 in order to avoid conflicts with our WildFly server (that will be bound with 0 offset), where our application will run:

$ ./standalone.sh -Djboss.socket.binding.port-offset=100

Now log into the Administration Console, available at: http://localhost:8180

In your first Login, you will be requested to create an administration user:

keycloak tutorial

Next, login with the admin user you have just created:

keycloak introduction

Create your Keycloak Realm, Roles and Users

The core concept in Keycloak is a Realm. A realm secures and manages security metadata for a set of users, applications, and registered oauth clients. Users can be created within a specific realm within the Administration console. Roles (permission types) can be defined at the realm level and you can also set up user role mappings to assign these permissions to specific users.

Let's start by creating a new Realm by clicking on the Add Realm Button, located on the left side bar:

keycloak tutorial

Enter the Realm Name, for example MyRealm and click on Create:

keycloak tutorial

Now we will define a Role. The Role will be used by your applications to define which users will be authorized to access the application. Click on the "Roles" left link and choose "Add Role":

keycloak tutorial

We have added a Role named "Manager" that will be authorized to access our application. So far we don't have any User, besides the admin user. We will create another one to be used by our application. Click on the "Users" left option and choose to Add a new User:

keycloak tutorial

The User named "frank" will be added by clicking on Save. Now select the User from the list: we need to perform two actions on it.

keycloak tutorial

The first one will be setting a password for it so click on Credentials and set a new Password for the user:

keycloak tutorial

Next we will include the User as part of the Manager Role. Click on Role Mappings and assign the User to the Manager Role by selecting the Manager Role and clicking on Add selected:

keycloak tutorial

Define Client policies

Done with User and Realms. We need to define which applications are mapped to our Users/Roles. In the earlier versions of KeyCloak you had to click on the "Applications" left link. Now applications are categorized as "Clients" so click on that link on the left:

keycloak tutorial

Choose to Create a new Client. The most important settings are the application Root URL (that will be appended to the URI path) and the Redirect URIs where request will be forwarded after login. In our case, we will create a web application named "keydemo" therefore we will use the following settings:

keycloak tutorial

Click on Save. Once saved, the last step will be generating a public key for your realm that will be bundled in your application. From the Clients perspective, click on the Installation link and choose to generate a JSON authorization code for your application:

keycloak tutorial

Download the JSON or simply copy it in an editor, we will use it in a minute.

Patching Keycloak

Your application server, as it is, is now aware of Keycloak authentication/authorization mechanisms, hence we need to install an adapter for it. You should have already download the correct installer for your server version. In order to patch the application server perform these two steps:

1) Unzip the Adapter into the directory where you have installed WildFly:

Unzip this file into the root directory of your Wildfly distribution.

Next perform the following actions:
For WildFly 10:

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

For WildFly 11 and above:

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

This script will make the appropriate edits to the …‚Äč/standalone/configuration/standalone.xml file of your app server distribution.

Great. Reload or Restart your server which now is Keycloak aware!

Securing an application secured with Keycloak

There are two options to authenticate your applications using Keycloak.

  • The first option consists in adding the Keycloak JSON file within your Web application and specify in web.xml that we will be using KEYCLOAK Auth.
  • The second option consists in configuring WildFly keycloak's subsystem with the list of applications that will use KEYCLOAK Auth.

Keycloak security in the Web application

Create a Web application that exposes the "/hello" URL and include within the web.xml file a security-constraint bound to the "Manager" Role. Also include as authentication mechanism "KEYCLOAK" which is not a standard JEE authentication mechanism, hence it needs that you patched the application server as we have describer earlier:

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"




The last thing we need to add, in the WEB-INF folder, is a keycloak.json with that contains the JSON descriptor we have just generated.

  "realm": "MyRealm",
  "auth-server-url": "http://localhost:8180/auth",
  "ssl-required": "external",
  "resource": "demo-keycloak",
  "credentials": {
    "secret": "86f1644f-b686-4011-8c05-31ca7245f94a"
  "confidential-port": 0

Save and deploy the application. If you try to access your application at localhost:8080/hello the Keycloak login authentication UI will prompt:

keycloak introduction

Enter your User's credentials with the "Manager" Role and verify that you can access the pages contained in your application.

Keycloak security in the WildFly

This option has the advantage that can be applied without changing the content of your Web application. The whole configuration is applied on the server.

From the Keycloak client Tab, you can choose as Installation "Keycloak OIDC JBoss Subsystem XML" as you can see from this picture:

keycloak subsystem

Copy the XML template from the Installation page, and paste this into the standalone.xml file that resides in the standalone/configuration directory of the application server instance on which your application is deployed.

Open the standalone/configuration/standalone.xml file and search for the following text:

<subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>

Simply paste the XML in the subsystem and replace the secure-deployment name with the application name. You are done!

That was a kickstart tutorial to keycloak. Lots more advanced options are available such as User federation, SSO and more! We will learn more in the next keycloak tutorials!