Deploying a Production-Ready Keycloak Server on GCP with Cloudflare

Keycloak, PostgreSQL, Nginx, Certbot in a Docker Compose Stack

8 min readSep 21, 2024

Deploying a Production-Ready Keycloak Server on GCP with Cloudflare

Introduction

Keycloak is an open-source tool that makes it easy to add login and user access features to your applications. You don’t need to worry about storing or authenticating users yourself. Keycloak handles it for you. It also offers helpful features like connecting to other user databases, multi-factor authentication, and managing users and their permissions. In this guide, we’ll show you how to set up Keycloak on GCP and protect it using Cloudflare.

How Keycloak Works?

Keycloak acts as a secure intermediary between users and applications, managing authentication. When a user tries to access an application, they are redirected to Keycloak, where they log in. If the credentials are valid, Keycloak generates a token and redirects the user back to the application for access. If invalid, an error is shown. Keycloak simplifies authentication and supports modern protocols like OAuth2 and OpenID Connect.

Why Use Keycloak?

Keycloak provides a centralized solution for managing authentication and authorization, making it easier to secure applications. It offers features like Single Sign-On (SSO), user federation, social login integration, and multi-factor authentication. With Keycloak, applications can delegate authentication, reducing security risks and simplifying user management. It supports modern protocols like OAuth2 and OpenID Connect, making it compatible with various platforms and easy to integrate into both web and mobile applications.

Use Cases:

1. Single Sign-On (SSO): Keycloak allows users to log in once and access multiple applications without needing to authenticate again, enhancing user experience.

2. User Federation: It integrates with existing user directories like LDAP or Active Directory, enabling centralized user management for organizations.

3. Social Login: Keycloak supports social identity providers like Google, Facebook, and GitHub, allowing users to log in with their existing social accounts.

4. API Security: By using OAuth2 and OpenID Connect, Keycloak secures APIs, handling authentication and access control across distributed services.

5. Multi-Factor Authentication: It enables organizations to enforce an additional layer of security by requiring multi-factor authentication (e.g., OTP, email verification).

6. Microservices Architecture: Keycloak can manage authentication for microservices, ensuring consistent and secure access control across services.

Prerequisites

A Google Cloud Platform (GCP) account with billing enabled
Basic familiarity with GCP Console and cloud computing concepts
A domain name that you own and can manage
A Cloudflare account for managing your domain and providing additional security
Basic understanding of Docker and containerization concepts

Setting Up Your Environment

Step 1: Creating and Configuring the VM on GCP: A virtual machine on Google Cloud Platform (GCP) and configured with open ports (80 and 443).

Before starting, ensure you have a virtual machine (VM) set up on Google Cloud Platform (GCP). The key requirement for this setup is that your VM must have ports 80 and 443 open to allow HTTP and HTTPS traffic. These open ports are crucial for the proper functioning of Keycloak and its secure communication. We’re using an Ubuntu 22.04 LTS-based VM for this guide, but the specific machine type isn’t critical as long as it meets the basic requirements for running Keycloak and has the necessary ports configured.

The following are the current specifications for our VM setup:

Machine type: e2-medium (2 vCPU, 4 GB memory)
Zone: me-central1-b
OS: Ubuntu 22.04 LTS (jammy)
Boot disk: 20 GB balanced persistent disk
Network: 
 - External IP: Ephemeral
 - Network tags: http-server, https-server
 - Firewalls: HTTP and HTTPS traffic allowed
VM provisioning model: Spot VM
Security:
 - Shielded VM with vTPM and Integrity Monitoring enabled
 - SSH access configured
Service account: Compute Engine default service account

Note that this is a Spot VM instance, which may be terminated at any time by GCP, and it uses an ephemeral external IP that may change if the instance is stopped and started.

The Public External IP Server for the VM

Note that this is a Spot VM instance, which may be terminated at any time by GCP. The external IP (34.18.8.227) is ephemeral and may change if the instance is stopped and started. Keep this in mind when configuring your Keycloak server and any services that need to connect to it.

Finally, check reachability by pining the domain

Step 2: Configuring Your Domain with Cloudflare: A domain name properly configured to point to your server.

To set up your domain, you’ll need a valid domain name registered with a domain registrar. Once you have your domain, add it to Cloudflare as shown in the image below:

After adding your domain to Cloudflare, create an A record that points to your VM’s public IP address. It’s crucial to set Cloudflare to “DNS only” mode for this record by ensuring the proxy is turned off (the cloud icon should be grey, not orange). This configuration allows direct communication with your server. The following image illustrates the correct Cloudflare DNS settings for your reference:

Cloudflare DNS settings showing the A record configuration with the proxy turned off

Don’t forget to update your domain’s nameservers to use Cloudflare’s nameservers, completing the setup process.

Step 3: Setting Up Docker on Your Server

If you haven’t already installed Docker Engine and Docker Compose on your server, follow these steps:

Update your package list:

sudo apt update

2. Install prerequisites:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

3. Add Docker’s official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg - dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

4. Set up the Docker repository:

echo "deb [arch=$(dpkg - print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. Update the package list again:

sudo apt update

6. Install Docker Engine:

sudo apt install -y docker-ce docker-ce-cli containerd.io

7. Add your user to the docker group (to run Docker without sudo):

sudo usermod -aG docker $USER

8. Install Docker Compose:

sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

9. Verify the installations:

docker - version
docker-compose - version

Docker and Docker Compose version commands and their output

After completing these steps, log out and log back in for the group changes to take effect.

If you prefer to use a script for installation, you can use the following:

#!/bin/bash

# Update the apt package index
sudo apt-get update

# Install packages to allow apt to use a repository over HTTPS
sudo apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Set up the stable repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Update the apt package index (again)
sudo apt-get update

# Install Docker Engine
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

# Add your user to the docker group to run Docker without sudo
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

echo "Docker and Docker Compose have been installed. Please log out and log back in for the group changes to take effect."

Always review scripts before running them, especially when they require sudo privileges.

Step 4: Setting Up Keycloak on Production Mode:

Once you’re logged into your GCP VM and Docker is installed, follow these steps to clone the Keycloak repository, configure it, and run the Docker containers.

1. Clone the Keycloak Production Repository

Run the following commands to clone the repository:

# Clone the Keycloak production repository
git clone https://github.com/anqorithm/keycloak-production.git
cd keycloak-production

2. Configure Environment Variables Using `vim`

Next, configure the .env file to set up your domain and SSL email:

# Copy the example environment file
cp .env.example .env
# Open the .env file with vim
vim .env

Once the .env file is open in vim, make the following changes:

Set your domain name:

KEYCLOAK_DOMAIN=sso.anqorithm.com

Set your email for SSL registration:

CERTBOT_LETSENCRYPT_EMAIL=abdullah@anqorithm.com

To save and exit vim, type :wq and hit Enter.

3. Run the SSL Setup

Now, set up SSL certificates for your domain by running the following command:

docker compose -f docker-compose-ssl.yml up -d

Generate SSL Certificate through Certbot

This command will launch Nginx and Certbot to request and install SSL certificates for your domain. Once the SSL certificates are successfully obtained, stop the containers:

docker compose -f docker-compose-ssl.yml down

4. Start the Docker Containers

After configuring SSL, start the full stack (Keycloak, PostgreSQL, Nginx, and Certbot) using Docker Compose:

docker compose up -d

This will launch all services in detached mode (-d).

5. Verify the Setup

To check if the containers are running, use:

docker ps

You should see the nginx, keycloak, postgres, and certbot containers running.

6. Access Keycloak

You can now access Keycloak by visiting your domain in a web browser:

https://sso.anqorithm.com

Login to the Portal using the admin/admin Credentials

This step guides you through cloning the project, configuring the environment, and running the containers for the Keycloak setup.

GitHub Repository

You will find the source code for this article in the following GitHub repository

https://github.com/anqorithm/keycloak-production

Resources

Google Cloud Platform (GCP): https://cloud.google.com/
Cloudflare: https://www.cloudflare.com/
Keycloak: https://www.keycloak.org/
Docker: https://www.docker.com/
Docker Compose: https://docs.docker.com/compose/
Ubuntu: https://ubuntu.com/