Web Services Addressing provides transport-neutral mechanisms to address Web services and messages. Web Services Addressing SOAP Binding (this document) defines the binding of the abstract properties defined in Web Services Addressing Core to SOAP Messages.
This is the
In this Working Draft, the Web Services Addressing Working Group
has, in keeping with its
Discussion of this document takes place on the public public
This document was produced under the
Per
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
Last Modified: $Date: 2004/12/08 21:28:59 $
Web Services Addressing Core
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:
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.
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 [
When describing abstract data models, this specification uses the notational
convention used by XML Infoset [
When describing concrete XML schemas [
This specification uses a number of namespace prefixes throughout; they are
listed in
| Prefix | Namespace |
|---|---|
| S | http://www.w3.org/2003/05/soap-envelope |
| S11 | http://schemas.xmlsoap.org/soap/envelope |
| wsa | http://www.w3.org/2004/12/addressing |
| xs | http://www.w3.org/2001/XMLSchema |
WS-Addressing is defined in terms of the XML Information Set [
All information items defined by WS-Addressing are identified by the XML
namespace URI [
This section defines the binding of Endpoint references to SOAP messages.
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] message information property. The infoset representation of the [destination] property becomes a header block in 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:
According to the mapping rules stated above, 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:
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 the default Action value for WSDL fault messages, as described in Section 3.3.2):
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:
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:
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]
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]
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
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]
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:
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.
These optional extensibility attributes do not affect processing.
It is strongly recommended that the communication between services be secured using
the mechanisms described in WS-Security [
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 reference 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.
Authentication – Authentication may be established 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.
TBD
Placeholder for automatic change log generation