WS-Security

In the distributed web-services model, messages are exchanged between collaborating parties. During this message exchange, end-to-end message security must be addressed. As we have seen in earlier examples of typical business processes, a message may hop between many participating service providers. XML provides a platform-independent and network-neutral format for data transport. However, such messages must be secured. There may be a need to encrypt sensitive data. Also, once a service requester sends a message for a service to a service provider, the service provider may ask for the sender’s identity. The request message should be able to transport the user credentials securely to the provider. Overall, message transport in a business process has many more requirements than are typically required for point-to-point messaging, where a single transport and a single protocol is used for communication.

Message security primarily involves the following:

• Message integrity
• Message confidentiality
• Message authentication

To implement security, a new standard has been defined—WS-Security. This defines enhancements to SOAP by providing a mechanism for associating security tokens with messages. The security token may be a binary token, X.509 certificate, Kerberos ticket, and so on. The standard is fully extensible and can support many types of tokens. It provides support for multiple security tokens, trust domains, signature formats, and encryption technologies.

WS-Security defines several tags to include security-related information in the XML document. Such information is embedded in the SOAP header.

Security-related information is enclosed in the Security element:

<S:Header>
  <wsse:Security
    xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/04/secext”>
                ...
  </wsse:Security>
</s:Header>

This security information may consist of a username and password required for server-side authentication, or may contain a digital certificate or information on the algorithms used for encrypting the message body.

Example

The following code illustrates how a security token is embedded in the message header:

<?xml version=”1.0” encoding=”utf-8”?>
<S:Envelope xmlns:S=”http://www.w3.org/2001/12/soap-envelope”
              xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>
  <S:Header>
    <wsse:Security
          xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/04/secext”>
      <wsse:UsernameToken>
        <wsse:Username>ABCOM</wsse:Username>
        <wsse:Password>Mumbai123</wsse:Password>
      </wsse:UsernameToken>
    </wsse:Security>
  </S:Header>
...
</S:Envelope>

This code first defines the required namespaces and then opens the Header element. This element may contain some message routing information (not shown in the above example). The security-related information is enclosed in the Security element. The current example encodes the user credentials in the message header. The UsernameToken encloses the UserName and Password elements. As the XML document is a text document that is readable by human beings, you will not send the password this way unless you are using secured transport (HTTPS) for sending the message. You need to send the username and password to the server for authentication. Once the server authenticates the user, the user is assigned permissions (authorized) to access the services provided by the server.

Instead of sending credentials in the form of a username and password, you can send them in the form of certificates. Such certificates are in binary format. For this purpose, WS-Security standard allows you to include binary tokens in XML documents, as explained in the next section.

Binary Security Token

You can include a binary security token by using the BinarySecurityToken element. The following code illustrates how to include a binary security token:

<?xml version=”1.0” encoding=”utf-8”?>
<S:Envelope xmlns:S=”http://www.w3.org/2001/12/soap-envelope”
            xmlns:ds=”http://www.w3.org/2000/09/xmldsig#”>
  <S:Header>
    <wsse:Security
          xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/04/secext”>
        <wsse:BinarySecurityToken
 Id=”myToken”
 ValueType=”wsse:X509v3”
 EncodingType=”wsse:Base64Binary”>
 ...
 </wsse:BinarySecurityToken>
    </wsse:Security>
  </S:Header>

The ValueType indicates the type of token (in this case it is X.509), and the EncodingType specifies the encoding method (in this case it is base-64 encoding).

You can also reference an external token rather than encoding a token in the message header.

Referencing an External Security Token

Sometimes, a security token may be located elsewhere, identified by a URI. Such external tokens are referenced using the SecurityTokenReference element. The syntax for SecurityTokenReference is given below:

<SecurityTokenReference Id=”...”>
  <Reference URI=”...”/>
</SecurityTokenReference>

The following code illustrates how an external token is referenced:

<wsse:SecurityTokenReference 
    xmlns:wsse=”http://schemas.xmlsoap.org/ws/2002/04/secext”>
  <wsse:Reference URI=”http://mysite.com/tokens/ABCOM#X509token”/>
</wsse:SecurityTokenReference>

In this case, the security token is taken from mysite.com at the specified location.

Faults

Several kinds of errors may occur during the processing of security information. For example, an invalid security token or signature could give rise to an error. The WS-Security specification defines several fault types. The different fault types and their meanings are listed below:

• wsse:UnsupportedSecurityToken: Indicates that an unsupported token was encountered
• wsse:UnsupportedAlgorithm: Indicates the use of an unsupported signature or encryption algorithm
• wsse:InvalidSecurity: Indicates an error during the processing of a security header
• wsse:InvalidSecurityToken: Indicates that an invalid token was encountered
• wsse:FailedAuthentication: Indicates that a token could not be authenticated
• wsse:FailedCheck: Indicates an invalid signature or decryption.
• wsse:SecurityTokenUnavailable: Indicates failure to retrieve the referenced token

If there is a fault, the message header will contain one of the appropriate elements from the above list to indicate the type of fault.

In addition to the above elements, the specification defines several more elements that allow you to include encrypted data, specify a signature, sign an algorithm, and so on. The reader is encouraged to look up the WS-Security specification (http://www-106.ibm.com/developerworks/webservices/library/ws-secure/) for further details.

Before we discuss more specifications, we will describe a typical business process that requires a distributed transaction involving many parties.