Run Keycloak Server in a Docker Container - CentLinux - Installation Guides & HowTos


Saturday, 15 February 2020

Run Keycloak Server in a Docker Container

Run a Keycloak Server in Docker Container

Keycloak is an open source software product to allow single sign-on with Identity Management and Access Management aimed at modern applications and services. As of March 2018 this JBoss community project is under the stewardship of Red Hat who use it as the upstream project for their RH-SSO product. From a conceptual perspective the tool's intent is to make it easy to secure applications and services with little to no coding. (courtesy: Wikipedia)

By using Keycloak, developers can add authentication to applications and secure services with minimum efforts. No need to deal with storing users or authenticating users. It's all available out of the box. You'll even get advanced features such as User Federation, Identity Brokering and Social Login.

There are two main components of Keycloak.

  1. Keycloak Server – It is the Server component of the Keycloak
  2. Keycloak Application Adapter – These are the plugins for applications to access Keycloak Authentication services.

In this article, we are creating and running a Keycloak server in Docker container.


Table of Contents:


Keycloak Features:

Some notable features of Keycloak are:

  • User Registration
  • Social login
  • Single Sign-On/Sign-Off across all applications belonging to the same Realm
  • 2-factor authentication
  • LDAP integration
  • Kerberos broker
  • multitenancy with per-realm customizable skin


Environment Specification:

We are using a minimal Ubuntu Server virtual machine with following specification.

  • CPU - 3.4 Ghz (2 cores)
  • Memory - 2 GB
  • Storage - 20 GB
  • Operating System - Ubuntu Server 18.04 LTS
  • Hostname –
  • IP Address - /24

We have already installed Docker on this server, you can follow our previous article to install Docker on Ubuntu Server 18.04 LTS.


Pulling required images from Docker Hub:

Connect with as an admin user by using a ssh tool.

Since, we have already installed Docker, therefore, we can now access Docker Hub and download the required images.

Here, we are creating two containers,

  1. the actual Jboss/Keycloak server and
  2. MariaDB as data store for the Keycloak server

First, download mariadb official docker image.

ahmer@docker-01:~$ sudo docker pull mariadb Using default tag: latest latest: Pulling from library/mariadb 5c939e3a4d10: Pull complete c63719cdbe7a: Pull complete 19a861ea6baf: Pull complete 651c9d2d6c4f: Pull complete 077e14009561: Pull complete 5f038f59a326: Pull complete 1b0216466f21: Pull complete 1b0570aa273a: Pull complete 07d05628c2aa: Pull complete 8f2f7d8e5cbd: Pull complete fbf3ad7b2eec: Pull complete 22080b3a46be: Pull complete 8021ad8acbef: Pull complete 0b1f06407ccd: Pull complete Digest: sha256:6f80d059050b80fd8bd951323f6e4a7dde36d62e355cf01b92d26c34d3f702f6 Status: Downloaded newer image for mariadb:latest

Now, download jboss/keycloak docker image.

ahmer@docker-01:~$ sudo docker pull jboss/keycloak Using default tag: latest latest: Pulling from jboss/keycloak 03e56b46bf0b: Pull complete 3a13cc2f5d65: Pull complete 315b0e98b961: Pull complete 3ac53bc98ab6: Pull complete 08d597fdd8b1: Pull complete Digest: sha256:70171289054e77e2a091fd4b7d274807e777bd01d18719a7b7b139b67d1952d4 Status: Downloaded newer image for jboss/keycloak:latest


Create a Virtual Network in Docker:

To interconnect MariaDB and Keycloak containers, we need to create a virtual network.

ahmer@docker-01:~$ sudo docker network create keycloak-network 152e689ac69f722e8b36bcb61558dba740ec909ec27c5a8ba34f2f5ca0694038


Run a MariaDB Server in Docker Container:

Create a directory on docker host to store MariaDB database files, so we can use the same database files with other containers of MariaDB server.

ahmer@docker-01:~$ mkdir /home/ahmer/keycloak_data

Create a MariaDB container and mount the keycloak_data directory in it.

ahmer@docker-01:~$ sudo docker run -d \ > --name mariadb \ > --net keycloak-network \ > -v /home/ahmer/keycloak_data:/var/lib/mysql \ > -e MYSQL_ROOT_PASSWORD=Root@1234 \ > -e MYSQL_DATABASE=keycloak \ > -e MYSQL_USER=keycloak \ > -e MYSQL_PASSWORD=Keycloak@1234 \ > mariadb 55de1ec4e0c94dbe22897e6122cec57a250c95cbc4dc1be76fc7a06832f7641a

The above command has been broken down as follows to describe for the readers.

  • docker run -d -> Staring a container in Daemon mode
  • --name mariadb -> Set the name of the container
  • --net keycloak-network -> set the network that will be used by the container
  • -v /home/ahmer/keycloak_data:/var/lib/mysql -> Mount the docker host directory in MariaDB container
  • -e MYSQL_ROOT_PASSWORD -> Set mysql root user password
  • -e MYSQL_DATABASE -> Creates a database with this name in MariaDB container
  • -e MYSQL_USER -> Creates a database user with necessary privileges
  • -e MYSQL_PASSWORD -> Sets the password of mysql user
  • mariadb -> It is the image that will be used to create the docker container

By using Docker, we have successfully started a MariaDB container that will serve as the data store for the Keycloak server.

Check the contains of keycloak_data directory now.

ahmer@docker-01:~$ ls /home/ahmer/keycloak_data/ aria_log.00000001 ibdata1 ibtmp1 mysql aria_log_control ib_logfile0 keycloak performance_schema ib_buffer_pool ib_logfile1

You can see that the MariaDB container has created its database files in keycloak_data directory.


Run a Jboss/Keycloak Server in Docker Container:

Create and run a Jboss/Keycloak container using docker command.

ahmer@docker-01:~$ sudo docker run -d \ > --name keycloak \ > --net keycloak-network \ > -p 8080:8080 \ > -e KEYCLOAK_USER=admin \ > -e KEYCLOAK_PASSWORD=Admin@1234 \ > -e DB_ADDR=mariadb \ > -e DB_USER=keycloak \ > -e DB_PASSWORD=Keycloak@1234 \ > jboss/keycloak e2b42254fa94804e1ab9cf2924fa0463b8997205f6002e81f542b117f56a91bf

Above command has been broken down to describe for better understanding of the readers.

  • docker run -d -> Start a docker container in Daemon mode
  • --name keycloak -> Set name of the docker container
  • --net keycloak-network -> Set the network used by the container
  • -p 8080:8080 -> Port mapping of Docker container with the host machine
  • -e KEYCLOAK_USER -> Set the name of the Keycloak's Admin user
  • -e KEYCLOAK_PASSWORD -> Set the password of Keycloak's Admin user
  • -e DB_ADDR -> set name of data store container
  • -e DB_USER -> set DB username to access MariaDB data store
  • -e DB_PASSWORD -> Set password of DB user
  • jboss/keycloak -> It is the image that will be used to create the Keycloak container

We have created and started the Jboss/Keycloak container.

Check the status of the docker containers by using following command.

ahmer@docker-01:~$ sudo docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e2b42254fa94 jboss/keycloak "/opt/jboss/tools/doâ¦" 10 minutes ago Up 10 minutes>8080/tcp, 8443/tcp keycloak 55de1ec4e0c9 mariadb "docker-entrypoint.sâ¦" 26 minutes ago Up 26 minutes 3306/tcp mariadb

Allow the 8080/tcp service port on docker host, so our Keycloak server can be accessed by the other computers across the network.

ahmer@docker-01:~$ sudo ufw allow 8080/tcp Rules updated Rules updated (v6) ahmer@docker-01:~$ sudo ufw enable Command may disrupt existing ssh connections. Proceed with operation (y|n)? y Firewall is active and enabled on system startup


Accessing Keycloak Server Web UI:

Open URL in a client's browser.


Click on ‘Administration Console’ to access it.


Login as admin user that we have defined while creating the docker container.


After successful login, we are now at the ‘Realm Settings’ page.

We have successfully started a Keycloak container in Docker. You can now use it to create realms, users, roles, etc. For this you should refer to the Keycloak documentation.

No comments:

Post a Comment