Keycloak注册新用户出现403 Forbidden权限错误求助

云上老周

2026-6-16

Keycloak 403 Forbidden（用户注册接口）排查与解决

问题根源

从解码的服务账号Token和Keycloak日志可以明确：

服务账号service-account-test-backend的Token中缺少realm-management客户端的manage-users和view-users权限，导致调用/admin/users创建用户接口时触发ForbiddenException。
错误地将自定义USER-MANAGEMENT角色分配给了test-backend客户端本身，而非该客户端对应的服务账号用户——服务账号的权限是基于其自身的角色映射，而非客户端的角色。

解决方法

方法1：直接为服务账号分配所需管理角色

登录Keycloak管理控制台，进入test-realm
左侧菜单点击Clients，找到test-backend并进入详情页
切换到Service Account Roles标签
在Client Roles下拉框中选择realm-management
从可用角色列表中选中manage-users和view-users，点击Add selected完成分配

方法2：通过自定义复合角色分配权限

若想保留USER-MANAGEMENT复合角色，需调整分配对象：

左侧菜单点击Users，搜索service-account-test-backend（这是test-backend客户端自动生成的服务账号用户）
进入该用户详情页，切换到Role Mappings标签
在Client Roles下拉框选择realm，找到USER-MANAGEMENT角色并添加到已分配角色中
确认该用户的Composite Roles中包含realm-management的manage-users和view-users

验证步骤

获取新的服务账号Token，调用以下接口（client_credentials模式）：

curl -X POST http://localhost:9090/realms/test-realm/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=test-backend" \
  -d "client_secret=your-backend-secret"

解码Token，检查resource_access字段是否包含：

"resource_access": {
  "realm-management": {
    "roles": [
      "view-users",
      "manage-users"
    ]
  },
  "test-backend": {
    "roles": [
      "uma_protection"
    ]
  }
}