How to: Set the Security Mode

Article
09/15/2021

Windows Communication Foundation (WCF) security has three common security modes that are found on most predefined bindings: transport, message, and "transport with message credential." Two additional modes are specific to two bindings: the "transport-credential only" mode found on the BasicHttpBinding, and the "Both" mode, found on the NetMsmqBinding. However, this topic concentrates on the three common security modes: Transport, Message, and TransportWithMessageCredential.

Note that not every predefined binding supports all of these modes. This topic sets the mode with the WSHttpBinding and NetTcpBinding classes and demonstrates how to set the mode both programmatically and through configuration.

For more information, see WCF security, see Security Overview, Securing Services, and Securing Services and Clients. For more information about transport mode and message, see Transport Security and Message Security.

To set the security mode in code

Create an instance of the binding class that you are using. For a list of predefined bindings, see System-Provided Bindings. This example creates an instance of the WSHttpBinding class.

Set the Mode property of the object returned by the Security property.

WSHttpBinding b = new WSHttpBinding();
b.Security.Mode = SecurityMode.Transport;

Dim b As New WSHttpBinding()
b.Security.Mode = SecurityMode.Transport

Alternatively, set the mode to message, as shown in the following code.

WSHttpBinding b = new WSHttpBinding();
b.Security.Mode = SecurityMode.Message;

Dim b As New WSHttpBinding()
b.Security.Mode = SecurityMode.Message

Or set the mode to transport with message credentials, as shown in the following code.

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

Dim b As New WSHttpBinding()
b.Security.Mode = SecurityMode.TransportWithMessageCredential

You can also set the mode in the constructor of the binding, as shown in the following code.

WSHttpBinding b = new WSHttpBinding(SecurityMode.Message);

Dim b As New WSHttpBinding(SecurityMode.Message)

Setting the ClientCredentialType Property

Setting the mode to one of the three values determines how you set the ClientCredentialType property. For example, using the WSHttpBinding class, setting the mode to Transport means you must set the ClientCredentialType property of the HttpTransportSecurity class to an appropriate value.

To set the ClientCredentialType property for Transport mode

Create an instance of the binding.
Set the Mode property to Transport.

Set the ClientCredential property to an appropriate value. The following code sets the property to Windows.

WSHttpBinding b = new WSHttpBinding();
b.Security.Mode = SecurityMode.Transport;
b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows;

Dim b As New WSHttpBinding()
b.Security.Mode = SecurityMode.Transport
b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Windows

To set the ClientCredentialType property for Message mode

Create an instance of the binding.
Set the Mode property to Message.

Set the ClientCredential property to an appropriate value. The following code sets the property to Certificate.

WSHttpBinding b = new WSHttpBinding();
b.Security.Mode = SecurityMode.Message;
b.Security.Message.ClientCredentialType = MessageCredentialType.Certificate;

Dim b As New WSHttpBinding()
b.Security.Mode = SecurityMode.Message
b.Security.Message.ClientCredentialType = MessageCredentialType.Certificate

To set the Mode and ClientCredentialType property in configuration

Add an appropriate binding element to the <bindings> element of the configuration file. The following example adds a <wsHttpBinding> element.
Add a <binding> element and set its name attribute to an appropriate value.
Add a <security> element and set the mode attribute to Message, Transport, or TransportWithMessageCredential.
If the mode is set to Transport, add a <transport> element and set the clientCredential attribute to an appropriate value.

The following example sets the mode to "Transport", and then sets the clientCredentialType attribute of the <transport> element to "Windows".
```
<wsHttpBinding>
<binding name="TransportSecurity">
    <security mode="Transport" >
       <transport clientCredentialType = "Windows" />
    </security>
</binding>
</wsHttpBinding >
```
Alternatively, set the security mode to "Message", followed by a <"message"> element. This example sets the clientCredentialType to "Certificate".
```
<wsHttpBinding>
<binding name="MessageSecurity">
    <security mode="Message" >
       <message clientCredentialType = "Certificate" />
    </security>
</binding>
</wsHttpBinding >
```
Using the TransportWithMessageCredential value is a special case, and is explained below.

Using TransportWithMessageCredential

When setting the security mode to TransportWithMessageCredential, the transport determines the actual mechanism that provides the transport-level security. For example, the HTTP protocol uses Secure Sockets Layer (SSL) over HTTP (HTTPS). Therefore, setting the ClientCredentialType property of any transport security object (such as HttpTransportSecurity) is ignored. In other words, you can only set the ClientCredentialType of the message security object (for the WSHttpBinding binding, the NonDualMessageSecurityOverHttp object).

For more information, see How to: Use Transport Security and Message Credentials.