Keycloak版本获取、启动报错及OIDC Realm跳转问题求助

一、获取Keycloak 12/18版本 #

官方归档页仅提供21.0.0及以上版本，可直接从Maven中央仓库搜索对应版本的分发包：

• 搜索关键词：keycloak distribution，选择对应版本（如12.0.4、18.0.0）的zip/tar.gz包下载即可。

二、JDK版本适配（针对Keycloak 21+版本） #

Keycloak 21+基于Quarkus重构，强制要求JDK 17及以上版本，之前的报错原因如下：

• Java 11启动：Quarkus编译时使用了更高的JDK版本（JDK17），导致类版本不兼容（错误提示io.quarkus.bootstrap.runner.QuarkusEntryPoint编译版本过高）。
• JDK8启动：--add-opens是JDK9+引入的参数，JDK8不支持该参数，导致JVM启动失败。

解决步骤：

1. 安装JDK 17（OpenJDK或Oracle JDK均可）。
2. 设置系统环境变量JAVA_HOME指向JDK17安装目录。
3. 重新运行kc.bat start-dev即可正常启动。

三、OIDC自定义Realm URL跳转问题排查 #

针对登录态无法打开目标页面、未登录无法跳转登录页后打开页面的问题，按以下步骤排查：

1. 检查Realm基础配置 #

• 确认Realm的Frontend URL配置正确：在Keycloak后台的Realm设置中，Frontend URL需与Keycloak对外暴露的完整URL一致（如本地部署为http://localhost:8080，注意21+版本已移除/auth上下文）。该配置错误会直接导致跳转路径偏移。

2. 检查客户端（Client）配置 #

• 有效重定向URI（Valid Redirect URIs）：必须包含应用所有需要回调的URL，格式如http://your-app-domain:port/*，确保覆盖所有可能的跳转路径，避免因URI不匹配被拦截。
• 根URL（Root URL）：设置为应用的根域名，如http://your-app-domain:port。
• 访问类型（Access Type）：根据应用类型选择，公开Web应用选public，后端服务选confidential，错误类型会导致认证流程异常。

3. 检查应用侧OIDC配置 #

• 确认应用配置的Keycloak端点路径与版本匹配：
  • Keycloak 21+版本端点示例：/realms/{realm-name}/protocol/openid-connect/auth（授权端点）、/realms/{realm-name}/protocol/openid-connect/token（令牌端点）。
  • 旧版本（12/18）端点示例：/auth/realms/{realm-name}/protocol/openid-connect/auth。
• 应用的回调URL需与Keycloak客户端的有效重定向URI完全一致，包括协议（http/https）、端口、路径，不能有任何差异。

4. 登录态跳转问题排查 #

• 检查浏览器Cookie：确认Keycloak的SESSIONID Cookie已正确设置，若应用与Keycloak跨域，需在Keycloak客户端配置中开启CORS，允许应用域名的跨域请求。
• 排查应用侧登录态校验逻辑：确认应用在登录态下正确读取Keycloak令牌，且目标页面的路径拼接、权限校验无错误。

5. 未登录跳转问题排查 #

• 检查应用拦截器/过滤器：确认未登录请求被正确捕获，并重定向到Keycloak授权端点，且重定向URL中的redirect_uri参数正确指向应用的目标页面。
• 检查Realm认证流程：确认Realm启用的认证流程无自定义错误，若使用了自定义认证入口，需确保该流程能正常引导用户完成登录并跳转回应用。

内容的提问来源于stack exchange，提问作者Dev Anand Sadasivam