Configuring HTTP

This article is now a part of the Windows SDK.

Although most people think of web servers when they hear HTTP, it's entirely possible to self-host WCF services over HTTP. You do need to perform some configuration magic to make this happen, especially if you want to peacefully coexist with an existing server like IIS. You also need to deal with the stronger security for services on Vista. This article explains how.

Configuring HTTP

Using Windows Communication Foundation (WCF) over HTTP either requires the use of a host, such as IIS, or manual configuration of the HTTP settings through the HTTP Server API. This document describes configuring WCF when using HTTP and HTTPS.

The instructions in this document use the httpcfg.exe tool to configure HTTP settings. This tool is a part of the Windows Support Tools download. With Windows Vista, it is now possible to configure these settings through the netsh tool. These settings are part of the http context of netsh.

Configuring SSL Certificates

Secure Sockets Layer (SSL) uses certificates on the client and server to store encryption keys. The server provides its SSL certificate when a connection is made so that the client can verify the identity of the server. The server can also request a certificate from the client to provide mutual authentication of both sides of the connection.

Certificates are stored in a centralized store according to the IP address and port number of the connection. The special IP address 0.0.0.0 matches any IP address for the local machine. Note that the certificate store does not distinguish URLs based on the path. Services with the same IP address and port combination must share certificates even if the path in the URL for the services is different. Modifying the certificates stored on the computer requires administrative privileges.

Use the "httpcfg.exe set ssl" command to register SSL certificates. The Windows Support Tools documentation explains the syntax for the httpcfg.exe tool. Client certificates require passing an additional "/f 2" flag to httpcfg.exe to indicate that the certificate may be used for the client side of mutual authentication.

Configuring Namespace Reservations

Namespace reservation assigns the rights for a portion of the HTTP URL namespace to a particular group of users. A reservation gives those users the right to create services that listen on that portion of the namespace. Reservations are URL prefixes, meaning that the reservation covers all subpaths of the reservation path. Namespace reservations permit various types of wildcarding. The HTTP Server API documentation describes the order of resolution between namespace claims that involve wildcards.

Modifying the reservation rights for a portion of the namespace requires either administrative privileges or ownership of that portion of the namespace. Initially, the entire HTTP namespace belongs to the local administrator. Use the "httpcfg.exe set urlacl" command to change namespace reservations. The Windows Support Tools documentation explains the syntax for the httpcfg.exe tool.

Configuring the IP Listen List

The HTTP Server API only binds to an IP address and port once a user registers an URL. By default, the HTTP Server API binds to the port in the URL for all of the IP addresses of the machine. A conflict arises if an application that doesn't use the HTTP Server API has previously bound to that combination of IP address and port. The IP Listen List allows WCF services to coexist with applications that use a port for some of the IP addresses of the machine. If the IP Listen List contains any entries, the HTTP Server API will only bind to those IP addresses that the list specifies.

Use the "httpcfg.exe set iplisten" command to modify the IP Listen List. The Windows Support Tools documentation explains the syntax for the httpcfg.exe tool. Modifying the IP Listen List requires administrative privileges. Issues Specific to Windows XP

• HTTP addressing is not integrated into the personal firewall on Windows XP. An exception must be added to the firewall configuration to allow inbound connections using a particular URL.
• IIS does not support port sharing on Windows XP. If IIS is running and a WCF service attempts to use a namespace with the same port, the WCF service will fail to start. IIS and WCF both default to using port 80. Either change the port assignment for one of the services or use the IP Listen List to assign the WCF service to a network adapter not used by IIS.

Other Configuration Settings

The HTTP Server API has some advanced configuration settings that are not available through httpcfg. These settings are maintained in the registry and apply to all applications running on the system that use the HTTP Server APIs. Microsoft Knowledge Base article 820129 describes these settings in detail. Most users should not need to change these settings.

Next time: Building a Custom File Transport, Part 1: Planning

Comments

• Anonymous
  April 14, 2006
  Statistics indicate that you likely would not be able to read this post without the help of network address...

• Anonymous
  July 24, 2006
  I still get a lot of hits for the series of documentation articles I did back in April and May.  All...

• Anonymous
  January 09, 2007
  I have a machine with multiple network cards. How do I control which networks my service listens on?

• Anonymous
  September 07, 2007
  I want to run this post as a reminder to people building and deploying services. I see people deploy