Expressing Requirements and Capabilities for Web Services

1 September 2004

Jeffrey Schlimmer and Kyle Young, Microsoft Corporation

Legal Statement

Microsoft hereby grants to the W3C, permission to copy, display and distribute this Expressing Requirements and Capabilities for Web Services Paper (the "Paper") in any medium without fee or royalty, provided that the W3C includes the entirety of this Statement on ALL copies of the Paper.

EXCEPT FOR THE COPYRIGHT LICENSE GRANTED ABOVE, MICROSOFT DOES NOT GRANT, EITHER EXPRESSLY OR IMPLIEDLY, A LICENSE TO ANY INTELLECTUAL PROPERTY, INCLUDING PATENTS, THEY OWN OR CONTROL.

THIS DOCUMENT AND ITS CONTENTS ARE PROVIDED "AS IS." MICROSOFT AND ITS AFFILIATES MAKE NO WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR OR INTENDED PURPOSE, TITLE, NON-INFRINGEMENT, ACCURACY, COMPLETENESS, RESULTS, LACK OF VIRUSES, LACK OF NEGLIGENCE, LACK OF ERRORS, AND SUITABILITY FOR ANY PURPOSE.

MICROSOFT AND ITS AFFILIATES WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, OR SPECIAL DAMAGES, WHETHER UNDER CONTRACT, TORT, WARRANTY, OR OTHERWISE, ARISING FROM OR RELATED TO THIS DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF, INCLUDING, BUT NOT LIMITED TO, THE COST OF PROCURING SUBSTITUTE GOODS OR SERVICES, LOSS OF PROFITS, LOSS OF USE, OR LOSS OF DATA, EVEN IF MICROSOFT OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES IN ADVANCE.

Introduction

Web services is an architecture developed in response to business requirements for interoperable systems in heterogeneous and distributed computing environments. The core of this architecture is Messages exchanged between Services, where SOAP Messages were chosen as the only intercommunication mechanism, and Services are defined as network-addressable entities that send and receive Messages.

This architecture includes a collection of components, each defining Messages exchanged. Prime examples of these components include security [WS-Security 2004, WS-Federation, WS-SecureConversation, WS-Trust], reliable messaging [WS-Addressing, WS-ReliableMessaging], and transactions [WS-Coordination, WS-AtomicTransaction]. These components may be used independently or collectively to enable various Service messaging capabilities and requirements.

Web services are being successfully used in interoperable solutions across the industry. One of the key reasons for interest and investment in Web services is that they are well suited to enable service-oriented systems. Based on early success, developers and customers are looking to solve increasingly difficult problems using Web services. This drives the need for more capabilities from the Web services architecture.

XML-based technologies such as XML Schema, WSDL, and SOAP provide a broadly-adopted foundation on which to build interoperable Web services. The recently re-published Web services specifications WS-Policy [WS-Policy] and WS-PolicyAttachment [WS-PolicyAttachment] extend this foundation with a new mechanism of choice to represent Web service capabilities / requirements as Policies. Policies provide functionality that helps automate the operation of Web services and are a novel mechanism to implement and deploy Web services.

Contracts

Service orientation avoids the tight-coupling issues that plague earlier distributed systems, like platform dependence, all-at-once deployment, and brittle versioning. To avoid these issues, some Service behavior must be hidden; obvious examples include Service implementation details like the programming model, object references, and in-memory representations. This is simply applying the concept of information hiding, learned initially in abstract data types and later in object-oriented systems, to distributed computing. However, to enable interoperability with other Services, some Service behavior must be visible; examples include Message interchange formats, Message Exchange Patterns (MEPs), Service capabilities / requirements, and Message semantics. Service orientation differs from other applications of information hiding in its choice of which details are hidden versus visible; sharing a well-designed set of shared assumptions across Services is the basis for interoperability across a broader range of environments, scenarios, and platforms.

A "Contract" is an expression of visible aspects of Service behavior. A Contract is represented by a mixture of machine-readable languages and human language. Besides the obvious opportunity for additional precision, machine-readable languages enable tooling to construct partial Service implementations, automate Service deployment, audit/validate Messages exchanged, manage Services, and enable a host of other network-related functions. However, due to limitations in the expressive power of machine-readable languages, human languages remain an important component of Contracts, principally to describe Message and MEP semantics.

Interoperability is correct interaction between Services, i.e., the correct exchange of Messages. A Contract enables interoperability by describing valid Message exchanges, but in a less-obvious manner, a Contract also enables interoperability by hiding private Service behaviors. As an enabler, even if a Contract were represented entirely in human language, Services could interoperate (as indeed they did before the invention of XML Schema and WSDL); the most obvious downside to such an approach is that Service behavior and network-related functions would have to be built by hand.

As the diagram below illustrates, Contract is a logical subset of general metadata. In the current state of the art, a Contract is represented by two machine-readable languages. First, XML Schema is used to represent Message interchange formats; within the SOAP message model, this equates to representing the SOAP Body and SOAP Header blocks; as the diagram illustrates, XML Schema has applicability beyond this use. Second, WSDL is used to represent MEPs, currently basic one-way and back-and-forth MEPs. Both XML Schema and WSDL have extensive tooling suites, which in large part accounts for their popularity.

Contract is a logical subset of general metadata

Capabilities and Requirements

Service capabilities and requirements are a third component of Contract that represent aspects or cross-cutting concerns not naturally expressed in Message interchange formats or MEPs, for example, whether a Message must be secured (and how), whether a Message is to be delivered reliably (and how), and whether a Message is transacted (and how). WS-Policy [WS-Policy] provides a new machine-readable language for representing Service capabilities / requirements as Policies. A Policy is a collection of Alternatives. Each Alternative represents an independent and consistent set of capabilities / requirements, that is, a valid way to interact with the Service. For example, if a Service is capable of providing either transport- or message-level security, then its Policy would have (at least) two Alternatives.

Within each Alternative, Assertions represent individual capabilities / requirements. For example, one Assertion may represent transport-level security and another may represent message-level security.

WS-Policy [WS-Policy] defines a carefully-chosen, simple set of mechanisms to express Alternatives in a compact form, to reference named Policies, and to determine the compatibility between Web service Policies. Specifications that define Web service capabilities / requirements also define corresponding Assertions [e.g., WS-AtomicTransaction, WS-ReliableMessaging, WS-SecurityPolicy]. WS-PolicyAttachment [WS-PolicyAttachment] defines several ways to associate Policy with a Service. A common approach will be to embed Policy within the WSDL for the Service; this has the advantage that various WSDL constructs can be used to indicate the applicability of Policy, specifically, whether a Policy applies to an endpoint as a whole or to a specific message.

Example

The WSDL specification introduced the StockQuote example to illustrate how to represent Message interchange formats and MEPs. Below is an extension of that example to illustrate how WS-Policy [WS-Policy] and WS-PolicyAttachment [WS-PolicyAttachment] can represent service capabilities and requirements, specifically, to indicate that clients must support:

Message-level security [WS-Security 2004] using either an X.509 certificate or username and password,
Reliable messaging [WS-ReliableMessaging], and
Transactions [WS-AtomicTransaction].

Ellipses indicate uninteresting content that has been omitted.

(01) <definitions name="StockQuote"

xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/08/policy"

xmlns:p="http://schemas.xmlsoap.org/ws/2002/12/policy"

xmlns:wsat="http://schemas.xmlsoap.org/ws/2003/09/wsat"

xmlns:wsrm="http://schemas.xmlsoap.org/ws/2004/03/rm"

xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"

xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"

... >

(02) <wsp:UsingPolicy wsdl:Required="true" />

(03) <wsp:Policy wsu:Id="SRT" >

(04) <p:SpecVersion URI="http://schemas.xmlsoap.org/ws/2002/07/secext" />

(05) <wsp:ExactlyOne>

(06) <wsse:SecurityToken>

(07) <wsse:TokenType>wsse:X509v3</wsse:TokenType>

</wsse:SecurityToken>

(08) <wsse:SecurityToken>

(09) <wsse:TokenType>wsse:UsernameToken</wsse:TokenType>

</wsse:SecurityToken>

</wsp:ExactlyOne>

(10) <p:SpecVersion URI="http://schemas.xmlsoap.org/ws/2004/03/rm" />

(11) <wsrm:SequenceCreation />

(12) <wsrm:BaseRetransmissionInterval Milliseconds="3000" />

(13) <p:SpecVersion URI="http://schemas.xmlsoap.org/ws/2003/09/wsat" />

(14) <wsp:ExactlyOne>

(15) <wsat:VolatileTwoPhaseCommit />

(16) <wsat:DurableTwoPhaseCommit />

</wsp:ExactlyOne>

</wsp:Policy>

(17) <wsp:Policy wsu:Id="EncryptSubscribeHeader" >

(18) <wsse:Confidentiality>

(19) <wsse:Algorithm Type="wsse:AlgEncryption"

URI="http://www.w3.org/2001/04/xmlenc#3des-cbc" />

(20) <wsse:KeyInfo>

(21) <xenc:EncryptedKey />

</wsse:KeyInfo>

(22) <wsse:MessageParts

Dialect="http://schemas.xmlsoap.org/2002/12/wsse#part" >

p:Header(tns:SubscribeHeader)

</wsse:MessageParts>

</wsse:Confidentiality>

</wsp:Policy>

...

(23) <binding name="StockQuoteSoapBinding"

type="tns:StockQuotePortType" >

(24) <wsoap:binding style="document"

transport="http://schemas.xmlsoap.org/soap/http" />

(25) <wsp:PolicyReference URI="#SRT" />

(26) <operation name="GetLastTradePrice" >

(27) <wsoap:operation soapAction="http://example.com/GetLastTradePrice" />

(28) <input>

(29) <wsoap:body use="literal" />

(30) <wsoap:header message="tns:SubscribeToQuotes"

part="subscribeheader"

use="literal"/>

(31) <wsp:PolicyReference URI="#EncryptSubscribeHeader" />

</input>

...

</operation>

</binding>

...

</definitions>

Line (02) indicates that the WSDL is extended using WS-Policy; in this particular example, each of the provided bindings uses WS-Policy, and the WSDL should not be processed without understanding WS-Policy, so @wsdl:Required = "true".

Line (03) is a policy expression that applies to a binding as a whole. It expresses requirements for security (Lines 04-09), reliability (Lines 10-12), and transactions (Lines 13-16); this policy is named using @wsu:Id for convenient reference from a binding, e.g., see Line (25).

Security starts with Line (04) which is a generic assertion that indicates support for a specification, identified by URI, is required; in this case, WS-Security is required. Line (05) is a choice between assertions defined in WS-SecurityPolicy that indicate an X.509 security token (Lines 06-07) or a username and password (Lines 08-09).

Reliability starts with Line (10), indicating support for WS-ReliableMessaging is required; the assertion in Line (11) indicates that the RM destination is responsible for creating RM sequences, and the assertion in Line (12) is a parameterized assertion indicating that the RM source will wait 3 seconds for an acknowledgement before retransmitting Messages. These latter assertions are defined in WS-ReliableMessaging.

Transactions starts with Line (13), indicating support for WS-AtomicTransaction; Line (14) is a choice between assertions defined in WS-AtomicTransaction that indicate volatile two phase commit (Line 15) or durable two phase commit (Line 16).

Taken as a whole, the policy in Line (03) has four valid alternatives corresponding to combinations of the choices in Line (05) and (14).

Line (17) lists policy that applies to a specific input message; it too is named using @wsu:Id. The assertion in Line (18) is defined in WS-SecurityPolicy and indicates encryption using DES (Line 19), with a symmetric key protected by a token (Lines 05-09), of the Subscribe SOAP header (Line 22). (We assume the Subscribe SOAP header allows for encrypted content.) Using the Integrity assertion [WS-SecurityPolicy], the policy could also indicate that the Subscribe header must signed; this is omitted from the example for simplicity.

Line (23) is a typical binding to SOAP (Line 24). Line (25) attaches the policy in Line (03) to this binding, requiring secure, reliable, transacted messaging.

Line (26) lists the GetLastTradePrice Message Exchange Pattern. Line (29) defines the SOAP Body for the input message using the existing SOAP binding; Line (30) defines a SOAP header block; Line (31) attaches the policy in Line (17) to this message, requiring the header to be encrypted. (The output Message is not shown.)

This example illustrates how a Web service could indicate its security, reliable messaging, and transaction capabilities and requirements within WSDL. In the future, we anticipate exploring issues such as P3P policy and attaching policies to arbitrary policy subjects, perhaps using XPath domain expressions.

7. Acknowledgements

We would like to thank the following people for their contributions towards this article: Luis Felipe Cabrera, Tim Ewald, Chris Kaler, Chris Kurt, Omri Gazitt, Martin Gudgin, and Doug Walter.