Overview

SOAP Headers can play an important role in SOAP messages.  By using headers, you can separate data that is used by the Web Service but not directly related to the functionality exposed by a given Web Method.  Unlike the Body element of a SOAP message, which includes the in and out parameters for the XML Web service method, which are thus processed by the XML Web service method, the Header element is optional and can be processed by the infrastructure.  In other words, it is processed by an infrastructure developed to provide a custom authentication mechanism.

The following sample demonstrates how to achieve Custom Authentication using Soap Headers in XML Web Services.

Requirements

Microsoft Visual Studio 2005

Web Service Creation

Add the new Web Service Application project (with name set as SoapHeaderAuth) and add the code, as given below.

Listing 1 : Service.cs

using System;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using System.Configuration;
[WebService(Namespace ="www.XMLWebServiceSoapHeaderAuth.net")
  ][WebServiceBinding(ConformsTo =WsiProfiles.BasicProfile1_1)]
public class Service:System.Web.Services.WebService
{
  public AuthSoapHd spAuthenticationHeader;
 
  public Service()
  {
  }
 
  public class AuthSoapHd: SoapHeader
  {
    public string strUserName;
    public string strPassword;
  }
 
  [WebMethod,SoapHeader("spAuthenticationHeader")]
  public string HelloWorld()
  {
    if (spAuthenticationHeader.strUserName =="TestUser" &&
      spAuthenticationHeader.strPassword =="TestPassword")
    {
      return "User Name : " +spAuthenticationHeader.strUserName + " and " +
        "Password : " +spAuthenticationHeader.strPassword;
    }
    else
    {
      return "Access Denied";
    }
  }
}

In listing 1, by using headers a custom class AuthSoapHd is derived from the SoapHeader class.   This custom class is referenced in the Web Service by adding the spAuthenticationHeader header to a HelloWorld Web Method by using the SoapHeaderAttribute class.

HelloWorld Webmethod specifies that it expects the SOAP header containing the authentication credentials and then authorizes the client access to the XML Web service.  Using Soap Header spAuthenticationHeader, User credentials are checked for authentication.  If the credentials are valid, then the UserName and Password are returned to the client.  If not, then an Access Denied message is returned to the client.

Create the Client Application

Now, create the Web Site project with the name as SoapHeaderAuthClient.  Add the Web Reference to the above web service application, specifying Web Reference Name as localhost in the Add Web Reference dialog.  Next, paste the following code in the page load event of the Default.aspx form.

Listing 2

using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using System.Web.Services.Protocols;
public partial class _Default:System.Web.UI.Page
{
  protected void Page_Load(object sender,EventArgs e)
  {
    localhost.Service objWebService = newlocalhost.Service();
    localhost.AuthSoapHd objAuthSoapHeader = newlocalhost.AuthSoapHd();
 
    string strUsrName =ConfigurationManager.AppSettings["UserName"];
    string strPassword =ConfigurationManager.AppSettings["Password"];
 
    objAuthSoapHeader.strUserName = strUsrName;
    objAuthSoapHeader.strPassword = strPassword;
 
    objWebService.AuthSoapHdValue =objAuthSoapHeader;
    string str = objWebService.HelloWorld();
 
    Response.Write(str);
 
  }
}

In the above listing, the client application gets the credentials from Web.config file and sends these credentials to the XML Web service by adding the expected SOAP header to the SOAP request and then populating it with the client's credentials. In this sample, credentials are sent over the network in clearly readable text.  However, if the text has to be sent in encrypted form, add an encryption algorithm.

Add the following keys in the Web.Config file of the Client Application, as shown below.

Listing 3

<add key="UserName"value="TestUser"/>
<add key="Password"value="TestPassword"/>

These are the credentials defined for the client application.

Run the Client Application

Now, run the Client application with the Listing 3 credentials (these are valid credentials for the Web service).  After the client logs into a service with a user name and password, the Web Service validates the User Credentials and returns them if the credentials are valid. These credentials are displayed on the Default.aspx, as shown below.

Figure 1

Now, modify the Key Values with the invalid credentials in the Web.Config file of the Client application, as shown below.

Listing 4

<add key="UserName"value="TestUser1"/>
<add key="Password"value="TestPassword1"/>

Next, refresh Figure 1.  The Web service validates the credentials received from the client once again. Since this time invalid credentials are sent to the web service, the following message is displayed on the Default.aspx form, as shown below.

Figure 2

Downloads

[Download Sample]

Conclusion

We have seen in this article how useful Soap Header authentication is for both secure and non-secure Internet scenarios.  User credentials are passed within the SOAP header of the SOAP message. The Web server, regardless of the platform hosting the XML Web service, provides a custom authentication implementation.

Also, we have seen that on the consumer/client-side, very little code is required to add a SOAP header into a request.  A proxy object does the majority of the work required in adding header details into SOAP messages.