Configuring Keycloak Database

This tutorial will show you three different ways to configure a different database for your Keycloak Identity Provider. Let’s check it out!

Configuring a local Keycloak Database

So the first way to configure a Keycloak Identity Provider with a Database is by adding a Datasource configuration specific for keycloak. This can be done by setting the property dataSource of your keycloak subsystem, nested into the spi element:

<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="false"/>
             <property name="migrationStrategy" value="manual"/>
             <property name="migrationExport" value="${jboss.home.dir}/keycloak-database-update.sql"/>
         </properties>
     </provider>
    </spi>
    ...
</subsystem>

Therefore, you have to provide a valid KeycloakDS definition in your configuration. For example, if you were to use MySQL as back-end for your Keycloak server:

<subsystem xmlns="urn:jboss:domain:datasources:4.0">
   <datasources>
      <datasource jndi-name="java:/jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true">
         <connection-url>jdbc:mysql://localhost:3306/keycloak?useSSL=false&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="mysql" module="com.mysql">
            <driver-class>com.mysql.jdbc.Driver</driver-class>
         </driver>
      </drivers>
   </datasources>
</subsystem>

For that to work, you have to create the schema on the Keycloak Database:

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)

Well that appears to be a bit verbose, so let’s see how we can speed up things using the Docker image of keycloak. For more info about how to use the Docker image of keycloak check this tutorial: Running Keycloak with Docker

Creating a Docker Network to bind Keycloak with a Database

So, the next option we will show, consists in creating an User Defined Network with docker, in order to connect the Docker image of Keycloak with that of a Database.

The following command will create an user defined bridge network:

docker network create keycloak-network

Docker network under the hoods

Docker’s user-defined bridges provide isolation and interoperability between containerized applications.
Containers connected to the same user-defined bridge network automatically expose all ports to each other, and no ports to the outside world. User-defined bridges also provide automatic DNS resolution between containers. Finally, linked containers on the default bridge network share environment variables.

Now start the Database instance, for example a PostgreSQL instance, passing as argument (–net) the user defined network:

docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres

Start a Keycloak instance, passing as well as argument the user’s defined network:

docker run --name keycloak --net keycloak-network jboss/keycloak -e DB_USER=keycloak -e DB_PASSWORD=password

That’s all. pretty cool isn’t it?

Using Docker compose to manage Keycloak and the DB Container

Lastly, it is worth mentioning that you can use Docker-Compose tool to manage both Keycloak Identity Provider and the Database container image in a single file. In this approach, we will use the DB_VENDOR environment variable of keycloak’s image to determine which database we want to link to. Here’s an example docker-compose.yml file which configures Keycloak with PostgreSQL Database:

version: '3'

volumes:
  postgres_data:
      driver: local

services:
  postgres:
      image: postgres
      volumes:
        - postgres_data:/var/lib/postgresql/data
      environment:
        POSTGRES_DB: keycloak
        POSTGRES_USER: keycloak
        POSTGRES_PASSWORD: password
  keycloak:
      image: jboss/keycloak
      environment:
        DB_VENDOR: POSTGRES
        DB_ADDR: postgres
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_SCHEMA: public
        DB_PASSWORD: password
        KEYCLOAK_USER: admin
        KEYCLOAK_PASSWORD: Pa55w0rd
        # Uncomment the line below if you want to specify JDBC parameters. The parameter below is just an example, and it shouldn't be used in production without knowledge. It is highly recommended that you read the PostgreSQL JDBC driver documentation in order to use it.
        #JDBC_PARAMS: "ssl=true"
      ports:
        - 8080:8080
      depends_on:
        - postgres

You can simply run it with:

docker-compose up

In this tutorial we have covered how to configure Keycloak Identity Provider with a Database. Check this Github page for more examples of Docker-compose files for various Databases: https://github.com/keycloak/keycloak-containers/tree/master/docker-compose-examples