An Extensive Examination of Web Services: Part 8By Scott Mitchell
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.
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:
Password. From the Web service methods that require authentication, the
passed-in SOAP header's
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
The client consuming this Web service would need to craft the appropriate SOAP header, populate the
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:
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
<AuthHeader>, or might decide to use property names
Pwd rather than
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.
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
SOAP header. The UsernameToken authentication standard adds a
<UsernameToken> XML element under the
<Security> SOAP header,
with children elements
<Password>, as shown below:
We'll discuss the specifics of UsernameToken authentication in Part 9 of this article series. If you're
<wsse:Nonce> is used as a salt for sending a hashed password; the
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
and then add the token to the proxy class's
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
as the SOAP message is about to leave the client and be sent to the Web service, a SOAP Extension runs and notices
UsernameToken instance has been added. It then inserts the appropriate SOAP header into the outgoing
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!