Migrate Keycloak like SQL

July 25, 2020

What is Keycloak?

Keycloak is an authorization provider that supports various authentication protocols. You can use it with OAuth, LDAP, Kerberos, etc.

It is based on the free WildFly application server.

Why is migration a Problem?

You can manage Keycloak through an admin ui, or with the provided REST-Api. Keycloak also supports realm export and import. So we could just track keycloak changes through the export file.

The difficulty of this approach is, that the realm export has to be done before starting the Keycloak server. This makes the export really difficult in some scenarios.

The realm file is also hard to manage manually because its very large and therefore confusing.

I worked on several projects with Keycloak and encountered the migration problem in every case.

What is my solution?

I wanted a migration solution like Liquibase for sql databases. With Liquibase you keep track of your migrations with migration files.

Those files are small yaml files containing incremental migrations. Those migrations are applied to the sql database and the hash of each migration, that is executed successfully is stored in the database.

Thats what I want for Keycloak. Small migration files controlled by hashes.

I can use the REST-Api to apply the migrations and store the hashes in the user attributes of the migration user.

One major drawback and I haven’t found a solution for this problem yet is that Keycloak does not support transactions.

Therefore I can’t just rollback if migration fails. My current workaround works by having a rollback action for each migration action.

Where can I find it?

I created a Github Repository keycloak_migration it is written in Kotlin and already supports some basic migrations.

At next I will add a Gradle plugin to enable the usage in a build pipeline.

There is no documentation or tests yet but I hope to get to work on this the following months.