Keycloak OIDC Adapter 22.0.5不支持JakartaEE的解决方案咨询

问题背景 #

使用Keycloak OIDC Adapter 22.0.5时，发现该版本依赖Java EE的javax.servlet API（源码中明确导入javax.servlet.http.HttpServletResponse），无法直接在Jakarta EE环境下运行。同时引入Java EE和Jakarta EE API包后，出现如下报错：

org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:198)
at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:726)
... 37 more
Caused by: java.lang.NoSuchMethodError: 'javax.servlet.ServletContext org.apache.catalina.Context.getServletContext()'
at org.keycloak.adapters.tomcat.AbstractKeycloakAuthenticatorValve.keycloakInit(AbstractKeycloakAuthenticatorValve.java:111)
at org.keycloak.adapters.tomcat.AbstractKeycloakAuthenticatorValve.lifecycleEvent(AbstractKeycloakAuthenticatorValve.java:70)
at ...

报错核心原因是：Jakarta EE环境下Tomcat的getServletContext()返回jakarta.servlet.ServletContext类型，但适配器仍在寻找javax.servlet.ServletContext的方法签名，导致方法匹配失败。

可行解决办法 #

1. 升级到Jakarta EE兼容的Keycloak适配器版本 #

Keycloak官方已推出针对Jakarta EE的适配包，建议升级到23.x及以上版本，同时替换原有依赖：

• 将原keycloak-oidc-adapter等Java EE版本依赖，替换为keycloak-jakarta-oidc-adapter
• 确保项目中所有Servlet相关依赖统一使用Jakarta EE版本（如jakarta.servlet:jakarta.servlet-api）

2. 改用Jakarta Servlet Filter适配方案 #

放弃传统的Tomcat Valve配置，使用官方推荐的基于Jakarta Servlet Filter的适配方式：

• 引入keycloak-jakarta-servlet-filter-adapter依赖
• 在web.xml或通过注解配置Keycloak Filter及映射规则，替代原Valve配置
• 同步配置realm地址、认证服务器地址等Keycloak初始化参数

3. 临时使用API桥接工具（仅过渡用） #

若暂时无法升级适配器，可使用Tomcat提供的迁移桥接工具，实现javax.servlet到jakarta.servlet的调用转换：

• 引入依赖org.apache.tomcat:tomcat-jakartaee-migration
• 在Tomcat启动参数中添加-Dorg.apache.tomcat.jakartaee-migration.enabled=true启用转换
• 注意：该方案为临时过渡方案，存在兼容性风险，不建议长期使用

内容的提问来源于stack exchange，提问作者cypre-midi