Apache WSS4J 4.0.2 介绍与选型指南

一、信息基准

本章列明本文事实性信息的核查时间与来源，全部信息取自 Apache WSS4J 官方渠道，不含本地实测推算。

1.1 版本基准

1.2 官方来源清单

二、软件概述

本文介绍的是 Apache WSS4J 4.0.2。官方定义：WSS4J 提供 OASIS Web Services Security（WS-Security）系列规范的 Java 实现，覆盖 OASIS Web Services Security TC 制定的主要安全标准。

官方用户指南给出的技术定位是：WSS4J 面向 Apache CXF、Apache Axis 这类 Web 服务栈使用，为 SOAP 消息提供安全能力；底层加密能力来自 Apache Santuario（XML Security）。它是 Java 生态中 WS-Security 事实上的基础实现库——通常不直接出现在业务代码里，而是由 CXF 等服务框架集成后对外提供声明式安全配置。

版本线方面，官网"Supported versions"明确三条活跃维护线：4.0.x（JDK 17 基线，Jakarta 版本）、3.0.x（JDK 11 基线，Jakarta 版本）、2.4.x（JDK 8 基线，非 Jakarta）。2026-09 三线同步发布了 4.0.2、3.0.6、2.4.4，官方说明其中包含多项安全修复。

三、核心架构

3.1 标准实现矩阵

依据官网首页，WSS4J 实现以下 WS-Security 标准：

3.2 安全能力分层

官方用户指南把高层能力归纳为四类：消息机密性（Confidentiality）、消息完整性（Integrity）、消息认证（Authentication）、消息授权（Authorization）。实现机制上：

• 加密：借助 Apache Santuario 对 SOAP 消息加密，典型做法是加密 SOAP Body 与安全头中的 UsernameToken，同时支持对称与非对称加密，常规模式为先用随机对称密钥加密消息体再用公钥保护该对称密钥。
• 签名与令牌：通过 XML 数字签名与 WS-Security 令牌（UsernameToken、X.509 证书、SAML 断言、Kerberos 票据）实现完整性与认证。

3.3 依赖与版本支持矩阵

官网给出的官方支持矩阵（WSS4J 线 / JDK 下限 / XML Security / OpenSAML / Jakarta）：

四、功能特性

4.1 协议覆盖

• 一套库覆盖 WS-Security 全家桶：消息级加解密、签名、时间戳、UsernameToken、X.509、SAML 1.1/2.0 断言、Kerberos 票据、带附件消息（SwA）档案与 WS-I Basic Security Profile 合规（官网标准清单）。
• 与 Apache Santuario（XML Security）协同完成 XML 加解密与签名，与 OpenSAML 协同处理 SAML 断言（官网支持矩阵）。

4.2 Jakarta 与双栈过渡

• 4.0.x 与 3.0.x 均提供 Jakarta 命名空间版本，适配新一代 Jakarta EE 服务栈；2.4.x 保持传统 Java EE（javax）能力，供存量系统使用（官网矩阵 Jakarta 列）。

4.3 三线并行维护

• 2026-09 官方同月发布 4.0.2、3.0.6、2.4.4，并明确说明包含"significant number of bug fixes and security updates"，多个 CVE 在官方安全公告页公示。对无法升级运行时的存量系统，旧维护线仍在获得安全修复，这是 WSS4J 的突出运维优势。

五、快速上手

WSS4J 通常不单独使用，官方用户指南明确其设计目标是配合 Apache CXF 或 Apache Axis 等服务栈为 SOAP 消息提供安全能力。本文不做本地实测，以下为官方口径下的接入要点。

5.1 Maven 引入

核心构件在 Maven Central 的 groupId 为 org.apache.wss4j，以最新稳定版 4.0.2 为例（构件目录 https://repo1.maven.org/maven2/org/apache/wss4j/ ）：

<dependency>
    <groupId>org.apache.wss4j</groupId>
    <artifactId>wss4j-ws-security-dom</artifactId>
    <version>4.0.2</version>
</dependency>

运行要求（官网支持矩阵）：该版本线要求 JDK 17，并搭配 XML Security 4.0.x 与 OpenSAML 5.x。

5.2 与 Apache CXF 集成的典型路径

官方用户指南指出的标准用法：在 CXF 服务端/客户端上声明 WS-SecurityPolicy（如签名、加密、UsernameToken 策略），由 CXF 内部调用 WSS4J 完成安全头的生成与校验。安全属性（签名密钥、信任库、回调密码处理器等）通过 CXF 的配置属性传入，具体回调接口（如密码回调 handler）以官方 Using Apache WSS4J 文档为准。

5.3 版本线选择

• 新项目（Jakarta EE / 现代 JDK）：选 4.0.x（JDK 17+）。
• JDK 11 运行时的中间态项目：选 3.0.x。
• 只能运行在 JDK 8 的存量系统：选 2.4.x（无 Jakarta 支持）。

六、适用场景与限制

6.1 适用场景

• 政企金融等仍以 SOAP/WSS 报文规范对接的集成场景（SAML 断言、X.509 签名加密、Kerberos 票据等）。
• 已有 CXF/Axis 服务栈需要补充企业级消息安全的项目。
• 需要跨组织端到端消息级安全的 B2B 集成（传输层 TLS 之外的报文级完整性/机密性要求）。
• 存量系统分批升级：2.4.x → 3.0.x → 4.0.x 三线并存，允许按 JDK 升级节奏分阶段迁移。

6.2 已知限制

• 只覆盖 WS-Security 体系，不提供 OAuth2/JWT 等现代令牌机制（该类需求应选 OAuth/OIDC 栈，见第七章）。
• 配置复杂度较高：密钥管理、信任链、策略文件都需要专业安全知识。
• 4.0.x 要求 JDK 17，老运行时只能选择旧维护线。
• GitHub 关注度低（官方仓库 ws-wss4j stars 46），社区讨论以 JIRA 与邮件列表为主，遇问题更依赖官方文档。

七、同类选型对比

7.1 对比对象与数据基准

选取三类可比对象：Apache CXF（内置 WSS4J 的服务栈，WS-Security 的上层集成形态）、JJWT（现代 JWT 库）、Spring Security（OAuth2/OIDC 与 JWT 的主流框架）。数据于 2026-10-18 取自各项目官方渠道（GitHub 仓库页、releases.atom、Maven Central）。

7.2 量化对比

补充说明：CXF 与 WSS4J 是同一体系的上层/底层关系（CXF 的 WS-SecurityPolicy 由 WSS4J 承接），选 CXF 即隐式选择了 WSS4J；JJWT 与 Spring Security 代表现代 JSON 令牌路线，解决的是"认证令牌"而非"报文级加解密签名"问题，与 WSS4J 并非同一问题域。

7.3 选型建议

对内对接方仍要求 WS-Security 报文安全时，直接用 CXF 4.x 并由其集成 WSS4J 4.0.x；只需要登录态 JWT 时选 JJWT 或 Spring Security 而不要引入 WS-Security；存量 JDK 8 SOAP 系统按 2.4.x 维护线获取安全修复并规划向 4.0.x 迁移。

八、参考链接

• 项目官网：https://ws.apache.org/wss4j/
• 官方用户指南：https://ws.apache.org/wss4j/user_guide.html
• 官方下载页：https://ws.apache.org/wss4j/download.html
• 安全公告：https://ws.apache.org/wss4j/security_advisories.html
• GitHub 仓库：https://github.com/apache/ws-wss4j
• Maven Central 构件目录：https://repo1.maven.org/maven2/org/apache/wss4j/