How to: Secure an Application Using a Custom Policy Assertion

  • Article

The following procedures explain how to use a custom policy assertion to secure a SOAP message exchange between a client and an XML Web service. There are individual procedures for securing a Web service and a client, although there are only a couple of differences between the two. Specifically, a Web service requires the WSE server protocol factory to be registered and a PolicyAttribute attribute be applied to the class implementing the Web service. Whereas a client uses a proxy class instead of the server protocol factory and a call to the SetPolicy method on the proxy class is required instead of applying the attribute.

The procedures also apply to Turnkey Security Assertions when you do not want to use the WSE Settings 3.0 Tool.

To secure the Web service using a custom policy assertion

  1. Open the Web service project in Visual Studio 2005.

  2. Register WSE configuration section handler by adding a <section> Element to the Web service's Web.config file.

    The name and type attributes must be set to microsoft.web.services3 and Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, respectively.

    The following code example, registers WSE configuration section handler.

    <configSections>
  <section name="microsoft.web.services3"
           type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
</configSections>

  3. Register WSE server protocol factory by adding a <soapServerProtocolFactory> Element to the Web service's Web.config file.

    The type attribute must be set to Microsoft.Web.Services3.WseProtocolFactory, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35.

    Note

    The WSE server protocol factory only needs to be registered when the Web service is hosted by ASP.NET inside of Internet Information Services (IIS).

    The following code example registers the WSE server protocol factory.

    <system.web>
  <webServices>
    <soapServerProtocolFactory type="Microsoft.Web.Services3.WseProtocolFactory, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </webServices>
</system.web>

  4. Specify the policy file that contains the Web service's policies by adding a <policy> Element to the Web service's Web.config file.

    Use the fileName attribute of the <policy> element to specify the name of a file on the local computer that represents the policy file.

    The following code example specifies that the Web service's policy file is wse3policyCache.config.

    <microsoft.web.services3>
  <policy fileName="..\..\wse3policyCache.config" />
</microsoft.web.services3>

  5. Register the custom policy assertion by adding an <extension> Element to the policy file.

    Use the name attribute of the <extension> element to specify the name of the XML element that contains the details for the custom policy assertion. Use the type attribute to specify the fully qualified type name for the custom policy assertion.

    The following code example specifies the fully qualified type name for the custom policy assertion and the element representing the custom policy assertion is CustomPolicyAssertions.CustomTraceAssertion, Server and CustomTraceAssertion, respectively.

    <extensions>
  <extension name="CustomTraceAssertion"           type="CustomPolicyAssertions.CustomTraceAssertion, Server" />
</extensions>

  6. Specify a policy by adding a <policy> Element (Policy) element to the policy file.

    The following code example defines a policy named ServicePolicy.

    <policy name="ServicePolicy">

  7. Specify the parameters for the custom policy assertion by adding the element(s) that the custom policy assertion is expecting as child elements of the <policy> element.

    The following code example adds the details of a custom policy assertion to the ServicePolicy policy.

    <policy name="ServicePolicy">
  <CustomTraceAssertion input="input-before.xml" output="output-before.xml"/>
</policy>

  8. Apply a PolicyAttribute attribute to the class implementing the Web service.

    By applying the PolicyAttribute attribute to the class that is implementing the Web service methods, the policy applies to all Web service methods (operations) within that class.

    The following code example specifies that all Web service methods within the Service class adhere to the ServicePolicy policy.

    <WebService(Namespace:="https://www.contoso.com/")> _
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _
<Policy("ServicePolicy")> _
Public Class Service
    Inherits System.Web.Services.WebService

    [WebService(Namespace = "https://www.contoso.com/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[Policy("ServicePolicy")] 
public class Service : System.Web.Services.WebService
{

To secure the client using a custom policy assertion

  1. Open the client project in Visual Studio 2005.

  2. Register the WSE configuration section handler by adding a <section> Element to the client application's app.config file.

    The name and type attributes must be set to microsoft.web.services3 and Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35, respectively.

    The following code example registers the WSE configuration section handler.

    <configSections>
  <section name="microsoft.web.services3"
           type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
</configSections>

  3. Specify the policy file that contains the client application's policies by adding a <policy> Element to the client application's app.config file.

    Use the fileName attribute of the <policy> element to specify the name of a file on the local computer that represents the policy file.

    The following code example specifies that the client application's policy file is wse3policyCache.config.

    <microsoft.web.services3>
  <policy fileName="..\..\wse3policyCache.config" />
</microsoft.web.services3>

  4. Register the custom policy assertion by adding an <extension> Element to the policy file.

    Use the name attribute of the <extension> element to specify the name of the XML element that contains the details for the custom policy assertion. Use the type attribute to specify the fully qualified type name for the custom policy assertion.

    The following code example specifies the fully qualified type name for the custom policy assertion and the element representing the custom policy assertion is CustomPolicyAssertions.CustomTraceAssertion, Client and CustomTraceAssertion, respectively.

    <extensions>
  <extension name="CustomTraceAssertion"           type="CustomPolicyAssertions.CustomTraceAssertion, Client" />
</extensions>

  5. Specify a policy by adding a <policy> Element (Policy) element to the policy file.

    The following code example defines a policy named ClientPolicy.

    <policy name="ClientPolicy">

  6. Specify the parameters for the custom policy assertion by adding the elements that the custom policy assertion is expecting as child elements of the <policy> element.

    The following code example adds the details of a custom policy assertion to the ClientPolicy policy.

    <policy name="ClientPolicy">
  <CustomTraceAssertion input="input-before.xml" output="output-before.xml"/>
</policy>

  7. Apply the policy to a SOAP message exchange by adding a call to the SetPolicy method of the proxy class with the policy name to the client code.

    The following code example specifies that the policy for the client is named ClientPolicy.

    proxy.SetPolicy("ClientPolicy")

    proxy.SetPolicy("ClientPolicy");

Example

The following code example is a configuration file for a Web service that registers the WSE configuration section handler, the WSE server protocol factory, and specifies the Web service's policy file.

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns="https://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <section name="microsoft.web.services3" type="Microsoft.Web.Services3.Configuration.WebServicesConfiguration, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </configSections>
  <system.web>
    <webServices>
      <soapServerProtocolFactory type="Microsoft.Web.Services3.WseProtocolFactory, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    </webServices>
  </system.web>
  <microsoft.web.services3>
    <policy fileName="..\..\wse3policyCache.config" />
  </microsoft.web.services3>
</configuration>

The following code example is a policy file for a Web service that defines a policy named ServicePolicy, which uses the CustomSecurityAssertion and CustomTraceAssertion custom policy assertions. Because policy assertions are ordered within a policy, the CustomTraceAssertion custom policy assertion is called before and after security is applied by the CustomSecurityAssertion custom policy assertion.

<policies>
  <extensions>
    <extension name="CustomSecurityAssertion" type="CustomPolicyAssertions.CustomSecurityAssertion, Service" />
    <extension name="CustomTraceAssertion" type="CustomPolicyAssertions.CustomTraceAssertion, Service" />
  </extensions>
  <policy name="ServicePolicy">
    <CustomTraceAssertion input="input-before.xml" output="output-before.xml"/>
    <CustomSecurityAssertion >
      <clientToken>
        <x509 
          storeLocation="CurrentUser"
          storeName="My"
          findValue="CN=WSE2QuickStartClient"
          findType="FindBySubjectDistinguishedName" />
      </clientToken>
      <serviceToken>
        <x509
          storeLocation="LocalMachine"
          storeName="My"
          findValue="CN=WSE2QuickStartServer"
          findType="FindBySubjectDistinguishedName" />
      </serviceToken>
    </CustomSecurityAssertion >
    <CustomTraceAssertion input="input-after.xml" output="output-after.xml"/>
  </policy>
</policies>

See Also

Tasks

How to: Create a Custom Policy Assertion that Secures SOAP Messages

Reference

<section> Element
<soapServerProtocolFactory> Element
<policy> Element
<extension> Element
<policy> Element (Policy)
SetPolicy
PolicyAttribute

Concepts

Policy Files
Policy Assertions
Policy Extensions

Other Resources

Custom Policy Assertions