When you think ASP, think...
Recent Articles xml
All Articles
ASP.NET Articles
Related Web Technologies
User Tips!
Coding Tips
spgif spgif

Book Reviews
Sample Chapters
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Stump the SQL Guru!
Web Hosts
Author an Article
spgif spgif

ASP ASP.NET ASP FAQs Feedback topnav-right
Print this Page!
Published: Wednesday, June 30, 2004

An Extensive Examination of Web Services: Part 8

By Scott Mitchell

An Extensive Examination of Web Services Index
An Extensive Examination of Web Services is a multi-part article series spanning several months. Listed below are the current "parts," along with a very brief synopsis and the date published.
  • Part 1 - Examines the basics of Web services, what Web services are, and the technologies and standards that serve as the underpinnings of Web services. (October 8th, 2003)
  • Part 2 - Examines creating Web services using Visual Studio .NET. Looks underneath the hood of the code created by VS.NET. (October 15th, 2003)
  • Part 3 - Examines creating a client application that consumes a Web service. Discusses the purpose and structure of a WSDL document, along with creating and using proxy classes to consume a Web service. (November 5th, 2003)
  • Part 4 - Examines the utility of Web services and common scenarios where Web services make sense. A business-oriented look at Web services. (November 19th, 2003)
  • Part 5 - Takes an in-depth look at XML serialization, which is the process of converting a data type, such as an integer, array, or custom class, into its XML representation, and back again. Every time a message is passed to or from a Web service, XML serialization transpires. (December 17th, 2003)
  • Part 6 - Looks at sending metadata to a Web method through the use of SOAP headers. Examines defining and accepting a SOAP header on the Web service end, and looks at sending a populated SOAP header from the client. (December 31st, 2003)
  • Part 7 - Examines how the incoming and outgoing messages to a Web service can be programmatically modified via SOAP Extensions. (January 21st, 2004)
  • Part 8 - Learn about the Web Service Enhancements (WSE) and Microsoft's free class library for implementing the WSE standards. (June 30th, 2004)
  • Part 9 - See how to implement UsernameToken authentication using the WSE 2.0 Toolkit. (July 14, 2004)
  • Part 10 - Learn how to send large amounts of data as attachments using DIME and WS-Attachments. (September 8th, 2004)
  • Part 11 - Create (and consume) client-side script-accessible Web Services using Microsoft's ASP.NET AJAX framework. (September 26th, 2007)


As we've discussed in the previous installments of this article series, Web services are comprised of a number of core standards, including:

  • XML - XML serves as a universal data format, and is the means by which data passed to and from a Web service is encoded. XML was the chosen data format because of its platform-neutrality and expressiveness.
  • SOAP - SOAP is a standard that defines how to exchange structured information in a distributed environment. The messages sent to and from a Web service are formatted according to the SOAP specification.
  • WSDL - WSDL is an XML-formatted description language used to formally describe a Web service's interface in a machine-readable format. When creating a client to consume a Web service, we first create a proxy class, which can be autogenerated with information from the Web service's WSDL contract.

These core standards spell out how to accomplish the simple, required tasks inherent to all Web services: how to format data, how to encode the messages sent between client and Web service, and how to formally define a Web service's functionality. What these core standards don't provide, however, is a means for accomplishing common business tasks with Web services. Developers can create their own techniques for accomplishing any complex tasks built on top of the core standards, but ideally there would be a standardized technique for accomplishing common tasks.

Fortunately, there are a number of standards being drafted by industry titans on how to accomplish a variety of common business tasks. These extended standards, dubbed by Microsoft as the Web Service Enhancements (WSE), spell out standardized techniques for things like authentication, encryption, sending binary attachments, routing SOAP messages among intermediaries, establishing trust between a Web service and a Web service client, and many more. Additionally, at TechEd 2004, Microsoft officially released the WSE Toolkit 2.0, a set of classes for the .NET Framework that make working with the WSE standards a breeze.

In this article we'll take a high-level look at the WSE standards and the format of SOAP messages that utilize these extended standards. We'll then take a sneak peek at the WSE Toolkit 2.0, and see how the WSE Toolkit simplifies working with these standards. In the next installment of this article series, Part 9, we'll start using the WSE Toolkit and examine techniques for authenticating those utilizing your Web services.

- continued -

The Motivation for Web Service Enhancements

Since Web services are implemented as URLs on a Web server, by default those accessing a Web service can do so anonymously. Imagine, however, that you wanted to require users invoking your Web service to send along some bit of information to authenticate them. (Authentication is the process of identifying a requestor, and is typically accomplished by the requestor sending along a token. A token is some bit of information that uniquely identifies the user, such as a username and password.) For this example, assume that you need to know who's accessing the Web service because the results the Web service returns depends upon their account information. Finally, assume that your user accounts are maintained in a database that, among other things, includes their username and password.

The question facing us now is, How can the user send along their credentials so that we can authenticate them? One option would be to add to each Web service method two additional parameters: username and password. While this approach would work, it's burdensome - as the developers creating the Web service we must remember that each method must include an additional two input parameters. The developers building the clients that are consuming our Web service will have to remember to include their username and password when calling each method. Since the username and password are really peripheral to the functionality of any given Web service method, it makes more sense to place this metadata in the SOAP headers of the SOAP message being sent from the client to the Web service. (Recall from our discussion in Part 6 that SOAP headers are an optional component of a SOAP message that are present for sending along metadata with the SOAP request or response.)

If we wanted to send the username and password in the SOAP headers we could create an appropriate class on the Web service side. In fact, in Part 6 of this article series we looked at such an example, creating an AuthenticationHeader class on the Web service with two public string properties: Username and Password. From the Web service methods that require authentication, the passed-in SOAP header's Username and Password properties could be used to construct a SQL query to ensure that the user exists in the database, and take appropriate action based on the results of this query.

The client consuming this Web service would need to craft the appropriate SOAP header, populate the Username and Password properties, and attach the header to the proxy class used to invoke the Web service. The actual SOAP message sent across the wire would look something like:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    <WebServiceMethodName xmlns="Web Service Namespace" />

While this approach works, the main disadvantage is that the technique is not standardized. That is, another Web service provider might want to also enable authentication, but might decide to use a SOAP header named <LoginInfo> rather than <AuthHeader>, or might decide to use property names Login and Pwd rather than Username and Password. Since each Web service provider might implement authentication using different techniques, each client must be customized to handle the Web service provider(s) specific authentication technique. If a standardized technique for authentication is used, however, all clients can use the same code base for authenticating themselves with Web service provides that implement the standard. Furthermore, introducing standards enables vendors like Microsoft to add support for the standards in the tools we developers use, thereby making utilizing the standards that much easier.

An Overview of the Web Service Standards

The Web Service Enhancements aim to define standardized techniques for implementing many common business needs not addressed by the core standards. The WSE standards begin as drafts coauthored by a variety of industry leaders. For example, the WS-Trust standard, which defines how to establish trust between disparate actors involved in a Web service interaction, was contributed to by individuals from IBM, Microsoft, BEA, RSA Security, VeriSign, Computer Associates, and others. Once a WSE standard is introduced as a draft, it typically goes through a number of revisions. There are usually meetings and open forums for those interested in helping shape the standards. As these drafts mature, they are usually adopted by open standards groups, such as OASIS.

"The Web Service Enhancements aim to define standardized techniques for implementing many common business needs not addressed by the core standards."
There are an array of proposed WSE standards, broken down into various categories. Some of the more mature WSE standards include:

  • WS-Security (an OASIS standard as of April 2004)
    • UsernameToken Authentication - specifies a standard for passing username/password tokens for the purpose of authentication.
    • XML Encryption - defines a standard for encrypting the contents of a SOAP message.
    • XML Digital Signatures - defines a means for digitally signing a SOAP message. A digital signature ensures that the contents of the SOAP message have not been altered in transit.
    • WS-SecureConversation - provides a technique for a Web service and a client to have an encrypted message exchange.
    • WS-Trust - defines how to establish trust between disparate actors involved in a Web service interaction.
    • ...
  • DIME and WS-Attachments - specifies a technique for attaching large amounts of binary data outside of the SOAP envelope. Useful for sending large documents to or from a Web service, such as images, PDFs, or other large files.
  • WS-Addressing - defines a standard for encapsulating addressing information within the SOAP message. WS-Addressing adds information such as the Web service endpoint, the client's endpoint, the method to invoke, and other such information, in the headers of the SOAP message, as opposed to having it out of band in the HTTP headers.
  • WS-Eventing - specifies a standard for Web services to send an event notification message to clients who have subscribed.
  • ...

All of the WSE standards work in roughly the same way - by adding a predefined set of headers to the SOAP envelope. For example, the standards under the WS-Security umbrella are implemented with the addition of a <Security> SOAP header. The UsernameToken authentication standard adds a <UsernameToken> XML element under the <Security> SOAP header, with children elements <Username> and <Password>, as shown below:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    <wsse:Security soap:mustUnderstand="1">
        <wsse:UsernameToken namespaces>
          <wsse:Password Type="type info">password</wsse:Password>
          <wsu:Created>date created</wsu:Created>
    <WebServiceMethodName xmlns="Web Service Namespace" />

We'll discuss the specifics of UsernameToken authentication in Part 9 of this article series. If you're wondering, the <wsse:Nonce> is used as a salt for sending a hashed password; the <wsu:Created> element contains a date/time the token was created to prevent replay attacks. The point is, the UsernameToken authentication standard defines how to send along username and password credentials in the SOAP header.

A Look at Implementing WSE Standards in .NET Web Services - Microsoft's WSE Toolkit

Earlier we talked about how the benefit of standardizing common business techniques, such as authentication, is that tool vendors can then integrate such functionality into developer tools, thereby making implementing the standards a breeze for us developers. For .NET developers, the WSE standards can be implementing in Web services or Web service clients using Microsoft's free WSE Toolkit. At the time of this writing (June 30, 2004), the WSE Toolkit is at version 2.0, and is downloadable from http://msdn.microsoft.com/webservices/building/wse/.

The WSE Toolkit provides an assembly with a set of classes that can be used to programmatically work with the WSE standards. From a developer's standpoint, you will need to only work with the appropriate classes in the WSE Toolkit, and not concern yourself with crafting the SOAP message and its intricate headers. For example, for a client to authenticate itself with a Web service that uses UsernameToken authentication, a .NET client using the WSE Toolkit can simply create an instance of the UsernameToken class, set the Username and Password properties, and then add the token to the proxy class's Security object's Tokens collection.

Under the covers, the WSE Toolkit works using SOAP Extensions, which we discussed in Part 7 of this article series. Recall that SOAP Extensions are useful for intercepting the incoming and outgoing SOAP messages, and can be used to inspect or modify the SOAP message's content. When a client application adds a UsernameToken instance to the proxy class's Security object's Tokens collection, as the SOAP message is about to leave the client and be sent to the Web service, a SOAP Extension runs and notices that a UsernameToken instance has been added. It then inserts the appropriate SOAP header into the outgoing message content.

Similarly, when a .NET Web service utilizing the WSE Toolkit receives a message, a SOAP Extension examines the incoming message. For the UsernameToken authentication example, the Web service's SOAP Extension will note that there's a UsernameToken in the SOAP headers, and will attempt to automatically authenticate the user's credentials. (When developing the Web service you can specify how the credentials should be validated. You can provide your own class with the authentication logic, or can have the user authenticated against the Windows user accounts.)

The point is, with the WSE Toolkit our jobs as developers of Web services or Web service clients becomes infinitely easier. In the next article (Part 9) in this series we'll see how to install the WSE Toolkit 2.0, as well as how to use the WSE Toolkit to implement UsernameToken authentication. Until then, Happy Programming!

  • By Scott Mitchell

    Beginner's .NET XML Web Services

    Beginner's .NET XML Web Services DVD

    Beginner's .NET XML Web Services offers nearly eight hours of training on .NET XML Web services in a video format. This two-disc DVD set, presented by author Scott Mitchell, offers a unique opportunity for learning about the fundamentals of Web services. The 14 lessons begin with an examination of the core Web service standards, and then quickly move into showing you how to create and consume Web services in Microsoft's .NET Framework. There are in-depth lessons for each of the core Web service standards - XML, SOAP, and WSDL - along with examples of the Web Service Enhancements (WSE). Scattered throughout each of these chapters are extensive demos, depicting how to build, deploy, and access Web services using Microsoft's Visual Studio .NET. The DVD also contains a thorough examination of a real-world, end-to-end Web service application.

    Scott Mitchell is the editor and founder of 4GuysFromRolla.com, author of the An Extensive Examination of the Web Services article series, and author of numerous ASP and ASP.NET books.

    [Buy this DVD]

    Why get stuck with a 600-page paperweight when you can learn about .NET Web Services through an interesting and interactive video presentation?

  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article