Realm & Configuration Migration


Exporting and Importing Realms

Elestio enables seamless migration of Keycloak realms by supporting realm exports and imports. This capability is vital for backing up configurations, replicating environments, or transitioning between staging and production systems. The process ensures consistency across deployments while preserving all realm-level resources such as users, roles, groups, clients, and identity providers.

Key Steps for Exporting and Importing

Pre-Migration Preparation

Before initiating realm export or import, it’s essential to prepare both the source and target environments to ensure compatibility and prevent data loss:

Exporting a Realm

Keycloak provides CLI-based tools and startup parameters to export realm configurations. Elestio supports these via custom startup commands.

/opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password <your-password>
/opt/keycloak/bin/kcadm.sh get realms/<realm-name> > myrealm-export.json

This method exports the realm configuration to a JSON file.

KEYCLOAK_IMPORT=/opt/keycloak/data/import/myrealm-export.json

And use the following command:

/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/import --realm <realm-name> --users realm_file

This will export the full realm configuration including users, clients, and roles into the myrealm-export.json file.

After the export completes, use the Elestio dashboard or scp/rsync to download the exported JSON file from the container.

Importing a Realm into Elestio-Hosted Keycloak

Once the realm has been exported and downloaded, follow these steps to import it into your Elestio-hosted Keycloak instance:

KEYCLOAK_IMPORT=/opt/keycloak/data/import/myrealm-export.json

Post-Import Validation and Optimization

After importing the realm into your Elestio-hosted Keycloak instance, perform the following steps

Benefits of Using Elestio for Realm Management

Migrating from Another IAM Provider to Keycloak

Migrating to Keycloak from other IAM platforms such as Auth0, Okta, Firebase Auth, or custom-built identity solutions requires careful preparation, structured data transformation, and secure reconfiguration of users, applications, and federation protocols. This guide provides a comprehensive, command-supported migration pathway tailored for real-world deployments—especially useful in DevOps pipelines and managed hosting environments such as Elestio.

Pre-Migration Preparation

Begin by auditing your existing IAM system to determine the number of users, the complexity of roles and permissions, the use of federated identity providers (like Google or LDAP), and any custom claims or attributes associated with each user. Export the data structure if the platform supports it. For example, Auth0 offers a Management API to export users in JSON format, while Okta allows CSV exports directly from the dashboard. Firebase Auth provides CLI-based user export via the auth:export command.

Simultaneously, deploy a new Keycloak instance on your preferred infrastructure—using Docker, Kubernetes, or a managed solution. For local Docker-based testing, the following command spins up a Keycloak container:

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev

After starting the Keycloak server, access the admin console at http://localhost:8080/admin/. Create a new realm to isolate your identity configuration. In this realm, define the clients (applications), roles, and groups you plan to import or recreate based on your previous IAM structure.

User and Credential Migration

Export users from your existing IAM provider and structure the data for compatibility with Keycloak. If using Auth0, the export may look like this:

{
  "email": "jane.doe@example.com",
  "user_id": "auth0|abc123",
  "email_verified": true,
  "given_name": "Jane",
  "family_name": "Doe",
  "custom_roles": ["admin", "viewer"]
}

Transform this data into a Keycloak-compatible JSON using a script. You can use the Keycloak Admin REST API or the kcadm.sh CLI to programmatically create users. Here’s an example using kcadm.sh:

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

./kcadm.sh create users -r myrealm -s username=jane.doe \
  -s enabled=true \
  -s email=jane.doe@example.com \
  -s emailVerified=true

./kcadm.sh set-password -r myrealm --username jane.doe --new-password newPassword123!

To bulk import users, generate a JSON file with user definitions and mount it into the Keycloak container using the keycloak-config-cli. For example:

docker run --rm \
  -e KEYCLOAK_URL=http://localhost:8080 \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin \
  -v "$(pwd)/realm-config:/config" \
  adorsys/keycloak-config-cli:latest

If your previous IAM provider did not expose hashed passwords or used incompatible hashing algorithms, plan to send password reset links after user import. Alternatively, you can enforce first-login password resets using the following command:

./kcadm.sh update users/<user_id> -r myrealm -s "requiredActions=['UPDATE_PASSWORD']"

Application and Federation Migration

Next, migrate application integrations. In Keycloak, applications are known as clients. For each application that used your old IAM system, recreate a corresponding client in Keycloak. Choose the correct protocol (OpenID Connect or SAML) and configure the redirect URIs, web origins, client secrets, and access token lifetimes.

For example, to create a public OpenID Connect client:

./kcadm.sh create clients -r myrealm \
  -s clientId=my-app \
  -s enabled=true \
  -s publicClient=true \
  -s 'redirectUris=["https://myapp.com/*"]'

For third-party identity federation, use the Keycloak admin console or CLI to add identity providers. To connect Google OAuth:

./kcadm.sh create identity-provider/instances -r myrealm \
  -s alias=google \
  -s providerId=google \
  -s enabled=true \
  -s storeToken=true \
  -s "config.clientId=<GOOGLE_CLIENT_ID>" \
  -s "config.clientSecret=<GOOGLE_CLIENT_SECRET>" \
  -s "config.defaultScope=email profile"

For LDAP integration:

./kcadm.sh create user-storage -r myrealm \
  -s name=ldap \
  -s providerId=ldap \
  -s "config.connectionUrl=ldap://ldap.example.com" \
  -s "config.bindDn=cn=admin,dc=example,dc=com" \
  -s "config.bindCredential=adminpass" \
  -s "config.usersDn=ou=users,dc=example,dc=com"

For SAML-based federation, download the SAML metadata from your IdP and import it using the admin console under Identity Providers > Add provider > SAML v2.0.

Post-Migration Validation and Optimization

After users, clients, and federation setups are migrated, conduct the following checklist for validation:

Cloning a Realm to a New Cluster or Region

In scenarios where high availability, regional redundancy, or environment separation (e.g., staging to production) is required, cloning an entire Keycloak realm to a new cluster or region becomes essential. This process involves exporting the realm’s configuration and optionally user data, transferring it securely, and importing it into a fresh Keycloak instance. This guide covers all the required steps, including command-line tooling, configuration handling, and validation checks to ensure a seamless realm replication.

Pre-Cloning Preparation

Before initiating the cloning process, ensure that both the source and target Keycloak clusters are accessible and running compatible versions of Keycloak. This avoids schema mismatches and import errors. Install the Keycloak Admin CLI (kcadm.sh) and Keycloak Configuration CLI (keycloak-config-cli) on your local system or CI/CD pipeline.

Deploy a new Keycloak instance in the target cluster or region. This can be done using Docker, Kubernetes, or a managed hosting provider. Example Docker command to spin up a development instance:

docker run -d --name keycloak \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev

Ensure that network connectivity exists between your machine and the target Keycloak instance. Also, create an admin user for the new instance.

Exporting Realm Configuration from the Source Cluster

To begin the cloning process, export the realm’s full configuration (including clients, roles, groups, and optionally users) using the Keycloak Admin CLI or built-in export tools. If using the Keycloak start command with --export flag, execute:

/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users skip

To include users in the export:

/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users all

If the Keycloak instance is running in Docker:

docker exec -it keycloak /opt/keycloak/bin/kc.sh export \
  --dir /opt/keycloak/data/export \
  --realm myrealm \
  --users all

The exported realm will be saved as a JSON file, e.g., myrealm-realm.json.

Transferring Exported Data

Once exported, securely transfer the generated realm export directory or file (myrealm-realm.json) to the target cluster or region. Depending on your infrastructure, use one of the following methods:

scp myrealm-realm.json user@target-host:/tmp/

Ensure that the target Keycloak container or pod has access to the file location.

Importing Realm into the Target Cluster

To import the realm into the new Keycloak instance, use the same kc.sh tool on the target side. The import must be triggered before the Keycloak server starts. If using a container:

docker run -d --name keycloak-new \
  -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -v $(pwd)/export:/opt/keycloak/data/import \
  quay.io/keycloak/keycloak:24.0.3 \
  start-dev --import-realm

This command will initialize the new Keycloak instance with the cloned realm, including users if they were part of the original export.

Alternatively, if the server is already running, use kcadm.sh or the keycloak-config-cli for post-start import. The keycloak-config-cli is suitable for GitOps-style deployments:

docker run --rm \
  -e KEYCLOAK_URL=http://localhost:8080 \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin \
  -v "$(pwd)/myrealm:/config" \
  adorsys/keycloak-config-cli:latest

Post-Cloning Validation

After the import is complete, validate the integrity of the cloned realm with the following checks: