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.
- I’m going to work with Keycloak running as a Docker service. You can learn how to run Keycloak with Docker in the Keycloak in Docker #1 – How to run Keycloak in a Docker container post. As a result of my previous work, I have two services running on my machine:
- The starting point for the work presented in this post is contained in the commit 13ff7aeebd5fdd411437d4e6d81344747d82f96b.
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
- 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 to go to the form where we’re going to provide our realm name:
As we can read in the official documentation:
The realm name is case-sensitive, so make note of the case that you use.https://www.keycloak.org/docs/latest/getting_started/index.html#creating-a-realm-and-a-user
I’m going to name my realm
efficient-mvp and provide
Efficient MVP name as a value that will be displayed to users:
Next we should define all the other settings for our realm. For instance, you can see my example
Login configuration on the image below:
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:
Remember that realm export may take some time and make the service unresponsive for other requests:
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
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:
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
Therefore, I’m going to add the volume with the realm to my
Recreate the container
Make sure that the
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:
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:
You can see the work presented in this article in the fc67a690d5898cd5ea49c7e5dced2a21790db38b commit.
Learn more on how to import a Keycloak realm
- How to run Keycloak in a Docker container
- Keycloak export and import documentation
- Importing a realm and exporting a realm chapters in the image documentaion
- KeyCloak: Display name vs HTML Display name