How to: Use basicHttpBinding with Windows Authentication and TransportCredentialOnly in WCF from Windows Forms

Article
04/27/2010

Applies To

Microsoft Windows Communication Foundation (WCF) 3.5
Microsoft Visual Studio 2008

Summary

This how-to article walks you through the process of using Windows authentication over the basicHttpBinding binding using the TransportCredentialsOnly security mode. The article shows you how to configure WCF, configure Internet Information Services (IIS) for Windows authentication, and test the service with a sample WCF client.

Objectives
Overview
Summary of Steps
Step 1: Create a Sample WCF Service
Step 2: Configure the WCF Service to Use basicHttpBinding
Step 3: Configure basicHttpBinding to use Windows Authentication with TransportCredentialOnly
Step 4: Enable Windows Authentication on IIS
Step 5: Create a Windows Forms Test Client Application
Step 6: Add a WCF Service Reference to the Client
Step 7: Test the Client and WCF Service
Additional Resources

Objectives

Learn how to create a WCF service hosted in IIS.
Learn how to expose the WCF service as a legacy Web service through basicHttpBinding.
Learn how to call the service from a test client.

Overview

Windows authentication is well suited for scenarios in which your users have domain credentials. In the scenario described in this how-to article, users are authenticated by using Windows authentication. The basicHttpBinding binding is used in order to provide support for older clients that expect a legacy ASMX Web service. The TransportCredentialOnly security mode option passes the user credentials without encrypting or signing the messages. Use this mode with caution as it will not protect the credentials being transmitted and they will have to be protected by some other means, such as Internet Protocol Security (IPSec).

In this how-to article, you will create a sample WCF service in Visual Studio 2008. You will then configure the service to use basicHttpBinding with TransportCredentialOnly security through the use of the WCF Configuration Editor. You will enable Windows authentication in IIS to allow your users to authenticate to the service. Finally, you will create a test client to verify that the service is working properly.

Summary of Steps

Step 1: Create a Sample WCF Service
Step 2: Configure the WCF Service to Use basicHttpBinding
Step 3: Configure the basicHttpBinding to use Windows Authentication with TransportCredentialOnly
Step 4: Enable Windows Authentication on IIS
Step 5: Create a Windows Forms Test Client Application
Step 6: Add a WCF Service Reference to the Client
Step 7: Test the Client and WCF Service

Step 1: Create a Sample WCF Service

In this step, you create a WCF service in Visual Studio, hosted in an IIS virtual directory.

In Visual Studio, on the File menu, click New Web Site.
In the Templates section, select WCF Service. Make sure that the Location is set to Http, and specify https://localhost/WCFServiceBasicHttp as the Path. Click OK in the New Web Site dialog box to create a virtual directory and a sample WCF service.
Browse to your WCF service at https://localhost/WCFServiceBasicHttp/Service.svc.

You should see your WCF service respond with details of the service.

Step 2: Configure the WCF Service to Use basicHttpBinding

In this step, you configure your WCF service endpoint to use basicHttpBinding.

Right-click the Web.config file of the WCF service and then click Edit WCF Configuration.

If you do not see the Edit WCF Configuration option, on the Tools menu, click WCF Service Configuration Editor. Close the WCF Service Configuration Editor tool that appears. The option should now appear on the web.config context menu.
In the Configuration Editor, in the Configuration section, expand Service and then expand Endpoints.
Select the first node [Empty Name]. Set the name attribute to BasicHttpEndpoint.

By default, the name will be empty because it is an optional attribute.
In the Service Endpoint section, set the binding attribute to basicHttpBinding by choosing this option from the drop-down list.
In the Configuration Editor, on the File menu, click Save.

In Visual Studio, verify your configuration settings in Web.config. The configuration should look as follows:

…
<services>
  <service behaviorConfiguration="ServiceBehavior" name="Service">
    <endpoint address="" binding="basicHttpBinding"
        name="BasicHttpEndpoint"
        bindingConfiguration=""
        contract="IService">
      <identity>
        <dns value="localhost" />
      </identity>
    </endpoint>
    <endpoint address="mex" binding="mexHttpBinding"
       contract="IMetadataExchange" />
  </service>
</services> 
…

Step 3: Configure basicHttpBinding to use Windows Authentication with TransportCredentialOnly

By default, the basicHttpBinding security mode is None. This default setting means that you do not have authentication and that neither transport nor message security is enabled. By enabling Windows authentication with TransportCredentialOnly, you will get authentication, but no message protection; this is similar to how an ASMX Web service works.

In the Configuration Editor, in the Configuration section, select the Bindings folder.
In the Bindings section, choose New Binding Configuration.
In the Create a New Binding dialog box, select basicHttpBinding.
Click OK.
Set the Name of the binding configuration to some logical and recognizable name; for example, BasicHttpEndpointBinding.
Click the Security tab.
Set the Mode attribute to TransportCredentialOnly by choosing this option from the drop-down menu.
Set the TransportClientCredentialType to Windows by choosing this option from the drop-down list.

In this case, the Windows option represents Kerberos.
In the Configuration section, select BasicHttpEndpoint.
Set the BindingConfiguration attribute to BasicHttpEndpointBinding by choosing this option from the drop-down list.

This associates the binding configuration setting with the binding.
In the Configuration Editor, on the File menu, click Save.

In Visual Studio, verify your configuration, which should look as follows:

...
<bindings>
  <basicHttpBinding>
    <binding name="BasicHttpEndpointBinding">
      <security mode="TransportCredentialOnly">
        <transport clientCredentialType="Windows" />
      </security>
    </binding>
  </basicHttpBinding>
</bindings>
<services>
  <service behaviorConfiguration="ServiceBehavior" name="Service">
    <endpoint address="" binding="basicHttpBinding"
      bindingConfiguration="BasicHttpEndpointBinding"
      name="BasicHttpEndpoint" contract="IService">
      <identity>
        <dns value="localhost" />
      </identity>
    </endpoint>
    <endpoint address="mex" binding="mexHttpBinding"
        contract="IMetadataExchange" />
  </service>
</services>
...

Step 4: Enable Windows Authentication on IIS

In this step, you enable IIS for Windows authentication to match the authentication scheme used in your WCF service.

Open Internet Information Services (IIS) Manager by running the inetmgr command from the command line.
Browse to the WCF Service virtual directory created in Step 1.
Right-click the virtual directory and then click Properties.
In the Properties dialog box, click the Directory Security tab.
In the Authentication and access control section, click Edit.
In the Authentication Methods dialog box, clear the Enable anonymous access check box, and then select the Integrated Windows authentication check box.
In the Authentication Methods dialog box, click OK.
In the Properties dialog box, click Apply and then click OK.
Run the iisreset command from the command line.
Verify that your service is working correctly. In IIS Manager, browse to your service (Service.svc).

Note

Important: Make sure that you have installed ASP.NET on your machine; if not or if in doubt, run the following command:
> c:\Windows\Microsoft.NET\Framework\vX.X.XXXXX\aspnet_regiis.exe /i

Step 5: Create a Windows Forms Test Client Application

In this step, you create a Windows Forms application to test the WCF service.

Right-click your solution, click Add, and then click New Project.
In the Add New Project dialog box, in the Templates section, select Windows Application.
In the Name field, type Test Client and then click OK to create a Windows Forms application.

Step 6: Add a WCF Service Reference to the Client

In this step, you add a Web reference of the WCF service to your Client application. This How To article uses a Web reference to show the usage of a WCF service as a legacy Web service; otherwise, you can add it as a service reference.

Right-click your Client project and then click Add Service References.
Click Advanced and then click Add Web Reference under the Compatibility section.
In the Add Web References dialog box, set the URL to your WCF service: https://localhost/WCFServiceBasicHttp/Service.svc
Click Go.
In the Web reference name: field, change localhost to WCFTestService.
Click Add Reference.

A Web reference to WCFTestService should now appear in your Client project.

Step 7: Test the Client and WCF Service

In this step, you access the WCF service as a legacy ASMX Web service and make sure that it works.

In your Client project, drag a button control onto your form.
Double-click the button control to show the underlying code.

In the code behind the button click, create an instance of the proxy, pass the default user credentials, and call MyOperation1 of your WCF Service. The code should look as follows:

private void button1_Click(object sender, EventArgs e)
{
      WCFTestService.Service myService = new 
                              WCFTestService.Service();
      myService.Credentials = 
                       System.Net.CredentialCache.DefaultCredentials;
      MessageBox.Show(myService.GetData(123, true));
      myService.Dispose();
}

Right-click the Client project and then click Set as Startup Project.
Run the Client application by pressing F5 or CTRL+F5. When you click the button on the form, the message “You entered: 123” should appear.

Additional Resources

For more information on using the DefaultCredentials property, see How to: Pass Current Credentials to an ASP.NET Web Service.