Keycloak 26.1.2：通过Admin CLI为永久管理员授予双域管理权限

前置准备 #

确保已完成以下步骤：

• 引导临时管理员
• 启动Keycloak服务
• 导入自定义realm.json

首先用临时管理员完成Admin CLI的无交互认证：

# 配置Admin CLI使用临时管理员认证
kcadm.sh config credentials \
  --server http://localhost:8080 \ # 替换为你的Keycloak服务地址
  --realm master \
  --user "$KC_BOOTSTRAP_ADMIN_USERNAME" \
  --password "$KC_BOOTSTRAP_ADMIN_PASSWORD"

步骤1：创建永久管理员用户 #

在master域创建永久管理员账号：

# 定义永久管理员的用户名和密码（建议用环境变量传递）
PERM_ADMIN_USERNAME="permanent-super-admin"
PERM_ADMIN_PASSWORD="your-secure-password"

# 创建永久管理员用户
kcadm.sh create users \
  --realm master \
  -s username="$PERM_ADMIN_USERNAME" \
  -s enabled=true \
  -s credentials='[{"type":"password","value":"'"$PERM_ADMIN_PASSWORD"'","temporary":false}]'

步骤2：授予master域完整管理权限 #

给永久管理员授予master域内置的realm-admin复合角色（该角色包含master域的所有管理权限）：

kcadm.sh add-roles \
  --realm master \
  --uusername "$PERM_ADMIN_USERNAME" \
  --client realm-management \
  --rolename realm-admin

步骤3：授予自定义域完整管理权限 #

假设你的自定义域名为my-custom-realm，执行以下命令授予该域的全管理权限：

CUSTOM_REALM_NAME="my-custom-realm" # 替换为你的自定义域名称

kcadm.sh add-roles \
  --realm "$CUSTOM_REALM_NAME" \
  --uusername "$PERM_ADMIN_USERNAME" \
  --client realm-management \
  --rolename realm-admin

步骤4：验证权限（可选） #

如果需要确认权限分配结果，可以用以下命令查询：

# 获取永久管理员的用户ID
USER_ID=$(kcadm.sh get users?username="$PERM_ADMIN_USERNAME" --realm master | jq -r '.[0].id')

# 查询master域的角色映射
kcadm.sh get users/"$USER_ID"/role-mappings/clients/realm-management --realm master

# 查询自定义域的角色映射
kcadm.sh get users/"$USER_ID"/role-mappings/clients/realm-management --realm "$CUSTOM_REALM_NAME"

步骤5：删除临时管理员 #

完成配置后删除临时引导管理员：

# 获取临时管理员的用户ID
TEMP_ADMIN_ID=$(kcadm.sh get users?username="$KC_BOOTSTRAP_ADMIN_USERNAME" --realm master | jq -r '.[0].id')

# 删除临时管理员
kcadm.sh delete users/"$TEMP_ADMIN_ID" --realm master

关键说明 #

• realm-admin是Keycloak内置的复合角色，包含对应域的所有管理权限，无需逐个添加单个权限角色
• 确保Keycloak服务处于运行状态，否则Admin CLI无法正常连接
• 敏感信息（如密码）建议用环境变量传递，避免硬编码在脚本中
• 若自定义域名称为动态值，可通过解析导入的realm.json获取或提前定义为环境变量

内容的提问来源于stack exchange，提问作者Dawid