Web Services Policy Framework | Understanding Web Services Specifications and the WSE (Pro Developer)

As the highest level of these policy- related specifications, the WS-Policy specification describes the framework that can be used to combine various policy assertions, each one of them an XML node, into a single policy expression. Applications and services can then use this policy expression to determine the requirements for accessing a Web service provider, and a policy expression might apply to one or more Web methods supported by a Web service or even be used with multiple Web services across an entire domain. As such, multiple policy expressions can be combined into an overall policy document for an entire entity, such as a domain or a company.

Although they might sound complicated, policy expressions are simply hierarchical structures of XML nodes, in which these nodes are either policy assertions, policy operators, or other policy expressions. The structure of a policy expression conveys the ultimate requirements for accessing the service. For example, you can create a policy expression that says a valid request message must have property A, and if not, it must have properties B and C.

The following is an example of a simple policy expression that makes two security assertions:

 <wsp:Policy xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:All> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="1"> 
 <wsse:TokenType>wsse:X509</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:Integrity wsp:Usage="wsp:Required" wsp:Preference="8" > 
 <wsse:Algorithm Type="wsse:AlgSignature" 
 URI="http://www.w3.org/2000/09/xmlenc#aes" /> 
 </wsse:Integrity> 
 </wsp:All> 
 </wsp:Policy>

In this statement, the two assertions are that a request message must include a valid X.509 certificate that can be used to identify the sender and that the message must be digitally signed using the Advanced Encryption Standard (AES) algorithm so that the recipient can determine whether the message has been tampered with. As you can see, a policy statement is simply an XML structure that combines one or more assertions using policy expressions.

Policy Operators

Much like logical or arithmetic operators, policy operators allow us to define relationships among multiple assertions in a policy expression. WS-Policy defines the following operators, which themselves can contain other nested operators.

All

This element dictates that all assertions or other expression elements that are child elements must be satisfied in order to access a Web service. In the following example, All indicates that an X.509 certificate must be included in the request and that the message must be encrypted and digitally signed:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:All> 
 <wsse:SecurityToken wsp:Usage="wsp:Required"> 
 <wsse:TokenType>wsse:X509</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:Integrity wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgSignature" 
 URI="http://www.w3.org/2000/09/xmlenc#aes" /> 
 </wsse:Integrity> 
 <wsse:Confidentiality wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgEncryption" 
 URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/> 
 <MessageParts> 
 wsp:GetNodesetForNode(wsp:GetBody(.)) 
 </MessageParts> 
 </wsse:Confidentiality> 
 </wsp:All> 
 </wsp:Policy>

ExactlyOne

This element dictates that only one of the requirements prescribed by the contained assertions is to be followed when the service is accessed. For example, the following policy expression states that the requesting application must provide only one of three types of security tokens for authentication:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:ExactlyOne> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="10"> 
 <wsse:TokenType>wsse:Kerberosv5TGT</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="5"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="1"> 
 <wsse:TokenType>wsse:UsernameToken</wsse:TokenType> 
 </wsse:SecurityToken> 
 </wsp:ExactlyOne> 
 </wsp:Policy>

Note that when the ExactlyOne operator is used, it overrides the Usage attribute value, which in this example is Required . When using the ExactlyOne operator, it s helpful to also specify the optional Preference attribute on the contained assertions to give requesting applications an idea of which of these assertions are preferred. A higher Preference value is more preferable than a lower value.

OneOrMore

This element dictates that at least one of the requirements prescribed by the contained assertions must be followed when accessing the service. For example, the following policy expression states that the requesting application need provide only one of the three types of security tokens for authentication but can provide more if desired:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:OneOrMore> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="10"> 
 <wsse:TokenType>wsse:Kerberosv5TGT</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="5"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="1"> 
 <wsse:TokenType>wsse:UsernameToken</wsse:TokenType> 
 </wsse:SecurityToken> 
 </wsp:OneOrMore > 
 </wsp:Policy>

Like ExactlyOne , the OneOrMore operator benefits from having the Preference attribute specified on the contained assertions.

PolicyReference

Although not technically a policy operator, the PolicyReference element provides a means whereby one policy expression can be included, by reference, as an element in another. This element is treated as an All element with respect to the assertions and operators in the policy expression that references it. For a policy expression to be referenced, it must have a Uniform Resource Identifier (URI) assigned by the Id attribute or else a qualified name assigned to the Name attribute. The following is an example of a policy expression that references two other expressions, one by name and one by URI:

 <wsp:Policy wsu:Id="X509" 
 xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsse:SecurityToken wsp:Usage="wsp:Required"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 </wsse:SecurityToken> 
 </wsp:Policy> 
 
 <wsp:Policy Name="Kerberos" 
 TargetNamespace="http://example.com/policy/Kerberos" 
 xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="10"> 
 <wsse:TokenType>wsse:Kerberosv5TGT</wsse:TokenType> 
 </wsse:SecurityToken> 
 </wsp:Policy> 
 
 <wsp:Policy xmlns:xname="http://example.com/policy/Kerberos" 
 xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:All> 
 <wsp:PolicyReference URI="#X509" /> 
 <wsp:PolicyReference Ref="xname:Kerberos" /> 
 </wsp:All> 
 </wsp:Policy>

Policy Assertions

Assertions are the building blocks of a policy expression, and they describe the rules that an application must follow when making requests to a Web service. Policy assertions follow this general XML format:

 <wsp:Policy wsu:Id="..."? Name="..."? TargetNamespace="..."? > 
 <Assertion wsp:Usage="..."? wsp:Preference="..."? /> * 
   
 <wsse:Security>...</wsse:Security> ? 
 </wsp:Policy>

General Messaging Assertions

The WS-PolicyAssertions specifications define a set of policy assertions that apply to the general messaging behaviors of SOAP-based Web services. All of these assertions follow the general format defined in WS-Policy and are defined next .

TextEncoding

If a Web service supports more than one character encoding or requires a nonstandard encoding, the TextEncoding assertion can be used to define such a policy, provided the XML specification supports the encoding. Of course, to maximize interoperability, the default encoding of UTF-8 should be used. The following sample is a policy expression that declares an option between two supported character encodings:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy"> 
 <wsp:ExactlyOne> 
 <wsp:TextEncoding wsp:Usage="wsp:Required" Encoding="iso-8859-5" 
 wsp:Preference="5" /> 
 <wsp:TextEncoding wsp:Usage="wsp:Required" Encoding="iso-8859-1" /> 
 wsp:Preference="1" /> 
 </wsp: ExactlyOne> 
 </wsp:Policy>

Language

If a Web service supports multiple languages for textual content or if English isn t the standard, the Language assertion can be used to declare such policies. The following policy example declares that both English and German are supported:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy"> 
 <wsp:ExactlyOne> 
 <wsp:Language wsp:Usage="wsp:Required" Language="en" /> 
 <wsp:Language wsp:Usage="wsp:Required" Language="de" /> 
 </wsp:ExactlyOne> 
 </wsp:Policy>

SpecVersion

This assertion enables a Web service to specify which versions of a specification request messages must conform to, where a specification is referenced by its URI.

MessagePredicate

This assertion is used to ensure that request messages contain the necessary XML elements in order to comply with a Web service s requirements. This assertion is particularly useful for declaring requirements for proprietary elements in the message header or body elements. The message predicate is selected using either XPath 1.0 or the message part selection functions defined in WS-Policy, which are used to select either the entire message body ( wsp:Body ) or a specified message header ( wsp:Header ). The selection language used is specified in the Dialect attribute; if this attribute is not specified, the default, XPath 1.0, is assumed. While the two message part functions are easier to use, XPath should be used to select specific parts of a body or header element. The WS-PolicyAssertions specification introduces nine new XPath functions for selecting parts of a SOAP message, which I won t detail here. In the following assertion, an XPath expression, which uses the new GetHeader function, identifies messages with only one MyCustomHeader header element:

 <wsp:MessagePredicate wsp:Usage="wsp:Required"> 
 count(wsp:GetHeader(.)/MyCustomHeader) = 1 
 </wsp:MessagePredicate>

Note that the use of XPath expressions to select the message predicate is not supported by WSE 2.0.

Security Policy Assertions

While there is certainly a need for general messaging assertions, the drive to declare security requirements to enable interoperability with the WS-Security specification was certainly a major impetus behind the development of WS-Policy. Thus an entire specification, the WS-SecurityPolicy specification, is devoted to defining security assertions. These assertions, most of which are supported by WSE 2.0, are defined next.

SecurityToken

This assertion is used to declare which types of security tokens, defined in WS-Security, must be supplied in order to authenticate a requesting application. Usage of the security tokens listed in Table 6-1 can be specified by this assertion.

Table 6-1: Security Tokens with Defined Policy Assertions
Qualified Name	Token Type
wsse:X509v3	X.509 Certificate
wsse:Kerberosv5TGT	Kerberos ticket-granting ticket (TGT)
wsse:Kerberosv5ST	Kerberos service ticket
wsse:UsernameToken	Username token
wsse:SAMLAssertion	SAML Assertion
wsse:XrMLLicense	XrML License

In this table, SAML refers to an XML-based security-assertion token.

WS-SecurityPolicy supports additional optional elements for specifying additional information about token requirements, including which certificate authorities and key distribution centers are acceptable and any token-specific information that makes it easier for requesting clients to present the correct token in the request message. For example, the following policy expression defines acceptable tokens as X.509 certificates from one of two different certificate authorities: a Kerberos TGT from the specified key distribution center or a username token with the specified username.

 <wsp:Policy> 
 <wsp:ExactlyOne> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="10"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>My Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact"> 
 cn = VendorXYZ 
 </wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="5"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>Alternate Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact"> 
 cn = VendorXYZ 
 </wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="3"> 
 <wsse:TokenType>wsse:Kerberosv5TGT</wsse:TokenType> 
 <wsse:TokenIssuer>My KDC</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Prefix"> 
 VendorXYZ 
 </wsse:SubjectName> 
 <wsse:ServiceName>VendorPOService</wsse:ServiceName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="1"> 
 <wsse:TokenType>wsse:UsernameToken</wsse:TokenType> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact">VendorXYZ</wsse:SubjectName> 
 <wsse:UsePassword wsp:Usage="wsp:Required" Type="wsse:PasswordDigest"/> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 </wsp:ExactlyOne> 
 </wsp:Policy>

For more information about details and usage of security token assertions, refer to the WS-SecurityPolicy specification.

Integrity

When a Web service requires that incoming request messages be digitally signed to indicate whether they have been tampered with or modified, an Integrity assertion can be added to the policy expression. The following is an example of an assertion that the message header must be digitally signed with an X.509 certificate using the Secure Hash Algorithm (SHA) algorithm:

 <wsse:Integrity wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgCanonicalization" 
 URI="http://www.w3.org/Signature/Drafts/xml-exc-c14n"/> 
 <wsse:Algorithm Type="wsse:AlgSignature" 
 URI=" http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> 
 <wsse:SecurityToken> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:MessageParts> 
 wsp:GetNodesetForNode(wsp:GetHeader(.)) 
 </MessageParts> 
 </wsse:Integrity>

For more information about details and usage of integrity assertions, refer to the WS-SecurityPolicy specification.

Confidentiality

If the Web service requires that any parts of a request message be encrypted, this can be stated in the policy expression using a Confidentiality assertion. A Confidentiality assertion that declares that the EncryptedElement node in the message body must be encrypted using the service s X.509 certificate and Triple-DES (Data Encryption Standard) specification might look like this:

 <wsse:Confidentiality wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgEncryption" 
 URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/> 
 <wsse:KeyInfo> 
 <wsse:SecurityToken> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>My Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact"> 
 cn = InvoiceService 
 </wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 </wsse:KeyInfo> 
 <MessageParts> 
 wsp:GetNodesetForNode(GetBody(.)/EncryptedElement) 
 </MessageParts> 
 </wsse:Confidentiality>

Visibility

A request message to a Web service can be routed through one or more intermediate Web services. If any of these intermediaries need to be able to access part of the request message, a Visibility assertion can be made to prevent that portion of the message from being encrypted. The following example assertion requires that the message header not be encrypted:

 <wsse:Visibility wsp:Usage="wsp:Required"> 
 <MessageParts> 
 wsp:GetInfosetForNode(wsp:GetHeader(.)) 
 </MessageParts> 
 </wsse:Visibility>

SecurityHeader

This assertion specifies requirements of the format of the Security header element in a request message. The following example requires that child elements within the Security header be prefixed by the WS-Security XML namespace and that only encrypted elements specifically referenced in the Security header will be processed :

 <wsse:SecurityHeader wsp:Usage="wsp:Required" MustPrepend="true" 
 MustManifestEncryption="true"/>

MessageAge

This assertion defines the maximum number of seconds a message has to travel from the sender to the receiver. The total travel time is determined by using the value of the Timestamp header, which makes it mandatory when this assertion is used. If the message transmission time exceeds the value of the Age attribute, the message is rejected. The following is an example of this assertion with an age of 30 minutes:

 <wsse:MessageAge wsse:Usage="wsp:Required Age="1800"/>

Obviously the smaller this value, the more important it becomes for the two endpoints to have their times synchronized. The means by which these machines synchronize their times is not addressed in any of the specifications addressed by this book. Rather, time synchronization is normally accomplished via some out-of- band mechanism like a phone call or use of a common time server.

Reliable Messaging Assertions

The WS-ReliableMessaging specification, which I described in Chapter 4, defines a set of policy assertions that are used when declaring the message reliability features that must be used when accessing a Web service endpoint. These assertions include the following:

Specification Version This assertion is used to declare the version of WS-ReliableMessaging to which a message must conform. This assertion is made by the SpecVersion element, as in the following:
```
 <wsp:SpecVersion 
 wsp:URI="http://schemas.xmlsoap.org/ws/2003/03/rm" 
 wsp:Usage="wsp:Required"/> 
```
Delivery Assurance This assertion is used by the Web service that is the ultimate recipient to declare message delivery behaviors when receiving messages from the service guaranteeing reliability. This assertion is made by the DeliveryAssurance element, where the Value attribute can be one of these values:
- wsrm:AtMostOnce Messages are delivered only once.
- wsrm:AtLeastOnce Messages are delivered at least once.
- wsrm:ExactlyOnce Messages are delivered exactly once, which is equivalent to both of the previous assertions together.
- wsrm:InOrder Messages are delivered in the order they were sent.

For example, the following assertions request that messages be delivered by the reliability service exactly once and in the order that they were sent:

 <wsrm:DeliveryAssurance Value="wsrm:ExactlyOnce"/> 
 <wsrm:DeliveryAssurance Value="wsrm:InOrder"/>

Sequence Expiration This assertion declares the time at which a reliable messaging sequence is no longer valid. This assertion is made using the wsu: Expires element. The following assertion indicates that a sequence expires on December 31, 2005:
```
 <wsu:Expires>2005-12-31T12:00:00.000-00:00</wsu:Expires> 
```
Inactivity Timeout This assertion declares the number of milliseconds before an inactive sequence expires. The Milliseconds attribute of the InactivityTimeout element is used to specify this inactivity period. The following assertion indicates that a sequence will expire if it is inactive for longer than 1 minute:
```
 <wsrm:InactivityTimeout Milliseconds="60000" wsp:Usage="wsp:Observed" /> 
```
Retransmission Interval This assertion declares the number of milliseconds before an unacknowledged message is re-sent. The Milliseconds attribute of the BaseRetransmissionInterval element is used to specify this period. Another related assertion, ExponentialBackoff , is used to declare that a previously agreed upon algorithm is used when a new retransmission interval is negotiated. The following assertion indicates that a message must be re-sent if an acknowledgement has not been received within 1 minute and that the back- off algorithm should be used:
```
 <wsrm:BaseRetransmissionInterval Milliseconds="60000" 
 wsp:Usage="wsp:Observed" /> 
 <wsrm:ExponentialBackoff wsp:Usage="wsp:Observed"/> 
```
Acknowledgement Interval This assertion declares the number of milliseconds before an acknowledgement must be sent in a separate message. The Milliseconds attribute of the AcknowledgementInterval element is used to specify this period. The following assertion indicates that a stand-alone acknowledgement message must be sent if another message is not being returned to the sender within 1 minute:
```
 <wsrm:AcknowledgementInterval Milliseconds="60000" wsp:Usage="wsp:Observed" /> 
```

Referencing Policy Expressions

Of course, it s not enough that we can simply create policy expressions. Just as important are mechanisms for communicating policy expressions to other parties and for applying them against sent and received messages. In fitting with the Web service model promoted by WSDL, the best way to communicate policies are to make them discoverable and accessible to the parties who must access a Web service endpoint. We already have mechanisms defined for publishing Web service definitions, such as WSDL and UDDI. However, we need to be able to locate policy files and reference policy expressions from these description-and-discovery documents. The WS-PolicyAttachment specification provides mechanisms for including policy expressions within an XML document, such as a SOAP message header, or referencing them from an XML document, such as a WSDL file. By linking policies to WSDL, we can leverage the discoverability, description, and extensibility features of WSDL.

Before I discuss how to link policies to WSDL, I need to discuss some of the semantics for identifying policies. While policy expressions are the integral unit for declaring policies, when publishing multiple policy assertions, a service may want to store all policy assertions in a single document, even when these policies relate to multiple endpoints implemented by the service. WS-Policy provides a way to reference a single policy expression within an XML document containing multiple expressions using either a qualified name or a URI.

To reference a policy expression using a URI, the Id attribute must be supplied, as defined by the Web Service Security Addendum specification. This enables the policy expression to be referenced relative to a base URI plus the pound sign and the name assigned in the Id attribute. For example, you can reference the following policy expression in the http://example.com/policy namespace as http://example.com/policy#MySecurityPolicy :

   
 <wsp:Policy wsu:Id="MySecurityPolicy" 
 xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy"> 
   
 </wsp:Policy>

The other mechanism for referencing a policy element involves assigning a qualified name to the policy expression, which is done using the Name attribute as defined by WS-Policy. When the Name attribute is used to specify policy expressions, an expression named MyTextEncodingPolicy in the http://example.com/policy namespace is referenced as p:MyTextEncodingPolicy , where xmlns:p= http://example.com/policy .

To hook up policy expressions to other XML documents, the WS-PolicyAttachment specification defines two mechanisms for referencing policy expressions. The first enables a policy expression to be referenced within any arbitrary XML element. This mechanism lets us add a PolicyURIs attribute to any XML element and reference the URI for a policy expression. Likewise, the PolicyRefs attribute can be added to any XML element to reference a policy expression by its fully qualified name. The following example element references these policy expressions that I have just discussed:

 <myXmlElement xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:p="http://example.com/policy" 
 TargetNamespace="http://example.com" 
 wsp:PolicyURIs="http://example.com/policy#MySecurityPolicy" 
 wsp:PolicyRefs="p:MyTextEncodingPolicy"> 
 
 </myXmlElement>

The other mechanism enables a policy expression to be assigned to an arbitrary Web service resource; such resources can be specified using the semantics of the WS-Addressing specification, which I discussed in Chapter 4. Known as a policy attachment, this XML policy structure is composed of the following elements:

A reference to the resource to which the policy statement applies, where this reference is based on WS-Addressing.
A policy expression either defined by a Policy element or referenced by a PolicyReference element.
Security information, defined using WS-Security, such as a digital signature.

In the following example, the PolicyAttachment element maps two policy expressions that reference Web services, wherein the security token policy is contained within the policy attachment document and the message age policy is referenced externally:

 <wsp:PolicyAttachment> 
 <wsp:AppliesTo> 
 <wsa:EndpointReference xmlns:x="http://example.com/myservice"> 
 <wsa:Address>http://example.com/myservice</wsa:Address> 
 <wsa:PortType>x:myPortType</wsa:PortType> 
 <wsa:ServiceName>x:myService</wsa:ServiceName> 
 </wsa:EndpointReference> 
 </wsp:AppliesTo> 
 <wsp:Policy> 
 <wsse:SecurityToken wsp:Usage="wsp:Required"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>My Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact"> 
 cn = VendorXYZ 
 </wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 </wsp:Policy> 
 <wsp:PolicyReference URI="http://example.com/message_age_policy.xml" /> 
 </wsp:PolicyAttachment>

Policy Assertions and WSDL

Now that you have the means to define policies for particular Web service resources, you need to add this information to your WSDL files so that it can be publicly exposed to applications that consume your services. The ideal method for publishing a policy assertion for a given resource is to add it to the part of the WSDL file that defines the section of the Web service to which policy applies. However, when doing so, it is important to remember that policy assertions made on parent WSDL elements are enforced on child elements, which means that we must use care when applying policies at multiple, overlapping levels in a service definition because we may get unexpected results for the effective policy for a given WSDL element. For example, when a policy assertion, say a signature requirement, is defined at the message level of the service description, this policy will apply to all parts of the message. However, when a policy, such as confidentially requirement, is also defined for a single message part , the effective policy for that part of the message will include both the signature policy, defined for message, and the confidentiality policy, defined on the part . This can get even more complicated when you define a policy for the portType or operation elements to which the message belongs. In such cases, the effective policy for a message part is determined as the sum total of the policies defined for the portType , operation , message , and part elements.

To make things even less straight-forward, because of restrictions in WSDL 1.1, you aren t able to add arbitrary XML, such as a PolicyAttachment element, to portType and message elements. Instead, WS-PolicyAttachment specifies that a required UsingPolicy element be added to the WSDL definition to indicate that policies are being defined. In addition, policy references are added to the appropriate elements in the WSDL document for the Web service functionalities for which policies are being defined. When consuming a policy annotated WSDL file, you must be able to retrieve the externally referenced policy files. For example, the following WSDL file includes policy information for the DocumentService Web service:

 <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" 
 targetNamespace="http://example.com/documentservice/" 
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:ps="http://example.com/documentservice/policy/" 
 xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:s="http://example.com/documentservice/" 
 xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
 xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
 xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"> 
 <wsp:UsingPolicy wsdl:Required="true" /> 
 <types> 
   
 </types> 
 <message name="GetDocumentSoapIn" 
 wsp:PolicyURIs="http://example.com/policy#SignaturePolicy"> 
 <part name="parameters" element="s:GetDocument" 
 wsp:PolicyURIs="http://example.com/policy#EncryptionPolicy /> 
 </message> 
 <message name="GetDocumentSoapOut"> 
 <part name="parameters" element="s:GetDocumentResponse" /> 
 </message> 
   
 <portType name="DocumentServiceSoap"> 
 <operation name="GetDocument"> 
 <documentation>Retrieves XML documents using DIME</documentation> 
 <input message="s:GetDocumentSoapIn" /> 
 <output message="s:GetDocumentSoapOut" /> 
 </operation> 
   
 </portType> 
 <binding name="DocumentServiceSoap" type="s:DocumentServiceSoap"> 
 <soap:binding 
 transport="http://schemas.xmlsoap.org/soap/http" style="document" /> 
 <operation name="GetDocument"> 
 <soap:operation 
 soapAction="http://example.com/documentservice/GetDocument" 
 style="document" /> 
 <input> 
 <soap:body use="literal" /> 
 </input> 
 <output> 
 <soap:body use="literal" /> 
 </output> 
 <wsp:Policy> 
 <wsse:SecurityToken wsp:Usage="wsp:Required"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>My Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact" 
 >cn = VendorXYZ</wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 </wsp:Policy> 
 </operation> 
   
 </binding> 
 <service name="DocumentService"> 
 <documentation> 
 Stores XML documents for search and retrieval 
 </documentation> 
 <port name="DocumentServiceSoap" binding="s:DocumentServiceSoap"> 
 <soap:address 
 location="http://example.com/documentservice/documentservice.asmx" /> 
 </port> 
 </service> 
 </definitions>

In this example, any requests to the GetDocument method must contain a X509-based security token, and all parts of the request message to the GetDocument Web method must conform to a signature policy referenced by the SignaturePolicy identifier. In addition, the body of the request message must conform to the encryption policy referenced by the EncryptionPolicy identifier. This makes the effective policy for the body of a request message to the GetDocumen t method the same as the following:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:All> 
 <wsse:SecurityToken wsp:Usage="wsp:Required"> 
 <wsse:TokenType>wsse:X509v3</wsse:TokenType> 
 <wsse:TokenIssuer>My Trusted Root Authority</wsse:TokenIssuer> 
 <wsse:Claims> 
 <wsse:SubjectName MatchType="wsse:Exact" 
 >cn = VendorXYZ</wsse:SubjectName> 
 </wsse:Claims> 
 </wsse:SecurityToken> 
 <wsse:Integrity wsp:Usage="wsp:Required" > 
 <wsse:Algorithm Type="wsse:AlgSignature" 
 URI="http://www.w3.org/2000/09/xmlenc#aes" /> 
 </wsse:Integrity> 
 <wsse:Confidentiality wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgEncryption" 
 URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/> 
 <MessageParts> 
 wsp:GetNodesetForNode(wsp:GetBody(.)) 
 </MessageParts> 
 </wsse:Confidentiality> 
 </wsp:All> 
 </wsp:Policy>

Securing Policy Expressions

As publicly exposed in XML documents, policy expressions and policy attachments are exposed to the same kinds of vulnerabilities as SOAP messages being transported using an unencrypted transport; therefore, policy expressions require the same kind of security considerations that are given to SOAP messages. For example, if I m consuming a policy expression for a Web service, I need to be able to know that this policy expression has indeed been published from the Web service that I m expecting and hasn t been modified by any malicious parties. To ensure this, the Web service must digitally sign its policy expressions using a trusted security token (either a shared secret or a private key) as defined in WS-Security. In a similar manner, if I need to protect my Web service s policies but also make them publicly available, I can encrypt parts of the policy expression using XML encryption as defined in WS-Security.

Because you can apply the features of WS-Security to a policy expression as you would a SOAP message, WS-Policy supports including the Security element, as defined by WS-Security, within a policy expression. When defined in this way, the Security element specifies the security features that are implemented in the policy expression. For example, the following policy expression includes a digital signature, which is defined in the Security element:

 <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2002/12/policy" 
 xmlns:ds="http://www.w3.org/2000/09/xmldsig#" 
 xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext/"> 
 <wsp:All > 
 <wsse:SecurityToken wsp:Usage="wsp:Required" wsp:Preference="1"> 
 <wsse:TokenType>wsse:X509</wsse:TokenType> 
 </wsse:SecurityToken> 
 <wsse:Integrity wsp:Usage="wsp:Required" wsp:Preference="8" > 
 <wsse:Algorithm Type="wsse:AlgSignature" 
 URI="http://www.w3.org/2000/09/xmlenc#aes" /> 
 </wsse:Integrity> 
 <wsse:Confidentiality wsp:Usage="wsp:Required"> 
 <wsse:Algorithm Type="wsse:AlgEncryption" 
 URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/> 
 <MessageParts> 
 wsp:GetNodesetForNode(wsp:GetBody(.)) 
 </MessageParts> 
 </wsse:Confidentiality> 
 </wsp:All> 
 <wsse:Security> 
 <wsse:BinarySecurityToken ValueType="wsse:X509v3" 
 EncodingType="wsse:Base64Binary" Id="MyX509Token"> 
 MIIEZzCCA9CgAwIBAgIQEmtJZc0rqrKh5i... 
 </wsse:BinarySecurityToken> 
 <ds:Signature> 
 <ds:SignedInfo> 
 <ds:CanonicalizationMethod Algorithm= 
 "http://www.w3.org/2001/10/xml-exc-c14n#"/> 
 <ds:SignatureMethod Algorithm= 
 "http://www.w3.org/2000/09/xmldsig#rsa-sha1"/> 
 <ds:Reference URI=""> 
 <ds:Transforms> 
 <ds:Transform 
 Algorithm="http://www.w3.org/TR/1999/REC-xpath-19991116"> 
 <XPath>not(ancestor-or-self::ds:Signature)</XPath> 
 </ds:Transform> 
 </ds:Transforms> 
 <ds:DigestMethod Algorithm= 
 "http://www.w3.org/2000/09/xmldsig#sha1"/> 
 <ds:DigestValue>A1b2C3d4E5f6...</ds:DigestValue> 
 </ds:Reference> 
 </ds:SignedInfo> 
 <ds:SignatureValue> 
 BL8jdfToEb1l/vXcMZNNjPOV... 
 </ds:SignatureValue> 
 <ds:KeyInfo> 
 <wsse:SecurityTokenReference> 
 <wsse:Reference URI="#MyX509Token"/> 
 </wsse:SecurityTokenReference> 
 </ds:KeyInfo> 
 </ds:Signature> 
 </wsse:Security> 
 </wsp:Policy>

In this example, the NULL value of the URI attribute in the Reference element indicates that the entire expression will be included in the signature. However, the act of signing will change the Signature element and, thereby, the contents of the expression, so I specify the referenced XPath transformation to indicate that the digital signature doesn t include the Signature element.