An Example Web Services Scenario

Let’s look at a typical Web Services scenario. We’ll use the well-worn stock-ordering example, which is something of a “hello world” for Web Services. The initial scenario is shown in Figure 1-1.

Figure 1-1: Business case for Web Services transaction

UDDI

In Figure 1-1, company A wishes to make use of the stock ordering system that is provided by company B. The first step in a services-oriented architecture is for company A to find out about company B’s Web Services. This is achieved in this case by using UDDI. Later, in a dedicated chapter, we will discuss UDDI security. UDDI sometimes gets a bad reputation. There is a perception that it is used to publish services to the entire world, allowing anybody to connect to the UDDI registry, find a Web Service published by a previously unknown company, and bind to it. This clearly does not match real-world business scenarios, in which business is rarely done between complete strangers—especially in the absence of credential checks such as credit worthiness. But this view does UDDI a disservice. Most uses of UDDI involve cases where the transacting parties already know each other. It provides a way to publish information about newly available Web Services, or to provide information about a Web Service whose interface has changed. In addition, UDDI is useful inside an organization (that is, “behind the firewall”) in order to publish information used by internal applications to bind to each other using SOAP. UDDI security is discussed in Chapter 13.

An example UDDI enquiry is shown in Listing 1-4.

Listing 1-4

<find_business generic='1.0' xmlns='urn:uddi-org:api'>     <name>Company B</name> </find_business>

Figure 1-2: Company A retrieves WSDL data for company B’s Web Service

Continuing with our example, Figure 1-2 shows company A retrieving a document from company B that lists the Web Services provided by company B.

To keep this example simple, let’s assume that company B only has one Web Service. Therefore, the response from the UDDI repository will look like Listing 1-5.

Listing 1-5

<businessList generic="1.0" operator="Company B" truncated="false" xmlns="urn:uddi-org:api">    <businessInfos>       <businessInfo businessKey="cbfa05fb-277d-4b7e-a101-e6925b376c18">          <name>Company B</name>          <description xml:lang="en"> A leading provider of financial services          </description>       <serviceInfos>           <serviceInfo serviceKey="5f73eff6-7a85-41cf-99d9-66cda3a82e63"  businessKey="cbca05fb-277d-4b7e-a101-e6925b376c18">            <name>Stock Ordering Service</name>          </serviceInfo>       </serviceInfos>     </businessInfo>   </businessInfos> </businessList>

In Listing 1-5, we can see the serviceKey value for the stock ordering service. Company A can now use this serviceKey value to perform a query to get the binding information about the stock ordering service, using the XML in Listing 1-6.

Listing 1-6

<get_serviceDetail generic='1.0' xmlns='urn:uddi-org:api'>    <serviceKey>5f73eff6-7a85-41cf-99d9-66cda3a82e63</serviceKey> </get_serviceDetail>

The binding information retrieved from this get_serviceDetail message is shown in Listing 1-7.

Listing 1-7

<serviceDetail generic="1.0" operator="Company B" truncated="false"  xmlns="urn:uddi-org:api">    <businessService serviceKey="be1a0b34-e2f1-4f4b-dae6-258c338ae358"  businessKey="cbea05fb-277d-4b7e-a101-e6925b376c18">    <name>Stock Ordering Service</name>    <description xml:lang="en">NYSE and Nasdaq Stock Ordering Service.</ description>    <bindingTemplates>       <bindingTemplate serviceKey="be1a0b34-e2f1-4f4b-aae6-258c338ae358"  bindingKey="00cbd2b2-2333-4f85-b144-369be3d95f7c">         <description xml:lang="en">NASDAQ and NYSE Stock Ordering Service with  real-time trades.</description>         <accessPoint URLType="https">https://www.stockorder.com/Stock</ accessPoint>         <tModelInstanceDetails>           <tModelInstanceInfo tModelKey="uuid:64c756d1-3374-4e00-ae83-ee12e38fae63">             <description xml:lang="en">Stock Ordering Service.</description>           </tModelInstanceInfo>         </tModelInstanceDetails>       </bindingTemplate> <categoryBag>       <keyedReference tModelKey="uuid:a035a07c-f362-44dd-8f95-e2b134bf43b4"  keyName="KEYWORD" keyValue="STOCK"></keyedReference>     </categoryBag>   </businessService> </serviceDetail>

WSDL: Web Service Definition Language

Now company A is in possession of enough information to retrieve the WSDL information from company B, in order to construct a SOAP message to send to company B’s stock ordering service. The location of the Web Service can now be seen in the accessPoint element. The WSDL message is shown in Listing 1-8.

Listing 1-8

<?xml version="1.0"?> <definitions name="StockQuote"              targetNamespace="http://stockorder.com/stockorder.wsdl"              xmlns:tns="http://stockorder.com/stockquote.wsdl"              xmlns:xsd1="http://stockorder.com/stockquote.xsd"              xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap"              xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">     <wsdl:types>        <xsd:schema targetNamespace="https://www.stockorder.com/Stock"               xmlns:xsd="http://www.w3.org/2000/10/XMLSchema">            <xsd:element name="StockOrderRequest">               <xsd:complexType>                   <xsd:all>                      <xsd:element name="tickerSymbol" type="string"/>                      <xsd:element name="quantity" type="string"/>                      <xsd:element name="market" type="string"/>                   </xsd:all>               </xsd:complexType>            </xsd:element>        </xsd:schema>     </wsdl:types>     <!-- request StockOrder is of type StockOrderRequest -->     <wsdl:message name="GetLastTradePriceInput">         <wsdl:part name="body" element="xsd1:TradePriceRequest"/>     </wsdl:message>       <wsdl:portType name="StockOrderPortType">         <wsdl:operation name="StockOrder">            <wsdl:input message="tns:StockOrderRequest"/>            <wsdl:output message="tns:StockOrderRequest"/>         </wsdl:operation>     </wsdl:portType>     <wsdl:binding name="StockOrderSoapBinding"                   type="tns:StockOrderPortType">         <soap:binding style="document" transport="http:// schemas.xmlsoap.org/soap/http"/>         <wsdl:operation name="GetLastTradePrice">            <soap:operation soapAction="http://www.stockquote.com/ StockOrder"/>             <wsdl:input>                <soap:body use="literal"/>            </wsdl:input>            <wsdl:output>                <soap:body use="literal"/>            </wsdl:output>         </wsdl:operation>     </wsdl:binding> </wsdl:definitions>

As can be see in Listing 1-8, WSDL isn’t a language designed for general human comprehension. However, it gives a Web Services broker all the information necessary to construct a SOAP message. We see at the top of the message that it refers to the XML Schema for the Web Service. We also see at the top of the WSDL message that a number of namespaces are used. These namespaces are used so that there is no confusion caused by XML elements and attributes from different contexts having the same names. This would occur if, for example, the XML Schema for the StockQuote service had element names in common with the XML Schema for SOAP. Namespaces avoid this problem, and are familiar to software developers as a common feature of modern programming languages.

Examining a SOAP Message

At this stage, a SOAP message can be sent from company A to company B. This action is illustrated in Figure 1-3.

Figure 1-3: Company A sends a SOAP message to company B

Let’s have a look at the actual SOAP message that is sent. Listing 1-9 shows the SOAP message itself.

Listing 1-9

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header> </SOAP-ENV:Header> <SOAP-ENV:Body  <StockOrder:StockOrder xmlns:StockOrder="https://www.stockorder.com/Stock"> <StockOrder:symbol>SGP</StockOrder:symbol> <StockOrder:quantity>2000</StockOrder:quantity> <StockOrder:market>New York</StockOrder:market> </order:buy> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

The SOAP message in Listing 1-9 is quite a simple message, because all the parameters are basic SOAP string types. Note also that although Figure 1-3 shows security data included in the SOAP message. We’ve omitted it from the SOAP listing. We’ll see later in the book how WS-Security allows security information to be placed into SOAP messages. This security data can include security tokens to indicate the identity of the sender, and digital signatures to ensure that the SOAP message hasn’t changed since it was digitally signed. Note again the use of namespaces to protect against “collisions” in the data caused by identical element and attribute names across different XML Schemas.

Listing 1-9 also shows that SOAP messages have a header and a body. Information in the header concerns processing of the message. The payload of the message is contained in the body. Here we see that the header portion of the SOAP message is empty. This is because we’ve omitted the security data (for now). Because it is an XML-based language, SOAP is extensible. Many security initiatives have chosen to insert security information into the SOAP header. The SOAP body is more suited to payload data, and as we’ll see in the next section, this payload can be divided up if it is intended for more than one SOAP actor.

SOAP With Attachments (SWA) allows SOAP messages to include binary attachments, expressed using the same Multipart Internet Message Exchange (MIME) syntax as is used for e-mail. This addresses one of the early criticisms of SOAP, namely that it wasn’t suitable for binary information. ebXML makes use of SWA, as we’ll see in Chapter 13.

Routing SOAP Among Multiple Parties

In our simple example, company A sends a SOAP message directly to company B in order to bind to stock ordering functionality that has been published by company B. However, company A may wish to use additional services, all in the context of this one transaction. For example, company A may also want to use a Stockquote service, which may be published by a third party, prior to using the stock ordering service. Another scenario would be where company A wishes to run a portfolio update service after running the stock order service. This single SOAP message may be routed between more than one SOAP “actor” (note that in the SOAP 1.2 specification, “Actor” is replaced by “Role”—this is somewhat confusing for security, since “role” already has a definition in role-based access control). Each Web Service is responsible for certain portions of the message. If a certain actor must process certain elements in the header of the SOAP message (for example, a digital signature), the mustUnderstand attribute is set to true for these elements.

Note that the SOAP 1.1 specification from the W3C does not include information about how to route a SOAP message. More recent specifications, such as WS-Routing from Microsoft, address the area of routing, as does ebXML’s messaging specification. SOAP does, however, allow for portions of a SOAP message to be flagged as being appropriate for certain SOAP services. SOAP 1.2 incorporates routing, based on WS-Routing. This has implications for XML Proxies and XML Firewall applications, which may be required to honor routing information in SOAP messages. We will encounter XML Firewall functionality in the third case study in the Appendix.

Because SOAP messages can be routed between multiple SOAP roles, it is important that there are mechanisms to ensure that certain information cannot be seen (or manipulated) by intermediate roles before reaching their intended destination. That is why persistent security in the SOAP message itself is required.

SOAP Fault

After sending this SOAP message, company A’s Web Service broker will either receive a SOAP message in response, with content to indicate that the stock order was successful, or it will receive a SOAP Fault message. A SOAP Fault indicates that a problem occurred in the processing of the SOAP message.

A SOAP fault uses the Fault element, defined in SOAP 1.2 within the SOAP envelope namespace (“http://www.w3.org/2002/06/soap-envelope”), and defines the following five child elements:

• Code (mandatory) This element contains a subelement called “Value” that must include one of the SOAP fault codes defined at http://www.w3.org/TR/2002/WD-soap12-part1-20020626/#faultcodes. These are

  • VersionMismatch: This error code indicates that this version of SOAP is not supported. This error is appropriate if a Web Service only supports SOAP 1.2, and is sent a SOAP 1.1 message.

  • MustUnderstand: A SOAP header item was flagged as “MustUnderstand,” but the Web Service was not able to process the element.

  • DataEncodingUnknown: This error indicates that the Web Service was unable to deserialize the SOAP message.

  • Sender: This means that the data sent to the Web Service was incorrectly formed, or did not contain the appropriate information. This is the SOAP fault code that should be returned for a SOAP message that, for example, does not contain the appropriate security information.

  • Receiver: The message could not be processed for reasons attributable to the processing of the message rather than to the contents of the message itself. The error may be due to the failure of an upstream processor, such as an XML database which had run out of disk space.

• Reason This element expresses an error in human-readable text. All fault elements must include a Reason element. It is important that this text be useful and not something like “A fault occurred.” However, in the scenario where a message was blocked due to a security issue, it is important that this field does not give away information to an intruder that could be useful to attack the Web Service (for example, “username OK, password wrong” would be helpful for an attacker).

• Node (optional) SOAP messages can be routed among a number of SOAP nodes. The Node field indicates which of the SOAP applications along the message path notified the fault.

• Role (optional) The Role element information item identifies the role the node was operating in at the point the fault occurred.

• Detail This element is mandatory when part or all of the SOAP body could not be processed. This element is not intended for information about difficulties in processing information contained in the SOAP header.

Since this book focuses on Web Services security, Listing 1-10 shows an example of a SOAP Fault generated by an authentication failure on the part of the Web Services broker.

Listing 1-10

<?xml version="1.0" ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope">  <env:Header>   <upg:Upgrade xmlns:upg="http://www.w3.org/2002/06/soap-upgrade">    <envelope qname="ns1:Envelope"               xmlns:ns1="http://www.w3.org/2002/06/soap-envelope"/>    <envelope qname="ns2:Envelope"               xmlns:ns2="http://schemas.xmlsoap.org/soap/envelope/"/>   </upg:Upgrade>  </env:Header>  <env:Body>   <env:Fault>    <env:Code><env:Value>env:Server</env:Value></env:Code>     <env:Reason>Not authenticated</env:Reason>    </env:Fault>  </env:Body> </env:Envelope>

The Reason element portion is included in the Fault element because the error relates to the Body element.