Keycloak in Docker #2 – How to import a Keycloak realm

featured image

Having a dockerized Keycloak service that works out-of-the-box and contains an imported realm with its default users is very useful. Not only does this greatly simplify the setup process, it also allows us to share a replicable Keycloak instance with other developers.


Create a custom realm

You can skip this part, if you already have a valid json file for your realm.

First of all, we’re going to create our custom realm using the Keycloak UI. You can find some example realms in the collection of official Keycloak examples on GitHub (e.g testrealm.json) and use them as an inspiration to create yours. However, for the sake of simplicity, I’m going to:

  • run the keycloak service,
  • use the UI to create and export a simple realm,
  • destroy the containers and recreate them, but this time, with the proper realm import.

Keep in mind that not all resources can be exported with this method but it’ll be enough for this example.

Visit the http://localhost:9900/auth/ url and log in with admin credentials (keycloak:keycloak in my example). Hover the mouse over the name of the default “Master” realm in the top left corner of the page:

Add realm option in Keycloak menu

Click the Add realm option to go to the form where we’re going to provide our realm name:

Form for adding new realm

As we can read in the official documentation:

The realm name is case-sensitive, so make note of the case that you use.

I’m going to name my realm efficient-mvp and provide Efficient MVP name as a value that will be displayed to users:

General settings of a Keycloak realm

Next we should define all the other settings for our realm. For instance, you can see my example Login configuration on the image below:

Login options of a Keycloak realm

This is all I will need in my example realm. You can freely configure yours before exporting it.

Export the realm

We’re going to export our realm to a json file. Select the Export option from the side menu and choose what you want to include in the exported file:

Export realm

Remember that realm export may take some time and make the service unresponsive for other requests:

Unresponsive Keycloak while realm export

As a result, we’ll have the realm-export.json file saved on our machine. Remember the location of this file as you’ll use it to provide the volume content for our dockerized Keycloak.

Now, we can remove the containers and the database volume with the following command:

Import a Keycloak realm using a Docker volume

Right now, we have a basic realm configuration. Let’s add some default users and then recreate the kecykloak service.

Add default users

I find it helpful to keep a separate json file with default realm users stored in the project’s repository (and you can find it on the project’s GitHub page). Below you’ll see an example user Christina Travis from the list I’m going to add to the realm:

Now, we’re going to add the users list at the beginning of the relam-export.json file (users’ details are folded so that we can see the list and the start of the realm config) as you can see on the following screenshot from my IDE:

Kecyloak realm config with users

Define the volume for realm import

The image documentation tells us to use the KEYCLOAK_IMPORT environment variable to specify the realm file mounted to the /tmp directory:

keycloak image docs on importing a realm

Therefore, I’m going to add the volume with the realm to my docker-compose.yml file:

Recreate the container

Make sure that the keycloak and keycloakdb services (and their volumes) were purged from your system after you had exported your realm. Now, we’re going to recreate the containers with the following command:

You should see the Keycloak realm import info in the keycloak container logs:

Let’s visit the http://localhost:9900/auth/ url and log in with admin credentials again. This time, we can see the imported efficient-mvp realm with its test users:

Imported realm with its users

For the reference, below you’ll see where I keep my docker-compose-keycloak.yml file and how the keycloak directory looks like in my project:

directory tree for dockerized Keycloak

You can see the work presented in this article in the fc67a690d5898cd5ea49c7e5dced2a21790db38b commit.

Learn more on how to import a Keycloak realm

Photo by Blue Bird from Pexels

Leave a Reply

Your email address will not be published. Required fields are marked *