1) Presentation

This chapter illustrates how to install Keycloak with MariaDB database and how it is possible to configure MariaDB with KeyCloak.

The version used are:

  • keycloak is 6.01
  • mariadb is 10.3

This done throughout the following steps :

  • (1) installation/configuration of mariadb database for keycloak
  • (2) installation of mariadb mdoule within keyclaok deployement
  • (3) Configuration of keycloak mariadb dasource and driver

2) installation/configuration of mariadb database for keycloak – install keycloak with mariadb

Mariadb is installed on ubuntu for this example, but it could be installed on any other OS.

2.1) install mariadb on ubuntu

Install mariadb on ubuntu

sudo apt install mariadb-server

You can verify it by typing:

2.2) install mysql_secure_installation

Run command :

  • sudo mysql_secure_installation

The script will

  • set up the root user password
  • remove the anonymous user,
  • restrict root user access to the local machine

answer “Y” (yes) to all questions.

At this stage, mariadb can only be accessed as sudo, otherwise you get error message:

ERROR 1698 (28000): Access denied for user ‘root’@’localhost’ at Ubuntu 18.04

2.3) login as non sudo user

To be able to log as non sudo user, you have to run following commands (in italic bold)

2.4) Create Keycloak database

Run the command Create DATABASE keycloak which creates the keycloak database in mariadb

3) Mariadb ConnectorJ

Go to mariadb connector from following URL

The driver to download is :

Let’s verify that is contains the Driver class

Interesting to be noticed is driver path org/mariadb/jdbc/Driver., which will be used further when configuring the driver.

4) Install the mariadb driver module within keycloak

The steps are as follows :

(1) Create a com/mariadb/main module subdirectory, below modules

cd $KEYCLOAK_HOME

mkdir -p modules/com/mariadb/main

(2) copy the mariadb driver into this directory

cd modules com/mariadb/main

cp mariadb-java-client-2.3.0.jar .

(3) create a module.xml file within this directory as follows

5) Configure keycloak with mariadb

The configuration is located in xml file

  • $KEYCLOAK_HOME/standalone/configuration/standalone.xml

The configuratin can be updated directly within the standalone.xml (or standalone-ha.xml) or using the management console

When running for the first time, easiest is to use the management console. In order to use the management console, you need to create an admin management user, using teh script add-user.sh

5.1) adding an admin management user

In order to use the management console, you need to create an admin management user, using teh script add-user.sh

5.2) Using the admin management console

Keycloak is started in standalone-ha mode

The standalone has management port is 9990

To access to the admin management console goto

  • (1) log to http://localhost:9990/console
    • as admin management user (created previously)
  • Go to configuration
  • Go to susbystems
  • Go to Datasources and drivers

You should see that the H2 driver is displayed.

5.2) Installing Mariadb driver

Toggle the button on top right handcorner of the driver iframe.

You should provide following information :

  • Driver Name :
    • mariadb
  • Driver module Name :
    • com.mariadb
  • Driver Class Name :
    • org .mariadb.jdbc.Driver
Howto install KeyCloak with MariaDB

Upon successful configuration, the mariadb driver appears in the management console

Howto install KeyCloak with MariaDB
5.3) Configuring the mariadb datasource

By default, after keycloak installation, it poinsgt to 2 datasources KeycloakDS and ExampleDS which are H2 based.

You need to peform following operations to configure a new DataSource

  • (1) Template
    • Choose custom radio button
  • (2) Attributes
    • Name :
      • KeycloakDS1
    • JNDI Name :
      • java:jboss/datasources/KeycloakDS1
  • (3) JDBC Driver :
    • Driver Name : mariadb
    • Driver Module Name : com.mariadb
    • Driver Class Name : org.mariadb.jdbc.Driver
Howto install KeyCloak with MariaDB
  • (4) Connection
    • Connection URL : jdbc:mariadb://localhost:3306/keycloak
    • UserName : root
    • password : password
Howto install KeyCloak with MariaDB
  • 5) Test Connection
  • (6) Successful connection

Upon Successful connection, message Test Succeeded   is returned

Howto install KeyCloak with MariaDB
  • 8) Displaying all the Datasources and removing H2 Datasources
    • KeycloakDS1 has been added has a new datasource of keycloak pointing to mariadb. It is not in use yet
    • There is still 2 other H2 Datasources (ExampleDS and KeyCloakDS) which needs to be removed

At the end there is only the KeycloakDS1 datasource left.

5.5) modify the JNDI properties

The value of the dataSource has to be updated with what you have put as JNDI Name previously

( java:jboss/datasources/KeycloakDS1)

6) Starting Keycloak with mariadb

You can now start keycloak

6.1 Possible error

Keycloak is likely to fail with following error message

6.3 Undertanding the error message

The error message is by itself quite explantory. The row size of table in Mariadb is 65536, and the command ALTER TABLE keycloak.REALM MODIFY CERTIFICATE VARCHAR(4000) is failing due to this limitation.

This error is due to the fact that the encoding proviedd bt mariadb is utf8_mb4 (4 bytes).

6.4 Fixing the error message

The mariadb charset is provided in /etc/mysql/mariadb.conf.d directory
Comment out all the lines referring to utf8_mb4 so it can uses the default as fallaback (latin1° which is 2 bytes.

6.5) Destroying previous database scheme

You need to remove mariadb keycloak scheme

From now you can restart keycloak safely, and it will no longer bump into the issue seen before.

Olivier Rivat

Senior Software Engineer with over 25 years of experience doing Software Development, Support and Consulting in Identity and Access Management Solutions.
Specialised in IAM (security, access control, identity management) and Open Source integration, settled in 2004 by IAM industry veteran, JANUA offers high value-added products and services to businesses and governements with a concern for Identity Management and Open Source components.
JANUA provides better security, build relationships, and enable new cloud, mobile, and IoT offerings from any device or connected thing.
Olivier Rivat

Les derniers articles par Olivier Rivat (tout voir)