Spring WebFlux集成pac4j+Keycloak OIDC获取Profile遇“State无法确定”错误

问题场景 #

基于Java 19、Spring Boot 3.0.3的Spring WebFlux项目，集成pac4j与Keycloak OpenID时，完成认证回调阶段获取KeycloakOidcProfile遇到**“State cannot be determined”**错误。已确认重定向到Keycloak时设置的SESSION Cookie在回调请求中存在且未变更，同时Keycloak返回的响应头包含Referrer-policy: no-referrer。

解决方案 #

1. 修正异步上下文的代码逻辑 #

WebFlux是异步非阻塞模型，你的代码中同步调用getCredentials、getUserProfile会破坏异步上下文，导致Session中的State参数无法正确读取。修改为异步链式调用：

public Mono<KeycloakOidcProfile> getUserProfile(ServerRequest serverRequest) {
    final WebContext context = new SpringWebfluxWebContext(serverRequest.exchange());
    final SessionStore sessionStore = new SpringWebfluxSessionStore(serverRequest.exchange());
    
    return Mono.justOrEmpty(serverRequest.queryParam("code"))
            .doOnNext(code -> System.out.println("Authorization code: " + code))
            .then(Mono.fromCallable(() -> config.getClients().findClient("KeycloakOidcClient").get()))
            .flatMap(client -> Mono.fromCallable(() -> client.getCredentials(context, sessionStore)))
            .filter(Optional::isPresent)
            .map(Optional::get)
            .flatMap(credentials -> Mono.fromCallable(() -> config.getClients().findClient("KeycloakOidcClient").get()
                    .getUserProfile(credentials, context, sessionStore)))
            .filter(Optional::isPresent)
            .map(Optional::get)
            .cast(KeycloakOidcProfile.class)
            .doOnNext(profile -> System.out.println("Access token: " + profile.getAccessToken()));
}

将同步的get()调用包装在Mono.fromCallable中，确保Session操作在异步上下文内完成，避免线程安全问题。

2. 检查State参数的Session存储 #

pac4j默认以pac4jState-[clientName]为键在Session中存储State参数，通过调试SpringWebfluxSessionStore的get方法，确认回调请求的Session中是否存在对应键值：

• 如果不存在，排查是否为重定向与回调请求使用了不同Session（比如负载均衡环境未配置Session同步、Cookie路径/域配置错误）
• 如果存在但值不匹配，检查Keycloak回调时携带的state参数是否与Session中存储的一致

3. 验证Cookie属性配置 #

即使SESSION Cookie存在，以下属性异常也可能导致State读取失败：

• Path：确保Cookie的Path覆盖回调接口的路径
• SameSite：若设置为Strict，跨域回调时浏览器可能阻止Cookie携带，建议改为Lax（非HTTPS环境）或None（HTTPS环境）
• HttpOnly：SpringWebfluxSessionStore默认支持读取HttpOnly Cookie，无需修改，但需确认是否有其他拦截器篡改Cookie

4. 排除Referrer-policy的影响 #

Referrer-policy: no-referrer不会直接导致该错误，pac4j的State验证逻辑不依赖请求的Referrer头，可排除此因素。

5. 启用pac4j调试日志 #

添加日志配置查看State参数的生成、存储、读取全过程：
在application.yml中配置：

logging:
  level:
    org.pac4j: DEBUG

通过日志定位State参数在哪个环节丢失或不匹配，快速缩小问题范围。

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