WS-Security Plugin for JMeter
Apache JMeter plugin for signing, encrypting and decrypting SOAP messages (WS-Security).
The plugin provides
Supported are HTTP Request, JMS Publisher and JMS Point-to-Point samplers, SMTP and TCP sampler, as well as third party samplers that expose the payload via a JMeter StringProperty or a pair of getter/setter methods.
Under tab “Available Plugins”, select “WS Security for SOAP”, then click “Apply Changes and Restart JMeter”.
From the context menu, add the appropriate Pre or Post Processor to the test plan scope with the sampler containing the SOAP message.
The message to be signed or encrypted must be a valid SOAP message and must be in one of the following locations:
Note that the plugin does not assist with composing the message nor does it do any XML schema validation. Only the WS-Security header element will be inserted or modified. It is recommended to exclude the WS-Security header from the SOAP request and let the plugin generate it.
Users familiar with SoapUI will find similarities to the outgoing WS-Security configuration.
The keystore file is expected to contain all keys referenced in the SOAP message headers that are required for signing and/or encrypting/decrypting.
The default keystore type is JCEKS (since v1.7, before Java platform default).
Other keystore types can be used by defining the JMeter property jmeter.wssecurity.keystoreType
(since v1.8),
e.g. PKCS12, JKS, JCEKS.
The dropdown fields allow for the customization of most signature and encryption settings, depending on what the endpoint’s WSDL defines.
:warning: Not all setting combinations are valid, and JMeter does not enforce a valid combination to be entered. Instead, invalid ones will cause errors to be logged during runtime.
Example: Key Identifier Type “Encrypted Key SHA1” is only valid for symmetric Signature Algorithms (HMAC).
These lists are empty by default, however, that results in the SOAP Body content to be signed or encrypted.
Suppose the Timestamp element was to be included in the signature or encryption in addition to the Body element, both would have to be listed as follows:
ID | Name | Namespace | Encode |
---|---|---|---|
Body | http://schemas.xmlsoap.org/soap/envelope/ | ||
Timestamp | http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd |
If there are multiple XML elements with the same name and namespace, the element’s ID attribute can be used to determine which element is to be signed/encrypted. If the ID is specified, the Name and Namespace are not necessary and will not be used.
Example:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<element ID="e1">this should be encrypted</element>
<element ID="e2">this is not to be encrypted</element>
<element>another one</element>
</soap:Body>
</soap:Envelope>
ID | Name | Namespace | Encode |
---|---|---|---|
e1 |
Encode is only relevant for encryption (or attachments, see below) and can be one of the following:
The SOAP Message Decrypter takes a sampler’s response data as input, expecting a SOAP message with WS-Security header, and decrypts the payload based on the content of a given keystore. This requires the private key password of the encryption certificate.
Until plugin version 1.6 this password is expected in the field “Private Key Password”. As of version 1.7 it needs to be provided in the table Credentials for WSS Processing, along with the alias of the keystore entry.
Note: Due to the way the underlying wss4j library is implemented, any other, not encryption related security tokens in the response message will also be processed, for example signature tokens. Any such processing will fail if key information is not present. For example, should the response message include a symmetric signature token, the SOAP Message Decrypter needs the secret key that was used to generate the token.
The key(s) may be provided in the configured keystore, and the secret key password(s) can be listed in the table Credentials for WSS Processing. Likewise, if a response were to contain a Username Token, the password(s) for the expected username(s) can be listed in that table, so that the Post-Processor is able to validate the token.
Any WS-Security related exception encountered by the SOAP Message Decrypter while trying to decrypt or validate a response message will cause the sampler to fail and will create an assertion result, effectively behaving like an implicit assertion.
If this behaviour is not desired, it may be turned off via setting the JMeter property jmeter.wssecurity.failSamplerOnWSSException=false
.
Samplers that are not JMeter core functionality, such as JMeter-Plugins, can also be used if they provide either a JMeter StringProperty or a public String getter/setter to access the sampler’s payload with the SOAP message.
In that case, the JMeter property jmeter.wssecurity.samplerPayloadAccessors
can be set to specify the class name and property name as in the following examples.
The SMTP Sampler stores the payload in the TestElement property “SMTPSampler.message”.
So, it would be configured for this plugin via
jmeter.wssecurity.samplerPayloadAccessors=org.apache.jmeter.protocol.smtp.sampler.SmtpSampler."SMTPSampler.message"
.
Note the quotes around the property name if it contains a dot.
Alternatively, if there is no such JMeter property, a Bean property can be used (without the get/set prefix), which the Pre-Processor will access at run time via Reflection.
Suppose a sampler like the following:
package some.package;
public class SomeSampler extends AbstractSampler {
public String getPayload()
// ...
public void setPayload(String content)
// ...
}
Then the JMeter property should be set like so: jmeter.wssecurity.samplerPayloadAccessors=some.package.SomeSampler.payload
More than one of these can be comma separated (if really required).
SOAP Message Attachments can be digitally secured or validated/decrypted by the plugin. However, the attachment data must be explicitely provided and must match the attachment(s) transmitted by the sampler, i.e. the plugin is unable to automatically access samplers’ attachments. To do this, the below lists (Attachments to Sign/Encrypt/Decrypt) have to be filled in with one row for each attachment.
Additionally, for SwA attachments, the special ID cid:Attachments
needs to be added to the “Parts to Sign”/”Parts to Encrypt” (without Name or Namespace).
The Encode column can be either:
Content-Description
, Content-Disposition
, Content-ID
, Content-Location
, Content-Type
.An attachment is identified by its Content-ID (cid:
) and consists of a sequence of bytes and (optionally) some headers.
The following columns need to be populated accordingly:
__groovy()
function,
such as ${__groovy(new File('secret.xml').bytes.encodeBase64())}
${__char(13)}
.The Content-ID, Bytes and Headers columns have the same semantics as above.
After encrypting an attachment, the plugin can make the encrypted data available to the sampler for transmission. This can be done is a few different ways. The following columns determine how the plugin stores the output:
byte[]
(variable name as per “Output Destination” column)byte[]
(context map key as per “Output Destination” column)Notes:
Attachment-Complete
as above), headers will be contained within the encrypted data.
However, this plugin cannot modify the headers sent by the sampler, so the user needs to ensure
that sensitive headers are removed from the attachment part.Content-Type
header value may be required for the <xenc:EncryptedData>
MimeType attribute
as per processing rules,
so the user needs to provide it in the Headers column.The plugin can also decrypt response attachments. They need to be listed as follows:
__groovy()
accessing ctx.previousResult.subResults
,
depending on how the sampler handles response attachments.
Example: ${__groovy(ctx.previousResult.subResults[0].responseData.encodeBase64())}
Note: If an attachment is referenced in the response’s WSS header but not included in the “Attachments to Decrypt” list, response validation will fail.
The decrypted attachment content (and possibly headers) will be stored as a sub-sample of the main sample. The plugin will try to find a sub-sample that matches the attachment’s Content-ID and if a match is found replace the sub-sample, or otherwise create a new sub-sample and add it to the main sample.
The search is done via recursively traversing all sub-samples (depth-first), and looking at either the sub-sample’s Content-ID response header
or the sub-sample’s label.
This can be configured via the JMeter property jmeter.wssecurity.findAttachmentsBySampleLabel
:
Example:
Suppose a sampler generates a main sample with an attachment sub-sample “somecontentid (text/xml)” but does not set the Content-ID header.
Using the property value jmeter.wssecurity.findAttachmentsBySampleLabel=(.*) \(.*\)
this sub-sample will be identified based on the first matcher group “somecontentid”.
The signed or encrypted message payload can be inspected via “View Results Tree”.
To avoid common problems, make sure that:
It may be useful to increase the logging level in order to investigate any keystore or encryption related issues,
for example by adding --loglevel=org.apache.wss4j=DEBUG
to the JMeter command line.
It may also be helpful to inspect server side logs, especially for HTTP 500 type responses, unspecific SOAP Fault messages etc.