多Pod环境下Spring OAuth2+Keycloak认证跳转异常排查与解决

可能原因 #

• ClientIP会话亲和性不覆盖Keycloak回调请求：Kubernetes Service的sessionAffinity: ClientIP基于请求源IP做路由绑定，但Keycloak发起的回调请求源IP是其自身Pod的集群内IP，而非用户浏览器IP。因此Service会将回调请求随机分发到任意aaa Pod，而非用户初始访问的Pod。
• Spring Security OAuth2状态未跨Pod共享：OAuth2授权码流程中，发起认证时生成的state参数默认存储在当前Pod的HttpSession中。回调时需要读取同一个Session中的state校验，但多副本aaa Pod的Session独立存储，跳转至其他Pod后找不到对应state，导致认证失败，出现页面跳转错误或keycloak?error页面。
• Session未做分布式配置：Spring应用默认将HttpSession存储在单个Pod内存中，多副本场景下无法跨Pod共享会话数据，直接导致OAuth2流程的状态校验失败。

诊断方法 #

• 查看aaa应用的Pod日志，搜索关键词state，若出现Invalid state parameter或类似错误，即可确认是state校验失败导致的问题。
• 对比Service或Ingress的访问日志，检查用户初始请求与Keycloak回调请求的目标Pod是否为不同实例。
• 确认Keycloak回调请求的源IP：通过kubectl logs查看Gateway日志，验证回调请求的源IP是Keycloak集群内IP，而非用户客户端IP，以此确认ClientIP亲和性对回调请求无效。

解决方案 #

1. 配置分布式Session（推荐） #

将Spring应用的HttpSession存储到分布式缓存（如Redis），实现跨Pod会话共享，无论请求路由到哪个Pod，都能获取OAuth2流程所需的state。

步骤：

• 添加Spring Session Redis依赖（Maven示例）：

<dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session-data-redis</artifactId>
</dependency>
<dependency>
    <groupId>io.lettuce</groupId>
    <artifactId>lettuce-core</artifactId>
</dependency>

• 在application.yaml中配置Redis连接：

spring:
  session:
    store-type: redis
  redis:
    host: <redis-service-name>
    port: 6379

2. 自定义OAuth2 State存储 #

若无需共享整个Session，可单独配置Spring Security OAuth2的StateRepository，将state存储到共享存储中：

示例代码：

@Bean
public StateRepository stateRepository(RedisConnectionFactory connectionFactory) {
    return new RedisStateRepository(connectionFactory);
}

@Bean
public OAuth2AuthorizationRequestResolver authorizationRequestResolver(
        ClientRegistrationRepository clientRegistrationRepository,
        StateRepository stateRepository) {
    DefaultOAuth2AuthorizationRequestResolver resolver =
            new DefaultOAuth2AuthorizationRequestResolver(clientRegistrationRepository, "/aaa/oauth2/authorization");
    resolver.setStateRepository(stateRepository);
    return resolver;
}

3. 临时验证方案（不推荐用于生产） #

将Service的sessionAffinity改为其他策略，但由于Keycloak源IP固定，此方式无法从根本上解决问题，仅适合临时测试。

4. 优化Gateway转发配置 #

确保Gateway转发用户请求时正确保留客户端IP（如配置X-Forwarded-For请求头），但此配置仅对用户发起的请求生效，需配合分布式Session使用才能解决回调路由问题。

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