Web Services Policy 1.5 - Guidelines for Policy Assertion Authors

4.1 Assertions and Their Target Use

WS-Policy authors need to have some definition of what the goal is for the assertions they author. WS-Policy authors should also understand the functionality the WS-Policy framework provides and apply the knowledge of framework processing when defining the set of assertions.

Assertions can be simple or they can be complex. WS-Policy authors may choose to specify one or two assertions or they may choose to specify many assertion elements that require parameters or other nested assertions. There are advantages to simplifying the set of assertions. The ultimate goal of policy assertions is to enable interoperability and assertions that define behavior for consumers and providers that can be clearly understood will most likely be consumed by a broad audience.

If a domain has a wide range of behaviors, the ability to combine individual assertions may also need to be considered.

The number of different subjects to which an assertion can be attached is also a factor when defining an assertion. Determining the appropriate policy subjects can sometimes involve understanding the requirements of wide range of client configurations, from stand alone client applications to "active" web service requestors that are capable of modifying their own configurations dynamically.

Once the range of policy subjects are is identified, there are choices for ways of attaching multiple instances of a simple policy assertion to multiple subjects. One way is to utilize the referencing mechanism that is present in the framework. By defining the assertion once and using it in different policies (e.g. with different alternatives) via reference, a policy assertion may be associated with different alternatives and subjects. A referencing mechanism is very useful in a tooling environment; when creating a domain specific attachment in multiple WSDL files or Endpoint References in which the same set of policies are expected to be applied.

Best practice: WS-Policy domain authors should include the following items factors when in the dialectset of domain assertions as it may make sense to factor out some assertions that can specification: be used by multiple subjects:

• The definition of the assertion. Does the assertion pertain to a specific behavior that is tied to a context or is the behavior different in each possible context? For example an assertion that may have different semantics for a single message exchange or for all message exchanges that pertain to an endpoint would probably be represented by separate assertions.

• Scoping of the assertion. Where does the assertion apply? Is the assertion about a specific description in WSDL? Is the assertion about a specific aspect of protocol? Is the assertion about a specific coordination between parties? Determination of the subject of an assertion is helpful in specifying the different scopes and subjects that it applies to.

• Composition. If the assertion is used with other assertions in a context, it is necessary to consider how the assertion may or may not affect the composition. For example, if an assertion applies to the SOAP protocol, it would be necessary to consider how its presence must interact with other policy assertions that are defined for security.

4.4 Comparison of Nested and Parameterized Assertions

There are two different ways to provide additional information in an assertion beyond its type. We cover these two cases below followed by a comparison of these approaches targeting when to use either of the approach.

<Policy>
  <sp:SignedParts>
    <sp:Body />
    <sp:Header />
  </sp:SignedParts>
</Policy>

<sp:TransportBinding>
  <Policy>
    <sp:TransportToken>
      <Policy>
        <sp:HttpsToken RequireClientCertificate="false" />
      </Policy>
    </sp:TransportToken>
    <sp:AlgorithmSuite>
      <Policy>
        <sp:Basic256Rsa15/>
      </Policy>
    </sp:AlgorithmSuite>
  </Policy>
</sp:TransportBinding>

4.5 Policy Assertions Designating Optional Behaviors

4.6 Typing Assertions

Since a QName is the central mechanism for identifying a policy assertion, assertion authors should be aware of the possible evolution of their assertions and how this would impact the semantics of the assertion overtime. A namespace associated with the assertion may be used to indicate a specific version of an assertion but this has its limitations. See Lifecycle material 5. Lifecycle of Assertions for more detail. assertion.

The typing must be done in combination with the scoping of the semantics to a policy subject. WS-PolicyAttachment provides a means of associating an assertion with arbitrary subjects, regardless of their nature. This flexibility can lead to ambiguity in the interpretation of policy; for example, if one attaches an assertion with the semantic "must be encrypted" to a SOAP endpoint, it's unclear what must be encrypted.

To avoid this confusion, assertion definitions should be precise about their semantics and include information that restricts their set of permissible policy subjects appropriately and indicates which Qnames are associated with which subjects. One way to disambiguate the semanticthis is to generally determine if an assertion is specific to a policy attachment mechanism. An example could be identifying whether the assertion expressed is associated with behaviors (endpoints) or artifacts (messages)( messages) and then constraining the use of an assertion to one of these subjects.

Thus our example encryption assertion would have a subject of "message", and could only be attached to messages, where the assertion is valid. However, authors need to be aware that policy attachment subjects are not limited to the subjects defined in WSDL. The external attachment model in WS-PolicyAttachment allows for the definition of other domain expressions to be policy subjects. More of this topic is covered in the [Web Services Policy Primer]

4.7 Levels of Abstraction in WSDL

A behavior identified by a policy assertion applies to the associated policy subject. If a policy assertion is to be used within WSDL, policy assertion authors must specify a WSDL policy subject. The policy subject is determined with respect to a behavior as follows:

• If the behavior applies to any message exchange using any of the endpoints offered by a service then the subject is the service policy subject.

• If the behavior applies to any message exchange made using an endpoint then the subject is the endpoint policy subject.

• If the behavior applies to any message exchange defined by an operation then the subject is the operation policy subject.

• If the behavior applies to an input message then the subject is the message policy subject - similarly for output and fault message policy subjects.

WS-Policy authors that wish to utilize WSDL policy subjects need to understand how the assertions will be processed in intersection and merging and the implications of the processing for considering a specific attachment point and policy subject. This topic is considered in detail in [Web Services Policy Primer]

The current set of subjects as mapped to the WSDL 1.1 elements, can also constrain the assertion constructs. For Example, In WS-RM, the domain authors chose to support certain capabilities at the endpoint level. This resulted in the finer granularity of the assertion to apply at the message policy subject, but the assertion semantics also indicates that the if a sender chosesenders choose to engage RM semantics (although not specified via attachment in WSDL at incoming messages), the providers will honor the engagement of RM. This is illustrative of how the assertion author can specify additional constraints and assumptions for attachment and engagement of behavior.

If the capability is not really suitable and may imply different semantics with respect to attachment points, the assertion authors should consider the following

• Decompose the semantics with several assertions

• Rewrite a single assertion targeting a specific subject.

For a given WSDL policy subject, there may be several attachment points. For example, there are three attachment points for the endpoint policy subject: the port, binding and portType element. Policy assertion authors should identify the relevant attachment point when defining a new assertion. To determine the relevant attachment points, authors should consider the scope of the attachment point. For example, an assertion should only be allowed in the portType element if the assertion reasonably applies to any endpoint that ever references that portType. Most of the known policy assertions are designed for the endpoint, operation or message policy subject. subject.

In using WSDL attachment, it should be noted that the service policy subject is a collection of endpoint policy subjects. The endpoint policy subject is a collection of operation policy subjects and etc. As a result, the WSDL policy subjects compose naturally. It is quite tempting to associate the identified behavior to a broader policy subject than to a fine granular policy subject. For instance, it is convenient to attach a supporting token assertion (defined by the Web Services Security Policy specification) to an endpoint policy subject instead of a message policy subject. Similarly, for authoring convenience, an assertion author may allow the association of an assertion to multiple policy subjects. If an assertion is allowed to be associated with multiple policy subjects then the assertion author has the burden to describe the semantics of multiple instances of the same assertion attached to multiple policy subjects at the same time in order to avoid conflicting behavior.

One approach is to specify a policy subject, choose the most granular policy subject that the behavior applies to and specify a preferred attachment point in WSDL. However, this approach only works if the policy subject is a true WSDL construct other than some other protocol concept that is layered over WSDL message exchanges. For example, the WS-RM Policy is a capability that governs a target endpoints capability to accept sequences that is beyond single message exchanges. Therefore, its semantics encompasses the cases when message level policy subjects may be used as attachment but considers when sequences are present. In addition, when the policy assertions do not target wire-level behaviors but rather abstract requirements, this technique does not apply. apply.

7.1 Appropriate Attachment: Preserving Context-Free Policies

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. In particular, the timing of a policy attachment or the role that a party who attaches policy should have no bearing on the evaluation of the policy assertion

7.2 Appropriate Attachment: Identifying Assertion Subjects

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".

7.3 Appropriate Attachment: Identifying Assertion Sources

As with identifying Policy subjects, policy attachment mechanisms should make it possible to clearly identify the source of a poly assertion both for debugging and for verification. This could take several forms: it could be assumed (in( in WSDL, the source of the assertion is the same as the WSDL provider) or it could be proven (using( using [WS-Trust]).