keycloak 升级至 20.0.3 后，因移除 `/auth` 路径前缀导致 rest api 调用返回 404 错误；修复方式是更新 keycloak admin client 的基础 url，显式剔除 `/auth`。
Keycloak 自版本 19 起开始逐步弃用并最终在 20.0.3 中正式移除 /auth 路径前缀，这是其向现代化、标准化 REST API 设计演进的关键变更。此前（如 v18/v19），Admin REST API 默认通过 https://keycloak.example.com/auth/admin/realms/{realm} 访问；升级后，该路径已简化为 https://keycloak.example.com/admin/realms/{realm}。若客户端仍沿用旧版 URL（含 /auth），所有 Admin API 请求（包括 realmResource.roles().get(...)）将触发 HTTP 404 —— 因为服务端已不再监听 /auth/* 下的管理端点。
✅ 正确配置 Keycloak Admin Client（Java 示例）
确保 KeycloakHelper.getRealmResource(...) 内部构造的 Keycloak 实例使用不含 /auth 的服务器 URL：
// ❌ 错误：包含 /auth（v18 风格，v20.0.3 不再支持） String serverUrl = "https://keycloak.example.com/auth"; // → 将导致 404 // ✅ 正确：仅保留根域名或上下文路径，不带 /auth String serverUrl = "https://keycloak.example.com"; // 推荐（默认映射到 /admin） // 或（若部署在子路径下，如 /kc） String serverUrl = "https://example.com/kc"; // 注意：此处也绝不能写成 /kc/auth
对应 Keycloak.getInstance(...) 的调用应类似：
Keycloak keycloak = KeycloakBuilder.builder()
.serverUrl(serverUrl) // ← 关键：不带 /auth
.realm("master")
.username("admin")
.password("secret")
.clientId("admin-cli")
.clientSecret("...")
.build();
RealmResource realmResource = keycloak.realm("my-realm");
RoleRepresentation roleRep = realmResource.roles()
.get("roleName")
.toRepresentation(); // ✅ 现在可成功返回⚠️ 注意事项与验证建议
不要手动拼接 /auth/admin：Keycloak Admin Java Client（keycloak-admin-client）内部会自动补全 /admin/realms/{realm} 路径，开发者只需提供基础 URL（即服务入口根地址）；
检查反向代理配置：若使用 Nginx/Apache 做代理，请确认未意外重写或强制添加 /auth 前缀；
-
验证 API 可达性：可通过 curl 快速验证：
# ✅ 正确（v20+） curl -X GET "https://keycloak.example.com/admin/realms/my-realm/roles/roleName" \ -H "Authorization: Bearer $TOKEN" # ❌ 404（v20.0.3 已废弃） curl -X GET "https://keycloak.example.com/auth/admin/realms/my-realm/roles/roleName" \ -H "Authorization: Bearer $TOKEN" 升级兼容性提醒：此变更影响所有 Admin REST API 调用（如用户、clients、groups 等），不仅限于 roles；建议全局审查所有 serverUrl 初始化逻辑。
? 总结
Keycloak 20.0.3 的 /auth 移除是一项破坏性变更（breaking change），但目标明确：统一 API 入口、简化路由结构、提升安全性与可维护性。解决问题的核心在于——彻底清理客户端中任何硬编码的 /auth 字符串，让 serverUrl 指向 Keycloak 服务的根上下文路径即可。完成配置修正后，realmResource.roles().get(...) 等所有 Admin Client 操作将恢复正常。
