How to: Configure an XML Web Service for Windows Authentication

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

.NET Framework Developer's Guide

How to: Configure an XML Web Service for Windows Authentication

[Note: This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

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

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.
Modify the configuration file to specify Windows authentication.
Set the mode attribute of the authentication XML element in a configuration file to "Windows". For details on how to configure a configuration file, see . 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

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
Create a new instance of the NetworkCredential class, setting the UserName, Password and Domain properties.
Create a new instance of CredentialCache.
Add the NetworkCredential to the CredentialCache using the Add method of CredentialCache
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 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.
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

Install SSL.
Configure the Web application to accept client certificates.
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". For details on how to configure a configuration file, see . 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

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.
Create a new instance of the X509Certificate.
Invoke the CreateFromCertFile(String) 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.

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(String) method and then added to the ClientCertificates property of the proxy class.

Visual Basic

' 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.<b>CreateFromCertFile</b>("c:\user.cer")

' Add the client certificate to the ClientCertificates property
' of the proxy class.
bank.<br /><b>ClientCertificates.Add</b>(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.<br /><b>CreateFromCertFile</b>(@"c:\user.cer");

// Add the client certificate to the ClientCertificates property
// of the proxy class.
bank.<br /><b>ClientCertificates.Add</b>(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 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.

Visual Basic

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.
<br /><b>     Dim mycredentialCache As CredentialCache = New CredentialCache()</b>

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

     ' Add the NetworkCredential to the CredentialCache.
<br /><b>       mycredentialCache.Add(New Uri(mathproxy.Url), "Basic", _</b><br /><b>                             credentials)</b>

     ' Add the CredentialCache to the proxy class credentials.
<br /><b>     mathproxy.Credentials = mycredentialCache</b>

     ' 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.
<br /><b>    CredentialCache credentialCache = new CredentialCache();</b>

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

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

   // Add the CredentialCache to the proxy class credentials.
<br /><b>   math.Credentials = credentialCache;</b>

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