How to: Specify Client Credential Values

Using Windows Communication Foundation (WCF), the service can specify how a client is authenticated to the service. For example, a service can stipulate that the client be authenticated with a certificate.

1. Retrieve metadata from the service's metadata endpoint. The metadata typically consists of two files: the client code in the programming language of your choice (the default is Visual C#), and an XML configuration file. One way to retrieve metadata is to use the Svcutil.exe tool to return the client code and client configuration. For more information, see Retrieving Metadata and ServiceModel Metadata Utility Tool (Svcutil.exe).

2. Open the XML configuration file. If you use the Svcutil.exe tool, the default name of the file is Output.config.

3. Find the <security> element with the mode attribute (<security mode =MessageOrTransport> where MessageOrTransport is set to one of the security modes.

4. Find the child element that matches the mode value. For example, if the mode is set to Message, find the <message> element contained in the <security> element.

5. Note the value assigned to the clientCredentialType attribute. The actual value depends on which mode is used, transport or message.

The following XML code shows configuration for a client using message security and requiring a certificate to authenticate the client.

<security mode="Message">
    <transport clientCredentialType="Windows" proxyCredentialType="None"
        realm="" />
     <message clientCredentialType="Certificate" negotiateServiceCredential="true"
    algorithmSuite="Default" establishSecurityContext="true" />
</security>

This example sets the security mode to Transport mode and sets the client credential value to an X.509 certificate. The following procedures demonstrate how to set the client credential value on the client in code and configuration. This assumes that you have used the ServiceModel Metadata Utility Tool (Svcutil.exe) to return the metadata (code and configuration) from the service. For more information, see How to: Create a Client.

1. Use the ServiceModel Metadata Utility Tool (Svcutil.exe) to generate code and configuration from the service.

2. Create an instance of the WCF client using the generated code.

3. On the client class, set the ClientCredentials property of the ClientBase<TChannel> class to an appropriate value. This example sets the property to an X.509 certificate using the SetCertificate method of the X509CertificateInitiatorClientCredential class.

   C# Copy

   // Create a binding using Transport and a certificate.
   NetTcpBinding b = new NetTcpBinding();
   b.Security.Mode = SecurityMode.Transport;
   b.Security.Transport.ClientCredentialType =
       TcpClientCredentialType.Certificate;
   
   // Create an EndPointAddress.
   EndpointAddress ea = new EndpointAddress(
       "net.tcp://localHost:8036/Calculator/MyCalculator");
   
   // Create the client.
   CalculatorClient cc = new CalculatorClient(b, ea);
   
   // Set the certificate for the client.
   cc.ClientCredentials.ClientCertificate.SetCertificate(
       StoreLocation.LocalMachine,
       StoreName.My,
       X509FindType.FindBySubjectName,
       "cohowinery.com");
   try
   {
       cc.Open();
       // Begin using the client.
       Console.WriteLine(cc.Divide(1001, 2));
       cc.Close();
   }
   catch (AddressAccessDeniedException adExc)
   {
       Console.WriteLine(adExc.Message);
       Console.ReadLine();
   }
   catch (System.Exception exc)
   {
       Console.WriteLine(exc.Message);
       Console.ReadLine();
   }
   

   You can use any of the enumerations of the X509FindType class. The subject name is used here in case the certificate is changed (due to an expiration date). Using the subject name enables the infrastructure to find the certificate again.

1. Add a <behavior> element to the <behaviors> element.

2. Add a <clientCredentials> element to the <behaviors> element. Be sure to set the required name attribute to an appropriate value.

3. Add a <clientCertificate> element to the <clientCredentials> element.

4. Set the following attributes to appropriate values: storeLocation, storeName, x509FindType, and findValue, as shown in the following code. For more information about certificates, see Working with Certificates.

   XML Copy

   <behaviors>
      <endpointBehaviors>
         <behavior name="endpointCredentialBehavior">
           <clientCredentials>
             <clientCertificate findValue="Contoso.com"
                                storeLocation="LocalMachine"
                                storeName="TrustedPeople"
                                x509FindType="FindBySubjectName" />
           </clientCredentials>
         </behavior>
      </endpointBehaviors>
   </behaviors>
   

5. When configuring the client, specify the behavior by setting the behaviorConfiguration attribute of the <endpoint> element, as shown in the following code. The endpoint element is a child of the <client> element. Also, specify the name of the binding configuration by setting the bindingConfiguration attribute to the binding for the client. If you are using a generated configuration file, the binding's name is automatically generated. In this example, the name is "tcpBindingWithCredential".

   XML Copy

   <client>
     <endpoint name =""
               address="net.tcp://contoso.com:8036/aloha"
               binding="netTcpBinding"
               bindingConfiguration="tcpBindingWithCredential"
               behaviorConfiguration="endpointCredentialBehavior" />
   </client>
   

• NetTcpBinding
• SetCertificate
• X509CertificateRecipientServiceCredential
• ClientBase<TChannel>
• X509CertificateInitiatorClientCredential
• Programming WCF Security
• Selecting a Credential Type
• ServiceModel Metadata Utility Tool (Svcutil.exe)
• Working with Certificates
• How to: Create a Client
• <netTcpBinding>
• <security>
• <message>
• <behavior>
• <behaviors>
• <clientCertificate>
• <clientCredentials>