Web Services Addressing 1.0 - SOAP Binding (2024)

Example1-1. Use of message addressing properties in a SOAP 1.2message.

(01) <S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://www.w3.org/2005/08/addressing">(02) <S:Header>(03) <wsa:MessageID>http://example.com/6B29FC40-CA47-1067-B31D-00DD010662DA</wsa:MessageID>(04) <wsa:ReplyTo>(05) <wsa:Address>http://example.com/business/client1</wsa:Address>(06) </wsa:ReplyTo>(07) <wsa:To>http://example.com/fabrikam/Purchasing</wsa:To>(08) <wsa:Action>http://example.com/fabrikam/SubmitPO</wsa:Action>(09) </S:Header>(10) <S:Body>(11) ...(12) </S:Body>(13) </S:Envelope>

Lines (02) to (09) represent the header of the SOAP messagewhere the mechanisms defined in the specification are used. Thebody is represented by lines (10) to (12).

Lines (03) to (08) contain the message addressing propertiesserialized as SOAP header blocks. Specifically, line (03) specifiesthe identifier for this message and lines (04) to (06) specify theendpoint to which replies to this message should be sent as anEndpoint Reference. Line (07) specifies the address URI of theultimate receiver of this message. Line (08) specifies an actionURI identifying expected semantics.

1.1 NotationalConventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALLNOT", "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 usesthe 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 specificationuses the notational convention of WS-Security [WS-Security]. Specifically, each memberof an element's [children] or [attributes] property is describedusing an XPath-like notation (e.g.,/x:MyHeader/x:SomeProperty/@value1). The use of {any} indicates thepresence 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 prefixesthroughout; they are listed in Table 1-1.Note that the choice of any namespace prefix is arbitrary and notsemantically significant (see [XMLNamespaces]).

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 Messaging Framework] processingmodel and is also compatible with SOAP 1.1[SOAP 1.1] for backwards compatibility.WS-Addressing may be used with WSDL [WSDL2.0 Core Language] described services as described inWeb Services Addressing 1.0 - WSDL Binding[WS-Addressing WSDL Binding]. The examplesin this specification use an XML 1.0 [XML1.0] representation but this is not a requirement.

All information items defined by this specification areidentified by the XML namespace URI [XMLNamespaces] http://www.w3.org/2005/08/addressing.A normative XML Schema [XML SchemaStructures, XML SchemaDatatypes] document can be obtained by dereferencing theXML namespace URI.

2.1 FeatureName

The SOAP 1.2 Addressing 1.0 Feature is named using the followingURI:

• http://www.w3.org/2005/08/addressing/feature

2.2Description

The SOAP 1.2 Addressing 1.0 Feature provides a SOAP-specificexpression of the abstract message addressing properties defined byWeb Services Addressing 1.0 - Core[WS-Addressing Core].

This feature may be used with any SOAP MEP. A binding thatsupports this feature MUST provide a means to transmit theproperties listed below with a message and to reconstitute theirvalues on receipt of a message.

2.3Properties

The SOAP 1.2 Addressing 1.0 Feature defines the followingproperties:

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

Corresponds to the abstract [destination] property.

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

Corresponds to the abstract [source endpoint] property.

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

Corresponds to the abstract [reply endpoint] property.

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

Corresponds to the abstract [fault endpoint] property.

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

Corresponds to the abstract [action] property.

http://www.w3.org/2005/08/addressing/feature/MessageID

Corresponds to the abstract [message id] property.

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

Corresponds to the abstract [relationship] property.

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

Corresponds to the abstract [reference parameters] property.

2.4 Interactions with Other SOAPFeatures

If the http://www.w3.org/2003/05/soap/features/action/Actionproperty of the SOAP Action feature[SOAP 1.2 Adjuncts] has a value, then thevalue of the http://www.w3.org/2005/08/addressing/feature/Actionproperty of the SOAP 1.2 Addressing 1.0 feature MUST be identicalto it. Failure to have an identical value results in an InvalidAddressing Header fault (see 6.4.1Invalid Addressing Header).

3.1 ModuleName

The SOAP 1.2 Addressing 1.0 Module is identified using thefollowing URI:

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

3.2Description

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 theabstract message addressing properties defined by Web ServicesAddressing 1.0 - Core[WS-AddressingCore]. The SOAP 1.2 Addressing 1.0 Module defines SOAPheaders corresponding to the XML Infoset representation of theabstract message addressing properties defined in Web ServicesAddressing 1.0 - Core.

3.3Additional Infoset Items

The SOAP 1.2 Addressing 1.0 Module defines the followingadditional XML Infoset items:

/[referenceparameters]/@wsa:IsReferenceParameter

This REQUIRED attribute (of type xs:boolean) signifies whetherthe message addressing header is a reference parameter, see section3.4 Binding Message AddressingProperties for more details on its use.

3.4 Binding MessageAddressing Properties

When a message is to be addressed to an endpoint, the XMLInfoset representation of each message addressing property that hasbeen assigned a value is inserted into the message as a SOAP headerblock subject to the following additional constraints:

• The value, if any, of the [reference parameters] property isadded to the SOAP message header: the element information item ofeach of the [reference parameters] (including all of its[children], [attributes] and [in-scope namespaces]) is added as aSOAP header block in the new message.

  Note:

  The insertion of SOAP headers into a message implies particularsemantics. Since the reference parameter mechanism does notrestrict the content of the generated headers, EPR suppliers shouldexercise appropriate caution to ensure their reference parametersdo not cause unintended or erroneous semantics in the resultantSOAP message. For example, using a reference parameter to send aWS-Security[WS-Security]header would be ill-advised (since other parts of the SOAPinfrastructure will often control this header, and there must be atmost one of them per message).

• Each header block added as a result of the above rule isannotated with a wsa:IsReferenceParameter attribute (see 3.3 Additional Infoset Items) whosevalue is a valid xs:boolean representation of "true". Any existingwsa:IsReferenceParameter attribute on the header block isreplaced.

  Note:

  Integrity validation of [reference parameters] needs to takeinto account the addition of wsa:IsReferenceParameter attributesand the corresponding introduction of the WS-Addressing namespaceto the [in-scope namespaces]

• The value of each message addressing property that is of typeIRI MUST be serialized as an absolute IRI in the corresponding SOAPheader block. No additional %-escaping is performed.

• Each optional element or attribute that has a value equal to thedefined default value for that element or attribute MAY beomitted.

The following example shows how the SOAP 1.2 Addressing 1.0Module is used to construct a message addressed to theendpoint:

<wsa:EndpointReference xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:wsaw="http://www.w3.org/2006/02/addressing/wsdl" xmlns:fabrikam="http://example.com/fabrikam" xmlns:wsdli="http://www.w3.org/2006/01/wsdl-instance" wsdli:wsdlLocation="http://example.com/fabrikam http://example.com/fabrikam/fabrikam.wsdl"> <wsa:Address>http://example.com/fabrikam/acct</wsa:Address> <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>

The address value is copied in the "To" header block and the"CustomerKey" and "ShoppingCart" elements are copied literally as aheader blocks in a SOAP message addressed to this endpoint. Theresulting 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/08/addressing" xmlns:fabrikam="http://example.com/fabrikam"> <S:Header> ... <wsa:To>http://example.com/fabrikam/acct</wsa:To> <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>

3.5Relationship between SOAP Headers and transport-levelproperties

Some underlying protocols may support native properties similarto the Message Addressing Properties. For example, the reply-to:email header is similar to the [reply endpoint] Message AddressingProperty. Authors and implementors of bindings should not assumeany particular correspondence between native properties and MessageAddressing Properties. For example, if an email message representsonly one hop in a multi-hop path, then the reply-to: header islikely to differ from the [reply endpoint] address.

4.1 ExtensionName

The SOAP 1.1 Addressing 1.0 Extension is identified using thefollowing URI:

• http://www.w3.org/2005/08/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 theabstract message addressing properties defined by Web ServicesAddressing 1.0 - Core[WS-AddressingCore]. The SOAP 1.1 Addressing 1.0 Extension uses theXML Infoset representation of the abstract message addressingproperties defined in Web Services Addressing 1.0 - Core and bindseach element information item to a SOAP header block. The SOAP 1.1Addressing 1.0 Extension operates as described in 3. SOAP 1.2 Addressing 1.0 Module with thefollowing exceptions:

SOAP Action

Use of the SOAPAction HTTP request header field is required whenusing the SOAP 1.1 HTTP binding. The field-value of the SOAPActionHTTP request header MUST either be the value of the [action]property enclosed in quotation marks, or the empty value "". Thelatter case supports the ability to obscure the [action] propertythrough SOAP-level security mechanisms, without requiring otherwiseunnecessary transport-level security. Any other value forSOAPAction results in an Invalid Message Addressing Property fault(see 6.4.1 Invalid AddressingHeader).

5.1 Use of AnonymousAddress in SOAP Response Endpoints

A value of "http://www.w3.org/2005/08/addressing/anonymous" forthe [destination] property implies no additional semantics beyondthose resulting from the rules defined below and as described inWeb Services Addressing 1.0 - Core[WS-Addressing Core]. In particular, notethat Web Services Addressing 1.0 - Core[WS-Addressing Core], section 3.4 requiressuch a value in messages sent to a response endpoint whose[address] is "http://www.w3.org/2005/08/addressing/anonymous".

5.2 Use ofNon-Anonymous Addresses in SOAP Response Endpoints

http://www.w3.org/2005/08/addressing/fault 

http://www.w3.org/2005/08/addressing/soap/fault

6.1 SOAP 1.2 FaultBinding

The fault properties bind to a SOAP 1.2 fault as follows:

[Code]

The value of the [Code] property is bound as the value of theSOAP faults S:Fault/S:Code/S:Value element information item.

[Subcode]

The value of the [Subcode] property is bound as the value of theSOAP faults S:Fault/S:Code/S:Subcode/S:Value element informationitem.

[Subsubcode]

The value of the [Subsubcode] property is bound as the value ofthe SOAP faults S:Fault/S:Code/S:Subcode/S:/Subcode/S:Value elementinformation item.

[Reason]

The value of the [Reason] property is bound as the value of theSOAP faults S:Fault/S:Reason/S:Text element information item.

See Also

SOAP Web Services Tutorial: What is SOAP Protocol? EXAMPLE

[Details]

The value of the [Details] property is bound as child elementsof the SOAP faults S:Fault/S:Detail element information item.

<S:Envelope> <S:Header> <wsa:Action>http://www.w3.org/2005/08/addressing/fault</wsa:Action> <!-- Headers elided for brevity. --> </S:Header> <S:Body> <S:Fault> <S:Code> <S:Value>[Code]</S:Value> <S:Subcode> <S:Value>[Subcode]</S:Value> <S:Subcode> <S:Value>[Subsubcode]</S:Value> </S:Subcode> </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> 

6.2 SOAP 1.1 FaultBinding

The SOAP 1.1 fault is slightly less expressive than the SOAP 1.2fault and maps only [Subcode], [Reason] and [Detail]. These theproperties bind to a SOAP 1.1 fault as follows:

[Subcode] or [Subsubcode]

The value of the [Subsubcode] or, if that is not specified, thevalue of the [Subcode] property is bound as the value of the SOAPfaults S11:Fault/faultcode element.

[Reason]

The value of the [Reason] property is bound as the value of theSOAP faults S11:Fault/faultstring element.

[Details]

The SOAP 1.1 fault detail is only for use with faults related tothe body of a message and is therefore not used for SOAP 1.1 faultsrelated to processing of addressing headers. Instead the value ofthe [Details] property is bound as the value of a newwsa:FaultDetail SOAP header block. The following describes thewsa:FaultDetail element:

/wsa:FaultDetail

Zero or more of the elements defined in 6.3 Fault Detail Elements.

/wsa:FaultDetail/@{any}

Optional extensibility attributes including SOAP role andmustUnderstand.

<S11:Envelope> <S11:Header> <wsa:Action>http://www.w3.org/2005/08/addressing/fault</wsa:Action> <wsa:FaultDetail>[Details]</wsa:FaultDetail> <!-- Other headers elided for brevity. --> </S11:Header> <S11:Body> <S11:Fault> <faultcode>[Subcode] or [Subsubcode]</faultcode> <faultstring xml:lang="en">[Reason]</faultstring> </S11:Fault> </S11:Body></S11:Envelope> 

6.3Fault Detail Elements

The following subsections define a set of elements used toconvey additional information in the faults described in 6.4 Predefined Faults.

6.4 PredefinedFaults

Note:

No assumptions are made herein of the application level securityrequirement, the organization of the application, implementation ofsenders or receivers, or of the ways that other protocols may makeuse of WS-Addressing, and what security mechanisms they may employ.A holistic approach to security which considers all components ofthe application, other protocols utilized, the way that theseprotocols compose with WS-Security, and the use of other methods oradditional techniques is highly recommended.

7.1 Establishing EPRTrust

There are many mechanisms that could be used to supply proofthat a message sender has authority to represent the [address] ofEPRs supplied within the message. Typically such mechanisms requirethe inclusion of a WS-Security[WS-Security] header that contains XMLdigital signatures binding the wsa:ReplyTo and wsa:FaultTo elementsto the SOAP message using a security token issued by an authoritytrusted by the receiver of the message for the domain of the[address] of the EPR. Possession of a security token issued by atrusted authority for the domain of the [address] of the EPRprovides a level of confidence that the message sender hasauthority to represent the [address].

For example, a message could include aWS-Security[WS-Security]header that contains XML digital signatures binding the wsa:ReplyToand wsa:FaultTo elements to the SOAP message using an X.509certificate for the domain addressed by the [address] of the EPR.If the certificate is issued by a certificate authority trusted bythe receiver of the message then the receiver can have some levelof confidence that the message sender has authority to representthe [address] of the EPR.

7.2 Additional SecurityConsiderations

The wsa:isReferenceParameter attribute is only meaningful onSOAP headers. Message processors should consider its appearanceelsewhere in a SOAP message as a possible attack.

Message processors should consider elements from the soap11,soap12 and wsa namespaces appearing as reference parameters in anEPR as a possible attack.

There are known XML ID and re-structuring attacks which shouldbe considered by message processors, see [WS-Security] - Security Considerations:Removal and modification of XML elements.

7.3 AdditionalConsiderations for SOAP Intermediaries

To avoid breaking signatures, intermediaries MUST NOT change theXML representation of WS-Addressing headers when relaying thoseheaders. Specifically, intermediaries MUST NOT remove XML contentthat explicitly indicates otherwise-implied content, andintermediaries MUST NOT insert XML content to make implied valuesexplicit. For instance, if a RelationshipType attribute is presentwith a value of "http://www.w3.org/2005/08/addressing/reply", anintermediary MUST NOT remove it; similarly, if there is noRelationshipType attribute, an intermediary MUST NOT add one.

Note:

Web Services Addressing 1.0 - WSDL Binding[WS-Addressing WSDL Binding] definesadditional conformance requirements for the description of anendpoint.

Note:

Endpoints MAY accept and respond to messages which contain noWSA headers.

9.1 Normative References

[IETF RFC2119]

Key wordsfor use in RFCs to Indicate Requirement Levels, S.Bradner, Author. Internet Engineering Task Force, June 1999.Available at http://www.ietf.org/rfc/rfc2119.txt.

[IETF RFC3987]

Internationalized ResourceIdentifiers (IRIs) M. Duerst, and M. Suignard, Authors.Internet Engineering Task Force, January 2005. Available athttp://www.ietf.org/rfc/rfc3987.txt.

[SOAP 1.1]

Simple ObjectAccess Protocol (SOAP) 1.1, D. Box, et al, Editors.World Wide Web Consortium, 8 May 2000. Available athttp://www.w3.org/TR/2000/NOTE-SOAP-20000508/.

[SOAP 1.2 Messaging Framework]

SOAP Version1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley,N. Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World WideWeb Consortium, 24 June 2003. This version of the SOAP Version 1.2Part 1: Messaging Framework Recommendation ishttp://www.w3.org/TR/2003/REC-soap12-part1-20030624/. The latest version of SOAP Version1.2 Part 1: Messaging Framework is available athttp://www.w3.org/TR/soap12-part1/.

[SOAP 1.2 Adjuncts]

SOAP Version1.2 Part 2: Adjuncts, M. Gudgin, M. Hadley, N.Mendelsohn, J-J. Moreau, H. Frystyk Nielsen, Editors. World WideWeb Consortium, 24 June 2003. This version of the SOAP Version 1.2Part 2: Adjuncts Recommendation ishttp://www.w3.org/TR/2003/REC-soap12-part2-20030624/. The latest version of SOAP Version1.2 Part 2: Adjuncts is available athttp://www.w3.org/TR/soap12-part2/.

[WS-Addressing Core]

Web ServicesAddressing 1.0 - Core, M. Gudgin, M. Hadley, and T.Rogers, Editors. World Wide Web Consortium, 9 May 2006. Thisversion of the WS-Addressing Core Recommendation ishttp://www.w3.org/TR/2006/REC-ws-addr-core-20060509. The latest version of WS-AddressingCore is available at http://www.w3.org/TR/ws-addr-core.

[XML 1.0]

Extensible MarkupLanguage (XML) 1.0 (Third Edition), T. Bray, J. Paoli,C. M. Sperberg-McQueen, and E. Maler, Editors. World Wide WebConsortium, 4 February 2004. This version of the XML 1.0Recommendation is http://www.w3.org/TR/2004/REC-xml-20040204. Thelatest version of XML1.0 is available at http://www.w3.org/TR/REC-xml.

[XMLNamespaces]

Namespaces inXML, T. Bray, D. Hollander, and A. Layman, Editors.World Wide Web Consortium, 14 January 1999. This version of the XMLInformation Set Recommendation ishttp://www.w3.org/TR/1999/REC-xml-names-19990114. The latest version of Namespacesin XML is available at http://www.w3.org/TR/REC-xml-names.

[XMLInformation Set]

XMLInformation Set (Second Edition), J. Cowan and R. Tobin,Editors. World Wide Web Consortium, 4 February 2004. This versionof the XML Information Set Recommendation ishttp://www.w3.org/TR/2004/REC-xml-infoset-20040204. The latest version of XMLInformation Set is available athttp://www.w3.org/TR/xml-infoset.

[XMLSchema Structures]

XML SchemaPart 1: Structures Second Edition, H. Thompson, D.Beech, M. Maloney, and N. Mendelsohn, Editors. World Wide WebConsortium, 28 October 2004. This version of the XML Schema Part 1Recommendation ishttp://www.w3.org/TR/2004/REC-xmlschema-1-20041028. The latest version of XML SchemaPart 1 is available at http://www.w3.org/TR/xmlschema-1.

[XMLSchema Datatypes]

XML SchemaPart 2: Datatypes Second Edition, P. Byron and A.Malhotra, Editors. World Wide Web Consortium, 28 October 2004. Thisversion of the XML Schema Part 2 Recommendation ishttp://www.w3.org/TR/2004/REC-xmlschema-2-20041028. The latest version of XML SchemaPart 2 is available at http://www.w3.org/TR/xmlschema-2.

9.2 Other References

[SOAP1.1 Request Optional Response HTTP Binding]

SOAP1.1 Request Optional Response HTTP Binding, D. Orchard,Editor. World Wide Web Consortium, 21 March 2006. This version ofthe SOAP 1.1 Request Optional Response HTTP Binding specificationis http://www.w3.org/TR/2006/NOTE-soap11-ror-httpbinding-20060321/.The latestversion of SOAP 1.1 Request Optional Response HTTP Binding isavailable http://www.w3.org/TR/soap11-ror-httpbinding.

[WS-Addressing WSDL Binding]

Web ServicesAddressing 1.0 - WSDL Binding, M. Gudgin, M. Hadley, T.Rogers, Ü. Yalçinalp, Editors. World Wide Web Consortium, 16February 2006. This version of the WS-Addressing WSDL Bindingspecification ishttp://www.w3.org/TR/2006/WD-ws-addr-wsdl-20060216. The latest version of WS-AddressingWSDL Binding is available athttp://www.w3.org/TR/ws-addr-wsdl.

[WSDL 2.0 CoreLanguage]

Web ServicesDescription Language (WSDL) Version 2.0 Part 1: CoreLanguage, R. Chinnici, J. J. Moreau, A. Ryman, and S.Weerawarana, Editors. World Wide Web Consortium, 27 March 2006.This version of the WSDL 2.0 specification ishttp://www.w3.org/TR/2006/CR-wsdl20-20060327. The latest version of WSDL 2.0 isavailable at http://www.w3.org/TR/wsdl20.

[WS-Security]

Web Services Security: SOAP Message Security 1.0 (WS-Security2004), A. Nadalin, C. Kaler, P. Hallam-Baker, R.Monzillo, Editors. Organization for the Advancement of StructuredInformation Standards, March 2004.