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
Log in the Keycloak Admin Console. Select your Realm and choose the Realm Settings option from the left menu:
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
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