Deploying Keycloak with SSL in just 10 minutes!

5 min readDec 21, 2021

Are you looking to dive into the world of Keycloak and establish your own Identity Provider (IdP) for testing or proof of concept purposes? The process may seem overwhelming, but fear not! In this comprehensive guide, we’ll walk you through each step with precision, enabling you to effortlessly set up and run a fully-functional Keycloak IdP.

– Background and Scope
– Prerequisites
– Certificate generation with Lets Encrypt
– Install & Configure Docker
– Keycloak server pre-configuration
– Deploying and Testing the Keycloak Server
– Appendix

Background and Scope

This article presents a comprehensive guide, drawing upon a diverse range of authoritative sources, including official documentation from Lets Encrypt, Docker, and Keycloak, as well as relevant insights from reputable blog and forum posts on platforms such as Medium and Stack Overflow.

Importantly, the instructions presented herein have been meticulously tested and validated, ensuring a successful outcome when followed diligently.

The overarching objective of this guide is to streamline the configuration process and expedite the ‘time to market’ for creating environments, such as Demonstration, Proof of Concept (PoC), or Testing

🪧 This guide was originally written in H2 2021, but updated in H1 2023.

Prerequisites

The following are prerequisites towards following this guide:

Ubuntu 20.04 or later
DNS (FQDN resolvable)
Firewall rules: 22(SSH), 443 (SSL/TLS) (80 )

Certificate generation with Lets Encrypt

On the target Keycloak host perform the following steps:

SSH to the Keycloak Server host
Run the following command to install the Letsencrypt Certbot: sudo snap install --classic certbot
Next, run the following command to ensure that the certbot command can now be run: sudo ln -s /snap/bin/certbot /usr/bin/certbot
Now run Certbot to start the certificate generation: sudo certbot certonly --standalone
Follow the on-screen instructions to generate a SSL/TLS certificate and private key.

🥉 You now have a fullchain.pem and a privkey.pem file for use with SSL/TLS

Install & Configure Docker

Set up the repository

Before installing Docker and Docker Compose the repository must be configured:

Update the apt package index and install packages to allow apt to use a repository over HTTPS:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg

2. Add Docker’s official GPG key:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

3. Use the following command to set up the stable repository:

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine with the Compose plugin

With the repository done, now install and verify Docker installation:

Update the apt package index: sudo apt-get update
Then install the latest version of Docker, Containerd and Compose:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Start Docker and (optionally) set it as a service and adding a user:

sudo systemctl start docker 
sudo useradd userName 
sudo usermod -a -G docker userName 
sudo systemctl enable docker.service 
sudo systemctl enable containerd.service

4. Ensure that Docker is now running: sudo docker version

5. Ensure Docker Compose (plugin) is installed: docker compose version

🥈 You now have a working Docker setup.

Keycloak server pre-configuration

The certificates have been generated and Docker has been installed and verified. The next step is to move the certificates, any additional configuration, and any plugin/module to a path where they can be accessed when running the solution.

Copy the certificate .pem files to a location where they can be read by Docker/Docker-Compose (observe example below)
Set and test for permissions for the above file to ensure they can be accessed: sudo chmod 655 ./certs/*

Example files and file structure

Here is an example file structure showing location of certificate files (fullchain.pem, privkey.pem).

⚠️ The Lets Encrypt are not to be renamed or converted to .crt!

├── keycloak.yml
├── certs
│   └── fullchain.pem
│   └── privkey.pem

Here is an example Docker Compose keycloak.yml (click!) for Keycloak:

version: '3'services:keycloak:
  image: quay.io/keycloak/keycloak:latest
  container_name: keycloak
  restart: always
  ports:
    - 80:8080
    - 443:8443
 
  volumes:
    - ./certs/fullchain.pem:/etc/x509/https/tls.crt"
    - ./certs/privkey.pem:/etc/x509/https/tls.key
   
  environment:
    - KEYCLOAK_ADMIN=admin
    - KEYCLOAK_ADMIN_PASSWORD=password
    - KC_HOSTNAME=fqdn
    - KC_HTTPS_CERTIFICATE_FILE=/etc/x509/https/tls.crt
    - KC_HTTPS_CERTIFICATE_KEY_FILE=/etc/x509/https/tls.key  command:
    - start-dev

Deploying and Testing the Keycloak Server

At this point, assuming all the files are in the requisite directories and adequate permissions are set you are now ready to standup and test the service!

Run Docker with Keycloak: sudo docker compose -f keycloak.yml up
To verify everything is working, open a browser and navigate to your Keycloak host using https:// e.g. https://keycloak.swjm.blog

🥇 The Keycloak main page displays without certificate errors.

Navigating to your Keycloak host over HTTPS should work without errors or warnings

Appendix

The following are some useful commands in managing the Keycloak container once deployed with Docker.

Logs
If things aren’t working, check the log with: sudo docker logs keycloak -f

List docker containers
You can list the Keycloak (and other) containers by issuing command: sudo docker ps This will also confirm container name, identifier as well as mapped ports which is useful when troubleshooting.

Attach to the Keycloak container to access file system
If you need to check something (the SSL certs?) inside the Keycloak container you can use the above list command to get the container id and then issue: sudo docker exec -it <containerId> /bin/bash

Stop Keycloak
To manually stop Keycloak you can use: sudo docker stop keycloak

Start Keycloak
Assuming you followed my guide, Keycloak will start with each host reboot. If you still need to start Keycloak you can use command: sudo docker start keycloak

Remove Keycloak
Finally, if things go wrong (don’t blame me!) you can remove the Keycloak container (after having first stopped it) using: sudo docker rm keycloak