This section describes a mechanism for associating policy expressions with Web service constructs in WSDL 1.1 [WSDL 1.1].
The mechanism consists of:
WSDL 1.1 disallows the use of extensibility elements on certain elements and
the use of extensibility attributes on others. However, the WS-I Basic Profile 1.1
[BP 1.1] overrules this restriction and allows element extensibility everywhere.
Therefore, when attaching a reference directly to the WSDL element the policy
reference SHOULD be attached using wsp:PolicyReference as child element unless
it
is absolutely necessary to maintain the original WSDL 1.1 restriction, in which
case the @wsp:PolicyURIs attribute MAY be used for the following WSDL elements:
To ensure that consumers of policy-annotated WSDL elements are
capable of processing such policy attachments, attachments using
wsp:PolicyReference
SHOULD be
marked as a mandatory extension (e.g., with a
@wsdl11:required="true" attribute).
4.1 Calculating Effective Policy in WSDL 1.1
Policy attachments in WSDL 1.1 can be used to associate policies
with four different types of policy subject, identified as the service
policy subject, the endpoint policy subject, the operation policy
subject, and the message policy subject. These policy subjects should be
considered as nested, due to the hierarchical nature of WSDL.
When attaching a policy to a WSDL element, a policy scope is
implied for that attachment. The policy scope only contains the policy
subject associated with that element and not those associated with the
children of that element. Therefore, it is
RECOMMENDED that each policy assertion contained
within a WSDL element's element policy should have the correct
semantic such that the policy subject for that assertion is that WSDL
element. For example, assertions that describe behaviours regarding
the manipulation of messages should only be contained within policies
attached to WSDL message elements.
Figure 1 represents how the effective policies, with regard to
WSDL, are calculated for each of these policy subjects. In the
diagram, the dashed boxes represent policy scopes implied by WSDL
elements. For a particular policy subject, the effective policy
MUST
merge the element policy of each
element with a policy scope that contains the policy subject.
For abstract WSDL definitions, the element policy is considered an
intrinsic part of the definition and applies to all uses of that
definition. In particular, it MUST be
merged into the effective policy of every implementation
of that abstract WSDL definition.
Policies that are attached to a deployed resource (e.g., services
or ports) are only considered in the effective policy of that deployed
resource itself.
(This graphic is also available in SVG format here.)
When attaching policies at different levels of the WSDL hierarchy, care must be taken.
A message exchange with an endpoint MAY be described by the
effective policies
in all four subject types simultaneously.
For example, in Figure 4-1, for a particular input message to a deployed
endpoint, there are four policy subjects involved, each with their own
effective policy. There is an effective policy for the message, as
well as an effective policy for the parent operation of that message,
an effective policy for the deployed endpoint, and the effective
policy for the service as a whole. All four effective policies are
applicable in relation to that specific input message.
It is RECOMMENDED that, where specific policy
assertions associated with one policy subject are only compatible with
specific policy assertions on another policy subject in the same
hierarchical chain, the policies containing these assertions should be
attached within a single WSDL binding hierarchy.
For any given port, the policy
alternatives for each policy
subject type SHOULD be compatible with
each of the policy
alternatives at each of the policy subjects parent and child
policy subjects, such that
choices between policy
alternatives at each level are independent of each
other.
The rest of this section describes these policy subject types, and
how the effective policy for each policy subject is calculated.
4.1.1 Service Policy Subject
The following WSDL 1.1 element is considered as the service policy subject:
This element MAY have element policy as per
Section 3. Policy Attachment, and if present
MUST be merged into the effective policy of the
WSDL service policy subject.
A policy associated with a service policy subject applies to any
message exchange using any of the endpoints offered by that service.
4.1.2 Endpoint Policy Subject
The following WSDL 1.1 elements collectively describe an endpoint:
wsdl11:port
wsdl11:portType
wsdl11:binding
These elements MAY have element policy as per Section 3. Policy Attachment. The policy scope implied by each of these elements contains the endpoint policy subject representing the deployed endpoint.
Since the wsdl11:portType may be used by more than one
binding, it is RECOMMENDED that only policies
containing abstract (i.e., binding independent) assertions should be
attached to this type of element.
Policies associated with an endpoint
policy subject apply to any message exchange made using that endpoint.
The effective policy for a WSDL endpoint policy subject includes
the element policy of the wsdl11:port element that defines
the endpoint merged with the element policy of the
referenced wsdl11:binding element and the element policy of
the referenced wsdl11:portType element that defines the
interface of the endpoint.
4.1.3 Operation Policy Subject
The following WSDL 1.1 elements collectively describe an operation:
These elements MAY have element policy as per Section 3. Policy Attachment.
The policy scope implied by each of these elements contains the
operation policy subject representing the specific operation of the
endpoint policy subject.
Since the wsdl11:portType/wsdl11:operation may be used by
more than one binding, it is RECOMMENDED that only
policies containing abstract (i.e., binding independent) assertions
should be attached to this type of element.
Policies associated with an operation policy subject apply to
the message exchange described by that operation.
The effective policy for a WSDL operation policy subject is
calculated in relation to a specific port, and includes the element
policy of the wsdl11:portType/wsdl11:operation element that
defines the operation merged with that of the
corresponding wsdl11:binding/wsdl11:operation element.
4.1.4 Message Policy Subject
The following WSDL 1.1 elements are used to describe messages:
wsdl11:message
wsdl11:portType/wsdl11:operation/wsdl11:input
wsdl11:portType/wsdl11:operation/wsdl11:output
wsdl11:portType/wsdl11:operation/wsdl11:fault
wsdl11:binding/wsdl11:operation/wsdl11:input
wsdl11:binding/wsdl11:operation/wsdl11:output
wsdl11:binding/wsdl11:operation/wsdl11:fault
These elements MAY have element policy as per Section 3. Policy Attachment.
The policy scope implied by these elements contains the message
policy subject representing the specific input, output, or fault
message in relation to the operation policy subject.
Policies associated with a message policy subject apply to that
message (i.e. input, output or fault message).
The effective policy for a specific WSDL message (i.e., input,
output, or fault message) is calculated in relation to a specific
port, and includes the element policy of the wsdl11:message
element that defines the message's type merged with the
element policy of the wsdl11:binding and
wsdl11:portType message definitions that describe that
message.
For example, the effective policy of a specific input message for a
specific port would be the merge of the
wsdl11:message element defining the message type, the
wsdl11:portType/wsdl11:operation/wsdl11:input element, and
the corresponding
wsdl11:binding/wsdl11:operation/wsdl11:input element for that
message.
Since a wsdl11:message may be used by more than one
wsdl11:portType, it is RECOMMENDED that
only policies containing abstract (i.e., binding independent)
assertions should be attached to this type of element.
Since wsdl11:input, wsdl11:output, and
wsdl11:fault elements in a
wsdl11:portType/wsdl11:operation may be used by more than
one binding, it is RECOMMENDED that only policies
containing abstract (i.e., binding independent) assertions should be
attached to these types of elements.
Care should be taken when attaching policies to outbound messages
as the result may not be what is expected. For example, expressing a
choice on a service's outbound message without a mechanism for a
requester of that service to communicate its choice to the service
before the outbound message is sent may not result in the desired
behaviours. It is therefore RECOMMENDED that policy
alternatives on outbound messages SHOULD be avoided
without the use of some form of mutual policy exchange between the
parties involved.
4.1.5 Example
As an example of the combination of these policy subjects and
effective policy calculation, consider the WSDL type definition in
Example 4-1 that references policies.
Example 4-1. Example Policy Attached to WSDL.
(01) <wsdl11:definitions name="StockQuote"
targetNamespace="http://www.example.com/stock/binding"
xmlns:tns="http://www.example.com/stock/binding"
xmlns:fab="http://www.example.com/stock"
xmlns:rmp="http://docs.oasis-open.org/ws-rx/wsrmp/200702"
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:wsoap12="http://schemas.xmlsoap.org/wsdl/soap12/"
xmlns:wsp="http://www.w3.org/ns/ws-policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" >
(02) <wsp:Policy wsu:Id="RmPolicy" >
(03) <rmp:RMAssertion>
(04) <wsp:Policy/>
(05) </rmp:RMAssertion>
(06) </wsp:Policy>
(07) <wsp:Policy wsu:Id="X509EndpointPolicy" >
(08) <sp:AsymmetricBinding>
(09) <wsp:Policy>
<!-- Details omitted for readability -->
(10) <sp:IncludeTimestamp />
(11) <sp:OnlySignEntireHeadersAndBody />
(12) </wsp:Policy>
(13) </sp:AsymmetricBinding>
(14) </wsp:Policy>
(15) <wsp:Policy wsu:Id="SecureMessagePolicy" >
(16) <sp:SignedParts>
(17) <sp:Body />
(18) </sp:SignedParts>
(19) <sp:EncryptedParts>
(20) <sp:Body />
(21) </sp:EncryptedParts>
(22) </wsp:Policy>
(23) <wsdl11:import namespace="http://www.example.com/stock"
location="http://www.example.com/stock/stock.wsdl" />
(24) <wsdl11:binding name="StockQuoteSoapBinding" type="fab:Quote" >
(25) <wsoap12:binding style="document"
(26) transport="http://schemas.xmlsoap.org/soap/http" />
(27) <wsp:PolicyReference URI="#RmPolicy" wsdl11:required="true" />
(28) <wsp:PolicyReference URI="#X509EndpointPolicy" wsdl11:required="true" />
(29) <wsdl11:operation name="GetLastTradePrice" >
(30) <wsoap12:operation soapAction="http://www.example.com/stock/Quote/GetLastTradePriceRequest" />
(31) <wsdl11:input>
(32) <wsoap12:body use="literal" />
(33) <wsp:PolicyReference URI="#SecureMessagePolicy"
wsdl11:required="true" />
(34) </wsdl11:input>
(35) <wsdl11:output>
(36) <wsoap12:body use="literal" />
(37) <wsp:PolicyReference URI="#SecureMessagePolicy"
(38) wsdl11:required="true" />
(39) </wsdl11:output>
(40) </wsdl11:operation>
(41) </wsdl11:binding>
(42) </wsdl11:definitions>
For endpoints bound to StockQuoteSoapBinding, the effective policy
of the endpoint is listed in Example 3-1 (above). For
the GetLastTradePrice operation, an additional
message-level effective policy is in effect for the input message,
whose XML 1.0 representation is listed in Example 4-2.
Example 4-2. Example Message Security Policy Expression.
(01) <wsp:Policy
xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702"
xmlns:wsp="http://www.w3.org/ns/ws-policy"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
wsu:Id="SecureMessagePolicy" >
(02) <sp:SignedParts>
(03) <sp:Body />
(04) </sp:SignedParts>
(05) <sp:EncryptedParts>
(06) <sp:Body />
(07) </sp:EncryptedParts>
(08) </wsp:Policy>
