Edit

Message Security Sample

  • Article

The MessageSecurity sample demonstrates how to implement an application that uses the basicHttpBinding and message security. This sample is based on the Getting Started that implements a calculator service.

Note

The setup procedure and build instructions for this sample are located at the end of this topic.

The security mode of basicHttpBinding can be set to the following values: Message, Transport, TransportWithMessageCredential, TransportCredentialOnly and None. In the following sample service App.config file, the endpoint definition specifies the basicHttpBinding and references a binding configuration named Binding1, as shown in the following sample configuration:

<system.serviceModel>
  <services>
    <service name="Microsoft.ServiceModel.Samples.CalculatorService"
             behaviorConfiguration="CalculatorServiceBehavior">
     <!-- This endpoint is exposed at the base address provided by -->
     <!-- host: http://localhost:8000/ServiceModelSamples/service.-->
     <endpoint address=""
               binding="basicHttpBinding"
               bindingConfiguration="Binding1"
               contract="Microsoft.ServiceModel.Samples.ICalculator" />
    </service>
  </services>
  ...
</system.serviceModel>

The binding configuration sets the mode attribute of the <security> to Message and sets the clientCredentialType attribute of the <message> to Certificate as shown in the following sample configuration:

<bindings>
  <basicHttpBinding>
    <!--
        This configuration defines the SecurityMode as Message and
        the clientCredentialType as Certificate.
        -->
    <binding name="Binding1" >
      <security mode = "Message">
        <message clientCredentialType="Certificate"/>
      </security>
    </binding>
  </basicHttpBinding>
</bindings>

The certificate that the service uses to authenticate itself to the client is set in the behaviors section of the configuration file under the serviceCredentials element. The validation mode that applies to the certificate that the client uses to authenticate itself to the service is also set in the behaviors section under the clientCertificate element.

<!--For debugging purposes, set the includeExceptionDetailInFaults attribute to true.-->
<behaviors>
  <serviceBehaviors>
    <behavior name="CalculatorServiceBehavior">
      <serviceMetadata httpGetEnabled="True"/>
      <serviceDebug includeExceptionDetailInFaults="False" />
      <!--The serviceCredentials behavior allows one to define a -->
      <!--service certificate. A service certificate is used by a -->
      <!--client to authenticate the service and provide message -->
      <!-- protection. This configuration references the "localhost"-->
      <!--certificate installed during the setup instructions. -->
      <serviceCredentials>
        <serviceCertificate findValue="localhost"
               storeLocation="LocalMachine"
               storeName="My" x509FindType="FindBySubjectName" />
        <clientCertificate>
          <!-- Setting the certificateValidationMode to -->
          <!-- PeerOrChainTrust means that if the certificate -->
          <!--is in the user's Trusted People store, then it is -->
          <!-- trusted without performing a validation of the -->
          <!-- certificate's issuer chain. This setting is used -->
          <!-- here for convenience so that the sample can be run -->
          <!-- without having to have certificates issued by a -->
          <!-- certification authority (CA). -->
          <!-- This setting is less secure than the default, -->
          <!-- ChainTrust. The security implications of this -->
          <!-- setting should be carefully considered before using -->
          <!-- PeerOrChainTrust in production code. -->
          <authentication
                       certificateValidationMode="PeerOrChainTrust" />
        </clientCertificate>
      </serviceCredentials>
    </behavior>
  </serviceBehaviors>
</behaviors>

The same binding and security details are specified in the client configuration file.

The identity of the caller is displayed in the service console window by using the following code:

Console.WriteLine("Called by {0}", ServiceSecurityContext.Current.PrimaryIdentity.Name);

When you run the sample, the operation requests and responses are displayed in the client console window. Press ENTER in the client window to shut down the client.

Add(100,15.99) = 115.99
Subtract(145,76.54) = 68.46
Multiply(9,81.25) = 731.25
Divide(22,7) = 3.14285714285714
Press <ENTER> to terminate client.

To set up and build the sample

  1. Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

  2. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

To run the sample on the same machine

  1. Run Setup.bat from the sample install folder. This installs all the certificates required for running the sample.

    Note

    The Setup.bat batch file is designed to be run from a Windows SDK Command Prompt. It requires that the MSSDK environment variable point to the directory where the SDK is installed. This environment variable is automatically set within a Windows SDK Command Prompt.

  2. Run the service application from \service\bin.

  3. Run the client application from \client\bin. Client activity is displayed on the client console application.

  4. If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

  5. Remove the certificates by running Cleanup.bat when you have finished with the sample. Other security samples use the same certificates.

To run the sample across machines

  1. Create a directory on the service machine for the service binaries.

  2. Copy the service program files to the service directory on the server. Also copy the Setup.bat, Cleanup.bat, and ImportClientCert.bat files to the server.

  3. Create a directory on the client machine for the client binaries.

  4. Copy the client program files to the client directory on the client machine. Also copy the Setup.bat, Cleanup.bat, and ImportServiceCert.bat files to the client.

  5. On the server, run setup.bat service. Running setup.bat with the service argument creates a service certificate with the fully-qualified domain name of the machine and exports the service certificate to a file named Service.cer.

  6. Edit Service.exe.config to reflect the new certificate name (in the findValue attribute in the <serviceCertificate> element) which is the same as the fully-qualified domain name of the machine. Also change the value of the base address to specify a fully-qualified machine name instead of localhost.

  7. Copy the Service.cer file from the service directory to the client directory on the client machine.

  8. On the client, run setup.bat client. Running setup.bat with the client argument creates a client certificate named client.com and exports the client certificate to a file named Client.cer.

  9. In the Client.exe.config file on the client machine, change the address value of the endpoint to match the new address of your service. You do this by replacing localhost with the fully-qualified domain name of the server. Also change the findValue attribute of the <defaultCertificate> to the new service certificate name which is the fully-qualified domain name of the server.

  10. Copy the Client.cer file from the client directory to the service directory on the server.

  11. On the client, run ImportServiceCert.bat. This imports the service certificate from the Service.cer file into the CurrentUser - TrustedPeople store.

  12. On the server, run ImportClientCert.bat, This imports the client certificate from the Client.cer file into the LocalMachine - TrustedPeople store.

  13. On the service machine, run Service.exe from a command prompt.

  14. On the client machine, launch Client.exe from a command prompt window.

    1. If the client and service are not able to communicate, see Troubleshooting Tips for WCF Samples.

To clean up after the sample

  • Run Cleanup.bat in the samples folder once you have finished running the sample.

    Note

    This script does not remove service certificates on a client when running this sample across machines. If you have run Windows Communication Foundation (WCF) samples that use certificates across machines, be sure to clear the service certificates that have been installed in the CurrentUser - TrustedPeople store. To do this, use the following command: certmgr -del -r CurrentUser -s TrustedPeople -c -n <Fully Qualified Server Machine Name> For example: certmgr -del -r CurrentUser -s TrustedPeople -c -n server1.contoso.com