You may not wish to use any of the Windows authentication modes because you do not want to create each user who logs into your site as a user on your domain. If this is the case, you will need to build your own custom security mechanism. The SOAP protocol has already defined a SOAP header that can pass credential information. You can implement that in an XML Web Service by creating a custom class with login ID and password properties.
Creating a SOAP Header Class
You will now learn to create a SOAP header class in your Web Service project. To do this, you will need to create a new class that inherits from the .NET Framework SoapHeader class. The SoapHeader class is located in the System.Web.Services.Protocols namespace, so it is a good idea to import this namespace. Follow these steps:
Open your WSSecure Web Service project.
Open the Service1.asmx code-behind file and add the following line of code to the top of the file:
Now you will create the new class just below the Service1 class in this file.
Move your cursor to the line after End Class in the Service1 file.
Create the class shown in Listing 31.3.
Listing 31.3 The Simplest SoapHeader Class
Public Class LoginInfo Inherits SoapHeader Public UserName As String Public Password As String End Class
You can add any custom properties you need to this class in order to authenticate your user. For example, a simple class like the one shown in Listing 31.3 uses public variables to maintain UserName and Password properties. You can add as many additional properties as you want to this SoapHeader class, and they will be passed to your Web Service for you to extract them.
You will now create a new method in your Service1.asmx file to test out this SoapHeader class. To use this class, you will need to add some additional attributes to the WebMethod attribute of your Web Service function. In addition, you need to create a public member variable of the type LoginInfo. Here are the steps to follow:
Just above the WindowsSecure method, add the following public variable:
Public LoginCredentials As LoginInfo
Now you will create your new method, as shown in Listing 31.4.
Listing 31.4 This Simple Example Shows How You Can Use the SoapHeader Attribute
<WebMethod(), _ SoapHeader("LoginCredentials", _ Direction:=SoapHeaderDirection.InOut, _ Required:=True)> _ Public Function SOAPSecure() As String If LoginCredentials Is Nothing Then Return "Invalid User" Else Return "Hello " & LoginCredentials.UserName End If End Function
The SoapHeader attribute specifies the name of the class to use (LoginCredentials), the direction (InOut, indicating that the header will be sent to both the Web Service and to the client), and that the header is required. The name in the SoapHeader attribute "LoginCredentials" must match the name of the object you create in the Public variable. This method returns either "Invalid user" or text that includes the username, if the client passed in a LoginInfo object.
Calling the SOAP Method
When you call the SOAPSecure method of this Web Service, you will need to create a LoginCredentials object and fill in its UserName and Password properties. You then set the LoginInfoValue property of your Web Service to this new object. The LoginInfoValue property is automatically created whenever you have a class within a Web Service that uses a SOAP header. It will create a "Value" property, so you may create an instance of that class and pass the class to the Web Service.
After you fill in the LoginInfo object, .NET will serialize the information in this object and pass the header information with your request to the SOAPSecure Web Service method. Here's an example of how you might make this call to the secure Web Service:
Private Sub btnTestSoap_Click( _ ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles btnTestSoap.Click Dim ws As WebSecure.Service1 Dim lc As WebSecure.LoginInfo Try ' Create the Service ws = New WebSecure.Service1() ' Create the Login Credentials lc = New WebSecure.LoginInfo() ' Fill in the credentials lc.UserName = "Bill" lc.Password = "Gates" ' Place credentials object into web service ws.LoginInfoValue = lc ' Call the Web Service lblResponse.Text = ws.SOAPSecure() Catch exp As Exception lblResponse.Text = exp.Message End Try End Sub
After running this code, you would see the words "Hello Bill" appear in the Label control. This shows that the information got passed from the client to the Web Service via the LoginInfo object.
The information in the SOAP header is passed as an XML string in clear text across the Internet. As such, you should make sure you are using SSL if this information needs to be secure.