Starting SSO with Keycloak

 

I've been using Keycloak for years now and have been experimenting with the newer versions that are based on top of Quarkus.  One of the struggles I've had is spinning up a test server for development.  The new Quarkus model though is pretty simple.  A small Docker Compose script let's you spin up an environment in almost no time.

My script looks like:

version: '3.8'

services:
  postgres:
    image: postgres:latest
    environment:
        POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    restart: unless-stopped
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U postgres" ]
    networks:
      - pg_network
    volumes:
      - ./pgdata:/var/lib/postgresql/data
      - ./create_db.sql:/docker-entrypoint-initdb.d/create_db.sql

  keycloak:
    image: quay.io/keycloak/keycloak:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      KC_DB: ${KC_DB}
      KC_DB_URL: ${KC_DB_URL}
      KC_DB_USERNAME: ${KC_DB_USERNAME}
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KEYCLOAK_ADMIN:  ${KEYCLOAK_ADMIN}
      KEYCLOAK_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_PROXY: edge
      KC_HOSTNAME_URL: ${KC_HOSTNAME_URL}

    volumes:
      - /tmp:/opt/keycloak/data/import

    networks:
      - pg_network
    restart: unless-stopped
    ports:
      - 8080:8080
    entrypoint: /opt/keycloak/bin/kc.sh start

networks:
  pg_network:
    driver: bridge

So what does this do?   Ultimately we start a PostgreSQL database server and then Keycloak.  The PostgreSQL server is the current latest one.  A small script:

CREATE USER keycloak WITH PASSWORD 'keycloak';
CREATE DATABASE keycloak with
    owner = keycloak
    encoding = 'UTF8';

is used to create a Keycloak user and password.  This script is meant for development so I'm not too concerned about the database password.  Plus that, we never expose the PostgreSQL port to the outside world so it really doesn't matter - think of the database running in the private network of a VPN.

Next, we startup Keycloak.  Most of the configuration comes from a local .env file:

#
# postgres env vars
#
POSTGRES_PASSWORD=postgres


#
# keycloak env vars
#
KC_DB=postgres
KC_DB_URL=jdbc:postgresql://postgres:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=keycloak

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=changeme!

KC_HOSTNAME_URL=http://localhost:8080

that allows you to separate out the code from the credentials.

Running the server

To run the server, you don't need to build a local Docker.  Just run:

docker compose -f docker-compose.yml up

This will start the PostgreSQL server along with Keycloak. As part of this it will create the local directory pgdata/ that contains the PostgreSQL database. Note that on Unix-based environments like Linux this directory may have files that are owned by root that will require superuser permissions to remove.

Now you can connect to http://localhost:8080/. You'll be able to log into Keycloak with the user admin with password changeme! as specified in the .env file.  See the Keycloak docs to get started.

Code

The code above is available at https://github.com/stdunbar/keycloak-docker

 

 Photo by Waldemar on Unsplash