1.1. Required Software
To use this guide, download and install the following software:
- Oracle JavaSE Runtime or Development Kit
- Container (note: Metro can be run on any Servlet container)
- Metro binary. See the particular release page for instructions about downloading and installing Metro in a servlet container.
- NetBeans IDE (Java version)
1.2. What is WSIT?
For three years (and continuing) Sun has worked closely with Microsoft to ensure interoperability of web services enterprise technologies such as security , reliable messaging, and atomic transactions. That portion of Metro is known as WSIT (Web Service Interoperability Technologies). Metro's WSIT subsystem is an implementation of a number of open web services specifications to support enterprise features. In addition to security, reliable messaging, and atomic transactions, Metro includes a bootstrapping and configuration technology.Metro's WSIT Web Services Features shows the underlying services that were implemented for each technology.
Starting with the core XML support currently built into the Java platform, Metro 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
1.2.1. 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 Bootstrapping and Configuration.
- 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.
- The client uses the URL and the wsimport tool to send a WS-MetadataExchange Request 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, reliability, transactional, etc., capabilities and requirements of the service. The description describes the requirements that must be satisfied to access and consume the web service.
- The client uses the WSDL file to create the web service client.
- The web service client accesses and consumes the web service.
Bootstrapping and Configuration explains how to bootstrap and configure a web service client and a web service endpoint that use the Metro's WSIT technologies.
1.2.2. 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 Message Optimization.
1.2.3. Reliable Messaging Technology
Reliable Messaging is a Quality of Service (QoS) technology for building more reliable web services. Reliability (in terms of what is provided by WS-ReliableMessaging) is measured by a system‚Äôs ability to deliver messages from point A to point B. 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.
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 uses more memory (especially if the ordered delivery option is enabled) since messages must be stored (even after they are sent) until receipt is acknowledged.
- 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 Using Reliable Messaging.
1.2.4. Security Technology
Until now, web services have relied on transport-based security such as SSL to provide point-to-point security. Metro 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 Metro is in addition to existing transport-level security, which may still be used.
Metro 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, Metro implements two additional features to improve security in web services:
- 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.
- Web Services Security Policy: Enables web services to use security assertions to clearly represent security preferences and requirements for web service endpoints.
Metro 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 Metro and WCF endpoints.
For instructions on how to use the WS-Security technology, see Using WSIT Security.
1.3. How Metro Relates to .NET Windows Communication Foundation (WCF)
Web services interoperability is an initiative of Sun and Microsoft. We test and deliver products to market that interoperate across different platforms.
Metro is the product of Sun‚Äôs web services interoperability initiative. Windows Communication Foundation (WCF) in .NET is Microsoft‚Äôs unified programming model for building connected systems. WCF, which is available as part of the .NET Framework 3.x product, includes application programming interfaces (APIs) for building secure, reliable, transacted web services that interoperate with non-Microsoft platforms.
Sun Microsystems and Microsoft jointly test Metro 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. This testing ensures that the following interoperability goals are realized:
- Metro web services clients can access and consume WCF web services.
- WCF web services clients can access and consume Metro web services.
Sun provides Metro on the Java platform and Microsoft provides WCF on the .NET 3.0 and .NET 3.5 platforms. 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.
| Because Metro-based clients and services are interoperable, you can gain the benefits of Metro without using WCF.
1.4. Metro 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
Metro implements the following WS-* specifications.
|Bootstrapping|| since v1.0 : WS-MetadataExchange v1.1
|Policy (W3C standards)|| since v1.0 : WS-Policy v1.2
since v1.0 : WS-PolicyAttachment v1.2
since v1.3 : WS-Policy v1.5
since v1.3 : WS-PolicyAttachment v1.5
|Reliable Messaging (OASIS standards)|| since v1.0 : WS-ReliableMessaging v1.0
since v1.0 : WS-ReliableMessaging Policy v1.0
since v1.3 : WS-ReliableMessaging v1.1
since v1.3 : WS-ReliableMessaging Policy v1.1
since v2.0 : WS-ReliableMessaging v1.2
since v2.0 : WS-ReliableMessaging Policy v1.2
since v2.0 : WS-MakeConnection v1.1
| Atomic Transactions (OASIS submissions)
Note: Metro does not implement the
standard versions of these specifications.
| since v1.0 : WS-AtomicTransaction v1.0
since v1.0 : WS-Coordination v1.0
|Security (OASIS standards)|| since v1.0 : WS-Security v1.0
since v1.0 : WS-Security v1.1
since v1.0 : WS-SecurityPolicy v1.1
since v1.3 : WS-SecurityPolicy v1.2
since v1.0 : WS-Trust v1.2
since v1.3 : WS-Trust v1.3
since v2.0 : WS-Trust v1.4
since v1.0 : WS-SecureConversation v1.2
since v1.3 : WS-SecureConversation v1.3
since v2.0 : WS-SecureConversation v1.4
|Security Profiles (OASIS standards)|| since v1.3 All 1.0 and 1.1 profiles listed here except Web Services Security REL Token Profile V1.0
Metro 1.3 + and WCF in .NET 3.5 implement the same specifications.
1.4.1. 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. Bootstrapping and Configuration Specifications shows the specifications that were implemented to support bootstrapping and configuration.
In addition to the Core XML specifications, bootstrapping and configuration was implemented using the following specifications:
- WSDL: 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.
1.4.2. 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.
Message Optimization Specifications shows the specifications that were implemented to optimize communication between two web service endpoints.
In addition to the Core XML specifications, optimization was implemented using the following specifications:
- SOAP: With SOAP implementations, client requests and web service responses are most often transmitted as 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: This specification defines a endpoint reference representation. 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 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.
1.4.3. Reliable Messaging Specifications
Reliability (in terms of WS-ReliableMessaging) is measured by a system‚Äôs ability to deliver messages from point A to point B regardless of network errors. Reliable Messaging Specifications shows the specifications that were implemented to ensure reliable delivery of messages between two web services endpoints.
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.
1.4.4. Security Specifications
Web Services Security Specifications shows the specifications implemented to secure communication between two web service endpoints and across intermediate endpoints.
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 Metro 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 Metro 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.
1.5. How the Metro Technologies Work
1.5.1. 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 Metro 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.
1.5.2. 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.
Application Message Exchange Without Reliable Messaging shows a simplified view of client and web service application message exchanges when the Reliable Messaging protocol is not used.
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.
Application Message Exchange with Reliable Messaging Enabled shows a simplified view of client and web service application message exchanges when reliable messaging is enabled.
With reliable messaging enabled, the Reliable Messaging source module is plugged into the Metro 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 Metro dispatch for delivery to the endpoint or application destination.
1.5.3. How Security Works
22.214.171.124. How Security Policy Works
The Metro Web Service Security Policy implementation builds on the features provided by the Web Service Policy implementation in Metro. 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 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.
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.
126.96.36.199. How Trust Works
Trust and Secure Conversation shows how the Web Services Trust technology establishes trust.
To establish trust between a client, a Security Token Service, and a web service:
- 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.
- The client sends a RequestSecurityToken message to the Security Token Service.
- The Security Token Service sends a Security Assertion Markup Language (SAML) token to the Client.
- The client uses the SAML token to authenticate itself to the web service and trust is established.
188.8.131.52. How Secure Conversation Works
Secure Conversation shows how the Web Services Secure Conversation technology establishes a secure conversation when the Trust technology is not used.
To establish a secure conversation between a Client and a web service:
- The client sends a X509 Certificate to authenticate itself to the web service.
- The web service sends a X509 Certificate to authenticate itself to the client.
All communication uses SOAP messages.