adorsys/keycloak-config-cli repository overview

⁠Table of Contents

• Config Files⁠
• Variable Substitution⁠
• Logging⁠
• Supported Features⁠
• Compatibility with Keycloak⁠
• Build this Project⁠
• Run Integration Tests⁠
• Run this Project⁠
• Docker⁠
• Helm⁠
• Configuration⁠
• Perform Release⁠
• Commercial Support⁠

⁠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.enabled=true (disabled by default).

Variables exposed by spring boot (through configtree or external configuration⁠) can be accessed by $(property.name).

In additional, the string substitution support multiple prefixes for different approaches

Base64 Decoder:        $(base64Decoder:SGVsbG9Xb3JsZCE=)
Base64 Encoder:        $(base64Encoder:HelloWorld!)
Java Constant:         $(const:java.awt.event.KeyEvent.VK_ESCAPE)
Date:                  $(date:yyyy-MM-dd)
DNS:                   $(dns:address|apache.org)
Environment Variable:  $(env:USERNAME)
File Content:          $(file:UTF-8:src/test/resources/document.properties)
Java:                  $(java:version)
Localhost:             $(localhost:canonical-name)
Properties File:       $(properties:src/test/resources/document.properties::mykey)
Resource Bundle:       $(resourceBundle:org.example.testResourceBundleLookup:mykey)
Script:                $(script:javascript:3 + 4)
System Property:       $(sys:user.dir)
URL Decoder:           $(urlDecoder:Hello%20World%21)
URL Encoder:           $(urlEncoder:Hello World!)
URL Content (HTTP):    $(url:UTF-8:http://www.apache.org)
URL Content (HTTPS):   $(url:UTF-8:https://www.apache.org)
URL Content (File):    $(url:UTF-8:file:///$(sys:user.dir)/src/test/resources/document.properties)
XML XPath:             $(xml:src/test/resources/document.xml:/root/path/to/node)

to replace the values with java system properties or environment variables. Recursive variable replacement like $(file:UTF-8:$(env:KEYCLOAK_PASSWORD_FILE)) is enabled by default if import.var-substitution.enabled is set to true.

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

See Apache Common StringSubstitutor documentation⁠ for more information and advanced usage.

Note: Since variable substitution is a part of the keycloak-config-cli, it's done locally. This means, the environment variables need to be available where keycloak-config-cli is executed.

If import.var-substitution.prefix=${ and import.var-substitution.suffix=} (default in keycloak-config-cli 3.x) is set, then keycloak builtin variables like ${role_uma_authorization} needs to be escaped by $${role_uma_authorization}.

⁠Logging

⁠JSON logging support

keycloak-config-cli supports logging in JSON format. To enable, set SPRING_PROFILES_ACTIVE=json-log.

⁠Log level

⁠Supported features

See: docs/FEATURES.md⁠

⁠Compatibility with keycloak

Since keycloak-config-cli 4.0 will support the latest 4 releases of keycloak, if possible. There are some exceptions:

• keycloak-config-cli will try the keep an extended support for RH-SSO⁠
• keycloak-config-cli will cut the support if keycloak introduces some breaking changes

⁠Build this project

keycloak-config-cli using maven⁠ to build and test keycloak-config-cli. In case maven is not installed on your system, the mvnw⁠ command will download maven for you.

Further development requirements

• Java Development Kit (JDK)
• Docker Desktop or an alternative replacement (e.g Rancher Desktop)

Before running mvn verify, you have to set the JAVA_HOME environment variable to prevent some test failures.

./mvnw verify

# Windows only
mvnw.cmd verify

If your are working with a Docker Desktop replacement, some of the Integrationtests can fail due to internal DNS Lookups (host.docker.internal is not reachable). In this case the host can be replaced by a property.

mvn verify -DJUNIT_LDAP_HOST=an.alternate.host.or.ip

⁠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.

./mvnw verify

# Windows only
mvnw.cmd verify

⁠Run this project

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.files.locations=./contrib/example-config/moped.json

⁠Docker

A docker images is available at DockerHub⁠ (docker.io/adorsys/keycloak-config-cli) and quay.io⁠ (quay.io/adorsys/keycloak-config-cli)

Available docker tags

Additionally, the tag maven contains the source code and compile keycloak-config-cli at runtime. This has the advantage to keycloak-config-cli with Keycloak versions, that not official supported., e.g.:

docker run --rm -ti -v $PWD:/config/ -eKEYCLOAK_VERSION=23.0.1 -eMAVEN_CLI_OPTS="-B -ntp -q" adorsys/keycloak-config-cli:edge-build

⁠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_AVAILABILITYCHECK_ENABLED=true \
    -e KEYCLOAK_AVAILABILITYCHECK_TIMEOUT=120s \
    -e IMPORT_FILES_LOCATIONS='/config/*' \
    -v <your config path>:/config \
    adorsys/keycloak-config-cli:latest

⁠Docker build

You can build an own docker image by running

docker build -t keycloak-config-cli .

⁠Helm

We provide a helm chart here⁠.

Since it makes 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⁠!

⁠Configuration

⁠CLI option / Environment Variables

⁠Keycloak options

⁠Import options