Setup Keycloak Cluster on OpenShift 3

Nowadays, security is a big concern in the IT area. We want to stay secure and private everywhere. To address these security and privacy needs, we use public and private keys, password, fingerprints, and eyes recognition. There are so many platforms, so many credentials to be created, so many usernames and passwords to remember. Do you really remember all your credentials? Some people use password managers and others frequently use the “Forgot Password” feature.

As sysadmins, when we deploy platforms into production infrastructure, our desire is that every platform has it’s authentication and authorization system. But it’s tiresome for developers teams to create and maintain these authentication modes.

This problem can be resolved by using SSO (Single-Sign-On) systems. A single account linked to all your accounts. Everyone can benefit from SSO systems. Users just need to remember credentials of one account to rule them all, while developers don’t have to come up with authentication and authorization services for every platform. Keycloak is a great open-source alternative for SSO systems that provides security and privacy for modern applications.

What is Keycloak?

Keycloak, by Red Hat, Inc., is an open source Identity and Access Management solution intended to provide security for modern applications. Keycloak offers several features, like social login, multi-factor authentication, and centralized users management. For more information, you can check the official documentation.

In this article I will be covering the basics for deploy and setting up of Keycloak on OpenShift 3.

Prerequisites

We’ll be using OpenShift (OKD — open source version) to deploy Keycloak, but you could self-hosted an OpenShift cluster using MiniShift.

Knowledge about Docker and containers is highly recommended. If you are not familiar with these concepts, check these documentation before we get started:

1. What’s a Linux Container?
2. Docker docs

Step 0 — Project/Namespace

Before we start, we’ll login in the OpenShift/MiniShift using oc login command. After that, it’s time to create the namespace in the cluster. The following command will create namespace and apply label region to select in which k8s nodes Keycloak will be running.

$ make patch

Makefile to deploy Keycloak on OpenShift cluster

Step 1 — Database

In this article we’ll set up PostgreSQL on OpenShift cluster. However, I suggest to set up external database to avoid I/O from PV (Persistent Volume) in the OpenShift cluster. In our scenario we’re running the OpenShit cluster using low-end HDD and SSDs with limited hardware capabilities as disks options. When you’ve a set of applications running at the same cluster, and these applications and services are using PV and PVC (Persistent Volume Claim), the load average from virtual machines can increase quickly, and could depreciate your cluster or turn a few nodes unavailable.

The file to deploy PostgreSQL in the OpenShift cluster is available below. However, before we deploy the PostgreSQL service, we should define all secrets for PostgreSQL credentials. At the end of file, there are three secrets objects, which are defined as postgres-username-secret, postgres-password-secret, and postgres-root-passoword-secret. When we use secrets, the value should be encode using base64 format. Following is an example of how to encode strings text-plan into base64 hash in Linux:

$ echo 'string-sensitive-secret' | base64

After generating the secrets, we should use flag database on Makefile to deploy PostgreSQL:

$ make database

Deploy file for PostgreSQL on OpenShift cluster

Step 2 — Keycloak Cluster

You can download the latest release of Keycloak from Docker Hub. In this article, we’ll be using Keycloak 9.0.2 Server.

Before we deploy and set up Keycloak in the OpenShift cluster, it is necessary to build Keycloak Docker images. In our scenario, cluster configuration and adding themes will be declared in the Dockerfile.

The cluster script is showed below:

Script to configure infinispan for share sessions between Keycloak(s) nodes.

We’re going to add the script above into /opt/jboss/tools/cli/jgroups/discovery directory. To do this, we use the command as shown below in the Dockerfile.

COPY ./default.cli /opt/jboss/tools/cli/jgroups/discovery/default.cli

By default, we set the lower limit of pods to 1 replica and the upper limit to 2 replicas in AutoScale for Keycloak cluster. Bellow you can checkout AutoScaling object for OpenShift.

Declaration of HorizontalAutoScale Object

Next, we’ll add custom themes in Keycloak, add the custom themes under ./themes directory. The Dockerfile is responsible to add themes under /opt/jboss/keycloak/themes.

COPY ./themes /opt/jboss/keycloak/themes/

After that, we’ve to build Docker image in local environment. For this article we can build the Docker images in our local environment, but I suggest using a CI/CD system if following these steps in development and production environments.

To build the Keycloak Docker image, following the below command:

docker build -t keycloak-openshift:9.0.2 -f ${PWD}/Dockerfile .

After building the Docker image, tag and push to OpenShift Docker registry:

Tag:

docker tag keycloak-openshift:9.0.2 docker-registry/sso/keycloak:latest

Login into Docker registry:

docker login docker-registry

Push Docker image to registry:

docker push docker-registry/sso/keycloak:latest

Finally, we’ll deploy Keycloak on OpenShift cluster. However, we still need to set up the environmental variables for Keycloak.

Open keycloak-https-mutual-tls.yml in a editor.

$ vim keycloak-https-mutual-tls.yml

We should define all secrets for Keycloak admin credentials. At the end of file there are two secrets objects, which were defined as keycloak-admin-user-secret and keycloak-admin-password-secret. When we use secrets, the value should be encode using base64 format. Following is an example of how to encode strings text-plan into base64 hash in Linux:

$ echo 'string-sensitive-secret' | base64

Next, make the changes on variables DB_ADDR and DB_DATABASE or you can simply copy/paste the below content as it is.

Environment sample file for Keycloak

Save and exit the file.

Next, we’ll use Makefile again to deploy Keycloak. Now it’ll be used flag create to deploy on OpenShift cluster.

$ make create

Now access the Keycloak server at:

https://<instance-public-ip>/auth/

Keycloak — Main page

To login enter the admin username and password that we defined in the Secrets objects.

Keycloak — Realm Master admin page

We have successfully logged into the master realm administration console. We can now create new realms, clients, roles, groups or users as we need.

Checkout the full code on my repository in GitHub.