The WS-Policy Framework

As you can see, there is a need for something more expressive than what exists with WSDL alone. In an effort to create a richer language for describing the constraints around WS-Security, as we discussed at the beginning of this chapter, another specification framework called WS-Policy has emerged. The WS-Policy framework describes policies about nearly anything related to Web services; however, it is particularly well suited to WS-Security. The WS-Policy framework consists of a set of specifications relating to policy:

• WS-Policy defines a framework for describing policy assertions.

• WS-PolicyAttachment describes how these policies are attached to a resource (for example, WSDL).

• WS-PolicyAssertions describes a common set of assertions that are applicable across different domains.

These three WS-Policy specifications set the stage for WS-SecurityPolicy, which provides a set of WS-Security “specific policies used to publish information about all aspects of WS-Security.

WS-Policy Details

WS-Policy is a generalized grammar for describing the capabilities, requirements, and characteristics of a Web service. ^[1] It is not specific to a particular problem domain such as security; however, security was the initial problem domain that provoked the creation of a higher-level WS-Policy grammar. Aside from security, WS-Policy can be used for reliable messaging, privacy, or quality-of-service characteristics. WS-Policy itself does not describe how a policy would be bound to a Web service; however, a separate specification called WS-PolicyAttachment ^[2] describes this use, and we will touch on this topic next .

^[1] See the WS-Policy specification at http://msdn.microsoft.com/ webservices /default.aspx?pull=/library/en-us/dnglobspec/html/ws-policy.asp.

^[2] See the WS-Policy Attachment specification at http://msdn.microsoft.com/webservices/default.aspx?pull=/library/en-us/dnglobspec/html/ws-policyattachment.asp.

To specify a policy in WS-Policy, you make assertions. A policy assertion describes some requirement that a Web service or client must adhere to. For example, the server might specify that a specific encryption algorithm must be used when encrypting messages bound for the service. Policy assertions are wrapped by a Policy element. Listing 8.1 shows an example of a Policy element from the WS-Policy specification.

Listing 8.1. A Sample <Policy> Element

 <wsp:Policy xmlns:wsp="..." xmlns:wsse="...">   <wsp:ExactlyOne>     <wsp:All wsp:Preference="100"/>       <wsse:SecurityToken TokenType="wsse:Kerberosv5TGT" />       <wsse:Algorithm Type="wsse:AlgSignature"         URI=" http://www.w3.org/2000/09/xmlenc#aes"/>     </wsp:All>     <wsp:All wsp:Preference="1"/>       <wsse:SecurityToken TokenType="wsse:X509v3" />       <wsse:Algorithm Type="wsse:AlgEncryption"                URI="http://www.w3.org/2001/04/xmlenc#3des-cbc"/>     </wsp:All>   </wsp:ExactlyOne> </wsp:Policy> 

Reading this policy is reasonably straightforward. The policy first has the ExactlyOne operator, which means that one of its direct child elements must be applicable. In this example, the ExactlyOne operator has two All operator children, so one of them must be applicable. An All operator means that all the assertions must be applicable. The first All specifies that the two assertions, a Kerberos token and an AES encryption algorithm, must be used. The second All specifies that an X.509 certificate and the 3DES encryption algorithm must be used. So this policy statement says you must have either a Kerberos v5 TGT token and use the AES algorithm to encrypt, or an X.509 token and use 3DES to encrypt.

Listing 8.2 shows a template of the usage syntax for a Policy statement.

Listing 8.2. The Template for the <Policy> Structure

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

An Assertion is a placeholder for the element the assertion is about (such as SecurityToken ). The two most interesting attributes here are Usage and Preference . Usage describes how the assertion is to be processed . It can have one of the following values:

• wsp:Required ” The assertion must be applied to the subject. If the subject does not meet the criteria expressed in the assertion, a fault or error will occur.

• wsp:Rejected ” The assertion is explicitly not supported and if present will cause failure.

• wsp:Optional ” The assertion may be made of the subject, but it is not required to be applied.

• wsp:Observed ” The assertion will be applied to all subjects, and requestors of the service are informed that the policy will be applied.

• wsp:Ignored ” The assertion is processed but ignored. That is, it can be specified, but no action will be taken as a result of its being specified. Subjects and requestors are informed that the policy will be ignored.

Preference is an optional attribute for specifying a ranking of alternatives. The higher the Preference number, the more the party expressing the preference would like that particular option used.

As you saw in Listing 8.2, a Policy can have one or more operators within it. The three valid operators are as follows :

• wsp:All ” All the child assertions must be satisfied.

• wsp:ExactlyOne ” Exactly one of the child assertions must be satisfied.

• wsp:OneOrMore ” One or more of the child assertions must be satisfied.

If no operator appears directly under the Policy element, all the child assertions must be satisfied, the same as the All operator specified previously.

The WS-Policy specification does not provide any specific types of assertions itself; it focuses on the syntax for declaring assertions. Specific sets of assertions are defined in other specifications for a specific domain (such as security). However, a set of general assertions is defined in the WS-PolicyAssertions specification.

WS-PolicyAssertions

The objective of WS-PolicyAssertions ^[3] is to define a set of common policy assertions that would be applicable across all Web services rather than just within a specific area such as security or reliable messaging. So far, only four of these general policy assertions are defined. The following short sections cover them with examples so that you can get a feel for how you might use policy assertions.

^[3] You can find the WS-PolicyAssertions specification at http://msdn.microsoft.com/webservices/default.aspx?pull=/library/en-us/dnglobspec/html/ws-policyassertions.asp.

TextEncoding

The TextEncoding assertion allows a Web service to specify one or more character sets that it supports. For example,

 <wsp:TextEncoding wsp:Usage="wsp:Required" Encoding="iso-8859-5"/> 

Language

A Web service can allow multiple languages to be used in the message content. The Language assertion allows a Web service to denote supported and preferred languages, as shown in Listing 8.3.

Listing 8.3. The <Language> Assertion

 <wsp:ExactlyOne>   <wsp:Language wsp:Usage="wsp:Required"                 wsp:Preference="10"                 Language="da"/>   <wsp:Language wsp:Usage="wsp:Required"                 wsp:Preference="7"                 Language="en-gb"/>   <wsp:Language wsp:Usage="wsp:Required"                 wsp:Preference="1"                 Language="en"/> </wsp:ExactlyOne> 

SpecVersion

As schemas and specifications evolve , they are revised, and Web services may support different versions of the same specification. For example, in some cases, the Web service is backward compatible; in other cases, it is not. Listing 8.4 shows an example of the SpecVersion assertion.

Listing 8.4. The <SpecVersion> Assertion

 <wsp:SpecVersion wsp:Usage="wsp:Required"      URI="http://schemas.xmlsoap.org/ws/2002/12/policy"/> 

MessagePredicate

The MessagePredicate assertion allows a Web service to specify that a message must have a particular precondition defined by an XPath (or perhaps some other dialect , but XPath 1.0 is the default). For example, perhaps a Web service requires a particular header. Listing 8.5 shows an example of a MessagePredicate assertion requiring that a message contain a security header.

Listing 8.5. The <MessagePredicate> Assertion

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

WS-PolicyAttachment

You have learned how a WS-Security policy can be put together using a set of assertions, but how do you now associate this policy with a particular Web service? The answer to this question is described in the WS-PolicyAttachment specification. ^[4] Two strategies are described for associating the policy. One strategy is to define the policy within the definition of the Web service ”for example, in the WSDL or pointed to from the WSDL. Another strategy is for the policy to stand alone and for it to point back to the Web service or services that it is associated with.

^[4] You can find the WS-PolicyAttachment specification at http://msdn.microsoft.com/webservices/default.aspx?pull=/library/en-us/dnglobspec/html/ws-policyattachment.asp.

Arbitrary Resource Attachment

The simplest policy attachment strategy to understand is the standalone approach, called Arbitrary Resource Attachment . This approach allows you to describe the policy and what resources it applies to separately from the definition of the resource itself. To accomplish this, you use the PolicyAttachment element with children of the AppliesTo element and a set of policy assertions. Using the AppliesTo element is a general way to describe resources that the policy applies to. Listing 8.6 shows an example from the specification that uses a domain expression pointing to a deployed WSDL endpoint.

Listing 8.6. The <PolicyAttachment> Assertion

 <wsp:PolicyAttachment>    <wsp:AppliesTo>         <wsp:EndpointReference xmlns:fabrikam="...">            <wsp:ServiceName Name="fabrikam:InventoryService"/>            <wsp:PortType Name="fabrikam:InventoryPortType"/>            <wsp:Address URI="http://www.fabrikam123.com/acct"/>         </wsp:EndpointReference>    </wsp:AppliesTo>    <wsp:PolicyReference Ref="http://www.fabrikam123.com/acct-policy.xml"/> </wsp:PolicyAttachment> 

In this example, the policy applies to the PortType titled InventoryPortType in the Web Service called InventoryService located at http://www.fabrikam123/acct . You can find the policy assertions at http://www.fabrikam123.com/acct-policy.xml .

Specifying WS-Policy in WSDL

Specifying policy in WSDL is somewhat more complex than the standalone approach and requires some understanding of WSDL because you can attach the policy at different locations in the WSDL and therefore have different meanings to the policy. For example, if you want to specify WS-SecurityPolicy for a specific Web service operation, you add an attribute to the specific WSDL operation element you want the policy or policies to apply to. Let's go through the different aspects of attaching a policy to WSDL.

You first need to know that WS-PolicyAttachment defines two attributes that can be used within WSDL to contain a list of pointers to policies that apply. These two attributes are PolicyURIs and PolicyRefs ; the only difference between the two is that the first points directly to a policy via URI, and the second makes use of QNames.

You can use one of these attributes within WSDL to point to one or more appropriate policies. The trick is to determine where in the WSDL to add these policy pointer attributes. To understand this concept, let's quickly review the structure of the definitions section in WSDL 1.1. Hierarchically, for an operation with a request and response, the part of the WSDL definitions section that we are interested in for this discussion is structured like Listing 8.7.

Listing 8.7. A WSDL <definitions> Section to Be Modified with WS-Policy Attributes

 <wsdl:definitions .... >     <message name=""> *         <part name="" element=""? type=""?/> *     </message>     <wsdl:portType .... > *         <wsdl:operation name=""            parameterOrder=" ">            <wsdl:input name=""? message=""/>            <wsdl:output name=""? message=""/>            <wsdl:fault name="" message=""/>*         </wsdl:operation>     </wsdl:portType > </wsdl:definitions> 

Policy that is attached higher in the hierarchy is inherited. So, for example, a policy attached to the message element would apply to each of the part elements. If the lower-level element has policy defined for it, the parent's attached policy is merged with the child's policy.

As you can see in the WSDL structure in Listing 8.7, two hierarchies are represented: the message/part hierarchy and the portType/operation/(input output fault) hierarchy. Listing 8.8 shows an example from the specification using the PolicyRef attribute on the message and part elements of the WSDL structure.

Listing 8.8. A WSDL <definitions> Structure with <PolicyRef> Attributes on the <message> and <part> Elements

 <?xml version="1.0"?> <wsdl:definitions name="Inventory"    xmlms:wsdl="http://schemas.xmlsoap.org/wsdl"    targetNamespace="http://example.com/inventory.wsdl"    ...    xmlns:ps="http://example.com/policies">  <wsp:UsingPolicy wsdl:Required="true"/>  <wsdl:message name="LookupResponse"  wsp:PolicyRefs="ps:Q1">  <wsdl:part name="key" type="xs:string"  wsp:PolicyRefs="ps:Q2"  />     <wsdl:part name="value" type="xs:string"  wsp:PolicyRefs="ps:Q3"  />     <wsdl:part name="hint" type="xs:string"  />   </wsdl:message> </wsdl:definitions> 

In Listing 8.8, first notice that a UsingPolicy element must be defined in the WSDL definitions section and must be marked as a mandatory extension ( wsdl:required = "true" ) to make sure that consumers of this service have the capability to process policies. The message LookupResponse points to the policy with the qualified name ps:Q1 (a policy in the namespace http://example.com/policies named Q1 ; see Listing 8.9). The first part element, key , points to the policy with the qualified name ps:Q2 ; and the second part element, value , points to the policy with the qualified name ps:Q3 . The third part element does not point to any policy explicitly. Listing 8.9 shows the three fictitious policies that ps:Q1 , ps:Q2 , and ps:Q3 refer to, respectively.

Listing 8.9. Three Fictitious Policies Referred to from the WSDL in Listing 8.8

 <wsp:Policy xmlns:wsp="..." xmlns:wsu="..." xmlns:xxx="..."     xml:base="http://www.fabrikam123.com/policies"     wsu:Id="P1"  Name="Q1"  TargetNamespace="http://example.com/policies">  <xxx:Sign wsp:Usage="wsp:Required" />  </wsp:Policy> <wsp:Policy xmlns:wsp="..." xmlns:wsu="..." xmlns:xxx="..."     xml:base="http://www.fabrikam123.com/policies"     wsu:Id="P2"  Name="Q2"  TargetNamespace="http://www.fabrikam123.com/policies">  <xxx:Encrypt wsp:Usage="wsp:Required" />  </wsp:Policy> <wsp:Policy xmlns:wsp="..." xmlns:wsu="..." xmlns:xxx="..."     xml:base="http://www.fabrikam123.com/policies"     wsu:Id="P3"  Name="Q3"  TargetNamespace="http://www.fabrikam123.com/policies">  <xxx:ExpeditedDelivery wsp:Usage="wsp:Required" />  </wsp:Policy> 

In Listing 8.9, because the Q1 policy is associated with the LookupResponse message from the WSDL, all three parts inherit the Sign policy (presumably meaning that the message must be digitally signed). The key message part from the WSDL explicitly points to the Q2 policy, so it would also have the Encrypt policy. Therefore, the effective policy for the key message part would be that shown in Listing 8.10.

Listing 8.10. The Effective Policy for the key message part of the Sample WSDL from Listing 8.8

 <wsp:Policy>   <xxx:Sign wsp:Usage="wsp:Required" />   <xxx:Encrypt wsp:Usage="wsp:Required" /> </wsp:Policy> 

Similarly, the value message part from the WSDL in Listing 8.8 points to Q2 , giving it the effective policy of Sign and ExpeditedDelivery . Because the hint message part from the same WSDL example does not point explicitly to a policy, it simply inherits from the LookupResponse message and has an effective policy of just Sign .

In Listing 8.10, we attached policies to the message and parts elements in WSDL, but we also could have attached policies to the portType , operation , input , output , or fault elements in WSDL. The same inheritance characteristics that were shown in the message example would apply.

WS-PolicyAttachment provides a tremendous amount of flexibility for assigning policies to different aspects of a Web service ”from the portType (which would apply to all the operations in a Web service), to an operation , or even to a specific input (request) and output (response).