Prerequisites for this example

• WebSphere Application Server 6.1 with Web Services Feature Pack (WSFP)
• WebSphere DataPower SOA Appliance XS40 or XI50, with firmware version 3.6.1 or greater
• Security credentials for web services Security in the form of JCEKS key stores or the private keys/public certificates required for the specified cryptographic operations

In this article

In this article we build on the previous scenario by deploying the WebSphere DataPower SOA Appliance to process the WS-Security portion for the application server. A web service Proxy will be created on the WebSphere DataPower SOA Appliance to receive the web service request sent to the EchoService service.

In this article, we will cover the following tasks:

• Configure a web service proxy in the DataPower SOA Appliance to perform the web services security processing for a deployed web service
• Prepare JCE and JCEKS security credentials for this example
• Use the WebSphere Application Server console to disable web service security policies for the sample service

Introduction

In part 1, we used Rational Application Developer to import a sample EchoService client EAR and enabled it with WS-Security. The sample web service Client was then installed on WebSphere Application Server. The EchoService was installed and configured with WS-Security. The browser was used to enter a message to be sent from the web service EchoService Client application to the web service EchoService service. The message was echoed back to the Web Service Client.

The steps in this article will demonstrate how to off-load the WS-Security processing portion from the Server to the DataPower Web Service proxy and defer the remaining web service processing to the application server. This allows the resource-intensive processing to be done by the WebSphere DataPower SOA Appliance and the application business logic to be processed by the application server.

The WebSphere DataPower SOA Appliance is a purpose-built network device that helps to secure and accelerate XML and web services processing. While the WebSphere DataPower SOA Appliance has an extensive list of capabilities and features, this article focuses on the web services aspects of the appliance. The web services capabilities relevant to this article include: XML message-level security processing for encryption/decryption, digital signature signing/verification, WS-Security, XML schema validation, web services management support, and detailed logging and auditing. Secure XML processing can be extremely resource-intensive. The WebSphere DataPower SOA Appliance offers XML processing and security that may not be available in traditional XML engines. Allowing the WebSphere DataPower SOA Appliance to perform process-intensive portions of the web service requests accelerates and decreases the load on the application server's web service.

To review the configuration in part 1, we configured an EchoClient to communicate securely to an EchoService using WS-Security asymmetric signing and encryption. The following depicts the part 1 of the web service configuration:

In this scenario all elements of the SOAP message are processed by the web services engine in WebSphere Application Server (WAS) Feature Pack for 6.1. To off-load the security processing, the WebSphere DataPower SOA Appliance becomes the targeted endpoint for the web service request. The WS-Security policy processing will be done by the WebSphere DataPower SOA Appliance then forwards the web service request to the application server to process the service operation. The default WS-Security policy will be removed from the web services application server service. For the WebSphere DataPower SOA Appliance to process the WS-Security policy, the necessary security credentials, WSDL, and application server addressability information will be configured with the WebSphere DataPower SOA Appliance's web service proxy. The WebSphere DataPower SOA Appliance configuration will use a browser to access the DataPower's webGUI. The following figure is an overview of the web service with the security being off-loaded and processed by the WebSphere DataPower SOA Appliance:

In this configuration, WAS default security policy has been removed from the web services engine. The request received from the WebSphere DataPower SOA Appliance is now dispatched directly to the web service endpoint for processing. The credentials and the WSDL for the specified web service have been exported and configured on the WebSphere DataPower SOA Appliance.

Steps for this sample configuration

Off-loading the security processing to the WebSphere DataPower SOA Appliance will require the device to have access to the web service security credentials. Steps will be performed to make these available.

The WebSphere DataPower SOA Appliance web service proxy will be configured to process the WS-Security default policy. This security policy performs digital signing and verification, encryption and decryption using asymmetric cryptography.

Using the WAS Console, we will ensure that the WS-Security is no longer configured. Since the WebSphere DataPower SOA Appliance is performing this task, this is no longer needed.

We will use a browser accessing the EchoService client to send messages verifying the scenario is configured properly.

Key and certificate management

The sample configuration for this example uses two different type of keystores that are shipped with WAS WSFP. The keystore used in the WS-Security default policy for digital signatures is the standard JDK keystore. The keystore used for encryption is the JCE keystore (Java Cryptography Extension). In order for the WebSphere DataPower SOA Appliance to perform the digital signature, encryption, and decryption actions, the keys and certificates need to be uploaded from these keystores. In order to upload the JKS, the keystores will first need to be converted to JCE keystores. Use the following steps to prepare the keystores for uploading to the WebSphere DataPower SOA Appliance:

1. Copy ${USER_INSTALL_ROOT}/etc/ws-security/samples/dsig-receiver.ks to a temporary directory /temp.
2. For convenience copy the following two files to the temporary directory as well.

   ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks

   ${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer

   (If gsk7 is available, the gsk7cmd.exe can be used to do the conversion.)
3. Use the following command to convert the JKS keystore to a JCE keystore.

   keytool -keypasswd -alias soapprovider -storetype jceks -keystore dsig-receiver.ks -v -storepass server -keypass server -new server

4. This temporary directory will be used later as the source directory for uploading the keys and certificates to the apppliance from these keystores.

Back to top

Configure the WebSphere DataPower SOA Appliance for Web Services default security policy

This section shows step-by-step how to configure the WebSphere DataPower SOA Appliance with a web service proxy. This proxy serves as the web service endpoint for the EchoClient application, performs the web service security processing, and then forwards the remaining SOAP message to the final WAS web service endpoint to process the requested operation.

The web service proxy configuration for this example has a HTTP front end configured for the desired port. The remote system address and port will be configured to forward the request to the targeted web service endpoint. Request and response processing rules are created to manipulate the SOAP message as required to conform to the desired security policy. For the encryption/decryption, sign/verify processing, the necessary keystores are uploaded to the DataPower Appliance. Crypto objects are created and configured into the processing rules. Each of the processing rules are linked via input/output/pipe as necessary to complete a fully processed request.

The WebSphere DataPower SOA Appliance allows the crypto objects to be created individually and then selected in the configuration needed. In this example, the crypto objects are created as needed while configuring the web service proxy.

For configuration context, the WebSphere DataPower SOA Appliance browser logon is from the WAS machine providing the web service. The sample keystores, converted keystores, certificates, and the exported WSDL described above will need to be available for the WebSphere DataPower SOA Appliance upload processes.

1. Using a browser, login into the WebSphere DataPower SOA Appliance WebGUI using the proper user id, password, and domain.
2. Click the icon Web Service Proxy
   
   Figure 3: WebSphere DataPower SOA Appliance Configuration Selections
   
   
   
3. Create new web service proxy, click the add button
4. Enter a Web proxy name, WSP-EchoService"
5. For Web Service Proxy WSDLs, select Add WSDL
6. Upload the WSDL exported from the WebSphere Console for the EchoService (above)
7. Click the Upload button
8. Browse or enter the location of the WSDL file (unzipped) for the EchoService
9. Verify the file name to save-as
10. Select the Upload button
    
    Figure 4: Configure WebSphere DataPower SOA Appliance web service proxy
    
    
    
11. Select Next
12. To setup the front side handler or local EndPoint handler, create a new front side handler.
13. Choose the Http Front Side Handler from the menu options.
14. Enter a name for the front side handler, FSH-HTTP-EchoService
15. Enter the IP address for the front side handler. Leaving this value 0.0.0.0 will use the default configured DataPower address.
16. Enter the desired port for the EndPoint, 9080
17. Verify other desired settings, this example takes the defaults
18. Select Apply
19. With "FSH-HTTP-EchoService" in the pull down window, Select "+ Add" to the right to make it the active front side handler.
20. Select Next
    
    Figure 5: Configure HTTP Front Side Handler
    
    
    
21. Enter the Remote setting for the WAS web service Endpoint where the operation will be processed.
22. Enter the IP address or hostname, port (9080), and URI (/WSSampleSei/EchoService)
    
    Figure 6: Configure HTTP Back Side Handler
    
    
    
23. Select Next.

At this point the WebSphere DataPower SOA Appliance is configured to accept requests and forward them to the remote system and perform no processing. This screen is an example of the configuration so far:

WebSphere DataPower SOA Appliance Policy configuration

The security processing policy needs to be configured to match the WAS WS-Security default policy. We will configure them in the order of processing flow as follows:

Request Rule

• Decrypt the incoming SOAP message
• Verify the incoming SOAP message
• Use a Transform to remove the SOAP security headers for the WAS EndPoint

Response Rule

• Sign the outgoing SOAP message
• Encrypt the outgoing SOAP message

Configure Request Decrypt Rule

1. Select the Policy tab at the top of the Configure Web Service Proxy screen
2. Click on (request-rule) to get the rule configuration panel
3. Click on the decrypt icon and drag it to the processing line after the match action icon and drop
4. Double click on the decrypt icon just dropped to configure the encryption settings
5. For the field Decrypt Key click to create the crypto decryption object
6. Enter Name for the crypto key, WS-enc-receiver-privatekey
7. Select the Upload button to upload the private key from our JCEKS KeyStore
8. Select the Source Java Key Store
9. Browse or enter file name for ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks
10. For Key store type, enter JCEKS
11. For Key store password, enter storepass
12. Tab to the Key to upload: field and select the (key)
13. For Key password, enter keypass
14. Tab to the Save as: field and enter file name, WS-enc-receiver-bob.pem
15. Click Upload button (this will complete the Configure Crypto Key screen)
    
    Figure 8: Upload Request Certificate
    
    
    
16. Verify that the Crypto Key just created (WS-enc-receiver-privatekey) is selected in the Decrypt Key field.
17. Click the Done button
    
    Figure 9: Configure Decryption Action
    
    
    
18. Next choose the "Proxy Settings" tab. In the "Decrypt Key" pull down field, select "WS-enc-receiver-privatekey" that was just configured.
19. Click the Apply button to save the current configuration

Configure Request Verify Rule

1. From the Policy tab page, click on (request-rule) to get the rule configuration panel
2. Click on the verify icon and drag it to the processing line after the decrypt action icon previously created and drop the icon onto the line
3. Double click on the verify icon just dropped to configure the verify settings
4. For name, enter "WS-Verify-Credential".
5. For the field "Certificates", click "+" to create a new certificate for the signer to be used to verify the incoming request.
6. Enter Name for the crypto key, WS-Verify-Soap-ca
7. Select the Upload button to upload the verify certificate
8. Select the Source File option
9. Browse or enter file name for ${USER_INSTALL_ROOT}/etc/ws-security/samples/intca2.cer
10. Tab to the Save as field and enter file name, WS-intca2.cer
11. Click the Upload button (this will complete the Configure Crypto Key screen)
    
    Figure 10: Configure Crypto Validation Credentials
    
    
    
12. Verify that the Crypto Key just created (WS-Verify-Soap-ca) is selected in the Validation Credential field.
13. Click the Apply button to save
14. Select the Advanced tab to expand additional settings. Verify that the timestamp settings have a reasonable response window. A value should be chosen that tolerates client and DataPower system time mismatches plus network response delays. Set to 300.
15. Click the Done button
    
    figure 11: Configure Verify Action
    
    
    
16. Click the Apply button to save the current configuration

Configure Request Transform Rule

1. From the Policy tab page, click on (request-rule) to get the rule configuration panel
2. Click on the transform icon and drag it to the processing line after the transform action icon previously created icon and drop
3. Double click on the transform icon just dropped to configure the verify settings
4. Select the Input field. This links the transform action to the processing stream that will be forwarded.
5. For the Processing Control File setting, select the XSL stylesheet location store:/// in the first pull down menu, choose the XSL document transformation stylesheet strip-security-header.xsl in the second pull down menu.
   
   Figure 12: Configure Transform Action
   
   
   
6. Click the Done button
7. Click the Apply button to save the current configuration

1. From the Policy tab page, click on (request-rule) to get the rule configuration panel
2. Double click on the Results icon at the end of the configured rule settings
3. Verify that it is selected for the Input field. This sets the stream that will be sent to the backend service.
4. Click the Done button
   
   Figure 13: Configure Request Output
   
   
   
5. Click the Apply button to save the current configuration

1. From the Policy tab on the "Configure Web Service Proxy" page, click on (response-rule) to get the rule configuration panel
2. Click on the Sign icon and drag it to the processing line after the match action icon
3. Double click on the Sign icon just dropped to configure the Sign action settings
4. Choose the Advanced tab
5. Select the Envelope Method and the option WSSec method
6. Select message type Selected Elements
7. Create a Document Crypto Map
8. On new screen Enter name, WS-Sec-Sign-Map
9. For XPATH expression, enter, //*[local-name()='Body']
10. Select the Add button
11. For next XPATH expression enter, //*[local-name()='Header']/*[local-name()='Action']
12. Select the Add button
13. For next XPATH expression enter, //*[local-name()='Header']/*[local-name()='RelatesTo']
14. Select the Add button
15. Select Apply to complete the Document Crypto Map.
    
    Figure 14: Configure Signature Map
    
    
    
16. Verify that the newly created "WS-Sec-Sign-Map" is selected for the "Document Crypto Map" field.
17. Create new signing Key for the Key field
18. Enter name for private crypto key to be used for signing, WS-dsig-receiver-private
19. Select the upload button
20. Select Java Key Store
21. Browse for the converted JCEKS dsig-receiver.jceks file as described above.
22. Enter JCEKS in Key store type
23. Enter keystore password, server
24. Select the key to upload, soapprovider (key)
25. Enter key password, server
26. Enter save-as: WS-dsig-receiver-soapprovider.pem
27. Select the upload button
    
    Figure 15: Upload Digital Signature Key
    
    
    
28. Verify the file name for the private key just uploaded is selected in the File Name field.
29. Select the Apply button to complete
30. Create new Certificate, this will be the soapprovider public key
31. Enter name for public crypto certificate, WS-dsig-receiver-public
32. Select the upload button
33. Select Java Key Store
34. Browse for the converted JCEKS dsig-receiver.jceks file as described above
35. Enter JCEKS in Key store type
36. Enter keystore password, server
37. Select the certificate to upload, soapprovider (certificate)
38. Enter key password, server
39. Enter save-as: WS-dsig-receiver-soapprovider.cer
40. Select the upload button
    
    Figure 16: Configure Digital Signature Crypto Certificate
    
    
    
41. Select the continue button
42. Verify the file name for the Configure Crypto Certificate for the public key just uploaded is selected.
    
    Figure 17: Configure Digital Signature Crypto Certificate
    
    
    
43. Select the Apply button to complete
44. Select Done to complete the sign action.
    
    Figure 18: Configure Sign Action
    
    
    
45. Click the Apply button to save the current configuration

1. From the Policy tab page, click on (response-rule) to get the rule configuration panel
2. Click on the Encrypt icon and drag it to the processing line after the Sign action icon just created.
3. Double click on the Encrypt icon just dropped to configure the Encrypt action settings
4. For the Envelope method, select WSSec Encryption
5. For Message type, select the Selected Elements
6. For Document Crypto Map, enter a new map that will select the elements to be encrypted with in the schema.
7. Enter name for Document Crypto Map, WS-encrypt-map
8. Enter the XPATH Expression, //*[local-name()='Signature']
9. Select the Add button
10. Select the Apply button to complete.
    
    Figure 19: Configure Crypto Map
    
    
    
11. Select the Advance tab at the top of the Configure Encrypt Action screen
12. For Recipient Certificate Select, add a new certificate to encrypt the signature.
13. Enter name for Crypto Certificate, WS-enc-receiver-publickey
14. Select the Upload button on the File Name field
15. Select for source, Java Key Store
16. Browse or enter file name for ${USER_INSTALL_ROOT}/etc/ws-security/samples/enc-receiver.jceks
17. Enter key store type, JCEKS
18. Enter key store password, storepass
19. Select the Key to upload, alice (certificate) …
20. Select the Key password, keypass
21. Enter for file name to Save-as, WS-enc-receiver-alice-cert.cer
22. Select the upload button
23. Verify the File Name field is configured for the public key just uploaded.
24. Select the continue button
25. Select the Apply button to complete the Configure Crypto Certificate panel.
26. For the Symmetric Encryption Algorithm, select AES128-CBC
    
    Figure 20: Configure Encryption Certificate
    
    
    
27. Select the Done button to complete the Configure Encrypt Action.
28. Click the Apply button to save the current configuration

1. From the Policy tab page, click on (response-rule) to get the rule configuration panel
2. Click on the Encrypt icon and drag it to the processing line after the previous Encrypt action icon.
3. Double click on the Encrypt icon just dropped to configure the second Encrypt action settings
4. Select the Advance tab at the top of the Configure Encrypt Action screen
5. For Envelope Method, select WSSec Encryption
6. For Message Type, select Soap Message
7. For Recipient Certificate select the pull-down bar, choose previously created certificate, WS-enc-receiver-publickey
8. For Symmetric Encryption Algorithm, select AES128-CBC
9. Select the Done button to complete the Configure Encrypt Action.
   
   Figure 21: Configure Encryption Action
   
   
   
10. Select the Apply button on Configure Web Service Proxy to apply the response configuration changes
    
    Figure 22: Configure Web Service Proxy response action
    
    
    
11. Select Save Config at the top right of the screen to save the current domain configuration.

The WebSphere DataPower SOA Appliance is now configured to perform the web services default security policy for the Web Services EchoService. Web Services requests will be sent from the WebSphere DataPower SOA Appliance to the WebSphere Application Server service as a clear SOAP messages. However, from an earlier configuration step, the WebSphere Application Server web service (EchoService) is expecting signed and encrypted messages. WS-Security needs to be turned off for the EchoService to allow the request to be passed to the service end point for processing.

To turn off WS-Security for the EchoService, perform the following steps.

1. From the WAS console (left panel) Services->Service providers, click on EchoService.
   
   Figure 23: Service Providers
   
   
   
2. Select all the entries. Click Detach from the menu.
   
   Figure 24: Service Provider Policy Attachments
   
   
   
3. The EchoService Service is now configured with no WS-Security.
   
   Figure 25: Service Provider Policy Attachments removed
   
   
   
4. At the top of the WAS Console screen, click Save to store the changes.

The configuration is now ready. We can use the Demo servlet configured in Part 1 of this series to send secure messages to the WebSphere DataPower SOA Appliance web service proxy and then to the back-end service. Refer to Part 1 to launch the browser with the Demo servlet. Select the message type to be sent. Enter the test message string to be sent. Accept the message count default. In the Service URI, you can choose the IP address, hostname, and port of the application server and port that the message should be sent. The message will be echoed in the dialog box below the "Send" button.

Summary/Conclusions

In part 1 of this series we used Rational Application Developer to import a sample EchoService client EAR and enabled it with WS-Security. The sample Web Service Client was then installed on WebSphere Application Server. The EchoService was installed and configured with WS-Security. The browser was used to enter a message to be sent from the Web Service EchoService Client application to the Web Service EchoService service. The message was echoed back to the Web Service Client.

Prior to the message being sent onto the wire from the client, WS-Security used asymmetric keys to digitally sign and encrypt the message. When the message was received at the application server, WS-Security used the asymmetric keys to verify the digital signature and decrypt the message. The message was then passed to the web service for processing. In this scenario the message was simply echoed in the response. WS-Security used the asymmetric keys to digitally sign and encrypt the response message prior to sending the message onto the wire. At the client WS-Security receives the response, decrypts the message, then validates the digital signature. The message is then consequently echoed on the browser screen.

In this part of series, we configured the WebSphere DataPower SOA Appliance to perform the WS-Security portion of the processing. A web service proxy was configured to become the web service endpoint via a Front End Handler. The front end handler matches the service request with the WSDL that was uploaded to the WebSphere DataPower SOA Appliance. When the request matches the configured WSDL, the WebSphere DataPower SOA Appliance begins to process the request using the configured request policy. In this case the message is decrypted using Bob's private key. Then the digital signature of the request is verified using the soaprequestor public key. Next a transform rule is executed to remove the already processed security headers. The request, now decrypted and verified to match the digital signature, is sent to the WebSphere Application Server EchoService for processing. With WS-Security removed from the service, the request is immediately processed by the service logic.

When the EchoService issues a response, it is sent to the DataPower Web Service Proxy to add the specified security attributes. In the response processing, a digital signature is applied to the body and headers using the soapprovider private key. Next the digital signature is encrypted using the public key for Alice. Next the response message is encrypted using the public key for Alice. The DataPower Web Service Proxy now sends the secured response to the initial EchoService request.

As you can see, once the WebSphere DataPower SOA Appliance is configured for the WS-Security processing policy, The web service message's security credentials can be processed independently by the purpose built WebSphere DataPower SOA Appliance. With it's speed of processing security credentials, substantial scalability and performance can be realized.

Resources

Learn

• Sample Keystore Configurations section provides information on the default Web Services Security and default Bindings. In the Sample keystore configurations section provides information about the sample keystore files and passwords.
  
  
• Tracing SOAP messages that request web services can be achieved by using the tcpmon tool.
  
  
• Troubleshooting JAX-WS applications with the WebSphere Application Server V6.1 Feature Pack for Web Services A developer works article describing common error conditions and some suggested methods for correcting them.
  
  
• In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  

Get products and technologies

• Feature Pack for Web Services for WebSphere Application Server V6.1 for Web Services extends the capabilities of Application Server V6.1 to enable Web Services messages to be sent asynchronously, reliably, and securely, focusing on interoperability with other vendors.
  
  
• WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy network devices that simplify, help secure, and accelerate your XML and web services deployments while extending your SOA infrastructure.
  
  
• WebSphere DataPower SOA Appliance Firmware and Documentation download site can be found here.
  
  

Discuss

• Participate in the discussion forum.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Prerequisites for this example
• In this article
• Introduction
• Steps for this sample configuration
• Key and certificate management
• Configure the WebSphere DataPower SOA Appliance for Web Services default security policy
• WebSphere DataPower SOA Appliance Policy configuration
• Summary/Conclusions
• Resources
• About the authors
• 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 SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers