Why WSE?

Article
06/30/2006

February 2005

Applies to:
Microsoft .NET
Web Services Enhancements (WSE) 2.0 for Microsoft .NET
WS-* Specifications

Summary: WSE provides benefits such as end-to-end message-level security, content-based routing, and policy by leveraging the WS-Security, WS-Addressing, and WS-Policy specifications. (7 printed pages)

WSE Is An Implementation of Many WS-* Specifications
Web Services Security and WS-Addressing Provide End-to-End Message-Level Security
How Does WS-Security Work?
Sample Application: A Credit Card Payment Service
Authentication and Signing with Username Tokens
Encrypting the Message Body with an X.509 Certificate
Content-based Routing with Headers Derived from WS-Addressing
Using WS-Policy to Implement the Security with Minimal Code
Summary
For More Information

Microsoft .NET has always had strong support for Web services. Now with the release of the Web Services Enhancements 2.0 (WSE) it is possible to develop secure, interoperable Web services based on open industry specifications. This article highlights the benefits that WSE provides, such as end-to-end message level security, content-based routing, and policy, by leveraging the WS-Security, WS-Addressing, and WS-Policy specifications.

WSE Is An Implementation of Many WS-* Specifications

Much of the promise of Web services is to provide communication for systems that span disparate operating systems and development platforms. To achieve this, they are based on a family of industry protocol specifications for Web services, often referred to as WS-*. WSE 2.0 provides implementations of many of these specifications for early adopters who want to use next-generation Web services technology today. WSE is a fully supported, free download that extends the existing Web services support in the .NET Framework. While there are no guarantees that 2.0 will be wire-level or object-model compatible with future major releases of WSE (e.g., 3.0), side-by-side compatibility with major versions is guaranteed. Simple and mechanical upgrades are expected for each release and to "Indigo"—the next-generation messaging infrastructure for the Microsoft Windows platform. It is expected that a version of WSE released before, or at the same time as, Indigo will be wire-level interoperable with Indigo.

Web Services Security and WS-Addressing Provide End-to-End Message-Level Security

The WS-Security specification, now ratified as a standard by OASIS [1] describes how to secure Web services at the message level, rather than at the transport protocol or wire level. Existing transport-level solutions such as SSL/TLS provide solid point-to-point data encryption and authentication but have limitations if a message needs to be processed or examined by an intermediate service. For example, many organizations deploy an application-layer-filtering firewall to examine traffic before it is passed along to an internal network.

If a message needs to go through multiple points to reach its destination, each intermediate point must forward the message over a new SSL connection (see Figure 1). In this model the original message from the client is not cryptographically protected as it traverses intermediate servers and additional computationally expensive cryptographic operations are performed for every new SSL connection that is established.

Figure 1. Protocol-level versus message-level security

WS-Addressing, recently submitted to the W3C [2], is a key part of achieving message-level security since it provides the mechanisms to address messages in a transport-independent fashion. This allows a secured message to be sent over any transport and to be easily routed.

Securing the message instead of using the transport protocol has several advantages. First, it is more flexible because parts of the message can be signed or encrypted rather than the entire message. This means that intermediaries are able to view parts of the message intended for them. An example of this is a Web service that routes SOAP messages being able to inspect unencrypted parts of a message to determine where to send the message, while other parts of the message remain encrypted. Second, intermediaries can add their own headers to the message and sign them for the purpose of audit logging. Finally, it means that the secured message can be sent over many different protocols such as SMTP, FTP, and TCP without having to rely on the protocol for security.

How Does WS-Security Work?

WS-Security defines how to achieve message integrity, confidentiality, and authentication with SOAP messaging. Authentication is concerned with identifying the caller. WS-Security uses security tokens to hold this information with a security header of the SOAP message. Message integrity is achieved with XML Digital Signatures to ensure that parts of the message have not been tampered with since it was signed by the originator. Message confidentiality is based on the XML Encryption specification and ensures that corresponding parts of the message can only be understood by the intended recipient(s).

Figure 2. Fabrikam Credit Card Processing Web service

Sample Application: A Credit Card Payment Service

To demonstrate the benefits of using WSE, imagine the fictitious Fabrikam Credit Card Processing Web service (see Figure 2) that allows client applications to submit credit card details to pay for a purchase. Fabrikam's clients must pay a monthly subscription to access this service. The clients are also invoiced monthly for the number of transactions processed. The cost per transaction depends on the processing speed, which can either be immediate or overnight.

To support this scenario, each Web service call must contain authentication information so that the internal services can validate that the client still has a monthly subscription. The credit card details must be kept secure until the message is received by either of the internal payments services. The following sections describe how WSE supports these requirements.

Authentication and Signing with Username Tokens

Clients are authenticated using a username token that contains their username and password. The payment service uses WSE to implement a custom UsernameTokenManager that validates the username and password against the client user details store (see Listing 1). Clients also sign the message using this username token and the payment service uses WSE to automatically validate the signature, ensuring that no one has tampered with the message. The UsernameTokenManager is just one example of how WSE can be extended beyond its default behavior, which is validating the username/password against a Windows domain or local user account. Please note, best practices are out of scope of this document. Kerberos, X509, or custom XML or binary tokens types may be preferable for particular scenarios. Reference the Web services developer center on MSDN for more in-depth articles on security [3].

Listing 1. Creating a custom username token manager

public class CustomUsernameTokenManager : UsernameTokenManager
{
   protected override string AuthenticateToken(UsernameToken token)
   {
      // Call our application's business logic to get the password
      string storedApplicationHashedPassword = 
       GetAppPasswordHashFromUserDetailsStore( token.Username );
   if ( storedApplicationHashedPassword != null )
   {
     return storedApplicationHashedPassword;
   }
   else
   {
      throw new SecurityFault( "An invalid security token was
            provided", SecurityFault.InvalidSecurityTokenCode );
   }
   }
}

Encrypting the Message Body with an X.509 Certificate

The client applications use the Fabrikam Accounts Department X.509 certificate (which is installed on each client's machine) to encrypt the credit card information (see Listing 2). Since the WSE HTTP Router does not process any security information in the message, the router will not be able to see the credit card details contained within the encrypted body of the SOAP envelope. The credit card details are secured once at the client and are only decrypted when the message is received by either the Immediate or Overnight Processing Services.

Listing 2. Encrypting the message body using an X509 certificate

// Encrypt the message body with the credit card details using the 
// Accounts Department Certificate
X509SecurityToken x509Cert =   
    GetFabrikamAccountsDepartmentCertificate();
paymentServiceProxy.RequestSoapContext.Security.Tokens.Add( x509Cert );
paymentServiceProxy.RequestSoapContext.Security.Elements.Add( new 
EncryptedData( x509Cert ) );

Content-based Routing with Headers Derived from WS-Addressing

The clients send the messages to a single, publicly visible routing service. This service uses WSE addressing and routing support to inspect the headers on the message in order to determine which internal payment service to send the message to. Having a Web service route SOAP messages like this provides a way to "virtualize" the physical network, implement load balancing, or allow for services to be moved or replaced without impacting the clients.

WSE supports HTTP routers that are hosted in IIS (they implement IHttpHandler). Listing 3 shows the PaymentServiceRouter which derives from the WSE SoapHttpRouter and does most of its work inside the ProcessRequestMessage function where it searches for an immediate processing message header (added using WS-Addressing's support for reference properties that are turned into stand-alone SOAP headers) in order to determine where to route the message. Listing 4 shows the referralCache.xml used to configure the router.

Listing 3. Implementing the Payment Server Router

public class PaymentServiceRouter : 
Microsoft.Web.Services2.Messaging.SoapHttpRouter
{
   static readonly string ImmediateProcessingURI = 
"http://fabrikam/ImmediatePaymentService.asmx";
   static readonly string ImmediateProcessingName = "Immediate";

   Uri AccountsPaymentServiceURI;

   public PaymentServiceRouter()
   {
      AccountsPaymentServiceURI = new Uri(ImmediateProcessingURI);
   }

   protected override Uri ProcessRequestMessage(SoapEnvelope message)
   {
      // Look for any Immediate headers
      XmlNodeList immediateHeaders = 
         message.Header.GetElementsByTagName(
         ImmediateProcessingName, ImmediateProcessingURI);
        if (immediateHeaders.Count == 0)
        {
            // Defer to the WSE RoutingHandler's implementation
      // to send it to the Overnight Batch Service specified
      // in the config.
            return base.ProcessRequestMessage(message);
        }
        else
        {
            // Add a new via to the accounts payment service
            return AccountsPaymentServiceURI;
        }
    }
}

Listing 4. The Payment Server Router Referral Cache

<?xml version="1.0" ?>
<r:referrals xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
  <r:ref>
    <r:for>
      <r:exact>https://fabrikam.com/PaymentService.asmx</r:exact>
    </r:for>
    <r:if />
    <r:go>
      <r:via>http://fabrikam/OvernightPaymentService.asmx</r:via>
    </r:go>
    <r:refId>uuid:fa469956-0057-4e77-962a-81c5e292f2ae</r:refId>
  </r:ref>
</r:referrals>

Using WS-Policy to Implement the Security with Minimal Code

While WSE provides automatic support for the verification of signatures and decryption of encrypted elements, it is still up to the service implementers to write code to check that the incoming messages had the correct message parts signed and encrypted using the correct tokens. As an alternative to writing this code within services, WSE supports WS-Policy, which defines an XML syntax that can be used to describe requirements beyond the capabilities of WSDL. WSE on the service side then uses this XML file to automatically validate the incoming SOAP messages. In a similar fashion, the client side can use a matching policy file to automatically secure the outbound communication. The result is reduced code for developers to write, as well as the ability to change the security requirements without having to recompile the service code. WSE also provides a Security Settings Wizard that can be used to create the XML policy file.

Summary

WSE as an add-on to the .NET Framework provides a toolkit that developers can use to secure interoperable Web services based on many WS-* specifications such as WS-Security, WS-Addressing, and WS-Policy. The sample application demonstrates the benefits of using WSE 2.0 for end-to-end message-level security, content-based routing, and policy to build applications that would be difficult to achieve with previously distributed technologies.