如何在pac4j中正确配置状态传输？OIDC回调state存在却报错

问题场景 #

在基于pac4j实现客户端OIDC连接时，出现状态（state）验证异常：

• 认证请求URL（含state参数）：

  https://authserver.com/mini-sinai/auth?scope=openid profile email&response_type=code&redirect_uri=https://client.com/jee-pac4j-demo/callback?client_name=MiniSinai&state=e8e3b77123&nonce=vvDVEE3hv70GLUvDVG5IyaU30S6EJqsAjGHEyuUg_NA&client_id=9d9a41d95b4907ca13ac60b0568aa3
  

• 认证服务器返回的回调URL（含匹配的state）：

  302 https://client.com/jee-pac4j-demo/callback?client_name=MiniSinai&code=TrCQCp02fodz071SdKTXisZseJFcNwWJcFs7z3772tw&state=e8e3b77123
  

• 客户端抛出异常：

  org.pac4j.oidc.exceptions.OidcMissingSessionStateException: State cannot be determined
      org.pac4j.oidc.credentials.extractor.OidcCredentialsExtractor.lambda$extract$0(OidcCredentialsExtractor.java:118)
      java.base/java.util.Optional.orElseThrow(Optional.java:403)
      org.pac4j.oidc.credentials.extractor.OidcCredentialsExtractor.extract(OidcCredentialsExtractor.java:118)
      org.pac4j.core.client.BaseClient.getCredentials(BaseClient.java:74)
      org.pac4j.core.engine.DefaultCallbackLogic.perform(DefaultCallbackLogic.java:83)
      org.pac4j.demo.jee.DemoConfigFactory$MyCallbackLogic.perform(DemoConfigFactory.java:126)
      org.pac4j.jee.filter.CallbackFilter.internalFilter(CallbackFilter.java:63)
      org.pac4j.jee.config.AbstractConfigFilter.doFilter(AbstractConfigFilter.java:92)
  

此前同主机运行正常，推测state依赖Tomcat Session存储，疑问是否需要特殊配置允许通过URI传输state。

问题分析 #

pac4j默认会将生成的state值存储在用户服务器端会话（Tomcat Session）中，回调阶段需要从会话中取出该值与URL中的state做一致性校验——这是防止CSRF攻击的核心机制。即使URL里存在正确的state，只要会话中找不到对应的存储记录，就会触发OidcMissingSessionStateException异常。

解决方向 #

• 排查会话共享问题
  同主机正常、跨主机异常的情况，大概率是会话Cookie无法跨域传递：

  • 检查Tomcat的context.xml或web.xml中Session Cookie的domain配置，确保覆盖客户端和回调域名；
  • 若为HTTPS跨域场景，需将Cookie的SameSite属性设为None，同时开启Secure属性，避免浏览器拦截会话Cookie。

• 检查自定义回调逻辑
  你使用了自定义的MyCallbackLogic，需确认：

  • 该逻辑未意外清除会话中的state存储；
  • 回调流程中正确传递了JEEContext对象（pac4j通过它获取会话）。

• 调整state存储策略（仅特殊场景）
  如果必须绕过服务器端会话（不推荐，存在CSRF风险），可配置pac4j使用CookieSessionStore将state存储在客户端Cookie中：

  OidcClient oidcClient = new OidcClient();
  oidcClient.setSessionStore(new CookieSessionStore());
  

  优先推荐解决会话共享问题，而非绕过安全校验。

• 验证OIDC客户端配置
  确认OidcClient配置无错误：

  • 未禁用state生成逻辑；
  • 默认的JEEHttpSessionStore未被替换为无法正常工作的自定义实现。

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