How to Setup Keycloak With MySQL Database using CLI in Docker

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, making it a top candidate in the enterprise world, where there are complicated use cases for user authentication and authorization use cases. For example, multiple applications 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  https://github.com/czetsuya/ct-keycloak-iam.

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.
• build-keycloak.sh
• 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'

services:
  keycloak-db:
    image: mysql:8.0
    ports:
      - 33066:3306
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: keycloak
      MYSQL_USER: keycloak
      MYSQL_PASSWORD: keycloak
    command: mysqld --sql_mode=""

  ct-keycloak-iam:
    depends_on:
      - keycloak-db
    build:
      context: ../
      dockerfile: docker/Dockerfile
    ports:
      - 8888:8888
      - 8080:8080
      - 8443:8443
      - 9990:9990
    environment:
      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

      KC_HOSTNAME_STRICT: false

      DEBUG_PORT: 8888
      PROXY_ADDRESS_FORWARDING: 'true'

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

4. Configure the MySQL Driver and Module

This is already done by the build-keycloak.sh, a script that 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"?>
<module
	xmlns="urn:jboss:module:1.0" name="com.mysql.jdbc">
  <resources>
    <resource-root path="mysql-connector-java-8.0.29.jar"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>

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, you know that it's our entry point to our custom Keycloak server.

Before running it, 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