Table of Contents

keycloak-config-cli

Config files

Variable Substitution

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:#"auto">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 ifimport.var-substitution.enabled is set totrue.
The variable substitution is running before the json parser gets executed. This allows json structures or complex values.
SeeApache CommonStringSubstitutor 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.
Ifimport.var-substitution.prefix=${ andimport.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, setSPRING_PROFILES_ACTIVE=json-log.
Log level
CLI Option
ENV Variable
Description
Default
--logging.level.root
LOGGING_LEVEL_ROOT
define the root log level
info
--logging.level.keycloak-config-cli
LOGGING_LEVEL_KEYCLOAKCONFIGCLI
log level of keycloak-config-cli components
value oflogging.level.root
--logging.level.http
LOGGING_LEVEL_HTTP
log level http requests between keycloak-config-cli and Keycloak
value oflogging.level.root
--logging.level.realm-config
LOGGING_LEVEL_REALMCONFIG
if set to trace, the realm config includingsensitive information will be logged
value oflogging.level.root
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 forRH-SSO
keycloak-config-cli will cut the support if keycloak introduces some breaking changes
Build this project
keycloak-config-cli usingmaven to build and test keycloak-config-cli.In case maven is not installed on your system, themvnw command will download maven for you.
Further development requirements
Java Development Kit (JDK)
Docker Desktop or an alternative replacement (e.g Rancher Desktop)
Before runningmvn verify, you have to set the JAVA_HOME environment variable to prevent some test failures.
./mvnw verify# Windows onlymvnw.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 usingTestContainers in our integration tests. To run the integration tests a configured docker environmentis required.
./mvnw verify# Windows onlymvnw.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 atDockerHub (docker.io/adorsys/keycloak-config-cli)andquay.io (quay.io/adorsys/keycloak-config-cli)
Available docker tags
Tag
Description
latest
latest available release of keycloak-config-cli which is built against the latest supported Keycloak release.
latest-x.y.z
latest available release of keycloak-config-cli which is built against the Keycloak versionx.y.z.
edge
latest commit on the main branch and which is built against the latest supported Keycloak release.
a.b.c
keycloak-config-cli versiona.b.c which is built against the latest supported Keycloak release.
a.b.c-x.y.z
keycloak-config-cli versiona.b.c which is built against the Keycloak versionx.y.z.
maven
See below
Additionally, the tagmaven contains the source code and compile keycloak-config-cli at runtime. This has the advantage to keycloak-config-cli withKeycloak 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 charthere.
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 aboutchart dependencies!
Configuration
CLI option / Environment Variables
Keycloak options
CLI Option
ENV Variable
Description
Default
Docs
--keycloak.url
KEYCLOAK_URL
Keycloak URL including web context. Format:scheme://hostname:port/web-context.
-
--keycloak.user
KEYCLOAK_USER
login user name
admin
--keycloak.password
KEYCLOAK_PASSWORD
login user password
-
--keycloak.client-id
KEYCLOAK_CLIENTID
login clientId
admin-cli
--keycloak.client-secret
KEYCLOAK_CLIENTSECRET
login client secret
-
--keycloak.grant-type
KEYCLOAK_GRANTTYPE
login grant_type
password
--keycloak.login-realm
KEYCLOAK_LOGINREALM
login realm
master
--keycloak.ssl-verify
KEYCLOAK_SSLVERIFY
Verify ssl connection to keycloak
true
--keycloak.http-proxy
KEYCLOAK_HTTPPROXY
Connect to Keycloak via HTTP Proxy. Format:scheme://hostname:port
-
--keycloak.connect-timeout
KEYCLOAK_CONNECTTIMEOUT
Connection timeout
10s
--keycloak.read-timeout
KEYCLOAK_READTIMEOUT
Read timeout
10s
configured asJava Duration
--keycloak.availability-check.enabled
KEYCLOAK_AVAILABILITYCHECK_ENABLED
Wait until Keycloak is available
false
configured asJava Duration
--keycloak.availability-check.timeout
KEYCLOAK_AVAILABILITYCHECK_TIMEOUT
Wait timeout for keycloak availability check
120s
Import options
CLI Option
ENV Variable
Description
Default
Docs
--import.validate
IMPORT_VALIDATE
Validate configuration settings
false
--import.parallel
IMPORT_PARALLEL
Enable parallel import of certain resources
false
--import.files.locations
IMPORT_FILES_LOCATIONS
Location of config files (URL, file path, or Ant-style pattern)
-
IMPORT.md
--import.files.include-hidden-files
IMPORT_FILES_INCLUDE_HIDDEN_FILES
Includes files that marked as hidden
false
--import.files.excludes
IMPORT_FILES_EXCLUDES
Exclude files with Ant-style pattern
-
--import.cache.enabled
IMPORT_CACHE_ENABLED
Enable caching of import file locations
true
--import.cache.key
IMPORT_CACHE_KEY
Cache key for importing config.
default
--import.remote-state.enabled
IMPORT_REMOTESTATE_ENABLED
Enable remote state management. Purge only resources managed by keycloak-config-cli.
true
MANAGED.md
--import.remote-state.encryption-key
IMPORT_REMOTESTATE_ENCRYPTIONKEY
Enables remote state in encrypted format. If unset, state will be stored in plain
-
--import.var-substitution.enabled
IMPORT_VARSUBSTITUTION_ENABLED
Enable variable substitution config files
false
--import.var-substitution.nested
IMPORT_VARSUBSTITUTION_NESTED
Expand variables in variables.
true
--import.var-substitution.undefined-is-error
IMPORT_VARSUBSTITUTION_UNDEFINEDISTERROR
Raise exceptions, if variables are not defined.
true
--import.var-substitution.prefix
IMPORT_VARSUBSTITUTION_PREFIX
Configure the variable prefix, ifimport.var-substitution.enabled istrue.
$(
--import.var-substitution.suffix
IMPORT_VARSUBSTITUTION_SUFFIX
Configure the variable suffix, ifimport.var-substitution.enabled istrue.
)
--import.behaviors.sync-user-federation
IMPORT_BEHAVIORS_SYNC_USER_FEDERATION
Enable the synchronization of user federation.
false
--import.behaviors.remove-default-role-from-user
IMPORT_BEHAVIORS_REMOVEDEFAULTROLEFROMUSER
The default setting of this flag prevents keycloak-config-cli from removingdefault-roles-$REALM, even if its not defined in the import json. To make keycloak-config-cli able to remove thedefault-role-$REALM,import.remove-default-role-from-user must be set to true. In conclusion, you have to add thedefault-role-$REALM to the realm import on certain users, if you want not remove thedefault-role-$REALM.
false
--import.behaviors.skip-attributes-for-federated-user
IMPORT_BEHAVIORS_SKIP_ATTRIBUTESFORFEDERATEDUSER
Set attributes to null for federated users to avoid read only conflicts
false
--import.behaviors.checksum-with-cache-key
IMPORT_BEHAVIORS_CHECKSUM_WITH_CACHE_KEY
Use cache key to store the checksum, if set tofalse a checksum for each import file is stored
true
--import.behaviors.checksum-changed
IMPORT_BEHAVIORS_CHECKSUM_CHANGED
Defines the behavior if the checksum of an imported file has changed. Set tofail when import should be aborted,continue reimport and update the checksum.
continue
Spring boot options
CLI Option
ENV Variable
Description
Default
Docs
--spring.profiles.active
SPRING_PROFILES_ACTIVE
enable spring profiles. comma separated
-
Set the Active Spring Profiles
--spring.config.import
SPRING_CONFIG_IMPORT
See below
info
Configure properties values through files
--logging.level.root
LOGGING_LEVEL_ROOT
define the root log level
info
Logging
--debug
DEBUG
enables debug mode of spring boot
false
Seeapplication.properties for all available settings.
For docker-e you have to remove hyphens and replace dots with underscores.
Take a look atspring relax binding orbinding from Environment Variablesif you need alternative spellings.
Configure properties values through files
By define an environment variableSPRING_CONFIG_IMPORT=configtree:/run/secrets/, the values of properties can be provided via files instead of plainenvironment variable values.
Example: To configure the propertykeycloak.password in this case, the file should be in/run/secrets/keycloak.password.
The configuration and secret support in Docker Swarm is a perfect match for this use case.
Checkout thespring docsto get more information about the configuration trees feature in spring boot.
Perform release
Building releases requires gpg signing.
Example to create and add a key to yout git config on MacOS
brew install gnupggpg --versiongpg --full-generate-key# follow instructionsgpg --list-keysgpg --list-secret-keys --keyid-format=short# check the 8 digit code eg "ssb   xxxxxxx/E51442F5 2022-01-01 [X]"git config --global user.signingkey E51442F5
Finally add the key to your Github account under Settings -> SSH and GPG keys -> New GPG key
Create release viamaven release plugin:
./mvnw -Dresume=false release:prepare release:cleangit push --follow-tags
Commercial support
Checkouthttps://adorsys.com/en/products/keycloak-config-cli/ for commercial support.