Applying the WS-RM and WS-Security specifications to web services in WebSphere Application Server and WebSphere Message Broker: Part 1

The Web Services Reliable Messaging (WS-RM) and Web Services Security (WS-Security) specifications describe protocols that enable encrypted messages to be delivered reliably between distributed applications, even when there are software component, system, or network failures. This article series shows you how to implement a web services application with WS-RM and WS-Security enabled on WebSphere Application Server V8 and WebSphere Message Broker V8.

Share:

Shelly Gupta (shellgup@in.ibm.com), Software Engineer, WebSphere Message Broker Development Team, IBM

Photo of Shelly GuptaShelly 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.



23 January 2013

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:
    Figure 1. Bank application project structure in WebSphere Message Broker
    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:
    Figure 2. WSRM_ProviderFlow message flow
    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:
    Figure 3. BankClient project structure in Rational Application Developer
    BankClient project structure in 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:
    Figure 4. Web service TestClient in Rational Application Developer
    WebService TestClient in Rational Application Developer
  8. Issue the following mqsireportproperties command to check which port the BankProvider execution group is using:
    Listing 1. 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:
    Figure 5. CreateAccount request-response in Rational Application Developer
    CreateAccount request-response in 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:
    Listing 2. 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:
    Listing 3. 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:
    Figure 6. Policy set with WS-Security and bindings in WebSphere Message Broker Explorer
    Policy set with WS-Security and bindings in 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:
    Figure 7. Policy set with WS-Security, WS_RM and bindings in Message Broker Explorer
    Policy set with WS-RM, WS-Security, and bindings in WebSphere 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:
    Figure 8. BankProvider Bar file with policy set and bindings applied
    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:
      Figure 9. Import policy set in Rational Application Developer
      Import policy set in 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:
      Figure 10. Attach policy set in Rational Application Developer
      Attach policy set in 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:
      Figure 11. Attach policy set and binding in Rational Application Developer
      Attach policy set and binding in 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:
    Figure 12. Open administrative console
    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:
    Figure 13. Import policy set in administrative console
    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.
    Figure 14. BankClientEAR in administrative console
    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:
    Figure 15. Attach client policy set in administrative console
    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:
    Figure 16. Attach client policy and binding in administrative console
    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 Listing 1.
    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:
      Figure 17. TCP/IP Monitor configuration
      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:
    Figure 18. CreateAccount Request-Response in Rational Application Developer
    CreateAccount Request-Response in 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:
    Figure 19. CreditRequest Request-Response in Rational Application Developer
    CreditRequest Request-Response in 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:
    Figure 20. DebitRequest Request-Response in Rational Application Developer
    DebitRequest Request-Response in 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:
    Figure 21. CheckBalance Request-Response in Rational Application Developer
    CheckBalance Request-Response in 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:
    Figure 22. Messages in TCP/IP Monitor
    Messages in TCP/IP Monitor
    Figure 23. Messages in TCP/IP Monitor
    Messages in TCP/IP Monitor

Download

DescriptionNameSize
Code samplesWSRM_WSS.zip250 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=856139
ArticleTitle=Applying the WS-RM and WS-Security specifications to web services in WebSphere Application Server and WebSphere Message Broker: Part 1
publish-date=01232013