最近在负责一个项目，需要与一个老旧但核心的SOAP服务进行数据交互。这个服务对安全性要求极高，不仅需要基本的用户名密码认证，还强制要求对请求进行数字签名，并且需要特定的WS-Addressing头。
你是否也曾遇到过这样的场景？当SOAP服务的文档摆在你面前，里面充斥着WSSE、WSA、X.509证书、xml数字签名、时间戳等各种术语，你是不是瞬间感到一阵眩晕？我当时就是这样。
尝试过最初的方案，是手动拼接XML，或者使用一些老旧的SOAP客户端，但很快就遇到了瓶颈：
- 复杂且易错的XML操作： WSSE头部的结构非常复杂，包含各种命名空间、元素顺序、时间戳、二进制安全令牌、签名信息等。手动构建或修改这些XML字符串，就像在走钢丝，一个字符的错误都可能导致服务拒绝。
- 证书和密钥管理： 数字签名需要用到私钥和公钥证书。如何安全地加载、使用这些密钥，并正确地将它们嵌入到XML中，成了一个大难题。
- 调试困难： 当请求被拒绝时，SOAP服务通常只会返回一个模糊的错误信息，很难定位是WSSE头部的结构问题、签名问题，还是证书配置问题。
- 缺乏灵活性： 不同的SOAP服务可能有不同的WSSE配置要求（例如，签名算法、摘要算法、KeyIdentifier类型）。手动方案很难快速适应这些变化。
眼看项目进度受阻，我开始寻找一个更现代、更健壮的解决方案。这时，composer的强大生态再次展现了它的魅力。
Composer在线学习地址：学习地址
立即学习“PHP免费学习笔记（深入）”；
我发现了 php-soap/psr18-wsse-middleware 这个库，它简直是我的救星！这个包是为基于PSR-18的http SOAP传输而设计的中间件，它能将复杂的WSSE和WSA安全逻辑封装起来，让我们以更简洁、更PHP友好的方式进行配置。
核心思想：中间件与可配置条目
php-soap/psr18-wsse-middleware 的核心在于它作为一个PSR-18 HTTP客户端的中间件，可以轻松地插入到你的HTTP请求流程中。它将WSSE的各种安全特性抽象为一系列可配置的“条目（Entry）”，例如：Username、timestamp、BinarySecurityToken、Signature、Encryption 等。你只需要根据SOAP服务的具体要求，组合这些条目即可。
如何使用它解决问题？
首先，通过Composer安装它：
<code class="bash">composer require php-soap/psr18-wsse-middleware</code>
这个包通常与 php-soap/psr18-transport 配合使用，后者提供了PSR-18标准的SOAP传输能力。
1. 添加WS-Addressing (WSA) 头
如果你的SOAP服务需要WSA头（例如，Action、To 等），你可以使用 WsaMiddleware 或 WsaMiddleware2005。
<pre class="brush:php;toolbar:false;">use HttpClientCommonPluginClient; use SoapPsr18TransportPsr18Transport; use SoapPsr18WsseMiddlewareWsaMiddleware; use SoapPsr18WsseMiddlewareWsaMiddleware2005; use GuzzleHttpClient as GuzzleClient; // 假设你使用Guzzle作为PSR-18客户端 $psr18Client = new GuzzleClient(); // 你的PSR-18兼容HTTP客户端 $transport = Psr18Transport::createForClient( new PluginClient($psr18Client, [ new WsaMiddleware(), // 或 new WsaMiddleware2005()，取决于WSA版本 ]) ); // 接下来，你可以使用这个 $transport 对象来发送SOAP请求 // ...
通过简单的实例化和添加到插件客户端，WSA头就自动注入到你的SOAP请求中了，省去了手动构建XML的麻烦。
2. 实现WS-Security (WSSE)
这才是真正的“大头”。WsseMiddleware 允许你配置各种WSSE条目。它的设计理念非常棒，如果你在SoapUI中配置过WS-Security，你会发现这里的PHP代码结构与SoapUI的UI配置非常相似，这极大地降低了学习成本。
示例一：添加用户名和密码认证
这是最常见的WSSE需求之一。
<pre class="brush:php;toolbar:false;">use SoapPsr18WsseMiddlewareWsseMiddleware; use SoapPsr18WsseMiddlewareWSSecurityEntry; use HttpClientCommonPluginClient; use SoapPsr18TransportPsr18Transport; use GuzzleHttpClient as GuzzleClient; $user = 'myUsername'; $password = 'myPassword'; $wsseMiddleware = new WsseMiddleware( outgoing: [ (new EntryUsername($user)) ->withPassword($password) ->withDigest(false), // 如果密码不需要摘要，设置为false new EntryTimestamp(60), // 添加一个有效期60秒的时间戳 ] ); $transport = Psr18Transport::createForClient( new PluginClient(new GuzzleClient(), [ $wsseMiddleware, ]) ); // 使用 $transport 发送SOAP请求，WSSE头会自动添加
几行代码，就完成了复杂的用户名密码和时间戳注入，比手动拼接XML要清晰和安全得多。
示例二：使用X.509证书对请求进行数字签名
这是我遇到的最棘手的问题之一。服务要求使用PKCS12证书进行签名。这个库提供了 KeyStore 类来管理密钥和证书。
<pre class="brush:php;toolbar:false;">use SoapPsr18WsseMiddlewareWsseMiddleware; use SoapPsr18WsseMiddlewareWSSecurityEntry; use SoapPsr18WsseMiddlewareWSSecurityKeyStoreCertificate; use SoapPsr18WsseMiddlewareWSSecurityKeyStoreKey; use SoapPsr18WsseMiddlewareWSSecurityKeyIdentifier; use SoapPsr18WsseMiddlewareWSSecuritySignatureMethod; use SoapPsr18WsseMiddlewareWSSecurityDigestMethod; use HttpClientCommonPluginClient; use SoapPsr18TransportPsr18Transport; use GuzzleHttpClient as GuzzleClient; // 假设你的私钥和公钥证书文件 $privateKeyFile = 'path/to/security_token.priv'; // 从PKCS12转换出的私钥 $publicKeyFile = 'path/to/security_token.pub'; // 从PKCS12转换出的公钥证书 $passphrase = 'your_key_passphrase'; $privKey = Key::fromFile($privateKeyFile)->withPassphrase($passphrase); $pubKey = Certificate::fromFile($publicKeyFile); $wsseMiddleware = new WsseMiddleware( outgoing: [ new EntryTimestamp(60), new EntryBinarySecurityToken($pubKey), // 将公钥证书作为二进制安全令牌 (new EntrySignature( $privKey, new KeyIdentifierBinarySecurityTokenIdentifier() // 指定签名时使用二进制安全令牌作为标识 )) ->withSignatureMethod(SignatureMethod::RSA_SHA256) // 签名算法 ->withDigestMethod(DigestMethod::SHA256) // 摘要算法 ->withSignAllHeaders(true) // 签名所有SOAP头 ->withSignBody(true) // 签名SOAP Body ] ); $transport = Psr18Transport::createForClient( new PluginClient(new GuzzleClient(), [ $wsseMiddleware, ]) ); // 现在，你的SOAP请求会自动包含签名和证书信息
这段代码清晰地展示了如何加载密钥、配置签名算法、摘要算法以及签名范围。它将所有复杂性封装在 EntrySignature 对象中，我们只需提供正确的参数，大大降低了出错的概率。
示例三：加密和解密敏感数据
某些服务甚至要求对SOAP请求或响应中的敏感部分进行加密。php-soap/psr18-wsse-middleware 也提供了 EntryEncryption 和 EntryDecryption。
<pre class="brush:php;toolbar:false;">// ... (密钥和证书加载与签名类似) $wsseMiddleware = new WsseMiddleware( outgoing: [ // ... 其他如Timestamp, BinarySecurityToken, Signature 条目 (new EntryEncryption( $signKey, // 用于加密的公钥证书 new KeyIdentifierX509SubjectKeyIdentifier($signKey) )) ->withKeyEncryptionMethod(KeyEncryptionMethod::RSA_OAEP_MGF1P) ->withDataEncryptionMethod(DataEncryptionMethod::AES256_CBC) ], incoming: [ new EntryDecryption($privKey) // 用于解密响应的私钥 ] ); // ...
注意：官方文档提到，加密功能在底层库中存在一个已知bug，并提供了Composer补丁的解决方案。这体现了在实际使用中需要关注细节和社区支持。
总结其优势和实际应用效果
使用 php-soap/psr18-wsse-middleware 之后，我深刻体会到了它带来的巨大优势：
- 告别XML噩梦： 最直接的感受就是再也不用手动去拼接和解析复杂的WSSE/WSA XML头了。库内部处理了所有细节，大大减少了出错的可能性。
- 开发效率大幅提升： 以前需要花费数天甚至一周来调试和解决的SOAP安全认证问题，现在通过阅读文档和配置几个
Entry对象，往往只需几个小时就能搞定。 - 代码可读性和可维护性增强： 清晰的面向对象API，让WSSE配置逻辑一目了然。当服务方调整安全要求时，我们只需修改或添加相应的
Entry，而不是修改大段的XML字符串。 - 高度灵活性： 它支持多种WSSE/WSA标准和算法，无论是用户名密码、数字签名、时间戳、SAML断言，还是加密解密，都能轻松应对。这使得它能够适应各种复杂的SOAP服务集成场景。
- 现代化集成： 基于PSR-18 HTTP客户端，使得它可以与现代PHP生态中的HTTP客户端（如Guzzle）无缝集成，符合现代php开发的最佳实践。
在我的项目中，通过引入 php-soap/psr18-wsse-middleware，我们成功地与遗留的SOAP服务建立了安全、稳定的连接，并按时完成了项目交付。它不仅解决了技术难题，更重要的是，将开发者从繁琐且易错的SOAP安全配置中解放出来，让我们能够专注于业务逻辑的实现。
如果你也在为SOAP服务的WSSE/WSA安全认证而烦恼，强烈推荐你尝试一下 php-soap/psr18-wsse-middleware。它将是你在SOAP集成之路上的得力助手！