Microsoft ASP.NET QuickStarts Tutorial

   Windows Authentication and Authorization
   Custom Authentication and Authorization (with Soap Headers)
   Section Summary

This section describes methods for securing your XML Web services. If you haven't already read the Security section of this tutorial, take the time to do so now before continuing in this topic.

Windows Authentication and Authorization

You use the same technique to secure your XML Web services using Windows authentication that you used for .aspx pages (described in the Windows-based Authentication section). To require authentication, you enable Integrated Windows authentication for your application and disable Anonymous access in the IIS management console. To allow or deny specific users access to your service, use the ASP.NET configuration system or set ACLs on the service file itself, as shown in the following example:

<configuration>

  <system.web>
    <authentication mode="Windows"/>
  </system.web>

  <location path="secureservice.asmx">

    <system.web>
      <authorization>
        <allow users="Administrator"/>
        <allow users="DOMAIN\Bradley"/>
        <deny roles="BUILTIN\Power Users"/>
      </authorization>
    </system.web>

  </location>

</configuration>

This works well when you know that the client of the XML Web service will be running as a specific Windows user. A more interesting case is that of a client running as one user, but acting on behalf of another. Consider an ASP.NET page that accesses a secure XML Web service that does not impersonate the client who accesses it. In such a case, you should programmatically set the username and password before connecting to the Web service. The following example uses basic authentication and illustrates a simple XML Web service:


<%@ WebService language="VB" Class="SecureService" %>

Imports System.Web.Services
Imports System

Class SecureService : Inherits WebService


    <WebMethod()> Public Function SecureTest As String
        Return "Hello from the secure web service"
    End
End Class

You could require basic authentication for this service by making appropriate settings in IIS as follows:

Open the IIS MMC console.
```
Start->Run "inetmgr"
```
In the left pane, expand the tree to find your virtual directory.
In the right pane, right-click Secureservice.asmx, and choose Properties.
Select the File Security tab. Under Anonymous Access and Authentication Control, click Edit.
- Disable anonymous access.
- Disable integrated Windows authentication.
- Enable basic authentication.
Click OK to save these settings and exit the MMC console.

The base XML Web service proxy class provides two properties, Username and Password, that you can use to specify the credentials with which to connect to the remote Web service. These must be set to valid Windows credentials on the Web service's computer or domain.


<%@ Import Namespace="SecureService" %>

<html>
<script language="VB" runat="server">

    Public Sub Page_Load(sender As Object, e As EventArgs)

        Dim s As New SecureService

        s.Credentials = New System.Net.NetworkCredential("Administrator", "test123")

        Message.Text = s.SecureTest()
    End Sub

</script>

<body>
  <h4><font face="verdana">
    <asp:Label id="Message" runat="server"/>
  </font></h4>
</body>

</html>

The base XML Web service class also provides a User property of type System.Security.Principal.IPrincipal, which you can use to retrieve information about the client user. Again, you can authorize access to your Web service using the Authorization section in the ASP.NET configuration system.

Custom Authentication and Authorization with Soap Headers

Windows authentication works well for intranet scenarios, in which you are authenticating against a user in your own domain. On the Internet, however, you probably want to perform custom authentication and authorization, perhaps against a SQL database. In that case, you should pass custom credentials (such as the username and password) to your service and let it handle the authentication and authorization itself.

A convenient way to pass extra information along with a request to a XML Web service is a SOAP header. To do this, define a class that derives from SOAPHeader in your service, and then declare a public field of your service as that type. This is exposed in the public contract for your service, and made available to the client when the proxy is created from WebServiceUtil.exe, as in the following example:


Imports System.Web.Services
Imports System.Web.Services.Protocols

' AuthHeader class extends from SoapHeader
Public Class AuthHeader : Inherits SoapHeader
    Public Username As String
    Public Password As String
End Class

Public Class HeaderService : Inherits WebService
    Public sHeader As AuthHeader
    ...
End Class

Each WebMethod in your service can define a set of associated headers using the SoapHeader custom attribute. By default, the header is required, but it is possible to define optional headers as well. The SoapHeader attribute specifies the name of a public field or property of the Client or Server class (referred to as a Headers property in this topic). XML Web services sets the value of a Headers property before the method is called for input headers, and retrieves the value when the method returns for output headers. For more information about output or optional headers see the .NET Framework SDK documentation.




<WebMethod(), SoapHeader("sHeader")> Public Function SecureMethod() As String

    If (sHeader Is Nothing)
        Return "ERROR: Please supply credentials"
    Else
        Return "USER: " & sHeader.Username
    End If
End Function

A client then sets the header on the proxy class directly before making a method call that requires it, as shown in the following example:


Dim h As New HeaderService
Dim myHeader As New AuthHeader
myHeader.Username = "JohnDoe"
myHeader.Password = "password"
h.AuthHeader = myHeader
Dim result As String = h.SecureMethod()

To see this code in action, run the following sample:

VB SoapHeaders.aspx

[Run Sample] | [View Source]

Section Summary

Securing your XML Web services on the server using Windows authentication follows exactly the same model as described for .aspx page.
You can also programmatically set Windows credentials using the Username and Password properties on the XML Web service proxy class.
Lastly, you can do custom authentication by passing credential information as SOAPHeaders, along with a SOAP request to the method that requires it.