Keycloak for Identity and Access Management & High Availability Deployment with Kubernetes

Overview

Keycloak is an open-source identity and access management solution which makes it easy to secure modern applications and services with little to no code.

Keycloak offers features such as,

1. Standard Protocols

Keycloak is based on standard protocols and provides support for OpenID Connect, OAuth 2.0, and SAML.

2. Single Sign-On

Your applications don’t have to deal with user stores, storing credentials of users, authenticating users, login forms, session management. With the Single Sign-On feature once a user logged-in to Keycloak, users don’t have to login again to access a different application. The same applied to logout as well.

Default Keycloak User Login Page

3. User Federation

Keycloak has built-in support to connect to existing LDAP or Active Directory servers.

User Federation in Keycloak admin console.

4. Identity Providers

Keycloak can authenticate users with existing OpenID Connect or SAML 2.0 identity providers with just a matter of configuring the identity provider through the admin console. Further with no code, your applications can be integrated with social networks such as Facebook, Google, Microsoft, GitHub, and more.

Identity Providers in Keycloak admin console.

5. Authorization Services

Keycloak provides fine-grained authorization to manage permissions for all the services, users, and groups. Roles can be defined with the provided Keycloak admin console as well as through APIs, SDK.

Roles in Keycloak admin console

Keycloak Deployment

There are many ways to deploy Keycloak. In this article let’s talk a few ways to get it deployed such as,

• Standalone Deployment with Keycloak Distribution Files
• Standalone Deployment with Docker
• High Availability Deployment in Kubernetes

1. Standalone Deployment with Keycloak Distribution Files

1. Make sure you have Java 11 installed to run the latest version of Keycloak.
   If you are using a MacOS, HomeBrew is the easiest way to install Java 11. Otherwise, download Java 11 distribution based on the operating system.

brew cask install java@11

2. Download the latest Keycloak distribution from Keycloak GitHub Releases page. https://github.com/keycloak/keycloak/releases

3. Extract the downloaded Keycloak zip/tar.gz file.

Let’s examine the purpose of some of the directories:

bin: This contains various scripts to either boot the server or performs some other management action on the server.

domain: This contains configuration files and working directory when running Keycloak in domain mode.

modules: These are all the Java libraries used by the server.

standalone: This contains configuration files and working directory when running Keycloak in standalone mode.

standalone/deployments: If you are writing extensions to Keycloak, you can put your extensions here. See the Server Developer Guide for more information on this.

themes: This directory contains all the html, style sheets, JavaScript files, and images used to display any UI screen displayed by the server. Here you can modify an existing theme or create your own. See the Server Developer Guide for more information on this.

4. Open the Terminal and run bin/standalone.sh

cd <PATH>/keycloak-9.0.2/bin
./standalone.sh

If you are a Windows user simply double click bin/standalone.bat file.

5. Access Keycloak using http://localhost:8080 with your favorite web browser.

6. Create an initial admin user by providing Username, Password, Password Confirmation, and clicking on ‘Create’ button.

You will receive the admin user creation confirmation as below.

7. Click on the Administration Console link to access Keycloak admin console. Provide the admin user credential used in the previous step and click on ‘Log In’.

8. Now you are connected to the Keycloak Admin Console.

9. Keycloak Server can be stopped by simply closing the Terminal window.

This deployment model would be useful for Keycloak code level customizations, custom theme development. Please expect an article on this soon.

2. Standalone Deployment with Docker

This is the simplest way to get Keycloak up and running.

1. Make sure you have Docker installed on the laptop or server.
   Follow the official documentation here: https://docs.docker.com/get-docker/
2. Open the Terminal, PowerShell or Command Line and run the following command. Replace the <username> and <password> fields in the below command which will be the initial administrator username and password.

docker run -p 8080:8080 \
    -e KEYCLOAK_USER=<USERNAME> \
    -e KEYCLOAK_PASSWORD=<PASSWORD> \
    jboss/keycloak

3. Access Keycloak using http://localhost:8080 with your favorite web browser.

There are many environment variables available for additional Keycloak configurations such as database integration (MySQL, PostgreSQL, MariaDB, Oracle, Microsoft SQL Server), Import/Export Realms, Custom Themes, Custom Providers, Clustering and more.

Refer Keycloak Docker Hub for more details: https://hub.docker.com/r/jboss/keycloak/

3. High Availability Deployment in Kubernetes

Kubernetes is a portable, extensible, open-source platform for managing containerized workloads and services, that facilitates both declarative configuration and automation. It has a large, rapidly growing ecosystem. Kubernetes services, support, and tools are widely available.

If you don’t have a Kubernetes cluster, the following Keycloak deployment steps can be tested by running Kubernetes locally with the latest Docker distribution. Enable Kubernetes in your local Docker with Docker Preferences/Settings > Kubernetes.

If you already have a Kubernetes cluster for the Keycloak deployment, make sure kubectl command-line tool is configured with the correct KUBECONFIG.

Further let’s consider the persistence, Keycloak high availability aspects as well in this setup.

1. Database Setup

Create a MySQL Database for Keycloak (Make sure Kubernetes can access the database host). Change the Database name keycloak as per your preference.

CREATE DATABASE `keycloak`;

Create a separate Keycloak database user as well for additional security. Change the Username (keycloak) and Password (keycloakpassword) as per your preference.

CREATE USER IF NOT EXISTS 'keycloak'@'%' IDENTIFIED BY 'keycloakpassword';
grant all privileges on `keycloak`.* to 'keycloak'@'%' identified by 'keycloakpassword';

2. Create Kubernetes Secrets

Create a Kubernetes secret to store Keycloak admin user password and database password as below.

Change the db_username, db_password and admin_password values with Base64 encoding.

Save the file as keycloak-secret.yaml and apply it to the Kubernetes cluster.

kubectl apply -f keycloak-secret.yaml

3. Install Helm

If you already have helm command line tool, you don’t need to proceed with this step.
If you are a MacOS user Helm can be downloaded with HomeBrew.

brew install helm
helm init --client-only

If you are a Windows user download Helm with Helm GitHub Releases page: https://github.com/helm/helm/releases

If you are using Helm 2, you need to initialize Tiller in the Kubernetes cluster as well.

helm init --tiller-namespace kube-system --service-account tiller-sa

4. Keycloak Helm Configuration

Download the helm-values.yaml and make the following changes.

• clusterDomain: The internal Kubernetes cluster domain
• keycloak.replicas: The number of Keycloak replicas. Provide more that one replicas for High Availability configuration.
• keycloak.image.tag: The Keycloak image tag
• keycloak.username: Username for the initial Keycloak admin user
• keycloak.persistence.dbName: The name of the MySQL database to connect.
• keycloak.persistence.dbHost: The MySQL database hostname
• keycloak.ingress.enabled: If true, an ingress is created
• keycloak.ingress.hosts: a list of ingress hosts

To deploy the Helm Chart to the Kubernetes cluster,

helm repo add codecentric https://codecentric.github.io/helm-charts
helm install --name keycloak --namespace keycloak --values helm-values.yaml codecentric/keycloak

After the deployment, Keycloak will get deployed to Kubernetes in keycloak namespace.

Check Keycloak pods with the following command.

kubectl -n keycloak get pods

Check Keycloak service with the following command.

kubectl -n keycloak get services

Check Keycloak Ingresses with the following command.

kubectl -n keycloak get ingresses

Keycloak would be accessible with the keycloak.ingress.hostsprovided in the helm-values file. Ex: https://keycloak.mydomain.com. Make sure required Ingress Controllers, DNS mappings are correctly configured beforehand.

If the Ingress was disabled, use port forwarding to access Keycloak from http://localhost:8080/auth/

kubectl -n keycloak port-forward service/keycloak-http 8080:80

In the Next article let’s discuss creating a Spring Boot Application and Securing REST APIs with Keycloak user tokens and roles.

Securing Spring Boot REST APIs with Keycloak