10 June 2009 - 3.0-beta-2 user guide eclipse intellij netbeans maven download nightly forum bugs blog sf.net eviware


Eviware Logo

WS-Security Configuration

This document will give an overview on how to configure Web Services Security, 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:

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, or verification.
  • Outgoing WSS - configurations to be applied to outgoing messages, either requests or MockResponses
  • Incoming WSS - configurations to be used for decrypting or verifying incoming messages containing WS-Security tokens; responses, MockRequests or monitored requests and 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.

Raw XML Editor with WS-Security

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.

A list of Certificates for Web Service Testing

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/certificate (Read Only
  • Password : the keystore password if required
  • Default Alias : the default alias in a keystore to use for validation or decryption
  • Default Password : the password for default alias
  • Security Provider : the JSSE Security Provider to use for handling certificates -> Removed in 2.5, if you need it back let us know!

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;

Configuring outgoing messageis for WS-Security

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 or namespace of the element to be encrypted.
  • Setting Encryption for Web Services

  • 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 or namespace of the element to be signed.
  • Setting Signature for Web Services

  • 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.
  • Setting Username for Web Services

  • Timestamp - adds a Timestamp token to the outgoing message with the specified Time To Live value. The millisecond-precision setting can be turned off for improved WCF compatibility.
  • Setting a timestamp for Web Services

  • SAML - adds a SAML assertion to the outgoing message with the specified assertion content.
  • Setting SAML for Web Services

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 or validate a message, the only configuration needed by soapUI is which keystores that contain referenced keys and certificates for decryption and signature validation.

Setting Configuration for Web Services

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 or 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:

Inspecting Web Services Security Results

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: Project JDBC Connections