How to: Use wsHttpBinding with Windows Authentication and Transport Security in WCF Calling from Windows Forms

patterns & practices Developer Center

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 wsHTTPBinding binding type by using transport security. The article shows you how to configure WCF, create and install the necessary certificate, and test the service with a sample WCF client.

Contents

  • Objectives
  • Overview
  • Summary of Steps
  • Step 1: Create and Install a Service Certificate for Transport Security
  • Step 2: Create a Sample WCF Service Project with SSL
  • Step 3: Configure the Virtual Directory to Require SSL
  • Step 4: Configure wsHttpBinding for Windows Authentication and Transport Security
  • Step 5: Configure the Service to Publish Metadata Securely
  • Step 6: Create a Test Client Application
  • Step 7: Add a WCF Service Reference to the Client
  • Step 8: Test the Client and WCF Service
  • Additional Resources

Objectives

  • Learn how to create a WCF service hosted in Internet Information Services (IIS).
  • Learn how to configure the service to use the Secure Sockets Layer (SSL) protocol.
  • Learn how to create and configure a certificate for the service.
  • Learn how to expose the WCF service over wsHttpBinding.
  • Learn how to call the service from a test client.

Overview

Windows authentication is suited for scenarios in which your users have domain credentials. In the scenario described in this How To article, users are authenticated by Windows authentication. The wsHttpBinding binding is used in order to provide support for message-based security, reliable messaging, and transactions, while also allowing the possibility that legacy clients can consume the service. WCF transport security is used to support a secure communication channel in a point-to-point scenario. In general, you should always use transport security unless you need the additional flexibility that message security affords you. For example, you would use message security for scenarios in which there are intermediaries who need to inspect and re-route the message.

In order to use SSL for transport security, you first need to install a service certificate. This certificate will be used to encrypt and protect the communication channel. You then configure the WCF service and IIS to use SSL. You will set the clientCredentialType attribute to Windows on wsHttpBinding in order to configure the WCF service to use Windows authentication. You will then configure and expose a mexHttpsBinding endpoint to expose the service metadata to the client securely. This metadata allows the client to generate a proxy and call the service.

Summary of Steps

  • Step 1: Create and Install a Service Certificate for Transport Security
  • Step 2: Create a Sample WCF Service Project with SSL
  • Step 3: Configure the Virtual Directory to Require SSL
  • Step 4: Configure wsHttpBinding for Windows Authentication and Transport Security
  • Step 5: Configure the Service to Publish Metadata Securely
  • Step 6: Create a Test Client Application
  • Step 7: Add a WCF Service Reference to the Client
  • Step 8: Test the Client and WCF Service

Step 1: Create and Install a Service Certificate for Transport Security

In this step, you create a temporary service certificate and install it in the local store. This certificate will be used to establish an SSL connection between the client and the WCF service.

Creating and installing the certificate is outside the scope of this How To article. For instructions on how to do this, see “How To: Create and Install Temporary Certificates in WCF for Transport Security during Development” and follow Steps 1 through 4.

Note

Temporary certificate should be used for development and testing purposes only. For actual production deployment, you will need to obtain a valid certificate from a certificate authority (CA).

Step 2: Create a Sample WCF Service Project with SSL

In this step, you create a WCF service in Microsoft Visual Studio® and enable SSL.

  1. In Visual Studio, on the File menu, select New Web Site.
  2. In the New Web Site dialog box, under Templates, select WCF Service. Make sure that the Location is set to Http and then click Browse.
  3. In the Choose Location dialog box, click Local IIS.
  4. At the bottom of the dialog box, select the Use Secure Sockets Layer check box, and then click Open.
  5. In the New Web Site dialog box, set the new Web site address as https://localhost/WCFTestService and then click OK.

Note

Because the SSL port might not be configured by default on the IIS, it might throw errors while creating the WCF service. To prevent this, open IIS Manager, right-click Default Web Site, and then click Properties. In the Default Web Site Properties dialog box, click the Web Site tab and make sure that the SSL port: is set to 443.

Step 3: Configure the Virtual Directory to Require SSL

In this step, you configure the virtual directory hosting the WCF service to use SSL.

  1. Click Start, click Run, and then type inetmgr to open IIS Manager.
  2. In the Internet Information Services Manager dialog box, expand (local computer), expand the Web Sites node, and then expand the Default Web Site node.
  3. Right-click your virtual directory (WCFTestService) and then click Properties.
  4. In the Properties dialog box, click the Directory Security tab, and then in the Secure Communication section, click Edit.
  5. In the Secure communications dialog box, select the Require secure channel (SSL) check box.
  6. In the Secure communications dialog box, click OK.
  7. In the Properties dialog box, click OK.

Step 4: Configure wsHttpBinding for Windows Authentication and Transport Security

In this step, you configure the WCF service to use Windows authentication and transport security.

  1. 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.

  2. In the Configuration Editor, in the Configuration section, expand Service and then expand Endpoints.

  3. Select the first node [Empty Name] and set the Name attribute to wsHttpEndpoint.

  4. Click the Identity tab and delete the Dns attribute value, which by default is set to “localhost”.

  5. In the Configuration Editor, select the Bindings folder.

  6. In the Bindings section, select New Binding Configuration.

  7. In the Create a New Binding dialog box, select wsHttpBinding.

  8. Click OK.

  9. Set the Name of the binding configuration to some logical and recognizable name; for example, wsHttpEndpointBinding.

  10. Click the Security tab.

  11. Set the Mode attribute to Transport by choosing this option from the drop-down list.

  12. Make sure that the TransportClientCredentialType is set to Windows, which is the default setting.

  13. In the Configuration section, select the wsHttpEndpoint node.

  14. Set the BindingConfiguration attribute to wsHttpEndpointBinding by choosing this option from the drop-down list.

    This associates the binding configuration setting with the binding.

  15. In the Configuration Editor, on the File menu, click Save.

  16. In Visual Studio, open your configuration and comment out the identity element. It should look as follows:

          <!--<identity>
            <dns value="" />
          </identity>-->
    
  17. In Visual Studio, verify your configuration. The configuration should look as follows:

    …
    <bindings>
      <wsHttpBinding>
        <binding name="wsHttpEndpointBinding">
          <security mode="Transport">
          </security>
        </binding>
      </wsHttpBinding>
    </bindings>
    <services>
      <service behaviorConfiguration="ServiceBehavior" name="Service">
        <endpoint address="" binding="wsHttpBinding"
          bindingConfiguration="wsHttpEndpointBinding"
          name="wsHttpEndpoint" contract="IService">
          <!--<identity>
            <dns value="" />
          </identity>-->
        </endpoint>
        <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" />
      </service>
    </services>
    …
    

Step 5: Configure the Service to Publish Metadata Securely

In this step, you configure your WCF service to publish and secure the metadata. By publishing the metadata, you allow your client to add a reference to your WCF service.

  1. In the Configuration Editor, expand the Service node, and then expand Endpoints.

  2. Select the second endpoint created [Empty Name] and then set the Name attribute to “MexHttpsBindingEndpoint”.

  3. Set the Binding attribute to mexHttpsBinding.

  4. In the Configuration Editor, on the File menu, click Save.

  5. In Visual Studio, verify your configuration in App.config. The configuration should look as follows.

    …
    <services>
          <service behaviorConfiguration="ServiceBehavior" name="Service">
    <endpoint address="" binding="wsHttpBinding"
     bindingConfiguration="wsHttpEndpointBinding"
          name="wsHttpEndpoint" contract="IService">
    </endpoint>
          <endpoint address="mex" binding="mexHttpsBinding"
                           bindingConfiguration=""
                           name="MexHttpsBindingEndpoint" 
                           contract="IMetadataExchange" />
        </service>
    </services>
    …
    
  6. In the Configuration Editor, expand the Advanced node, and then expand the Service Behaviors node.

  7. Expand the ServiceBehavior node and then select the serviceMetadata node.

  8. Set the httpGetEnabled attribute to False and the httpsGetEnabled attribute to True.

  9. In the Configuration Editor, on the File menu, click Save.

  10. In Visual Studio, verify your configuration in App.config. The configuration should look as follows.

    …
    <behaviors>
      <serviceBehaviors>
          <behavior name="ServiceBehavior">
              <serviceMetadata httpGetEnabled="false" httpsGetEnabled="true" />
              <serviceDebug includeExceptionDetailInFaults="false" />
          </behavior>
      </serviceBehaviors>
    </behaviors>
    …
    

Step 6: Create a Test Client Application

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

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

Step 7: Add a WCF Service Reference to the Client

In this step, you add a reference to your WCF service so that your client can call the service.

  1. Right-click your Client project and then click Add Service Reference.

  2. In the Add Service Reference dialog box, set the URL to your WCF service—for example, https://<<YourMachineName>>/WCFTestService/Service.svc—and then click Go.

  3. In the Namespace field, change ServiceReference1 to WCFTestService and then click OK.

    A reference to WCFTestService should appear beneath Service References in your Client project.

Note

If the machine name used in the Add Service Reference dialog box does not match the certificate name, you will get an error when trying to add the reference. You can resolve this by ensuring that the certificate name matches the machine name used in this URL.

Step 8: Test the Client and WCF Service

In this step, you access the WCF service, pass the user credentials, and make sure that the authentication works through a secure channel (HTTPS).

  1. In your Client project, drag a button control onto your form.

  2. Double-click the button control to show the underlying code.

  3. In the code behind the button click, create an instance of the proxy and call the GetData operation of your WCF service. The code should look as follows:

    private void button1_Click(object sender, EventArgs e)
    {
          WCFTestService.ServiceClient myService = new
                        WCFTestService.ServiceClient();
    MessageBox.Show(myService.GetData(123));
          myService.Close();
    }
    
  4. Right-click the Client project and then click Set as Startup Project.

  5. 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