How to install Keycloak on Docker

Share on Social Media

In this guide, you will learn how to install Keycloak on Docker container. #centlinux #keycloak #docker

What is Keycloak?

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.

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 – docker-01.centlinux.com
  • IP Address – 192.168.116.218 /24

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

Pull required images from Docker Hub:

Connect with docker-01.centlinux.com 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.

$ sudo docker pull mariadb
Using default tag: latest
latest: Pulling from library/mariadb
...
Digest: sha256:6f80d059050b80fd8bd951323f6e4a7dde36d62e355cf01b92d26c34d3f702f6
Status: Downloaded newer image for mariadb:latest

Now, download jboss/keycloak docker image.

$ sudo docker pull jboss/keycloak
Using default tag: latest
latest: Pulling from jboss/keycloak
...
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.

$ sudo docker network create keycloak-network

Install MariaDB 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.

$ mkdir /home/ahmer/keycloak_data

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

$ 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

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.

$ ls /home/ahmer/keycloak_data/
aria_log.00000001  ibdata1      ibtmp1             mysql
aria_log_control   ib_logfile0  keycloak           performance_schema
ib_buffer_pool     ib_logfile1  multi-master.info

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

Install Keycloak on Docker Container:

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

$ 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

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.

$ sudo docker ps
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                              NAMES
e2b42254fa94        jboss/keycloak      "/opt/jboss/tools/doâ¦"   10 minutes ago      Up 10 minutes       0.0.0.0:8080->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.

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

Access Keycloak Server Web UI:

Open URL http://docker-01.centlinux.com:8080 in a web browser.

Keycloak Web UI Welcome Page

Click on ‘Administration Console’ to access it.

Keycloak Web Login

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

Keycloak Server Realm Setting

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

Conclusion – Install Keycloak on Docker:

In this guide, you have learned how to install Keycloak on Docker container. You can now use it to create realms, users, roles, etc. For this you should refer to the Keycloak documentation.

Scroll to Top