What Is a Realm Export?

Export is the operation of writing out a Realm’s entire configuration — its Clients, Roles, Authentication Flows, Identity Providers, Groups, and (optionally) its Users — into a structured file, most commonly formatted as JSON, a widely used, human-readable text format for representing structured data. That file becomes a complete, self-contained snapshot of the Realm as it existed at the moment of export.

What Is a Realm Import?

Import is the reverse operation: reading a previously exported file back into a Keycloak server, recreating either a brand-new Realm from scratch, or updating pieces of an existing one, using the file’s contents as the source of truth for how that Realm should be configured.

Why This Capability Exists

Manually recreating a Realm’s dozens of Clients, Roles, and carefully tuned Authentication Flows by clicking through the Admin Console every time a new environment is needed is slow, error-prone, and produces subtly different results each time a human repeats it by hand. Export/Import exists to make a Realm’s configuration something that can be captured once, reviewed, stored, and reliably reproduced — turning identity configuration into something closer to ordinary software, rather than a one-off manual artifact living only in one administrator’s memory of what they clicked.

Client Secrets Are Included in Plain Text

A Confidential Client’s secret, covered elsewhere in this series’ guide to Client Authentication Methods, is written directly into the export file as plain, readable text. This means an export file is, functionally, a sensitive credential store in its own right, and needs to be handled with exactly the same care as any other file containing production secrets.

User Passwords Are Hashed, Not Reversible

When Users are included in an export, their passwords are exported in their already-hashed form — the same one-way, non-reversible representation Keycloak stores internally — rather than as plain text. This means an export doesn’t expose actual user passwords, though it’s still sensitive personal data deserving careful handling in its own right.

A Common Real-World Pattern: Export, Redact, Then Store

Many organizations address this by exporting, then deliberately stripping or replacing sensitive fields like Client secrets with placeholder values before the file is committed anywhere for version-controlled reuse, re-injecting real secrets separately at import time through an external secrets-management process rather than storing them inside the file itself.

Identity Provider Credentials Deserve the Same Treatment

Client secrets aren’t the only sensitive material an export can carry. Identity Brokering configuration, covered elsewhere in this series, often includes a client secret issued by the external Identity Provider itself, alongside whatever signing or encryption keys a SAML-based broker configuration might reference. Each of these deserves the exact same redaction discipline as a Client secret — a thorough security review of an export file checks every credential-shaped field, not only the most obvious one.

Exporting a Realm From the Admin Console

Inside a Realm’s own settings, an Export action produces a downloadable JSON file representing a partial export of that Realm’s current configuration, with optional checkboxes to include Groups and Users if a fuller snapshot is needed for this particular export.

Importing a Realm From the Admin Console

From the Realm selection screen, an administrator can choose to create a new Realm by directly uploading a previously exported JSON file, rather than configuring every setting by hand — Keycloak reads the file and recreates the entire Realm’s configuration from it in one operation.

Why a Separate Tool Exists

A full export of a Realm with a very large number of Users can be a substantial operation, and running it through the same live server handling ordinary authentication traffic risks impacting performance for real users during the export. Keycloak’s standalone export/import tooling is designed to run this kind of full, potentially large-scale operation directly against the underlying data, independent of the ordinary running server process.

Scripting Repeatable Operations

Because this tooling is invoked from the command line rather than clicked through manually, it fits naturally into automated scripts and scheduled jobs — a nightly full-export job feeding into an organization’s broader backup process, for instance, running unattended without requiring an administrator to remember to click through the Admin Console every time.

How It Works

Keycloak can be configured to automatically import one or more Realm files the moment the server itself starts up, rather than requiring any manual action after the server is already running. This is especially valuable in containerized deployments, where a fresh Keycloak container can come up already fully configured with its intended Realms, Clients, and Roles, entirely from files bundled alongside the deployment itself.

Merge Behavior, Not a Clean Overwrite

Importing into an already-existing Realm generally merges the file’s contents into what’s already there, rather than deleting everything first and starting fresh. Existing objects matching something described in the file are typically updated to match, while objects entirely unmentioned in the file are generally left untouched, though the precise behavior can vary depending on the specific import method and configuration used.

Why This Matters for Ongoing Environment Synchronization

Teams relying on repeated imports to keep an environment’s configuration aligned with a version-controlled source file need to understand this merge behavior clearly — configuration drift introduced through manual Admin Console changes made directly against a target environment won’t automatically be corrected by a subsequent import, unless that drift happens to be explicitly overwritten by something the file itself also describes.

What Genuinely Gets Removed on Import

It’s worth being precise about the boundary here rather than treating merge behavior as an all-or-nothing rule. A field that exists in the file and already exists on the target is generally updated to match the file’s value exactly. An object entirely described by the file but that already exists on the target under the same identifier is generally replaced with the file’s version of it. What generally survives untouched is an object that exists on the target but has no corresponding entry in the file at all — a Client an administrator created directly against the target environment after the file was last captured, for instance, is a common example of something an import typically leaves alone rather than removing.

Initial Configuration. A Realm is built up through the Admin Console, the REST Admin API, or an earlier import, reaching a state worth capturing and reusing.

Export. The Realm is exported, choosing full or partial scope depending on the intended purpose, as covered in Chapter 5.

Secret Handling. Sensitive fields are reviewed and, commonly, redacted or externalized before the file is stored anywhere long-lived, as covered in Chapter 4.

Storage. The resulting file is stored — in version control for configuration promoted between environments, or in a secured backup location for disaster-recovery purposes.

Import. The file is imported into its target — a fresh environment, a new Realm clone, or a startup-time provisioning process — recreating the captured configuration there.

Drift Management. Over time, the target environment may accumulate its own changes; a deliberate process for re-exporting and re-synchronizing keeps environments meaningfully aligned rather than silently diverging.

graph LR
    A["Realm Configured"] --> B["Exported
(Full or Partial)"]
    B --> C["Secrets Reviewed
& Redacted"]
    C --> D["Stored
(Version Control / Backup)"]
    D --> E["Imported Into Target"]
    E --> F["Ongoing Drift
Managed & Re-synced"]
    F --> B
    

Import as a Privileged Operation

Because an import can create Clients, assign Roles, and configure Identity Providers, the ability to perform an import is itself a highly privileged capability, deserving the same restriction and audit trail as any other administrative action covered elsewhere in this series’ discussion of Realm administration.

Validate Untrusted Import Files Before Use

An import file received from outside a fully trusted source — a vendor-provided template, for instance — deserves careful review before being imported, since a maliciously crafted file could introduce an unexpected Identity Provider, an unexpected administrative Role assignment, or other configuration a team wouldn’t have knowingly approved.

Least-Privilege Access to Export Files Themselves

Beyond who is allowed to perform an import, it’s worth separately restricting who can even read an already-produced export file, given the plain-text secrets it may contain, as covered in Chapter 4. Storage locations for these files — whether a version-control repository, a backup archive, or a shared drive — deserve access controls scoped as narrowly as the sensitivity of their contents actually warrants, rather than being left as broadly readable as an organization’s more routine, non-sensitive documentation.

Good Patterns

• Use partial exports for configuration promotion between environments, and full exports specifically for genuine disaster-recovery backups
• Redact or externalize secrets before storing any export file long-term or in version control
• Use startup-time import for reproducible environment provisioning, particularly in containerized deployments
• Understand merge behavior explicitly before relying on import to synchronize an already-existing environment, verifying the actual resulting state rather than assuming a clean reset occurred

Anti-patterns to Avoid