Keycloak for Identity and Access Management & High Availability Deployment with Kubernetes
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,
- 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.
3. User Federation
Keycloak has built-in support to connect to existing LDAP or Active Directory servers.
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.
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.
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
- 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.
4. Open the Terminal and run 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.
- Make sure you have Docker installed on the laptop or server.
Follow the official documentation here: https://docs.docker.com/get-docker/
- Open the Terminal, PowerShell or Command Line and run the following command. Replace the
<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> \
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
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.
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
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
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-chartshelm install --name keycloak --namespace keycloak --values helm-values.yaml codecentric/keycloak
After the deployment, Keycloak will get deployed to Kubernetes in
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.