Keycloak realm import strategy – OVERWRITE_EXISTING vs IGNORE_EXISTING

Getting advice
,
1

Hi all,

I’ve been using Keycloak for several years, and up until now I’ve always relied on the
OVERWRITE_EXISTING realm import strategy.
The main reason was consistency across environments — every deploy results in an identical realm state, no manual UI configuration, no drift, and no human errors.
All configuration lives in realm JSON, and this has worked well for DEV / STAGING / PROD.

I also use custom user federation, so no local users are stored in Keycloak, which made this approach feel safe and clean.

However, I recently ran into a problem with MFA:

  1. When a user configures MFA
  2. Keycloak is redeployed
  3. Realm is re-imported using OVERWRITE_EXISTING
  4. The user is forced to set up MFA again on next login.

From what I understand, this happens because OVERWRITE_EXISTING → MFA secrets and required-action state are stored as Keycloak-managed credentials, and realm overwrite removes them — even for federated users.

Now I’m considering switching to IGNORE_EXISTING if necessary and I wanted to ask the community:

  1. Which realm import strategy do you use in production and why?
  2. Does Keycloak recommend a preferred strategy?
  3. How do you balance configuration consistency?
  4. How do you rollback changes if something was wrong configured on UI?
    Enable events and track what was changed?

Thanks!

2

Keycloak’s im-/export functionality is not meant for being used as kind of configuration as code. As you experienced, it’s an “all or nothing” operation with OVERWRITE_EXISTING vs. IGNORE.
The im-/exports of a Keycloak realm is more a tool for something like “I want to port a dedicated state from one environment to another” to investigate in some behavior or to port it to a different environment in terms of a migration (e.g. migration of database).

To achieve consistency across environments, what I read from your post is your goal, I strongly recommend to use something like the official Keycloak Terraform provider [1], Keycloak Config CLI [2], Keycloak Ansible Collection [3] or similar projects.
The Terraform provider is maintained directly by the Keycloak team/project, the other ones are community projects.

[1] Terraform Registry
[2] GitHub - adorsys/keycloak-config-cli: Import YAML/JSON-formatted configuration files into Keycloak - Configuration as Code for Keycloak.
[3] GitHub - ansible-middleware/keycloak: Collection to install and configure Keycloak or Red Hat Single Sign-On / Red Hat Build of Keycloak

1 Like
3

Thanks @dasniko for answer!

I start considering and getting know with Terraform, do you have some example of using it in your work?
Is this should be separated form my repo where I define all my extensions or I can keep it in the same place?

Tnx,
Djordje

4

I’ve no real examples available from a real-life project, but in my KC training repository, there are some example resources: keycloak-workshop/terraform at main · dasniko/keycloak-workshop · GitHub

I recommend to read the official Terraform documentation. It’s possible to import an existing realm as a state and also to transform this state into the .tf file format. Documentation and also some AI advice (use carefully! and use it as some kind of support, don’t let do AI all of your stuff!) can be of good help.

The answer to the question to where to maintain the TF resources depends on your overall repository/project/resource structure. I’m a big fan of having as most as possible resources in one repository, but I know others who are happy to have it distributed across several repos. Distributing it may introduce more complexity to your deployment pipelines, but on the other hand may also give you more flexibility. As always, it’s a trade-off. :wink:

1 Like