Open Source

Keycloak Configuration as Code

Ensure the desired configuration state for your Keycloak realms using YAML or JSON files. Version-controlled, idempotent, and CI/CD-ready — no Keycloak restart required.

Get Started View on GitHub

Idempotent Configuration Import

keycloak-config-cli applies configuration changes rather than re-creating resources from scratch. Run it as many times as you like — only the delta between your desired state and the current Keycloak state is applied.

This idempotency makes it safe to include in any automated pipeline. A deploy that has nothing to change completes instantly without side effects.

# Run twice — second run is a no-op

$ docker run --rm \

-e KEYCLOAK_URL="http://keycloak:8080" \

-e KEYCLOAK_USER=admin \

-e KEYCLOAK_PASSWORD=admin123 \

-e IMPORT_FILES_LOCATIONS="/config/*" \

-v "$PWD/realms":/config \

adorsys/keycloak-config-cli:latest

# Output:

/ Realm 'my-realm': no changes

/ Client 'my-app': no changes

Done in 1.2s

# realm.yaml — works for any environment

realm: ${env:APP_ENV}-realm

enabled: true

clients:

- clientId: my-app

secret: ${file:UTF-8:${env:SECRET_FILE}}

redirectUris:

- "${env:APP_URL}/*"

# JavaScript evaluation

sessionTimeout: ${javascript: 2 * 60 * 60}

Variable Substitution for Multi-Environment Deployments

A single set of realm config files can target dev, staging, and production by injecting environment-specific values at import time. Enable import.var-substitution.enabled=true and reference environment variables, files, Base64 values, system properties, URLs, DNS lookups, and more.

Recursive substitution is supported: a variable can itself resolve to a file path, which is then read and substituted. Optional JavaScript evaluation enables dynamic expressions directly in your YAML.

Remote State Management

keycloak-config-cli tracks which resources were created by the tool using a state annotation stored directly in Keycloak. Only resources managed by keycloak-config-cli are removed during cleanup — manual changes made in the Admin UI are never touched unexpectedly.

Remote state can optionally be stored encrypted to protect sensitive configuration metadata. This gives you a safe and auditable view of exactly what your automation owns.

📋

State tracked inside Keycloak.
Only managed resources are modified.

# .github/workflows/keycloak.yml

name: Deploy Keycloak Config

on:

push:

paths: ['keycloak/**/*']

jobs:

deploy:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- run: |

docker run --rm \

CI/CD Pipeline Integration

keycloak-config-cli is designed to run as a step in any automated pipeline. It ships as a Docker image available on Docker Hub and Quay.io, as a Java JAR, and as a Helm chart for Kubernetes init-container patterns.

GitHub Actions, GitLab CI, Jenkins, ArgoCD, and Flux all work out of the box. Pair with Docker Secrets or Kubernetes Secrets for secure credential injection.

Docker, Helm, and Kubernetes Ready

Images are published to Docker Hub and Quay.io on every release. Multiple tags cover every supported Keycloak version as well as an edge-build tag for testing against unreleased versions.

🐳

Docker Hub • Quay.io • Helm Chart
All Keycloak versions supported

# realm.yaml — Keycloak export format

realm: my-realm

enabled: true

loginTheme: custom

clients:

- clientId: backend-api

protocol: openid-connect

bearerOnly: true

roles:

realm:

- name: app-admin

- name: app-user

YAML and JSON — Keycloak's Own Export Format

Configuration files use the same schema as Keycloak's native realm export. Export an existing realm from the Admin UI, trim the UUIDs and defaults, and you have a working config file immediately.

Both YAML and JSON are fully supported. Ant-style glob patterns let you split configuration across multiple files by resource type, realm, or environment — loaded in a predictable order.

Checksum Caching and Parallel Import

keycloak-config-cli caches checksums of imported config files so unchanged files are skipped on subsequent runs, making pipelines faster in environments where only a subset of realms change between deployments.

Parallel import can be enabled to speed up large configurations by processing compatible resources concurrently. Both behaviours are configurable through environment variables or CLI flags.

---

Features

✓

Idempotent Import

Apply once or a thousand times — only actual changes are made

📄

YAML & JSON Support

Keycloak's own export format, in the language you prefer

🔧

Variable Substitution

Env vars, files, Base64, URLs, DNS, system props and JavaScript

🚀

CI/CD Native

GitHub Actions, GitLab CI, Jenkins, ArgoCD — all work out of the box

🐳

Docker & Helm

Published to Docker Hub and Quay.io. Helm chart included

⏱️

Availability Check

Wait for Keycloak to be ready before importing — perfect for init containers

🏠

Remote State

Track managed resources so only automation-owned resources are removed

✓

Checksum Cache

Skip unchanged files on re-runs for faster pipelines

⚡

Parallel Import

Speed up large realm configurations with concurrent resource processing

✓

All Keycloak Resources

Realms, clients, roles, flows, identity providers, users, groups and more

⭐

Encrypted State

Optionally store remote state in encrypted format for added security

🔒

Spring Boot Based

Relaxed binding, configtree secrets, profiles and Spring config support

---

keycloak-config-cli is an open-source project by adorsys GmbH & Co. KG, used with Keycloak — a Cloud Native Computing Foundation project