122 lines
No EOL
5.6 KiB
Text
122 lines
No EOL
5.6 KiB
Text
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
<#import "/templates/links.adoc" as links>
|
|
|
|
<@tmpl.guide
|
|
title="Importing and Exporting Realms"
|
|
summary="An overview about how to import and export realms">
|
|
|
|
In this guide, you are going to understand the different approaches for importing and exporting realms using JSON files.
|
|
|
|
== Providing options for database connection parameters
|
|
|
|
When using the `export` and the `import` commands below, Keycloak needs to know how to connect to the database where the information about realms, clients, users and other entities is stored.
|
|
As described in <@links.server id="configuration"/> that information can be provided as command line parameters, environment variables or a configuration file.
|
|
Use the `--help` command line option for each command to see the available options.
|
|
|
|
Some of the configuration options are build time configuration options.
|
|
As default, Keycloak will re-build automatically for the `export` and `import` commands if it detects a change of a build time parameter.
|
|
|
|
If you have built an optimized version of Keycloak with the `build` command as outlined in <@links.server id="configuration"/>, use the command line option `--optimized` to have Keycloak skip the build check for a faster startup time.
|
|
When doing this, remove the build time options from the command line and keep only the runtime options.
|
|
|
|
== 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.
|
|
|
|
<@kc.export parameters="--help"/>
|
|
|
|
To export a realm to a directory, you can use the `--dir <dir>` option.
|
|
|
|
<@kc.export parameters="--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`.
|
|
|
|
<@kc.export parameters="--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.
|
|
|
|
<@kc.export parameters="--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:
|
|
|
|
<@kc.export parameters="[--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.
|
|
|
|
<@kc.import parameters="--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:
|
|
|
|
<@kc.import parameters="--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:
|
|
|
|
<@kc.import parameters="--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:
|
|
|
|
<@kc.import parameters="--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.
|
|
|
|
<@kc.start parameters="--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. Only regular files using the `.json` extension are read from this directory, sub-directories are ignored.
|
|
|
|
NOTE: For the https://quay.io/keycloak/keycloak[published containers], the import directory is `/opt/keycloak/data/import`
|
|
|
|
If a realm already exists in the server, the import operation is skipped. The main reason behind this behavior is to avoid re-creating
|
|
realms and potentially loose state between server restarts.
|
|
|
|
To re-create realms you should explicitly run the `import` command prior to starting the server.
|
|
|
|
Importing the `master` realm is not supported because as it is a very sensitive operation.
|
|
|
|
=== 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
|
|
[source, bash]
|
|
----
|
|
{
|
|
"realm": "${r"${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.
|
|
|
|
</@tmpl.guide> |