Keycloak 服务器管理：Admin CLI 完全指南

周琰策Scott

于 2025-06-01 09:03:51 发布

阅读量396

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00019/article/details/148360733

Keycloak 服务器管理：Admin CLI 完全指南

keycloak Keycloak 是一个开源的身份和访问管理解决方案，用于保护应用程序和服务的安全和访问。 * 身份和访问管理解决方案、保护应用程序和服务的安全和访问 * 有什么特点：支持多种认证和授权协议、易于使用、可扩展性强项目地址: https://gitcode.com/gh_mirrors/ke/keycloak

什么是 Keycloak Admin CLI

Keycloak Admin CLI 是一个命令行工具，允许管理员通过命令行界面执行各种管理任务。它通过调用 Keycloak 的 Admin REST API 端点来实现功能，为自动化管理和脚本化操作提供了强大支持。

安装与配置

安装 Admin CLI

Keycloak 服务器发行版中已经包含了 Admin CLI 工具，位于 bin 目录下：

Linux/macOS 系统使用 kcadm.sh
Windows 系统使用 kcadm.bat

建议将 Keycloak 的 bin 目录添加到系统 PATH 环境变量中，以便在任何位置都能使用 CLI 工具。

# Linux/macOS
export PATH=$PATH:$KEYCLOAK_HOME/bin

# Windows
set PATH=%PATH%;%KEYCLOAK_HOME%\bin

注意：需要先设置 KEYCLOAK_HOME 环境变量指向 Keycloak 的安装目录。

基本使用

使用 Admin CLI 前需要先进行身份验证：

# 配置认证凭据
kcadm.sh config credentials --server http://localhost:8080/auth \
  --realm master --user admin

# 创建新域
kcadm.sh create realms -s realm=demorealm -s enabled=true

# 创建客户端
CID=$(kcadm.sh create clients -r demorealm \
  -s clientId=my_client \
  -s 'redirectUris=["http://localhost:8980/myapp/*"]' -i)

# 获取客户端配置
kcadm.sh get clients/$CID/installation/providers/keycloak-oidc-keycloak-json

安全注意事项

生产环境必须使用 HTTPS：避免令牌暴露
证书信任配置：如果使用自签名证书，需要配置信任库

kcadm.sh config truststore --trustpass $PASSWORD ~/.keycloak/truststore.jks

敏感信息处理：避免在命令行直接输入密码，可以使用环境变量或交互式输入

认证机制详解

Admin CLI 支持两种认证方式：

会话保持模式（默认）：使用 config credentials 建立会话后会保存访问令牌和刷新令牌
单次认证模式：使用 --no-config 参数，每次命令都重新认证

# 会话保持模式
kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user admin

# 单次认证模式
kcadm.sh get realms --no-config --server http://localhost:8080/auth --realm master --user admin

配置文件管理

默认情况下，Admin CLI 会在用户主目录下创建配置文件：

Linux/macOS: ~/.keycloak/kcadm.config
Windows: %HOMEPATH%\.keycloak\kcadm.config

可以使用 --config 选项指定不同的配置文件，实现多会话并行管理。

重要安全提示：配置文件包含敏感信息，必须确保其权限设置正确，防止其他用户访问。

核心操作命令

Admin CLI 提供基本的 CRUD 操作命令：

kcadm.sh create ENDPOINT [ARGUMENTS]  # 创建资源
kcadm.sh get ENDPOINT [ARGUMENTS]    # 查询资源
kcadm.sh update ENDPOINT [ARGUMENTS] # 更新资源
kcadm.sh delete ENDPOINT [ARGUMENTS] # 删除资源

这些命令分别对应 HTTP 的 POST、GET、PUT 和 DELETE 方法。

域(Realm)管理实战

创建新域

# 简单创建
kcadm.sh create realms -s realm=demorealm -s enabled=true

# 通过JSON文件创建
kcadm.sh create realms -f demorealm.json

查询域信息

# 列出所有域
kcadm.sh get realms

# 查询特定域
kcadm.sh get realms/master

# 只显示部分字段
kcadm.sh get realms --fields realm,enabled

更新域配置

# 直接更新属性
kcadm.sh update realms/demorealm -s enabled=false

# 通过文件更新
kcadm.sh get realms/demorealm > demorealm.json
# 编辑文件后
kcadm.sh update realms/demorealm -f demorealm.json

删除域

kcadm.sh delete realms/demorealm

配置登录选项

kcadm.sh update realms/demorealm \
  -s registrationAllowed=true \
  -s registrationEmailAsUsername=true \
  -s rememberMe=true \
  -s verifyEmail=true \
  -s resetPasswordAllowed=true \
  -s editUsernameAllowed=true

密钥管理

查看域密钥

kcadm.sh get keys -r demorealm

生成新密钥

# 获取域ID
kcadm.sh get realms/demorealm --fields id --format csv --noquotes

# 添加RSA密钥提供者
kcadm.sh create components -r demorealm \
  -s name=rsa-generated \
  -s providerId=rsa-generated \
  -s providerType=org.keycloak.keys.KeyProvider \
  -s parentId=REALM_ID \
  -s 'config.priority=["101"]' \
  -s 'config.enabled=["true"]' \
  -s 'config.active=["true"]' \
  -s 'config.keySize=["2048"]'

从JKS文件导入密钥

kcadm.sh create components -r demorealm \
  -s name=java-keystore \
  -s providerId=java-keystore \
  -s providerType=org.keycloak.keys.KeyProvider \
  -s parentId=REALM_ID \
  -s 'config.priority=["101"]' \
  -s 'config.enabled=["true"]' \
  -s 'config.active=["true"]' \
  -s 'config.keystore=["/path/to/keystore.jks"]' \
  -s 'config.keystorePassword=["secret"]' \
  -s 'config.keyPassword=["secret"]' \
  -s 'config.keyAlias=["alias"]'

停用或删除密钥

# 停用密钥
kcadm.sh update components/PROVIDER_ID -r demorealm \
  -s 'config.active=["false"]'

# 删除密钥(确保已停用)
kcadm.sh delete components/PROVIDER_ID -r demorealm