How to: Use netTcpBinding with Windows Authentication and Message Security in WCF Calling from Windows Forms

Article
04/27/2010

Applies To

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

Summary

This how-to article shows you how to use netTcpBinding with Windows authentication and message security. netTcpBinding is used for communicating with WCF clients within an intranet and provides transport security with Windows authentication by default. The article shows you how to configure the service to use message security instead of transport security. For the purposes of this article, the WCF service is hosted in a Windows service.

Objectives
Overview
Summary of Steps
Step 1: Create a Windows Service
Step 2: Create a Sample WCF Service
Step 3: Modify the Windows Service to Host the WCF Service
Step 4: Configure the WCF Service to Use netTcpBinding with Message Security
Step 5: Configure the WCF Service to Publish Metadata
Step 6: Install the Windows Service
Step 7: Create a Test Client Application
Step 8: Test the Client and WCF Service
Additional Resources

Objectives

Learn how to create a WCF service hosted in a Windows service.
Learn how to expose the WCF service with message security.
Learn how to use Windows tokens for encrypting and signing your messages.
Learn why you need service principle names (SPNs) and how to create them.

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 Windows authentication. The scenario described in this article uses the netTcpBinding binding to expose a WCF service to WCF-enabled clients. The netTcpBinding binding offers improved performance over an HTTP binding. In this scenario, WCF is hosted in a Windows service. The WCF service with netTcpBinding can be consumed by a WCF-enabled .NET application through the use of a service reference. The Visual Studio service reference generates a proxy class to abstract the underlying message-based communication. WCF message security is used to support a secure communication channel in an end-to-end scenario. In general, you should always use transport security unless you need the additional flexibility that message security affords. For example, you would use message security for scenarios in which there are intermediaries who need to inspect and re-route the message.

In this how-to article, you will create a Windows service to host your WCF service. You will then create a sample WCF service in Visual Studio 2008 and configure the service to use netTcpBinding with message security through the use of the WCF Configuration Editor. Next, you will configure a mexTcpBinding so that the service can expose its metadata to clients, from which they can generate a WCF proxy and call your service. Finally, you will create a test client to verify that the service is working properly.

Solution Summary

Binding. By default, netTcpBinding offers improved performance over an HTTP binding and is the ideal choice for cross-machine communication between WCF clients and a WCF service within an intranet.
Security mode. Transport security is the default security mode for netTcpBinding and should be preferred over message security for better performance. If needed, message security can provide greater control over signing and encryption of the message.
Client authentication. Because this binding is used within an intranet, Windows is the recommended client authentication mechanism, though the default is UserName. The other possible values are None, Certificate, and IssuedToken.
Algorithm suite. The default message encryption algorithm used is Basic256, which should suffice for most scenarios. A stronger encryption algorithm can be chosen for increased security.
Hosting consideration. For the purposes of this how-to article, WCF is hosted in a Windows service. In general, netTcpBinding services can be hosted in a Windows service, Internet information Services (IIS) 7.0 (not IIS 6.0 or lower), or WAS, or it can be self-hosted. The choice should be based on the deployment requirements of the service.

Summary of Steps

Step 1: Create a Windows Service
Step 2: Create a Sample WCF Service
Step 3: Modify the Windows Service to Host the WCF Service
Step 4: Configure the WCF Service to Use netTcpBinding with Message Security
Step 5: Configure the WCF Service to Publish Metadata
Step 6: Install the Windows Service
Step 7: Create a Test Client Application
Step 8: Test the Client and WCF Service

Step 1: Create a Windows Service

In this step, you create a Windows service to host your WCF service.

In Visual Studio, on the File menu, click New and then click Project.
In the New Project dialog box, in the Project Types section, select Windows under Visual C#.
In the Templates section, select Windows Service, and then type the name of your project (WCFServiceHost) in the Name field.
In the Add a Project dialog box, click OK to add a sample Windows service to the solution.
Right-click Service1.cs and then click View Designer.
Right-click the designer and then click Add Installer to add the ProjectInstaller.cs file with two objects, serviceProcessInstaller1 and serviceInstaller1.
In the designer view of ProjectInstaller.cs, right-click serviceProcessInstaller1 and then click Properties.
In the Properties pane, set the Account attribute to NetworkService.

This will run your Windows service under the Network Service account.

Step 2: Create a Sample WCF Service

In this step, you add a WCF service to the Windows service that will host it.

Right-click the Windows service project, click Add, and then click New Item.
In the Add New Item dialog box, select WCF Service.
Set the Name as MyService.cs and then click the Add.

Note that the configuration file, App.config, gets added automatically.
Modify the DoWork() method signature in IMyService.cs to accept a string parameter and return a string data type as shown below:
```
string DoWork(string value);
```
Modify the DoWork() method in MyService.cs to accept a string parameter and return a string data type as shown below:
```
public string DoWork(string value)
      {
            return "Welcome " + value;
      }
```

Step 3: Modify the Windows Service to Host the WCF Service

In this step, you add code to the OnStart() and OnStop() methods to start and stop the WCF service inside the Windows service process.

In the Solution Explorer, right-click Service1.cs and then click View Code.
In the Service1.cs file, add a using statement as follows:
```
using System.ServiceModel;
```
Declare an internal static member of ServiceHost type as follows:
```
internal static ServiceHost myServiceHost = null; 
```

Add code to the OnStart method of the Windows service, to open the service:

protected override void OnStart(string[] args)
{
   if (myServiceHost != null)
   {
       myServiceHost.Close();
   }

   myServiceHost = new ServiceHost(typeof(MyService));
   myServiceHost.Open();
}

Add code to the OnStop method of the Windows service, to close the service host.

protected override void OnStop()
{
   if (myServiceHost != null)
   {
      myServiceHost.Close();
      myServiceHost = null;
   }
}

Build the solution and verify that your project produces WCFServiceHost.exe in your project \bin directory.

Step 4: Configure the WCF Service to Use netTcpBinding with Message Security

In this step, you configure your WCF service to use netTcpBinding and message security.

In the Solution Explorer, right-click the App.config file 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, expand the Services node and then expand WCFHostService.MyService.
Select the Host node, select the default BaseAddress in the Base addresses section, and then click Delete.
Click New and then in the Base Address Editor dialog box, set the Base address: to net.tcp://localhost:8523/WCFTestService.
Expand the Endpoints node, select the first [Empty Name] node, and then set the Name attribute to NetTcpBindingEndpoint.
Set the Binding attribute to netTcpBinding.
In the Configuration Editor dialog box, on the File menu, select Save.

In Visual Studio, verify the configuration in your App.config file, which should look as follows:

<services>
    <service behaviorConfiguration="WCFHostService.MyServiceBehavior"
        name="WCFHostService.MyService">
        <endpoint address="" binding="netTcpBinding"
               bindingConfiguration=""
               name="NetTcpBindingEndpoint"
               contract="WCFHostService.IMyService">
            <identity>
                <dns value="localhost" />
            </identity>
        </endpoint>
        <endpoint address="mex" binding="mexHttpBinding"
                  contract="IMetadataExchange" />
        <host>
            <baseAddresses>
                <add baseAddress="net.tcp://localhost:8523/WCFTestService" />
            </baseAddresses>
        </host>
    </service>
</services>

In the Configuration Editor, select the Bindings node and then click the New Binding Configuration link.
In the Create a New Binding dialog box, select netTcpBinding and then click OK.
Set the Name attribute to NetTcpBindingEndpointConfig on the newly created binding configuration.
Click the Security tab and then set the Mode attribute to Message.
Verify that the MessageClientCredentials attribute is set to Windows.
In the NetTcpBindingEndpoint binding created above, set the BindingConfiguration to NetTcpBindingEndpointConfig by selecting it from the drop-down list.
In the Configuration Editor dialog box, on the File menu, select Save.

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

...
<bindings>
    <netTcpBinding>
        <binding name="NetTcpBindingEndpointConfig">
            <security mode="Message" />
        </binding>
    </netTcpBinding>
</bindings>
...
<services>
    <service behaviorConfiguration="WCFHostService.MyServiceBehavior"
        name="WCFHostService.MyService">
        <endpoint address="" binding="netTcpBinding"
                   bindingConfiguration="NetTcpBindingEndpointConfig"
                   name="NetTcpBindingEndpoint" contract="WCFHostService.IMyService">
            <identity>
                <dns value="localhost" />
            </identity>
        </endpoint>
        <endpoint address="mex" binding="mexHttpBinding" bindingConfiguration=""
            contract="IMetadataExchange" />
        <host>
            <baseAddresses>
                <add baseAddress="net.tcp://localhost:8523/WCFTestService" />
            </baseAddresses>
        </host>
    </service>
</services>
...

Step 5: Configure the WCF Service to Publish Metadata

In this step, you configure your WCF service to publish metadata. Publishing the metadata will allow your client to add a reference to the WCF service.

In the Configuration Editor, expand the Services node and then expand the WCFHostService.MyService node.
Expand the Endpoints node, select the remaining [Empty Name] node, and then set the Name attribute to mexTcpBindingEndpoint.
Set the Binding attribute to mexTcpBinding.
In the Configuration Editor dialog box, on the File menu, lick Save.

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

...
<services>
    <service behaviorConfiguration="WCFHostService.MyServiceBehavior"
        name="WCFHostService.MyService">
        <endpoint address="" binding="netTcpBinding"
                      bindingConfiguration="NetTcpBindingEndpointConfig"
                  name="NetTcpBindingEndpoint" contract="WCFHostService.IMyService">
            <identity>
                <dns value="localhost" />
            </identity>
        </endpoint>
        <endpoint address="mex" binding="mexTcpBinding" bindingConfiguration=""
            name="mexTcpBindingEndpoint" contract="IMetadataExchange" />
        <host>
            <baseAddresses>                <add baseAddress="net.tcp://localhost:8523/WCFTestService" />
            </baseAddresses>
        </host>
    </service>
</services>
...

In the Configuration Editor, expand the Advanced node and then expand the Service Behaviors node.
Expand the WCFHostService.MyServiceBehavior node and then select the serviceMetadata node.
Set the HttpGetEnabled attribute to False.
In the Configuration Editor dialog box, on the File menu, select Save.

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

<behaviors>
    <serviceBehaviors>
        <behavior name="WCFHostService.MyServiceBehavior">
            <serviceMetadata httpGetEnabled="false" />
            <serviceDebug includeExceptionDetailInFaults="false" />
        </behavior>
    </serviceBehaviors>
</behaviors>

Step 6: Install the Windows Service

In this step, you install the Windows service and run it from the Services console.

Rebuild the solution and open a Visual Studio command prompt.
Navigate to the bin directory of the project where WCFServiceHost.exe was copied.
On the command line, execute the following command to install the service:
```
Installutil WCFServiceHost.exe 
```
After the service has installed successfully, open the Services console by executing services.msc on the command line.
In the Services console, search for the name of the service, Service1, and start it.

Note

If you have modified the service that is already installed, you can uninstall it by using following command:
Installutil /u WCFServiceHost.exe

Step 7: Create a 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 Forms Application.
In the Name field, type Test Client and then click OK.
Right-click your client project and then click Add Service Reference.
In the Add Service Reference dialog box, set the Service URI: to net.tcp://localhost:8523/WCFTestService and then click Go.
Set the Service reference name: to WCFTestService and then click OK.

Step 8: Test the Client and WCF Service

In this step, you use the test client to ensure that the WCF service is running properly.

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

Create an instance of the proxy and call the DoWork method on your WCF service.

When you call the service, your current user security context will automatically be passed to your WCF service. The code should look as follows:

private void button1_Click(object sender, EventArgs e)
{
      WCFTestService.MyServiceClient myService = new
                             WCFTestService.MyServiceClient();
      MessageBox.Show(myService.DoWork("Hello World!"));
      myService.Close();
}

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, it should display the message “Welcome Hello World!”.

Additional Resources

For more information on security authentication best practices, see Best Practices for Security in WCF.
For additional information on message security, see Message Security in WCF.
For more information on hosting in a Windows service, see How to: Host a WCF Service in a Managed Windows Service.
For more information on WCF hosing considerations, see Hosting Services.
For more information on netTcpBinding configuration options see <netTcpBinding>.