- 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