Skip to content

Latest commit

 

History

History
101 lines (71 loc) · 6.55 KB

how-to-secure-metadata-endpoints.md

File metadata and controls

101 lines (71 loc) · 6.55 KB
Raw
description title ms.date dev_langs ms.assetid
Learn more about: How to: Secure Metadata Endpoints
How to: Secure Metadata Endpoints
03/30/2017
csharp
vb
9f71b6ae-737c-4382-8d89-0a7b1c7e182b

How to: Secure Metadata Endpoints

Metadata for a service can contain sensitive information about your application that a malicious user can leverage. Consumers of your service may also require a secure mechanism for obtaining metadata about your service. Therefore, it is sometimes necessary to publish your metadata using a secure endpoint.

Metadata endpoints are generally secured using the standard security mechanisms defined in Windows Communication Foundation (WCF) for securing application endpoints. For more information, see Security Overview.

This topic walks through the steps to create an endpoint secured by a Secure Sockets Layer (SSL) certificate or, in other words, an HTTPS endpoint.

To create a secure HTTPS GET metadata endpoint in code

  1. Configure a port with an appropriate X.509 certificate. The certificate must come from a trusted authority, and it must have an intended use of "Service Authorization." You must use the HttpCfg.exe tool to attach the certificate to the port. See How to: Configure a Port with an SSL Certificate.

    [!IMPORTANT] The subject of the certificate or its Domain Name System (DNS) must match the name of the computer. This is essential because one of the first steps the HTTPS mechanism performs is to check that the certificate is issued to the same Uniform Resource Identifier (URI) as the address upon which it is invoked.

  2. Create a new instance of the xref:System.ServiceModel.Description.ServiceMetadataBehavior class.

  3. Set the xref:System.ServiceModel.Description.ServiceMetadataBehavior.HttpsGetEnabled%2A property of the xref:System.ServiceModel.Description.ServiceMetadataBehavior class to true.

  4. Set the xref:System.ServiceModel.Description.ServiceMetadataBehavior.HttpsGetUrl%2A property to an appropriate URL. Note that if you specify an absolute address, the URL must begin with the scheme https://. If you specify a relative address, you must supply an HTTPS base address for your service host. If this property is not set, the default address is "", or directly at the HTTPS base address for the service.

  5. Add the instance to the behaviors collection that the xref:System.ServiceModel.Description.ServiceDescription.Behaviors%2A property of the xref:System.ServiceModel.Description.ServiceDescription class returns, as shown in the following code.

    [!code-csharpc_HowToSecureEndpoint#1] [!code-vbc_HowToSecureEndpoint#1]

To create a secure HTTPS GET metadata endpoint in configuration

  1. Add a <behaviors> element to the <system.serviceModel> element of the configuration file for your service.

  2. Add a <serviceBehaviors> element to the <behaviors> element.

  3. Add a <behavior> element to the <serviceBehaviors> element.

  4. Set the name attribute of the <behavior> element to an appropriate value. The name attribute is required. The example below uses the value mySvcBehavior.

  5. Add a <serviceMetadata> to the <behavior> element.

  6. Set the httpsGetEnabled attribute of the <serviceMetadata> element to true.

  7. Set the httpsGetUrl attribute of the <serviceMetadata> element to an appropriate value. Note that if you specify an absolute address, the URL must begin with the scheme https://. If you specify a relative address, you must supply an HTTPS base address for your service host. If this property is not set, the default address is "", or directly at the HTTPS base address for the service.

  8. To use the behavior with a service, set the behaviorConfiguration attribute of the <service> element to the value of the name attribute of the behavior element. The following configuration code shows a complete example.

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <system.serviceModel>
  <behaviors>
   <serviceBehaviors>
    <behavior name="mySvcBehavior">
     <serviceMetadata httpsGetEnabled="true"
          httpsGetUrl="https://localhost:8036/calcMetadata" />
    </behavior>
   </serviceBehaviors>
  </behaviors>
 <services>
  <service behaviorConfiguration="mySvcBehavior"
        name="Microsoft.Security.Samples.Calculator">
   <endpoint address="http://localhost:8037/ServiceModelSamples/calculator"
   binding="wsHttpBinding" bindingConfiguration=""
   contract="Microsoft.Security.Samples.ICalculator" />
  </service>
 </services>
</system.serviceModel>
</configuration>

Example

The following example creates an instance of a xref:System.ServiceModel.ServiceHost class and adds an endpoint. The code then creates an instance of the xref:System.ServiceModel.Description.ServiceMetadataBehavior class and sets the properties to create a secure metadata exchange point.

[!code-csharpc_HowToSecureEndpoint#0] [!code-vbc_HowToSecureEndpoint#0]

Compiling the Code

The code example uses the following namespaces:

  • xref:System.ServiceModel?displayProperty=nameWithType

  • xref:System.ServiceModel.Description?displayProperty=nameWithType

See also