使用KeycloakOidcConfiguration时pac4j偶发NullPointerException问题咨询

使用pac4j框架结合KeycloakOidcConfiguration时，偶尔会出现NullPointerException，多数场景下功能正常，但错误日志需要重视，以下是对异常触发原因的分析：

异常堆栈信息 #

java.lang.NullPointerException: Cannot invoke "com.nimbusds.openid.connect.sdk.op.OIDCProviderMetadata.getCodeChallengeMethods()" because "opMetadataResolver" is null
    at org.pac4j.oidc.config.OidcConfiguration.findPkceMethod(OidcConfiguration.java:286)
    at org.pac4j.oidc.redirect.OidcRedirectionActionBuilder.addStateAndNonceParameters(OidcRedirectionActionBuilder.java:115)
    at org.pac4j.oidc.redirect.OidcRedirectionActionBuilder.getRedirectionAction(OidcRedirectionActionBuilder.java:58)
    at org.pac4j.core.client.IndirectClient.getRedirectionAction(IndirectClient.java:136)
    at org.pac4j.core.engine.DefaultSecurityLogic.redirectToIdentityProvider(DefaultSecurityLogic.java:240)
    at org.pac4j.core.engine.DefaultSecurityLogic.perform(DefaultSecurityLogic.java:160)
    at org.pac4j.http4s.SecurityFilterMiddleware$.securityFilter$$anonfun$1$$anonfun$1$$anonfun$1(SecurityFilterMiddleware.scala:76)

环境信息 #

pac4j版本：6.0.4.1

相关OIDC配置代码（已脱敏） #

def oidcClient(): OidcClient =
  val keycloakClientConfig = KeycloakOidcConfiguration()
  keycloakClientConfig.setBaseUri("https://example.com/")
  keycloakClientConfig.setRealm("my-realm")
  keycloakClientConfig.setClientId("id")
  keycloakClientConfig.setSecret("secret")
  keycloakClientConfig.setClientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
  keycloakClientConfig.setPreferredJwsAlgorithm(JWSAlgorithm.RS256)
  val keycloakClient = KeycloakOidcClient(keycloakClientConfig)
  keycloakClient.setCallbackUrl("/callback")
  keycloakClient.init()

异常触发原因分析 #

从堆栈信息可以定位到，异常发生在OidcConfiguration的findPkceMethod方法中，因为opMetadataResolver为null，导致调用其方法时触发NPE。结合pac4j的源码逻辑和配置代码，可能的原因如下：

• 初始化未完成即被使用：opMetadataResolver是在OidcConfiguration的init方法中完成初始化的，该方法会向Keycloak请求OpenID Provider元数据并解析。如果init尚未执行完毕（比如网络请求延迟），就有请求触发身份认证跳转逻辑，此时opMetadataResolver还未赋值，就会抛出NPE。
• 初始化过程中出现异常：如果init时向Keycloak请求元数据遇到网络波动、超时或服务暂时不可用，可能导致opMetadataResolver初始化失败。若异常未被正确捕获，未完成初始化的OidcClient仍被返回并用于后续请求，就会触发异常。
• 重复创建实例的并发问题：代码中每次调用oidcClient()都会创建新的KeycloakOidcClient并执行init，短时间内大量创建实例或多线程并发调用时，可能因资源竞争或请求排队，导致部分实例的init未完成就被使用。

解决方案建议 #

• 校验初始化结果：在init执行后添加逻辑，确认opMetadataResolver非null后再返回实例，避免返回未初始化完成的Client。
• 使用单例管理Client：将OidcClient配置为单例（比如依赖注入框架的单例Bean），避免重复创建实例，减少初始化开销和并发问题。
• 添加异常处理：捕获init过程中的异常，元数据请求失败时进行重试或返回错误，避免无效实例投入使用。
• 配置网络超时：调整OIDC配置的网络超时参数，避免因请求Keycloak元数据超时导致初始化失败。

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