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.

Supported features

See: docs/FEATURES.md

Compatibility matrix

keycloak-config-cli	Keycloak 4.x - Keycloak 7.x	Keycloak 8.x - 10.x
v0.8.x	✓	✗
v1.0.x - v2.0.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/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

Docker run

docker run \
    -e KEYCLOAK_URL=http://<your keycloak host>:8080 \
    -e KEYCLOAK_USER=<keycloak admin username> \
    -e KEYCLOAK_PASSWORD=<keycloak admin password> \
    -e WAIT_TIME_IN_SECONDS=120 \
    -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
WAIT_TIME_IN_SECONDS	Timeout in seconds for waiting keycloak until reachable. Only inside docker.	120
keycloak.url	Keycloak Url without /auth	-
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
import.path	Location of config files	/config
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.	true
import.file-type	Format of the configuration import file. Allowed values: JSON/YAML	json
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.

Experimental native build

keycloak-config-cli provides experimental native builds based on GraalVM native image.

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