升级Keycloak至20.0.3后获取角色出现404错误求助

问题重现 #

升级Keycloak至20.0.3版本后，执行以下代码获取角色时抛出javax.ws.rs.NotFoundException: HTTP 404 Not Found：

RealmResource realmResource = KeycloakHelper.getRealmResource(connectionParameters);
RoleRepresentation representation = realmResource.roles().get("roleName").toRepresentation();

排查与解决步骤 #

• 确认角色存在且名称完全匹配
  Keycloak角色名区分大小写，需登录Keycloak后台，进入目标Realm的「Roles」页面，搜索代码中指定的roleName，确认角色存在且名称（包括空格、特殊字符）完全一致。

• 验证用户/客户端权限
  用于连接Keycloak的用户需具备读取角色的权限：

  1. 进入目标Realm → 「Clients」 → 选择你的客户端 → 「Authorization」 → 「Permissions」 → 「Realm Permissions」；
  2. 添加view-realm和view-roles权限；
     或直接给用户分配Realm级角色：view-realm、view-roles。

• 同步Keycloak客户端依赖版本
  确保项目中keycloak-admin-client依赖版本与服务器版本（20.0.3）完全一致，例如Maven依赖：

  <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-admin-client</artifactId>
      <version>20.0.3</version>
  </dependency>
  

• 直接测试Admin API排查
  用HTTP工具直接调用Keycloak Admin API验证：

  1. 获取访问令牌：

     POST {keycloakServerUrl}/realms/{realm}/protocol/openid-connect/token
     # 参数：grant_type=password&username=你的用户名&password=你的密码&client_id=admin-cli
     

  2. 调用角色查询接口：

     GET {keycloakServerUrl}/admin/realms/{realm}/roles/{roleName}
     # 请求头：Authorization: Bearer {获取到的令牌}
     

     如果接口返回404，说明角色不存在或权限不足；如果正常返回，需检查代码中RealmResource的初始化逻辑。

• 检查RealmResource初始化正确性
  确认KeycloakHelper中初始化Keycloak客户端的参数无误：

  • keycloakServerUrl需指向正确的Keycloak服务器地址（如http://localhost:8080）；
  • keycloakServerRealm需与目标Realm名称完全匹配；
  • 若使用自定义客户端，需开启该客户端的「Service Account Enabled」并分配管理权限，示例初始化代码：

    Keycloak keycloak = KeycloakBuilder.builder()
        .serverUrl(connectionParameters.getKeycloakServerUrl())
        .realm(connectionParameters.getKeycloakServerRealm())
        .username(connectionParameters.getUsername())
        .password(connectionParameters.getPassword())
        .clientId("admin-cli") // 默认管理客户端，或你的自定义客户端ID
        .build();
    RealmResource realmResource = keycloak.realm(connectionParameters.getKeycloakServerRealm());
    

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