Best practices

November 27, 2024

Securing Applications Using Keycloak's Helm Chart

Rubaiat Hossain

Jan Lepsky

Keycloak, an open source identity and access management solution, offers single sign-on, user federation, and strong authentication for web applications and services.

Deploying Keycloak in a Kubernetes environment using Helm has several benefits:

‍

Scalability and high availability: As users or requests increase, Kubernetes can automatically scale Keycloak across multiple nodes to handle the load efficiently, ensuring consistent performance.
Simplified deployment and management: Helm handles deployment configurations through a single customizable file, drastically reducing manual configuration mistakes and making it easier to manage upgrades, rollbacks, and scaling operations.
Integration with cloud-native apps: Keycloak on Kubernetes integrates easily with other microservices, providing security and access management across your entire stack.

This tutorial guides you through installing Keycloak on Kubernetes using Helm, configuring it for secure usage, and managing users and realms through Helm.

Prerequisites

Before starting the installation process, make sure you have the following prerequisites installed on your local machine.

Kubernetes cluster: You need a running Kubernetes cluster that supports persistent volumes. You can use a local cluster, like kind or Minikube, or a cloud-based solution, like GKE or EKS.
The cluster should expose ports 80 (HTTP) and 443 (HTTPS) for external access.
Persistent storage should be configured to retain Keycloak data (*eg* user credentials, sessions) across restarts.
Nginx Ingress: An ingress controller, such as Nginx Ingress, must be installed and configured to route external traffic to Keycloak. You can deploy Nginx Ingress by following its official documentation.
Cert manager: You'll need the Let's Encrypt certificate manager installed and configured to provide secrets for TLS configurations.
kubectl: The kubectl command line interface is required to issue commands to the Kubernetes APIs. You can install Kubectl by following the official installation guide. This tutorial is tested with kubectl version 1.27.
Helm: You'll use Helm to deploy Keycloak and perform management tasks, such as creating realms and managing password policies. You can install Helm by following the official installation guide. This tutorial is tested with Helm version 3.12.1.

‍

Setting Up Keycloak Using Helm

‍

To start, you'll deploy the Keycloak stack to your local Kubernetes cluster using a Helm chart.

‍

Adding the Helm Repository

‍

First, add the Bitnami Helm repository to access the Keycloak Helm chart:

‍

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

‍

This step allows you to fetch and install the latest version of Keycloak from the Bitnami repository.

‍

Configuring the Keycloak Values File

To customize your Keycloak deployment, you need to configure the values.yaml file for the Keycloak Helm chart. This file allows you to define environment variables, ingress settings, database configurations, and resource limits for your Keycloak deployment.

‍

Create a values.yaml file and populate it with the following code snippet:

‍

keycloak:
  extraEnvVars:
    - name: KEYCLOAK_LOG_LEVEL
      value: DEBUG

  persistence:
    enabled: true  
    existingClaim: keycloak-pvc
  
  ingress:
    enabled: true
    hostname: keycloak.example.com
    ingressClassName: nginx
    path: /
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
    tls: false
  

postgresql:
  enabled: true
  postgresqlUsername: keycloak
  postgresqlPassword: keycloakpassword
  postgresqlDatabase: keycloakdb

service:
  type: NodePort
  nodePorts:
    http: 30080

readinessProbe:
  httpGet:
    path: /realms/master
    port: http
  initialDelaySeconds: 60
  timeoutSeconds: 5

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

‍

The above configuration defines the environment variable KEYCLOAK_LOG_LEVEL and sets its value to DEBUG. This enables detailed logs for any issues you may encounter during deployment. You can use environment variables like this to configure Keycloak's runtime behavior and change settings like service ports or database credentials without directly modifying the application code.

‍

It then sets up Ingress settings to expose your Keycloak service to external traffic and defines how ingress will route HTTP(S) requests to your Keycloak instance. The host name parameter specifies the domain name you'll use to access Keycloak. You can use any other domain name here, but make sure to map this URL to the external IP of your Kubernetes cluster in your DNS settings or local /etc/hosts file.

‍

The following part of the code exposes your Keycloak instance to external traffic through the domain keycloak.example.com, with Nginx as the ingress controller managing the traffic:

‍

  ingress:
    enabled: true
    hostname: keycloak.example.com
    ingressClassName: nginx
    path: /
    annotations:
      nginx.ingress.kubernetes.io/rewrite-target: /
    tls: false

‍

Keycloak stores its user data, realms, and configurations in a PostgreSQL database. It uses the postgresql block in the values.yaml file to set up this database and its credentials. The following part of the configuration enables the default database and sets up its credentials. You can use any other values for the credential:

‍

postgresql:
  enabled: true
  postgresqlUsername: keycloak
  postgresqlPassword: keycloakpassword
  postgresqlDatabase: keycloakdb
enabled: true

‍

the Helm chart installation, the enabled: true parameter enables this PostgreSQL database. You can set this to false if you have an external database or want to use a different service. In that case, you'll need to provide the connection details.

‍

In the resources section of the code, you set resource requests and limits to control the CPU and memory usage of your Keycloak deployment. This ensures that Keycloak has enough resources to run while preventing it from consuming too much of your cluster's resources:

‍

resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1"

‍

When you access Keycloak for the first time, you'll need to log in to the admin console using the administrator account user and its password. You can set the admin password when deploying the Keycloak Helm chart or let Keycloak create an autogenerated password for you.

‍

Use the second option for this tutorial to get a quick start.

‍

Deploying Keycloak Using Helm

‍

With the values.yaml file configured, you can now deploy Keycloak using Helm:

‍

helm install keycloak bitnami/keycloak -f values.yaml

‍

This command installs the Keycloak chart using the values.yaml file described above. It deploys Keycloak on your local Kubernetes cluster and creates all the necessary resources, including services, StatefulSets, and a PostgreSQL database.

‍

To verify that Keycloak is running, check the status of the pods using the following kubectl command:

‍

kubectl get pod

‍

Make sure all Keycloak-related pods are ready (*ie*, they have at least one replica) and in a running state.

‍

Accessing the Keycloak Admin Console

Once Keycloak is successfully installed on your cluster, you need to obtain the URL of the deployed Keycloak instance by logging into the admin panel.

‍

You can access Keycloak using the domain name set in the values.yaml file. However, the latest versions of the Keycloak Helm chart implement advanced SSL security checks that prevent users from logging in to the admin panel using HTTP requests to the URL.

‍

You can bypass this by using the IP address of the backend Keycloak server instead. Use the following commands to obtain this IP address:

‍

export HTTP_NODE_PORT=$(kubectl get --namespace default -o jsonpath="{.spec.ports[?(@.name=='http')].nodePort}" services keycloak)

export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath="{.items[0].status.addresses[0].address}")

echo "http://${NODE_IP}:${HTTP_NODE_PORT}/"

‍

Use the URL provided in the output to access the Keycloak admin panel. The default admin username is user. To retrieve the autogenerated password from the main Keycloak pod, use the command below, which spawns a shell inside the main pod and locates the admin password using grep:

‍

kubectl exec -it keycloak-`0 -- printenv | grep KEYCLOAK_ADMIN_PASSWORD

‍

Use these credentials to log in to the master realm, which is the default admin's realm from where you can create additional realms, security policies, users, and more.

‍

Initial Security Measures

When you're logged in to the master realm as the admin user, you can set up some initial security measures from the GUI interface. These settings will apply to all other realms and their identities.

‍

Enable SSL

Enabling SSL encrypts the data transferred between clients, such as browsers and applications, and the Keycloak server. This prevents attackers from intercepting sensitive data like – usernames, passwords, and access tokens – when users access Keycloak over the public internet.

‍

Keycloak SSl configuration

You can enable SSL by navigating to Configure > Realm settings > General. The Require SSL dropdown shows three options allowing you to configure SSL based on where the requests are coming from.

‍

Set the Require SSL option to All requests to enforce HTTPS for all connections and protect sensitive data. Use External requests if only external IPs need encryption while allowing internal access without HTTPS; avoid using None in production for security.

‍

Configure a Strong Password Policy

A strong password policy safeguards access to your business resources.

‍

The Keycloak GUI makes it very easy to configure password policies. Navigate to Configure > Authentication > Policies > Password policy and click the Add policy dropdown action.

‍

Keycloak password policy

‍

You can choose different attributes for user passwords, such as the minimum length, number of special characters and digits required, password expiry, and so on.

‍

Keycloak password policy setup

‍

Enable Account Lockout After Failed Login Attempts

‍

Setting up account lockout after a certain number of failed login attempts helps evade brute-force login attempts from malicious bots and thwarts DDoS attacks on the identity server.

‍

You can enable account lockout in Keycloak by navigating to Configure > Realm settings > Security defenses > Brute force detection and setting the desired mode from the action menu.

‍

Keycloak account lockout

‍

Creating and Managing Realms with Helm

‍

In Keycloak, a realm is a way to organize and isolate resources. It's a space where you manage users, roles, policies, and other settings specific to an application. Each realm is entirely isolated, meaning users and clients in one realm cannot access the resources of another realm. So realms allow you to isolate authentication and authorization settings for specific groups of users and applications.

‍

Once in the master realm's admin console, you can create additional realms from the GUI interface.

Creating realms through GUI

‍

However, manually creating and configuring realms through the admin console can be repetitive and time-consuming, especially in larger deployments.

‍

Helm simplifies this process by allowing you to define realms and their settings in its values.yaml file using the "keycloakConfigCli" utility. This automates the deployment process and makes it reproducible and easy to manage. You can use the `values.yaml` file to define realms, users, and other Keycloak settings.

‍

To create a new realm called "example-realm", add this configuration to your `values.yaml` file:

‍

keycloakConfigCli:
  enabled: true
  configuration:
    example-realm.json: |
      {
        "realm": "example-realm",
        "enabled": true,
        "registrationAllowed": true
      }

‍

Apply the changes directly to your Keycloak installation using the following helm command:

‍

helm upgrade --install keycloak bitnami/keycloak -f values.yaml

‍

If you log in to the Keycloak admin console again and navigate to the realm dropdown at the top left, you'll see the newly created example-realm.

‍

Creating new realm with Helm

‍

User Management Basics

User management is one of Keycloak's core features. You can either create the various users for a realm through the Keycloak GUI interface or use Helm and "keycloakConfigCli" to automatically create users, groups, and roles in your realms during deployment.

‍

By defining user configurations in the values.yaml file, you ensure that Keycloak automatically sets up your users and groups, making the process consistent and repeatable across environments.

‍

For example, if you update the keycloakConfigCli section of your values.yaml with the following code, it will create the "example-realm" alongside a user called "basicuser" and a group named "basicgroup" inside that realm:

‍

keycloakConfigCli:
  enabled: true
  configuration:
    example-realm.json: |
      {
        "realm": "example-realm",
        "enabled": true,
        "registrationAllowed": true,
        "users": [
          {
            "username": "basicuser",
            "email": "basicuser@example.com",
            "enabled": true,
            "firstName": "Basic",
            "lastName": "User",
            "credentials": [
              {
                "type": "password",
                "value": "basicpassword"
              }
            ]
          }
        ],
        "groups": [
          {
            "name": "basicgroup"
          }
        ]
      }

‍

Update the Keycloak installation to see the changes:

‍

helm upgrade --install keycloak bitnami/keycloak -f values.yaml

‍

Creating users with helm

‍

Conclusion

Congrats! You now know how to deploy and manage Keycloak on Kubernetes using Helm. You've learned how to configure Keycloak's values file, handle post-installation security measures, and automate realm and user management using the keycloakConfigCli utility and Helm.

‍

While Keycloak's Helm chart helps you efficiently deploy and manage your identity and access management (IAM) needs, managing Kubernetes applications can still be challenging, especially at scale. mogenius enables you to take care of the entire lifecycle of your Kubernetes applications – from deployment to scaling and maintenance – so you can focus on development rather than infrastructure management.

‍

Whether you use Keycloak or any other large-scale distributed application running on Kubernetes, mogenius abstracts Kubernetes complexity into easy-to-use workspaces, simplifies monitoring and maintenance, and provides seamless CI/CD pipelines to make application deployment a breeze. This reduces the need for DevOps support and increases productivity through developer self-service.

‍

Ready to get started?

Jump right in with our free plan or book a demo with a solution architect to discuss your needs.

START FOR FREE Book a demo

FAQ

What is the Keycloak Helm Chart?

The Keycloak Helm Chart is a pre-configured Kubernetes package that simplifies the deployment and management of Keycloak, an identity and access management (IAM) solution. It allows users to easily install Keycloak with predefined configurations, manage updates, and scale instances efficiently. By using Helm, administrators can automate many tasks, reducing manual setup and improving deployment consistency in Kubernetes environments.

What is the Bitnami Keycloak Helm Chart used for?

The Bitnami Keycloak Helm Chart is a popular Helm package that provides a production-ready Keycloak deployment in Kubernetes. It includes built-in configurations for security, persistence, and integration with a PostgreSQL database, making it a reliable choice for cloud-native environments. The chart is maintained by Bitnami and is regularly updated to align with the latest Keycloak versions and security best practices

How does the Codecentric Keycloak Helm Chart compare to Bitnami?

The Codecentric Keycloak Helm Chart is an alternative to the Bitnami chart, offering additional customization options tailored for enterprise use cases. While Bitnami’s chart is designed for ease of use with a standard configuration, Codecentric’s version allows deeper modifications, such as fine-tuned database settings, advanced authentication configurations, and extended integrations. Organizations that need a more tailored Keycloak setup often prefer the Codecentric chart over Bitnami’s default configuration.

How do I install Keycloak using Helm?

Installing Keycloak with Helm is straightforward and involves adding the appropriate repository and applying a values file for configuration. The standard installation command is:

helm install keycloak bitnami/keycloak -f values.yaml

This command deploys Keycloak on a Kubernetes cluster with a PostgreSQL database and the configurations defined in the `values.yaml` file. Helm simplifies the deployment process, making it easy to upgrade, rollback, or scale Keycloak instances as needed.

Why should I deploy Keycloak on Kubernetes using Helm?

Deploying Keycloak on Kubernetes using Helm provides significant advantages in scalability, automation, and maintainability. Helm enables simplified upgrades, rollback management, and easy configuration adjustments, making it ideal for dynamic, cloud-native applications. Additionally, Kubernetes ensures high availability and fault tolerance, while Helm automates complex setup processes, reducing operational overhead.

What is the difference between the Keycloak Helm Chart and Keycloak Operator?

The Keycloak Helm Chart deploys Keycloak as a Kubernetes application using predefined configurations, allowing for quick and easy setup. In contrast, the Keycloak Operator provides more advanced lifecycle management features, such as automatic scaling, self-healing, and dynamic configuration updates. Organizations with large-scale Keycloak deployments may benefit from the Operator’s automation capabilities, whereas smaller deployments may find the Helm Chart sufficient for their needs.

Interesting Reads

No items found.

Platform

Solutions

Company

Resources

Support

Securing Applications Using Keycloak's Helm Chart

Ready to get started?

FAQ

What is the Keycloak Helm Chart?

What is the Bitnami Keycloak Helm Chart used for?

How does the Codecentric Keycloak Helm Chart compare to Bitnami?

How do I install Keycloak using Helm?

Why should I deploy Keycloak on Kubernetes using Helm?

What is the difference between the Keycloak Helm Chart and Keycloak Operator?

Interesting Reads

Platform

Solutions

Company

Resources

Support

Platform

Solutions

Company

Resources

Support

Securing Applications Using Keycloak's Helm Chart

Ready to get started?

FAQ

What is the Keycloak Helm Chart?

What is the Bitnami Keycloak Helm Chart used for?

How does the Codecentric Keycloak Helm Chart compare to Bitnami?

How do I install Keycloak using Helm?

Why should I deploy Keycloak on Kubernetes using Helm?

What is the difference between the Keycloak Helm Chart and Keycloak Operator?

Interesting Reads

The latest on DevOps and Platform Engineering trends