Keycloak与Spring Authorization Server授权码流集成问题求助

场景1：Spring Boot 2.5.4 + Spring Authorization Server 0.2.0 + Keycloak 15.0.2（999错误码） #

问题原因 #

999是Keycloak的通用错误码，核心诱因是Spring认证成功后，回调Keycloak的流程被Spring Security默认错误页面拦截，或redirect_uri参数不匹配、认证成功后的跳转逻辑未适配Keycloak的回调要求。

解决方案 #

1. 精确匹配redirect_uri
   在Spring Authorization Server中注册Keycloak客户端时，redirect_uri必须完全匹配Keycloak二级OIDC提供商的回调地址，格式为：

   http://<keycloak-host>:<port>/auth/realms/<你的realm>/broker/<Spring Auth Provider的ID>/endpoint
   

   同时在Keycloak的二级IDP配置中，确保「Valid Redirect URIs」与上述地址完全一致。

2. 禁用默认错误页面并自定义跳转逻辑

   • 在application.properties中添加配置关闭默认错误页面：

     server.error.whitelabel.enabled=false
     

   • 自定义认证成功处理器，直接携带redirectionurl参数跳转回Keycloak：

     @Bean
     public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
         http
             .authorizeRequests(auth -> auth.anyRequest().authenticated())
             .oauth2Login(oauth2 -> oauth2
                 .successHandler((request, response, auth) -> {
                     String redirectUrl = request.getParameter("redirectionurl");
                     if (redirectUrl != null) {
                         response.sendRedirect(redirectUrl);
                     }
                 })
             );
         return http.build();
     }
     

3. 调整Keycloak二级IDP配置

   • 关闭「Validate Signature」选项（若使用自签名证书），或导入Spring Auth Server的公钥到Keycloak信任存储；
   • 开启「Use JWT from response as identity token」选项，确保Keycloak能正确解析Spring返回的身份令牌。

场景2：Spring Boot 3.1.1 + Spring Authorization Server 1.1.0 + Keycloak 15.0.2（400错误） #

问题原因 #

Spring Authorization Server 1.x（适配Spring Boot 3）的OIDC端点格式、参数处理逻辑与0.2.0版本差异较大，而Keycloak 15.0.2对新版OIDC规范的兼容性不足，导致请求参数不匹配或端点自动发现失败。

解决方案 #

1. 手动指定Spring Auth Server的OIDC端点
   在Keycloak的二级IDP配置中，关闭「Discovery」选项，手动填写以下端点：

   • 授权端点：http://<spring-auth-host>:<port>/oauth2/authorize
   • 令牌端点：http://<spring-auth-host>:<port>/oauth2/token
   • 用户信息端点：http://<spring-auth-host>:<port>/userinfo

2. 适配Spring Boot 3的参数编码与客户端配置

   • 在application.yml中显式配置Spring Auth Server的客户端信息：

     spring:
       security:
         oauth2:
           authorization-server:
             issuer: http://<spring-auth-host>:<port>
           client:
             registration:
               keycloak-broker:
                 client-id: <keycloak客户端ID>
                 client-secret: <keycloak客户端密钥>
                 redirect-uri: "{baseUrl}/login/oauth2/code/keycloak-broker"
                 scope: openid,profile,email
     

   • 添加字符编码过滤器，避免参数编码问题：

     @Bean
     public FilterRegistrationBean<CharacterEncodingFilter> characterEncodingFilter() {
         CharacterEncodingFilter filter = new CharacterEncodingFilter();
         filter.setEncoding("UTF-8");
         filter.setForceEncoding(true);
         FilterRegistrationBean<CharacterEncodingFilter> reg = new FilterRegistrationBean<>(filter);
         reg.addUrlPatterns("/*");
         return reg;
     }
     

3. Keycloak版本兼容调整
   Keycloak 15.0.2属于旧版本，建议升级到Keycloak 20+版本，可更好兼容Spring Authorization Server 1.x的OIDC实现；若无法升级，确保Keycloak二级IDP的「Client Authentication」选择「Client Secret Basic」，与Spring Auth Server的配置一致。

通用排查步骤 #

• 统一域名/端口：避免localhost与127.0.0.1混用，所有组件使用一致的访问地址；
• 开启调试日志：
  • Spring Boot添加：logging.level.org.springframework.security=DEBUG
  • Keycloak开启调试日志，查看具体的参数不匹配、签名验证失败等细节；
• 检查Scope配置：确保Keycloak请求的openid、profile等Scope在Spring Auth Server中已配置允许。

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