How to Setup Keycloak With MySQL Database using CLI in Docker

3 min readOct 9, 2022

1. Introduction

Keycloak is one of the most popular open-source Identity and Access Management platforms backed by RedHat. It is known for its flexibility and extensibility which makes it a top candidate in the enterprise world where there are complicated use cases for user authentication and authorization. For example, having multiple applications that must support multi-tenant and n-reseller levels with a single login.

1.1 Prerequisites

Knowledge of the following is required.

  • Keycloak
  • Docker
  • MySQL

2. ct-keycloak-iam

ct-keycloak-iam is a project I developed to deliver a custom Keycloak server in a docker container. It includes a default realm, custom themes, database connection (MySQL), and custom SPIs (required sponsorship).

It contains CLI scripts that will download the Keycloak server and install a MySQL data source.

The project is available at

Folders/files that we will use.

  • keycloak-docker-assembly
  • docker
  • Dockerfile — builds a custom Keycloak container
  • docker-compose-dev.yml — builds and runs the custom Keycloak container and MySQL.
  • src/main/resources
  • build
  • cli/database/mysql
  • set-database.cli — a set of instructions to create an entry of MySQL data source and driver in your Keycloak configuration. Note that it uses the environment variables defined in your docker-compose file.
  • modules/databases/mysql
  • module.xml — MySQL module file needed by Keycloak, make sure that the version matches the one defined in the Dockerfile (instead you changed it)

3. Docker Compose

Instead of manually creating a MySQL database, users, and permissions we will use a MySQL docker image to do the job.

We need to define the MySQL connection settings as environment variables.

version: ‘3’

image: mysql:8.0
— 33066:3306
MYSQL_USER: keycloak
command: mysqld — sql_mode=””

— keycloak-db
context: ../
dockerfile: docker/Dockerfile
— 8888:8888
— 8080:8080
— 8443:8443
— 9990:9990
DB_ADDR: keycloak-db
DB_PORT: 3306
DB_DATABASE: keycloak
DB_USER: keycloak
DB_PASSWORD: keycloak
DB_JDBC_PARAMS: useSSL=false&allowPublicKeyRetrieval=true

KEYCLOAK_IMPORT: /opt/jboss/keycloak_install_stage/realms/ct-realm-dev.json
KEYCLOAK_USER: keycloak.admin
KEYCLOAK_PASSWORD: keycloak.admin



Make sure that the DB_XXX parameter values in the ct-keycloak-iam container match that of MySQL.

4. Configure the MySQL Driver and Module

This is already done by the, a script which copies the MySQL driver and module.xml file to the extracted Keycloak server inside the Docker container.

Here’s our MySQL module file.

<?xml version=”1.0" encoding=”UTF-8"?>
xmlns=”urn:jboss:module:1.0" name=”com.mysql.jdbc”>
<resource-root path=”mysql-connector-java-8.0.29.jar”/>
<module name=”javax.api”/>
<module name=”javax.transaction.api”/>

5. Add the MySQL Datasource and Driver Configuration in Keycloak

This is handled by the set-database.cli script which installs the data source and driver configuration by using the values from the environment variables such as database url, username, password, and JDBC params.

/subsystem=datasources/data-source=KeycloakDS: remove()
/subsystem=datasources/data-source=KeycloakDS: add(jndi-name=java:jboss/datasources/KeycloakDS,enabled=true,use-java-context=true,use-ccm=true, connection-url=jdbc:mysql://${env.DB_ADDR:mysql}:${env.DB_PORT:3306}/${env.DB_DATABASE:keycloak}${env.DB_JDBC_PARAMS:}, driver-name=mysql)
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=user-name, value=${env.DB_USER:keycloak})
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=password, value=${env.DB_PASSWORD:password})
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=check-valid-connection-sql, value=”SELECT 1")
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=background-validation, value=true)
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=background-validation-millis, value=60000)
/subsystem=datasources/data-source=KeycloakDS: write-attribute(name=flush-strategy, value=IdleConnections)
/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql, driver-module-name=com.mysql.jdbc,driver-xa-datasource-class-name=com.mysql.cj.jdbc.MysqlXADataSource)

6. Running the Project

If you’re familiar with docker-compose then you know that it’s our entry point to our custom Keycloak server.

Before running it, make sure to comment on the line that imports the SPIs, or become my sponsor in GitHub, so that you can gain access to those restricted projects.

docker-compose -f ./keycloak-docker-assembly/docker/docker-compose-dev.yml up — build




Open for Collaboration | Senior Java Backend Developer