Introduction to 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 http://keycloak.jboss.org/keycloak/downloads.html?dir=0%3Dadapters/keycloak-oidc%3B (For WildFly 9/10 the adapter is keycloak-wildfly-adapter-dist-1.7.0.Final.zip)

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/auth/admin/

You can login with admin/admin though you will be required to change the password after your first access:

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 keycloak-wildfly-adapter-dist.zip

Now, start WildFly:

$ ./standalone.sh

2) And execute from the CLI the adapter installer which will create the keycloak subsystem and security domain:

$ jboss-cli.sh -c --file=adapter-install.cli

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

Deploying an application secured with Keycloak

Eager to test your Keycloak server? so just create a Web application named "keydemo" 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"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">

    <module-name>basicauth</module-name>
	
    <security-constraint>
        <web-resource-collection>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>Manager</role-name>
        </auth-constraint>
    </security-constraint>

    <login-config>
        <auth-method>KEYCLOAK</auth-method>
        <realm-name>MyRealm</realm-name>
    </login-config>

    <security-role>
        <role-name>Manager</role-name>
    </security-role>
</web-app>

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",
  "realm-public-key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAjPvdTFWEsTUYxJzFEy+h/Y0U5sekDgUt3m6ZV1tiu+PfZ2qf0lwj1WRtUusFwfdgK+cKVJ59NC8P4Sxl7Hwrl/jpwqXnuucEHSngmKsPCxMpUBoCxhg/d6uc2WlIVg35c5dn4mZvnWsMXi98PqQDA3ury0LIVq2y/17Dees7Nddfa/Im88l6LX72DHGtw3z0kG9c9z2J+h94DjdzR4f8f9lvgB9BofFlmoeRm8n55Ue9CLd7sll4Wh0+feRBTo2Zrn3iDWCQfQ/OKvZVwuD8+9menMcGezDR3bdrUaxlgV+pv6bI6DwTv4T3dlYThLYMvRJfE6N9Aj3chsi4XsPk3QIDAQAB",
  "auth-server-url": "http://localhost:8180/auth",
  "ssl-required": "external",
  "resource": "keydemo",
  "credentials": {
    "secret": "dc579a04-25d4-4661-9842-87ab2fcd093c"
  }
}

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

keycloak tutorial

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

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!

Follow us on Twitter