gem-hunter
Language: Java
Import YAML/JSON-formatted configuration files into Keycloak - Configuration as Code for Keycloak.
keycloak-config-cli provides declarative, idempotent configuration for Keycloak via the Admin API—version-controlled and CI/CD-ready—covering realms, clients, roles, flows, identity providers, and more.
It 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 is based on the Keycloak realm export format. Store and manage configuration files in Git just like normal code. A Keycloak restart isn't required to apply the configuration.
DOCUMENTATION.md and docs/FEATURES.mdSECURITY.mdCODE_OF_CONDUCT.mdUsing Docker:
docker run --rm \ -e KEYCLOAK_URL="http://localhost:8080" \ -e KEYCLOAK_USER=admin \ -e KEYCLOAK_PASSWORD=admin123 \ -e IMPORT_FILES_LOCATIONS='/config/*' \ -v "$PWD/contrib/example-config":/config \ adorsys/keycloak-config-cli:latest
Using the JAR (after building or downloading a release):
java -jar ./target/keycloak-config-cli.jar \ --keycloak.url=http://localhost:8080 \ --keycloak.user=admin \ --keycloak.password=admin123 \ --import.files.locations=./contrib/example-config/moped.json
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.
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)
JavaScript Evaluation: $${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.
keycloak-config-cli supports an explicit JavaScript evaluation phase. This is an opt-in feature and can be enabled by import.var-substitution.script-evaluation-enabled=true.
Syntax: $${javascript: ... }
Example:
{
"realm": "$${javascript: 'realm-' + (env.APP_ENV || 'default').toLowerCase()}",
"enabled": "$${javascript: env.APP_ENV === 'INT'}",
"sessionTimeout": "$${javascript: 2 * 60 * 60}"
}The evaluation is sandboxed and only has access to an env object containing all environment variables and system properties. Only JSON-serializable outputs are allowed (string, number, boolean, null, array, object).
The variable substitution is running before the json parser gets executed. This allows json structures or complex values.
See docs/javascript-substitution.md for more information.
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}.
keycloak-config-cli supports logging in JSON format. To enable, set SPRING_PROFILES_ACTIVE=json-log.
| 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 of logging.level.root |
| --logging.level.http | LOGGING_LEVEL_HTTP | log level http requests between keycloak-config-cli and Keycloak | value of logging.level.root |
| --logging.level.realm-config | LOGGING_LEVEL_REALMCONFIG | if set to trace, the realm config including sensitive information will be logged | value of logging.level.root |
See: docs/FEATURES.md
Since keycloak-config-cli 4.0 will support the latest 4 releases of keycloak, if possible. There are some exceptions:
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
Before running mvn verify, you have to set the JAVA_HOME environment variable to prevent some test failures.
./mvnw verify
# Windows only
mvnw.cmd verifyIf 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
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 verifyStart a local keycloak on port 8080:
docker-compose down --remove-orphans && docker-compose up keycloakbefore 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.jsonA docker images is available at DockerHub (docker.io/adorsys/keycloak-config-cli) and quay.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 version x.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 version a.b.c which is built against the latest supported Keycloak release. |
a.b.c-x.y.z |
keycloak-config-cli version a.b.c which is built against the Keycloak version x.y.z. |
maven |
See below |
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
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:latestYou can build an own docker image by running
docker build -t keycloak-config-cli .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!
| 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.client-assertion-file | KEYCLOAK_CLIENTASSERTIONFILE |
File containing a signed JWT client assertion; read for every authentication request | - | Signed JWT client authentication |
| --keycloak.grant-type | KEYCLOAK_GRANTTYPE |
login grant_type | password |
|
| --keycloak.authorization | KEYCLOAK_AUTHORIZATION |
pre-acquired bearer token (raw, without Bearer prefix). Bypasses grant-type login when set. No refresh is attempted — the token must outlive the run. |
- | |
| --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 as Java Duration |
| --keycloak.tls.keystore-path | KEYCLOAK_TLS_KEYSTOREPATH |
Path to keystore containing client certificate and private key for mTLS | - | |
| --keycloak.tls.keystore-password | KEYCLOAK_TLS_KEYSTOREPASSWORD |
Password for the keystore | - | |
| --keycloak.tls.keystore-type | KEYCLOAK_TLS_KEYSTORETYPE |
Keystore type | PKCS12 |
|
| --keycloak.tls.truststore-path | KEYCLOAK_TLS_TRUSTSTOREPATH |
Path to truststore containing trusted CA certificates | - | |
| --keycloak.tls.truststore-password | KEYCLOAK_TLS_TRUSTSTOREPASSWORD |
Password for the truststore | - | |
| --keycloak.tls.truststore-type | KEYCLOAK_TLS_TRUSTSTORETYPE |
Truststore type | PKCS12 |
|
| --keycloak.availability-check.enabled | KEYCLOAK_AVAILABILITYCHECK_ENABLED |
Wait until Keycloak is available | false |
configured as Java Duration |
| --keycloak.availability-check.timeout | KEYCLOAK_AVAILABILITYCHECK_TIMEOUT |
Wait timeout for keycloak availability check | 120s |
|
| --keycloak.skip-server-info | KEYCLOAK_SKIPSERVERINFO |
Skip fetching Keycloak server info. Required for non-master realm authentication. | false |
SKIP_SERVER_INFO.md |
Set keycloak.client-assertion-file to use Signed JWT or Signed JWT - Federated authentication. The file overrides keycloak.client-secret, is read for every authentication request, and is never cached.
For Kubernetes, follow the Keycloak Admin Guide. Configure:
kubernetes and issuer https://kubernetes.default.svc.cluster.local;kubernetes, and subject system:serviceaccount:keycloak:keycloak-config-cli.Keycloak 26.4 and 26.5 require --features=client-auth-federated,kubernetes-service-accounts. Both features are enabled by default from Keycloak 26.6.
Apply this example in the keycloak namespace. Add the usual /config import volume for your realm files.
apiVersion: v1 kind: ServiceAccount metadata: name: keycloak-config-cli --- apiVersion: batch/v1 kind: Job metadata: name: keycloak-config-cli spec: template: spec: serviceAccountName: keycloak-config-cli restartPolicy: Never containers: - name: keycloak-config-cli image: adorsys/keycloak-config-cli:latest env: - name: KEYCLOAK_URL value: https://keycloak.example.com - name: KEYCLOAK_LOGINREALM value: kubernetes - name: KEYCLOAK_SKIPSERVERINFO value: "true" - name: KEYCLOAK_GRANTTYPE value: client_credentials - name: KEYCLOAK_CLIENTID value: keycloak-config-cli - name: KEYCLOAK_CLIENTASSERTIONFILE value: /var/run/secrets/tokens/keycloak volumeMounts: - name: client-assertion mountPath: /var/run/secrets/tokens readOnly: true volumes: - name: client-assertion projected: sources: - serviceAccountToken: path: keycloak audience: https://keycloak.example.com/realms/kubernetes expirationSeconds: 600
For ordinary Signed JWT, the file source must provide a new assertion with a unique jti for every read; a static assertion file is not supported.
| 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_UNDEFINEDISERROR |
Raise exceptions, if variables are not defined. | true |
|
| --import.var-substitution.prefix | IMPORT_VARSUBSTITUTION_PREFIX |
Configure the variable prefix, if import.var-substitution.enabled is true. |
$( |
|
| --import.var-substitution.suffix | IMPORT_VARSUBSTITUTION_SUFFIX |
Configure the variable suffix, if import.var-substitution.enabled is true. |
) |
|
| --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 removing default-roles-$REALM, even if its not defined in the import json. To make keycloak-config-cli able to remove the default-role-$REALM, import.remove-default-role-from-user must be set to true. In conclusion, you have to add the default-role-$REALM to the realm import on certain users, if you want not remove the default-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 to false 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 to fail when import should be aborted, continue reimport and update the checksum. |
continue |
|
| --import.users.merge-roles | IMPORT_USERS_MERGEROLES |
Only add missing user realm roles; do not remove existing realm roles not present in the import config. | false |
|
| --import.users.merge-groups | IMPORT_USERS_MERGEGROUPS |
Only add missing user groups; do not remove existing groups not present in the import config. | false |
| 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 |
See application.properties for all available settings.
For docker -e you have to remove hyphens and replace dots with underscores.
Take a look at spring relax binding or binding from Environment Variables if you need alternative spellings.
By define an environment variable SPRING_CONFIG_IMPORT=configtree:/run/secrets/, the values of properties can be provided via files instead of plain
environment variable values.
Example: To configure the property keycloak.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 the spring docs to get more information about the configuration trees feature in spring boot.
Building releases requires gpg signing.
Example to create and add a key to yout git config on MacOS
brew install gnupg gpg --version gpg --full-generate-key # follow instructions gpg --list-keys gpg --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 via maven release plugin:
./mvnw -Dresume=false release:prepare release:clean git push --follow-tags
Checkout https://adorsys.com/en/products/keycloak-config-cli/ for commercial support.