Keycloak通过UI创建自定义角色客户端及权限、路径问题咨询

一、API路径404的原因 #

Keycloak 17及后续版本（包括你使用的22.0.1）默认移除了/auth上下文路径，所以旧资料里带/auth的请求路径会返回404。正确的token请求路径格式为：

http://localhost:8080/realms/claim-dev/protocol/openid-connect/token

这是新版本的默认行为，无需额外配置。

二、创建仅含用户管理权限的客户端 #

要实现严格权限控制，可按以下步骤操作：

1. 创建独立领域（Realm） #

• 登录Keycloak管理控制台，进入master域，点击左侧菜单「Realm Settings」→「Create realm」，输入领域名称（如custom-realm）后保存。

2. 在目标领域创建后端客户端 #

• 切换到刚创建的custom-realm，点击左侧菜单「Clients」→「Create client」。
• 填写客户端ID（如backend-user-admin），开启「Client authentication」（后端服务需用客户端凭证流），完成基础配置后点击「Save」。
• 进入客户端的「Credentials」标签页，记录客户端密钥（后续获取token需用到）。

3. 分配精准的用户管理权限 #

场景1：客户端管理自身领域（custom-realm）的用户

• 在custom-realm下，进入「Clients」→ 选中backend-user-admin →「Client scopes」→「Add client scope」。
• 搜索并添加内置的realm-management客户端范围，点击「Assign」。
• 进入「Clients」→backend-user-admin→「Roles」，在「Client Roles」下拉框选择realm-management。
• 仅勾选用户管理相关角色（按需选择）：
  • manage-users：创建、编辑、删除用户
  • view-users：查看用户列表及详情
  • query-users：查询用户数据
• 点击「Assign」完成权限分配。

场景2：客户端管理master域的用户（需谨慎操作）

• 切换到master域，创建新客户端（如cross-realm-user-admin），开启「Client authentication」并保存，记录密钥。
• 进入master域的「Clients」→cross-realm-user-admin→「Roles」，在「Client Roles」下拉框选择realm-management。
• 仅勾选master域下的manage-users、view-users等用户管理角色，点击「Assign」。

4. 验证权限有效性 #

用客户端凭证流获取token：

curl -X POST http://localhost:8080/realms/{你的领域}/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={客户端ID}" \
  -d "client_secret={客户端密钥}" \
  -d "grant_type=client_credentials"

拿到token后调用用户管理API验证：

curl -X GET http://localhost:8080/admin/realms/{目标领域}/users \
  -H "Authorization: Bearer {获取到的token}"

能正常返回用户列表即说明权限配置生效。

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