The WSIT Tutorial

Security Mechanism Configuration Options

The following fields shown in Table 8–1 are used to configure different security policies. Not every option is available for every mechanism, but many of the policies include the same configuration options, so they are grouped here for the purposes of defining them in one central location.

Table 8–1 Security Mechanism Configuration Options



Algorithm Suite 

This attribute specifies the algorithm suite required for performing cryptographic operations with symmetric or asymmetric key-based security tokens. An algorithm suite specifies actual algorithms and allowed key lengths. A mechanism alternative will define what algorithms are used and how they are used. The value of this attribute is typically referenced by a security binding and is used to specify the algorithms used for all cryptographic operations performed under the security binding. The default value is Basic 128 bit. 

Some of the algorithm suite settings require that Unlimited StrengthEncryption be configured in the Java Runtime Environment (JRE), particularly the algorithm suites that use 256 bit encryption. Instructions for downloading and configuring unlimited strength encryption can be found at the following URLS:

Read the OASIS specification WS-Security Policy section on Security Binding Properties for more description of the components for each of these algorithm suites. A link to this document can be found at

Encrypt Before Signing 

If selected, specifies that the order of message protection is to encrypt the SOAP content, then sign the entire SOAP body. Encryption key and signing key must be derived from the same source key. 

If not selected, the default behavior is Sign Before Encrypt. 

Encrypt Signature 

Specifies whether the signature must be encrypted. If selected, the primary signature must be encrypted and any signature confirmation elements must also be encrypted. If not selected (the default), the primary signature must not be encrypted and any signature confirmation elements must not be encrypted. 

Establish Secure Session (Secure Conversation) 

Secure Conversation enables a consumer and provider to establish a shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use (possibly derived) session keys that increase the overall security while reducing the security processing overhead for each message. 

In the absence of a notion of secure session, the client would have to reauthenticate with the server upon every request. In this situation, if the client is sending a Username token, it has to authenticate on every request, or, if the client is sending a certificate, the validity of the certificate has to be established on every request. This is expensive. Enable Secure Conversation to get over this requirement for re-authentication. 

When this option and Require Derived Keys are both enabled, a derived key will be used. If not, the original session key will be used. 

Note on Secure Conversation with Reliable Message Delivery: Reliable Messaging can be used independently of the security mechanisms; however, when Reliable Messaging (RM) is used with a security mechanism, it requires the use of Secure Conversation, which will be automatically configured for a security mechanism when Reliable Messaging is selected before the security mechanism is selected. If Secure Conversation is selected for a security mechanism and the Reliable Messaging option was not selected before the security mechanism was specified, Reliable Messaging will need to be manually selected in order for Secure Conversation to work. Reliable messaging, as well as the Advanced configuration options and Deliver Messages in Exact Order feature, is discussed in Chapter 6, Using Reliable Messaging.

Issuer Address 

This optional element specifies the address of the issuer (STS) that will accept the security token that is presented in the message. This element’s type is an endpoint reference. An STS contains a set of interfaces to be used for the issuance, exchange, and validation of security tokens. An example that creates and uses an STS can be found at Example: STS Issued Token (STS).

For example, for JAX-WS services, the Issuer Address is: 


For WCF STS, the Issuer Address is:

Issuer Metadata Address 

Specifies the address from which to retrieve the issuer metadata. They should be just the URLs. For example, for JAX-WS services, the Issuer Metadata Address is as follows: 


For WCF STS, the Issuer Metadata Address is as follows:

For more information, read Configuring A Secure Token Service (STS).

Key Type 

Applicable for Issued Token mechanisms only. The type of key the service provider desires. The choices are public key or symmetric key. Symmetric key cryptography relies on a shared secret and is usually faster than public key cryptography. Public key cryptography relies on a key that is made public to all and is primarily used for encryption but can be used for verifying signatures. 

Key Size 

Applicable for Issued Token mechanisms only. The size of the symmetric key requested, specified in number of bits. This is a request, and, as such, the requested security token is not obligated to use the requested key size, nor is the STS obligated to issue a token with the same key size. That said, the recipient should try to use a key at least as strong as the specified value if possible. The information is provided as an indication of the desired strength of the security. Valid choices include 128, 192, and 256. 

Require Client Certificate 

Select this option to require that a client certificate be provided to the server for verification. 

If you are using a security mechanism with SSL, a client certificate will be required by the server both during its initial handshake and again during verification. 

Require Derived Keys 

Require Derived Keys for: 

Issued Token, 
Secure Session, 
X509 Token

A derived key is a cryptographic key created from a password or other user data. Derived keys allow applications to create session keys as needed, eliminating the need to store a particular key. The use of the same session key (for example, when using Secure Conversation) for repeated message exchanges is sometimes considered a risk. To reduce that risk, enable Require Derived Keys. 

Require Signature Confirmation 

When the WSS Version is 1.1, select this option to reduce the risk of attacks because signature confirmation indicates that the responder has processed the signature in the request. For more information, read section 8.5, Signature Confirmation, of the Web Services Security: SOAP Message Security 1.1 specification at

SAML Version 

Specifies which version of the SAML token should be used. The SAML Version is something the CallbackHandler has to verify, not the security runtime. SAML tokens are defined in WSS: SAML Token Profile documents, available from

For an example that uses SAML Callbacks, refer to Example: SAML Authorization over SSL (SA).

Security Header Layout 

Specifies which layout rules to apply when adding items to the security header. The options are:

  • Strict: Items are added to the security header following the general principle of “declare before use”.

  • Lax: Items are added to the security header in any order that conforms to WSS: SOAP Message Security. However, WSIT follows Strict even when Lax is selected.

  • Lax (Timestamp First or Last): The same as for Lax, except that the first or last item in the security header must be a wsse:Timestamp.

Examples of the layout rules are described in the OASIS WS-SecurityPolicy specification, a link to which can be found at

Supporting Token 

Specifies the type of supporting token to be used. Supporting Tokens are included in the security header and may sign and/or encrypt additional message parts. Valid options for supporting tokens include X.509 tokens, Username tokens, SAML tokens, or an Issued Token from an STS. 

For more information on these options, read Supporting Token Options.

Token Type 

The type of SAML token the service provider requires, for example, urn:oasis:names:tc:SAML1.0:assertion.Choices are 1.0, 1.1, or 2.0.

WSS Version 

Specifies which version of the Web Services Security specification should be followed, 1.0 or 1.1. These specifications can be viewed from

Enabling WSS 1.1 enables an encrypted key generated by the client to be reused by the Server in the response to the client. This saves the time otherwise required to create a Symmetric Key during the course of response, encrypt it with the client public key (which is also an expensive RSA operation), and transmit the encrypted key in the message (it occupies markup and requires Base64 operations). Enabling WSS 1.1 also enables encrypted headers.