Implementing Security in a Windows Domain | Microsoft Windows Communication Foundation Step by Step (Step By Step Developer Series)

In the following exercises, you will see how to use transport and message level security in some common scenarios that can arise within a single organization. Because it is easier to demonstrate and explain things this way around, you will start by learning how to implement message confidentiality by encrypting messages. You will then see how to authenticate users running in a Windows environment, and finally, how to use the Windows Token Role provider to authorize access to operations.

Protecting a TCP Service at the Message Level

Message encryption is a very common requirement of most distributed systems; so much so that the majority of the standard bindings available in the WCF library encrypt messages by default. For example, the NetTcpBinding binding automatically encrypts data at the transport level if you have configured SSL over TCP. The NetTcpBinding binding also supports encryption at the message level, giving you a greater degree of control over the encryption algorithm used and without requiring you to configure SSL. You will use message level security to implement message encryption in the first exercise.

Enable message level encryption for the NetTcpBinding binding for the WCF service

Using Visual Studio 2005, open the solution file ProductsService.sln located in the Microsoft Press\WCF Step By Step\Chapter 4\ProductsService folder under your \My Documents folder.

This solution contains three projects: the ProductsService service, the ProductsService-Host application, and the ProductsClient. These projects are configured to catch and handle SOAP faults, as described in Chapter 3, “Making Applications and Services Robust.”
Expand the ProductsServiceHost project in Solution Explorer, right-click the App.config file, and then click Edit WCF Configuration.
In the WCF Service Configuration Editor, right-click the Bindings folder and then click New Binding Configuration.
In the Create a New Binding dialog box, select the netTcpBinding binding type and then click OK.

The WCF Service Configuration Editor generates a binding configuration with the default settings for the NetTcpBinding binding.
In the right pane of the WCF Service Configuration Editor, change the Name property of the binding to ProductsServiceTcpBindingConfig.
Click the Security tab.

Change the Mode property to Message. Change the AlgorithmSuite property to Basic128. Leave the MessageClientCredentialType property set to Windows.

These settings cause the binding to use message level security. Users will be expected to provide a valid Windows username and password, and all messages will be encrypted by using the Advanced Encryption Standard (AES) 128-bit algorithm. This is a widely used algorithm that is relatively quick to perform but should provide sufficient privacy for messages inside an organization (if you are sending messages across a public wide area network such as the Internet, you might prefer to use Basic256, which is the default value).

Note

If you set the Mode to None, then the binding will not encrypt data and any settings you specify for transport or message level security will be ignored. The Transport mode selects transport level security (SSL) rather than message level security, and the TransportWithMessageCredential mode uses message level security to provide the identity of the user for authorization purposes, while performing encryption at the transport level. Transport level encryption is usually more efficient than message level encryption, although it requires more configuration on the part of the administrator.

In the left pane of the WCF Service Configuration Editor, expand the Products.ProductsServiceImpl service in the Services folder, expand the Endpoints folder, and then click the ProductsServiceTcpBinding endpoint.
In the right pane, set the BindingConfiguration property to ProductsServiceTcpBindingConfig.

This action associates the binding configuration with the binding. All messages sent by using the ProductsServiceTcpBinding will use message level security and will be encrypted.
Save the configuration, and then exit the WCF Service Configuration Editor.

In Visual Studio 2005, open the file App.config in the ProductsServiceHost project. In the <system.serviceModel> section, you should see the new binding configuration, and the reference to this configuration in the ProductsServiceTcpBinding endpoint, as follows:

 … <system.serviceModel>   <bindings>     <netTcpBinding>       <binding name="ProductsServiceTcpBindingConfig">         <security mode="Message">           <message algorithmSuite="Basic128" />         </security>       </binding>     </netTcpBinding>   </bindings>   <services>     <service behaviorConfiguration="ProductsBehavior"              name="Products.ProductsServiceImpl">       …       <endpoint binding="netTcpBinding"          bindingConfiguration="ProductsServiceTcpBindingConfig"         name="ProductsServiceTcpBinding" contract="Products.IProductsService" />     </service>   </services>   … </system.serviceModel>

Be careful not to change anything in this file. Close the App.config file when you have finished examining it.

The service will expect clients that connect to the endpoint for this binding to use the same message level security settings. You will configure the client next.

Enable message level encryption for the NetTcpBinding binding for the WCF client

In the ProductsClient project, edit the app.config file by using the WCF Service Configuration Editor.

In the WCF Service Configuration Editor, right-click the Bindings folder and then click New Binding Configuration.

Note

The client configuration file already contains a binding configuration for the basicHttpBinding that was generated in Chapter 1, “Introducing Windows Communication Foundation.” Be careful not to modify this binding configuration by mistake!

In the Create a New Binding dialog box, select the netTcpBinding binding type and then click OK.
In the right pane of the WCF Service Configuration Editor, change the Name property of the binding to ProductsClientTcpBindingConfig.
Click the Security tab.

Change the Mode property to Message. Change the AlgorithmSuite property to Basic128. Leave the MessageClientCredentialType property set to Windows.

Note

If you select a different algorithm suite for the client and server, they will not be able to decipher each other’s communications. This will result in a runtime exception in the channel stack. If you are curious about this, try setting the AlgorithmSuite to TripleDes (for example) and examine the exception that occurs when you run the solution later.

In the left pane of the WCF Service Configuration Editor, click the NetTcpBinding_IProductsService node in the Endpoints folder, under the Client folder.
In the right pane, set the BindingConfiguration property to ProductsClientTcpBinding Config.
Save the configuration, and then exit the WCF Service Configuration Editor.
Start the solution without debugging.
In the ProductsServiceHost form, click Start. If a Windows Security Alert dialog box appears, click Unblock to allow the service to access the TCP port.
In the client console window, press Enter. Verify that the client application runs exactly as before.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

This exercise has shown you how easy it is to configure a WCF service and client application to secure messages by performing encryption, but how do you actually know that the messages have been encrypted? To answer this question, you can enable message tracing and then examine the messages as they flow in and out of the service.

Configure message tracing for the WCF service

In Visual Studio 2005, edit the App.config file for the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the WCF Service Configuration Editor, expand the Diagnostics folder and then click Message Logging.

In the right pane displaying the message logging settings, set the following properties to True:

LogEntireMessage
LogMessagesAtServiceLevel
LogMessagesAtTransportLevel

The LogEntireMessage property specifies whether the trace output should include the body of messages sent and received. Setting this property to True includes the body of the message. The default value, False, only traces the message header. Setting the LogMessagesAtServiceLevel property to True traces messages as they are presented to the service and as they are output from the service. If you are using message level security, this trace will show the unencrypted messages after they have been received and decrypted at the message level (for incoming messages) or before they are encrypted (for outgoing messages). Setting the LogMessagesAtTransportLevel property to True traces messages as they are sent to or received from the transport level. If you are using message level security, the messages traced at this point will be encrypted, although if you are using transport level security messages will already have been decrypted (for incoming messages) or not yet encrypted (for outgoing messages) at this point.

Important

Tracing at the message level records messages in their unencrypted form. You should ensure that you protect the trace files that are generated and only let authorized users examine this data.

In the left pane, right-click the Sources folder and then click New Source.

All tracing information for WCF is received from one or more trace sources. In this case, you will use the MessageLogging source, which traces messages. You can also use other sources. For example, the ServiceModel source traces events that occur in a service, such as tracking when a service starts listening, receives requests, and sends responses.
In the right pane, set the Name property to System.ServiceModel.MessageLogging. Set the Trace level property to Verbose.
In the left pane, right-click the Listeners folder, and then click New Listener.

A listener object is responsible for receiving data from the trace sources, formatting and filtering them, and then sending them to a destination.
In the right pane, set the Name property to MessageLog.
In the InitData property, click the ellipses button. In the Save Log As dialog box, move to the Microsoft Press\WCF Step By Step\Chapter 4 folder under your \My Documents folder. Set the file name to Products.svclog, and then click Save.

The InitData property specifies the name of the file that the listener will use for saving trace data. When tracing starts, if this file does not exist, the listener will create it; otherwise, it will append trace information to the end of any existing data in the file.
In the TraceOutputOptions property, click the dropdown arrow. Clear all items in the list. The trace output options are useful if you are tracing messages for multiple client applications and you need to be able to correlate the different request and response messages. In this example, you will be running a single client application, so this additional information is not really necessary.
Verify that the TypeName property is set to System.Diagnostics.XmlWriter.TraceListener. The listener can output data in several formats. However, you will be using another tool called the Service Trace Viewer to examine the trace output, and this tool expects the data to be in XML format.
Click Add at the bottom of the right pane. In the Add Tracing Source dialog box, select the System.ServiceModel.MessageLogging source, and then click OK.
Save the configuration, and then exit the WCF Service Configuration Editor.

Run the WCF client and service and examine the trace output

Start the solution without debugging.
In the ProductsServiceHost form, click Start.
In the client console window, press Enter. Verify that the client application still runs correctly.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.
On the Windows Start menu, point to All Programs, point to Microsoft Windows SDK, point to Tools, and then click Service Trace Viewer.
In the Service Trace Viewer, on the File menu, click Add.
In the Open dialog box, move to the Microsoft Press\WCF Step By Step\Chapter 4\ProductsService folder under your \My Documents folder, select the file Products.svclog, and then click Open.
In the Service Trace Viewer, in the left pane, click the Message tab. You will see a list of messages sent and received by the service, identified by their Action values.

Tip
Expand the Action column in this pane to see more of the name for each action.

At the top of this list are a number of messages in the http://schemas.xmlsoap.org/ws/2005/02/trust namespace. These messages are concerned with sending and verifying the user’s identity, and negotiating the encryption mechanism and encryption keys that the client application and WCF service will use for sending and receiving messages. These messages are followed by the application messages received and sent by the WCF service, identified by the http://tempuri.org namespace.
Click the first message with the action http://tempuri.org/IProductsService/ListProducts. Note that each action occurs twice. This is because you traced each message twice: once at the message level and once at the transport level.
In the lower right pane, click the Message tab. The window will display the entire SOAP message. This is the version of the message passed from the transport level to the message level. The message has a rather lengthy SOAP header, which you can examine at your leisure. The interesting part is the SOAP body, at the end of the message. This is the encrypted ListProducts request received from the client application. The <e:CipherValue> element contains the data for the request, as highlighted in the following image:
In the left pane, click the second message with the action http://tempuri.org/IProductsService/ListProducts. In the right pane, scroll to the end of the Message window. This is the unencrypted version of the message passed from the message level to the service:
In the left pane, click the first message with the action http://tempuri.org/IProductsService/ListProductsResponse. In the right pane, examine the message body in the Message window. You can see that this is an unencrypted message containing the list of products returned in response to the ListProducts request. This message is the output from the service to the message level and so has not yet been encrypted.
In the left pane, click the second message with the action http://tempuri.org/IProductsService/ListProductsResponse. In the right pane, scroll to the bottom of the Message window and examine the message body. This time you can see that this is the encrypted response sent by the message level to the transport level for transmission back to the client.
Examine the other messages. When you have finished, close the Service Trace Viewer.

Protecting an HTTP Service at the Transport Level

If you recall, the ProductsServiceHost application exposes two endpoints for clients to connect to: one based on the TCP protocol and the other using HTTP. The HTTP endpoint is configured to use the BasicHttpBinding binding. The BasicHttpBinding binding conforms to the WS-BasicProfile 1.1 specification and is intended for use with existing legacy Web services and clients. It is fully interoperable with ASP.NET Web services. By default, this binding provides minimal security; it does not support message level encryption or authentication, for example. To implement message confidentiality and remain interoperable with ASP.NET Web services, you should use transport level security. This requires you to configure HTTPS.

Note

The BasicHttpBinding binding also supports message level security. Ordinary ASP.NET Web services and client applications do not implement the WS-Security specification, and so will not be able to communicate with a service that implements message level security. However, Microsoft Web Services Enhancements (WSE) does support WS-Security, so Web services that you create by using WSE can communicate with a WCF service through an endpoint based on the BasicHttpBinding binding by using message level security.

Specify transport level security for the BasicHttpBinding binding for the WCF service

In Visual Studio 2005, in the ProductsServiceHost project in Solution Explorer, edit the App.config file by using the WCF Service Configuration Editor.
In the WCF Service Configuration Editor, right-click the Bindings folder and then click New Binding Configuration.
In the Create a New Binding dialog box, select the basicHttpBinding binding type and then click OK.
In the right pane of the WCF Service Configuration Editor, change the Name property of the binding to ProductsServiceBasicHttpBindingConfig.
Click the Security tab. Set the Mode to Transport.

In this mode, message security is provided by using HTTPS. You must configure SSL for the service by using a certificate. The client authenticates the service by using the service’s SSL certificate. The service authenticates the client by using the mechanism specified by the TransportClientCredentialType property. The default value of None does not provide any authentication–you will examine some of the other values you can specify for this property later in this chapter.
In the left pane of the WCF Service Configuration Editor, expand the ProductsServices-Impl service in the Services folder, expand the Endpoints folder, and then click the ProductsServiceHttpEndpoint endpoint.
In the right pane, set the BindingConfiguration property to ProductsServiceBasicHttpBindingConfig.
HTTP Web services that implement transport level security must specify the https scheme, so change the Address property as follows:
```
 https://localhost:8000/ProductsService/ProductsService.svc
```
Save the configuration, and exit the WCF Service Configuration Editor.
Rebuild the ProductsServiceHost project.

The next step is to reconfigure and modify the client to connect to the service by using the endpoint corresponding to the BasicHttpBinding binding.

Specify transport level security for the BasicHttpBinding binding for the WCF client

In the ProductsClient project, edit the app.config file by using the WCF Service Configuration Editor.
In the WCF Service Configuration Editor, expand the Bindings folder and then click the BasicHttpBinding_IProductsService binding.
In the right pane of the WCF Service Configuration Editor, change the Name property of the binding to ProductsClientBasicHttpBindingConfig. (This is to make the name of the binding consistent with the other bindings you have created. The original binding name was generated by the svcutil utility back in Chapter 1.)
Click the Security tab. Change the Mode to Transport.
In the left pane of the WCF Service Configuration Editor, click the BasicHttpBinding_IProductsService endpoint in the Endpoints folder, under the Client folder.
In the right pane, change the address to use the https scheme as shown below, and verify that the BindingConfiguration property has changed to ProductsClientBasicHttpBindingConfig:
```
 https://localhost:8000/ProductsService/ProductsService.svc
```
Save the configuration, and then exit the WCF Service Configuration Editor.
In Visual Studio 2005, in Solution Explorer, open the Program.cs file for the ProductsClient project.
In the Main method, update the statement that creates the proxy object to connect to the WCF service by using the endpoint named BasicHttpBinding_IProductsService:
```
 ProductsServiceClient proxy = new ProductsServiceClient("BasicHttpBinding_ IProductsService");
```
Rebuild the ProductsClient project.

If you try and run the client and service at this point, the client will fail with a CommunicationException, like this:

This error occurs because you have not yet configured transport security for the HTTPS protocol. In the next exercise, you will create a certificate for the WCF service, and configure SSL for the service by using the httpcfg utility.

Configure the WCF HTTP endpoint with an SSL certificate

On the Windows Start menu, point to All Programs, point to Microsoft Windows SDK, and then click CMD Shell.

A command prompt window opens, with an environment configured for running the Windows SDK tools.

In the command prompt window, type the following command:

 makecert -sr LocalMachine -ss My -n CN=HTTPS-Server -sky exchange -sk HTTPS-Key

The makecert utility is a useful tool for creating test certificates that you can use for development purposes. The command shown here creates a certificate that is stored in the Personal certificates store for the LocalMachine account. For detailed information about the options for the makecert utility, see the Windows SDK Documentation installed with the Windows SDK.

Important

Certificates that you create by using the makecert utility should not be used in a production environment as they are not certified by a verifiable certification authority. Remember that the service sends this certificate to the client to prove its identity. The client must be able to trust that this certificate was created by a reliable source that can verify the veracity of the service. When deploying a production service, you should obtain your certificates from recognized certification authority, such as VeriSign or Thawte. Alternatively, you can use Windows Certificate Services, which enables an enterprise to generate its own certificates.

To use the httpcfg utility to configure SSL for the service, you need to find the thumb-print of the certificate. The thumbprint is a hexadecimal string that uniquely identifies the certificate. You can obtain this information by using the Certificates Microsoft Management Console snap-in.

In the command prompt window, type the following command:
```
 mmc
```
This command starts the Microsoft Management Console, displaying the default Console Root window.
In the File menu, click Add/Remove Snap-In.
In the Add/Remove Snap-In dialog box, click Add.
In the Add Standalone Snap-In dialog box, select the Certificates snap-in and then click Add.
In the Certificates Snap-In dialog box, select Computer account and then click Next.
In the Select Computer dialog box, select Local computer and then click Finish.
In the Add Standalone Snap-In dialog box, click Close.
In the Add/Remove Snap-In dialog box, click OK.
In the Console Root window, expand the Certificates node, expand the Personal folder, and then click the Certificates folder. The HTTPS-Server certificate that you created by using the makecert utility should be displayed:
Double-click the HTTPS-Server certificate.
In the Certificate window, click the Details tab. Scroll to the bottom of the window displaying the details of the certificate. Click the Thumbprint property, and make a note of the hexadecimal string displayed in the lower window:

Tip
You might find it useful to simply select the text in the lower window and copy it to the Windows clipboard.
Click OK, close the Microsoft Management Console window, and return to the command prompt window.

In the command prompt window, type the command shown below. Replace the hexadecimal string following the –h flag with the digits from the certificate thumbprint (remove all spaces from the thumbprint string first):

 httpcfg set ssl -i 0.0.0.0:8000 -h c390e7a4491cf97b96729167bf50186a4b68e052

If this command is successful, it should report the message “HttpSetServiceConfiguration completed with 0.”

Note

Be very careful to specify the correct thumbprint. If you type an invalid thumb-print, the command still succeeds, but the client will not be able to communicate with the service as the thumbprint does not refer to a valid certificate.

This command binds the certificate with the thumbprint indicated with the –h flag to the port indicated by the –i flag. The port is specified as the IP address of the computer followed by the port. Specifying an IP address of 0.0.0.0 denotes the local computer.

Note

Under Windows Vista, use the netsh command to configure SSL rather than httpcfg., like this: netsh http add sslcert ipport=0.0.0.0:8000 certhash= c390e7a4491cf97b96729167bf50186a4b68e052 appid={}. The certhash parameter specifies the thumbprint. The appid parameter is a GUID that identifies this binding of the certificate to the port; you can use any unique GUID.

Warning

When a client application receives a certificate from a server, the WCF runtime attempts to ascertain that the certificate is valid and that the authority that issued it is trusted. The WCF runtime will fail this check when using the certificate that you have just installed. The following exercise shows how to force the WCF runtime to override this check and allow this certificate to be used. You should never do this in a production environment! The code is provided as-is, and without further explanation (it is not the author’s work–it was written by developers at Microsoft and is included in one of the WCF technology samples provided with the Windows SDK). In the real world, you should go out and buy a valid certificate.

Add code to the WCF client to override certificate validation checking

In Visual Studio 2005, edit the Program.cs file for the ProductsClient project.

Add the following using statements to the list at the top of the file:

 using System.Security.Crytography.X509Certificates; using System.Net;

Add the following class to the ProductsClient namespace, underneath the Program class:

Note

The code for this class is available in the PermissiveCertificatePolicy.cs file in the Chapter 4 folder, if you don’t want to type it in manually.

 // WARNING: This code is only needed for test certificates such as those // created by makecert. It is not recommended for production code. class PermissiveCertificatePolicy {     string subjectName;     static PermissiveCertificatePolicy currentPolicy;     PermissiveCertificatePolicy(string subjectName)     {         this.subjectName = subjectName;         ServicePointManager.ServerCertificateValidationCallback +=             new System.Net.Security.RemoteCertificateValidationCallback             (RemoteCertValidate);     }     public static void Enact(string subjectName)     {         currentPolicy = new PermissiveCertificatePolicy(subjectName);     }     bool RemoteCertValidate(object sender, X509Certificate cert,             X509Chain chain, System.Net.Security.SslPolicyErrors error)     {         if (cert.Subject == subjectName)         {             return true;         }         return false;     } }

Add the following statement shown in bold to the Main method of the Program class, immediately before creating the proxy object:

 … PermissiveCertificatePolicy.Enact("CN=HTTPS-Server"); ProductServiceClient proxy = new ProductServiceClient(…); …

Run the WCF client and service

Start the solution without debugging.
In the ProductsServiceHost form, click Start.
In the client console window, press Enter. Verify that the client application runs correctly.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

Protecting an HTTP Service at the Message Level

You can configure the BasicHttpBinding binding to provide message level security by selecting the Message security mode for the binding. In this mode, the service uses SOAP message level security to encrypt the message. The service must have a certificate installed, and the client uses the public key from the service’s certificate to perform the encryption. The service can send the certificate containing its public key at the start of the message exchange, or an administrator can install the service certificate on the client computer before the client application (in which case you must specify how to locate the service certificate in the client certificate store by adding a service behavior using the <serviceCredentials> element to the client configuration file). You will learn more about this in Chapter 5. Additionally, the only authentication mechanism supported by a WCF service that uses this mode requires that the client application identifies itself with a certificate–you cannot use authentication mechanisms such as Windows Integrated Security with this mode.

One other option is to use the TransportWithMessageCredential security mode. This is a hybrid combination of message level and transport level security. The service uses the HTTPS protocol and a certificate to provide message integrity and confidentiality. Client authentication is handled at the message level by using SOAP message security, and the client application can provide a username and password to identify the user. You will learn more about this security mode in Chapter 5.

If you really want to implement message level security for a WCF service with the minimum of fuss and configuration, you can opt to use the WSHttpBinding binding. The WSHttpBinding binding conforms to the current WS-* specifications and follows the WS-Security specification for encrypting messages and authenticating users by default. The following exercises demonstrate how to use the WSHttpBinding binding to implement message level security over HTTP.

Configure the WCF service to use the WSHttpBinding binding

In Visual Studio 2005, edit the App.config file for the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the left pane, expand the Products.ProductsServiceImpl node under the Services folder, right-click Endpoints, and then click New Service Endpoint.

In the right pane, set the properties of the endpoint to the values in the following table. Leave all other properties with their default value:

Open table as spreadsheet

Property	Value
Name	ProductsServiceWSHttpEndpoint
Address	http://localhost:8010/ProductsService/ProductsService.svc
Binding	wsHttpBinding
Contract	Products.IProductsService

Notice that the scheme used for the address of this endpoint is http, and not https.

Save the changes, and exit the WCF Service Configuration Editor.
Rebuild the ProductsServiceHost project.

Configure the WCF client to use the WSHttpBinding binding

Edit the app.config file for the ProductsClient project by using the WCF Service Configuration Editor.
In the left pane, right-click Endpoints in the Client folder, and then click New Client Endpoint.

In the right pane, set the properties of the endpoint to the values in the following table:

Open table as spreadsheet

Property	Value
Name	WSHttpBinding_IProductsService
Address	http://localhost:8010/ProductsService/ProductsService.svc
Binding	wsHttpBinding
Contract	ProductsClient.ProductsService.IProductsService

Save the changes, and exit the WCF Service Configuration Editor.
In Visual Studio 2005, edit the Program.cs file in the ProductsClient project. In the Main method, change the code that creates the proxy object to use the new binding, as follows:
```
 ProductsServiceClient proxy = new     ProductsServiceClient("WSHttpBinding_IProductsService");
```
Rebuild the ProductsClient project.

Run the WCF client and service and examine the trace output

Using Windows Explorer, delete the existing trace file Products.svclog in the Microsoft Press\WCF Step By Step\Chapter 4\ProductsService folder under your \My Documents folder.
In Visual Studio 2005, start the solution without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter. Verify that the client application still runs correctly. Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.
Start the Service Trace Viewer tool, and open the Products.svclog file.
In the Service Trace Viewer, in the left pane, click the Message tab.
Click the first message with the action http://tempuri.org/IProductsService/ListProducts. In the lower right pane, click the Message tab. You can see that the message has been encrypted–the body element of the message contains encrypted data.
In the left pane, click the second message with the action http://tempuri.org/IProductsService/ListProducts. In the right pane, scroll to the end of the Message window. This is the unencrypted version of the message passed from the message level to the service.
Examine the two ListProductsResponse messages. As with the NetTcpBinding example earlier in this chapter, you can see the encrypted version of the message being output by the service to the message level and the encrypted version of the message passing from the message level to the transport level.
Close the Service Trace Viewer.

The WSHttpBinding binding uses the 256-bit version of the AES encryption algorithm to encrypt data by default. You can select a different algorithm by creating a binding behavior and specifying the algorithm to use in the AlgorithmSuite property of the behavior, as you did when configuring message level security for the NetTcpBinding binding earlier in this chapter.

Authenticating Windows Users

So far, you have seen how to configure the NetTcpBinding, BasicHttpBinding, and WSHttp-Binding bindings to support confidentiality and privacy by encrypting messages. However, transporting messages securely is only useful if a service can verify the identity of the user running the client application. In the exercises that follow, you will look at how a service can authenticate a user when the client application and service are both running within the same Windows domain. In Chapter 5, you will see how to perform authentication when a client and service are located in different, possibly non-Windows, security domains.

You will start by adding code to the ProductsService service that displays the name of the user calling the ListProducts operation. You will then be able to see the effect that the authentication options available in WCF have on the identity passed from a client application to a service.

Note

You can configure authentication to be largely transparent to the WCF service. You will see in the exercises in this section that most of the actual authentication process is performed by the WCF runtime executing the service. All the service needs to do is specify the type of authentication it requires.

Display the name of the user calling an operation in the WCF service

In Visual Studio 2005, add a reference to the System.Windows.Forms assembly to the ProductsService project.
Open the ProductsService.cs file.

This file contains the code that implements the operations for the ProductsService service.
Add the following using statements to the list at the top of the file:
```
 using System.Threading; using System.Windows.Forms;
```
Locate the ListProducts method in the ProductsServiceImpl class. Add the following statements as the first two lines of the method:
```
 string userName = Thread.CurrentPrincipal.Identity.Name; MessageBox.Show("Username is " + userName,                 "ProductsService Authentication");
```
The first statement retrieves the name of the Windows user that the current thread is running on behalf of. The second statement displays the username in a message box.
Edit the Program.cs file in the ProductsClient project. In the Main method, change the code that creates the proxy object to use the BasicHttpBinding binding, as follows:
```
 ProductsServiceClient proxy = new     ProductsServiceClient("BasicHttpBinding_IProductsService");
```
Start the solution without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

A message box appears, displaying the user name sent by the client application. The user name will appear to be missing. This is not an error. By default, the BasicHttpBinding binding does not send authentication information about users. All messages are sent as the anonymous user.
Click OK, and verify that the client application still runs correctly.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

In the next set of exercises, you will revisit the BasicHttpBinding binding and implement user authentication. Many of the authentication options available for this binding apply to other bindings as well.

Configure the BasicHttpBinding binding for the WCF service to use Basic authentication

Edit the App.config file in the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the left pane, expand the Bindings folder and click the ProductsServiceBasicHttpBindingConfig node.
In the right pane, click the Security tab.

Notice that the TransportClientCredentialType property is currently set to None, so the service is not expecting client applications to provide authentication information about users, and anyone who can connect to the service can send it messages and invoke operations.
Set the TransportClientCredentialType property to Basic.

When using Basic authentication, the client application must provide a username and password, which is transmitted to the service. The WCF runtime executing the service can use this information to authenticate the user running the client application, and if the user is valid, it will provide the identity of the user to the service.
Save the configuration, and close the WCF Service Configuration Editor.
Start the solution.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

The client fails with a MessageSecurityException exception, “The HTTP request is unauthorized with client authentication scheme ‘Anonymous’… .” The WCF runtime for the service was expecting the client application to provide a username and password, which it has not done.
Close the client console window, stop the service, and close the ProductsServiceHost form.

Modify the WCF client to supply the user credentials to the service

In Visual Studio 2005, edit the app.config file in the ProductsClient project by using the WCF Service Configuration Editor.
In the left pane, expand the Bindings folder and click the ProductsClientBasicHttpBindingConfig node.
In the right pane, click the Security tab.
Set the TransportClientCredentialType property to Basic.
Save the configuration, and close the WCF Service Configuration Editor.
Edit the Program.cs file in the ProductsClient project.

In the Main method, add the following statements shown in bold immediately after the code that creates the proxy object. Replace LON-DEV-01 with the name of your domain or computer (if you are not currently a member of a domain), replace Student with your username, and replace Pa$$w0rd with your password:

 ProductsServiceClient proxy = new     ProductsServiceClient("BasicHttpBinding_IProductsService"); proxy.ClientCredentials.UserName.UserName = "LON-DEV-01\\Student"; proxy.ClientCredentials.UserName.Password = "Pa$$w0rd";

The ClientCredentials property of a WCF proxy object provides a mechanism for a client application to provide the credentials to send to the service. The UserName property of ClientCredentials can hold a username and password. Other properties are available, such as ClientCertificate, which enable you to supply different types of credentials information as required by the service configuration.

Warning

This code is for illustrative purposes in this exercise only. In a production application, you should prompt the user for their name and password. You should never hard-code these details into an application.

Start the solution without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

A message box appears, displaying the user name sent by the client application. This time, the user name appears as expected, verifying that the operation is executing with the credentials of the user.
Click OK, and verify that the client application still runs correctly.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

Using Basic authentication, you can provide the username and password of the user, and the WCF runtime executing the service will check that these credentials are valid. If you provide an invalid username of password, the WCF runtime will reject the request and the client will receive another MessageSecurityException exception with the message “The HTTP request was forbidden… .”

Basic authentication is a good solution if the user running the client application is not currently logged into the security domain used by the service.

Note

You can also configure the NetTCPBinding and WSHttpBinding bindings at the message level to require Username authentication. This is very similar to Basic authentication at the transport level as far as client application is concerned, although somewhat different as far as the service is concerned, as it takes responsibility for authenticating the user itself (typically using a custom database of usernames and passwords). However, usernames and passwords are not encrypted at the message level, so WCF insists that the underlying transport provide encryption to prevent the credential details being transmitted across an open network as clear text.

If the user is logged in to the domain, then you can make use of Windows Integrated Security to provide the user’s credentials automatically, rather than prompting the user for them again (or worse still, hard-coding them in your application!).

Configure the BasicHttpBinding binding for the WCF service and client to use Windows authentication

Edit the App.config file in the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the left pane, expand the Bindings folder, and click the ProductsServiceBasicHttpBindingConfig node.
In the right pane, click the Security tab.
Set the TransportClientCredentialType property to Windows.
Save the configuration and close the WCF Service Configuration Editor.
In Visual Studio 2005, edit the app.config file in the ProductsClient project by using the WCF Service Configuration Editor.
Repeat the process in steps 2 through 5, above and set the TransportClientCredentialType property of the ProductsClientBasicHttpBindingConfig binding configuration to Windows.
Save the configuration, and close the WCF Service Configuration Editor.
Edit the Program.cs file in the ProductsClient project.
In the Main method, comment out the two statements that add the username and password to the ClientCredentials property of the proxy object.
Start the solution without debugging.

In the ProductsServiceHost form, click Start. In the client console window, press Enter.

The message box appears displaying your Windows username, which was sent by the client application. However, rather than you having to supply the username and password, the WCF runtime executing the client application picked this information up from the user’s process automatically.

Note

If you omitted to comment out the lines that populated the ClientCredentials object, the solution still works; the credentials provided are simply ignored. However, note the ClientCredentials property has a Windows property that you can use to provide a domain, username, and password to the service if you want the service to run as a different Windows user. Any values that you specify in the Windows property override those retrieved from the user’s login process. The usual warnings about hard-coding usernames and password in your code still apply:

 proxy.ClientCredentials.Windows.ClientCredential.Domain = "LON-DEV-01"; proxy.ClientCredentials.Windows.ClientCredential.UserName = "Administrator"; proxy.ClientCredentials.Windows.ClientCredential.Password = "P@ssw0rd";

Click OK in the message box, and verify that the client application still runs correctly.
Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

When you use Windows Integrated Security, usernames and passwords are not transmitted as clear text. You can use Windows Integrated Security at the message level with the NetTCPBinding and WSHttpBinding bindings without needing to implement encryption at the transport level.

Examine the authentication mechanism used by the NetTcpBinding binding

Edit the App.config file in the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the left pane, expand the Bindings folder, and click the ProductsServiceBasicTcpBindingConfig node.
In the right pane, click the Security tab.
Verify that the MessageClientCredentialType property is set to Windows.

You have been using Windows Integrated Security without realizing it in earlier exercises!

Note
The WSHttpBinding binding also defaults to using Windows Integrated Security.
Close the WCF Service Configuration Editor without saving changes.
Edit the Program.cs file for the ProductsClient project and modify the statement that creates the proxy object to use the NetTcpBinding binding, as follows:
```
 ProductsServiceClient proxy = new     ProductsServiceClient("NetTcpBinding_IProductsService");
```
Start the solution without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

The familiar message box appears, displaying your Windows user name, proving that the NetTcpBinding automatically picks up your identity from Windows.
Click OK, and allow the client application to finish. Press Enter to close the client console window. Stop the service and close the ProductsServiceHost form.

Authorizing Users

After a service has established the identity of the user, it can then determine whether the service should perform the requested operations for the user. Different operations in a service could be considered more privileged than others. For example, in the ProductsService service, you might wish to let any staff who work in the warehouse query the product information in the AdventureWorks database but limit access to operations such as ChangeStockLevel, which modify data, to staff members who are stock controllers. WCF can use the features of the .NET Framework to enable a developer to specify which users and roles have the authority to request operations. You can perform this task declaratively (by using attributes) or imperatively (by adding code to the operations).

The authorization mechanism used by WCF requires access to a database defining users and the roles that they can fulfill. If you are performing authentication by using Active Directory, it makes sense to use the Active Directory database to hold the roles for each user as well. Therefore, the first step is to ensure that the WCF service is configured to retrieve roles from Active Directory by using the Windows Token Role Provider.

Configure the WCF service to use the Windows Token Role Provider

Edit the App.config file in the ProductsServiceHost project by using the WCF Service Configuration Editor.
In the left pane, expand the Advanced folder, expand the Service Behaviors folder and then click the ProductsBehavior node.

The ProductsBehavior behavior currently contains the serviceDebug element. You added this behavior to the service in Chapter 3.
In the right pane, click Add.
In the Adding Behavior Element Extension Sections dialog box, select serviceAuthorization and then click Add.

The serviceAuthorization behavior is added to the list of behaviors.
In the left pane, click serviceAuthorization under the ProductsBehavior node.
In the right pane, verify that the PrincipalPermissionMode property is set to UseWindowsGroups.

By default, WCF uses the Windows Token Role Provider to authenticate users, so you don’t actually need to change anything. However, you can configure the serviceBehavior element to specify a different role provider, such as the SQL Role Provider or the Authorization Store Role Provider mentioned earlier in this chapter. (You will configure the service to use the SQL Role Provider in Chapter 5.)
Save the configuration and close the WCF Service Configuration Editor.

The next step is to define the roles that can request the operations in the WCF service. When using the Windows Token Role Provider, Active Directory groups correspond to roles, so you define groups in the Active Directory database and add users to these groups.

Note

The following exercise assumes you do not have access to the Active Directory database for your organization, so it uses the Windows local users and groups database instead. The principles are the same, however.

Create groups for warehouse staff and stock controller staff

On the Windows Start menu, right-click My Computer, and then click Manage.

The Computer Management console appears.
In the Computer Management console, under the System Tools node, expand the Local Users and Groups node, right-click the Groups folder, and then click New Group.
In the New Group dialog box, enter WarehouseStaff for the Group name, and then click Create.
Still in the New Group dialog box, enter StockControllers for the Group name, and then click Create.
Click Close to close the New Group dialog box.

The two new groups should appear in the list of groups in right pane of the Computer Management console.
In the left pane of the Computer Management console, right-click the Users folder and then click New User.
In the New User dialog box, use the values in the following table to set the properties of the user and then click Create.

Open table as spreadsheet

Property

Value

User

name Fred

Password

Pa$$w0rd

Confirm password

Pa$$w0rd

User must change password at next logon

Unchecked
Add another user by specifying the values in the following table, and then click Create again.

Open table as spreadsheet

Property

Value

User name

Bert

Password

Pa$$w0rd

Confirm password

Pa$$w0rd

User must change password at next logon

Unchecked
Click Close the close the New User dialog box.
In the left pane of the Computer Management console, click the Users folder.

The two new users should appear in the list in the right pane of the Computer Management console.
In the right pane of the Computer Management console, right-click Bert and then click Properties.
In the Bert Properties dialog box, click the Member Of tab and then click Add.
In the Select Groups dialog box, type WarehouseStaff in the text box and then click OK.

Bert is added to the WarehouseStaff group.
In the Bert Properties dialog box, click OK.
In the right pane of the Computer Management console, right-click Fred and then click Properties.
In the Fred Properties dialog box, click the Member Of tab and then click Add.
In the Select Groups dialog box, type WarehouseStaff in the text box and then click OK.
Click Add again. In the Select Groups dialog box, type StockControllers in the text box and then click OK.

Fred is added to the WarehouseStaff and StockControllers groups–he has two roles.
In the Fred Properties dialog box, click OK.
Close the Computer Management console.

Property	Value
User	name Fred
Password	Pa$$w0rd
Confirm password	Pa$$w0rd
User must change password at next logon	Unchecked

Property	Value
User name	Bert
Password	Pa$$w0rd
Confirm password	Pa$$w0rd
User must change password at next logon	Unchecked

You can now use the groups you have just defined to specify the roles that can request each of the operations in the ProductsService service. To show how to specify authorization declaratively and imperatively, you will use attributes to specify the role for the operations that simply query the AdventureWorks database, but you will write code to specify the role that can modify the database.

Specify the roles for the WCF service operations

In Visual Studio 2005, open the ProductsService.cs file in the ProductsService project.

Add the following using statements to the list at the top of the file:

 using System.Security; using System.Security.Permissions; using System.Security.Principal;

Locate the ListProducts method in the ProductsServiceImpl class. Add the following attribute, shown in bold, to this method:
```
 [PrincipalPermission(SecurityAction.Demand, Role="WarehouseStaff")] public List<string> ListProducts() {     … }
```
The PrincipalPermission attribute specifies the authorization requirements of the method. In this case, the SecurityAction.Demand parameter indicates that the method requires that the user meet the criteria specified by the following parameters. The Role parameter indicates that the user must be a member of the WarehouseStaff role.

You can identify specific users by using the optional Name parameter. However, if you specify Name and Role, then the user must match both criteria to be granted access (if the user is not a member of the specified role, they will not be allowed to execute the method). If you require users to be granted access to the method if they have a specific name or are a member of a specific group, you can use the PrincipalPermission attribute twice, like this:
```
 [PrincipalPermission(SecurityAction.Demand, Role="WarehouseStaff")] // LON-DEV-01\Student is not a member of the WarehouseStaff group [PrincipalPermission(SecurityAction.Demand, Name="LON-DEV-01\\Student")] public List<string> ListProducts() {     … }
```
You can also specify SecurityAction.Deny as the first parameter to the PrincipalPermission attribute. If you do this, the specified users and roles will be explicitly denied access to the method.

Apply the PrincipalPermission attribute with the WarehouseStaff group to the GetProduct and CurrentStockLevel methods, as shown in bold below:

 [PrincipalPermission(SecurityAction.Demand, Role="WarehouseStaff")] public Product GetProduct(string ProductNumber) {     … } [PrincipalPermission(SecurityAction.Demand, Role="WarehouseStaff")] public int GetStockLevel(string ProductNumber) {     … }

Locate the ChangeStockLevel method. Add the following code, shown in bold, to the start of this method:
```
 public bool ChangeStockLevel(…) {     // Determine whether the user is a member of the StockControllers role     WindowsPrincipal user = new WindowsPrincipal(             (WindowsIdentity)Thread.CurrentPrincipal.Identity);     if (!(user.IsInRole("StockControllers")))     {         // If the user is not in the StockControllers role,         // throw a SecurityException         throw new SecurityException("Access denied");     }     … }
```
The first statement retrieves the identity information for the user and uses it to create a WindowsPrincipal object. Note that the identity returned by the current thread must be cast to a WindowsIdentity object. A WindowsPrincipal object is a representation of the user. It exposes the IsInRole method that this code uses to determine whether the user is a member of the StockControllers role. The IsInRole method returns true if the user is a member of the role, false otherwise. If the user is not a member of the role, the code throws a SecurityException exception with the message “Access Denied.”

Warning

It is tempting to provide more detail in the SecurityException exception. This practice is not recommended, as it could provide an attacker with useful information that they might be able to use to try and infiltrate your system. Keep the exception message bland!

Test the authorization for the WCF service

Start the solution without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

Assuming you are not currently logged in to Windows as Fred or Bert, the client application stops and reports the message “Access is denied” when attempting to invoke the ListProducts operation. This is because the authenticated Windows account for the client application must be a member of the WarehouseStaff role:
Press Enter to close the client console window, and then stop the service and close the ProductsServiceHost form.
In the ProductsClient project in Solution Explorer, open the Program.cs file.
In the Main method, add the following statements shown in bold immediately after the statement that creates the proxy object. Replace the value “LON-DEV-01” specified in the Domain property with the name of your computer:
```
 ProductsServiceClient proxy = new     ProductsServiceClient("NetTcpBinding_IProductsService"); proxy.ClientCredentials.Windows.ClientCredential.Domain = "LON-DEV-01"; proxy.ClientCredentials.Windows.ClientCredential.UserName = "Bert"; proxy.ClientCredentials.Windows.ClientCredential.Password = "Pa$$w0rd"; 
```
These statements explicitly set the Windows credentials for the user to those of Bert. The WCF runtime on the client will send these credentials to the service, rather than using those in the user’s login process.
Start the solution again, without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

This time, Bert is a member of the WarehouseStaff role and is granted access to the ListProducts, GetProduct, and CurrentStockLevel operations.
When the ListProducts method runs, it displays the message box confirming that the identity of the authenticated user is Bert. Click OK to continue execution. The first three tests run successfully, but when the client application attempts to perform test 4, which requires invoking the ChangeStockLevel operation, Bert has not been granted access to this method, and so the test fails with the “Access is denied” message:
Press Enter to close the client console window, and then stop the service and close the ProductsServiceHost form.
Return to the Program.cs file in the code view window.

In the Main method, change the Windows username of the user to Fred, like this:

 proxy.ClientCredentials.Windows.ClientCredential.Domain = "LON-DEV-01"; proxy.ClientCredentials.Windows.ClientCredential.UserName = "Fred"; proxy.ClientCredentials.Windows.ClientCredential.Password = "Pa$$w0rd";

Build and start the solution again without debugging.
In the ProductsServiceHost form, click Start. In the client console window, press Enter.

Fred is a member of the WarehouseStaff role and the StockControllers role, and so he is able to invoke all the operations in the ProductsService service.
When the ListProducts method displays the message box with the name of the authenticated user, verify that the username is Fred and then click OK.
The client application performs all four tests successfully. Press Enter to close the client console window, and then stop the service and close the ProductsServiceHost form.

Using Impersonation to Access Resources

Authenticating a user establishes the identity of the user to the WCF service, which can then perform authorization checks to verify that the user should be allowed to perform the requested operation. The method that implements the operation might require access to resources on the computer running the WCF service. By default, the service will attempt to gain access to these resources by using its own credentials. For example, when a method in the ProductsService service connects to the AdventureWorks database, it does so as the account running the service. When using Windows authentication, it is possible to specify that the WCF service should access resources by using the authenticated identity of the user instead. So, if Fred has been granted access to the AdventureWorks database, the WCF service can connect to SQL Server as Fred and will have access to all the database resources to which Fred has been granted access. If the user connects as Bert, the WCF service might be able to use a different set of resources in the database, depending on Bert’s access rights. The same principle applies to other resources, such as files, folders, and network shares. Using impersonation gives an administrator fine-grained control over the ability of a WCF service to read or write possibly sensitive information and can provide an additional degree of security–just because the user can connect to the WCF service, they might not be able to perform operations that retrieve or modify confidential data unless the administrator has explicitly granted the user access to this data.

You can enable impersonation for an operation by setting the Impersonation property of the OperationBehavior attribute, like this (shown in bold):

 [PrincipalPermission(SecurityAction.Demand, Role="WarehouseStaff")] [OperationBehavior(Impersonation=ImpersonationLevel.Required)] public List<string> ListProducts {   … }

Specifying the value ImpersonationLevel.Required enforces impersonation. The client application must also agree to this requirement and specify the level of impersonation that the WCF service application can use (you will see how to do this shortly). You can also specify the ImpersonationLevel.Allowed, which enables the WCF service to impersonate the user if the client application permits, but executes as the identity running the service application if not, and ImpersonationLevel.NotAllowed, which disables impersonation.

If you need to specify an impersonation level setting for all operations, you can set the ImpersonateCallerForAllOperations attribute of the <serviceBehavior> element of the service behavior to true in the service configuration file, as shown in bold below:

 <?xml version="1.0" encoding="utf-8" ?> <configuration>   …   <system.serviceModel>     …     <services>       <service behaviorConfiguration="ProductsBehavior" name="Products.ProductsServiceImpl">         …     </services>     <behaviors>       <serviceBehaviors>         <behavior name="ProductsBehavior">           <serviceAuthorization principalPermissionMode="UseWindowsGroups"             impersonateCallerForAllOperations="false" />         </behavior>       </serviceBehaviors>     </behaviors>   </system.serviceModel> </configuration>

You configure the client application to indicate the level of impersonation that the service can use by defining a behavior for the endpoint and specifying the AllowedImpersonationLevel property. The following fragments of a client configuration file highlight the pertinent elements:

 <?xml version="1.0" encoding="utf-8" ?> <configuration>   <system.serviceModel>     <behaviors>       <endpointBehaviors>         <behavior name="ImpersonationBehavior">           <clientCredentials>             <windows allowedImpersonationLevel="Impersonation" />             …           </clientCredentials>         </behavior>       </endpointBehaviors>     </behaviors>     …     <client>       …       <endpoint          address="http://localhost:8010/ProductsService/ProductsService.svc"         behaviorConfiguration="ImpersonationBehavior"         binding="wsHttpBinding"         contract="ProductsClient.ProductsService.IProductsService"         name="WSHttpBinding_IProductsService" />     </client>   </system.serviceModel> </configuration>

You can specify one of the following values for the AllowedImpersonationLevel property:

Impersonate. The service can use the user’s identity when accessing local resources on the computer hosting the service. However, the service cannot access resources on remote computers.
Delegation. The service can use the user’s identity when accessing local resources on the computer hosting the service and on remote computers. The service can pass the identity of the user on to remote services, which may authenticate the user and perform operations impersonating this user.
Identify. The service can use the user’s credentials to authenticate the user and authorize access to operations but cannot impersonate the user.
Anonymous. The service does not use the user’s identity to authenticate the user but can use the user’s credentials to perform access checks against resources accessed by the service. This setting is only valid for transport mechanisms such as named pipes that connect a client application to a service executing on the same computer. If the service is running on a remote computer, the setting is handled in the same way as the “Identify” option.
None. The service does not attempt to impersonate the user.