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>
