The security mode setting determines two fundamental security aspects for any service: the security model for message protection and the supported client authentication schema.

Each security mode has its own mechanism for passing the authentication credentials to the service, and therefore some authentication options might not be available according to the selected security model.

For example, federated authentication is supported only with message authentication. If you need to support that security schema, message security is the only option you have.

This setting is available in the configuration model through the Mode property in the security element.

The following examples show how to configure the security mode for a WsHttpBinding using the WCF configuration section, and the equivalent version using the code model:

<wsHttpBinding>
  <binding name="helloWorld">
    <security mode="TransportWithMessageCredential"></security>

</binding>
</wsHttpBinding>

WSHttpBinding binding = new WSHttpBinding();
binding.Security.Mode = SecurityMode.TransportWithMessageCredential;

The possible options for this setting are listed in Table 7-2.

By default, WCF encrypts and signs all the messages on wire to provide data confidentiality and integrity. In some circumstances, if the message you are sending through the transport does not contain any sensitive information, you might want to turn off encryption and sign the message to preserve the integrity of the data — without concern about confidentially. For those scenarios, WCF provides the flexibility of changing the default protection level when Message Security mode is used.

The protection level can be configured either at service level in the contract definition or at operation level for a more granular control. When the protection level is defined at both levels, the protection level in operation overrides the existing definition on the service level.

Message contracts also support a way to override the protection level for the operation. The [ProtectionLevel] attribute can be specified in the message contract itself or any specific message header or body.

The supported values for the ProtectionLevel setting are None, Sign, and EncryptAndSign.

None disables the message protection. Sign only provides message integrity against any possible change in the original message, and the last one, EncryptAndSign, provides message confidentiality and integrity.

The protection level is only configurable through attributes in the service definition, and it is not available in the binding configuration settings. The following examples illustrate how this setting can change different levels (an operation or a message contract) in the service definition:

[MessageContract(ProtectionLevel = ProtectionLevel.None)]
public class HelloWorldRequestMessage
{
  [MessageHeader]
  public string SampleHeader { get; set; }

  [MessageBodyMember()]
  public string Message { get; set; }
}

[MessageContract]
public class HelloWorldResponseMessage
{
  public string ResponseMessage { get; set; }
}

[ServiceContract(ProtectionLevel = ProtectionLevel.EncryptAndSign)]
public interface IHelloWorld
{
  [OperationContract(ProtectionLevel = ProtectionLevel.Sign)]
  HelloWorldResponseMessage Hello(HelloWorldRequestMessage request);
}

The final result, shown in the previous example, is that the request message will not be protected, and the response message will use the protection level defined for the operation, which is sign only.

The algorithmSuite setting is something specific to message security and determines the set of algorithms that will be used for message integrity and confidentiality. For practical purposes, you should understand that this setting basically affects the way in which WCF generates the final keys for digitally signing and encrypting the messages. The algorithm suite typically represents a pair of algorithms, an asymmetric algorithm for deriving a symmetric key, and a symmetric algorithm for encrypting and signing the messages.

Performing cryptographic operations such as digitally signing or encrypting information with asymmetric keys is very expensive in terms of computer resources such as CPU or memory. For that reason, WCF first generates and derives a symmetric key by using the asymmetric algorithm, and then uses that symmetric key to effectively perform the cryptographic operations.

The client and the service must agree on the selected algorithm suite to interoperate well. This is a very important aspect because some platforms or web services stacks only support specific algorithm suites. As long as interoperability is not a concern for you, you should consider leaving the default value for this setting:

<netTcpBinding>
  <binding name="helloWorld">
    <security mode="Message">
      <message algorithmSuite="Basic256"/>
    </security>
  </binding>
</netTcpBinding>

The previous configuration segment shows how that setting can be changed in a NetTcpBinding configured with message security.

The client credential type is a very important setting that determines the authentication schema used by your service. It represents the type of credentials expected for authenticating the client or consumer application.

Something that you should know first is that the supported options for this setting will vary according to the selected security mode and transport. Although the available options for message security in the most common bindings are pretty much the same — None, Windows, Username, Certificate, and IssueToken — the options for transport security are limited by the supported authentication schemas in the transport layer itself.

Tables 7-3 and 7-4 illustrate the available options for message security and transport security with a brief description about each one.

There are some exceptions to the previous table for the NetMsqmBinding and the NetNamedPipeBinding.

The first binding replaces the clientCredentialType setting with an equivalent one, msmqAuthenticationMode, which supports WindowsDomain for Windows authentication and Certificate for authentication based on certificates.

The NetNamedPipeBinding only supports transport security with Windows authentication.

This setting is available in the configuration model through two elements, Message and Transport. WCF picks one of these at runtime according to the configured security mode:

<wsHttpBinding>
  <binding name="helloWorld">
    <security mode="Transport">
      <transport clientCredentialType="Windows"/>
      <message clientCredentialType="Windows"/>
    </security>
  </binding>
</wsHttpBinding>

In this example, WCF uses the client credential type definition in the transport element because the security mode has been set to Transport. The message element can still exist in the configuration, but it is ignored by WCF.

Configuring this setting by code can be done in the same way seen with the configuration section:

WSHttpBinding binding = new WSHttpBinding();
binding.Security.Mode = SecurityMode.Transport;
binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows;
binding.Security.Message.ClientCredentialType = MessageCredentialType.Windows;

Services in WCF must provide credentials to clients to support mutual authentication and message protection. In other words, the client uses the service credentials for authenticating it before sending a message, and also provides message protection aspects such as data confidentiality and integrity.

In most cases the credentials are automatically negotiated between the client and the service. The SSL handshake in transport security is a good example of this. This handshake allows the server to authenticate itself to the client by proving an X509 public key, and then allows the client and the server to cooperate in the creation of symmetric keys used for message protection during the secure session that follows.

For some message security authentication schemas, WCF gives the flexibility to change this behavior with a specific setting negotiateServiceCredentials. By default, WCF automatically negotiates the credentials at message level using protocols such as TLSNego when the client credentials are set to None, Username, or Certificate, or SPNego only when they are set to Windows. This mechanism to negotiate the credentials is something specific to WCF, so you should disable it to interoperate well with other service stacks or platforms. That can be accomplished as shown next:

<wsHttpBinding>
  <binding name="helloWorld">
    <security mode="Message">
      <message clientCredentialType="Certificate"
               negotiateServiceCredential="false" />
    </security>
  </binding>
</wsHttpBinding>

When this setting is disabled, in case of certificate credentials, the service certificate must be provided to all the clients prior to establishing a communication with the service, and the clients should refer to the service certificate in their configuration:

<clientCredentials>
  <serviceCertificate>
    <defaultCertificate findValue="WCFService"
       storeLocation="LocalMachine" storeName="My"
       x509FindType="FindBySubjectName"/>
  </serviceCertificate>
</clientCredentials>

The service authentication is performed by WCF at the moment of establishing the communication by comparing the provided credentials with the configured identity element in the service endpoint. If that element is not configured, WCF will try to assume default values prior to making the comparison. For example, in case you are using certificate credentials, WCF will check whether the subject name in the certificate matches the Internet name of the server.

In most cases, you have to define the service endpoint identity explicitly. That can be done by adding an identity element to the endpoint configuration:

<endpoint name="sampleProxy"
    address="http://localhost:8000/helloWorld/"
    bindingConfiguration="sampleBinding"
    behaviorConfiguration="sampleBehavior"
    binding="wsHttpBinding"
    contract="WCFBook.Samples.IHelloWorld">
    <identity>
      <dns value="WCFService"/>
    </identity>
</endpoint>

The equivalent version using the object model would be the following:

ServiceEndpoint ep = myServiceHost.AddServiceEndpoint(
typeof(WCFBook.Samples.IHelloWorld),
new WSHttpBinding(),
String.Empty);

EndpointAddress myEndpointAdd = new EndpointAddress(
new Uri("http://localhost:8000/helloWorld"),
EndpointIdentity.CreateDnsIdentity("WCFService"));

ep.Address = myEndpointAdd;

In the previous example, the service should provide a certificate with a subject name equal to WCFService to be successfully authenticated by WCF.

WCF supports five types of identities for a service. Their uses depend on the scenario you want to implement and the security requirements that the services demand. All the possible values for the identity types are discussed in Table 7-5.

Secure sessions represent the last aspect that we discuss here before jumping into more concrete examples in the next chapter.

Secure sessions or secure conversations provide a way to improve the service response time when a client application needs to interchange more than one message with the service.

When this feature is enabled, the credential negotiation and authentication happen once during the first message interchange between the client and the service. Otherwise, these two steps are performed for every service call.

You should not confuse this type of session with typical Http-based sessions. WCF secure sessions are initiated by the clients and are there to support some kind of shared context between the client and the service.

This feature represents a specific implementation of the WS-SecureConversation and WS-Trust specifications in WCF, and therefore demands the use of message security.

In the way secure conversation works under the hood, the client first sends a special message RequestSecurityToken (with SOAP action http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue) to the service for a session token. This message is part of the WS-Trust specification and contains a reference to the client credentials that will be used to create the session token:

<s:Envelope xmlns:s="..." xmlns:a="...">
  <s:Header>
    <a:Action s:mustUnderstand="1">
      http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue
    </a:Action>
    <a:MessageID>urn:uuid:d55bd2a7-bae8-4751-a010-07e95fd82ee2</a:MessageID>
    <a:ReplyTo>
      <a:Address>http://www.w3.org/2005/08/addressing/anonymous</a:Address>
    </a:ReplyTo>
    <a:To s:mustUnderstand="1">http://localhost/HelloWorld</a:To>
  </s:Header>
  <s:Body>
    <t:RequestSecurityToken Context="uuid-f422503c-7974-42ab-9b8a-c330727290e9-1"
                          xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust">
     <t:TokenType>http://schemas.xmlsoap.org/ws/2005/02/sc/sct</t:TokenType>
     <t:RequestType>
       http://schemas.xmlsoap.org/ws/2005/02/trust/Issue
     </t:RequestType>
     <t:KeySize>256</t:KeySize>
     <t:BinaryExchange
       ValueType="http://schemas.xmlsoap.org/ws/2005/02/trust/spnego"
       EncodingType="http://docs.oasis-open.org/wss/2004/01/
         oasis-200401-wss-soap-message-security-1.0#Base64Binary">
     </t:BinaryExchange>
    </t:RequestSecurityToken>
  </s:Body>
</s:Envelope>

After the service receives the message and authenticates the client credentials, it creates a new session token called Secure Context Token (SCT) which references the client credentials and a symmetric key to perform cryptographic operations such as encrypt or sign messages (message confidentiality and integrity).

The service sends the session token back to the client using a RequestSecurityTokenResponse message (with SOAP action http://schemas.xmlsoap.org/ws/2005/02/trust/RSTR/Issue), and keeps track of the original credentials using different strategies such as encrypted Http cookies or in-memory caches:

<s:Envelope xmlns:s="..." xmlns:a="...">
  <s:Header>
    <a:Action s:mustUnderstand="1">
      http://schemas.xmlsoap.org/ws/2005/02/trust/RSTR/Issue
    </a:action>
    <a:RelatesTo>urn:uuid:d55bd2a7-bae8-4751-a010-07e95fd82ee2</a:RelatesTo>
  </s:Header>
  <s:Body>
  <t:RequestSecurityTokenResponse
     Context="uuid-f422503c-7974-42ab-9b8a-c330727290e9-1"
     xmlns:t="http://schemas.xmlsoap.org/ws/2005/02/trust"
     xmlns:u="http://docs.oasis-open.org/wss/2004/01/
       oasis-200401-wss-wssecurity-utility-1.0.xsd">
     <t:BinaryExchange
       ValueType="http://schemas.xmlsoap.org/ws/2005/02/trust/spnego"
       EncodingType="http://docs.oasis-open.org/wss/2004/01/
         oasis-200401-wss-soap-message-security-1.0#Base64Binary">
      </t:BinaryExchange>
    </t:RequestSecurityTokenResponse>
  </s:Body>
</s:Envelope>

In that way, the client can later protect messages with the symmetric key included in the session token or use the session token itself as a client credential.

The most important benefits of using a SCT to protect communication between the client and service are as follows:

From the perspective of the client application, secure conversation is something completely transparent that WCF keeps at channel level. For that reason, the session token is reused as long as the client application uses the same instance of the client channel.

When the client channel is closed in a normal fashion, a message is sent to the service to shut down the session and release all the associated resources. If the channel closes abruptly, the session will eventually be shut down on the service side after a fixed period of inactivity.

This feature is enabled by default for all the bindings that support message security (WS-Security). The custom binding also offers the possibility of enabling Secure Conversation by setting the value SecureConversation to the authenticationMode attribute. In addition, you can configure a binding that will be initially used to negotiate the session token by means of the element secureConversationBootstrap.

The following configuration shows how secure conversation can be enabled for a wsHttpBinding, and the equivalent version with a custom binding:

<bindings>
  <wsHttpBinding>
    <binding name="ServiceBinding">
      <security mode="Message">
        <message clientCredentialType="Certificate"
           establishSecurityContext="true"/>
      </security>
    </binding>
  </wsHttpBinding>

  <customBinding>
    <binding name="ServiceBinding">

      <security authenticationMode="SecureConversation"
            requireSecurityContextCancellation ="false">
        <secureConversationBootstrap authenticationMode="MutualCertificate">
        </secureConversationBootstrap>
      </security>
      <httpTransport/>
    </binding>
  </customBinding>
</bindings>

The attribute requireSecurityContextCancellation in the previous configuration specifies whether the client application must send a shutdown message to the service after closing the client channel. When this attribute is set to false, WCF uses an encrypted cookie to keep the state of the session token instead of keeping it in memory on the service side. As the cookies travel in every message to the service, they are ideal for web farm scenarios where intermediary servers or load balancers are used, and there is no guarantee that all the messages are handled by the same server.

You cannot reuse the client channel for sending more than one message to the same service because the benefits of using secure conversation get lost. The extra overhead associated with the initial handshake will affect your service performance, and you should consider disabling this feature when that happens.