Spring Boot 3.0升级SAML SSO时的Servlet API兼容性问题咨询

核心问题根源 #

spring-security-saml2-core 1.x系列基于javax.servlet栈开发，而Spring Boot 3.x完全切换到Jakarta EE栈（jakarta.servlet），两者API包路径不兼容，直接升级依赖必然引发类加载冲突。

具体迁移步骤 #

1. 替换SAML依赖 #

• 移除所有spring-security-saml2-core相关依赖（包括1.0.10.RELEASE版本）
• 引入Spring Security官方的Jakarta兼容版SAML2依赖：

  <!-- Maven 配置 -->
  <dependency>
      <groupId>org.springframework.security</groupId>
      <artifactId>spring-security-saml2-service-provider</artifactId>
  </dependency>
  

  依赖版本由Spring Boot 3.x的parent自动管理，无需手动指定。

2. 代码适配调整 #

• 替换旧API类：
  • 将原SAMLAuthenticationProvider、SAMLEntryPoint等类，替换为Spring Security 6.x中的Sam2AuthenticationToken、RelyingPartyRegistration等新类
  • 自定义断言解析、用户信息映射逻辑，需适配新的Saml2AuthenticatedPrincipal接口
• 重构配置逻辑：
  • 原XML或旧Java配置方式，替换为基于RelyingPartyRegistrationRepository的配置，或直接在application.yml中配置身份提供商（IdP）元数据：

    spring:
      security:
        saml2:
          relyingparty:
            registration:
              idp1:
                identityprovider:
                  entity-id: "https://your-idp.com/entity"
                  singlesignon:
                    url: "https://your-idp.com/sso"
                    binding: "POST"
                  metadata-uri: "https://your-idp.com/metadata"
    

3. 清理依赖冲突 #

• 用Maven命令排查依赖树，找出并排除所有残留的javax.servlet相关依赖：

  mvn dependency:tree | grep javax.servlet
  

  在pom.xml中对冲突依赖添加<exclusions>标签：

  <dependency>
      <groupId>第三方依赖组ID</groupId>
      <artifactId>第三方依赖包ID</artifactId>
      <exclusions>
          <exclusion>
              <groupId>javax.servlet</groupId>
              <artifactId>javax.servlet-api</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

• 确保所有其他第三方依赖都升级到支持Jakarta EE的版本（将javax.*包的依赖替换为jakarta.*版本）

4. 验证测试 #

• 先验证IdP元数据是否能正常加载，检查RelyingPartyRegistration的配置正确性
• 测试完整SSO流程：发起登录请求、跳转IdP、回调断言解析、用户身份认证
• 测试SLO（单点注销）流程，确保会话同步清理

关键注意事项 #

• spring-security-saml2-core 1.x已停止维护，官方不再提供Jakarta兼容更新，迁移到官方新SAML2模块是唯一长期可行的方案
• 若有自定义SAML扩展逻辑（如自定义签名验证、断言转换），需重新基于Spring Security 6.x的SAML2 API实现
• 建议先在测试环境完成迁移验证，再逐步推向生产环境

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