Examine allows for creating two types of global security configurations that can be used to apply WS-Security to SOAP requests -

Non-policy security configuration
Policy-based security configuration

This feature allows for applying existing configurations to SOAP scenarios instead of re-creating them for individual SOAP scenarios.

To create a new global security configuration click on Security->Security Configurations->Add to open the New Security Configuration dialog as shown below and specify a unique configuration name and click OK:


The list of all available security configurations in displayed in a tree view grouped under the respective configuration type node as shown below:


The Non-Policy security configuration requires a manual approach to configuring the outbound and inbound SOAP message security. There is no WS-SecurityPolicy involved in this configuration. The advantage of this approach is that it is possible to create request-only, response-only or request-response security configurations that can be applied to a SOAP scenario.

To enable WS-Security for the SOAP request sent to the WS endpoint, click on the Enable Request Security checkbox in the selected non-policy configuration. The following types of security actions can be added for the outbound request:


This assertion can be used to sign elements of a SOAP request and add a signature to the WS-Security SOAP header.


To be able to sign parts of the SOAP message, a valid keystore, which contains a private key must have been already configured. Without selecting a private key alias, it is not possible to sign the outbound message.   So the first step is to click on the Select… button to bring up the keystore alias dialog.


This dialog will list all keystores currently uploaded by the current user.  

After a private key alias is selected, it is displayed next to the Select… button

The ‘Sign Body’ and ‘Sign TimeStamp’ checkboxes are convenient options to quickly enable signing either the SOAP Body element, Timestamp element (if the Timestamp assertion was also configured) or both.  

If however, you would like to sign another part of the SOAP message, like a particular XML element within the SOAP Body, then click on the Add Part button. This will add a new row in the parts table as shown below. Here you can specify the XML element ID or the element name and its namespace. You can also specify whether the element itself or its content should be signed using the Mode combo box.


Note

Unlike adding a part for the Signature / Encryption action when creating a SOAP scenario specific security configuration, there is no dialog shown to select the XML element. This is because when creating a global security configuration, there is no SOAP scenario / request XML available. So you have to specify the element details manually.

To delete a previously added part, select the checkbox on the appropriate row and click on Delete

Advanced configuration for Signature

Sometimes the default signature options used may not be appropriate for the service being invoked. In this case, the advanced configuration link can be clicked to reveal fields that can be used to specify the Key Identifier or Signature Algorithm or Digest Algorithm to use during the process of signing the request contents.

For e.g. the default signature algorithm is http://www.w3.org/2000/09/xmldsig#dsa-sha1 which may not be appropriate if you are using a private key that is RSA-based. Check to make sure that the service provider specified signature requirements are followed to ensure that signature verification succeeds at the provider side.


This assertion can be used to encrypt parts of the SOAP message before it is sent to the service provider. The encrypted references are added in the generated WS-Security header.

In Public-Key cryptography, to encrypt something, you would need the public key of the recipient, since only the holder of the corresponding private key can decrypt the encrypted message. This means that a truststore that contains the recipient’s public key must have been configured prior to configuring this assertion. The figure below shows the available configuration options for this assertion:


The first step is to select the certificate that holds the public key used to encrypt the desired parts of the SOAP request message. Click on Select... to open a dialog to select the certificate alias from the list of available keystores as shown below:


Selecting SOAP Parts to encrypt

The Encrypt Timestamp and Encrypt Body Contents checkboxes provide convenient options to specify that the <wsu:Timestamp/> element (if the Timestamp assertion is configured as well) and the contents of the SOAP Body element must be encrypted.

To specify any other SOAP Envelope content, you have to click on the Add Part button to add a new row in the parts table as shown below:


Either the Element ID or a combination of the Element Name and Namespace must be specified to correctly select the element to be encrypted.

The Mode element specifies whether the selected element itself or the contents of the element must be encrypted.

Important

Do not add the SOAP Body element as a part to be encrypted with the Mode value set to Element. This can cause the Body element itself to be encrypted resulting in an invalid SOAP message!

Advanced Configuration


The advanced configuration section allows for configuring the Key Identifier, Encryption Algorithm or the Key Transport Algorithm to use when encrypting the selected SOAP request elements.

Note

These advanced configuration values will need to be selected depending on what the service provider expects

The Binary Security Token (BST) action allows for adding a X.509 Token to the WS-Security header of the outbound request as a <wsse:BinarySecurityToken/> element.

Sometimes it is required to send a X.509 certificate as a BST to the service provider to identify the client. Note that by itself this assertion really does not provide any security as the BST contains the public key of the client in Base64 encoding which is usually publicly known.


To specify the X.509 certificate to be used, click on the Configure link button to open the Keystore Alias selection dialog. Note that this dialog will allow you to select a private key alias only. The public key corresponding to the selected private key will be used to retrieve the certificate to be sent to the service.

The Use Single Certificate option decides whether just a single certificate or the entire certificate chain of the selected certificate will be sent to the service.  

Important

A current limitation when using this assertion is that it cannot be used by itself. If this assertion is added, another security assertion must be used along with it (like Timestamp Assertion).   Below is a sample request that uses both the Timestamp and Binary Security tokens.

  <?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header>
        <wsse:Security
            xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
            SOAP-ENV:mustUnderstand="1">
            <wsse:BinarySecurityToken
      EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
                ValueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3"
                wsu:Id="X509-B74EEF2C264E73ABB813137954338364"
                >MIICNjCCAZ8CBEo1POgwDQYJKoZIhvcNAQEEBQAwYjELMAkGA1UEBhMCSU4xCzAJBgNVBAgTAk1QMQ8wDQYDVQQHEwZJTkRPUkUxDz
  ANBgNVBAoTBkFwYWNoZTEMMAoGA1UECxMDRGV2MRYwFAYDVQQDEw1NYXlhbmsgTWlzaHJhMB4XDTA5MDYxNDE4MDk0NFoXDTE5MDYxMjE4MDk0NFowYjEL
  MAkGA1UEBhMCSU4xCzAJBgNVBAgTAk1QMQ8wDQYDVQQHEwZJTkRPUkUxDzANBgNVBAoTBkFwYWNoZTEMMAoGA1UECxMDRGV2MRYwFAYDVQQDEw1NYXlhb
  msgTWlzaHJhMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCdPhcimx7/CFX4H8isKEKCbRK6Kr+qeCMCby9I/Q/NY1bNqy6nsD+Y5BxSc2yCUnyLsR
  dmAHIxUwRQ9X5s8FP9+T1nwuoPzBvjcoZqWgDhe9RvydkijuzsFan/PY4oemd5EIoQu80ZpcFqb00xyDY3DkPgymXNsZ2uAM1ccsx90QIDAQABMA0GCSq
  GSIb3DQEBBAUAA4GBAGXIE7pFNInlyjHnq89zgvHJfZNE44El6Cd5V55JvL+LZUnynU2Y8WaUwD2Qvc1QTr9R7u6nhZ8abyB7TSx3idiN6KUSNtBHOeWU
  TmfGbAJqO/J6R2A9J20KCvss28D05rRI3z52VQHnMBzgirL6M5ClWBZfl2Q3bNKnOImjoNhK</wsse:BinarySecurityToken>
            <wsu:Timestamp wsu:Id="TS-2">
                <wsu:Created>…</wsu:Created>
                <wsu:Expires>…</wsu:Expires>
            </wsu:Timestamp>
        </wsse:Security>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
        <x1:sayHi xmlns:x1="http://cxf.apache.org/hello_world_soap_http/types"/>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

It is also possible to create a global WS-SecurityPolicy based Security Configuration that can be reused across multiple SOAP scenarios. This type of security configuration is a combination of a WS-SecurityPolicy and the required configuration data. The security policy must have been previously uploaded as detailed here. The figure below shows the configuration screen for a policy-based security configuration:


Specify a unique name for the security configuration and select the Policy file to use for this configuration. Click on Refresh to reload the available policies.

The policy file by itself usually does not contain the required configuration data (like keystore or truststore to use, or the username / password to send). To satisfy the policy requirements, the runtime policy parameters must be specified. Following are the list of available configuration parameters that can be specified:

By default, Examine does not verify if the response from the Web Service conforms to the selected WS-SecurityPolicy. To enable checking if the response is valid according to the policy, the Verify Reponse conforms to policy checkbox should be enabled. Note that it is only possible to verify the timestamp semantics, the response signature and/or decrypt the response contents using this option.

loading table of contents...