为何Keycloak Admin API用户查询端点返回空数组？

你使用拥有realm-management/query-users角色的服务账号获取access_token后，执行以下请求始终返回空数组[]：

curl --location --request GET 'https://example.com/admin/realms/REALM_NAME/users' \
        --header 'Authorization: Bearer eyTOKEN'

可以从以下几个方向排查问题：

• 确认服务账号的角色配置有效性
  确保realm-management/query-users角色是直接分配给服务账号，或者通过用户组间接关联，且该角色属于你请求的目标Realm（而非master Realm）。同时检查是否存在其他权限限制，比如角色的作用域设置是否正确。

• 验证access_token的权限内容
  解码你的access_token（可使用本地JWT解码工具），查看realm_access.roles字段中是否包含query-users，同时确认iss字段的域名是否与目标Realm的地址一致，避免使用了针对其他Realm生成的token。

• 检查Realm名称的准确性
  请求URL中的REALM_NAME必须与Keycloak中实际存在的Realm名称完全匹配，注意Keycloak的Realm名称是大小写敏感的，比如my-realm和My-Realm会被识别为两个不同的Realm。

• 添加查询参数扩大返回范围
  Keycloak Admin API默认的分页设置可能只返回少量用户，甚至当用户数量超过默认值时会返回空数组。可以尝试添加max参数指定返回数量，或者用q参数进行模糊查询，示例：

  curl --location --request GET 'https://example.com/admin/realms/REALM_NAME/users?max=100' \
          --header 'Authorization: Bearer eyTOKEN'
  

• 确认目标Realm中存在用户
  登录Keycloak控制台，进入目标Realm的用户管理界面，手动确认是否有用户存在。如果控制台中也没有用户，返回空数组属于正常情况。

• 核对API端点路径
  确保请求路径是正确的Admin API格式：/admin/realms/{realm}/users，避免出现拼写错误，比如遗漏realms路径段或者写错users关键字。

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