2005-03-31 diff-marked version: Web Services Addressing 1.0 - SOAP Binding

<a name="_Toc77464315" id="_Toc77464315"> 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 [ IETF RFC 2119 ].

When describing abstract data models, this specification uses the notational convention used by XML Infoset [ XML Information Set ]. Specifically, abstract property names always appear in square brackets (e.g., [some property]).

When describing concrete XML schemas [ XML Schema Structures , XML Schema Datatypes ], 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/>).

<a name="_Toc77464316" id="_Toc77464316"> 1.2 Namespaces

This specification uses a number of namespace prefixes throughout; they are listed in Table 1-1 . Note that the choice of any namespace prefix is arbitrary and not semantically significant (see [ XML Namespaces ]).

WS-Addressing is defined in terms of the XML Information Set [ XML Information Set ]. WS-Addressing is conformant to the SOAP 1.2 [ SOAP 1.2 Part 1: Messaging Framework ] processing model and is also compatible with SOAP 1.1[ SOAP 1.1 ] for backwards compatibility. WS-Addressing may be used with WSDL [ WSDL 2.0 ] described services as described in Web Services Addressing 1.0 - WSDL Binding[ WS-Addressing-WSDL ]. 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 this specification are identified by the XML namespace URI [ XML Namespaces ] "http://www.w3.org/2005/02/addressing". "http://www.w3.org/2005/03/addressing". A normative XML Schema [ XML Schema Structures , XML Schema Datatypes ] document can be obtained by dereferencing the XML namespace URI.

2.1 Feature Name

The SOAP 1.2 Addressing 1.0 Feature is named using the following IRI:

• When http://www.w3.org/2005/03/addressing/feature

2.2 Description

The SOAP 1.2 Addressing 1.0 Feature provides a SOAP-specific expression of the abstract message needs to addressing properties defined by Web Services Addressing 1.0 - Core[ WS-Addressing-Core ].

This feature may be addressed used with any SOAP MEP. A binding that supports this feature MUST provide a means to transmit the endpoint, properties listed above with a message and to reconstitute their values on receipt of a message.

2.3 Properties

The SOAP 1.2 Addressing 1.0 Feature defines the information contained in following properties:

http://www.w3.org/2005/03/addressing/feature/Destination

Corresponds to the endpoint reference is mapped abstract [destination] property.

http://www.w3.org/2005/03/addressing/feature/SourceEndpoint

Corresponds to the message according abstract [source endpoint] property.

http://www.w3.org/2005/03/addressing/feature/ReplyEndpoint

Corresponds to deleted text: a transformation that is dependent on the protocol and data representation used abstract [reply endpoint] property.

http://www.w3.org/2005/03/addressing/feature/FaultEndpoint

Corresponds to deleted text: send the message. Protocol-specific mappings (or bindings) will define how abstract [fault endpoint] property.

http://www.w3.org/2005/03/addressing/feature/MessageId

Corresponds to the information in abstract [message id] property.

http://www.w3.org/2005/03/addressing/feature/Relationship

Corresponds to the endpoint reference is copied abstract [relationship] property.

http://www.w3.org/2005/03/addressing/feature/ReferenceParameters

Corresponds to deleted text: message and protocol fields. This specification defines the abstract [reference parameters] property.

http://www.w3.org/2005/03/addressing/feature/Action

Corresponds to the abstract [action] property.

2.4 Interactions with Other SOAP binding for endpoint references. This mapping MAY be explicitly replaced by other bindings (defined as WSDL bindings or as policies); however, in Features

If the absence http://www.w3.org/2003/05/soap/features/action/Action property of an applicable policy stating that the SOAP Action feature SOAP 1.2 Part 2: Adjuncts has a different mapping must be used, value, then the value of the http://www.w3.org/2005/03/addressing/feature/Action property of the SOAP binding defined here is assumed 1.2 Addressing 1.0 feature MUST be identical to apply. it.

3.1 Module Name

The SOAP binding for endpoint references 1.2 Addressing 1.0 Module is defined by identified using the following three rules: IRI:

• http://www.w3.org/2005/03/addressing/module

3.2 Description

The [address] property in the endpoint reference is copied in SOAP 1.2 Addressing 1.0 Feature (see 2. SOAP 1.2 Addressing 1.0 Feature ) defines a set of SOAP properties and their correspondence to the [destination] abstract message information property. addressing properties defined by Web Services Addressing 1.0 - Core[ WS-Addressing-Core ]. The infoset SOAP 1.2 Addressing 1.0 Module uses the XML Infoset representation of the [destination] abstract message addressing properties defined in Web Services Addressing 1.0 - Core.

When sending a message each property becomes is represented using the appropriate element information item as a SOAP header block block. The resulting header blocks are targetted at the ultimate recipient in the SOAP message. message path (note that extensions to WS-Addressing could be written to specify different targetting). 3.3 Binding Message Addressing Properties describes additional processing required when binding message addressing properties to SOAP header blocks.

Each [reference parameter] When receiving a message, the abstract properties are populated from their corresponding element becomes information items in the message. Note that the message addressing properties gathered by an intermediary when receiving a SOAP message do not necessarily get replayed as MAPs when resending the message along the message path.

3.3 Binding Message Addressing Properties

When a message is be addressed to an endpoint, the values of the SOAP 1.2 Addressing 1.0 Feature properties are mapped to the message as SOAP header block in blocks with the following additional modifications:

• The value of the http://www.w3.org/2005/03/addressing/feature/ReferenceParameters property is added to the SOAP message. message header. The element information item of each [reference parameter] (including all of its [children], [attributes] and [in-scope namespaces]) is deleted text: to be added as a SOAP header block in the new message.

• Each header block added as a result of the above rule is annotated with a wsa:Type wsa:isReferenceParameter attribute whose value is "parameter". "true".

• Each property that is of type IRI MUST be serialized as an absolute IRI in the SOAP message.

The next following example shows how the deleted text: default SOAP binding for endpoint references 1.2 Addressing 1.0 Module is used to construct a message addressed to the endpoint:

<wsa:EndpointReference


     xmlns:wsa="http://www.w3.org/2005/02/addressing"



     xmlns:wsa="http://www.w3.org/2005/03/addressing"


     xmlns:fabrikam="http://example.com/fabrikam"
     xmlns:wsdli="http://www.w3.org/2004/08/wsdl-instance"
     wsdli:wsdlLocation="http://example.com/fabrikam
       http://example.com/fabrikam/fabrikam.wsdl">
   <wsa:Address>http://example.com/fabrikam/acct</wsa:Address>


   <wsa:InterfaceName>fabrikam:Inventory</wsa:InterfaceName>




   <wsa:Metadata>
       <wsaw:InterfaceName>fabrikam:Inventory</wsaw:InterfaceName>
   <wsa:Metadata>


   <wsa:ReferenceParameters>
       <fabrikam:CustomerKey>123456789</fabrikam:CustomerKey>
       <fabrikam:ShoppingCart>ABCDEFG</fabrikam:ShoppingCart>
   </wsa:ReferenceParameters>
</wsa:EndpointReference>

According to the mapping rules stated above, the The address value is copied in the "To" header block and the "CustomerKey" and "ShoppingCart" elements should be are copied literally as a header blocks in a SOAP message addressed to this endpoint. The resulting SOAP message would look as follows:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"


         xmlns:wsa="http://www.w3.org/2005/02/addressing"



         xmlns:wsa="http://www.w3.org/2005/03/addressing"


         xmlns:fabrikam="http://example.com/fabrikam">
   <S:Header>
     ...
    <wsa:To>http://example.com/fabrikam/acct</wsa:To>


    <fabrikam:CustomerKey wsa:Type='parameter'>123456789</fabrikam:CustomerKey>
    <fabrikam:ShoppingCart wsa:Type='parameter'>ABCDEFG</fabrikam:ShoppingCart>



    <wsa:Action>...</wsa:Action>
    <fabrikam:CustomerKey wsa:isReferenceParameter='true'>123456789</fabrikam:CustomerKey>
    <fabrikam:ShoppingCart wsa:isReferenceParameter='true'>ABCDEFG</fabrikam:ShoppingCart>


     ...
   </S:Header>
   <S:Body>
     ...
   </S:Body>
</S:Envelope>

4.1 Extension Name

The SOAP 1.1 Addressing 1.0 Extension is identified using the following IRI:

• http://www.w3.org/2005/03/addressing/module

4.2 Description

The SOAP 1.2 Addressing 1.0 Feature (see 2. SOAP 1.2 Addressing 1.0 Feature ) defines a set of SOAP properties and their correspondence to the abstract message addressing properties defined by Web Services Addressing 1.0 - Core[ WS-Addressing-Core ]. The SOAP 1.1 Addressing 1.0 Extension uses the XML Infoset representation of the abstract message addressing properties defined in Web Services Addressing 1.0 - Core and binds each element information item to a SOAP header block. The SOAP 1.1 Addressing 1.0 Extension operates as described in 3. SOAP 1.2 Addressing 1.0 Module with the following exceptions:

SOAP Action

Use of the SOAPAction HTTP header is required when using the SOAP 1.1 HTTP binding. The value of the SOAPAction HTTP header SHOULD be identical to the value of the http://www.w3.org/2005/03/addressing/feature/Action property of the Web Services Addressing 1.0 feature.

<a name="_Toc77464329" id="_Toc77464329"> 3.1 5.1 Invalid Message Information Header Addressing Property

A message information header property cannot be processed.

[Code] S:Sender

[Subcode] wsa:InvalidMessageInformationHeader wsa:InvalidMessageAddressingProperty

[Reason] A message information header addressing property 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 an IRI or a [relationship] to a [message id] that was never issued.

[Detail] [invalid header] property]

<a name="_Toc77464330" id="_Toc77464330"> 3.2 5.2 Message Information Header Addressing Property Required

A required message information header addressing property is absent.

[Code] S:Sender

[Subcode] wsa:MessageInformationHeaderRequired wsa:MessageAddressingPropertyRequired

[Reason] A required message information header, To, MessageID, or Action, addressing property is not present.

[Detail] [Missing Header Property QName]

<a name="_Toc77464331" id="_Toc77464331"> 3.3 5.3 Destination Unreachable

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. [destination].

[Detail] empty

<a name="_Toc55895108" id="_Toc55895108"> 3.4 5.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]

<a name="_Toc77464333" id="_Toc77464333"> 3.5 5.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) 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.

Editorial note: M Hadley
The WG seeks feedback on the choice of nonNegativeInteger for this element. Other types considered included unsignedLong, unsignedInt and duration.

/wsa:RetryAfter/@{any}

These optional Optional extensibility attributes that do not affect processing.

6.1 Additional Considerations for (or on behalf of) the address. </p> </li> </ul> <ul> <li> <p> Key integrity – Key integrity is maintained by using the strongest algorithms possible (by comparing secured policies. </p> </li> </ul> <ul> <li> <p> Authentication – Authentication may be established using the mechanisms described in WS-Security. </p> </li> </ul> <ul> <li> SOAP Intermediaries

Accountability – Accountability is a function of To avoid breaking signatures, intermediaries MUST NOT change the type of and strength XML representation of the key WS-Addressing headers. Specifically, intermediaries MUST NOT remove XML content that explicitly indicates otherwise-implied content, and algorithms being used. In many cases, a strong symmetric key provides sufficient accountability. However, in some environments, strong PKI signatures are required. </p> </li> </ul> <ul> <li> <p> Availability – All reliable messaging services are subject intermediaries MUST NOT insert XML content to make implied values explicit. For instance, if a variety of availability attacks. Replay detection RelationshipType attribute is present with 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 value of this specification. That said, care should be taken to ensure that minimal state "http://www.w3.org/2005/03/addressing/reply", an intermediary MUST NOT remove it; similarly, if there is saved prior to any authenticating sequences. </p> </li> </ul> <ul> <li> <p> 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. no RelationshipType attribute, an intermediary MUST NOT add one.