web services addressing (ws-addressing)
august 2004
authors
don box, microsoft (editor)
erik christensen, microsoft
francisco curbera, ibm (editor)
donald ferguson, ibm
jeffrey frey, ibm
marc hadley, sun microsystems, inc.
chris kaler, microsoft
david langworthy, microsoft
frank leymann, ibm
brad lovering, microsoft
steve lucco, microsoft
steve millet, microsoft
nirmal mukhi, ibm
mark nottingham, bea
david orchard, bea
john shewchuk, microsoft
eugène sindambiwe, sap
tony storey, ibm
sanjiva weerawarana, ibm
steve winkler, sap
copyright notice
(c) 2002-2004 bea systems inc., international business machines corporation, microsoft corporation, inc, sap ag, and sun microsystems. all rights reserved.
permission to copy and display the ws-addressing specification (the "specification"), in any medium without fee or royalty is hereby granted, provided that you include the following on all copies of the specification that you make:
1. a link or url to the specification at this location.
2. the copyright notice as shown in the specification.
bea systems, ibm, microsoft, sap, and sun (collectively, the "authors") each agree to grant you a license, under royalty-free and otherwise reasonable, non-discriminatory terms and conditions, to their respective essential patent claims that they deem necessary to implement the ws-addressing specification.
the specification is provided "as is," and the authors make no representations or warranties, express or implied, including, but not limited to, warranties of merchantability, fitness for a particular purpose, non-infringement, or title; that the contents of the specification are suitable for any purpose; nor that the implementation of such contents will not infringe any third party patents, copyrights, trademarks or other rights.
the authors will not be liable for any direct, indirect, special, incidental or consequential damages arising out of or relating to any use or distribution of the specifications.
the name and trademarks of the authors may not be used in any manner, including advertising or publicity pertaining to the specifications or their contents without specific, written prior permission. title to copyright in the specifications will at all times remain with the authors.
no other rights are granted by implication, estoppel or otherwise.
abstract
ws-addressing provides transport-neutral mechanisms to address web services and messages. specifically, this specification defines xml [xml 1.0, xml namespaces] elements to identify web service endpoints and to secure end-to-end endpoint identification in messages. this specification enables messaging systems to support message transmission through networks that include processing nodes such as endpoint managers, firewalls, and gateways in a transport-neutral manner.
status
ws-addressing and related specifications are provided as-is and for review and evaluation only. bea, ibm, microsoft, sap, and sun make no warrantees or representations regarding the specifications in any manner whatsoever.
table of contents
1. introduction
1.1 notational conventions
1.2 namespaces
2. endpoint references
2.1 information model for endpoint references
2.2 endpoint reference xml infoset representation
2.3 binding endpoint references
2.4 endpoint reference comparison
3. message information headers
3.1 message information headers xml infoset representation
3.2 formulating a reply message
3.3 associating action with wsdl operations
3.3.1 explicit association
3.3.2 default action pattern
4. faults
4.1 invalid message information header
4.2 message information header required
4.3 destination unreachable
4.4 action not supported
4.5 endpoint unavailable
5. security considerations
6. acknowledgements
7. references
1. introduction
web services addressing (ws-addressing) defines two interoperable constructs that convey information that is typically provided by transport protocols and messaging systems. these constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. the two constructs are endpoint references and message information headers.
a web service endpoint is a (referenceable) entity, processor, or resource where web service messages can be targeted. endpoint references convey the information needed to identify/reference a web service endpoint, and may be used in several different ways: endpoint references are suitable for conveying the information needed to access a web service endpoint, but are also used to provide addresses for individual messages sent to and from web services. to deal with this last usage case this specification defines a family of message information headers that allows uniform addressing of messages independent of underlying transport. these message information headers convey end-to-end message characteristics including addressing for source and destination endpoints as well as message identity.
both of these constructs are designed to be extensible and re-usable so that other specifications can build on and leverage endpoint references and message information headers.
the following example illustrates the use of these mechanisms in a soap 1.2 message being sent from http://business456.example/client1 to http://fabrikam123.example/purchasing:
(001) <s:envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
(002) <s:header>
(003) <wsa:messageid>
(004) uuid:6b29fc40-ca47-1067-b31d-00dd010662da
(005) </wsa:messageid>
(006) <wsa:replyto>
(007) <wsa:address>http://business456.example/client1</wsa:address>
(008) </wsa:replyto>
(009) <wsa:to>http://fabrikam123.example/purchasing</wsa:to>
(010) <wsa:action>http://fabrikam123.example/submitpo</wsa:action>
(011) </s:header>
(012) <s:body>
(013) ...
(014) </s:body>
(015) </s:envelope>
lines (002) to (011) represent the header of the soap message where the mechanisms defined in the specification are used. the body is represented by lines (012) to (014).
lines (003) to (010) contain the message information header blocks. specifically, lines (003) to (005) specify the identifier for this message and lines (006) to (008) specify the endpoint to which replies to this message should be sent as an endpoint reference. line (009) specifies the address uri of the ultimate receiver of this message. line (010) specifies an action uri identifying expected semantics.
1.1 notational conventions
the keywords "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in rfc 2119 [rfc 2119].
when describing abstract data models, this specification uses the notational convention used by the xml infoset [xml infoset]. specifically, abstract property names always appear in square brackets (e.g., [some property]).
when describing concrete xml schemas [xml schema part 1, part 2], this specification uses the notational convention of ws-security [ws-security]. specifically, each member of an element's [children] or [attributes] property is described using an xpath-like notation (e.g., /x:myheader/x:someproperty/@value1). the use of {any} indicates the presence of an element wildcard (<xs:any/>). the use of @{any} indicates the presence of an attribute wildcard (<xs:anyattribute/>).
1.2 namespaces
this specification uses a number of namespace prefixes throughout; they are listed in table 1. note that the choice of any namespace prefix is arbitrary and not semantically significant (see [xml namespaces]).
prefix namespace
s http://www.w3.org/2003/05/soap-envelope
s11 http://schemas.xmlsoap.org/soap/envelope
wsa http://schemas.xmlsoap.org/ws/2004/08/addressing
wsp http://schemas.xmlsoap.org/ws/2002/12/policy
xs http://www.w3.org/2001/xmlschema
table 1 prefixes and namespaces used in this specification
ws-addressing is defined in terms of the xml information set [xml infoset]. ws-addressing is conformant to the soap 1.2 [soap 1.2] processing model; soap 1.2 is not a requirement for using the constructs defined in this specification. ws-addressing is also designed to be able work with wsdl 1.1 [wsdl 1.1] described services. the examples in this specification use an xml 1.0 [xml 1.0] representation but this is not a requirement.
all information items defined by ws-addressing are identified by the xml namespace uri [xml namespaces] "http://schemas.xmlsoap.org/ws/2004/08/addressing". a normative xml schema [xml schema part 1, part 2] document can be obtained by dereferencing the xml namespace uri.
2. endpoint references
this section defines the model and syntax of an endpoint reference.
this specification introduces a new description element type, the endpoint reference, with the intent of supporting a set of dynamic usage patterns not currently appropriately covered by wsdl 1.1 [wsdl 1.1]. in particular, this specification intends to facilitate the following usage scenarios:
dynamic generation and customization of service endpoint descriptions.
identification and description of specific service instances that are created as the result of stateful interactions.
flexible and dynamic exchange of endpoint information in tightly coupled environments where communicating parties share a set of common assumptions about specific policies or protocols that are used during the interaction.
to support these scenarios, we define a lightweight and extensible mechanism to dynamically identify and describe service endpoints and instances. because of the current limits of the wsdl 1.1 extensibility model, the wsdl 1.1 service and port elements cannot be used to cover the use cases listed above. endpoint references logically extend the wsdl description model (e.g., porttypes, bindings, etc.), but do not replace it. endpoint references will be used instead of wsdl <service/> elements in the following cases:
specific instances of a stateful service need to be identified or its instance-specific configuration details need to be transmitted.
a lightweight, self-contained description of a service endpoint needs to be communicated. in particular, this may be necessary when the details of the endpoint configuration are already shared by the communicating parties, but specific policy information needs to be added or updated, typically as a result of a dynamic configuration process.
endpoint references complement and do not replace the wsdl/1.1 <wsdl:service> element. we expect solutions built on wsdl/1.1 to continue to utilize a service element. moving forward we anticipate that endpoint references and wsdl will evolve coherently. the endpoint references may link to service elements in wsdl/1.1, and support additional scenarios in which the wsdl information is not known by a party processing a message. these scenarios may include dynamic messaging or limited capability message processors.
2.1 information model for endpoint references
an endpoint reference consists of the following abstract properties:
[address] : uri (mandatory)
an address uri that identifies the endpoint. this may be a network address or a logical address.
[reference properties] : xs:any (0..unbounded).
a reference may contain a number of individual properties that are required to identify the entity or resource being conveyed. reference identification properties are element information items that are named by qname and are required to properly dispatch messages to endpoints at the endpoint side of the interaction. reference properties are provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. the interpretation of these properties (as the use of the endpoint reference in general) is dependent upon the protocol binding and data encoding used to interact with the endpoint. section 2.3 below defines the default binding for the soap protocol. consuming applications should assume that endpoints represented by endpoint references with different [reference properties] may accept different sets of messages or follow a different set of policies, and consequently may have different associated metadata (wsdl, xml schema, and ws-policy policies ). the relationship between reference properties and endpoint policies is further explained in section 2.4.
[reference parameters] : xs:any (0..unbounded).
a reference may contain a number of individual parameters which are associated with the endpoint to facilitate a particular interaction. reference parameters are element information items that are named by qname and are required to properly interact with the endpoint. reference parameters are also provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. the use of reference parameters is dependent upon the protocol binding and data encoding used to interact with the endpoint. section 2.3 describes the default binding for the soap protocol. unlike [reference properties], the [reference parameters] of two endpoint references may differ without an implication that different xml schema, wsdl or policies apply to the endpoints.
[selected port type] : qname (0..1)
the qname of the primary porttype of the endpoint being conveyed.
[service-port] : (qname, ncname (0..1)) (0..1)
this is the qname identifying the wsdl service element that contains the definition of the endpoint being conveyed. the service name provides a link to a full description of the service endpoint. an optional non-qualified name identifies the specific port in the service that corresponds to the endpoint.
[policy] : wsp:policy (0..unbounded)
a variable number of xml policy elements as described in ws-policy [ws-policy] describing the behavior, requirements and capabilities of the endpoint. policies may be included in an endpoint to facilitate easier processing by the consuming application, or because the policy was dynamically generated. however, embedded policies are not authoritative and may be stale or incoherent with the policies associated with the endpoint at the time when the interaction occurs.
2.2 endpoint reference xml infoset representation
this section defines an xml infoset-based representation for an endpoint reference as both an xml type (wsa:endpointreferencetype) and as an xml element (<wsa:endpointreference>).
the wsa:endpointreferencetype type is used wherever a web service endpoint is referenced. the following describes the contents of this type:
<wsa:endpointreference>
<wsa:address>xs:anyuri</wsa:address>
<wsa:referenceproperties> ... </wsa:referenceproperties> ?
<wsa:referenceparameters> ... </wsa:referenceparameters> ?
<wsa:porttype>xs:qname</wsa:porttype> ?
<wsa:servicename portname="xs:ncname"?>xs:qname</wsa:servicename> ?
<wsp:policy> ... </wsp:policy>*
</wsa:endpointreference>
the following describes the attributes and elements listed in the schema overview above:
/wsa:endpointreference
this represents some element of type wsa:endpointreferencetype. this example uses the predefined <wsa:endpointreference> element, but any element of type wsa:endpointreferencetype may be used.
/wsa:endpointreference/wsa:address
this required element (of type xs:anyuri) specifies the [address] property of the endpoint reference. this address may be a logical address or identifier for the service endpoint.
/wsa:endpointreference/wsa:referenceproperties/
this optional element contains the elements that convey the [reference properties] of the reference.
/wsa:endpointreference/wsa:referenceproperties/{any}
each child element of referenceproperties represents an individual [reference property].
/wsa:endpointreference/wsa:referenceparameters/
this optional element contains the elements that convey the [reference parameters] of the reference.
/wsa:endpointreference/wsa:referenceparameters/{any}
each child element of referenceparameters represents an individual [reference parameter].
/wsa:endpointreference/wsa:porttype
this optional element (of type xs:qname) specifies the value of the [selected port type] property of the endpoint reference.
/wsa:endpointreference/wsa:servicename
this optional element (of type xs:qname) specifies the <wsdl:service> definition that contains a wsdl description of the endpoint being referenced.
/wsa:endpointreference/wsa:servicename/@portname
this optional attribute (of type xs:ncname) specifies the name of the <wsdl:port> definition that corresponds to the endpoint being referenced.
/wsa:endpointreference/wsp:policy
this optional element specifies a policy that is relevant to the interaction with the endpoint.
/wsa:endpointreference/{any}
this is an extensibility mechanism to allow additional elements to be specified.
/wsa:endpointreference/@{any}
this is an extensibility mechanism to allow additional attributes to be specified.
the following illustrates an endpoint reference. this element references the port of type "fabrikam:inventoryporttype" at the uri "http://www.fabrikam123.example/acct".
<wsa:endpointreference xmlns:wsa="..." xmlns:fabrikam="...">
<wsa:address>http://www.fabrikam123.example/acct</wsa:address>
<wsa:porttype>fabrikam:inventoryporttype</wsa:porttype>
</wsa:endpointreference>
2.3 binding endpoint references
when a message needs to be addressed to the endpoint, the information contained in the endpoint reference is mapped to the message according to a transformation that is dependent on the protocol and data representation used to send the message. protocol-specific mappings (or bindings) will define how the information in the endpoint reference is copied to message and protocol fields. this specification defines the soap binding for endpoint references. this mapping may be explicitly replaced by other bindings (defined as wsdl bindings or as policies); however, in the absence of an applicable policy stating that a different mapping must be used, the soap binding defined here is assumed to apply. to ensure interoperability with a broad range of devices, all conformant implementations must support the soap binding.
the soap binding for endpoint references is defined by the following two rules:
the [address] property in the endpoint reference is copied in the [destination] header field of the soap message.
each [reference property] and [reference parameter] element becomes a header block in the soap message. the element information item of each [reference property] or [reference parameter] (including all of its [children], [attributes] and [in-scope namespaces]) is to be added as a header block in the new message.
the next example shows how the default soap binding for endpoint references is used to construct a message addressed to the endpoint:
<wsa:endpointreference xmlns:wsa="..." xmlns:fabrikam="...">
<wsa:address>http://www.fabrikam123.example/acct</wsa:address>
<wsa:referenceproperties>
<fabrikam:customerkey>123456789</fabrikam:customerkey>
</wsa:referenceproperties>
<wsa:referenceparameters>
<fabrikam:shoppingcart>abcdefg</fabrikam:shoppingcart>
</wsa:referenceparameters>
</wsa:endpointreference>
according to the mapping rules stated before, the address value is copied in the "to" header and the "customerkey" element should be copied literally as a header in a soap message addressed to this endpoint. the soap message would look as follows:
<s:envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="..." xmlns:fabrikam="... ">
<s:header>
...
<wsa:to>http://www.fabrikam123.example/acct</wsa:to>
<fabrikam:customerkey>123456789</fabrikam:customerkey>
<fabrikam:shoppingcart>abcdefg</fabrikam:shoppingcart>
...
</s:header>
<s:body>
...
</s:body>
</s:envelope>
2.4 endpoint reference comparison
during the course of web services interactions applications may receive multiple endpoint references describing the endpoints it needs to interact with. different copies of an endpoint reference may also be received over time.
the following rules clarify the relation between the behaviors of the endpoints represented by two endpoint references with the same [address] and the same [reference properties].
the two endpoints accept the same sets of messages, and follow and require the same set of policies. that is, the xml schema, wsdl, and ws-policy metadata applicable to the two references are the same.
in particular, the policies applicable to the two endpoints are the same regardless of the values of the embedded [policy]. embedded policies are not authoritative and may be stale or incoherent with the policies associated with the endpoint.
the [address] properties of two endpoint references are compared according to section 6 of [rfc 2396]. the [reference properties] of two endpoint references are equal if:
they contain the same number of individual properties;
for each reference property in one endpoint reference there exists an equivalent reference property in the other. one [reference property] is equivalent to another [reference property] if their byte streams per exclusive xml canonicalization are equal.
therefore, a consuming application should assume that different xml schemas, wsdl definitions and policies apply to endpoint references whose address or reference properties differ.
3. message information headers
this section defines the model and syntax of a message information header.
the message information headers collectively augment a message with the following abstract properties. these properties enable the identification and location of the endpoints involved in an interaction. the basic interaction pattern from which all others are composed is "one way". in this pattern a source sends a message to a destination without any further definition of the interaction.
"request reply" is a common interaction pattern that consists of an initial message sent by a source endpoint (the request) and a subsequent message sent from the destination of the request back to the source (the reply). a reply can be either an application message, a fault, or any other message.
the properties below support one way, request reply, and any other interaction pattern:
[destination] : uri (mandatory)
the address of the intended receiver of this message.
[source endpoint] : endpoint reference (0..1)
reference of the endpoint where the message originated from.
[reply endpoint] : endpoint reference (0..1)
an endpoint reference that identifies the intended receiver for replies to this message. if a reply is expected, a message must contain a [reply endpoint]. the sender must use the contents of the [reply endpoint] to formulate the reply message as defined in section 3.2. if the [reply endpoint] is absent, the contents of the [source endpoint] may be used to formulate a message to the source. this property may be absent if the message has no meaningful reply. if this property is present, the [message id] property is required.
[fault endpoint] : endpoint reference (0..1)
an endpoint reference that identifies the intended receiver for faults related to this message. when formulating a fault message as defined in section 3.2 and 4, the sender must use the contents of the [fault endpoint] of the message being replied to to formulate the fault message. if the [fault endpoint] is absent, the sender may use the contents of the [reply endpoint] to formulate the fault message. if both the [fault endpoint] and [reply endpoint] are absent, the sender may use the contents of the [source endpoint] to formulate the fault message. this property may be absent if the sender cannot receive fault messages (e.g., is a one-way application message). if this property is present, the [message id] property is required.
[action] : uri (mandatory)
an identifier that uniquely (and opaquely) identifies the semantics implied by this message.
it is recommended that value of the [action] property is a uri identifying an input, output, or fault message within a wsdl port type. an action may be explicitly or implicitly associated with the corresponding wsdl definition. section 3.3 below describes the mechanisms of association. finally, if in addition to the [action] property, a soap action uri is encoded in a request, the uri of the soap action must be the same as the one specified by the [action] property.
[message id] : uri (0..1)
a uri that uniquely identifies this message in time and space. no two messages with a distinct application intent may share a [message id] property. a message may be retransmitted for any purpose including communications failure and may use the same [message id] property. the value of this property is an opaque uri whose interpretation beyond equivalence is not defined in this specification. if a reply is expected, this property must be present.
[relationship] : (qname, uri) (0..unbounded)
a pair of values that indicate how this message relates to another message. the type of the relationship is identified by a qname. the related message is identified by a uri that corresponds to the related message's [message id] property. the message identifier uri may refer to a specific message, or be the following well-known uri that means "unspecified message:"
http://schemas.xmlsoap.org/ws/2004/08/addressing/id/unspecified
this specification has one predefined relationship type:
qname description
wsa:reply indicates that this is a reply to the message identified by the uri.
a reply message must contain a [relationship] property consisting of wsa:reply and the message id property of the request message.
the dispatching of incoming messages is based on two message properties. the mandatory "destination" and "action" fields identify the target processing location and the verb or intent of the message.
due to the range of network technologies currently in wide-spread use (e.g., nat, dhcp, firewalls), many deployments cannot assign a meaningful global uri to a given endpoint. to allow these "anonymous" endpoints to initiate message exchange patterns and receive replies, ws-addressing defines the following well-known uri for use by endpoints that cannot have a stable, resolvable uri.
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
requests whose [reply endpoint], [source endpoint] and/or [fault endpoint] use this address must provide some out-of-band mechanism for delivering replies or faults (e.g. returning the reply on the same transport connection). this mechanism may be a simple request/reply transport protocol (e.g., http get or post). this uri may be used as the [destination] for reply messages and should not be used as the [destination] in other circumstances.
3.1 message information headers xml infoset representation
the message information header blocks provide end-to-end characteristics of a message that can be easily secured as a unit. the information in these headers is immutable and not intended to be modified along the message path.
the following describes the contents of the message information header blocks:
<wsa:messageid> xs:anyuri </wsa:messageid>
<wsa:relatesto relationshiptype="..."?>xs:anyuri</wsa:relatesto>
<wsa:to>xs:anyuri</wsa:to>
<wsa:action>xs:anyuri</wsa:action>
<wsa:from>endpoint-reference</wsa:from>
<wsa:replyto>endpoint-reference</wsa:replyto>
<wsa:faultto>endpoint-reference</wsa:faultto>
the following describes the attributes and elements listed in the schema overview above:
/wsa:messageid
this optional element (of type xs:anyuri) conveys the [message id] property. this element must be present if wsa:replyto or wsa:faultto is present.
/wsa:relatesto
this optional (repeating) element information item contributes one abstract [relationship] property value, in the form of a (uri, qname) pair. the [children] property of this element (which is of type xs:anyuri) conveys the [message id] of the related message. this element must be present if the message is a reply.
/wsa:relatesto/@relationshiptype
this optional attribute (of type xs:qname) conveys the relationship type as a qname. when absent, the implied value of this attribute is wsa:reply.
/wsa:replyto
this optional element (of type wsa:endpointreferencetype) provides the value for the [reply endpoint] property. this element must be present if a reply is expected. if this element is present, wsa:messageid must be present.
/wsa:from
this optional element (of type wsa:endpointreferencetype) provides the value for the [source endpoint] property.
/wsa:faultto
this optional element (of type wsa:endpointreferencetype) provides the value for the [fault endpoint] property. if this element is present, wsa:messageid must be present.
/wsa:to
this required element (of type xs:anyuri) provides the value for the [destination] property.
/wsa:action
this required element of type xs:anyuri conveys the [action] property. the [children] of this element convey the value of this property.
3.2 formulating a reply message
the reply to a ws-addressing compliant request message must be compliant to ws-addressing and be constructed according to the rules defined in this section.
the following example illustrates a request message using message information header blocks in a soap 1.2 message:
<s:envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:f123="http://www.fabrikam123.example/svc53">
<s:header>
<wsa:messageid>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff
</wsa:messageid>
<wsa:replyto>
<wsa:address>http://business456.example/client1</wsa:address>
</wsa:replyto>
<wsa:to s:mustunderstand="1">mailto:[email protected]</wsa:to>
<wsa:action>http://fabrikam123.example/mail/delete</wsa:action>
</s:header>
<s:body>
<f123:delete>
<maxcount>42</maxcount>
</f123:delete>
</s:body>
</s:envelope>
this message would have the following property values:
[destination] the uri mailto:[email protected]
[reply endpoint] the endpoint with [address] http://business456.example/client1
[action] http://fabrikam123.example/mail/delete
[message id] uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff
the following example illustrates a reply message using message information header blocks in a soap 1.2 message:
<s:envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:f123="http://www.fabrikam123.example/svc53">
<s:header>
<wsa:messageid>
uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwwwww
</wsa:messageid>
<wsa:relatesto>
uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff
</wsa:relatesto>
<wsa:to s:mustunderstand="1">
http://business456.example/client1
</wsa:to>
<wsa:action>http://fabrikam123.example/mail/deleteack</wsa:action>
</s:header>
<s:body>
<f123:deleteack/>
</s:body>
</s:envelope>
this message would have the following property values:
[destination] http://business456.example/client1
[action] http://fabrikam123.example/mail/deleteack
[message id] uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwww
[relationship] (wsa:reply, uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff)
3.3 associating action with wsdl operations
ws-addressing defines two mechanisms to associate an action with input, output and fault elements within a wsdl port type.
3.3.1 explicit association
the action may be explicitly associated using the wsa:action attribute or in the absence of the attribute the action is defined by the rule in section 3.3.2.
for example consider the following wsdl excerpt:
<definitions targetnamespace="http://example.com/stockquote" ...>
...
<porttype name="stockquoteporttype">
<operation name="getlasttradeprice">
<input message="tns:gettradepricesinput"
wsa:action="http://example.com/getquote"/>
<output message="tns:gettradepricesoutput"
wsa:action="http://example.com/quote"/>
</operation>
</porttype>
...
</definitions>
the action for the input of the getlasttradeprice operation within the stockquoteporttype is explicitly defined to be http://example.com/getquote. the action for the output of this same operation is http://example.com/quote.
3.3.2 default action pattern
in the absence of the wsa:action attribute, the following pattern is used to construct a default action for inputs and outputs. the general form of an action uri is as follows:
[target namespace]/[port type name]/[input|output name]
the "/" is a literal character to be included in the action. the values of the properties are as defined below.
[target namespace] is the target namespace (/definition/@targetnamespace). if [target namespace] ends with a "/" an additional "/" is not added.
[port type name] is the name of the port type (/definition/porttype/@name).
[input|output name] is the name of the element as defined in section 2.4.5 of wsdl 1.1.
for fault messages, this pattern is not applied. instead, the following uri is the default action uri for fault messages:
http://schemas.xmlsoap.org/ws/2004/08/addressing/fault
for example consider the following wsdl excerpt:
<definitions targetnamespace="http://example.com/stockquote" ...>
...
<porttype name="stockquoteporttype">
<operation name="getlasttradeprice">
<input message="tns:gettradepricesinput" name="getquote"/>
<output message="tns:gettradepricesoutput" name="quote"/>
</operation>
</porttype>
...
</definitions>
[targetnamespace] = http://example.com/stockquote
[port type name] = stockquoteporttype
[input name] = getquote
[output name] = quote
applying the pattern above with these values we have:
input action = http://example.com/stockquote/stockquoteporttype/getquote
output action = http://example.com/stockquote/stockquoteporttype/quote
wsdl defines rules for a default input or output name if the name attribute is not present. consider the following example:
for example consider the following wsdl excerpt:
<definitions targetnamespace="http://example.com/stockquote" ...>
...
<porttype name="stockquoteporttype">
<operation name="getlasttradeprice">
<input message="tns:gettradepricesinput"/>
<output message="tns:gettradepricesoutput"/>
</operation>
</porttype>
...
</definitions>
[targetnamespace] = http://example.com/stockquote
[port type name] = stockquoteporttype
according to the rules defined in wsdl 2.4.5, if the name attribute is absent for the input of a request response operation the default value is the name of the operation "request" appended.
[input name] = getlasttradepricerequest
likewise, the output defaults to the operation name with "response" appended.
[output name] = getlasttradepriceresponse
applying the pattern above with these values we have:
input action =
http://example.com/stockquote/stockquoteporttype/getlasttradepricerequest
output action =
http://example.com/stockquote/stockquoteporttype/getlasttradepriceresponse
4. faults
the faults defined in this section are generated if the condition stated in the preamble in each subsection is met. they are sent to the [fault endpoint], if present and valid. otherwise they are sent to the [reply endpoint] if present. if neither is present faults may be sent to the [source endpoint].
endpoints compliant with this specification must include required message information headers on all fault messages. fault messages are correlated as replies using the [relationship] property as defined in section 3. the [action] property below designates ws-addressing fault messages (this uri is also used as default action value for wsdl fault messages, as described in section 3.3.2):
http://schemas.xmlsoap.org/ws/2004/08/addressing/fault
the definitions of faults use the following properties:
[code] the fault code.
[subcode] the fault subcode.
[reason] the english language reason element.
[detail] the detail element. if absent, no detail element is defined for the fault.
the properties above bind to a soap 1.2 fault as follows:
<s:envelope>
<s:header>
<wsa:action>
http://schemas.xmlsoap.org/ws/2004/08/addressing/fault
</wsa:action>
<!-- headers elided for clarity. -->
</s:header>
<s:body>
<s:fault>
<s:code>
<s:value>[code]</s:value>
<s:subcode>
<s:value>[subcode]</s:value>
</s:subcode>
</s:code>
<s:reason>
<s:text xml:lang="en">[reason]</s:text>
</s:reason>
<s:detail>
[detail]
</s:detail>
</s:fault>
</s:body>
</s:envelope>
the soap 1.1 fault is less expressive and map only [subcode] and [reason]. these the properties bind to a soap 1.1 fault as follows:
<s11:envelope>
<s11:body>
<s11:fault>
<faultcode>[subcode]</faultcode>
<faultstring xml:lang="en">[reason]</faultstring>
</s11:fault>
</s11:body>
</s11:envelope>
4.1 invalid message information header
a message information header cannot be processed.
[code] s:sender
[subcode] wsa:invalidmessageinformationheader
[reason] a message information header is not valid and the message cannot be processed. the validity failure can be either structural or semantic, e.g. a [destination] that is not a uri or a [relationship] to a [message id] that was never issued.
[detail] [invalid header]
4.2 message information header required
a required message information header is absent.
[code] s:sender
[subcode] wsa:messageinformationheaderrequired
[reason] a required message information header, to, messageid, or action, is not present.
[detail] [missing header qname]
4.3 destination unreachable
the no endpoint can be found capable of acting in the role of the [destination] property.
[code] s:sender
[subcode] wsa:destinationunreachable
[reason] no route can be determined to reach the destination role defined by the ws-addressing to.
[detail] empty
4.4 action not supported
the [action] property in the message is not supported at this endpoint.
the contents of this fault are as follows:
[code] s:sender
[subcode] wsa:actionnotsupported
[reason] the [action] cannot be processed at the receiver.
[detail] [action]
4.5 endpoint unavailable
the endpoint is unable to process the message at this time either due to some transient issue or a permanent failure.
the endpoint may optionally include a retryafter parameter in the detail. the source should not retransmit the message until this duration has passed.
[code] s:receiver
[subcode] wsa:endpointunavailable
[reason] the endpoint is unable to process the message at this time.
[detail]
<wsa:retryafter ...>[xs:nonnegativeinteger]</wsa:retryafter>
the following describes the attributes and elements listed above:
/wsa:retryafter
this element (of type xs:nonnegativeinteger) is a suggested minimum duration in milliseconds to wait before retransmitting the message. if this element is omitted from the detail, the value is infinite.
/wsa:retryafter/@{any}
these optional extensibility attributes do not affect processing.
5. security considerations
it is strongly recommended that the communication between services be secured using the mechanisms described in ws-security [ws-security]. in order to properly secure messages, the body and all relevant headers need to be included in the signature. specifically, the message information headers described in this specification (e.g. <wsa:to>) need to be signed with the body in order to "bind" the two together. it should be noted that for messages traveling through intermediaries, it is possible that some or all of the message information headers may have multiple signatures when the message arrives at the ultimate receiver. it is strongly recommended that the initial sender include a signature to prevent any spoofing by intermediaries.
whenever an address is specified (e.g. <wsa:from>, <wsa:replyto>, <wsa:faultto>, ...), the processor should ensure that a signature is provided with claims allowing it to speak for the specified target in order to prevent certain classes of attacks (e.g. redirects). as well, care should be taken if the specified endpoint contains resource properties or parameters as unverified endpoint references could cause certain classes of header insertion attacks.
the message information headers blocks may have their contents encrypted in order to obtain end-to-end privacy, but care should be taken to ensure that intermediary processors have access to required information (e.g. <wsa:to>).
some processors may use message identifiers (<wsa:messageid>) as part of a uniqueness metric in order to detect replays of messages. care should be taken to ensure that a unique identifier is actually used. for example, it may be appropriate in some scenarios to combine the message identifier with a timestamp.
the following list summarizes common classes of attacks that apply to this protocol and identifies the mechanism to prevent/mitigate the attacks:
message alteration – alteration is prevented by including signatures of the message information using ws-security.
message disclosure – confidentiality is preserved by encrypting sensitive data using ws-security.
address spoofing – address spoofing is prevented by ensuring that all address are signed by a party authorized to speak for (or on behalf of) the address.
key integrity – key integrity is maintained by using the strongest algorithms possible (by comparing secured policies – see ws-policy [ws-policy] and ws-securitypolicy [ws-securitypolicy]).
authentication – authentication is established using the mechanisms described in ws-security and ws-trust [ws-trust]. each message is authenticated using the mechanisms described in ws-security.
accountability – accountability is a function of the type of and strength of the key and algorithms being used. in many cases, a strong symmetric key provides sufficient accountability. however, in some environments, strong pki signatures are required.
availability – all reliable messaging services are subject to a variety of availability attacks. replay detection is a common attack and it is recommended that this be addressed by the mechanisms described in ws-security and/or caching of message identifiers. other attacks, such as network-level denial of service attacks are harder to avoid and are outside the scope of this specification. that said, care should be taken to ensure that minimal state is saved prior to any authenticating sequences.
replay – messages may be replayed for a variety of reasons. to detect and eliminate this attack, mechanisms should be used to identify replayed messages such as the timestamp/nonce outlined in ws-security. alternatively, and optionally, other technologies, such as sequencing, can also be used to prevent replay of application messages.
6. acknowledgements
keith ballinger, microsoft; michael coulson, microsoft; giovanni della-libera, microsoft; christopher ferris, ibm; tom freund, ibm; steve graham, ibm; christoph hofmann, sap; maryann hondo, ibm; efim hudis, microsoft; john ibbotson, ibm; gopal kakivaya, microsoft; al lee, microsoft; anthony nadalin, ibm; bill nagy, ibm; martin nally, ibm; henrik frystyk nielsen, microsoft; jeffrey schlimmer, microsoft; vladimir savchenko, sap; chris sharp, ibm; keith stobie, microsoft; vladimir videlov, sap; volker wiechers, sap; hervey wilson, microsoft;
7. references
[rfc 2119]
s. bradner, "key words for use in rfcs to indicate requirement levels," rfc 2119, harvard university, march 1997.
[rfc 2396]
t. berners-lee, et al, "uniform resource identifier (uri): generic syntax," rfc 2396bis, w3c/mit, july 2004.
[xml 1.0]
w3c recommendation "extensible markup language (xml) 1.0 (second edition)", tim bray, jean paoli, c. m. sperberg-mcqueen, eve maler, 6 october 2000
[xml namespaces]
w3c recommendation "namespaces in xml", tim bray, dave hollander, andrew layman, 14 january 1999
[xml infoset]
w3c recommendation "xml information set", john cowan, richard tobin, 24 october 2001
[xml schema, part 1]
h. thompson, et al, "xml schema part 1: structures," may 2001.
[xml schema, part 2]
p. biron, et al, "xml schema part 2: datatypes," may 2001.
[soap 1.2]
m. gudgin, et al, "soap version 1.2 part 1: messaging framework," june 2003.
[wsdl 1.1]
e. christensen, et al, "web services description language (wsdl) 1.1," march 2001.
[ws-security]
oasis, "web services security: soap message security", march 2004.
[ws-securitypolicy]
g. della-libera, et al, "web services security policy language (ws-securitypolicy)," december 2002.
[ws-trust]
s. anderson, et al, "web services trust language (ws-trust)," may 2004.
[ws-policy]
d. box, et al, "web services policy framework (ws-policy)," may 2003.
