For-Fee Web Services

One of the most commonly asked questions regarding Web services has to do with economics rather than programming conundrums. The question can be summarized as follows. I’m thinking about writing a particular Web service. For it to be commercially viable, I have to charge a fee for using it. If I charge for it, I have to know who’s calling it. How do I know who’s calling my Web service? In other words, how do I identify the originator of a Web method call?

The question is actually one of security. Identifying callers means authenticating callers. There are several ways to authenticate Web service callers. Here are three possibilities:

Assign authorized callers an authentication key (for example, a password or a random sequence of digits) and require them to pass the key in each method call.
Transmit user names and passwords in HTTP Authorization headers.
Transmit user names and passwords or some other form of credentials in SOAP headers.

The third of these three options is arguably the most compelling because it transmits authentication data out-of-band and enables developers to leverage the high-level support for SOAP headers built into the .NET Framework. To demonstrate, here’s a Web service whose Add method can be called successfully only if the SOAP request contains a header named AuthHeader that in turn contains a UserName element equal to “jeffpro�?and a Password element equal to “imbatman�?

<%@ WebService Language="C#" Class="SafeService" %>

using System;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;

public class AuthHeader : SoapHeader
{
    public string UserName;
    public string Password;
}

class SafeService
{
    public AuthHeader header;

    [WebMethod]
    [SoapHeader ("header", Required="true")]
    public int Add (int a, int b)
    {
        if (header.UserName == "jeffpro" &&
            header.Password == "imbatman")
            return a + b;
        else
            throw new HttpException (401, "Not authorized");
    }
}

AuthHeader is a custom type derived from System.Web.Services.Protocols.SoapHeader that represents a SOAP header. The SoapHeader attribute affixed to the Add method tells ASP.NET to reject calls (that is, throw SoapHeaderExceptions) to Add that lack AuthHeaders and to map incoming AuthHeaders to the SafeService field named header. The Add method extracts the user name and password from the SOAP header and throws an exception if the credentials are invalid.

How does a client attach AuthHeaders to outgoing calls? Here’s an excerpt from a .NET Framework client that calls SafeService’s Add method with the proper authorization header:

SafeService calc = new SafeService ();
AuthHeader header = new AuthHeader ();
header.UserName = "jeffpro";
header.Password = "imbatman";
calc.AuthHeaderValue = header;
int sum = calc.Add (2, 2);

The AuthHeader data type is defined in the service’s WSDL contract. When Wsdl.exe generated the Web service proxy (SafeService), it also generated an AuthHeader class definition and added an AuthHeader field named AuthHeaderValue to SafeService. Initializing that field with an AuthHeader object transmits the data contained therein in a SOAP header. Here, in fact, is what the outgoing SOAP envelope might look like, with the SOAP header highlighted in boldface text:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd=http://www.w3.org/2001/XMLSchema
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="http://tempuri.org/">
      <UserName>jeffpro</UserName>
      <Password>imbatman</Password>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <Add xmlns="http://tempuri.org/">
      <a>2</a>
      <b>2</b>
    </Add>
  </soap:Body>
</soap:Envelope>

As you can see, the .NET Framework goes to great lengths to insulate you from the nuts and bolts of SOAP and XML. It even provides high-level abstractions for SOAP headers.

A variation on this technique is to include an Application_Authenticate- Request handler in a Global.asax file and examine SOAP headers there. The advantage to this approach is that you don’t have to authenticate the caller in each and every Web method. Application_AuthenticateRequest centralizes the authentication code and allows you to prevent the Web method from even being called if the caller lacks the proper credentials.

Yet another way to identify callers is to configure IIS to require authenticated access to the directory that hosts the Web service and enable Windows authentication in ASP.NET via a Web.config file. Then derive your Web service class from System.Web.Services.WebService and use the inherited User property to obtain callers�?user names. This form of authentication, unlike methods that perform custom authentication using SOAP headers, is appropriate only if callers have accounts in the Web server’s domain. In other words, it’s a fine solution for Web services that serve clients on the company’s intranet but not for ones that serve the population at large.