How to export and import Realms in Keycloak

This article discusses about Importing and Exporting Keycloak Realms using the latest product distribution which runs on a Quarkus runtime.

Realm Set up

Firstly, if you are new to Keycloak and Quarkus, we recommend checking this article which covers the basics: Getting started with Keycloak powered by Quarkus

A Keycloak Realm is a space where you manage objects, including users, applications, roles, and groups. A user belongs to and logs into a realm. In order to test Realm export/import we will at first create the wildfly-realm.

Use the following batch script in order to create it:

./kcadm.sh config credentials --server http://localhost:8180 --realm master --user admin --password admin

./kcadm.sh create realms -s realm=wildfly-realm -s enabled=true -o

./kcadm.sh create users -r wildfly-realm -s username=customer-admin -s enabled=true

./kcadm.sh set-password -r wildfly-realm --username customer-admin --new-password admin

./kcadm.sh create clients -r wildfly-realm -s clientId=customer-manager-client -s publicClient="true"  -s "redirectUris=[\"http://localhost:8080/*\"]" -s enabled=true

./kcadm.sh create roles -r wildfly-realm -s name=customer-manager

./kcadm.sh add-roles --uusername customer-admin --rolename customer-manager -r wildfly-realm

In the next paragraphs, we will show how to export and import the wildfly-realm.

Exporting a Keycloak Realm

To export a Realm, you can use the export option in the Keycloak shell tool. In this example, we are exporting the wildfly-realm into the directory data/import from the root of your installation:

./kc.sh export --realm wildfly-realm --dir ../data/import

A file <RealmName>-realm.json is now available under the Keycloak_HOME/data/import:

To import the Realm, there are several options available. Let’s see them in detail.

Importing the Realm in a running keycloak server

To import a Realm into a Running Keycloak server, use the import option of the kc shell command. You can either pass as argument a directory:

./kc.sh import --dir  ../data/import

The above example will import all Realms available in that dir. You can also import a realm from a single file as follows:

./kc.sh import --file  ../data/import/wildfly-realm-realm.json

Importing a Realm at Start up

Finally, you can also import the Realm at start up time by adding the –import-realm option to your start command:

./kc.sh start-dev --http-port=8180 --import-realm

You should be able to see in the server start up logs the following message:

2022-06-24 11:28:48,986 INFO  [org.keycloak.services] (main) KC-SERVICES0004: Imported realm wildfly-realm from file /home/jboss/keycloak-18.0.1/bin/../data/import/wildfly-realm-realm.json.

Conclusion

This article was a quick walk through the import and export of Keycloak realms using the kc shell command.