Chapter 2 Introduction to WSIT

This tutorial describes how to use the Web Services Interoperability Technologies (WSIT), a product of Sun Microsystems web services interoperability effort to develop Java clients and service providers that interoperate with Microsoft .NET 3.0 clients and service providers.

What is WSIT?

Sun is working closely with Microsoft to ensure interoperability of web services enterprise technologies such as message optimization, reliable messaging, and security. The initial release of WSIT is a product of this joint effort. WSIT is an implementation of a number of open web services specifications to support enterprise features. In addition to message optimization, reliable messaging, and security, WSIT includes a bootstrapping and configuration technology. Figure 2–1 shows the underlying services that were implemented for each technology.

Figure 2–1 WSIT Web Services Features

Starting with the core XML support currently built into the Java platform, WSIT uses or extends existing features and adds new support for interoperable web services. See the following sections for an overview of each feature:

• Bootstrapping and Configuration

• Message Optimization Technology

• Reliable Messaging Technology

• Security Technology

Bootstrapping and Configuration

Bootstrapping and configuration consists of using a URL to access a web service, retrieving its WSDL file, and using the WSDL file to create a web service client that can access and consume a web service. The process consists of the following steps, which are shown in Figure 2–2.

Figure 2–2 Bootstrapping and Configuration

1. Client acquires the URL for a web service that it wants to access and consume. How you acquire the URL is outside the scope of this tutorial. For example, you might look up the URL in a Web Services registry.

2. The client uses the URL and the wsimport tool to send a MetadataExchangeRequest to access the web service and retrieve the WSDL file. The WSDL file contains a description of the web service endpoint, including WS-Policy assertions that describe the security and/or reliability capabilities and requirements of the service. The description describes the requirements that must be satisfied to access and consume the web service.

3. The client uses the WSDL file to create the web service client.

4. The web service client accesses and consumes the web service.

Chapter 4, Bootstrapping and Configuration explains how to bootstrap and configure a web service client and a web service endpoint that use the WSIT technologies.

Message Optimization Technology

A primary function of web services applications is to share data among applications over the Internet. The data shared can vary in format and include large binary payloads, such as documents, images, music files, and so on. When large binary objects are encoded into XML format for inclusion in SOAP messages, even larger files are produced. When a web service processes and transmits these large files over the network, the performance of the web service application and the network are negatively affected. In the worst case scenario the effects are as follows:

• The performance of the web service application degrades to a point that it is no longer useful.

• The network gets bogged down with more traffic than the allotted bandwidth can handle.

One way to deal with this problem is to encode the binary objects so as to optimize both the SOAP application processing time and the bandwidth required to transmit the SOAP message over the network. In short, XML needs to be optimized for web services. This is the exactly what the Message Optimization technology does. It ensures that web services messages are transmitted over the Internet in the most efficient manner.

Sun recommends that you use message optimization if your web service client or web service endpoint will be required to process binary encoded XML documents larger than 1KB.

For instructions on how to use the Message Optimization technology, see Chapter 5, Message Optimization.

Reliable Messaging Technology

Reliable Messaging is a Quality of Service (QoS) technology for building more reliable web services. Reliability is measured by a system’s ability to deliver messages from point A to point B without error. The primary purpose of Reliable Messaging is to ensure the delivery of application messages to web service endpoints.

The reliable messaging technology ensures that messages in a given message sequence are delivered at least once and not more than once and optionally in the correct order. When messages in a given sequence are lost in transit or delivered out of order, this technology enables systems to recover from such failures. If a message is lost in transit, the sending system retransmits the message until its receipt is acknowledged by the receiving system. If messages are received out of order, the receiving system may re-order the messages into the correct order.

The Reliable Messaging technology can also be used to implement session management. A unique message sequence is created for each client-side proxy, and the lifetime of the sequence identifier coincides with the lifetime of the proxy. Therefore, each message sequence can be viewed as a session and can be used to implement session management.

You should consider using reliable messaging if the web service is experiencing the following types of problems:

• Communication failures are occurring that result in the network being unavailable or connections being dropped

• Application messages are being lost in transit

• Application messages are arriving at their destination out of order and ordered delivery is a requirement

To help decide whether or not to use reliable messaging, weigh the following advantages and disadvantages:

• Enabling reliable messaging ensures that messages are delivered exactly once from the source to the destination and, if the ordered-delivery option is enabled, ensures that messages are delivered in order.

• Enabling reliable messaging causes a degradation of web service performance, especially if the ordered delivery option is enabled.

• Non-reliable messaging clients cannot interoperate with web services that have reliable messaging enabled.

For instructions on how to use the Reliable Messaging technology, see Chapter 6, Using Reliable Messaging.

Security Technology

Until now, web services have relied on transport-based security such as SSL to provide point-to-point security. WSIT implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing transport-level security, which may still be used.

WSIT also enhances security by implementing WS-Secure Conversation, which enables a consumer and provider to establish a shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use derived session keys that increase the overall security while reducing the security processing overhead for each message.

Further, WSIT implements two additional features to improve security in web services:

• Web Services Security Policy: Enables web services to use security assertions to clearly represent security preferences and requirements for web service endpoints.

• Web Services Trust: Enables web service applications to use SOAP messages to request security tokens that can then be used to establish trusted communications between a client and a web service.

WSIT implements these features in such a way as to ensure that web service binding security requirements, as defined in the WSDL file, can interoperate with and be consumed by WSIT and WCF endpoints.

For instructions on how to use the WS-Security technology, see Chapter 7, Using WSIT Security.

How WSIT Relates to Windows Communication Foundation (WCF)

Web services interoperability is an initiative of Sun and Microsoft. The goal is to produce web services consumers and producers that support platform independence, and then to test and deliver products to market that interoperate across different platforms.

WSIT is the product of Sun’s web services interoperability initiative. Windows Communication Foundation (WCF) is Microsoft’s unified programming model for building connected systems. WCF, which is now available as part of the .NET Framework 3.0 product, includes application programming interfaces (APIs) for building secure, reliable, transacted web services that interoperate with non-Microsoft platforms.

In a joint effort, Sun Microsystems and Microsoft are testing WSIT against WCF to ensure that Sun web service clients (consumers) and web services (producers) do in fact interoperate with WCF web services applications and vice versa. The testing will ensure that the following interoperability goals are realized:

• WSIT web services clients can access and consume WCF web services.

• WCF web services clients can access and consume WSIT web services.

Sun is building WSIT on the Java platform and Microsoft is building WCF on the .NET 3.0 platform. The sections that follow describe the web services specifications implemented by Sun Microsystems in Web Services Interoperability Technologies (WSIT) and provide high-level descriptions of how each WSIT technology works.

---

Note –

Because WSIT-based clients and services are interoperable, you can gain the benefits of WSIT without using WCF.

---

WSIT Specifications

The specifications for bootstrapping and configuration, message optimization, reliable messaging, and security technologies are discussed in the following sections:

• Bootstrapping and Configuration Specifications

• Message Optimization Specifications

• Reliable Messaging Specifications

• Security Specifications

WSIT 1.0 implements the specification versions listed in Table 2–1.

Table 2–1 WSIT Specification Versions

Technology	Version
Bootstrapping	WS-MetadataExchange v1.1
Reliable Messaging	WS-ReliableMessaging v1.0  WS-ReliableMessaging Policy v1.0
Atomic Transactions	WS-AtomicTransaction v1.0  WS-Coordination v1.0
Security	WS-Security v1.1  WS-SecurityPolicy v1.1  WS-Trust v1.0  WS-SecureConversation v1.0
Policy	WS-Policy v1.2  WS-PolicyAttachment v1.2

The same versions of these specifications are also implemented in WCF in .NET 3.0. Sun will update to the standard versions of these specifications in a future release of WSIT. Those versions will coincide with the versions used in WCF in .NET 3.5.

Bootstrapping and Configuration Specifications

Bootstrapping and configuring involves a client getting a web service URL (perhaps from a service registry) and obtaining the information needed to build a web services client that is capable of accessing and consuming a web service over the Internet. This information is usually obtained from a WSDL file. Figure 2–3 shows the specifications that were implemented to support bootstrapping and configuration.

Figure 2–3 Bootstrapping and Configuration Specifications

In addition to the Core XML specifications, bootstrapping and configuration was implemented using the following specifications:

• WSDL: The Web Services Description Language (WSDL) specification was previously implemented in JAX-WS. WSDL is a standardized XML format for describing network services. The description includes the name of the service, the location of the service, and ways to communicate with the service, that is, what transport to use. WSDL descriptions can be stored in service registries, published on the Internet, or both.

• Web Services Policy: This specification provides a flexible and extensible grammar for expressing the capabilities, requirements, and general characteristics of a web service. It provides the mechanisms needed to enable web services applications to specify policy information in a standardized way. However, this specification does not provide a protocol that constitutes a negotiation or message exchange solution for web Services. Rather, it specifies a building block that is used in conjunction with the WS-Metadata Exchange protocol. When applied in the web services model, policy is used to convey conditions on interactions between two web service endpoints. Typically, the provider of a web service exposes a policy to convey conditions under which it provides the service. A requester might use the policy to decide whether or not to use the service.

• Web Services Metadata Exchange: This specification defines a protocol to enable a consumer to obtain a web service’s metadata, that is, its WSDL and policies. It can be thought of as a bootstrap mechanism for communication.

Message Optimization Specifications

Message optimization is the process of transmitting web services messages in the most efficient manner. It is achieved in web services communication by encoding messages prior to transmission and then de-encoding them when they reach their final destination.

Figure 2–4 shows the specifications that were implemented to optimize communication between two web service endpoints.

Figure 2–4 Message Optimization Specifications

In addition to the Core XML specifications, optimization was implemented using the following specifications:

• SOAP: JAX Web Services currently supports the SOAP wire protocol. With SOAP implementations, client requests and web service responses are most often transmitted as Simple Object Access Protocol (SOAP) messages over HTTP to enable a completely interoperable exchange between clients and web services, all running on different platforms and at various locations on the Internet. HTTP is a familiar request-and response standard for sending messages over the Internet, and SOAP is an XML-based protocol that follows the HTTP request-and-response model. In SOAP 1.1, the SOAP portion of a transported message handles the following:

  • Defines an XML-based envelope to describe what is in the message and how to process the message.

  • Includes XML-based encoding rules to express instances of application-defined data types within the message.

  • Defines an XML-based convention for representing the request to the remote service and the resulting response.

    In SOAP 1.2 implementations, web service endpoint addresses can be included in the XML-based SOAP envelope, rather than in the transport header (for example in the HTTP transport header), thus enabling SOAP messages to be transport independent.

• Web Services Addressing: The Java APIs for W3C Web Services Addressing were first shipped with Java Web Services Developer’s Pack 2.0 (JWSDP 2.0). This specification defines a set of abstract properties and an XML Infoset representation that can be bound to a SOAP message so as to reference web services and to facilitate end-to-end addressing of endpoints in messages. A web service endpoint is an entity, processor, or resource that can be referenced and to which web services messages can be addressed. Endpoint references convey the information needed to address a web service endpoint. The specification defines two constructs: message addressing properties and endpoint references, that normalize the information typically provided by transport protocols and messaging systems in a way that is independent of any particular transport or messaging system. This is accomplished by defining XML tags for including web service addresses in the SOAP message, instead of the HTTP header. The implementation of these features enables messaging systems to support message transmission in a transport-neutral manner through networks that include processing nodes such as endpoint managers, firewalls, and gateways.

• Web Services Secure Conversation: This specification provides better message-level security and efficiency in multiple-message exchanges in a standardized way. It defines basic mechanisms on top of which secure messaging semantics can be defined for multiple-message exchanges and allows for contexts to be established and potentially more efficient keys or new key material to be exchanged, thereby increasing the overall performance and security of the subsequent exchanges.

• SOAP MTOM: The SOAP Message Transmission Optimization Mechanism (MTOM), paired with the XML-binary Optimized Packaging (XOP), provides standard mechanisms for optimizing the transmission and/or wire format of SOAP messages by selectively encoding portions of the SOAP message, while still presenting an XML Infoset to the SOAP application. This mechanism enables the definition of a hop-by-hop contract between a SOAP node and the next SOAP node in the SOAP message path so as to facilitate the efficient pass-through of optimized data contained within headers or bodies of SOAP messages that are relayed by an intermediary. Further, it enables message optimization to be done in a binding independent way.

Reliable Messaging Specifications

Reliability is measured by a system’s ability to deliver messages from point A to point B without error. Figure 2–5 shows the specifications that were implemented to ensure reliable delivery of messages between two web services endpoints.

Figure 2–5 Reliable Messaging Specifications

In addition to the Core XML specifications and supporting standards (Web Services Security and Web Services Policy, which are required building blocks), the reliability feature is implemented using the following specifications:

• Web Services Reliable Messaging: This specification defines a standardized way to identify, track, and manage the reliable delivery of messages between exactly two parties, a source and a destination, so as to recover from failures caused by messages being lost or received out of order. The specification is also extensible so it allows additional functionality, such as security, to be tightly integrated. The implementation of this specification integrates with and complements the Web Services Security, and the Web Services Policy implementations.

• Web Services Coordination: This specification defines a framework for providing protocols that coordinate the actions of distributed applications. This framework is used by Web Services Atomic Transactions. The implementation of this specification enables the following capabilities:

  • Enables an application service to create the context needed to propagate an activity to other services and to register for coordination protocols.

  • Enables existing transaction processing, workflow, and other coordination systems to hide their proprietary protocols and to operate in a heterogeneous environment.

  • Defines the structure of context and the requirements so that context can be propagated between cooperating services.

• Web Services Atomic Transactions: This specification defines a standardized way to support two-phase commit semantics such that either all operations invoked within an atomic transaction succeed or are all rolled back. Implementations of this specification require the implementation of the Web Services Coordination specification.

Security Specifications

Figure 2–6 shows the specifications implemented to secure communication between two web service endpoints and across intermediate endpoints.

Figure 2–6 Web Services Security Specifications

In addition to the Core XML specifications, the security feature is implemented using the following specifications:

• Web Services Security: This specification defines a standard set of SOAP extensions that can be used when building secure web services to implement message content integrity and confidentiality. The implementation provides message content integrity and confidentiality even when communication traverses intermediate nodes, thus overcoming a short coming of SSL. The implementation can be used within a wide variety of security models including PKI, Kerberos, and SSL and provides support for multiple security token formats, multiple trust domains, multiple signature formats, and multiple encryption technologies.

• Web Services Policy: This specification provides a flexible and extensible grammar for expressing the capabilities, requirements, and general characteristics of a web service. It provides a framework and a model for the expression of these properties as policies and is a building block for Web Services Security policy.

• Web Services Trust: This specification supports the following capabilities in a standardized way:

  • Defines extensions to Web Services Security that provide methods for issuing, renewing, and validating security tokens used by Web services security.

  • Establishes, assesses the presence of, and brokers trust relationships.

• Web Services Secure Conversation: This specification defines a standardized way to provide better message-level security and efficiency in multiple-message exchanges. The WSIT implementation provides basic mechanisms on top of which secure messaging semantics can be defined for multiple-message exchanges and allows for contexts to be established along with more efficient keys or new key material. This approach increases the overall performance and security of the subsequent exchanges. While the Web Services Security specification, described above, focuses on the message authentication model, it does leave openings for several forms of attacks. The Secure Conversation authentication specification defines a standardized way to authenticate a series of messages, thereby addressing the short comings of Web Services Security. With the Web Services Security Conversation model, the security context is defined as a new Web Services security token type that is obtained using a binding of Web Services Trust.

• Web Services Security Policy: This specification defines a standard set of patterns or sets of assertions that represent common ways to describe how messages are secured on a communications path. The WSIT implementation allows flexibility in terms of tokens, cryptography, and mechanisms used, including leveraging transport security, but is specific enough to ensure interoperability based on assertion matching by web service clients and web services providers.

How the WSIT Technologies Work

The following sections provide a high-level description of how the message optimization, reliable messaging, and security technologies work.

How Message Optimization Works

Message optimization ensures that web services messages are transmitted over the Internet in the most efficient manner. Because XML is a textual format, binary files must be represented using character sequences before they can be embedded in an XML document. A popular encoding that permits this embedding is known as base64 encoding, which corresponds to the XML Schema data type xsd:base64Binary. In a web services toolkit that supports a binding framework, a value of this type must be encoded before transmission and decoded before binding. The encoding and decoding process is expensive and the costs increase linearly as the size of the binary object increases.

Message optimization enables web service endpoints to identify large binary message payloads, remove the message payloads from the body of the SOAP message, encode the message payloads using an efficient encoding mechanism (effectively reducing the size of the payloads), re-insert the message payloads into the SOAP message as attachments (the file is linked to the SOAP message body by means of an Include tag). Thus, message optimization is achieved by encoding binary objects prior to transmission and then de-encoding them when they reach there final destination.

The optimization process is really quite simple. To effect optimized message transmissions, the sending endpoint checks the body of the SOAP message for XML encoded binary objects that exceed a predetermined size and encodes those objects for efficient transmission over the Internet.

SOAP MTOM, paired with the XML-binary Optimized Packaging (XOP), addresses the inefficiencies related to the transmission of binary data in SOAP documents. Using MTOM and XOP, XML messages are dissected in order to transmit binary files as MIME attachments in a way that is transparent to the application. This transformation is restricted to base64 content in canonical form as defined in XSD Datatypes as specified in XML Schema Part 2: Datatypes Second Edition, W3C Recommendation 28 October 2004.

Thus, the WSIT technology achieves message optimization through an implementation of the MTOM and XOP specifications. With the message optimization feature enabled, small binary objects are sent in-line in the SOAP body. For large binary objects, this becomes quite inefficient, so the binary object is separated from the SOAP body, encoded, sent as an attachment to the SOAP message, and decoded when it reaches its destination endpoint.

How Reliable Messaging Works

When reliable messaging is enabled, messages are grouped into sequences, which are defined by the client’s proxies. Each proxy corresponds to a message sequence, which consists of all of the request messages for that proxy. Each message contains a sequence header. The header includes a sequence identifier that identifies the sequence and a unique message number that indicates the order of the message in the sequence. The web service endpoint uses the sequence header information to group the messages and, if the Ordered Delivery option is selected, to process them in the proper order. Additionally, if secure conversation is enabled, each message sequence is assigned its own security context token. The security context token is used to sign the handshake messages that initialize communication between two web service endpoints and subsequent application messages.

Thus, using the Reliable Messaging technology, web service endpoints collaborate to determine which messages in a particular application message sequence arrived at the destination endpoint and which messages require resending. The reliable messaging protocol requires that the destination endpoint return message-receipt acknowledgements that include the sequence identifier and the message number of each message received. If the source determines that a message was not received by the destination, it resends the message and requests an acknowledgement. Once the source has sent all messages for a given sequence and their receipt has been acknowledged by the destination, the source terminates the sequence.

The web service destination endpoint in turn sends the application messages along to the application. If ordered delivery is configured (optional), the destination endpoint reconstructs a complete stream of messages for each sequence in the exact order in which the messages were sent and sends them along to the destination application. Thus, through the use of the reliable messaging protocol, the destination endpoint is able to provide the following delivery assurances to the web service application:

• Each message is delivered to the destination application at least once.

• Each message is delivered to the destination application at most once.

• Sequences of messages are grouped by sequence identifiers and delivered to the destination application in the order defined by the message numbers.

Figure 2–7 shows a simplified view of client and web service application message exchanges when the Reliable Messaging protocol is not used.

Figure 2–7 Application Message Exchange Without Reliable Messaging

When the Reliable Messaging protocol is not used, application messages flow over the HTTP connection with no delivery assurances. If messages are lost in transit or delivered out of order, the communicating endpoints have no way of knowing.

Figure 2–8 shows a simplified view of client and web service application message exchanges when reliable messaging is enabled.

Figure 2–8 Application Message Exchange with Reliable Messaging Enabled

With reliable messaging enabled, the Reliable Messaging source module is plugged into the JAX-WS web service client. The source module transmits the application messages and keeps copies of the messages until their receipt is acknowledged by the destination module through the exchange of protocol messages. The destination module acknowledges messages and optionally buffers them for ordered-delivery guarantee. After guaranteeing order, if configured, the destination module allows the messages to proceed through the JAX-WS dispatch for delivery to the endpoint or application destination.

How Security Works

The following sections describe how the WSIT security technologies, security policy, trust, and secure conversation work.

How Security Policy Works

The WSIT Web Service Security Policy implementation builds on the features provided by the Web Service Policy implementation in WSIT. It enables users to use XML elements to specify the security requirements of a web service endpoint, that is, how messages are secured on the communication path between the client and the web service. The web service endpoint specifies the security requirements to the client as assertions (see Figure 2–9).

Figure 2–9 Security Policy Exchange

The security policy model uses the policy specified in the WSDL file for associating policy assertions with web service communication. As a result, whenever possible, the security policy assertions do not use parameters or attributes. This enables first-level, QName-based assertion matching to be done at the framework level without security domain-specific knowledge. The first-level matching provides a narrowed set of policy alternatives that are shared by the client and web service endpoint when they attempt to establish a secure communication path.

---

Note –

A QName is a qualified name, as specified by the XML Schema Part2: Datatypes specification, Namespaces in XML, and Namespaces in XML Errata. A qualified name is made up of a namespace URI, a local part, and a prefix.

---

The benefit of representing security requirements as assertions is that QName matching is sufficient to find common security alternatives and that many aspects of security can be factored out and reused. For example, it may be common that the security mechanism is constant for a web service endpoint, but that the message parts that are protected, or secured, may vary by message action.

The following types of assertions are supported:

• Protection assertions: Define the scope of security protection. These assertions identify the message parts that are to be protected and how they are to be protected, that is, whether data integrity and confidentiality mechanisms are to be used.

• Conditional assertions: Define general aspects or preconditions of the security. These assertions define the relationships within and the characteristics of the environment in which security is being applied, such as the tokens that can be used, which tokens are for integrity or confidentiality protection, applicable algorithms to use, and so on.

• Security binding assertions: Define the security mechanism that is used to provide security. These assertions are a logical grouping that defines how the conditional assertions are used to protect the indicated message parts. For example, the assertions might specify that an asymmetric token is to be used with a digital signature to provide integrity protection, and that parts are to be encrypted with a symmetric key, which is then encrypted using the public key of the recipient. In their simplest form, the security binding assertions restrict what can be placed in the wsse:Security header and the associated processing rules.

• Supporting token assertions: Define the token types and usage patterns that can be used to secure individual operations and/or parts of messages.

• Web Services Security and Trust assertions: Define the token referencing and trust options that can be used.

How Trust Works

Figure 2–10 shows how the Web Services Trust technology establishes trust.

Figure 2–10 Trust and Secure Conversation

To establish trust between a client, a Security Token Service, and a web service:

1. The client establishes an HTTPS connection with the Secure Token Service using one of the following methods:

   • Username Authentication and Transport Security: The client authenticates to the Security Token Service using a username token. The Security Token Service uses a certificate to authenticate to the Client. Transport security is used for message protection.

   • Mutual Authentication: Both the client-side and server-side use X509 certificates to authenticate to each other. The client request is signed using Client’s X509 certificate, then signed using ephemeral key. The web service signs the response using keys derived from the client’s key.

2. The client sends a RequestSecurityToken message to the Security Token Service.

3. The Security Token Service sends a Security Assertion Markup Language (SAML) token to the Client.

4. The client uses the SAML token to authenticate itself to the web service and trust is established.

All communication uses SOAP messages.

How Secure Conversation Works

Figure 2–11 shows how the Web Services Secure Conversation technology establishes a secure conversation when the Trust technology is not used.

Figure 2–11 Secure Conversation

To establish a secure conversation between a Client and a web service:

1. The client sends a X509 Certificate to authenticate itself to the web service.

2. The web service sends a X509 Certificate to authenticate itself to the client.

All communication uses SOAP messages.