Security Configurations

Add, remove or manage global security configurations

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:

Figure 5.12. Security Configuration - Create new configuration

Security Configuration - Create new configuration


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

Figure 5.13. Security Configuration - List of configurations

Security Configuration - List of configurations


Non-Policy security configuration

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.

Outbound request security

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:

Figure 5.14. Security Configuration - NonPolicy Outbound Security

Security Configuration - NonPolicy Outbound Security


Timestamp

The timestamp assertion can be used to add a <wsu:Timestamp/> element to the SOAP request header. Select the ‘Use Milli Seconds Precision’ checkbox to use milli-second level precision for the ‘Created’ and ‘Expires’ element value.

Figure 5.15. NonPolicy configuration - Timestamp

NonPolicy configuration - Timestamp


Username Token

This assertion is used to add a WS-Security Username Token as specified in Username Token Profile 1.1

Figure 5.16. NonPolicy configuration - Username Token

NonPolicy configuration - Username Token


Username

Specifies the value of the username element

Password

Specifies the value of the password element

Type

Specifies the value of the attribute ‘Type’ for the password element. The value can be ‘Text’, ‘Digest’ or ‘None’. If ‘Text’ or ‘Digest’ is chosen, the Type attribute value will be generated as either http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText   or http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest  If ‘None’ is chosen, then no password element will be sent in the UsernameToken element even if a password value is specified.

If the ‘Add Nonce’ and ‘Add Created’ checkboxes are enabled, then the <wsse:Nonce/> and <wsse:Created/> elements will also be added to the UsernameToken element.

Signature

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

Figure 5.17. NonPolicy configuration - Signature

NonPolicy configuration - Signature


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.

Figure 5.18. NonPolicy Configuration - Signature - Private key

NonPolicy Configuration - Signature - Private key


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

Note

You have to click on the private key alias to enable the OK button which will remain disabled until done so.

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.

Figure 5.19. NonPolicy Configuration - Signature Parts

NonPolicy Configuration - Signature Parts

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.

Figure 5.20. NonPolicy Configuration - Advanced Signature Options

NonPolicy Configuration - Advanced Signature Options


Encryption

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:

Figure 5.21. NonPolicy Configuration - Encryption

NonPolicy Configuration - Encryption


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:

Figure 5.22. NonPolicy Configuration - Encryption - Public Key

NonPolicy Configuration - Encryption - Public Key

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:

Figure 5.23. NonPolicy Configuration - Encryption Parts

NonPolicy Configuration - Encryption Parts

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

Figure 5.24. NonPolicy Configuration - Advanced Encryption Options

NonPolicy Configuration - Advanced Encryption Options


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

SAML Assertion

This assertion allows for adding a previously obtained / created SAML assertion in the outbound request SOAP WS-Security header.

Figure 5.25. NonPolicy Configuration - SAML Assertion

NonPolicy Configuration - SAML Assertion


The Edit button can be used to open the Add Assertion dialog which contains a text field to capture the SAML Assertion element to be added to the request.  

Note

The value specified in the dialog must be a syntactically valid XML SAML 1.x or 2.0 Assertion element. The specified Assertion will be added as is to the WS-Security header in the outbound WS request.

This action assumes that you have a way to obtain or create a valid SAML Assertion. Please see the Tools section to see how to generate a valid SAML 2 Assertion manually. It is also possible to use the built-in STS to obtain a valid SAML token and add the Assertion element present in the token (refer to the STS Usage section)  

The Clear button can be used to remove any previously added assertion contents.

Binary Security Token (X.509 token)

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.

Figure 5.26. NonPolicy Configuration - Binary Security Token

NonPolicy Configuration - Binary Security Token


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>

Inbound response security

To enable WS-Security processing for the SOAP response select the Enable Response Security checkbox as shown below:

Figure 5.27. Security Configuration - NonPolicy Inbound Security

Security Configuration - NonPolicy Inbound Security


The following response processing actions are available when response security is enabled:

Verify Timestamp

If this option is enabled, then the <wsu:Timestamp/> element if present in the WS-Security header of the SOAP response is verified for correctness (i.e. not expired)

Verify Response Signature

When this option is enabled, Examine verifies the response signature. Note that a valid truststore that contains the public key of the web service must be configured to be able to verify the signature.

Decrypt Response Body

When this option is enabled, Examine decrypts the elements which were encrypted by the service in the response it sends back. Note that for the decryption to succeed, a keystore that contains the private key corresponding to the public key used by the service to encrypt must be configured.

Policy-based security configuration

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:

Figure 5.28. Security Configuration - Policy-based configuration

Security Configuration - Policy-based 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.

Runtime policy parameters

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:

Time-To-Live

Specify the value in seconds that will be used for the <wsu:Timestamp/> element. It will default to 300s or 5 minutes by default if unspecified

Username Token

Specify the username and password to be sent as part of the <wsse:UsernameToken/> element. Note that whether the password is sent in plain text or digest form is usually specified in the policy

Signature

Click on Select to choose the private key alias that will be used to sign the request elements. Note that atleast one keystore must have been uploaded earlier to be able to choose a private key alias from it. Refer to the Security Configuration guide for information on how to manage keystores.

Encryption

Click on Select to choose a public key alias that will be used to encrypt the request elements. Note that atleast one keystore that contains an X.509 certificate must have been uploaded earlier to be able to choose a public key alias from it. Refer to the Security Configuration guide for information on how to manage keystores.

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.