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

If you’re moving from one Keycloak instance to another, or if you want to share your realm with someone else, you may need to export and import your realm. In this article, we’ll explain how to export and import a Keycloak realm, step by step.

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

There are two possible strategies to export/import Keycloak Realms:

Perform a partial import/export: You can do that through the Admin Console. This kind of export does not includes Users.
Perform a full export/import: You can use the Keycloak command line ( kc.sh ) that is available in the bin folder of your installation.

Let’s see at first how to use the Admin Console.

Partial Realm Export using the Admin Console

Then, choose from the top right menu Action | Partial export. In the following UI you will be able to choose if your Realm export also includes the Groups and Roles and the Clients available in the Realm:

Click on Export to download the Realm as a JSON file.

Full Realm export using the Command Line

To fully export a Realm from the Command Line, you can use the export option in the Keycloak kc.sh tool. For example, the following command exports the Realm “demo-realm” into a file realm.json:

./kc.sh export --file realm.json --realm demo-realm

Let’s see another example. Here 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 a Realm in Keycloak

The simplest option to import a Keycloak Realm is to use the Admin Console. Choose “Create Realm”. Then, point to the location where your Realm is stored. Alternatively, paste the Realm definition file in the Resource file text area:

To import a Realm using the Command line, you can also 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. For example:

./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. For example, to import Realms from the default directory:

./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.

On the other hand, if you want to specify a file, for example in the current directory, you can use the following command:

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

Conclusion

This article was a quick walk through the import and export of Keycloak realms using the kc shell command. To learn how to import a Realm in a Docker container we recommend checking this article: How to run Keycloak with Docker