15 January 2008 - 2.0.1 home user-guide eclipse intellij netbeans maven PDF files forums bugs sourceforge eviware.com






WS-Security

This document will give an overview on how to configure WS-Security related settings in soapUI. It does not strive to explain WS-Security and related standards themselves, please seek this information elsewhere!

soapUI manages WS-Security-related configurations at the project level, allowing these configurations to be used at several places within a project:

  • For outgoing requests and their responses, see Requests
  • For incoming requests to MockServices and their MockResponses, see MockServices
  • For monitored requests and their monitored responses, see SOAP Monitors

soapUI defines three types of objects that need to be configured to enable WS-Security:

  • KeyStores / Certificates - hold keys / certificated to be used for encryption/decryption/signing/verification.
  • Outgoing WSS - configurations to be applied to outgoing messages, either requests or MockResponses
  • Incoming WSS - configurations to be used for decrypting/verifying incoming messages containing WS-Security tokens; responses, mock-requests or monitored requests/responses

All these are managed from the WS-Security tab in the Project View and then applied to their desired targets at corresponding locations

Usage

The basic flow to enable WS-Security is the following:

  1. Add your Keystores/Certificates to the Keystores tab.
  2. Create relevant Outgoing WSS and Incoming WSS configurations
  3. Associate the created configurations with your desired endpoints/requests/mockresponses/etc..

Once a configuration has been associated with (for example) a request, it will be automatically applied when sending the request and receiving its response. You can see the actual message with all the applied WSS-tokens in the http log or the "Raw" editor tab in the request and MockResponse editors.

Keystores

The Keystores / Certificates tab allows you to add an arbitrary number of keystores and certificate-files to your WS-Security configuration. These should contain the corresponding Key Material to be used for security-related processing.

Add add new Keystore or Certificate by selecting the Add button in the toolbar, browse to the corresponding file and press ok. You will be prompted for the password to the file and it will be added to the list, the Status column will display if loading went ok.

The following columns are available in the Keystores table:

  • Source : the source file of the keystore/certificate (Read Only)
  • Status : the load-status of the keystore/certifcate (Read Only
  • Password : the keystore password if required
  • Default Alias : the default alias in a keystore to use for validation/decryption
  • Default Password : the password for default alias
  • Security Provider : the JSSE Security Provider to use for handling certificates

Outgoing WSS

Outgoing WSS configurations are used for processing outgoing messages; encrypting, signing, etc. Each configurations contains a configurable number of "WSS Entries", each corresponding to some WSS-related action to be taken on the outgoing message.

The table on the top contains the currently configured configurations, add new ones with the "Add" button in the tables toolbar, which will prompt for a unique name for the configuration. In the table it is also possible to set default username/password values for the configuration, which will be used be the configurations WSS Entries where applicable.

When selecting a configuration in the table, the lower half of the window will show the currently configured entries for that configuration as tabs;

Add new entries to the selected configuration with the Add Entry toolbar button on top of the tab panel. Any number of entries can be added; entries are applied in the order they are shown in the tabpanel. The following types of entries are currently available:

  • Encryption - Encrypts outgoing message content. Specify which Keystore to use and the desired alias/password. The parts table at the bottom allows you to selectively encrypt only subsets of the message content (if left empty the entire message will be encrypted); either specify an ID which corresponds to a WS-Security ID attribute in the message content, or the name/namespace of the element to be encrypted.
  • Signature - Signs outgoing message content. Specify which Keystore to use and the desired alias/password. The parts table at the bottom allows you to selectively sign only subsets of the message content (if left empty the entire message will be encrypted); either specify an ID which corresponds to a WS-Security ID attribute in the message content, or the name/namespace of the element to be signed.
  • Username - adds a UsernamePassword token to the outgoing message, specify the username and password to use and if nonce/created should be added (recommended). The Password Type drop-down selects how the password should be serialized in the message. The "PasswordDigest Ext" option is non-standard and should only be used for interop issues where the message receiver desires an extra MD5 Hash of the password.
  • Timestamp - adds a Timestamp token to the ougoing message with the specified Time-To-Live value.
  • SAML - adds a SAML assertion to the ougoing message with the specified assertion content.

Incoming WSS

Incoming WSS configurations are used to process incoming messages (responses, MockRequest and monitor requests/response) and decrypt/validate their encrypted/signed content. Since the WS-Security headers of an incoming message contain most of the information required to decrypt/validate a message, the only configuration needed by soapUI is which keystores that contain referenced keys/certificates for decryption and signature validation.

Add new Incoming WSS configurations using the "Add" toolbar button on top of the table, you will be prompted for a unique name for the configuration and can then further associate the keystores to use for decryption/validation in the table. Optionally specify the password required for validating signatures (if not specified and required, a popup will be shown during the validation process).

When receiving a message with an associated Incoming WSS configuration in one of the request/MockResponses editors, the results of the processing will be shown in the "WSS" Inspector for the corresponding message. The inspector shows a list of processing results and any errors that may have occurred:

For testing, there is also a WS-Security Status Assertion that can be added to a TestRequest step for validating that the WS-Security headers were valid in the received response.


Next: