Keycloak and mod_auth_openidc

This page contains information, code snippets and other information regarding using Keycloak with mod_auth_openidc.

Getting Keycloak up and running

Keycloak is available from keycloak.org.  It is an application embedded in a JBoss WildFly JEE container.  The easiest way to get it working is to use an existing docker container.  This container is set up to use with a MySQL datastore.  To run Keycloak with a dockerized version of MySQL, try this:

$ docker run --name mysql -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e MYSQL_ROOT_PASSWORD=password -d mysql

$ docker run -it --link mysql:mysql -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -p 8080:8080 -p 9990:9990 jboss/keycloak-mysql

A docker-compose.yml file for the latter command is:

keycloak:

    image: jboss/keycloak-mysql

    environment:

        MYSQL_DATABASE: keycloak

        MYSQL_USER: keycloak

        MYSQL_PASSWORD: keycloak

        KEYCLOAK_USER: admin

        KEYCLOAK_PASSWORD: admin

    ports:

        - "8080:8080"

        - "9990:9990"

    external_links:

        - mysql:mysql

Keycloak will create and populate the required database tables on initial startup.  The admin console should then be available via http://localhost:8080 and the Admin Console link using the KEYCLOAK_* credentials from the above command (admin/admin in this example).

Adding a realm manually

Initially, Keycloak has only one admin realm, which should be used for admin purposes only so we must add a non-admin realm.  From the admin console, below the Keycloak logo on the left, click on "Master" with the down arrow symbol and select the "Add realm" button.  Let's call the new realm heeadmin and save it.

Adding a client manually

Once the new realm has been added, we need to add a client.  This client is the account that will be used by Apache to call into Keycloak to validate the authorisation code that Keycloak passes via the browser for logged in users.

Click on the Client option on the left-hand menu and then the Create button at the top right above the list of existing clients.  Let's call the new client "apache" and set the access type to "confidential".  Enter a redirect URL (towards the bottom of the page) within the URL namespace that will be protected by Keycloak and save.  You can also put just the host's root URL and a wildcard (e.g. http://server/*).  Save the client.

On the credentials tab (second tab at the top of the page), make a note of the client secret: it's a UUID that will be needed when setting up Apache.

Adding users and groups manually

Click on the group menu item on the left-hand menu and then at the top right click "New" to add new groups.

Click on the user menu item on the left-hand menu and then at the top right "Add user".  Enter the desired username and save.  On the credentials tab you can then enter a new password.  Turn off the temporary password feature and reset the password.  Go to the group tab at the top and add groups to the created user.

Installing mod_auth_openidc

The latest release of the module and its dependencies is available at https://github.com/pingidentity/mod_auth_openidc/releases/latest (2.0.0 at the time of writing).

The Apache module relies on the cjose library (for decoding JWTs) and libhiredis for the optional Redis shared session cache.  (I had a small problem when installing on Fedora 24 as the binary release required libhiredis.so.0.12 but the installed version on my machine was 0.13.  I got around this by creating a symbolic link from 0.12 to 0.13 on an assumption of backward compatibility.  You might not be affected by this.)

Configuring Apache

The Apache configuration needs to be set up to talk to Keycloak.  There is an Apache configuration file fragment at https://github.com/Health-Education-England/TIS-SECURITY/blob/master/keycloak/httpd_openidconnect.conf.  

The main elements to configure manually are:

Setting up permissions

Access control rules can be put into the Apache config file to limit access to certain URLs to users with a given set of permissions (granted via groups).

    <Location />
        AuthType openid-connect
        Require claim groups:supervisor
        ProxyPass           http://localhost:8082/
        ProxyPassReverse    http://localhost:8082/
    </Location>

Note that Apache's authorisation by default looks for any of the Require rules to pass (i.e. it ORs the rules).  If you want to enforce all of the claims (such as being a member of two groups) then you should use a <RequireAll> block.  Rules based on HTTP methods can also be defined either with "Require method GET" or with <Limit GET>.  Be careful that <Limit methods...> applies the contained rules only to the named methods so you may want to use <LimitExcept methods...> instead.  See the Apache documentation at https://httpd.apache.org/docs/2.4/mod/mod_authz_core.html for further details on Require and https://httpd.apache.org/docs/2.4/mod/core.html#limit for details on Limit.