Web Services Policy 1.5 - Guidelines for Policy Assertion Authors

2.1 Roles and Responsibilities in Utilizing Policy Assertions

In order for the policy framework to enable communities to express their own domain knowledge, it needed to provide basic functionality that all domains could exploit and then allow points of extension where authors of the various WS-Policy expressions for a particular domain could provide additional semantics.

Below we capture some of the characteristics of the roles and responsibilities for the authors, consumers and providers.

3.1 Assertions and Their Target Use

When a community of WS-Policy authors decides to define a set of WS-Policy assertions they should understand what functionality the framework provides and apply the knowledge of framework processing when defining the set of assertions. This will require the WS-Policy authors to have some definition and/or understanding of what the goal is for the use of the assertions.

Assertions can be simple or they can be complex. A set of 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 associated is also a factor when defining an assertion. It is possible that WS-Policy assertions will be consumed by a wide range of client configurations, from stand alone client applications to "active" web service requestors that are capable of adapting to constraints and capabilities modifying their own configurations dynamically. If the assertion is intended to be consumed by a broad range of clients, then the behavior should be simple for all of these clients to understand and implement.

Once the subjects are identified, one way of attaching multiple instances of a simple policy assertion is to utilize the referencing mechanism that is present in the framework. By defining the assertion once and using it in different policies (i.e.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 or when creating a domain specific attachment in multiple WSDL files, EPRS, in which the same set of policies are expected to be applied.

WS-Policy domain authors should consider the following factors when composing the set of domain assertions as it may make sense to factor out some assertions that can 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 does 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 assertions subject is helpful in determining the different scopes and subjects that it applies to.

• Composition. If the assertion is used with other assertions in a context, how does 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.

We will cover these aspects in more detail with respect to the type of assertions being used in the subsequent sections.

5.1 Single Domains

When considering the creation of a new domain of policy assertions, it is important to identify whether or not the domain is self contained or can be well defined. A domain that expresses a broad set of capabilities will need to have community support to provide value to the consumers. Ultimately it is the consumers and providers that will determine whether a particular set of assertions correctly characterize the domain. A community should avoid duplicating assertions that have already been defined as this will create ambiguity not clarification and focus on creating assertions for those specific constraints and capabilities that do not overlap with other domains but that communicate new functionality.

The model is an opt-in model. Namely, the providers of services must find the set of assertions useful to improve interoperability of services or they will not include the assertions in their service descriptions.

A review by a broad community is the best way to ensure that the granularity of a set of domain assertions is appropriate.

5.2 New Policy Domains

When creating a new policy domain, it is important to understand how policy expressions are used by the framework. Some WS-Policy domains represent infrastructure efforts like WS-SecurityPolicy and WS-ReliableMessaging Policy. We also anticipate that individual web services applications and deployments may wish to reuse the WS-Policy framework in order to enable dynamic negotiation of business requirements and capabilities at runtime.

New policy authors should not try to overload assertions. A single assertion indicates a single behavior. Sets of assertions can by grouped by an operator "all". This indicates that there is a relationship between the assertions and they now constitute a policy alternative. Choices between alternatives can be indicated by an "exactly one" operator. This basic set of operators allows authors a wide range of options for expressing the possible combinations of assertions within their domain.

It requires a good deal of effort to evaluate the capabilities of a domain and capture them in a way that reflects the options of the domain if the domain has a lot of assertions to define. Interoperability testing of new policy domains is recommended to ensure that consumers and providers are able to use the new domain assertions.

Domain authors are encouraged to look at WS-SecurityPolicy [ADD REFERENCE HERE doc references] to see an example of a complex domain that has been decomposed into a set of policy expressions. New aurthors are encouraged to look at WS-ReliableMessaging Policy to see an example of a simple domain that has only defined 2 assertions.

5.3 Nested Assertions

The framework provides the ability to "nest" policy assertions. For domains with a complex set of options, nesting provides one way to indicate dependent elements within a behavior. The granularity of assertions is determined by the authors and it is recommended that care be taken when defining nested policies to ensure that the options provided appropriately specify policy alternatives within a specific behavior.

We will use the WS-SecurityPolicy to illustrate the use of nested assertions.

Securing messages is a complex usage scenario. The WS-SecurityPolicy authors have defined the sp:TransportBinding policy assertion to indicate the use of transport-level security for protecting messages. Just indicating the use of transport-level security for protecting messages is not sufficient. To successfully interact with a Web service, the consumer must know not only that transport-level security is required, but also what transport token to use, what secure transport to use, what algorithm suite to use for performing cryptographic operations, etc. The sp:TransportBinding policy assertion can represent these dependent behaviors.

A policy assertion like the sp:TransportBinding- identifies a visible behavior that is a requirement. A nested policy expression can be used to enumerate the dependent behaviors on the Transport binding. A nested policy expression is a policy expression that is a child element of another policy assertion element. A nested policy expression further qualifies the behavior of its parent policy assertion.

In the example below, the child Policy element is a nested policy expression and further qualifies the behavior of the sp:TransportBinding policy assertion. The sp:TransportToken is a nested policy assertion of thesp:TransportBinding policy assertion. The sp:TransportToken assertion requires the use of a specific transport token and further qualifies the behavior of the sp:TransportBinding policy assertion (which already requires the use of transport-level security for protecting messages).

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

The sp:AlgorithmSuite is a nested policy assertion of thesp:TransportBinding policy assertion. Thesp:AlgorithmSuite assertion requires the use of the algorithm suite identified by its nested policy assertion (sp:Basic256Rsa15 in the example above) and further qualifies the behavior of the sp:TransportBinding policy assertion.

Setting aside the details of using transport-level security,, a policy-aware client that recognizes this policy assertion can engage transport-level security and its dependent behaviors automatically. That is, the complexity of security usage is absorbed by a policy-aware client and hidden from these Web service developers.

5.4 Assertions with Parameters

The framework provides an alternative approach for providing additional information for an assertion beyond its type. The framework allows WS-Policy domain authors to define name value pairs to qualify an assertion. For some domains it will be appropriate to specify these parameters instead of nesting elements.

Note that parameters of assertions include the following:

• Complex elements that have element children which can not be policy assertions.

• Elements that have attributes

5.5 Comparison of Nested and Parametrized Assertions

The main consideration for selecting parameters or nesting of assertions, is that the framework intersection algorithm processes nested alternatives, but does not consider parameters in its algorithm.

Domain authors should recognize that the framework can yield multiple assertions of the same type. The QName of the assertion is the only vehicle for the framework to match a specific assertion, NOT the contents of the element. If the assertion is a parameterized assertion the authors must understand that this type of assertion will require additional processing by consumers in order to disambiguate the assertions or to understand the semantics of the name value pairs, complex content, attribute values contribution to the processing. Therefore, if the domain authors want to delegate the processing to the framework, utilizing nesting should be considered. Otherwise, domain specific comparison algorithms would need to be devised and be delegated to the specific domain handlers that are not visible to the WS-Policy framework. The tradeoff is the generality vs. the flexibility and complexity of the comparison expected for a domain.

ADD THE EARLIER EXAMPLE FROM THE AUTHORS DOCUMENT

5.6 Self Describing Messages

WS-Policy is intended to communicate the requirements, capabilities, preferences and behaviors of nodes on the message's path, not specifically declare properties of the messages themselves. One of the advantages of Web services is that an XML message can be stored and later examined (e.g. as a record of a business transaction) or interpreted by an intermediary; however, if information that is necessary to understand a message is not available, these capabilities suffer.

For example, if the details of a message's encryption ( e.g., the cipher used, etc) are expressed in policy that isn't attached to the message, it isn't possible to later decipher it. This is very different from expressing, in policy, what ciphers (and so forth) are supported by a particular endpoint, or those that are required in a particular message; the latter are the intended uses of the Ws-Policy framework.

The assertion authors should take into account that there are two important concepts when designing assertions. Firstly, an assertion type indicates a runtime behavior. Secondly, an assertion should also indicate how the assertion type can be inferred or indicated from a message, if there is a need for the behavior to be represented in a persistent way by additional data or metadata that is present in a message. If such a relationship exists, it should be incorporated into an assertion design document that illustrates the disambiguation of the usage of the policy at runtime and in the message if that message is persisted.

REWRITEAs a result, Policy assertions should not be used to express what otherwise should be part of the message; if a property is required to understand a message, it should be communicated in the message, or made available to in a message (e.g., being referenced by a URI in the message) rather than communicated as a policy element.

5.7 Optional Policy Assertion

Optional assertions represent behaviours which may be engaged by a consumer. When using the compact authoring form for assertions, behaviours are marked by using wsp:optional attribute that has a value, "true". During the process of normalization, the runtime behaviour is indicated by two policy alternatives, one with and one without containing the assertion. In a consumer/provider scenario, the choice of engaging the runtime behaviour is upon the consumer although the provider is capable of engaging the runtime behaviour.

The Primer document contains an example that proposes MTOM as an optional behaviour that can be engaged by a consumer. The primer proposes that this assertion identifies the use of MIME Multipart/Related serialization for messages to enable a Policy-aware clients to recognize the policy assertion and if they select an alternative with this assertion, they engage Optimized MIME Serialization for messages.

The semantics of this assertion declare that the behavior is reflected in messages: they use an optimized wire format (MIME Multipart/Related serialization). Note that in order for an optional behaviours to be engaged, the wire message that would utilize the specific assertion must be self describing. For example, an inbound message to a web service that asserts MTOM, must evaluate, the protocol format of the message to determine whether the incoming message adheres to the Optimized MIME Serialization. By examining the message, the provider can determine whether the policy alternate that contains the MTOM assertion is being selected.

Assertion authors should be aware that optional behaviours, like utilizing optional support for Optimized MIME Serialization require some care.

• Since optional behaviours indicate optionality for both the provider and the consumer, behaviours that must always be engaged by a consumer must not be marked as "optional" with a value "true" since presence of two alternatives due to normalization enables a consumer to choose the alternative that does not contain the assertion, and thus making the behaviour not being engaged in an interaction.

• As demonstrated in the MIME optimization behaviour, behaviours must be engaged with respect to messages that are targeted to the provider so that the provider can determine that the optional behaviour is engaged. In other words, the requirement of self describing nature of messages in order to engage behaviours must not be forgotton with regard to the client's ability to detect and select the alternative if it is to participate in the exchange. It is recommended that authors not utilize optional assertions for outbound messages unless there is explicit, out of band mechanism (currently such a mechanism is outside the scope of WS-Policy Framework) that a client can use to indicate that the optional capability must be engaged.

• When optional behaviours are attached with only one side of an interaction, such as an inbound message of a request-response, the engagement of the rest of the interaction will be undefined. For example, if a request-response interaction only specified MTOM optimization for an inbound message, it would not be clear whether the outbound message from the provider could also utilize the behaviour. Therefore, the assertion authors are encouraged to consider how the attachment on a message policy subject on a response message should be treated when optional behaviours are specified for message exchanges within a request response for response messages. Leaving the semantics undescribed may result in providers making assumptions (i.e. if the incoming message utilized the optimization, the response will be returned utilizing the MTOM serialization). Similarly, if engagement of a behaviour is only specified for an outbound message, it may be necessary to describe the semantics if the incoming messages also utilized the behaviour. WS-RM Policy currently allows the incoming messages to utilize WS-RM protocol to be engaged although the assertion may only appear on an outbound message in a request response.

• Optional assertion authors should explicitly state how the capability that is enabled by the assertion would be engaged when they are designing their assertion, whether by specific headers or some other means.

5.8 Considerations for Intersection and Merging

5.9 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 overtime. A namespace associated with the assertion may be used to indicate a specific version of an assertion.

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 do this 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 behaviours (endpoints) or artifacts ( 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.

EXAMPLE

More of this topic is covered in the Section [REFERENCE?]

5.10 Subject Scoping Considerations

Appendix A. Which assertions

Enabled versioning. Conservative composites.

Anti patterns. Interaction between the subjects and interaction between different attachment points. How you can get into trouble.

Granularity we need to talk about. Give wS-RX as example.

Give examples for WSDL 1.0.

5.11 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 behaviour as follows behavior?

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

The authors 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. PROVIDE REFERENCE TO SECTIONS IN PRIMER

The current set of subjects as mapped to the WSDL 1.1 elements, can constrain the assertion constructs to a WSDL exchange if the authors so choose. For Example, In WS-RM, there was not a WSDL subject that was appropriate to some of the characteristics of a reliable messaging exchange and the domain authors chose to not 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 the senders 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 behaviour.

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. The commonly used attachment points for these policy subjects are outlined in XXX.

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

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. Howeever, 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 behaviours but rather abstract requirements, this technique does not apply.

5.12 Lifecycle of Assertions

There are three aspects that govern an assertions lifecycle:

• Assertion Extensibility

• Policy Language Extensibility

• Subject attachment Extensibility

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 [CLARIFY SUBJECT RELATIONSHIP]

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 WSDL, the source of the assertion is the same as the WSDL provider) or it could be proven ( using WS-Trust).