keycloak-config-cli

keycloak-config-cli是一个Keycloak实用工具，用于基于JSON/YAML文件确保领域的期望配置状态。JSON/YAML文件格式基于导出的领域格式，可像管理代码一样在Git中存储和处理配置文件，无需重启Keycloak即可应用配置。

配置文件

配置文件基于Keycloak导出文件格式，可用于重新导入设置。建议保持文件精简，移除所有UUID和Keycloak默认设置的内容。

moped.json是一个完整的示例配置文件，其他示例位于测试资源目录中。

变量替换

keycloak-config-cli支持配置文件的变量替换功能，可通过import.var-substitution.enabled=true启用（默认禁用）。

Spring Boot公开的变量（通过配置树或外部配置）可通过$(property.name)访问。

此外，字符串替换支持多种前缀用于不同场景：

Base64解码器:        $(base64Decoder:SGVsbG9Xb3JsZCE=)
Base64编码器:        $(base64Encoder:HelloWorld!)
Java常量:         $(const:java.awt.event.KeyEvent.VK_ESCAPE)
日期:                  $(date:yyyy-MM-dd)
DNS:                   $(dns:address|apache.org)
环境变量:  $(env:USERNAME)
文件内容:          $(file:UTF-8:src/test/resources/document.properties)
Java信息:                  $(java:version)
本地主机:             $(localhost:canonical-name)
属性文件:       $(properties:src/test/resources/document.properties::mykey)
资源包:       $(resourceBundle:org.example.testResourceBundleLookup:mykey)
脚本:                $(script:javascript:3 + 4)
系统属性:       $(sys:user.dir)
URL解码器:           $(urlDecoder:Hello%20World%21)
URL编码器:           $(urlEncoder:Hello World!)
URL内容(HTTP):    $(url:UTF-8:[***]
URL内容(HTTPS):   $(url:UTF-8:[***]
URL内容(文件):    $(url:UTF-8:file:///$(sys:user.dir)/src/test/resources/document.properties)
XML XPath:             $(xml:src/test/resources/document.xml:/root/path/to/node)

用于替换Java系统属性或环境变量的值。如果import.var-substitution.enabled设为true，默认启用递归变量替换，如$(file:UTF-8:$(env:KEYCLOAK_PASSWORD_FILE))。

变量替换在JSON解析器执行前运行，支持JSON结构或复杂值。

有关更多信息和高级用法，请参见Apache Common StringSubstitutor文档。

注意：变量替换是keycloak-config-cli的一部分，在本地完成。这意味着环境变量需要在执行keycloak-config-cli的环境中可用。

如果设置了import.var-substitution.prefix=${和import.var-substitution.suffix=}（keycloak-config-cli 3.x中的默认值），则Keycloak内置变量（如${role_uma_authorization}）需要使用$${role_uma_authorization}进行转义。

日志记录

JSON日志支持

keycloak-config-cli支持JSON格式日志。要启用，请设置SPRING_PROFILES_ACTIVE=json-log。

日志级别

支持的功能

参见：docs/FEATURES.md

与Keycloak的兼容性

从keycloak-config-cli 4.0开始，将支持Keycloak的最新4个版本（如可能）。存在一些例外情况：

• keycloak-config-cli将尝试为RH-SSO提供扩展支持
• 如果Keycloak引入重大变更，keycloak-config-cli可能会终止对旧版本的支持

Docker使用

Docker镜像可在DockerHub（docker.io/adorsys/keycloak-config-cli）和quay.io（quay.io/adorsys/keycloak-config-cli）获取。

可用的Docker标签

此外，maven标签包含源代码，可在运行时编译keycloak-config-cli。这有助于使用非***支持的Keycloak版本运行keycloak-config-cli，例如：

bash
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运行

对于Docker环境变量，需要将点替换为下划线。

shell
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构建

您可以通过以下命令构建自己的Docker镜像：

shell
docker build -t keycloak-config-cli .

配置

CLI选项/环境变量

Keycloak选项

导入选项

运行示例

本地运行

启动本地Keycloak（端口8080）：

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

然后执行以下命令：

shell
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