Download the PHP package php-soap/psr18-wsse-middleware without Composer

SOAP WSSE/WSA Middleware

This package provides the tools you need in order to add WSSE and WSA security to your PSR-18 based SOAP Transport.

Want to help out? 💚

• Become a Sponsor
• Let us do your implementation
• Contribute
• Help maintain these packages

Want more information about the future of this project? Check out this list of the next big projects we'll be working on.

Installation

This package includes the php-soap/psr18-transport package and is meant to be used together with it. It is a middleware wrapper for the wse-php package of robrichards package.

Usage

WsaMiddleware

If your remote server expects Web Service Addressing (WSA) headers to be available in your request, you can activate this middleware. The middleware is a light wrapper that makes it easy to use in your application.

In case you need WSA w3c 2005 based Web Service Addressing, you should use WsaMiddleware2005.

WsseMiddleware

Oh boy ... WS-Security ... can be a real pain ! This package aims for being as flexible as possible and provides you the tools you need to correctly configure Web Service Security. The components are shaped based on the WS-Security UI inside SoapUI. This enables you to configure everything the way your SOAP server wants you to! If you have a working config on SoapUI, you can transform it to PHP code by following the entries and their configurations.

Usage:

The WSSE middleware can be built out of multiple configurable entries:

• BinarySecurityToken
• Decryption
• Encryption
• SamlAssertion
• Signature
• Timestamp
• Username

Underneath, there are some common examples on how to configure the $wsseMiddleware.

Adding a username and password

Some services require you to add a username and optionally a password. This can be done with following middleware.

Key stores

This package provides a couple of Key wrappers that can be used to pass private / public keys:

• KeyStore\Certificate: Contains a public X.509 certificate in PEM format.
• KeyStore\Key: Contains a PKCS_8 private key in PEM format.
• KeyStore\ClientCertificate: Contains both a public X.509 certificate and PKCS_8 private key in PEM format.

Example:

In case of a p12 certificate: convert it to a private key and public X509 certificate first:

Signing a SOAP request with PKCS12 or X509 certificate.

This is one of the most common implementation of WSS out there. You are granted a certificate by the soap service with which you need to fetch data.

Next, you can configure the middleware like this:

This example can also be used in combination with signing and username authentication.

Authorize a SOAP request with a SAML assertion

Another common implementation is authentication through a WS-Trust compliant STS instance. In this case, you first have to fetch a SAML assertion from the STS service. Most of them require you to sign the request with a X509 certificate. This can be done with the middleware above.

Once you received back your SAML assertion, you have to pass it to the webservice you want to contact. A common configuration for passing the SAML assertion might look like this:

Encrypt sensitive data

Some services require you to encrypt sensitive parts of the request and decrypt sensitive parts of the response. In this case, you can add your public key to the request, encrypt the payload and send it over the wire. Incoming responses will be encrypted with your public key and kan be decrypted by using your private key.

Encryption contains a known bug in the underlying robrichards/wse-php library. Since a fix has not been merged yet, you can apply a patch like this:

The configuration for encryption looks like this:

Note: Encryption only can also be done without adding a signature.