How to: Configure an XML Web Service for Windows Authentication

This topic is specific to a legacy technology. XML Web services and XML Web service clients should now be created using Windows Communication Foundation.

Code Example

Follow these procedures to configure and pass client credentials to a Web service using all forms of Windows authentication except Client Credentials. For that case, follow the procedures in the Client Certificate Authentication section.

To configure a Web service for Windows authentication

1. Configure the Web service to use Windows authentication, using IIS.

   IIS allows you to specify security at either the directory or file level. If you want to specify the security for a Web service on a per-file basis, set the permissions for the Web service on the .asmx file in IIS. The .asmx file is the entry point into the Web service. See the IIS documentation for details.

2. Modify the configuration file to specify Windows authentication.

   Set the mode attribute of the authentication XML element in a configuration file to "Windows". The following code example modifies a configuration file to use Windows authentication.

   // Fragment of a Web.config file.
   <authentication mode= "Windows">
   </authentication> 
   

To pass client credentials to a Web service using Windows authentication

1. Create a new instance of the proxy class to the Web service. If a proxy class has not been generated, see Creating an XML Web Service Proxy for details

2. Create a new instance of the NetworkCredential class, setting the UserName, Password and Domain properties.

3. Create a new instance of CredentialCache.

4. Add the NetworkCredential to the CredentialCache using the Add method of CredentialCache

5. Assign the instance of CredentialCache to the Credentials property of the proxy class.

   If Integrated Windows authentication is used, then you must set the Credentials property to System.Net.CredentialCache.DefaultCredentials.

   When the Credentials property is set to DefaultCredentials then the client negotiates with the server to do Kerberos and/or NTLM authentication depending on how the server is configured.

6. The following code example sets the client credentials passed to a Web service method using Windows authentication.

Client Certificate Authentication

Follow these procedures to configure and pass client credentials to a Web service using the Client Credentials form of Windows authentication.

To configure a Web service for Client Certificate authentication

1. The following list is an overview of how to configure IIS to authenticate clients using client certificates. For details, see the IIS documentation.

2. Install SSL.

3. Configure the Web application to accept client certificates.

4. Modify the configuration file to specify Windows authentication for the Web service.

   Set the mode attribute of the authentication XML element in a configuration file to "Windows". The following code example modifies a configuration file to use Windows authentication.

   // Fragment of a Web.config file.
   <authentication mode= "Windows">
   </authentication>
   

To pass client credentials to a Web service using Client Certificate authentication

1. Create a new instance of the proxy class to the Web service. If a proxy class has not been generated, see Creating an XML Web Service Proxy for details.

2. Create a new instance of the X509Certificate.

3. Invoke the CreateFromCertFile method to load the client certificate from a file.

   A client can obtain a client certificate file from a trusted certificate authority. For details, see the IIS documentation.

4. Add the X509Certificate to the ClientCertificates ClientCertificates collection of the proxy class.

   The following code example demonstrates how a Web service client passes its credentials using a client certificate. A client certificate issued from the Web server is loaded from a file with the CreateFromCertFile method and then added to the ClientCertificates property of the proxy class.

   ' Instantiate proxy class to a Bank Web service.
   Dim bank As BankSession = new BankSession()
   
   ' Load the client certificate from a file.
   Dim x509 As X509Certificate = X509Certificate.CreateFromCertFile("c:\user.cer")
   
   ' Add the client certificate to the ClientCertificates property
   ' of the proxy class.
   bank.ClientCertificates.Add(x509)
   
   ' Call the method on the proxy class, which requires authentication
   ' using client certificates.
   bank.Deposit(500)
   

   // Instantiate proxy class to a Bank Web service.
   BankSession bank = new BankSession();
   
   // Load the client certificate from a file.
   X509Certificate x509 = X509Certificate.CreateFromCertFile(@"c:\user.cer");
   
   // Add the client certificate to the ClientCertificates property
   // of the proxy class.
   bank.ClientCertificates.Add(x509);
   
   // Call the method on the proxy class, which requires
   // authentication using client certificates.
   bank.Deposit(500);
   

Example

When the Credentials property is set to System.Net.CredentialCache.DefaultCredentials then the client negotiates with the server to do Kerberos and/or NTLM authentication depending on how the server is configured.

The following code example sets the client credentials passed to a Web service method using Windows authentication.

Imports System
Imports System.Web.Services.Protocols
Imports System.Net
Imports MyMath

Public Class Calculator
   Public Shared Sub Main()
     ' Create a new instance of the proxy class to an
     ' Web service method. 
     Dim mathproxy As MyMath.Math = New MyMath.Math()
     
     ' Create a new instance of CredentialCache.
     Dim mycredentialCache As CredentialCache = New CredentialCache()

     ' Create a new instance of NetworkCredential using the client
     ' credentials.
       Dim credentials As NetworkCredential = New _          NetworkCredential(UserName,SecurelyStoredPasword,Domain)

     ' Add the NetworkCredential to the CredentialCache.
       mycredentialCache.Add(New Uri(mathproxy.Url), "Basic", _                             credentials)

     ' Add the CredentialCache to the proxy class credentials.
     mathproxy.Credentials = mycredentialCache

     ' Call the method on the proxy class.
     Dim result As Integer 
     result = mathproxy.Add(3,5)
  End Sub
End Class 

using System;
using System.Web.Services.Protocols;
using System.Net;
using MyMath;

public class Calculator
{
  public static void Main() 
  {
     // Create a new instance of the proxy class to an XML
     // Web service method. 
     MyMath.Math math = new MyMath.Math();

    // Create a new instance of CredentialCache.
    CredentialCache credentialCache = new CredentialCache();

   // Create a new instance of NetworkCredential using the client
   // credentials.
   NetworkCredential credentials = new
      NetworkCredential(UserName,SecurelyStroredPassword,Domain);

   // Add the NetworkCredential to the CredentialCache.
   credentialCache.Add(new Uri(math.Url),                        "Basic", credentials);

   // Add the CredentialCache to the proxy class credentials.
   math.Credentials = credentialCache;

     // Call the method on the proxy class.
     int result = math.Add(3,5);
  }
}

See Also

Tasks

How to: Perform Custom Authentication Using SOAP Headers

Reference

NetworkCredential
CredentialCache
X509Certificate

Concepts

Securing XML Web Services Created Using ASP.NET

Other Resources

ASP.NET Web Application Security
XML Web Services Using ASP.NET