Chapter 19. Managing Policies
Prev   Next
Links: Table of Contents | Single HTML | Single PDF

Chapter 19. Managing Policies

Table of Contents

19.1. Managing Policies
19.1.1. Introduction
19.1.2. Policy References
19.1.3. WSDL Import
19.1.4. External Policy References

19.1. Managing Policies

19.1.1. Introduction

The section WSIT Configuration and WS-Policy Assertions explained how WSIT functionality is configured using policies. If you are deploying a web service bundled with WSDL then all these policies are contained in the WSDL document. A web service that has no WSDL bundled will read the policies from a configuration file and then generate WSDL that contains these policies. This model works fine if you develop a few web services and do not want to share policies. NetBeans will generate the configuration with the policies for you and you do not need to be concerned with the details. Sometimes however, particularly in larger scale deployments, you will want to use the same policies for all web services or you might want to use an enterprise-wide policy. The following sections explain how to use externally defined policies.

19.1.2. Policy References

Policies are referenced using the XML element PolicyReference. Here is an example of a WSDL fragment that contains a policy and its reference:

Example 19.1. 

<?xml version="1.0" encoding="UTF-8"?>
<definitions
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                   oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:tns="http://service.test.policy.ws.xml.sun.com/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns="http://schemas.xmlsoap.org/wsdl/"
        targetNamespace="http://service.test.policy.ws.xml.sun.com/"
        name="TestServiceService">
   ...
   <wsp:Policy
           wsu:Id="TestServicePortBindingPolicy"
           xmlns:wsaws="http://www.w3.org/2005/08/addressing"
           xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsaws:UsingAddressing
               xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <wsrm:RMAssertion/>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
   ...
   <binding name="TestServicePortBinding" type="tns:TestService">
      <wsp:PolicyReference URI="#TestServicePortBindingPolicy"/>
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
      <operation name="echo">
         <soap:operation soapAction=""/>
         <input>
            <soap:body use="literal"/>
         </input>
         <output>
            <soap:body use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>


Above you see one policy defined with the id TestServicePortBindingPolicy. This policy is referenced by the PolicyReference element in the WSDL binding section. You can see here that the policy reference #TestServicePortBindingPolicy is relative as signified by the leading # character. This is telling the policy processor that it is to look for this policy only in the enclosing document.

An alternative to WS-Policy identifiers and relative references are WS-Policy Names. A Name is an absolute URI that can be resolved across document boundaries. Here is an example of a WSDL fragment that contains a policy identified by a Name and the corresponding PolicyReference:

Example 19.2. 

<?xml version="1.0" encoding="UTF-8"?>
<definitions
        xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                   oasis-200401-wss-wssecurity-utility-1.0.xsd"
        xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        xmlns:tns="http://service.test.policy.ws.xml.sun.com/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
        xmlns="http://schemas.xmlsoap.org/wsdl/"
        targetNamespace="http://service.test.policy.ws.xml.sun.com/"
        name="TestServiceService">
   ...
   <wsp:Policy
           Name="http://service.test.policy.ws.xml.sun.com/
                 TestServicePortBindingPolicy"
           xmlns:wsaws="http://www.w3.org/2005/08/addressing"
           xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsaws:UsingAddressing
               xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <wsrm:RMAssertion/>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>
   ...
   <binding name="TestServicePortBinding" type="tns:TestService">
      <wsp:PolicyReference
              URI="http://service.test.policy.ws.xml.sun.com/
                   TestServicePortBindingPolicy"/>
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
      <operation name="echo">
         <soap:operation soapAction=""/>
         <input>
            <soap:body use="literal"/>
         </input>
         <output>
            <soap:body use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>


The mechanism of using a PolicyReference element to reference a policy is defined in WS-Policy. The PolicyReference element in the above examples is a direct child element of the WSDL binding element. That effectively means that we attached the policy with id TestServicePortBindingPolicy to this particular WSDL binding element. In theory, policies could be attached to any WSDL element using that technique. In practice however, policies may only be attached to a few select elements, depending on the policy assertions that the policy contains. In the example above we have one addressing and one reliable messaging assertion. Both may only be attached to WSDL port and WSDL binding elements.

19.1.3. WSDL Import

The WSDL import statement lets us to manage policies in one central document and refer to these policies from any other WSDL document. The policies contained in a separate WSDL document are best identified using the WS-Policy Name attribute because that allows to reference these policies by an absolute URI that does not depend on the location of the imported WSDL document. Here is an example of how this may look.

Example 19.3. policies.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:tns="http://policies.test.policy.ws.xml.sun.com/"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://policies.test.policy.ws.xml.sun.com/"
             name="Policies">

   <wsp:Policy
           Name="http://policies.test.policy.ws.xml.sun.com/
                 ReliableMessagingPolicy"
           xmlns:wsaws="http://www.w3.org/2005/08/addressing"
           xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsaws:UsingAddressing
               xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <wsrm:RMAssertion/>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>

   <wsp:Policy
        Name="http://policies.test.policy.ws.xml.sun.com/SecurePolicy"
        xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsaws:UsingAddressing
               xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <sp:SymmetricBinding>
               <wsp:Policy>
                  <sp:ProtectionToken>
                     <wsp:Policy>
                        <sp:X509Token
                            sp:IncludeToken="http://schemas.xmlsoap.org/
                            ws/2005/07/securitypolicy/IncludeToken/Never">
                           <wsp:Policy>
                              <sp:WssX509V3Token10/>
                           </wsp:Policy>
                        </sp:X509Token>
                     </wsp:Policy>
                  </sp:ProtectionToken>
                  <sp:Layout>
                     <wsp:Policy>
                        <sp:Strict/>
                     </wsp:Policy>
                  </sp:Layout>
                  <sp:IncludeTimestamp/>
                  <sp:OnlySignEntireHeadersAndBody/>
                  <sp:AlgorithmSuite>
                     <wsp:Policy>
                        <sp:Basic128/>
                     </wsp:Policy>
                  </sp:AlgorithmSuite>
               </wsp:Policy>
            </sp:SymmetricBinding>
            <sp:Wss11>
               <wsp:Policy>
                  <sp:MustSupportRefKeyIdentifier/>
                  <sp:MustSupportRefIssuerSerial/>
                  <sp:MustSupportRefThumbprint/>
                  <sp:MustSupportRefEncryptedKey/>
               </wsp:Policy>
            </sp:Wss11>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>

</definitions>


Example 19.4. reliable-service.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="http://reliable.service.test.policy.ws.xml.sun.com/"
             targetNamespace="http://reliable.service.test.policy.ws.xml.sun.com/"
             name="ReliableService">
   ...
   <import namespace="http://reliable.service.test.policy.ws.xml.sun.com/"
           location=".../policies.wsdl"/>
   ...
   <binding name="ReliableServicePortBinding"
            type="tns:ReliableService">
      <wsp:PolicyReference
              URI="http://policies.test.policy.ws.xml.sun.com/
                   ReliableMessagingPolicy"/>
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
      <operation name="echo">
         <soap:operation soapAction=""/>
         <input>
            <soap:body use="literal"/>
         </input>
         <output>
            <soap:body use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>


Example 19.5. secure-service.wsdl

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             xmlns:tns="http://secure.service.test.policy.ws.xml.sun.com/"
             targetNamespace="http://secure.service.test.policy.ws.xml.sun.com/"
             name="SecureService">
   ...
   <import namespace="http://secure.service.test.policy.ws.xml.sun.com/"
           location=".../policies.wsdl"/>
   ...
   <binding name="SecureServicePortBinding" type="tns:SecureService">
      <wsp:PolicyReference
              URI="http://policies.test.policy.ws.xml.sun.com/SecurePolicy"/>
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
      <operation name="echo">
         <soap:operation soapAction=""/>
         <input>
            <soap:body use="literal"/>
         </input>
         <output>
            <soap:body use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>


19.1.4. External Policy References

Since the PolicyReference is a URI, it comes natural to use an absolute URI instead of a relative URI. This is exactly how you would attach an external policy, i.e. a policy that is not contained in the same document as the PolicyReference. You still need to reference the policy ID by attaching it to the URI of the document. Here is an example of a file that contains the same policy as the one that was inside the WSDL document previously:

Example 19.6. 

<wsp:Policy wsu:Id="TestServicePortBindingPolicy"
            xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                       oasis-200401-wss-wssecurity-utility-1.0.xsd"
            xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
            xmlns:wsaws="http://www.w3.org/2005/08/addressing"
            xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">
   <wsp:ExactlyOne>
      <wsp:All>
         <wsaws:UsingAddressing
                 xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
         <wsrm:RMAssertion/>
      </wsp:All>
   </wsp:ExactlyOne>
</wsp:Policy>


Let's assume the document above can be retrieved from the URI http://example.test/policy. You could now write a WSDL document like this:

Example 19.7. 

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns:tns="http://service.test.policy.ws.xml.sun.com/"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
             xmlns="http://schemas.xmlsoap.org/wsdl/"
             targetNamespace="http://service.test.policy.ws.xml.sun.com/"
             name="TestServiceService">
   ...
   <binding name="TestServicePortBinding" type="tns:TestService">
      <wsp:PolicyReference
              URI="http://example.test/policy#TestServicePortBindingPolicy"/>
      <soap:binding transport="http://schemas.xmlsoap.org/soap/http"
                    style="document"/>
      <operation name="echo">
         <soap:operation soapAction=""/>
         <input>
            <soap:body use="literal"/>
         </input>
         <output>
            <soap:body use="literal"/>
         </output>
      </operation>
   </binding>
   ...
</definitions>


Note that the PolicyReference above uses an absolute URI. It references the document URI appended with the # character and the ID of the policy. The fact that you need to state the particular ID allows to contain multiple policies inside one document and reference single policies out of that document. Here is an example of a document with more than one policy:

Example 19.8. 

<?xml version="1.0" encoding="UTF-8"?>
<policies xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
          xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
                     oasis-200401-wss-wssecurity-utility-1.0.xsd"
          xmlns:wsoma="http://schemas.xmlsoap.org/ws/2004/09/policy/
                       optimizedmimeserialization"
          xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"
          xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy">

   <wsp:Policy wsu:Id="GlobalRMPolicy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsaws:UsingAddressing
                    xmlns:wsaws="http://www.w3.org/2006/05/addressing/wsdl"/>
            <wsrm:RMAssertion/>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>

   <wsp:Policy wsu:Id="GlobalMtomPolicy">
      <wsp:ExactlyOne>
         <wsp:All>
            <wsoma:OptimizedMimeSerialization/>
         </wsp:All>
      </wsp:ExactlyOne>
   </wsp:Policy>

</policies>


The policies are contained by a policies element so that this document is valid XML. This root element may actually have any name. Assuming that this document has the absolute URI http://example.test/policies, you can now create references for both policies: <PolicyReference URI="http://example.test/policies#GlobalRMPolicy"/> and <PolicyReference URI="http://example.test/policies#GlobalMtomPolicy"/>.

Note that unlike the approach discussed in section WSDL Import, external policy references may not be interoperable with other products.

Prev   Next
Chapter 18. Using Atomic Transactions Home Chapter 20. Monitoring and Management