Introduction

Keycloak is an Open Source Identity and Access Management with which you can add authentication to applications and secure services with minimum fuss. No need to deal with storing users or authenticating users. It’s all available out of the box.

The basic installation works with embedded H2 database which is not for production systems. If you want to use for production you have to connect with an external database. Here we will see the steps for using MySQL Server:

• Create the database schema
• JDBC Setup
  • Download library and pack it as a keycloak module
  • Declare and load JDBC Driver
  • Datasource setup
  • Database configuration

Files affected

• KEYCLOAK_HOME/modules/system/layers/keycloak/com/mysql/main/module.xml
• KEYCLOAK_HOME/standalone/configuration/standalone.xml

Create the database schema

mysql> CREATE USER 'keycloak'@'%' IDENTIFIED BY 'keycloak';
Query OK, 0 rows affected (0.01 sec)

mysql> CREATE DATABASE keycloak CHARACTER SET utf8 COLLATE utf8_unicode_ci;
Query OK, 1 row affected (0.00 sec)

mysql> GRANT ALL PRIVILEGES ON keycloak.* TO 'keycloak'@'%';
Query OK, 0 rows affected (0.00 sec)

JDBC Setup

Download the library

• Download the mysql library from https://dev.mysql.com/get/Downloads/Connector-J/mysql-connector-java-5.1.42.zip
• Package the jar file into a module and install it into the server. You have to create a file named module.xml under KEYCLOAK_HOME/modules/system/layers/keycloak/com/mysql/main. The module name should match the directory structure of your module. So, com/mysql maps to com.mysql

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="com.mysql">
<resources>
<resource-root path="mysql-connector-java-5.1.42-bin.jar" />
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>

Declare your packaged JDBC driver

Declare your packaged JDBC driver into your deployment profile so that it loads and becomes available when the server boots up. You have to edit KEYCLOAK_HOME/standalone/configuration/standalone.xml.

Inside drivers XML block within the datasources subsystem, you should see a pre-defined driver declared for the H2 JDBC driver. This is where you’ll declare the MySQL JDBC driver.

<subsystem xmlns="urn:jboss:domain:datasources:4.0">
<datasources>
...
<drivers>
<driver name="mysql" module="com.mysql">
<driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
</subsystem>

We specify the module attribute which points to the module package we created earlier for the mysql JAR and finally, we specify the driver’s Java class, which in our case is com.mysql.jdbc.Driver

Datasource setup

Now we have to modify the existing datasource configuration that Keycloak uses to connect it to MySQL. This has to be done in the same file registered the mysql jdbc driver

<subsystem xmlns="urn:jboss:domain:datasources:4.0">
<datasources>
<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
<connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
<driver>h2</driver>
<security>
<user-name>sa</user-name>
<password>sa</password>
</security>
</datasource>
<datasource jndi-name="java:/jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true">
<connection-url>jdbc:mysql://localhost:3306/keycloak?useSSL=false&amp;characterEncoding=UTF-8</connection-url>
<driver>mysql</driver>
<pool>
<min-pool-size>5</min-pool-size>
<max-pool-size>15</max-pool-size>
</pool>
<security>
<user-name>keycloak</user-name>
<password>keycloak</password>
</security>
<validation>
<valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker"/>
<validate-on-match>true</validate-on-match>
<exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter"/>
</validation>
</datasource>
<drivers>
<driver name="h2" module="com.h2database.h2">
<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>
<driver name="mysql" module="com.mysql">
<driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>
</drivers>
</datasources>
</subsystem>

Database Configuration

The configuration can be found in standalone.xml (if we are running in standalone mode). We keep the default database configuration in the keycloak-server subsystem

<subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
...
<spi name="connectionsJpa">
<provider name="default" enabled="true">
<properties>
<property name="dataSource" value="java:jboss/datasources/KeycloakDS"/>
<property name="initializeEmpty" value="true"/>
<property name="migrationStrategy" value="update"/>
<property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
</properties>
</provider>
</spi>
...
</subsystem>