keycloak-config-cli

keycloak-config-cli is a Keycloak utility to ensure the desired configuration state for a realm based on a JSON/YAML file. The format of the JSON/YAML file based on the export realm format. Store and handle the configuration files inside git just like normal code. A Keycloak restart isn't required to apply the configuration.

Config files

The config files are based on the keycloak export files. You can use them to re-import your settings. But keep your files as small as possible. Remove all UUIDs and all stuff which is default set by keycloak.

moped.json is a full working example file you can consider. Other examples are located in the test resources.

Variable Substitution

keycloak-config-cli supports variable substitution of config files. This could be enabled by import.var-substitution=true (disabled by default). Use variables like ${sys:name-of-system-property} or ${env:NAME_OF_ENVIRONMENT} to replace the values with java system properties or environment variables.

The variable substitution is running before the json parser gets executed. This allows json structures or complex values.

See: Apache Common StringSubstitutor for more information and advanced usage.

Supported features

See: docs/FEATURES.md

Compatibility matrix

keycloak-config-cli	Keycloak 4.x - Keycloak 7.x	Keycloak 8.x - 11.x
v0.8.x	✓	✗
v1.0.x - v2.3.x	✗	✓
master	✗	✓

• ✓ Supported
• ✗ Not supported

Build this project

mvn package

Run integration tests against real keycloak

We are using TestContainers in our integration tests. To run the integration tests a configured docker environment is required.

mvn verify

Run this project

via Maven

Start a local keycloak on port 8080:

docker-compose down --remove-orphans && docker-compose up keycloak

before performing following command:

java -jar ./target/keycloak-config-cli.jar \
    --keycloak.url=http://localhost:8080 \
    --keycloak.ssl-verify=true \
    --keycloak.user=admin \
    --keycloak.password=admin123 \
    --import.path=./contrib/example-config/moped.json

Docker

The docker tag latest points to the latest availible release while master points to the latest commit on the master branch.

Docker run

For docker -e you have to replace dots with underscores.

docker run \
    -e keycloak_url=http://<your keycloak host>:8080 \
    -e keycloak_user=<keycloak admin username> \
    -e keycloak_password=<keycloak admin password> \
    -e keycloak_availability-check_enabled=true \
    -e keycloak_availability-check_timeout=120s \
    -e import_path=/config \
    -e import_force=false \
    -v <your config path>:/config \
    adorsys/keycloak-config-cli:latest

Helm

We provide a helm chart here.

Since it make no sense to deploy keycloak-config-cli as standalone application, you could add it as dependency to your chart deployment.

Checkout helm docs about chart dependencies!

CLI option / Environment Variables

CLI / ENV Variable	Description	Default	Docs
keycloak.url	Keycloak URL including web context. Format: scheme://hostname:port/web-context.	-
keycloak.user	login user name	admin
keycloak.password	login user name	-
keycloak.client-id	login clientId	admin-cli
keycloak.login-realm	login realm	master
keycloak.ssl-verify	Verify ssl connection to keycloak	true
keycloak.http-proxy	Connect to Keycloak via HTTP Proxy. Format: scheme://hostname:port	-
keycloak.availability-check.enabled	Wait until Keycloak is available	false
keycloak.availability-check.timeout	Wait timeout for keycloak availability check	120s
import.path	Location of config files (if location is a directory, all files will be imported)	/config
import.var-substitution	Enable variable substitution config files	false
import.force	Enable force import of realm config	false
import.cache-key	Cache key for importing config.	default
import.state	Enable state management. Purge only resources managed by kecloak-config-cli. S.	true	MANAGED.md
import.file-type	Format of the configuration import file. Allowed values: AUTO,JSON,YAML	auto
import.parallel	Enable parallel import of certain resources	false

See application.properties for all available settings.

Take a look at spring relax binding if you need alternative spellings. For docker -e you have to replace dots with underscores.

Experimental native build

keycloak-config-cli provides experimental native builds based on GraalVM native image. While native builds configs provided for multiple versions of keycloak, only the latest version will be tested and released as artifact.

Benefits:

• No java required
• smaller footprint (less cpu, less memory, less image size)
• Speed. Running sample config in 5 seconds. (8 seconds on normal builds)

Limitations:

• Some dynamic jvm features needs to be define manually in graalvm. The list isn't complete which can be result in an unexpected behavior.

Perform release

Create release via maven release plugin:

mvn -Dresume=false release:prepare release:clean
git push --follow-tags