Alauda Application Services Identity Management E1

Import and Export

Keycloak supports importing and exporting Realm configurations for backup, migration, and environment replication purposes.

TOC

Export MethodsExport via Admin Console (Partial Export)Export via CLI (Full Export)Export via REST APIImport MethodsImport via KeycloakRealmImport CRD (Recommended for Initial Setup)Import via CLI (Startup Import)Import via Admin ConsoleMigration Between Environments

Export Methods

Export via Admin Console (Partial Export)

  1. In the Admin Console, select the target Realm.
  2. Go to Realm Settings > Action menu (top right) > Partial export.
  3. Select what to include:
    • Groups and related roles
    • Clients
    • Roles
  4. Click Export.
  5. A JSON file is downloaded containing the selected Realm configuration.
Partial Export Limitations

Partial export does not include user data, secrets, or credentials. It exports only the structural configuration (clients, roles, groups, authentication flows, etc.).

Export via CLI (Full Export)

For a full export including users and credentials, use the Keycloak CLI export command. In a Kubernetes environment, run this as a Job or exec into a Pod:

# Exec into the Keycloak Pod
kubectl exec -it <keycloak-pod> -n <namespace> -- \
  /opt/keycloak/bin/kc.sh export \
    --dir /tmp/export \
    --realm <realm-name> \
    --users realm_file

Export options:

OptionDescription
--dir <path>Output directory for the export files
--file <path>Output to a single file (alternative to --dir)
--realm <name>Export a specific realm (omit to export all realms)
--users realm_fileInclude users in the realm export file
--users same_fileInclude users in the same file (for single-file export)
--users skipExclude users from the export
--users different_filesExport users to separate files (for large user sets)
Server Restart Required

The Keycloak CLI export command requires the server to be stopped or run in a special export mode. In Kubernetes, this is best done as a one-off Job or by scaling down the deployment, running the export, and scaling back up. Alternatively, use the Admin REST API for live exports.

Export via REST API

Use the Admin REST API for live, non-disruptive partial exports:

# Export a realm (does not include secrets or user credentials)
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>" | jq . > realm-export.json

# Export users
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/users?max=1000" | jq . > users-export.json

# Export clients
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://<keycloak-host>/admin/realms/<realm>/clients" | jq . > clients-export.json

Import Methods

The KeycloakRealmImport CRD is the preferred method for initial Realm provisioning in Kubernetes deployments. See Manage Realms for details.

apiVersion: k8s.keycloak.org/v2alpha1
kind: KeycloakRealmImport
metadata:
  name: my-realm-import
spec:
  keycloakCRName: example-kc
  realm:
    # Full realm JSON embedded here
KeycloakRealmImport Is a One-Shot Import

The KeycloakRealmImport CRD performs a one-time import when the resource is created. It is not a continuous synchronization controller — subsequent changes made via the Admin Console or REST API are not reflected back to the CR, and updating the CR does not automatically re-apply changes to an existing Realm.

Specifically:

  • It creates a new Realm at import time. If a Realm with the same name already exists, the import will not overwrite or update the existing Realm.
  • It does not track or reconcile ongoing Realm state.
  • Modifying the CR after the initial import does not trigger a re-import automatically.
  • It does not delete Realms or Realm objects — it is a create-only mechanism.
  • It should not be relied upon as a full lifecycle management or GitOps sync mechanism.

For ongoing Realm configuration changes after initial import, use the Admin Console or Admin REST API.

Import via CLI (Startup Import)

Place export files in a directory and configure Keycloak to import on startup:

kubectl exec -it <keycloak-pod> -n <namespace> -- \
  /opt/keycloak/bin/kc.sh import \
    --dir /tmp/export \
    --override true
OptionDescription
--dir <path>Directory containing export files to import
--file <path>Import from a single file
--override trueOverwrite existing realm configuration if the realm already exists

Import via Admin Console

  1. Go to Create Realm (top-left dropdown > Create Realm).
  2. Click Browse and select a realm export JSON file.
  3. Click Create.

This method creates a new realm from the JSON file. It does not merge into existing realms.

Migration Between Environments

To replicate a Keycloak configuration from one environment to another:

  1. Export the realm from the source environment (using partial export or REST API).
  2. Review and sanitize the export:
    • Remove environment-specific URLs and hostnames.
    • Remove or replace client secrets (use KeycloakRealmImport placeholders for secrets).
    • Update redirect URIs to match the target environment.
  3. Import into the target environment using the KeycloakRealmImport CRD.

For migration from Red Hat Single Sign-On, see Migrate from RH-SSO.