Introduction

The Web Services Security (WS-Security) specification describes enhancements to SOAP messaging to provide message integrity, message confidentiality, and single message authentication. You can use these mechanisms to accommodate a wide variety of security models and encryption technologies.

The Web Services Reliable Messaging (WS-RM) specification ensures the reliable delivery of SOAP messages between web services clients or sources, and Web service providers.

This article shows you how to apply WS-RM and WS-Security on client and server web services running on IBM® WebSphere® Application Server V8 and IBM WebSphere Message Broker V8, in order to meet security and reliable messaging requirements. This article also shows how a JAX-WS client running on WebSphere Application Server interacts with a server running on WebSphere Message Broker when WS-RM and WS-Security are enabled on both, as well as the reverse situation

WS-RM and WS-Security are especially important when an application's SOAP messages are critical and confidential, as in the case of financial transactions. Therefore the scenario in this article uses a sample banking application to introduce WS-RM and WS-Security.

The article does not cover web service development, the WS-Security policy set, or bindings development. The article provides a set of existing web services, policy sets, and bindings. To benefit from this article, you should be familiar with those tasks, and with the basics of using WebSphere Application Server and WebSphere Message Broker. You should also understand how WS-RM and WS-Security works for the web service client and provider. For more information, see WS-RM specification and WS-Security specification in the WebSphere Message Broker information center.

Overview of banking application

The sample banking application involves a web service on WebSphere Message Broker and a JAX-WS client on WebSphere Application Server, as well as the reverse -- a web service client on WebSphere Message Broker and a web service on WebSphere Application Server.

In the banking application, the client application sends requests for CreateAccount, CreditRequest, DebitRequest, and CheckBalance operations, which are processed on the server side, with an appropriate response sent back to the client. First a CreateAccount request is sent and a response is sent back with the new account information. Then CreditRequest and DebitRequest requests are sent -- they are one-way operations, so the requests are processed on the server side and no response is sent back to the client. Finally, a CheckBalance request is sent and a response is sent back to the client with the account balance.

The rest of this article shows you how to use the banking application to generate a web service and a web service client, and how to apply WS-RM and WS-Security on WebSphere Application Server using Rational Application Developer V8 and the WebSphere Application Server administrative console, and on WebSphere Message Broker using the command console and WebSphere Message Broker Explorer.

Integrating a web service on WebSphere Message Broker and a JAX-WS client on WebSphere Application Server

Import a web service to WebSphere Message Broker

The first step is to import the provider server flow into WebSphere Message Broker V8 that you can use to deploy and run your web service server:.

1. Download the WSRM_WSS.zip file at the bottom of this article and extract WMB_BankApplication_PI.zip.
2. Start WebSphere Message Broker Toolkit V8.
3. Import the project: Select File => Import. In the Import window, select Other => Project Interchangeand then select Next.
4. Browse to the Message Broker project file that you downloaded. Select All and then select Finish.
5. After importing the project, you should see the project structure shown below:
   
   Bank application project structure in WebSphere Message Broker
   
   
   
6. Double-click on WSRM_ProviderFlow.msgflow in the BankMessageFlowProject. You should see the flow shown below:
   
   WSRM_ProviderFlow message flow
   
   
   --> This flow behaves like a web service server/provider. The SOAPInput node of this flow can receive SOAP request messages from client applications. Then the Route To Label node routes the message to the appropriate Label. A SHARED ROW data type is declared and used to store the details for each account on the basis of the user identifier. A SHARED ROW variable exists for the lifetime of the:
   • Execution group process
   • Flow or node
   • Node ESQL code that declares the variable

   If the broker or execution or flow is restarted then the variable declared as SHARED ROW data type is reset. For more information, see Declare SHARED ROW data type in the WebSphere Message Broker information center.

   1. The CreateAccount Label receives CreateAccount requests and propagates them to the ComputeCreateAccount node. This compute node uses the variable declared as SHARED ROW and creates an entity for a particular user identifier with account information. If the user already exists, it throws an error and then propagates the response to the SOAPReply node.
   2. The CheckBalance Label receives CheckBalance requests and propagates them to the ComputeCheckBalance node. This compute node searches for an entity based on the user identifier in the shared variable tree structure and gets the balance value for that particular user identifier. The node then propagates the response to the SOAPReply node.
   3. The CreditRequest Label receives Credit requests and propagates them to the ComputeCreditRequest node. This compute node searches for an entity based on the user identifier in the shared variable tree structure and updates the amount for that particular user identifier. There is no need to send the response back as it is a one-way operation.
   4. The DebitRequest Label receives Debit requests and propagates them to the ComputeDebitRequest node. This compute node searches for an entity based on the user identifier in the shared variable tree structure and updates the amount for that particular user identifier only if the amount is greater than 50.0. There is no need to send the response back as it is a one-way operation.
   5. The SOAPReply node sends the response back to the client application.
7. Create an execution group called BankProvider.
8. Open the BankProvider BAR file in the BankMessageFlowProject. Select the Prepare tab, ensure that the WSRM_ProviderFlow and its message set are selected, and then click Build and Save.
9. Deploy the flow on the BankProvider execution group.

Import a JAX-WS Client into WebSphere Application Server

The next step is to import a client application in Rational Application Developer V8 that you can use to deploy and run your web service client. Your server must be set up to let you configure applications directly in the administrative console.

1. If you have not already done so, download the WSRM_WSS.zip file at the bottom of the article and extract RAD_BankClient.zip.
2. Start Rational Application Developer V8.
3. Import the project by selecting File => Import. In the Import window, select Other => Project Interchange and then select Next.
4. Browse to the RAD project file that you downloaded. Select BankClient and BankClientEAR, and then select Finish.
5. After importing the project, you may get a Java build path error, so make sure that all JAR files are added in the build path. You should see the project structures as shown below:
   
   BankClient project structure in Rational Application Developer
   
   
   
6. Navigate to BankClient => WebContent => sampleBankMessageSetSOAP_HTTP_PortProxy, right-click on TestClient.jsp, select Run As => Run On Server.
7. Select the Server and click Next, then click Finish. You should see a window as shown below:
   
   Web service TestClient in Rational Application Developer
   
   
   
8. Issue the following mqsireportproperties command to check which port the BankProvider execution group is using:
   
   Command to check the port used by the provider flow
   

   mqsireportproperties MB8BROKER -e BankProvider -o HTTPConnector -n port

   
   
9. The Test Client invokes the broker flow, so check the port value for Endpoint in the Web Service Test Client. If it is the same one used by the provider flow, then there is no need to do anything. Otherwise, change it to the correct port and click Update next to Endpoint text box.
10. Click on the CreateAccount method listed on the left side. Provide the input values on the right side and click Invoke. You should get the response shown below:
    
    CreateAccount request-response in Rational Application Developer
    
    
    

Now both the client and server applications are ready to apply WS-RM and WS-Security. If you want to create your own client application, use the RAD_WSDL.zip file provided with this article.

Importing and applying the policy set and bindings to the client and server applications

All of the required EAR, keystore, XML, and ZIP files for the policy set and bindings are provided with this article. To use then, complete the following steps:

Set up the keystore and truststore and import the policy set and bindings ino WebSphere Message Broker

1. If you have not already done so, download the WSRM_WSS.zip file at the bottom of the article, and then extract KeyStore.zip, WSSecurity-WSRMPolicySet.xml, and WSSecurity-WSRMProviderBinding.xml.
2. Store the KeyStore folder on your local system.
3. Unzip WMB_Policy_Bindings.zip and store WSSecurity-WSRMPolicySet.xml and WSSecurity-WSRMProviderBinding.xml in the KeyStore folder on your local system.
4. The BankProvider execution group is used as a provider. To set up the keystore and truststore on the BankProvider execution group, run the following commands on the runtime command console:
   
   Setup keystore and truststore on BankProvider execution group
   

   mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n truststoreFile -v c:\KeyStore\server.keystore mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n keystoreFile -v c:\KeyStore\server.keystore mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n keystorePass -v serverKeystore::password mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n truststorePass -v serverTruststore::password mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n keystoreType -v jks mqsichangeproperties <Broker Name> -e BankProvider -o ComIbmJVMManager -n truststoreType -v jks mqsistop <Broker Name> mqsisetdbparms <Broker Name> -n serverKeystore::password -u NA -p serverpass mqsisetdbparms <Broker Name> -n serverTruststore::password -u NA -p serverpass mqsisetdbparms <Broker Name> -n serverKeystore::keypass::servercert -u NA -p serverpass mqsisetdbparms <Broker Name> -n serverTruststore::keypass::servercert -u NA -p serverpass mqsistart <Broker Name>

   
   
5. Run the following commands to create and import the policy set and policy binding on the runtime command console:
   
   Create and import the policy set and policy binding on runtime command console
   

   mqsicreateconfigurableservice <broker name> -c PolicySets -o WSSecurity-WSRMPolicySet mqsicreateconfigurableservice <broker name> -c PolicySetBindings -o WSSecurity-WSRMProviderBinding mqsichangeproperties <broker name> -c PolicySets -o WSSecurity-WSRMPolicySet -n ws-security -p c:\KeyStore\WSSecurity-WSRMPolicySet.xml mqsichangeproperties <broker name> -c PolicySetBindings -o WSSecurity-WSRMProviderBinding -n associatedPolicySet -v WSSecurity-WSRMPolicySet mqsichangeproperties <broker name> -c PolicySetBindings -o WSSecurity-WSRMProviderBinding -n ws-security -p c:\KeyStore\WSSecurity-WSRMProviderBinding.xml

   
   
6. Open WebSphere Message Broker Explorer. Right-click on <BrokerName> and select Properties.
7. Under Security and Policy, select Policy Sets.
8. The WSSecurity-WSRMPolicySet policy set, and the WSSecurity-WSRMProviderBinding binding must be listed there, as shown below:
   
   Policy set with WS-Security and bindings in WebSphere Message Broker Explorer
   
   
   
9. Add WS-RM (with default configuration) as well in the WSSecurity-WSRMPolicySet policy set and click Finish.
10. Restart the broker to make the changes effective.
11. Open WebSphere Message Broker Explorer to check the policy set. The WSSecurity-WSRMPolicySet policy set should have WS-RM and WS-Security as shown below:
    
    Policy set with WS-Security, WS_RM and bindings in Message Broker Explorer
    
    
    

Now your execution group, policy set ,and binding are ready to use.

Apply the policy set and bindings to the provider flow

You must apply the policy set and bindings on the flow so that they can run with WS-RM and WS-Security enabled:

1. Open the BankProvider BAR file in the BankMessageFlowProject, select the Manage tab at bottom left, and select WSRM_ProviderFlow.cmf.
2. In the Provider Policy Set field, click Edit and select the WSSecurity-WSRMPolicySet policy that you imported.
3. In the Provider Policy Set Bindings field, click Edit and select the WSSecurity-WSRMProviderBinding binding that you imported, as shown below:
   
   BankProvider Bar file with policy set and bindings applied
   
   
   
4. Save and deploy the BAR file on the BankProvider execution group.

Import and apply the policy set and binding in Rational Application Developer

1. Unzip the WMB_Consumer_Policy.zip file provided with this article and import it into Rational Application Developer using the steps below:
   1. Click on File => Import in Rational Application Developer.
   2. Select WebSphere Policy Sets under Web service and click Next, as shown below:
      
      Import policy set in Rational Application Developer
      
      
      
   3. Browse to the WMB_Consumer_Policy.zip file in the next window and click Finish.
2. Now you must attach the same policy set and binding to the BankClient service, using the following steps:
   1. Navigate to BankClient => Services => Clients.
   2. Right-click on BankMessageSetSOAP_HTTP_Service and select Manage Policy Set Attachment, as shown below:
      
      Attach policy set in Rational Application Developer
      
      
      
   3. In the Client Policy Set Attachment window, click Next.
   4. In the next window, click Add under Application.
   5. In the Configure Policy Set and Binding window, select WMB Consumer Policy under Policy Set and then select Client sample under Binding, as shown below:
      
      Attach policy set and binding in Rational Application Developer
      
      
      
   6. Click OK. Ignore any warnings that appear.
   7. Click Finish.

Import and apply the policy set and binding in WebSphere Application Server

The next step is to import the WMB Consumer Policy and apply it to BankClientEAR in the administrative console. To do so, complete the following steps:

1. To launch the administrative console, right-click the WebSphere Application Server V8 runtime and click Administration => Run administrative console, as shown below:
   
   Open administrative console
   
   
   
2. Select Services => Policy Sets => Application policy sets, as shown below. You will see that some of the most common policy set configurations are already available. For the banking example, import the Bank Consumer Policy: Click Import and select From selected location:
   
   Import policy set in administrative console
   
   
   
3. Browse to WMB_Consumer_Policy.zip and click OK.
4. After you save the changes, you should see WMB Consumer Policy in the Application policy sets list.
5. Select Applications => Application Types => WebSphere enterprise applications, as shown below: You should see that BankClientEAR is already available.
   
   BankClientEAR in administrative console
   
   
   
6. Click on BankClientEAR.
7. Under Web Services Properties, select Service client policy set and bindings.
8. Select the check boxes for BankClientEAR and BankMessageSetSOAP_HTTP_Service. Click on the Attach Client Policy Set dropdown box and select WMB Consumer Policy from the list, as shown below:
   
   Attach client policy set in administrative console
   
   
   
9. Save the changes.
10. Again, select the check boxes for BankClientEAR and BankMessageSetSOAP_HTTP_Service. Click on the Assign Binding dropdown box and select WMB Customer Binding. After you save the changes, you should the screen shown below:
    
    Attach client policy and binding in administrative console
    
    
    
11. Go back to Applications => Application Types => WebSphere enterprise applications and restart BankClientEAR.

If you encounter any issues while attaching a policy set or binding, then import the BankClientEAR.ear file provided with this article into the administrative console, using the following steps:

1. In the administrative console, select Applications => Application Types => WebSphere enterprise applications. Select the checkbox for BankClientEAR and click Uninstall.
2. Click OK in next window and save the changes
3. Now click Install. Browse to BankClientEAR.ear and click Next.
4. Complete the installation with the default configuration by clicking Next.
5. Save the installation and start BankClientEAR.

Now the client and server are ready to test with WS-RM and WS-Security enabled.

Test web service application with WS-RM and WS-Security enabled

1. You can call the provider by using the web service client. Only application messages reach the message flow. If you want to see the additional WS-RM protocol messages such as create sequence, terminate sequence, message number, and the signed and encrypted messages that are passed between the provider and consumer, then you must set up a TCP/IP Monitor, as shown below:
   1. Issue the mqsireportproperties command to check which port your provider execution group is using, as shown in .
   2. In the workbench, go to Window => Preferences => Run/Debug => TCP/IP Monitor.
   3. Ensure that Show the TCP/IP Monitor view when there is activity is selected.
   4. Click Add. Set the Local monitoring port to an unused port on your system, such as 5555.
   5. Set the Type to TCP/IP.
   6. Set the Host name to localhost.
   7. Set Port to the port on which the BankProvider execution group is running.
   8. Click OK. You should see the screen shown below:
      
      TCP/IP Monitor configuration
      
      
      
   9. Select the TCP/IP Monitor you have just created and click Start.
   10. You have set up a TCP/IP Monitor to receive messages sent to an unused port on your system, such as 5555, and forward them to the provider flow.
2. Refresh the Web Service Test Client page. Change the port on the Endpoint to 5555 and click Update.
3. Click on the CreateAccount method on the left side. Provide the input values on the right side and click Invoke. You should get a response as shown below:
   
   CreateAccount Request-Response in Rational Application Developer
   
   
   
4. Click on the CreditRequest method on the left side. Provide the input values on the right side and click Invoke. You should not get any response, as shown below:
   
   CreditRequest Request-Response in Rational Application Developer
   
   
   
5. Click on the DebitRequest method on the left side. Provide the input values on the right side and click Invoke. You should get a response as shown below:
   
   DebitRequest Request-Response in Rational Application Developer
   
   
   
6. Click on the CheckBalance method on the left side. Provide the input values on the right side and click Invoke. You should get a response as shown below:
   
   CheckBalance Request-Response in Rational Application Developer
   
   
   
7. You can check in TCP/IP monitor that all requests and responses are encrypted and in sequence. You should get the create sequence messages and SOAP header as shown below:
   
   Messages in TCP/IP Monitor
   
   
   

Back to top

Download

Information about download methods

Resources

• Web services resources
  • Web Services Reliable Messaging Specification V1.1.
    The WS-RM specification from OASIS describes a protocol that enables messages to be transferred reliably between nodes implementing this protocol in the presence of software component, system, or network failures.
  • Introduction to Web Services Reliable Messaging
    An excellent technical introduction to WS-RM.
  • Implementing the Web Services Security standard
    This developerWorks article shows you how to implement WS-Security to secure a web service.
  • Web Services Reliable Messaging support in WebSphere Application Server V8
    These topics in the WebSphere Application Server V8 information center show you how to implement WS-RM in WebSphere Application Server V8.
  • Web Services Security support in WebSphere Application Server V8
    These topics in the WebSphere Application Server V8 information center show you how to configure WS-Security and bindings in WebSphere Application Server V8.
  • Applying Web Services Reliable Messaging to a web service, Part 1: A hands-on approach using WebSphere Application Server V8 and Rational Application Developer V7.5
    This developerWorks article shows you how to configure WS-RM for a JAX-WS web service and web service client.
  • Developing a Web Services Reliable Messaging solution using WebSphere Message Broker V8
    This developerWorks article shows you how WebSphere Message Broker V8 supports WS-RM.
  • Configuring Web Services Reliable Messaging in WebSphere Message Broker V8
    This topic in the WebSphere Message Broker V8 information center shows you how to configure message flows to use WS-RM.
  
  
• WebSphere Application Server resources
  • WebSphere Application Server V8 information center
    A single Web portal to all WebSphere Application Server documentation, with conceptual, task, and reference information on installing, configuring, and using WebSphere Application Server.
  • WebSphere Application Server developer resources page
    Technical resources to help you use WebSphere Application Server.
  • WebSphere Application Server product page
    Product descriptions, product news, training information, support information, and more.
  • WebSphere Application Server information roadmaps
    Roadmap of articles and resources to help you with installation, migration, administration, development, troubleshooting, and understanding the underlying technology.
  • WebSphere Application Server documentation library
    WebSphere Application Server product manuals.
  • WebSphere Application Server support
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • Download a free trial version of WebSphere Application Server V7
    WebSphere Application Server V7 is a Java EE 5 certified, EJB 3.0 supported application platform that drives business agility with an innovative, performance based foundation for your SOA environment on the broadest range of platforms in the industry.
  
  
• WebSphere Message Broker resources
  • WebSphere Message Broker V8 information center
    A single Web portal to all WebSphere Message Broker V8 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
  • WebSphere Message Broker developer resources page
    Technical resources to help you use WebSphere Message Broker for connectivity, universal data transformation, and enterprise-level integration of disparate services, applications, and platforms to power your SOA.
  • WebSphere Message Broker product page
    Product descriptions, product news, training information, support information, and more.
  • Download free trial version of WebSphere Message Broker
    WebSphere Message Broker is an ESB built for universal connectivity and transformation in heterogeneous IT environments. It distributes information and data generated by business events in real time to people, applications, and devices throughout your extended enterprise and beyond.
  • WebSphere Message Broker documentation library
    WebSphere Message Broker specifications and manuals.
  • WebSphere Message Broker forum
    Get answers to technical questions and share your expertise with other WebSphere Message Broker users.
  • WebSphere Message Broker support page
    A searchable database of support problems and their solutions, plus downloads, fixes, and problem tracking.
  • IBM Training course: WebSphere Message Broker V8 Development
    This course from IBM Training shows you how to use the components of the WebSphere Message Broker development and runtime environments to develop and troubleshoot message flows that use ESQL, Java, and PHP to transform messages.
  • Youtube tutorial: Integrating Microsoft .NET code in a WebSphere Message Broker V8 message flow
    This five-minute youtube tutorial shows you how simple it is to use WebSphere Message Broker V8 to build a message flow that includes Microsoft .NET code. Microsoft Visual Studio is used to build .NET code in C#, which is then integrated into a message flow using Message Broker and an HTTP RESTful interface.
  
  
• WebSphere resources
  • developerWorks WebSphere developer resources
    Technical information and resources for developers who use WebSphere products. developerWorks WebSphere provides product downloads, how-to information, support resources, and a free technical library of more than 2000 technical articles, tutorials, best practices, IBM Redbooks, and online product manuals.
  • developerWorks WebSphere application integration developer resources
    How-to articles, downloads, tutorials, education, product info, and other resources to help you build WebSphere application integration and business integration solutions.
  • Most popular WebSphere trial downloads
    No-charge trial downloads for key WebSphere products.
  • WebSphere forums
    Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  • WebSphere on-demand demos
    Download and watch these self-running demos, and learn how WebSphere products and technologies can help your company respond to the rapidly changing and increasingly complex business environment.
  • WebSphere-related articles on developerWorks
    Over 3000 edited and categorized articles on WebSphere and related technologies by top practitioners and consultants inside and outside IBM. Search for what you need.
  • developerWorks WebSphere weekly newsletter
    The developerWorks newsletter gives you the latest articles and information only on those topics that interest you. In addition to WebSphere, you can select from Java, Linux, Open source, Rational, SOA, Web services, and other topics. Subscribe now and design your custom mailing.
  • WebSphere-related books from IBM Press
    Convenient online ordering through Barnes & Noble.
  • WebSphere-related events
    Conferences, trade shows, Webcasts, and other events around the world of interest to WebSphere developers.
  
  
• developerWorks resources
  • Trial downloads for IBM software products
    No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  • developerWorks business process management developer resources
    BPM how-to articles, downloads, tutorials, education, product info, and other resources to help you model, assemble, deploy, and manage business processes.
  • developerWorks blogs
    Join a conversation with developerWorks users and authors, and IBM editors and developers.
  • developerWorks tech briefings
    Free technical sessions by IBM experts to accelerate your learning curve and help you succeed in your most challenging software projects. Sessions range from one-hour virtual briefings to half-day and full-day live sessions in cities worldwide.
  • developerWorks podcasts
    Listen to interesting and offbeat interviews and discussions with software innovators.
  • developerWorks on Twitter
    Check out recent Twitter messages and URLs.
  • IBM Education Assistant
    A collection of multimedia educational modules that will help you better understand IBM software products and use them more effectively to meet your business requirements.
  
  

About the author

Shelly Gupta is a Software Engineer on the WebSphere Message Broker Development Team in India. She is a post-graduate from Banasthali Vidhyapeeth in Jaipur, India, and has been working for IBM for five years. You can contact Shelly at shellgup@in.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Overview of banking application
• Integrating a web service on WebSphere Message Broker and a JAX-WS client on WebSphere Application Server
• Importing and applying the policy set and bindings to the client and server applications
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers