How to: Create a Policy File

Article
09/15/2006

A policy file defines a set of policy assertions and the endpoints to which they are applied, which is called a mapping.

To create a policy file

Create a new XML document.
Add a root <policyDocument> Elementelement.
Add a single <policies> Element child****element and a single <mappings> Element childelement to the <policyDocument> Element element.

The <policies> element contains all of the policies for the policy file. Each policy defines a named set of requirements (known as policy assertions) for a SOAP message. The <mappings> element contains all of the mappings between policies and SOAP messages sent to or received by a Web service.

The following code example adds a <policies> element and a <mappings> element to a <policyDocument> element.
```
<policyDocument xmlns="https://schemas.microsoft.com/wse/2003/06/Policy">
  <mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
  </mappings>
  <policies xmlns:wsu=
    "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
    xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext" 
    xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy">
  </policies>
</policyDocument>
```

Add one or more <Policy> Element (WSE for Microsoft .NET) (1) childelements to the <policies> Element element

A <policy> element defines a single policy that is named by using the required Id attribute. For more information about declaring a policy assertion, see How to: Declare a Policy.

The following code example defines a policy that requires the SOAP <Body> element to be signed using an X.509 certificate.

<wsp:Policy wsu:Id="encrypted-body-x509">
  <wssp:Confidentiality wsp:Usage="wsp:Required">
    <wssp:KeyInfo>
      <wssp:SecurityToken>
        <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</wssp:TokenType>
        <wssp:Claims>
            <wssp:SubjectName>CN=WSE2QuickStartServer</wssp:SubjectName>
        </wssp:Claims>
      </wssp:SecurityToken>
    </wssp:KeyInfo>
    <wssp:MessageParts xmlns:rp="https://schemas.xmlsoap.org/rp" 
      Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
      wsp:Body()
    </wssp:MessageParts>
  </wssp:Confidentiality>
</wsp:Policy>

Add one or more <endpoint> Element child elements to the <mappings> Element element.

An <endpoint> element is used to map to a policy defined in a <Policy> Element (WSE for Microsoft .NET) (1) element to SOAP messages sent to or received by a Web service. Within each endpoint, the <operation> element is used to specify the operation. The <request>, <response>, and <fault> elements within the <operation> element are used to specify the policy to be applied. When a policy is found that matches the message, it is either verified or enforced*.* Verification is used on incoming messages to verify that a message satisfies the policy it is mapped to. Enforcement is used for outgoing messages. It uses the policy assertions to modify a message to match the policy it was mapped to.

The following code example maps the policy assertion x509-sign to all request SOAP messages sent to the endpoint http://www.cohowinery.com/Service1.asmx for the operation whose action is https://contoso.com/StockQuoteRequest. It specifies that there is no policy to be applied to the response messages sent by this service.
```
<mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
  <endpoint uri="https://localhost/X509SignPolicyService/X509SigningService.asmx">
    <operation requestAction="http://stockservice.contoso.com/wse/samples/2003/06/StockQuoteRequest"> 
      <request policy="#encrypted-body-x509" />
    </operation>
  </endpoint>
</mappings>
```

Example

The following code example shows mapping to a default operation by defining a policy named encrypted-body-x509 that requires the encryption of the <Body> element by an X509SecurityToken. This policy requires that SOAP messages sent to and from the endpoint http:// http://www.cohowinery.com/Service1.asmx adhere to the policy assertion.

<?xml version="1.0" encoding="utf-8"?>
<policyDocument xmlns="https://schemas.microsoft.com/wse/2003/06/Policy">
  <mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
    <endpoint uri="https://localhost/X509SignPolicyService/X509SigningService.asmx">
      <operation requestAction="http://stockservice.contoso.com/wse/samples/2003/06/StockQuoteRequest"> 
        <request policy="#encrypted-body-x509" />
      </operation>
    </endpoint>
  </mappings>
  <policies xmlns:wsu=
    "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" 
    xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext" 
    xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy">
    <!-- This policy requires that the body be encrypted by an x509 security token. -->
    <wsp:Policy wsu:Id="encrypted-body-x509">
      <wssp:Confidentiality wsp:Usage="wsp:Required">
        <wssp:KeyInfo>
          <wssp:SecurityToken>
            <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</wssp:TokenType>
            <wssp:Claims>
                <wssp:SubjectName>CN=WSE2QuickStart</wssp:SubjectName>
            </wssp:Claims>
          </wssp:SecurityToken>
        </wssp:KeyInfo>
        <wssp:MessageParts xmlns:rp="https://schemas.xmlsoap.org/rp" 
          Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
          wsp:Body()
        </wssp:MessageParts>
      </wssp:Confidentiality>
    </wsp:Policy>
  </policies>
</policyDocument>

How to: Create a Policy File

To create a policy file

Example

See Also

Tasks

Concepts

Other Resources

Additional resources