- From: Asir Vedamuthu via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 18 Jul 2007 10:13:19 +0000
- To: public-ws-policy-eds@w3.org
Update of /sources/public/2006/ws/policy In directory hutz:/tmp/cvs-serv2245 Modified Files: ws-policy-guidelines.html ws-policy-guidelines.xml Log Message: Implemented the resolution for issue 3988. Editors' action: 338, drop Section 7 Scenario and a worked example Implemented the resolution for issue 3978. Editors' action: 339, drop Section 6 Applying Best Practices for Policy Attachment Index: ws-policy-guidelines.html =================================================================== RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.html,v retrieving revision 1.83 retrieving revision 1.84 diff -u -d -r1.83 -r1.84 --- ws-policy-guidelines.html 17 Jul 2007 15:49:41 -0000 1.83 +++ ws-policy-guidelines.html 18 Jul 2007 10:13:16 -0000 1.84 @@ -147,12 +147,6 @@ 6.1 <a href="#Referencing_Policy_Expressions">Referencing Policy Expressions</a><br> 6.2 <a href="#extending-assertions"> Evolution of Assertions (Versioning and Compatibility)</a><br> 6.3 <a href="#supporting-new-policy-subjects">Supporting New Policy Subjects</a><br> -7. <a href="#best-practices-attachment">Applying Best Practices for Policy Attachment</a><br> - 7.1 <a href="#context-free-policies">Appropriate Attachment: Preserving Context-Free Policies</a><br> - 7.2 <a href="#appropriate-attachment-assertion-subjects">Appropriate Attachment: Identifying Assertion Subjects</a><br> - 7.2.1 <a href="#interaction">Interaction between Subjects</a><br> - 7.3 <a href="#identifying-assertion-sources">Appropriate Attachment: Identifying Assertion Sources </a><br> -8. <a href="#scenario">Scenario and a worked example</a><br> </p> <h3><a name="appendices" id="appendices"></a>Appendices</h3><p class="toc">A. <a href="#security-considerations">Security Considerations</a><br> B. <a href="#xml-namespaces">XML Namespaces</a><br> @@ -208,9 +202,9 @@ the question. </p></div><div class="div1"> <h2><a name="best-practices-list" id="best-practices-list"></a>2. List of Best Practice Statements</h2><p>The following Best Practices appear in this document with discussion and examples, and are summarized here for quick reference:</p><ul><li><p><a href="#bp-assertion-semantics"><b>1. Semantics Independent of - Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>6. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a></p></li><li><p><a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable -Attribute in XML </b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>11. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>12. Use Parameters for Useful - Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>13. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>14. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>15. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Use the wsp:Optional attribute to indicate optional</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p>a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li><li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Use Independent Assertions for Different Versions of a Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>28. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1"> + Attachment Mechanisms</b></a></p></li><li><p><a href="#bp-compatibility-tests"><b>2. Behaviors Relevant to Compatibility Tests</b></a></p></li><li><p><a href="#bp-semantics-and-form"><b>3. Semantics Independent of the Form</b></a></p></li><li><p><a href="#bp-assertion-start"><b>4. Start with a Simple Assertion</b></a></p></li><li><p><a href="#bp-unique-qnames"><b>5. Use Unique QNames</b></a></p></li><li><p><a href="#XMLOutline"><b>6. Provide an XML Outline</b></a></p></li><li><p><a href="#AssertionDefinitions"><b>7. Specify Semantics Clearly</b></a></p></li><li><p><a href="#bp-not-necessary-to-understand-a-message"><b>10. Not Necessary to Understand a Message</b></a></p></li><li><p><a href="#bp-assertion-duplication"><b>11. Avoid Duplication of Assertions</b></a></p></li><li><p><a href="#bp-assertion-parameters"><b>12. Use Parameters for Useful + Information</b></a></p></li><li><p><a href="#bp-dependent-behaviors"><b>13. Use Nested Assertions for Dependent Behaviors</b></a></p></li><li><p><a href="#bp-declare-nested-assertions"><b>14. Enumerate Nested Assertions</b></a></p></li><li><p><a href="#bp-discourage-domain-specific-intersection"><b>15. Discourage Domain Specific Intersection</b></a></p></li><li><p><a href="#DefineIgnorable"><b>8. Assertion Authors Should Document Ignorable Behavior</b></a></p></li><li><p><a href="#ignorableAssertions"><b>9. Assertion Authors Should Document Use of the Ignorable +Attribute in XML </b></a></p></li><li><p><a href="#bp-assertion-xml-allow-optional"><b>16. Assertion XML should allow use of wsp:Optional attribute</b></a></p></li><li><p><a href="#bp-assertion-description-explicitly-allow-optional"><b>17. Use the wsp:Optional attribute to indicate optional</b></a></p></li><li><p><a href="#bp-limit-optional-assertions"><b>18. Limit use of Optional Assertions</b></a></p></li><li><p><a href="#bp-entire-mep-for-optional"><b>19. Consider entire message exchange pattern when specifying Assertions that may be optional</b></a></p></li><li><p><a href="#bp-indicate-optional-assertion-use"><b>20. Indicate use of an Optional Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject"><b>21. Specify Policy Subject(s)</b></a></p></li><li><p><a href="#bp-WSDL-policy-subject-Granularity"><b>22. Choose the Most Granular Policy Subject</b></a></p></li><li><p><a href="#bp-WSDL-multiple-policy-subjects"><b>23. Define Semantics of Attachment to Multiple Policy Subjects</b></a></p></li<li><p><a href="#bp-WSDL-preferred-attachment-point"><b>24. Specify Preferred Attachment Point for an Assertion</b></a></p></li><li><p><a href="#bp-WSDL-policy-multiple-instance-semantics"><b>25. Describe Semantics of Multiple Assertions of Same Type</b></a></p></li><li><p><a href="#bp-specify-composition"><b>26. Specify Composition with Related Assertions</b></a></p></li><li><p><a href="#bp-independent-assertions"><b>27. Use Independent Assertions for Different Versions of a Behavior</b></a></p></li><li><p><a href="#bp-policy-subject-change"><b>28. Change of the Policy Subject Over Time</b></a></p></li></ul></div><div class="div1"> <h2><a name="Assertions" id="Assertions"></a>3. What is an Assertion? </h2><p>An assertion is a piece of metadata that describes a capability related to a specific WS-Policy domain. Sets of domain-specific assertions are typically defined in a dedicated specification that describes @@ -1130,225 +1124,7 @@ </p><div class="boxedtext"><p><a name="bp-policy-subject-change" id="bp-policy-subject-change"></a><span class="practicelab">Best Practice 28: Change of the Policy Subject Over Time</span></p><p class="practice">If the policy subjects change over time, the assertion description should also be versioned to reflect this - change.</p></div></div></div><div class="div1"> -<h2><a name="best-practices-attachment" id="best-practices-attachment"></a>7. Applying Best Practices for Policy Attachment</h2><div class="div2"> -<h3><a name="context-free-policies" id="context-free-policies"></a>7.1 Appropriate Attachment: Preserving Context-Free Policies</h3><p>Policy attachment should not affect the interpretation of - Policy alternatives. If it did, each policy assertion would - need to be written with different (and possibly unknown) - attachment mechanisms in mind. </p></div><div class="div2"> -<h3><a name="appropriate-attachment-assertion-subjects" id="appropriate-attachment-assertion-subjects"></a>7.2 Appropriate Attachment: Identifying Assertion Subjects</h3><p>Each policy attachment mechanism should unambiguously - identify the subject of the attached assertions. Generally, - this should be a specific SOAP node or a specific message - between two SOAP nodes. Some attachment mechanisms may - encompass multiple notes or messages, for example, "the - message along its entire path". </p><div class="div3"> -<h4><a name="interaction" id="interaction"></a>7.2.1 Interaction between Subjects</h4><p>If the best practices are followed, and the assertions - are scoped according to their subject, then multiple policy - domains may be combined without conflict. Each domain - should define any limitations at the policy subject level - that might impact interoperability (i.e. WS-SecurityPolicy - - binding abstraction to group capabilities per message - exchange). </p></div></div><div class="div2"> -<h3><a name="identifying-assertion-sources" id="identifying-assertion-sources"></a>7.3 Appropriate Attachment: Identifying Assertion Sources </h3><p>As with identifying Policy subjects, policy attachment - mechanisms should make it possible to clearly identify the - source of a policy assertion both for debugging and for - verification. This could take several forms: it could be - assumed (in WSDL, the source of the assertion is the same - as the WSDL provider) or it could be proven (using - <cite><a href="#WS-Trust">WS-Trust</a></cite>). </p></div></div><div class="div1"> -<h2><a name="scenario" id="scenario"></a>8. Scenario and a worked example</h2><p>To illustrate the topics explored in this document, we - include an example of a web service and how a fictitious company - might utilize the WS-Policy Framework to enable Web Service - interoperability. Company A has determined to utilize WS-Security, - WS-Addressing and WS-Reliable Messaging in all its new web - service offerings and has instructed its developers to use the - policy assertions defined by the following documents: </p><ul><li><p>Web Services Security Policy </p></li><li><p>Web Services Reliable Messaging Policy </p></li><li><p>Web Services Addressing WSDL Binding</p></li></ul><p>The application developers at Company A are instructed to - review the current web services at Company A and propose a plan - for adding policy assertions. </p><p>The application developers collect information about web - services within Company A and determine that all of the web - services already have a WSDL 1.1 description. The developers - have determined that Company A's web services fall into two - types of web services. There are those that fall into the - "default" category, and will use a predefined set of policy - assertions, and there are those that use the default but also - extend the policy alternatives. </p><p>They have also determined that for the both types, the - appropriate policy subject is the endpoint. They determined - this because the capabilities apply to all operations and - messages for the web service not to any one individual operation - or message exchange. </p><p>Service A is a WSDL 1.1 conformant web service and requires - the use of transport-level security for protecting messages as - well as including addressing headers. Employees of Company A have - already incorporated <code>wss:Security</code> headers into their - messages. </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-1. </span>Message with Security Headers</i></p><div class="exampleInner"><pre><soap:Envelope> - <soap:Header> - <wss:Security soap:mustUnderstand ="1"> - <wsu:Timestamp wsu:Id=_0"> - <wsu:Created> 20006-01-19T02:49:53.914Z </u:Created> - <wsu:Expires> 20006-01-19T02:54:53.914Z </u:Expires> - </wsu:Timestamp> - </wss:Security> - <wsa:To> http://CompanyA/quote <wsa:To> - <wsa:Action> http://CompanyA/GetRealQuote</wsa:Action> - </soap:Header> - <soap:Body> ... -</soap:Envelope></pre></div></div><p>The SOAP message in the example above includes security - timestamps that express creation and expiration times of this - message. Company A requires the use of these security timestamps - and transport-level security, such as HTTPS for protecting - messages. </p><p>The example below illustrates a policy expression that - CompanyA has created for its employees to use on their web - services to indicate the use of addressing and transport-level - security for securing messages. </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-2. </span> CompanyA-ProfileA </i></p><div class="exampleInner"><pre> -<Policy URI=http://www.CompanyA.com/WebServicesProfileA.xml> - <wsam:Addressing>…</wsam:Addressing> - <sp:TransportBinding></sp:TransportBinding> -</Policy></pre></div></div><p>The <code>sp:TransportBinding</code> element is a policy assertion. The - assertion identifies the use of transport-level-security - such - as HTTPS for protecting messages at the transport - level. Company A's policy aware clients can now recognize this - policy assertion and if they support it, engage in transport - level security for protecting messages and providing security - timestamps in SOAP envelopes for any WSDL with this policy - attached. </p><p>When creating the policy for the default web services, the - developers took into consideration several factors. First, all - their web services were WSDL 1.1 web services. Second, they - wanted to reuse policy assertions where ever possible. Third, - they wanted to ensure that where possible they would support - alternatives rather than forcing a single client - configuration. </p><p>The developers read the WS-Policy specification and noted that - there were three ways to express combinations of behaviors. The three - policy operators, (Policy, All and ExactlyOne) were considered - and the result was the creation of two policy elements. </p><p>The first policy is shown in Figure - <em>CompanyA-ProfileA</em> and it is the policy that is used - by many web services at Company A that rely on HTTPS to provide - transport level protection of messages. </p><p>The second policy is shown in Figure - <em>CompanyA-ProfileB</em> and it offers requesters of a - service the ability to provide additional integrity protection by - including WS-Security Headers to protect the message content - after it is processed by the transport. The additional security - processing is not required by all Company A web services. </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-3. </span>CompanyA-ProfileB (not expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding></sp:TransportBinding> - <sp:AsymmetricBinding></sp:AssymetricBinding> - </ExactlyOne> -</Policy></pre></div></div><p>We have shown above that Company A offered a - second profile that included two security options. The details of - the Bindings, requires a more detailed exploration of some of the - other features of the WS-Policy Framework. </p><p>When Assertion Authors create sets of Policy assertions, like - WS-Security Policy they need to consider expressing the semantics - of their domain in a way that policy consumers, like Company A, - can utilize them. In this case, the WS-SecurityPolicy Assertion Authors - factored out common elements of security mechanisms and utilized a - feature of WS-Policy called "nested" assertions. In the case of - an <code>sp:TransportBinding</code> assertion, just indicating the use of - transport-level security for protecting messages is not - sufficient. For a consumer of a web service provided by a company, - like Company A, to successfully interact, the consumer must also - know what transport token, what algorithm suite, etc. is - required. The <code>sp:TransportBinding</code> assertion, can (and has) - represent (ed) these dependent behaviors as "nested" policy - assertions. </p><p>In the example below the child Policy element is a nested - policy behavior and further qualifies the behavior of the - <code>sp:TransportBinding</code> policy assertion. </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-4. </span>CompanyA-ProfileB (fully expanded)</i></p><div class="exampleInner"><pre><Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding> - <Policy> - <sp:TransportToken> - <Policy> - <sp:HttpsToken> - <wsp:Policy/> - </sp:HttpsToken> - </Policy> - </sp:TransportToken> - <sp:AlgorithmSuite> - <Policy> - <sp:Basic256Rsa15 /> - </Policy> - </sp:AlgorithmSuite> - </Policy> - </sp:TransportBinding> - <sp:AsymmetricBinding> - </sp:AssymetricBinding> - </ExactlyOne> -</Policy></pre></div></div><p> - <code>The sp:AlgorithmSuite</code> is a nested policy - assertion of the <code>sp:TransportBinding</code> assertion and - indicates that this suite is required. The - <code>sp:TransportToken</code> is a nested policy assertion that - indicates the use of a specific type of token, in this case an - HttpsToken. </p><p>It should be noted that each policy has an Identifier. In the - case of the default policy expression, Company A has decided that - this policy expression should be broadly available via a URI. - There are advantages and disadvantages to using each type of - identifier. For URI's there is the issue of maintaining the - policy expression when it may no longer be used (Company A gets - bought by Company B and starts using the policies of Company B, - but some "old" consumers may still try to reference the - URI). </p><p> For the second type of web services, which may be used only - by certain of Company A's business partners, the id is an XML ID. - The relative URI for referencing this within the same WSDL - document is #CompanyA-ProfileB. This can be useful for company's - when the policy expressions are agreed to between partners but - may be changed as the business agreements change. But the - disadvantage is that the policy expression must be included in - each WSDL document. </p><p>Since Company A has decided to use well known policy - expressions that are part of a specification, they - adhere to the guidance given in the WS-SecurityPolicy - specification and attach the policies to the web service endpoint - policy subject as recommended by the WS-SecurityPolicy - specification. For the default web services, the URI is included - in the wsdl binding for each web service. </p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-5. </span></i></p><div class="exampleInner"><pre><wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault"> - <wsp:PolicyReference URI="http://www.CompanyA.com/WebServicesProfileA.xml"> - <wsdl:operation name="GetQuote"> </wsdl:operation> -</wsdl:binding></pre></div></div><p>The partner specified policy is included in the beginning of - the WSDL 1.1 document and referenced by the binding for the service - as in the example below.</p><div class="exampleOuter"> -<p style="text-align: left" class="exampleHead"><i><span>Example 8-6. </span></i></p><div class="exampleInner"><pre> -<wsdl:definitions name="StockQuote" - targetNamespace="http:.."> -<wsp:Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding> - <Policy> - <sp:TransportToken> - <wsp:Policy> - <sp:HttpsToken> - <wsp:Policy/> - </sp:HttpsToken> - </wsp:Policy> - </sp:TransportToken> - <sp:AlgorithmSuite> - <wsp:Policy> - <sp:Basic256Rsa15 /> - </wsp:Policy> - </spAlgorithmSuite> - </Policy> - </sp:TransportBinding> - <sp:AsymmetricBinding> - </sp:AssymetricBinding> - </ExactlyOne> -</wsp:Policy> - -<wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault"> - <wsp:PolicyReference id=#CompanyA-ProfileB> - <wsdl:operation name="GetQuote"> </wsdl:operation> -</wsdl:binding></pre></div></div><p>In some cases, companies may chose to implement their own - assertions. When companies chose to become Assertion Authors they need - to consider not only the definition of the behavior that the - assertion represents but they need to consider how new assertions - will be intersected and merged with other assertions in the - calculation of an effective policy and this also indicates they need - to consider policy subjects.</p><p> The WS-Policy 1.5 - Attachment specification defines algorithms for calculating the - effective policy for a given policy subject and effective policies for - WSDL 1.1, WSDL 2.0 and UDDI policy subjects.</p></div></div><div class="back"><div class="div1"> + change.</p></div></div></div></div><div class="back"><div class="div1"> <h2><a name="security-considerations" id="security-considerations"></a>A. Security Considerations</h2><p> Security considerations are discussed in the <cite><a href="#WS-Policy">Web Services Policy Framework</a></cite> document.</p></div><div class="div1"> <h2><a name="xml-namespaces" id="xml-namespaces"></a>B. XML Namespaces</h2><p>The table below lists XML Namespaces that are used in this document. The choice of any namespace prefix is arbitrary and not semantically significant.</p><a name="nsprefix"></a><table summary="Prefixes and XML Namespaces used in this specification" border="1" cellspacing="0" cellpadding="5"><caption>Table B-1. Prefixes and XML Namespaces used in this specification.</caption><thead><tr><th rowspan="1" colspan="1">Prefix</th><th rowspan="1" colspan="1">XML Namespace</th><th rowspan="1" colspan="1">Specifications</th></tr></thead><tbody><tr><td rowspan="1" colspan="1"> @@ -1536,7 +1312,7 @@ <a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0129.html">Part 1</a> and <a href="http://lists.w3.org/Archives/Public/public-ws-policy-eds/2006Nov/0134.html">Part 2</a>. </td></tr><tr><td rowspan="1" colspan="1">20061129</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Formatted examples in <a href="#extending-assertions"><b>6.2 Evolution of Assertions (Versioning and Compatibility)</b></a>. - </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and <a href="#scenario"><b>8. Scenario and a worked example</b></a>. + </td></tr><tr><td rowspan="1" colspan="1">20061218</td><td rowspan="1" colspan="1">FS</td><td rowspan="1" colspan="1">Formatted examples in <a href="#compact-full"><b>5.2 Authoring Styles </b></a> and . </td></tr><tr><td rowspan="1" colspan="1">20061219</td><td rowspan="1" colspan="1">TIB</td><td rowspan="1" colspan="1">Editorial revision: most parts of editorial action <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/96">96</a>. Remaining editorials to be reviewed. @@ -1747,4 +1523,14 @@ <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/332">332</a>. </td></tr><tr><td rowspan="1" colspan="1">20070717</td><td rowspan="1" colspan="1">DBO</td><td rowspan="1" colspan="1">Implemented partial resolution, section 5.5 updates, for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4662">4662</a>, Editors' action - <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/332">332</a> #2.</td></tr></tbody></table><br></div></div></body></html> \ No newline at end of file + <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/332">332</a> #2.</td></tr><tr><td rowspan="1" colspan="1">20070718</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the resolution + for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3988</a>. + Editors' action: + <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/338">338</a>, + drop <a href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#scenario">Section + 7 Scenario and a worked example</a></td></tr><tr><td rowspan="1" colspan="1">20070718</td><td rowspan="1" colspan="1">ASV</td><td rowspan="1" colspan="1">Implemented the resolution + for issue <a href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3978</a>. + Editors' action: + <a href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/339">339</a>, + drop <a href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#best-practices-attachment">Section + 6 Applying Best Practices for Policy Attachment</a></td></tr></tbody></table><br></div></div></body></html> \ No newline at end of file Index: ws-policy-guidelines.xml =================================================================== RCS file: /sources/public/2006/ws/policy/ws-policy-guidelines.xml,v retrieving revision 1.98 retrieving revision 1.99 diff -u -d -r1.98 -r1.99 --- ws-policy-guidelines.xml 17 Jul 2007 15:46:49 -0000 1.98 +++ ws-policy-guidelines.xml 18 Jul 2007 10:13:16 -0000 1.99 @@ -1525,290 +1525,6 @@ </div2> </div1> - <div1 id="best-practices-attachment"> - <head>Applying Best Practices for Policy Attachment</head> - <div2 id="context-free-policies"> - <head>Appropriate Attachment: Preserving Context-Free Policies</head> - <p>Policy attachment should not affect the interpretation of - Policy alternatives. If it did, each policy assertion would - need to be written with different (and possibly unknown) - attachment mechanisms in mind. </p> - <!-- EDS TO DO: [CLARIFY SUBJECT RELATIONSHIP] in the paragraph above --> - </div2> - <div2 id="appropriate-attachment-assertion-subjects"> - <head>Appropriate Attachment: Identifying Assertion Subjects</head> - <p>Each policy attachment mechanism should unambiguously - identify the subject of the attached assertions. Generally, - this should be a specific SOAP node or a specific message - between two SOAP nodes. Some attachment mechanisms may - encompass multiple notes or messages, for example, "the - message along its entire path". </p> - <div3 id="interaction"> - <head>Interaction between Subjects</head> - <p>If the best practices are followed, and the assertions - are scoped according to their subject, then multiple policy - domains may be combined without conflict. Each domain - should define any limitations at the policy subject level - that might impact interoperability (i.e. WS-SecurityPolicy - - binding abstraction to group capabilities per message - exchange). </p> - </div3> - </div2> - <div2 id="identifying-assertion-sources"> - <head>Appropriate Attachment: Identifying Assertion Sources </head> - <p>As with identifying Policy subjects, policy attachment - mechanisms should make it possible to clearly identify the - source of a policy assertion both for debugging and for - verification. This could take several forms: it could be - assumed (in WSDL, the source of the assertion is the same - as the WSDL provider) or it could be proven (using - <bibref ref="WS-Trust"/>). </p> - </div2> - </div1> - <div1 id="scenario"> - <head>Scenario and a worked example</head> - <p>To illustrate the topics explored in this document, we - include an example of a web service and how a fictitious company - might utilize the WS-Policy Framework to enable Web Service - interoperability. Company A has determined to utilize WS-Security, - WS-Addressing and WS-Reliable Messaging in all its new web - service offerings and has instructed its developers to use the - policy assertions defined by the following documents: </p> - <ulist> - <item> - <p>Web Services Security Policy </p> - </item> - <item> - <p>Web Services Reliable Messaging Policy </p> - </item> - <item> - <p>Web Services Addressing WSDL Binding</p> - </item> - </ulist> - <p>The application developers at Company A are instructed to - review the current web services at Company A and propose a plan - for adding policy assertions. </p> - <p>The application developers collect information about web - services within Company A and determine that all of the web - services already have a WSDL 1.1 description. The developers - have determined that Company A's web services fall into two - types of web services. There are those that fall into the - "default" category, and will use a predefined set of policy - assertions, and there are those that use the default but also - extend the policy alternatives. </p> - <p>They have also determined that for the both types, the - appropriate policy subject is the endpoint. They determined - this because the capabilities apply to all operations and - messages for the web service not to any one individual operation - or message exchange. </p> - <p>Service A is a WSDL 1.1 conformant web service and requires - the use of transport-level security for protecting messages as - well as including addressing headers. Employees of Company A have - already incorporated <code>wss:Security</code> headers into their - messages. </p> - <example> - <head>Message with Security Headers</head> - <eg xml:space="preserve"><soap:Envelope> - <soap:Header> - <wss:Security soap:mustUnderstand ="1"> - <wsu:Timestamp wsu:Id=_0"> - <wsu:Created> 20006-01-19T02:49:53.914Z </u:Created> - <wsu:Expires> 20006-01-19T02:54:53.914Z </u:Expires> - </wsu:Timestamp> - </wss:Security> - <wsa:To> http://CompanyA/quote <wsa:To> - <wsa:Action> http://CompanyA/GetRealQuote</wsa:Action> - </soap:Header> - <soap:Body> ... -</soap:Envelope></eg> - </example> - <p>The SOAP message in the example above includes security - timestamps that express creation and expiration times of this - message. Company A requires the use of these security timestamps - and transport-level security, such as HTTPS for protecting - messages. </p> - <p>The example below illustrates a policy expression that - CompanyA has created for its employees to use on their web - services to indicate the use of addressing and transport-level - security for securing messages. </p> - <example> - <head> CompanyA-ProfileA </head> - <eg xml:space="preserve"> -<Policy URI=http://www.CompanyA.com/WebServicesProfileA.xml> - <wsam:Addressing>…</wsam:Addressing> - <sp:TransportBinding></sp:TransportBinding> -</Policy></eg> - </example> - <p>The <code>sp:TransportBinding</code> element is a policy assertion. The - assertion identifies the use of transport-level-security - such - as HTTPS for protecting messages at the transport - level. Company A's policy aware clients can now recognize this - policy assertion and if they support it, engage in transport - level security for protecting messages and providing security - timestamps in SOAP envelopes for any WSDL with this policy - attached. </p> - <p>When creating the policy for the default web services, the - developers took into consideration several factors. First, all - their web services were WSDL 1.1 web services. Second, they - wanted to reuse policy assertions where ever possible. Third, - they wanted to ensure that where possible they would support - alternatives rather than forcing a single client - configuration. </p> - <p>The developers read the WS-Policy specification and noted that - there were three ways to express combinations of behaviors. The three - policy operators, (Policy, All and ExactlyOne) were considered - and the result was the creation of two policy elements. </p> - <p>The first policy is shown in Figure - <emph>CompanyA-ProfileA</emph> and it is the policy that is used - by many web services at Company A that rely on HTTPS to provide - transport level protection of messages. </p> - <p>The second policy is shown in Figure - <emph>CompanyA-ProfileB</emph> and it offers requesters of a - service the ability to provide additional integrity protection by - including WS-Security Headers to protect the message content - after it is processed by the transport. The additional security - processing is not required by all Company A web services. </p> - <example> <head>CompanyA-ProfileB (not expanded)</head> <eg - xml:space="preserve"><Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding></sp:TransportBinding> - <sp:AsymmetricBinding></sp:AssymetricBinding> - </ExactlyOne> -</Policy></eg> </example> - <p>We have shown above that Company A offered a - second profile that included two security options. The details of - the Bindings, requires a more detailed exploration of some of the - other features of the WS-Policy Framework. </p> - <p>When Assertion Authors create sets of Policy assertions, like - WS-Security Policy they need to consider expressing the semantics - of their domain in a way that policy consumers, like Company A, - can utilize them. In this case, the WS-SecurityPolicy Assertion Authors - factored out common elements of security mechanisms and utilized a - feature of WS-Policy called "nested" assertions. In the case of - an <code>sp:TransportBinding</code> assertion, just indicating the use of - transport-level security for protecting messages is not - sufficient. For a consumer of a web service provided by a company, - like Company A, to successfully interact, the consumer must also - know what transport token, what algorithm suite, etc. is - required. The <code>sp:TransportBinding</code> assertion, can (and has) - represent (ed) these dependent behaviors as "nested" policy - assertions. </p> - <p>In the example below the child Policy element is a nested - policy behavior and further qualifies the behavior of the - <code>sp:TransportBinding</code> policy assertion. </p> - <example> - <head>CompanyA-ProfileB (fully expanded)</head> - <eg xml:space="preserve"><Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding> - <Policy> - <sp:TransportToken> - <Policy> - <sp:HttpsToken> - <wsp:Policy/> - </sp:HttpsToken> - </Policy> - </sp:TransportToken> - <sp:AlgorithmSuite> - <Policy> - <sp:Basic256Rsa15 /> - </Policy> - </sp:AlgorithmSuite> - </Policy> - </sp:TransportBinding> - <sp:AsymmetricBinding> - </sp:AssymetricBinding> - </ExactlyOne> -</Policy></eg> - </example> - <p> - <code>The sp:AlgorithmSuite</code> is a nested policy - assertion of the <code>sp:TransportBinding</code> assertion and - indicates that this suite is required. The - <code>sp:TransportToken</code> is a nested policy assertion that - indicates the use of a specific type of token, in this case an - HttpsToken. </p> - <p>It should be noted that each policy has an Identifier. In the - case of the default policy expression, Company A has decided that - this policy expression should be broadly available via a URI. - There are advantages and disadvantages to using each type of - identifier. For URI's there is the issue of maintaining the - policy expression when it may no longer be used (Company A gets - bought by Company B and starts using the policies of Company B, - but some "old" consumers may still try to reference the - URI). </p> - <p> For the second type of web services, which may be used only - by certain of Company A's business partners, the id is an XML ID. - The relative URI for referencing this within the same WSDL - document is #CompanyA-ProfileB. This can be useful for company's - when the policy expressions are agreed to between partners but - may be changed as the business agreements change. But the - disadvantage is that the policy expression must be included in - each WSDL document. </p> - <p>Since Company A has decided to use well known policy - expressions that are part of a specification, they - adhere to the guidance given in the WS-SecurityPolicy - specification and attach the policies to the web service endpoint - policy subject as recommended by the WS-SecurityPolicy - specification. For the default web services, the URI is included - in the wsdl binding for each web service. </p> - <example> - <head/> - <eg xml:space="preserve"><wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault"> - <wsp:PolicyReference URI="http://www.CompanyA.com/WebServicesProfileA.xml"> - <wsdl:operation name="GetQuote"> </wsdl:operation> -</wsdl:binding></eg> - </example> - <p>The partner specified policy is included in the beginning of - the WSDL 1.1 document and referenced by the binding for the service - as in the example below.</p> - <example> - <head/> - <eg xml:space="preserve"> -<wsdl:definitions name="StockQuote" - targetNamespace="http:.."> -<wsp:Policy wsu:Id="CompanyA-ProfileB"> - <wsam:Addressing>…</wsam:Addressing> - <ExactlyOne> - <sp:TransportBinding> - <Policy> - <sp:TransportToken> - <wsp:Policy> - <sp:HttpsToken> - <wsp:Policy/> - </sp:HttpsToken> - </wsp:Policy> - </sp:TransportToken> - <sp:AlgorithmSuite> - <wsp:Policy> - <sp:Basic256Rsa15 /> - </wsp:Policy> - </spAlgorithmSuite> - </Policy> - </sp:TransportBinding> - <sp:AsymmetricBinding> - </sp:AssymetricBinding> - </ExactlyOne> -</wsp:Policy> - -<wsdl:binding name="CompanyADefaultBinding" type="tns:CompanyADefault"> - <wsp:PolicyReference id=#CompanyA-ProfileB> - <wsdl:operation name="GetQuote"> </wsdl:operation> -</wsdl:binding></eg> - </example> - <p>In some cases, companies may chose to implement their own - assertions. When companies chose to become Assertion Authors they need - to consider not only the definition of the behavior that the - assertion represents but they need to consider how new assertions - will be intersected and merged with other assertions in the - calculation of an effective policy and this also indicates they need - to consider policy subjects.</p> - <p> The WS-Policy 1.5 - Attachment specification defines algorithms for calculating the - effective policy for a given policy subject and effective policies for - WSDL 1.1, WSDL 2.0 and UDDI policy subjects.</p> - </div1> </body> <back> <div1 id="security-considerations"> @@ -2751,7 +2467,27 @@ <td>Implemented partial resolution, section 5.5 updates, for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=4662">4662</loc>, Editors' action <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/332">332</loc> #2.</td> - </tr> + </tr> + <tr> + <td>20070718</td> + <td>ASV</td> + <td>Implemented the resolution + for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3988</loc>. + Editors' action: + <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/338">338</loc>, + drop <loc href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#scenario">Section + 7 Scenario and a worked example</loc></td> + </tr> + <tr> + <td>20070718</td> + <td>ASV</td> + <td>Implemented the resolution + for issue <loc href="http://www.w3.org/Bugs/Public/show_bug.cgi?id=3988">3978</loc>. + Editors' action: + <loc href="http://www.w3.org/2005/06/tracker/wspolicyeds/actions/339">339</loc>, + drop <loc href="http://www.w3.org/TR/2007/WD-ws-policy-guidelines-20070330/#best-practices-attachment">Section + 6 Applying Best Practices for Policy Attachment</loc></td> + </tr> </tbody> </table> </inform-div1>
Received on Wednesday, 18 July 2007 10:13:22 UTC