Keycloak Backup and Restore

Follow up on my keycloak blogs about

• Running Keycloak in Docker with an external DB
• Run Keycloak locally with Docker compose
• backup and restore Keycloak

In this document, I’d like to show you how you can backup and restore Keycloak

Design

Keycloak Backup has two parts:

• Backing up its realm
• Backing up its database

The design should be suitable for any platforms, that we run keycloak in standalone Virtual machine, kubernetes cluster, on AWS/Azure Clouds, or on-promise.

Todo list

I haven’t yet figured out how to automate the backup of its realm using scripts, allowing me to schedule a daily cronjob from a virtual machine. I’ll address and update this part later.

Backing up the realm

A Keycloak realm is a container for a set of users, credentials, and authentication mechanisms, as well as a set of applications or services that use those credentials. In Keycloak, a realm represents a security administrative domain where you can define your identity and access management configurations. Realms are often used to isolate different applications or services, each with its own set of users, roles, and authentication settings.

Within a Keycloak realm, you can define users, groups, roles, and various authentication flows. It allows you to manage access control and security policies for your applications or services. Realms provide a way to organize and secure different parts of your system, ensuring that users and services within a realm are isolated from those in other realms.

I prefer to back up each realm separately, generating distinct output files for each. This way, I can easily restore a specific realm without the need to restore all realms simultaneously.

1. Connect to the Keycloak pod (This step is optional. If you have installed Keycloak directly on the host, you can skip this.)

$ kubectl exec -it $KEYCLOAK_POD -- /bin/bash

2. Run Keycloak with the arguments below to export the realm. For example, the realm name is project-x

bash-5.1$ export KC_DB=postgres
bash-5.1$ /opt/keycloak/bin/kc.sh export --file /tmp/realm-master.json --realm master
bash-5.1$ /opt/keycloak/bin/kc.sh export --file /tmp/realm-project-x.json --realm project-x

export KC_DB=postgres is so important; it took me over two months to achieve a successful realm backup.

with above commands, you can backup the realm (master, and project-x) , but the output backup files are still in keycloak pod. We need copy them out.

3. Copy the files to your local host and subsequently upload them to an Azure Storage account or another designated location for backup.

$ kubectl cp $KEYCLOAK_POD:/tmp/realm-master.json realm.json
$ kubectl cp $KEYCLOAK_POD:/tmp/realm-project-x.json realm-project-x.json

# then recommend to upload the files to Azure Storage accounts

Restore realm for Keycloak

Restore is simple, similar as backup. Make sure you have copied the realm file into Keycloak pod.

bash-5.1$ export KC_DB=postgres
bash-5.1$ /opt/keycloak/bin/kc.sh import --file /tmp/realm.json --override=true

Backing up the database

Keycloak uses a PostgreSQL database that can be backed up using pg_dump

This can be done using the following command:

# suppose the DB connection string has been saved in Azure Key/Vault
export PG_CONNECTION_STRING=$( az keyvault secret show --vault-name project-x-secret --name psql_connection_string --query value -o tsv )
pg_dump --dbname=${PG_CONNECTION_STRING}" > database-keycloak.sql

Restore database for keycloak

Follow the postgresql official document to restore Postgresql database.

Reference

Keycloak backup and restore — kdb products

Learning is fun

# kubernetes # Keycloak # docker # Azure # AWS # Cloud # DevOps # Best Practices # SecOps