Keycloak Admin API创建Realm失败：403未知错误求助

以下是排查和解决的关键点：

• 确认Token的请求端点：获取access_token时，必须向master realm的token端点发起请求，比如：

  POST /realms/master/protocol/openid-connect/token
  

  （Keycloak 17+版本去掉了/auth前缀，旧版本需保留/auth）

• 检查API端点路径：创建Realm的正确API端点是根级的/admin/realms（旧版为/auth/admin/realms），不能使用某个具体realm下的子路径，比如错误的/admin/realms/{existing-realm}/realms。

• 验证权限配置：

  1. 确保给service account分配的是master realm的realm-admin角色，而非其他realm的同名角色；
  2. 部分Keycloak版本中，创建Realm需要单独的manage-realms权限（realm-admin角色通常包含该权限，但可直接给service account添加manage-realms角色验证）。

• 解码Token确认权限：手动解码access_token，检查：

  • realm_access.roles数组中是否包含realm-admin；
  • iss字段是否为master realm的地址；
  • resource_access中对应master realm的客户端是否拥有正确的权限映射。

• 规范API请求格式：

  1. 必须使用POST方法；
  2. 请求头需设置Content-Type: application/json；
  3. 请求体必须包含必填的realm字段，示例：

     {
       "realm": "my-new-realm",
       "enabled": true
     }
     

• 检查客户端配置：确保custom-admin-api客户端的Access Type设置为confidential，且Service Accounts Enabled选项已开启。

内容的提问来源于stack exchange，提问作者dev.support