keycloak 从 18.x 升级至 20.0.3 后，调用 `realmresource.roles().get("rolename")` 报 `404 not found`，核心原因是 v20+ 移除了 `/auth` 路径前缀，需更新 admin rest api 基础 url。
Keycloak 20.0 版本是一个重大架构变更版本（基于 Quarkus 重构），其中一项关键调整是彻底移除 Admin REST API 中已弃用的 /auth 路径前缀。这意味着所有管理端请求（包括通过 keycloak-admin-client 发起的 RealmResource 调用）必须使用精简后的基础 URL：https://
若仍沿用含 /auth 的 URL 初始化 Keycloak 实例，客户端生成的最终请求路径将变为类似：
GET /auth/admin/realms/myrealm/roles/roleName
而 Keycloak 20.0.3 实际只响应：
GET /admin/realms/myrealm/roles/roleName
——路径不匹配直接导致 HTTP 404。
✅ 正确配置示例如下（Java + keycloak-admin-client 20.0.3）：
Keycloak keycloak = KeycloakBuilder.builder()
.serverUrl("https://keycloak.example.com") // ✅ 不再包含 /auth
.realm("master")
.username("admin")
.password("secret")
.clientId("admin-cli")
.clientSecret("...") // 若使用 confidential client
.build();
RealmResource realmResource = keycloak.realm("myrealm");
RoleRepresentation roleRep = realmResource.roles()
.get("admin-role") // 注意：此处传入的是 role name（非 ID）
.toRepresentation();⚠️ 关键注意事项：
- URL 必须纯净：serverUrl 参数值应为 Keycloak 服务根地址（如 https://kc.example.com 或 http://localhost:8080），绝对不可附加 /auth、/admin 或任何路径；客户端会自动拼接 /admin/realms/{realm}。
- 区分 role name 与 role ID：realmResource.roles().get("xxx") 中的 "xxx" 是角色的 name 字段值（如 "view-users"），不是数据库 ID。若需按 ID 查询，请改用 realmResource.roles().roleById("role-id-hex")。
- 检查客户端版本兼容性：确保使用的 keycloak-admin-client 依赖版本与 Keycloak 服务端严格一致（如服务端为 20.0.3，则客户端也应为 20.0.3）。混合版本可能导致序列化或路由异常。
- 验证 Admin Console 是否可用：访问 https://your-kc-server.com/admin/（无 /auth）能正常打开管理控制台，是确认基础 URL 正确的最快方式。
? 总结：该问题并非权限或角色不存在，而是纯粹的 REST API 路由变更所致。升级 Keycloak 至 20.x 后，务必全局审查所有 serverUrl 配置项，剥离 /auth 前缀，并同步更新客户端依赖版本。这一改动提升了 API 路径一致性，也是 Keycloak 迈向现代化架构的重要一步。
