PAC4J中DirectClient提取凭证时偶现NullPointerException求助

问题概述 #

在Java环境中使用PAC4J 5.7.0/5.7.1版本，通过DirectBearerAuthClient结合JWT实现认证功能时，偶现NullPointerException。异常触发场景：

• 搭载PAC4J的后端7×24小时运行，更新部署时会出现短暂停机；
• 后端重启后，前端持有的旧JWT失效，发起请求时触发认证流程；
• 功能整体正常，但该异常会干扰生产日志监控。

经排查，异常根源是时序问题：DirectClient初始化未完成时，credentialsExtractor对象仍为null就被调用，触发NPE。

异常栈信息：

2023-05-12T10:17:28.383 ERROR [qtp211001987-60] spark.http.matching.GeneralError -
java.lang.NullPointerException: Cannot invoke "org.pac4j.core.credentials.extractor.CredentialsExtractor.extract(org.pac4j.core.context.WebContext, org.pac4j.core.context.session.SessionStore)" because "this.credentialsExtractor" is null
at org.pac4j.core.client.BaseClient.retrieveCredentials(BaseClient.java:71) ~[pac4j-core-5.7.0.jar:?]
at org.pac4j.http.client.direct.DirectBearerAuthClient.retrieveCredentials(DirectBearerAuthClient.java:58) ~[pac4j-http-5.7.0.jar:?]
at org.pac4j.core.client.DirectClient.getCredentials(DirectClient.java:44) ~[pac4j-core-5.7.0.jar:?]
at org.pac4j.core.engine.DefaultSecurityLogic.perform(DefaultSecurityLogic.java:108) ~[pac4j-core-5.7.0.jar:?]
at org.pac4j.sparkjava.SecurityFilter.handle(SecurityFilter.java:64) ~[spark-pac4j-5.0.1.jar:?]
at spark.FilterImpl$1.handle(FilterImpl.java:73) ~[spark-core-2.9.4.jar:?]
at spark.http.matching.BeforeFilters.execute(BeforeFilters.java:48) ~[spark-core-2.9.4.jar:?]
at spark.http.matching.MatcherFilter.doFilter(MatcherFilter.java:133) ~[spark-core-2.9.4.jar:?]
at spark.embeddedserver.jetty.JettyHandler.doHandle(JettyHandler.java:50) ~[spark-core-2.9.4.jar:?]
at org.eclipse.jetty.server.session.SessionHandler.doScope(SessionHandler.java:1598) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.handler.ScopedHandler.handle(ScopedHandler.java:141) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.handler.HandlerWrapper.handle(HandlerWrapper.java:127) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.Server.handle(Server.java:516) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.HttpChannel.lambda$handle$1(HttpChannel.java:487) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.HttpChannel.dispatch(HttpChannel.java:732) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.HttpChannel.handle(HttpChannel.java:479) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.server.HttpConnection.onFillable(HttpConnection.java:277) ~[jetty-server-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.io.AbstractConnection$ReadCallback.succeeded(AbstractConnection.java:311) ~[jetty-io-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.io.FillInterest.fillable(FillInterest.java:105) ~[jetty-io-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.io.ChannelEndPoint$1.run(ChannelEndPoint.java:104) ~[jetty-io-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:883) ~[jetty-util-9.4.48.v20220622.jar:9.4.48.v20220622]
at org.eclipse.jetty.util.thread.QueuedThreadPool$Runner.run(QueuedThreadPool.java:1034) ~[jetty-util-9.4.48.v20220622.jar:9.4.48.v20220622]
at java.lang.Thread.run(Thread.java:833) ~[?:?]

解决方案 #

1. 确保客户端初始化完成后再对外提供服务 #

• 将DirectBearerAuthClient的初始化逻辑（包括设置credentialsExtractor、JwtAuthenticator等依赖）放在应用启动的主线程同步执行，避免在请求处理线程中延迟初始化。
• 在SparkJava场景下，可借助启动锁（如CountDownLatch）确保所有PAC4J客户端配置完成后，再让Jetty容器开始接收外部请求。

2. 自定义安全客户端增加空值校验 #

继承DirectBearerAuthClient，重写retrieveCredentials方法，提前校验credentialsExtractor是否为null，避免触发NPE：

public class SafeDirectBearerAuthClient extends DirectBearerAuthClient {
    @Override
    public Credentials retrieveCredentials(WebContext context, SessionStore sessionStore) {
        // 先判断核心组件是否初始化完成
        if (getCredentialsExtractor() == null) {
            // 返回空Credentials，让后续认证流程处理未初始化场景
            return null;
            // 也可抛出明确的可控异常，便于日志排查
            // throw new IllegalStateException("DirectBearerAuthClient not fully initialized");
        }
        return super.retrieveCredentials(context, sessionStore);
    }
}

之后使用自定义的SafeDirectBearerAuthClient替代原客户端即可。

3. 优化部署与前端逻辑 #

• 采用滚动部署代替停机部署，逐步切换新旧实例，减少后端重启后的请求冲击。
• 在前端增加JWT过期的主动检测逻辑，提前刷新token，减少后端重启后无效请求的数量。

4. 检查初始化代码的线程安全性 #

确认PAC4J客户端的配置代码不存在线程安全问题：

• 避免在多线程环境下修改客户端实例的属性（如setCredentialsExtractor）。
• 客户端实例应作为单例管理，初始化完成后不再修改其核心属性。

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