Running Keycloak using PostgreSQL database.

In this post, we will be going over how to configure the PostgreSQL database with Keycloak. Keycloak standard distribution comes with H2 embedded database. The process discussed in this post can be used for other supported databases like Mysql.

Prerequisites

• Docker
• Keycloak (using version: 13.0.1)
• PostgreSQL JDBC 4.2 Driver, 42.2.20
• git

GitHub repository: keycloak-integration

git clone https://github.com/akoserwal/keycloak-integrations.git

Setup

Postgres Module Configuration

For EAP/Wildfly distribution. It follows the Java convention for the package structure. Like a reverse domain name.

Let’s name the module com.postgres and the folder structure would look like this:

com
│   ├── postgres
│   │   └── main
│   │       ├── module.xml
│   │       └── postgresql-42.2.20.jar

The main folder will contain

• module.xml
• Postgresql driver

Module.xml

<?xml version="1.0" ?>
<module xmlns="urn:jboss:module:1.3" name="com.postgres">
 <resources>
  <resource-root path="postgresql-42.2.20.jar" />
 </resources>
 <dependencies>
  <module name="javax.api"/>
  <module name="javax.transaction.api"/>
 </dependencies>
</module>

We need to create this module in the Keycloak installation director

keycloak-x.x.x/modules/system/layers/keycloak/com

I have already provided a sample module structure in the repository to make it easier to configure. Follow the instructions to configure.

Download the PostgreSQL driver and copy the driver to the modules directory in the repository.

After cloning the repository

cd keycloak-integrations/keycloak-postgresql/

Run to download the driver.

cd keycloak-config/postgres/main && { wget https://jdbc.postgresql.org/download/postgresql-42.2.20.jar ; cd -; }

Set your Keycloak installation directory path. In my case, it is the root directory.

export KEYCLOAK_DIR=~/keycloak-X.X.X

Copy the Postgres module to the Keycloak modules directory path

rsync -r keycloak-config/* $KEYCLOAK_DIR/modules/system/layers/keycloak/com

Run the PostgreSQL Database

Run this shell script setup_postgres.sh to spin up an ephemeral instance of PostgreSQL DB

• Update the POSTGRES_USER & POSTGRES_PASSWORD

#!/bin/bash
set -e
docker network create keycloak-postgres-network || true
docker run \
  --name=keycloak-postgres \
  --net keycloak-postgres-network \
  -e POSTGRES_PASSWORD=<Your-Pass> \
  -e POSTGRES_USER=<Admin-User> \
  -e POSTGRES_DB=keycloak\
  -p 32769:5432 \
  -d postgres:13

Check if the PostgreSQL database is up & running

$ docker ps -a
//In my case it is running on
postgres:13  0.0.0.0:32769->5432/tcp   keycloak-postgres

Keycloak: update the data source configuration

cd $KEYCLOAK_DIR/standalone/configuration

Open the standalone.xml in an editor. Search for the data source & update the config with:

Refer link: standalone.xml#L439

• make sure the connection url is correct. In my case, it is jdbc:postgresql://localhost:32769/keycloak
• Use the same <user-name></user-name> asPOSTGRES_USER
• Use the same <password></password> as POSTGRES_PASSWORD

Below, add the driver configuration. You can see a reference to the module=”com.postgres”

Refer to link: standalone.xml#L457

Replace the ExampleDS with KeycloakDS

Please refer: standalone.xml#L108

That’s all you need to configure the PostgreSQL database with keycloak.

Start the Keycloak Server

cd $KEYCLOAK_DIR/bin
./standalone.sh

Now you have Keycloak running with Postgres Database.

Docker Compose

If you want to try out the docker-compose version for running Keycloak with Postgres.

https://raw.githubusercontent.com/keycloak/keycloak-containers/main/docker-compose-examples/keycloak-postgres.yml

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: quay.io/keycloak/keycloak:legacy
      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

Conclusion

A similar process can be followed for configuring other supported databases with Keycloak.

Steps we followed:

• Create the module structure
• Download the driver
• Configure the data source configuration

If you like this post, give it a Cheer!!!

Follow the Collection: Keycloak for learning more…

Happy Secure Coding ❤