Importing and Exporting Realms

In this guide, you are going to understand the different approaches for importing and exporting realms using JSON files.

Exporting a Realm to a Directory

To export a realm, you can use the export command. Your Keycloak server instance must not be started when invoking this command.

bin/kc.[sh|bat] export --help

To export a realm to a directory, you can use the --dir <dir> option.

bin/kc.[sh|bat] export --dir <dir>

When exporting realms to a directory, the server is going to create separate files for each realm being exported.

Configuring how users are exported

You are also able to configure how users are going to be exported by setting the --users <strategy> option. The values available for this option are:

  • different_files: Users export into different json files, depending on the maximum number of users per file set by --users-per-file. This is the default value.

  • skip: Skips exporting users.

  • realm_file: Users will be exported to the same file as the realm settings. For a realm named "foo", this would be "foo-realm.json" with realm data and users.

  • same_file: All users are exported to one explicit file. So you will get two json files for a realm, one with realm data and one with users.

If you are exporting users using the different_files strategy, you can set how many users per file you want by setting the --users-per-file option. The default value is 50.

bin/kc.[sh|bat] export --dir <dir> --users different_files --users-per-file 100

Exporting a Realm to a File

To export a realm to a file, you can use the --file <file> option.

bin/kc.[sh|bat] export --file <file>

When exporting realms to a file, the server is going to use the same file to store the configuration for all the realms being exported.

Exporting a specific realm

If you do not specify a specific realm to export, all realms are exported. To export a single realm, you can use the --realm option as follows:

bin/kc.[sh|bat] export [--dir|--file] <path> --realm my-realm

Importing a Realm from a Directory

To import a realm, you can use the import command. Your Keycloak server instance must not be started when invoking this command.

bin/kc.[sh|bat] import --help

After exporting a realm to a directory, you can use the --dir <dir> option to import the realm back to the server as follows:

bin/kc.[sh|bat] import --dir <dir>

When importing realms using the import command, you are able to set if existing realms should be skipped, or if they should be overridden with the new configuration. For that, you can set the --override option as follows:

bin/kc.[sh|bat] import --dir <dir> --override false

By default, the --override option is set to true so that realms are always overridden with the new configuration.

Importing a Realm from a File

To import a realm previously exported in a single file, you can use the --file <file> option as follows:

bin/kc.[sh|bat] import --file <file>

Importing a Realm during Startup

You are also able to import realms when the server is starting by using the --import-realm option.

bin/kc.[sh|bat] start --import-realm

When you set the --import-realm option, the server is going to try to import any realm configuration file from the data/import directory. Each file in this directory should contain a single realm configuration. Only regular files using the .json extension are read from this directory, sub-directories are ignored.

For the published containers, the import directory is /opt/keycloak/data/import

If a realm already exists in the server, the import operation is skipped.

Using Environment Variables within the Realm Configuration Files

When importing a realm at startup, you are able to use placeholders to resolve values from environment variables for any realm configuration.

Realm configuration using placeholders
{
    "realm": "${MY_REALM_NAME}",
    "enabled": true,
    ...
}

In the example above, the value set to the MY_REALM_NAME environment variable is going to be used to set the realm property.