Advanced Web Services

Beyond the basic concept of Web Services as used to invoke one service from another, there are advanced concepts that occasionally come into play. This section discusses some of these concepts and describes how they can be used in conjunction with IBPM.

WS-Notification

WS-Notification is an open standard that overlays the concepts of Publish and Subscribe on top of Web Services. WebSphere Application Server implements v1.3 of the specification.

A NotificationProducer is a component that produces messages. Put another way, the NotificationProducer is a message publisher. In the WS-Notification specification, messages that are published are called “Notifications”. Another concept is the component known as the NotificationConsumer. Relating this back to the more common publish and subscribe terminology, this can be though of as a subscriber. The NotificationProducer accepts requests from NotificationConsumers for subscriptions. When a subscription is made, the subscription includes information allowing the NotificationProducer to send messages to the subscriber and it also identifies which messages should be sent.

A NotificationConsumer sends a SubscribeRequest message to a NotificationConsumer when it wishes to register for a subscription. The subscriber is returned a reference to a Subscription that is managed by the SubscriptionManager. A SubscriptionManager is a service that implements the subscription management interface. The SubscriptionManager is considered to be a subordinate to the NotificationProducer and may be implemented as part of the NotificationProducer.

When a subscriber registers a desire for a subscription, it names the form of the subscription that should be taken. There are two possible options here. Raw notification and Notify Message notification. The Notify Message form includes additional metadata beyond the payload of the published message.

Subscription Manager


Notification Broker


Publisher Registration Manager


To subscribe to a topic, the subscriber sends a Subscribe message. The result from this is a Subscription.

A NotificationConsumer can itself be a Web Service provider. In this case, when the Notification Producer generates a message, that message is sent to the NotificationConsumer directly. This model of operation is called a “push-style” as the messages are pushed from the producer to the consumer. There may be cases where this is not possible such as the NotificationConsumer existing behind a firewall. In these circumstances, the consumer can utilize a “pull” model. The consumer can “poll” the provider to see if a message it is interested in is available for retrieval. To allow this “pull” model, a subscriber can ask the provider to create a “PullPoint”. Think of this as a location against which published messages are collected on behalf of the subscriber.

The concept of a NotificationBroker is that it relieves a publisher and a consumer from having to implement Web Services. The NotificationBroker performs the role of both a NotificationProducer and a NotificationConsumer. WAS 7.0 implements a NotificationBroker so we will focus on that for the remainder of the story. Associated with a NotificationBroker are one or more applications that are known as “Publishers”. A publisher sends messages to be published to the NotificationBroker.

Subscribe Request

A Subscription Request is made against the Notification Broker. It may be made by the actual subscriber itself or on behalf of the subscriber. The subscription request names an Interface offered by the Subscriber such that when a publish is made, the notification broker will invoke the subscribers interface to deliver the published message. The interface offered by the subscriber must conform to the NotificationConsumer interface provided.

Here is a SOAP message that was mechanically captured for a successful subscription.

\<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"\>
 \<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"\>
 \<wsa:To\>http://localhost:9081/weatherWSNServiceweatherWSNServicePointNB/Service\</wsa:To\>
 \<wsa:MessageID\>urn:uuid:8A37D7D3CF62D4990C1283181983897\</wsa:MessageID\>
 \<wsa:Action\>http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeRequest\</wsa:Action\>
 \</soapenv:Header\>
 \<soapenv:Body\>
 \<Subscribe
 xmlns="http://docs.oasis-open.org/wsn/b-2"
 xmlns:ns2="http://docs.oasis-open.org/wsn/t-1"
 xmlns:ns3="http://docs.oasis-open.org/wsrf/bf-2"
 xmlns:wsa="http://www.w3.org/2005/08/addressing"
 xmlns:ns5="http://docs.oasis-open.org/wsrf/rp-2"
 xmlns:ns6="http://docs.oasis-open.org/wsn/br-2"
 xmlns:ns7="http://docs.oasis-open.org/wsrf/r-2"\>
 \<ConsumerReference\>
 \<wsa:Address\>http://127.0.0.1:9081/WeatherWSNConsumerPushWeb/WeatherNotificationConsumer\</wsa:Address\>
 \</ConsumerReference\>
 \<Filter\>
 \<TopicExpression
 Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"
 xmlns:tns="http://weather"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:type="TopicExpressionType"\>tns:daily-weather\</TopicExpression\>
 \</Filter\>
 \</Subscribe\>
 \</soapenv:Body\>
 \</soapenv:Envelope\>

Here is a sample response message

\<?xml version="1.0" encoding="UTF-8" standalone="no"?\>
 \<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\>
 \<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"\>
 \<wsa:Action\>http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeResponse\</wsa:Action\>
 \<wsa:RelatesTo\>urn:uuid:8A37D7D3CF62D4990C1283181983897\</wsa:RelatesTo\>
 \</soapenv:Header\>
 \<soapenv:Body\>
 \<b2:SubscribeResponse xmlns:b2="http://docs.oasis-open.org/wsn/b-2"\>
 \<b2:SubscriptionReference\>
 \<wsa:Address
 xmlns:wsa="http://www.w3.org/2005/08/addressing"\>http://win7-x64:9080/weatherWSNServiceweatherWSNServicePointSM/Service\</wsa:Address\>
 \<wsa:ReferenceParameters xmlns:wsa="http://www.w3.org/2005/08/addressing"\>
 \<subscriptionId xmlns="http://www.ibm.com/websphere/wsn/reference"\>sub\_01ccc151d9a246c3d5c60ebc\_12ac39b203b\_5\</subscriptionId\>
 \<wsaucf:RoutingInformation
 xmlns:wsaucf="http://ucf.wsaddressing.ws.ibm.com"\>
 \<wsaucf:HAClusterId\>00000000020004747970650010575341465f5349425f4d455f55554944000475756964001046444143453444413033303532303336\</wsaucf:HAClusterId\>
 \</wsaucf:RoutingInformation\>
 \<messagingEngineUuid
 xmlns="http://www.ibm.com/websphere/wsn/reference"\>FDACE4DA03052036\</messagingEngineUuid\>
 \<wsaucf:VirtualHostName xmlns:wsaucf="http://ucf.wsaddressing.ws.ibm.com"\>default\_host\</wsaucf:VirtualHostName\>
 \</wsa:ReferenceParameters\>
 \<wsa:Metadata xmlns:wsa="http://www.w3.org/2005/08/addressing"\>
 \<ServiceName EndpointName="SubscriptionManagerPort" xmlns="http://www.w3.org/2006/05/addressing/wsdl" xmlns:ns1121979737="http://www.ibm.com/websphere/wsn/subscription-manager"\>ns1121979737:weatherWSNServiceweatherWSNServicePointSM\</ServiceName\>
 \</wsa:Metadata\>
 \</b2:SubscriptionReference\>
 \<b2:CurrentTime\>2010-08-30T15:26:17.659Z\</b2:CurrentTime\>
 \</b2:SubscribeResponse\>
 \</soapenv:Body\>
 \</soapenv:Envelope\>

To make a subscription from a mediation flow, the SMO has to be constructed as follows:

/headers/SOAPHeader[1]/nameSpace
 http://www.w3.org/2005/08/addressing
 /headers/SOAPHeader[1]/name
 Action
 /headers/SOAPHeader[1]/value (Cast: anyURI)
 http://docs.oasis-open.org/wsn/bw-2/NotificationProducer/SubscribeRequest
 /headers/SOAPHeader[2]/nameSpace
 http://www.w3.org/2005/08/addressing
 /headers/SOAPHeader[2]/name
 MessageID
 /headers/SOAPHeader[2]/value
 someUUID
 /body/Subscribe/ConsumerReference/Address/value
 WS-Hostname&Port
 /body/Subscribe/Filter/TopicExpression/@Dialect (Cast: TopicExpression)
 http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple
 /body/Subscribe/Filter/TopicExpression/\*mixed
 topic value

Publishing a message

In order to publish a message, the Notification Producer uses the Web Services interface provided by the Notification Broker and calls the Notify operation passing in the message to be published.

As of 2011-04, it appears that the notification message must be a single line of text. Errors are reported otherwise. This problem is claimed to be fixed in WAS 7.0.0.9 and above and there is an APAR with a fix for releases prior to that.

Here is a sample published message:

\<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"\>
 \<soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"\>
 \<wsa:To\>http://localhost:9081/weatherWSNServiceweatherWSNServicePointNB/Service\</wsa:To\>
 \<wsa:ReplyTo\>
 \<wsa:Address\>http://www.w3.org/2005/08/addressing/none\</wsa:Address\>
 \</wsa:ReplyTo\>
 \<wsa:MessageID\>urn:uuid:8A37D7D3CF62D4990C1283269176009\</wsa:MessageID\>
 \<wsa:Action\>http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify\</wsa:Action\>
 \</soapenv:Header\>
 \<soapenv:Body\>
 \<Notify xmlns="http://docs.oasis-open.org/wsn/b-2"
 xmlns:ns2="http://docs.oasis-open.org/wsrf/bf-2"
 xmlns:ns3="http://www.w3.org/2005/08/addressing"
 xmlns:ns4="http://docs.oasis-open.org/wsrf/rp-2"
 xmlns:ns5="http://docs.oasis-open.org/wsn/t-1"
 xmlns:ns6="http://docs.oasis-open.org/wsn/br-2"
 xmlns:ns7="http://docs.oasis-open.org/wsrf/r-2"\>
 \<NotificationMessage\>
 \<Topic
 Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"
 xmlns:tns="http://weather"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:type="TopicExpressionType"\>tns:daily-weather\</Topic\>
 \<Message\>
 \<weatherobj xmlns=""
 xmlns:ns8="http://docs.oasis-open.org/wsn/b-2"\>partly cloudy,-5,SW,39,1283269151817\</weatherobj\>
 \</Message\>
 \</NotificationMessage\>
 \</Notify\>
 \</soapenv:Body\>
 \</soapenv:Envelope\>

Using a mediation flow to build a WS-Notification message

The messages to be sent to the NotificationBroker can be built by a WESB mediation flow. This involves a little work but once understood isn't that complex. Here is an example of a Notify message:

To describe these mapings in this document, an XPath like notation will be used:

/headers/SOAPHeader[1]/nameSpace
 http://www.w3.org/2005/08/addressing[
](http://www.w3.org/2005/08/addressing)
 /headers/SOAPHeader[1]/name
 Action
 /headers/SOAPHeader[1]/value (Cast: anyURI)
 http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify[
](http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify)
 /body/Notify/NotificationMessage/Topic/@Dialect
 http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple
 /body/Notify/NotificationMessage/Topic/mixed
 daily-weather
 /body/Notify/NotificationMessage/Message/MyPayload (Cast: as appropriate)
 data

Topics for WS-Notification

When a subscription is made, it is made on a particular topic. This describes which publications that notifiers publish will be delivered to a given subscriber. A Topic is actually considered a topic expression and has rules that govern its structure.

Here is a simple example of the Topic section:

\<Topic
 Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"
 xmlns:tns="http://weather"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:type="TopicExpressionType"\>tns:daily-weather\</Topic\>

In general, a Topic is contained within a <Topic> tag. This tag has a mandatory attribute called Dialect which will be discussed shortly. The Dialect attribute describes how the Topic should be interpreted. The body of the <Topic> tag identifies the topic.

There are three classes of topic expressions.

Simple Topic Expression

The class known as Simple Topic Expression has the dialect attribute of the <Topic> tag set to:

Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"

The topic value is an explicit value with no hierarchy descriptions nor wild cards.

Concrete Topic Expression

This class known as Concrete Topic Expression has the dialog attribute of the <Topic> tag set to:

Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Concrete"

The topic value is again an explicit value but with the addition of "/" characters to represent a hierarchy.

Full Topic Expression

The class known as Full Topic Expression has the dialect attribute of the <Topic> tag set to:

Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Full"

The topic value can use XPath notation to define the topic.

Building a Notification Subscriber

A Notification Subscriber is a Web Service implementation that implements the Notification Consumer service interface. The Notification Subscriber is the “application” that is destined to receive the notifications that a publisher has published a message. This interface has a single operation on it called “Notify”:

It is the service endpoint of the NotificationSubscriber that is supplied in a subscription request. This means that when a publisher publishes a message, the broker can look at its current set of subscriptions and for each subscription matching the publish, send a message to the subscriber by invoking its service interface.

A trivial implementation of the subscriber interface may look as follows:

The export is given the NotificationConsumer interface and a Web Services binding is defined. Here is an example of an SMO generated as a result of a published message received by a subscriber.


\<?xml version="1.0" encoding="UTF-8"?\>
 \<Se:smo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:Se="http://www.ibm.com/websphere/sibx/smo/v6.0.1" xmlns:\_2="wsdl.http://docs.oasis-open.org/wsn/bw-2" xmlns:\_2\_1="http://docs.oasis-open.org/wsn/b-2" xmlns:ad="http://www.w3.org/2005/08/addressing" xmlns:ht="http://www.ibm.com/xmlns/prod/websphere/http/sca/6.1.0" xmlns:re="http://www.ibm.com/websphere/wsn/reference" xmlns:uc="http://ucf.wsaddressing.ws.ibm.com" xmlns:wsdl="http://www.w3.org/2006/05/addressing/wsdl"\>
 \<context/\>
 \<headers\>
 \<SMOHeader\>
 \<MessageUUID\>ED0819C0-012A-4000-E000-1910C0A8016F\</MessageUUID\>
 \<Version\>
 \<Version\>7\</Version\>
 \<Release\>0\</Release\>
 \<Modification\>0\</Modification\>
 \</Version\>
 \<MessageType\>Request\</MessageType\>
 \<Operation\>Notify\</Operation\>
 \<Action\>http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify\</Action\>
 \<SourceNode\>MyConsumer\</SourceNode\>
 \<SourceBindingType\>WebService\</SourceBindingType\>
 \<Interface\>wsdl:http://docs.oasis-open.org/wsn/bw-2\</Interface\>
 \</SMOHeader\>
 \<HTTPHeader\>
 \<control\>
 \<ht:URL\>http://localhost:9080/WSNMod1Web/sca/MyConsumer\</ht:URL\>
 \</control\>
 \</HTTPHeader\>
 \<WSAHeader version="http://www.w3.org/2005/08/addressing"\>
 \<ad:To\>http://localhost:9081/WSNMod1Web/sca/MyConsumer\</ad:To\>
 \<ad:ReplyTo\>
 \<ad:Address\>http://www.w3.org/2005/08/addressing/none\</ad:Address\>
 \</ad:ReplyTo\>
 \<ad:Action\>http://docs.oasis-open.org/wsn/bw-2/NotificationConsumer/Notify\</ad:Action\>
 \<ad:MessageID\>urn:uuid:8B98FC5FF77DBF4EA81283876991522\</ad:MessageID\>
 \</WSAHeader\>
 \</headers\>
 \<body xsi:type="\_2:Notify"\>
 \<\_2\_1:Notify\>
 \<\_2\_1:NotificationMessage\>
 \<\_2\_1:SubscriptionReference\>
 \<ad:Address\>http://win7-x64:9080/weatherWSNServiceweatherWSNServicePointSM/Service\</ad:Address\>
 \<ad:ReferenceParameters\>
 \<re:subscriptionId\>sub\_d0e1004de6f28244ac58deb0\_12aecf2aee3\_1\</re:subscriptionId\>
 \<uc:RoutingInformation\>\<uc:HAClusterId\>00000000020004747970650010575341465f5349425f4d455f55554944000475756964001041453745313633354531454645353134\</uc:HAClusterId\>\</uc:RoutingInformation\>
 \<re:messagingEngineUuid\>AE7E1635E1EFE514\</re:messagingEngineUuid\>
 \<uc:VirtualHostName\>default\_host\</uc:VirtualHostName\>
 \</ad:ReferenceParameters\>
 \<ad:Metadata\>
 \<wsdl:ServiceName EndpointName="SubscriptionManagerPort"\>ns1121979737:weatherWSNServiceweatherWSNServicePointSM\</wsdl:ServiceName\>
 \</ad:Metadata\>
 \</\_2\_1:SubscriptionReference\>
 \<\_2\_1:Topic Dialect="http://docs.oasis-open.org/wsn/t-1/TopicExpression/Simple"\>daily-weather\</\_2\_1:Topic\>
 \<\_2\_1:Message\>
 \<MyPayload\>
 \<a\>1\</a\>
 \<b\>2\</b\>
 \<c\>3\</c\>
 \</MyPayload\>
 \</\_2\_1:Message\>
 \</\_2\_1:NotificationMessage\>\</\_2\_1:Notify\>
 \</body\>
 \</Se:smo\>
 

A WS-Notification Sample

Here we will build a complete WS-Notification sample. We will use the simple story domain of stock prices for our illustration. We will have a publisher that is publishing stock updates. We will also have a subscriber that is watching for such updates.

We will start by setting up a WS-Notification environment. WAS implements WS-Notification on top of the WAS SI Bus JMS technology. We could re-use an existing SI Bus but for this story, we will create a new bus as it is a relatively quick task.

First we create a new SI Bus to host our Stocks topic environment.

We have decided to switch off SI Bus security at this time as this only complicates the overall story. Once the bus has been created, at least one bus member must be added.

Standard options were selected and the local server was added as a Bus Member.

Following the creation of a new SI Bus, we can now define a new WS-Notification environment. This can be found here:

Once complete, the WS-Notification environment should be available. It is suggested to stop and restart the WAS server to be sure.

In order for applications to use the WS-Notification configuration just made, they must make Web Service calls to the server. To make a Web Service call, these applications will need WSDL that describes the target server and operations. The WSDL for these services can be dynamically retrieved from the new server configuration using the WAS admin console.

Once the WSDL and XSD files have been exported, create a new Library project to hold the content. When the project has been created, import the ZIP file content that were exported from the WAS server.

Don't import all the content, just the NBModule. The NB acronym is Notification Broker.

Warning!!: When importing these artifacts, be sure to only import the files and not the folders. The folders contain the period character (".") which can not be used as folder names in WID as this conflicts with Java Packaging constructs.

There are three services that we are going to be interested in. Two already exist and one we will build. The WS-Notification environment provides operations to register a subscription for a topic against a subscriber and also provides an operation to publish a notification. We will want to create a service that will act as a recipient for a subscription request.

We will start with that. We create a new module and associate the library we just built with that new module. In the module, we create an Export component and select the interface called NotificationConsumer as the interface of that export. We define a Web Service binding for that export. Finally we implement a trivial mediation flow for the export simply to show that it is called when we expect it to be called.

The next thing we wish to accomplish is to be able to register a subscription with the WS-Notification engine. WS-Notification provides us a service interface to be able to achieve exactly this. In the module, we add in the import for the WS-Notification broker.

Implementation notes


[4/27/11 14:18:42:663 CDT] 0000005b WebServiceExc E org.apache.axis2.jaxws.WebServiceExceptionLogger log A javax.xml.ws.soap.SOAPFaultException throwable was caught. The detail message is: ationMessageHolderType instance: unexpected Java class com.ibm.ws.webservices.engine.xmlsoap.Text encountered for child object at com.ibm.ws.sib.wsn.webservices.utils.WSNMarshallerImpl.createSOAPFaultException(WSNMarshallerImpl.java:748) at com.ibm.ws.sib.wsn.webservices.impl.inbound.provider.NBInvokerImpl.invoke(NBInvokerImpl.java:311) at com.ibm.ws.sib.wsn.webservices.impl.inbound.provider.NBProviderImpl.invokeTargetService(NBProviderImpl.java:142) at com.ibm.ws.sib.wsn.webservices.impl.inbound.provider.WSNProviderImpl.invoke(WSNProviderImpl.java:140) at com.ibm.ws.sib.wsn.webservices.impl.inbound.provider.NBProviderImpl.invoke(NBProviderImpl.java:108)

Changing the format to be single line seems to make the error disappear. A PMR has been raised to address this issue (2011-04-27 – 82736,7TD,000).

SIBWsn=all:com.ibm.ws.sib.webservices.\*=all

Bugs and Fixes

A problem was found where payload data with name spaces was not being handled correctly. A PMR was opened (00850,004,000) and a fix was provided. The fix requires the setting of a custom property. After applying the fix, a custom property need be set. Here is the doc on that:

To set this: Click Servers > Server Types > WebSphere application servers > server_name, and then, in the Server Infrastructure section, click Java and process management > Process definition > Control > Java virtual machine > Custom properties Then define a new property and in the Name field, type the property name "sib.wsn.client.includeNSDecls". In the Value field, type the value "true". ( The default value is false ) .

References – WS-Notification


WS-Addressing

WS-Addressing is the ability to describe Web Services endpoint information in a standard format. There are many uses for this capability.

Within an SCA Module we can define in the dependencies that the inclusion of WS-Addressing should be done.

This adds a number of data types into the project.

Within BPEL, we can perform assignments into a WS-Address by declaring a variable of type ServiceRefType. If we declare a variable of this type and then perform an assignment to it, we have two selection options. The first is selecting a Partner Reference. This will plug-in SCA bindings to the target.

The second option is an explicit Endpoint Reference. Using that technique, a wizard is displayed which prompts us for a variety of input parameters:

This will plug in the specified details.

If we look at a value of an example ServiceReferenceType we see that it has the following structure:

\<p:ServiceRefType xsi:type="p:ServiceRefType"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:ad="http://schemas.xmlsoap.org/ws/2004/08/addressing"
 xmlns:i3="http://Async1/I3"
 xmlns:p="http://schemas.xmlsoap.org/ws/2004/03/business-process/"\>
 \<ad:EndpointReference\>
 \<ad:Address\>http://localhost:9080/Async1Web/sca/I3Export\</ad:Address\>
 \<ad:PortType\>i3:I3\</ad:PortType\>
 \<ad:ServiceName
 PortName="I3Export\_I3HttpPort"\>i3:I3Export\_I3HttpService\</ad:ServiceName\>
 \</ad:EndpointReference\>
 \</p:ServiceRefType\>

Now let us give some thought to dynamic BPEL invokes. At a high level, we have the following notion. A BPEL process wishes to invoke a Partner service. Let us call this partner service "ABC". However, at development time, the endpoint address of "ABC" is not known. What we need to do is set the endpoint information dynamically at runtime. When we defined the BPEL process, we added a partner reference. Inside BPEL, this named partner reference is actually a variable of type ServiceReferenceType. What this means is that if we assign a ServiceReferenceType variable instance to the partner reference variable, the value of ServiceReferenceType will be honored. This specifically includes the addressing information and hence we have achieve dynamic invocation.

WS-Security

Security associated with Web Service calls is based on the idea of Policy Sets. A policy set is a set of definitions of how security should be performed. Prior to policy sets, each service caller or provider would be explicitly coded or declared to have its own security settings. If a solution had many such services, each service would have to have the security settings replicated by hand which was error prone and tedious. If a change was required to the security settings, all locations where the change needed to be applied had to be found and replaced. All in all, not a good situation. With the arrival of JAX-WS as a Java based Web Services engine/package, the notion of policy sets was introduced. Think of a policy set as a container of all the settings that one may wish to apply to a service. When a service is created, the named policy set can now be associated with that service. For additional web services, they can also be associated with the same named policy set. Because of this, the definitions for the security need only be created once and re-used when and where needed. A change to the policy set definitions results in an effective change to all the other services that referenced the policy set.

When an SCA Import is associated with a JAX-WS web service call, a named policy-set can then be associated with the SCA Import.

As such, the actual SCA import is not configured for security but instead a policy set is created and then the policy set associated with the import. If there are multiple SCA imports, each one can be re-use the same named policy set and thus provide loose coupling. If a security entry needs to be changed, changing it within the policy set will change it where ever that policy set is referenced.

The same notion applied to SCA Export components:

To delve deeper into policy sets, we must set up some definitions.

Policy Type – The Policy Type is a type of potential definitions for a type of policy. Think of it like a template of a group of setting that can be configured. Supplied Policy Types include:


Policy – A policy is named instance of a Policy Type. It contains specific definitions for that Policy Type but explicitly does not include some specifics.

Binding – A binding is associated with a Policy. The binding contains environment specific information. There are two types of binding:

Policy Set – A collection of policies

Policy set configurations are performed in the WAS admin console under Services > Policy sets:

The security settings for a security policy look as follows:

In the Message Part Protection section we define how we want either the request or response messages protected. Protected in this case means two primary considerations. The first is encryption. If encryption is used then we define which parts of the message will be encrypted so that anyone examining the message in transit will not be able to decode all or part of the content. Note that this is not the same as SSL which encrypts at the transport level. Encryption in WS-Security encrypts parts of the body of the message.

The other part of message protection is called integrity. This is a technique to prevent tampering with a message once it has been sent but before it arrives. The integrity of a message is assured by digitally signing the request message and on receipt checking that the signature of the message was not changed. Think of this as performing a CRC or hash function over the content of the message and then including the resulting hash value as part of the message. If the message were changed, when the receiver performs the same hash function then the signature generated would be different than the one supplied with the message. The original signature is itself encoded with private keys so that a message can not simply have a new (but tampered with) signature added to the tampered message.

The parts of the message chosen for encryption and the parts for signing do not have to be the same.


Building a secure Web Service

When we wish to set up secure Web Service communications, we start by choosing a Policy Set and associated bindings. These will then be attached to the Web Services. When creating a new Policy Set, it is always recommended to start from one of the IBM supplied Policy Sets and copy that for use.

To view the existing Policy Sets, we can use the WAS admin console from Services → Policy Sets:

Testing Web Services security with TCP/Mon

It seems like a sensible idea to test with TCP/Mon to visualize the Web Services traffic flowing between a service client and a service provider. In my testing I then placed TCP/Mon between the two but started to get some new errors. Specifically, the following fault was returned:

\<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"\>
 \<soapenv:Fault\>
 \<faultcode\>soapenv:FailedAuthentication\</faultcode\>
 \<faultstring\>security.wssecurity.WSSContextImpl.s02: com.ibm.websphere.security.WSSecurityException: Exception org.apache.axis2.AxisFault: CWWSS6521E: The Login failed because of an exception: javax.security.auth.login.LoginException: CWWSS7218E: SCT is not valid for the webservice endpoint "http://localhost:9082/ProviderWeb/sca/ProviderI2". SCT is issued for "http://localhost:9999/ProviderWeb/sca/ProviderI2". ocurred while running action: com.ibm.ws.wssecurity.handler.WSSecurityConsumerHandler\$1@21cb21cb\</faultstring\>
 \</soapenv:Fault\>
 \</soapenv:Body\>

In my testing, my client was running on port 9081, my server on port 9082 with TCP/Mon proxying port 9999 to 9082. The client sent the request to 9999. At a guess, I'd say that the signature was built for a target of 9999 (where the client thought it was sending the request) while when it arrived at 9082 (the real target), the signature no longer matched. This seems to mean that we can't place TCP/Mon in the path of signatures.

JAX-WS

JAX-WS is the Java based way of either providing or invoking Web Services.

JAX-WS Java SE stand alone Service Provider

With JAX-WS it is quite straightforward to build a Web Service provider that is nothing more than a stand-alone Java SE application. Here is a quick recipe.

Build a Java application that looks as follows:

package kolban;
 import javax.jws.WebService;
 import javax.xml.ws.Endpoint;
 @WebService
 public class CircleFunctions {
 public static void main(String[] args) {
 System.out.println("About to publish!");
 Endpoint.publish(
 "http://localhost:9998/WebServiceExample/circlefunctions",
 new CircleFunctions());
 System.out.println("Ending");
 }
 public double getArea(double r) {
 return java.lang.Math.PI \* (r \* r);
 }
 public double getCircumference(double r) {
 return 2 \* java.lang.Math.PI \* r;
 }
 }

The key things to note are that it is annotated as being a Web Service. When the application is executed, we can obtain the WSDL at:

http://localhost:9998/WebServiceExample/circlefunctions?wsdl

Parameters for exposed methods should also be annotated with the "@WebParam" tags. This allows parameter names to be exposed to the callers. For example:

public void chargeCard(
 @WebParam(name="billingDetails") BillingDetails\_srv billingDetails,
 @WebParam(name="chargeAmount") float chargeAmount)
No Comments
Back to top