Skip to main content

Keycloak Configuration as Code with Terraform

There are two ways to manage Keycloak configuration as code, and they are not alternatives — they do different jobs:

  1. The Terraform provider (keycloak/keycloak) manages a realm continuously. It detects when someone changes a setting in the admin console and puts it back.
  2. Realm JSON import (--import-realm) creates a realm once, at first boot. It has no update path that is not a delete and recreate.

Use Terraform for anything that will be changed again. Use realm JSON to bootstrap an empty server — a CI job, a dev container, a new cluster — and then hand the realm to Terraform.

Everything below was run against a real server. The parts that surprised us: a service-account client that returns 401 on every Admin API call until you attach one client scope, a terraform apply that cheerfully leaves a client someone added by hand in place forever, and a kc.sh import whose default is to delete the realm and every user in it first.

Tested against

Keycloak 26.8.2 (quay.io/keycloak/keycloak:26.8.2 start-dev), Terraform 1.17.2, and the keycloak/keycloak provider 5.10.0 on a 2-vCPU host. Every command, log line, error message and timing below is copied from a run on 2026-11-16.

The reference pages are Keycloak's Importing and exporting realms and the provider's registry documentation. Both are accurate. Neither tells you which of the two to reach for, what each one stops noticing, or what the defaults destroy.

Which Terraform provider, and why most examples are wrong​

Nearly every blog post and Stack Overflow answer about Terraform and Keycloak starts with this:

# Do not use this.
keycloak = {
source = "mrparkers/keycloak"
}

That namespace is frozen. The repository was transferred to the Keycloak organisation — github.com/mrparkers/terraform-provider-keycloak now redirects to github.com/keycloak/terraform-provider-keycloak, same repository ID — but the Terraform Registry treats a namespace as permanent, so the old listing stayed where it was:

Registry sourceLatest versionPublished
mrparkers/keycloak4.4.02024-01-08
keycloak/keycloak5.10.02026-10-05

Pinning mrparkers/keycloak gives you a provider that predates most of what is in Keycloak 26. Change the source, delete .terraform.lock.hcl, and re-run terraform init. The resource names did not change, so in most configurations that is the whole migration.

The provider's own README states it supports the latest three minor versions of Keycloak, and 5.10.0's acceptance tests run against 26.8.0 down to 26.2.5. Older servers often work; they are not tested.

Give Terraform its own credential​

Do not point Terraform at admin-cli with your admin password. It is a human's password in a CI variable, it has no audit identity of its own, and admin-cli is a client many people disable on a production realm.

Create a dedicated client with a service account instead. Start a server:

docker rm -f kc 2>/dev/null
docker run -d --name kc --memory 1536m -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
quay.io/keycloak/keycloak:26.8.2 start-dev

Then bootstrap the credential. This is the one piece of imperative setup you cannot avoid — Terraform needs an account before it can manage anything:

KC="docker exec kc /opt/keycloak/bin/kcadm.sh"

$KC config credentials --server http://localhost:8080 \
--realm master --user admin --password admin

# A dedicated client for Terraform: service account, no browser flows.
$KC create clients -r master \
-s clientId=terraform \
-s enabled=true \
-s publicClient=false \
-s standardFlowEnabled=false \
-s serviceAccountsEnabled=true

CID=$($KC get clients -r master -q clientId=terraform --fields id --format csv --noquotes)

# Required on Keycloak 26.8.2 and later. Without this scope every Admin REST
# API call from this client returns 401. See the next section.
SCOPE=$($KC get client-scopes -r master -q name=kc-admin-api \
--fields id,name --format csv --noquotes | grep kc-admin-api | cut -d, -f1)
$KC update clients/$CID/default-client-scopes/$SCOPE -r master

$KC add-roles -r master --uusername service-account-terraform --rolename admin

$KC get clients/$CID/client-secret -r master --fields value

The same thing in the admin console: Clients → Create client, turn off Standard flow, turn on Client authentication and Service accounts roles, then Client scopes → Add client scope → kc-admin-api as Default, then Service accounts roles → Assign role → filter by realm roles → admin.

The 401 that is not about your roles​

This is new, it is recent, and it will be the first thing that stops you.

Keycloak 26.8.2 added an audience check to the Admin REST API. The upgrading guide puts it under Breaking changes: "A new built-in client scope, kc-admin-api, provides this capability… you must assign the kc-admin-api client scope to those clients (as a default or optional scope)." The upgrade creates the scope in every realm but attaches it only to the built-in admin-cli and security-admin-console clients. A client you create yourself does not get it.

Skip that step and the provider fails before it touches a single resource:

Error: error initializing keycloak provider

with provider["registry.terraform.io/keycloak/keycloak"],
on main.tf line 11, in provider "keycloak":
11: provider "keycloak" {

failed to perform initial login to Keycloak: error sending GET request to
/admin/serverinfo: 401 Unauthorized. Response body: {"error":"HTTP 401
Unauthorized"}

Nothing in that message mentions scopes or audiences. The token is issued fine — the client_credentials grant returns 200 and the token carries every admin role. It is the aud claim that is wrong. Before attaching the scope:

{ "aud": ["master-realm", "account"], "azp": "terraform", "scope": "profile email" }

After:

{
"aud": ["http://localhost:8080/admin/realms/master", "master-realm", "account"],
"azp": "terraform",
"scope": "profile email kc-admin-api"
}

GET /admin/serverinfo goes from 401 to 200 on that change alone. Tokens issued before you attach the scope do not gain the audience; get a fresh one.

The two status codes mean different things, and the difference saves an afternoon:

CodeCauseFix
401 Unauthorized on every endpointToken lacks the kc-admin-api scope and the Admin API audienceAttach the kc-admin-api client scope to the client
403 Forbidden on one endpointToken is accepted; the service account lacks the role for that callGrant the role

Your first realm as code​

terraform {
required_version = ">= 1.9"
required_providers {
keycloak = {
source = "keycloak/keycloak"
version = "5.10.0"
}
}
}

provider "keycloak" {
client_id = "terraform"
client_secret = var.terraform_client_secret
url = "http://localhost:8080"
realm = "master"
}

variable "terraform_client_secret" {
type = string
sensitive = true
}

resource "keycloak_realm" "acme" {
realm = "acme"
enabled = true
display_name = "Acme Corp"

login_with_email_allowed = true
duplicate_emails_allowed = false

access_token_lifespan = "10m"
sso_session_idle_timeout = "30m"
sso_session_max_lifespan = "10h"
}

resource "keycloak_openid_client" "webapp" {
realm_id = keycloak_realm.acme.id
client_id = "acme-webapp"
name = "Acme Web App"
enabled = true

access_type = "CONFIDENTIAL"
standard_flow_enabled = true
valid_redirect_uris = ["https://app.acme.example/callback"]
web_origins = ["https://app.acme.example"]
}

resource "keycloak_role" "support" {
realm_id = keycloak_realm.acme.id
name = "support-agent"
description = "Read-only access to customer records"
}

resource "keycloak_group" "support" {
realm_id = keycloak_realm.acme.id
name = "support"
}

resource "keycloak_group_roles" "support" {
realm_id = keycloak_realm.acme.id
group_id = keycloak_group.support.id
role_ids = [keycloak_role.support.id]
}
export TF_VAR_terraform_client_secret='<the secret printed above>'
terraform init
terraform apply

Five resources, created in 0.7 seconds. The provider is a thin wrapper over the Admin REST API, so an apply against a local server is as fast as the API is — the slow part of a real run is terraform plan refreshing state, one GET per resource.

standard_flow_enabled is not optional above. Leave it out and the provider rejects the plan before it calls Keycloak at all:

Error: valid_redirect_uris cannot be set when standard or implicit flow is not enabled

That is the provider's own validation, not the server's — a useful property, because it fails in plan rather than halfway through an apply. Which client type you want decides which flow flags to set.

What terraform plan catches, and what it will never catch​

This is the part that decides whether config-as-code is actually buying you anything.

We changed three things on the running server by hand, the way a colleague with console access would:

  1. Added https://evil.example/cb to acme-webapp's redirect URIs.
  2. Created a new client, added-by-hand.
  3. Created a new realm role, rogue-admin.
Plan: 0 to add, 1 to change, 0 to destroy.

# keycloak_openid_client.webapp will be updated in-place
~ resource "keycloak_openid_client" "webapp" {
~ valid_redirect_uris = [
- "https://evil.example/cb",
# (1 unchanged element hidden)
]
}

One of three. terraform apply removed the rogue redirect URI. After the apply, added-by-hand and rogue-admin were both still there.

Terraform reverts what it manages and is blind to everything else. It is a configuration baseline, not an inventory one. A client someone adds by hand — the exact thing you want to catch — produces 0 to add forever, because Terraform has no record that it should not exist.

What to do about it:

WantDo
Revert console edits to managed objectsterraform plan -detailed-exitcode on a schedule; exit code 2 means drift
Notice objects nobody declaredDiff a nightly realm export against a list of expected clientIds — Terraform will not do this
Stop console edits happeningRemove console access, or scope it; see fine-grained admin permissions
An audit trail of who changed whatAdmin events, not Terraform state

The state file is key material​

A Keycloak confidential client has a secret, and Terraform reads it:

$ grep -o '"client_secret": "[^"]*"' terraform.tfstate
"client_secret": "j2yrvF0CYMfYSYm22z5s7sCchRWr97pQ0U4EV9tQV4uQFOGBTO48exLd3V7eMMfEbD7d93hYBJjf5TJ1akGs2p"

Marking an output sensitive = true hides it from the console. It does nothing to the state file. A five-resource state here is 11 KB of JSON containing one client secret in cleartext — the same property that makes kc.sh export output key material, covered in exporting a realm.

So:

  • Never commit terraform.tfstate. Use a remote backend with encryption at rest and locking, from the first commit.
  • Treat read access to the backend as equivalent to read access to every client secret in every realm you manage.
  • The provider's own credential is not written to state — we checked. Only resource attributes are. That is the one thing you do not have to worry about.
  • For secrets you supply rather than read, the provider has write-only variants (client_secret_wo with client_secret_wo_version) that keep the value out of state.

Adopting a realm you already have​

Nobody starts from an empty server. Terraform 1.5+ import blocks plus -generate-config-out will write the HCL for you:

import {
to = keycloak_openid_client.added_by_hand
id = "acme/93e42b86-6bc5-4038-b0e5-097de67ffee8"
}
terraform plan -generate-config-out=generated.tf
Plan: 1 to import, 0 to add, 0 to change, 0 to destroy.

Two things to know before you plan a migration around this.

The IDs are internal UUIDs, not names. keycloak_openid_client wants {realm}/{internal client UUID}, which you get from kcadm.sh get clients -r acme -q clientId=added-by-hand --fields id. Scripting that lookup is most of the work of a bulk import. The admin CLI tutorial covers the query syntax.

Generated config is exhaustive, not minimal. A client we had created with five attributes of HCL came back as 40 attributes, every default spelled out, including client_secret = null # sensitive. It is correct and it is unreadable. Treat the output as a starting point to delete from, not as the config you keep.

The import itself is non-destructive: the client secret of an imported client was byte-for-byte identical before and after terraform apply, and landed in state. Importing does not rotate anything.

The other path: realm JSON at startup​

The second mechanism is a JSON file in /opt/keycloak/data/import, read by start --import-realm. It is the right tool for a server that does not exist yet.

{
"realm": "beta",
"enabled": true,
"displayName": "Beta Corp",
"accessTokenLifespan": 600,
"clients": [
{
"clientId": "beta-webapp",
"enabled": true,
"publicClient": false,
"secret": "${BETA_WEBAPP_SECRET}",
"redirectUris": ["https://beta.example/callback"],
"standardFlowEnabled": true
}
],
"roles": { "realm": [{ "name": "support-agent" }] },
"groups": [{ "name": "support", "realmRoles": ["support-agent"] }]
}
docker run -d --name kc --memory 1536m -p 127.0.0.1:8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
-e BETA_WEBAPP_SECRET=s3cr3t-from-env \
-v "$PWD/import:/opt/keycloak/data/import:ro" \
quay.io/keycloak/keycloak:26.8.2 start-dev --import-realm
KC-SERVICES0030: Full model import requested. Strategy: IGNORE_EXISTING
Realm 'beta' imported
KC-SERVICES0032: Import finished successfully

${BETA_WEBAPP_SECRET} is substituted from the environment. We confirmed the client's secret came out as s3cr3t-from-env. That is how you keep a realm JSON file in git without keeping the secrets in git, and it is the single best reason to use this path for bootstrapping.

IGNORE_EXISTING is the whole problem​

Change the file and restart. The server logs this:

KC-SERVICES0030: Full model import requested. Strategy: IGNORE_EXISTING
Realm 'beta' already exists. Import skipped
KC-SERVICES0032: Import finished successfully

Import skipped, then finished successfully, then exit 0. We changed displayName and accessTokenLifespan; after the restart both were still at their original values. A green deploy, a committed file, and a server that does not match it.

There is no option on start to change this. kc.sh start-dev --help-all lists exactly one import flag — --import-realm — and no strategy setting. The startup import can create a realm. It can never update one.

kc.sh import --override updates it by deleting it​

The separate kc.sh import command does have the knob, and its default is the dangerous one:

--override <true|false>
Set if existing data should be overwritten. If set to false, data will be
ignored. Default: true.

We created a user, alice, in the imported beta realm, stopped the server, and ran:

kc.sh import --file /opt/keycloak/data/import/beta-realm.json --override true
Full importing from file /opt/keycloak/data/import/beta-realm.json
Realm 'beta' already exists. Removing it before import
Realm 'beta' imported

"Removing it before import." After restarting, displayName was the new value from the file — and the realm had zero users. alice was gone, along with every session, consent, federated-identity link and credential in the realm.

That is the honest answer to "why can't I just re-apply my realm JSON on every deploy?" Because "apply" means DELETE /admin/realms/beta. Realm JSON describes a realm's configuration; it is not a desired-state engine, and nothing in it distinguishes "this realm should have these clients" from "this realm should have only these clients and no users that aren't listed".

partialImport merges, on a running server​

There is a third, narrower option that most people never find: POST /admin/realms/{realm}/partialImport. It merges clients, roles, groups and identity providers into a live realm — no restart, no realm deletion — and a single top-level ifResourceExists field decides what happens to collisions. Tested against a realm that already had acme-webapp:

ifResourceExistsResponse
SKIP200 · {"overwritten":0,"added":0,"skipped":1}
OVERWRITE200 · {"overwritten":1,"added":0,"skipped":0}
FAIL409 · {"errorMessage":"Client id 'acme-webapp' already exists"}
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"ifResourceExists":"OVERWRITE","clients":[{"clientId":"acme-webapp","enabled":true}]}' \
http://localhost:8080/admin/realms/acme/partialImport

OVERWRITE does not mean "patch". After that call the client had a new internal UUID, a new client secret, and an empty redirectUris — because the payload did not mention redirect URIs. It deletes the object and recreates it from exactly what you sent. Every application holding the old secret is now broken.

So partialImport is additive and safe with SKIP or FAIL, destructive per-object with OVERWRITE, and in no mode can it remove something you stopped declaring. It drifts in the other direction from Terraform: it never deletes what it should, where kc.sh import --override deletes what it shouldn't.

Picking one​

Terraform providerRealm JSON (--import-realm)kcadm.sh scripts
Creates a realmYesYesYes
Updates an existing realmYes, in placeNo — skipped silentlyYes
Detects console driftYes, for managed objectsNoNo
Removes what it no longer declaresYesOnly by deleting the realmNo
Notices objects it never declaredNoNoNo
Needs a server runningYesNo — runs at bootYes
Keeps secrets out of the artefactVariables, write-only attributes${ENV_VAR} substitutionShell
Keeps secrets out of stateNo — plaintext in tfstaten/a, no staten/a, no state
Review a change before it landsterraform planNoNo
Realistic blast radius of a mistakeThe managed objectsThe whole realmOne call

The combination most teams land on: realm JSON to get a brand-new server to a working baseline with no network calls, then Terraform for everything after that. A realm JSON file checked into the repo and re-applied on every deploy is the configuration that looks safest and is the most dangerous.

Stop Terraform from deleting your realm​

keycloak_realm has an argument for this, added in provider 5.6.0:

resource "keycloak_realm" "acme" {
realm = "acme"
terraform_deletion_protection = true
}

It works — terraform destroy refuses:

Error: Deletion protection is enabled for keycloak_realm resource with realm
acme (ID: acme). To delete this resource, first set
`terraform_deletion_protection` to `false`.

Read the rest of that run before you trust it. Destroy walks the dependency graph leaves first, so by the time the realm resource errored, Terraform had already destroyed the client, the role, the group and the group-role binding inside it. We checked the server afterwards: realm acme present, every managed object in it gone.

So the flag protects the realm object — its login settings, its token lifespans, its keys, its users. It protects nothing you declared inside it. Set it, and still keep prevent_destroy lifecycle blocks on the resources you cannot lose.

Narrow the credential​

The bootstrap above grants admin in master, which is every permission on every realm. Where one Terraform workspace owns one realm, put the service-account client inside that realm instead and give it realm-admin from realm-management:

KC="docker exec kc /opt/keycloak/bin/kcadm.sh"
$KC create clients -r acme -s clientId=terraform-acme -s enabled=true \
-s publicClient=false -s standardFlowEnabled=false -s serviceAccountsEnabled=true
CID=$($KC get clients -r acme -q clientId=terraform-acme --fields id --format csv --noquotes)
SCOPE=$($KC get client-scopes -r acme -q name=kc-admin-api \
--fields id,name --format csv --noquotes | grep kc-admin-api | cut -d, -f1)
$KC update clients/$CID/default-client-scopes/$SCOPE -r acme
$KC add-roles -r acme --uusername service-account-terraform-acme \
--cclientid realm-management --rolename realm-admin

Point the provider at realm = "acme" and it manages everything in that realm normally. Ask it to create a second realm and you get the bounded failure you wanted:

Error: error sending POST request to /admin/realms: 403 Forbidden.

The cost: this credential cannot create the realm it lives in, so realm creation stays a privileged bootstrap step. That is usually the right trade — realm creation is rare, and everything frequent is inside a realm.

Where this runs out​

Two things worth knowing before you put the whole realm under Terraform.

Authentication flows are the painful resource. A flow is modelled as a parent plus ordered children, and on keycloak_authentication_execution both authenticator and parent_flow_alias are ForceNew — change which authenticator a step uses and Terraform destroys the execution and creates a new one rather than editing it. terraform plan says 1 to add, 1 to destroy, and for a window inside the apply the flow is missing that step. If the realm is bound to that flow, that window is a login outage. Build the new flow under a new alias, then switch keycloak_authentication_bindings to it — a rename is cheap, a replacement in place is not.

Realm JSON covers more than the provider does. The partial-export of the small realm above was 59 KB and 123 top-level keys — every WebAuthn policy field, every brute-force setting, the full authentication flow tree, clientPolicies, components. The provider has 111 resource types and covers the common ground well, but when something has no resource, the escape hatches are keycloak_generic_client_protocol_mapper, keycloak_custom_user_federation and keycloak_ldap_custom_mapper — and for a few things, nothing.

Check the resource exists before you promise a team their realm is fully declarative.

Next steps​