Home » Securing .NET Web Services with the WS-Security Protocol

Securing .NET Web Services with the WS-Security Protocol

or years now, SSL has been the magic bullet for securing HTTP messaging. While you can use this encryption-based technology to secure SOAP messages over HTTP, it limits Web service functionality. SSL requires a negotiation between messaging endpoints to exchange keys and establish encryption, so messaging secured by SSL must be fully decrypted at each endpoint before the contents of a message can be read. In other words, when using SSL, your application must pay the processing cost of decrypting each message?even before it can read the SOAP message headers to determine, for example, that the message needs to be re-encrypted and forwarded to another application. Clearly, applications need a security solution that better enables such complex message routing. To fulfill that need, representatives from IBM, VeriSign, and Microsoft teamed up to draft the WS-Security specification.

Inside the WS-Security Specification
WS-Security introduces the concept of security tokens. These XML-based tokens contain claims about the sender of a SOAP message, and can include data sufficient to prove these claims. Username tokens, which will be the focus of this article, can contain a username and optionally a password or a cryptographically-derived password hash. Signed security tokens, such as X.509 or Kerberos-based tokens, are binary security tokens encoded as base-64 binary XML. They include cryptographic endorsements made by a token-issuing authority.

SOAP messages transport these security tokens in the new Security header element. Applications can use the header contents to authenticate the sender and secure the message itself. Rather than proposing a new set of security technologies, WS-Security leverages existing XML security specifications, including XML Encryption and XML Signature; cryptographic algorithms, such as SHA-1 and Triple-DES; and authentication mechanisms, such as X.509 and Kerberos.

When using SSL, your application must pay the processing cost of decrypting each message.

Implementing WS-Security
To implement the WS-Security specification in your Web service or consuming client application, you must be able to write security elements to and read them from your SOAP messages, and you must have access to standard cryptographic algorithms. While it’s certainly possible to do the necessary XML serialization yourself, you can avoid extra work by leveraging out-of-the-box implementations of WS-Security offered by IBM, Microsoft and others. In this article, I will focus on Microsoft’s implementation of WS-Security in its Web services Enhancements (WSE) offering. In particular, you’ll see how to use the WSE 2.0 Technical Preview release to secure a request to the classic “Hello World” Web service.

Welcome to WSE 2.0
WSE is Microsoft’s solution for supporting advanced Web services functionalities, including security, reliable messaging, and policies. WSE, which supports both TCP and HTTP transports, implements a set of input and output filters as well as a rich API.

WSE input filters intercept incoming SOAP messages and translate supported SOAP header elements into programming objects, which are accessible using the SoapContext object. WSE output filters construct SOAP headers based on the properties of the SoapContext object for the outgoing message. The WSE runtime, which hosts these filters and API, is implemented in the .NET assembly Microsoft.Web.Services.dll.

WSE also supports Web service policies, which ensures that incoming messages have the required headers and can automate the securing of outbound messages.

To follow the code in the remainder of this article, you should download and install the WSE 2.0 Technical Preview before continuing.

Author’s Note: WSE 2.0 integrates with Visual Studio 2003. To benefit from this integration, select the Visual Studio Tools option during installation; this installs all of the tools that I discuss in this article.

You configure WSE 2.0 on a per-application basis by adding XML elements to the application configuration file. Modifying the configuration lets you change the default behavior of WSE without recompiling your application, but it is tricky to edit these files without making mistakes. To avoid such errors, I recommend setting configuration parameters through the WSE Settings Tool, a Visual Studio add-in for WSE 2.0 installed when you select the Visual Studio Tools option during installation.

Configuring a WSE-based Application
After installing Visual Studio 2003 and WSE 2.0, you can create and build the sample code for this article. For a simple introduction, you’ll create a client application to access a “Hello World” Web service. After completing this simple test case, you’ll be able to use the same techniques to access any WS-Security-enabled Web service.

Creating the Hello World service is trivial. Create a new Web service project, and uncomment the HelloWorld Web method, and compile the project. You will follow the same steps to enable WSE for the service as you do for the client. Now, you can create a client application to consume the service.

After creating a new client application in Visual Studio 2003 (you can use any project type), right-click the project in the “Solution Explorer” pane and select “WSE Settings 2.0?.” This displays the WSE Settings Tool shown in Figure 1.

Adding a Security Token
Because all messages sent to a WSE-enabled application must contain at least one security token, you need to instruct WSE to add a username token to the application’s request to the Hello World Web service. You do that by adding a UsernameToken object to the SoapContext for the request message. The following code adds a UsernameToken and a new digital signature to the SoapContext object before making the Web service request to the GetHelloWorld method.

   // Instantiate the HelloWorldWse class.   HelloWorldWse myService = new HelloWorldWse();      // Get the SoapContext object for the    // outgoing message.   SoapContext myContext = myService.RequestSoapContext;      // Instantiate a new UsernameToken object.   UsernameToken myToken = new UsernameToken(myName,      myPwd, PasswordOption.SendNone);      // Add the token to the SoapContext.   myContext.Security.Tokens.Add(myToken);      // Generate a signature using the username token,    // and add the signature to the SoapContext.   myContext.Security.Elements.Add(      new Signature(myToken));      // String for the "Hello World" response.   string response = "";      try   {     // Call the Web method.     response = myService.GetHelloWorld();   }   catch(Exception ex)   {     // Do error handling here.   }

Note that by using a signature as proof-of-possession, you can specify the PasswordOption.SendNone so WSE doesn’t send the password in the header.

In this case, WSE generates a UsernameToken element in the message’s Security header. The following code shows the WS-Security header from a digitally signed message. When WSE digitally signs a message, it uses the supplied security token to generate the signature. WSE generated this Security header using the UsernameToken object shown in the preceding listing.

Author’s Note: I removed some of the URI strings and repeating Reference elements from the code below to improve readability.

               2003-12-11T06:57:26Z       2003-12-11T07:02:26Z                 [email protected]       LVovrPhjLV4bcXnhoyEE6g==       2003-12-11T06:57:24Z                                                                                                     …                  …              …

When instantiating a UsernameToken object, you have the option of specifying how WSE handles the password, which you must always supply. Never hard-code passwords into your application. When WSE adds a UsernameToken element to the message, it creates a Username element as well as Nonce and Created elements. These elements hold data used to prevent replay attacks and to stiffen a hashed password against dictionary attacks when using the PasswordOption.SendHashed option. However, because even a hashed password is vulnerable to a brute force dictionary attack, a better solution, aside from encrypting the transport, is to use the PasswordOption.SendNone option.

Authenticating Security Tokens
When using Kerberos and X.509-based security tokens, WSE automatically attempts to authenticate the message sender using the appropriate mechanism. However, WSE will be able to authenticate Username tokens that represent Windows accounts only when the password is sent in clear text (PasswordOption.SendPlainText) by presenting the username and password to the system. First, unless you’re using SSL, this is a very bad idea because the password is completely unprotected. Second, it requires ASP.NET to run with full system privileges.

To securely use username tokens for authentication, you need to implement your own usernametoken manager, in a class that derives from UsernameTokenManager, and register it with WSE. This works particularly well for a custom authentication scheme; you simply retrieve the password that corresponds to the username and return it to WSE, which automatically compares it to the value of the password or password hash in the UsernameToken element. Even if you do not send a password, WSE can use your retrieved password to validate an attached digital signature, thereby verifying authentication. I don’t have the space to fully cover security token managers here, but I do show how to do this in my book. You can also see this example on MSDN.

Adding Digital Signatures
As I mentioned, digital signatures become even more important in a custom username token-based scheme, since WSE can use them for authentication instead of a password or password hash. When you add a Signature object, which represents a digital signature, to the SoapContext for a message (see this code), WSE generates a digital signature over the message body?using the UsernameToken specified in the Signature object’s constructor?and adds it to a new Signature element in the Security header (see this code). At the other end, WSE uses the provided UsernameToken to verify the attached digital signature. To determine if a security token can be used to sign a message, check the token object’s SupportDigitalSignature property.

Encrypting Messages
You can use binary security tokens, such as X.509-based and Kerberos-based tokens, to encrypt part or all of a SOAP message. However, username security tokens do not support encryption. You can easily determine if a security token can be used for encryption by checking the token object’s SupportsDataEncryption property.

To sum up, WS-Security provides a solid framework for securing SOAP messaging. However, other specifications like WS-Trust, WS-SecureConversation, WS-SecurityPolicy, and WS-Federation have been proposed to build even more robust and functional security scenarios. Out of the box, WSE provides an immediate security benefit by blocking all request messages that cannot be authenticated and that contain invalid digital signatures or encryption. With a little effort, you can configure WSE to provide much needed security for .NET Web services. While this article focused on username tokens, other solutions, like X.509, provide a higher level of security and functionality.

About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.