Skip to content

Keycloak MySQL Setup

Jump to bottom
Adrian Matei edited this page May 14, 2017 · 12 revisions

Keycloak comes with its own embedded Java-based relational database called H2. This is the default database that Keycloak will use to persist data and really only exists so that you can run the authentication server out of the box. It's fine for development purposes, but for production it is recommended to replace it with a more production ready external database. Given my history and affinity with MySQL, we use the MySQL Community Edition v5.7 for the #codingmarks project, which is the freely downloadable version of the world's most popular open source database. It is available under the GPL license and is supported by a huge and active community of open source developers.

This guide presents what we need to do to run Keycloak on MySQL. Check out the Relational Database Setup official documentation, for configuring other Relational database management system(RDBMS)

The installation of the MySQL Community Edition is not in scope, of this guide, but I can tell you is a straight forward process. You can find instructions about installing MySQL on the different platforms in the official documentation

Prepare Keycloak schema and user

Connect to the MySQL shell as root and create a schema and user needed for Keycloak:

$ mysql -uroot -p
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 3
Server version: 5.7.17 MySQL Community Server (GPL)

Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

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

mysql> CREATE DATABASE keycloak;
Query OK, 1 row affected (0.00 sec)

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

After giving in your password you have done the following

  • created keycloak database
  • created keycloak user with the password keycloak (please use a strong password for production)
  • granted all privileges to the keycloak on the keycloak database

If you prefer it visual, then MySQL Workbench is the right tool for this job.

RDBMS Setup Checklist

Now that we have the database prepared there are a couple of steps steps we will need to perform to get an RDBMS configured for Keycloak:

  • Locate and download a JDBC driver for your database
  • Package the driver JAR into a module and install this module into the server
  • Declare the JDBC driver in the configuration profile of the server
  • Modify the datasource configuration to use your database's JDBC driver
  • Modify the datasource configuration to define the connection parameters to your database

JDBC Setup

JDBC is a Java API that is used to connect to a RDBMS. There are different JDBC drivers per database type that are provided by your database vendor.

First thing we need to do is find and download the JDBC driver JAR for MySQL. MySQL Connector/J is the official JDBC driver for MySQL. We can download it from the official page. We download the ´.zip´ version and place it in our tmp folder:

Before we can use this driver, we must package it up into a module and install it into the server. Modules define JARs that are loaded into the Keycloak classpath and the dependencies those JARs have on other modules. They are pretty simple to set up.

Clone this wiki locally