Enable WS-Security and Transport Layer Security in IBM Business Process Manager Standard

Learn how you can leverage WS-Security and Transport Layer Security (TLS) when working with outbound integrations using the web services integration component in IBM® Business Process Manager Standard.

Parasuram Balakrishnan (bparasuram@in.ibm.com), Senior IT Consultant, IBM

Parasumar Balakrishnan photoParasuram Balakrishnan is a Senior IT Consultant in the IBM Software Services for WebSphere BPM Practice in India. In this role, he focuses on the architecture, design and implementation of IT solutions involving BPM, SOA and middleware technologies. He has worked closely with a number of clients across various industries such as manufacturing, financial services, and government organizations.



28 August 2013

Introduction

IBM Business Process Manager Standard V8.0.1 (IBM BPM), provides a web services integration component that enables IBM BPM services to invoke external web services. The integration component provides the support to discover web services, generate IBM BPM data types corresponding to WSDLs, and exchange SOAP messages with remote services.

In many cases, web services invocation needs to happen securely. Commonly, this is achieved by using Transport Layer Security (TLS) or Secure Sockets Layer (SSL) to secure request and response message exchanges. However, this approach has some limitations, for example, when using an intermediary to route messages. In this case, because the intermediary will need to decrypt data, it would help to secure message parts independent of transport security. Because WS-Security protocol helps you encrypt SOAP messages, it enhances security when routing messages through intermediaries.

WS-Security is used to address three different security requirements when sending or receiving SOAP messages:

  • Assuring the integrity of a SOAP message, that is, it has not been tampered with when sent to a receiver. This is done by using a digital signature.
  • Confirming the identity of the sender or receiver of a SOAP message. This is done by using security tokens such as the Username token.
  • Assuring that the message is being sent confidentially. This is done by encryption and decryption of a SOAP message or parts of a SOAP message.

In this article, we'll look at how to secure web services requests that originate from IBM BPM using the web services integration component. We'll first describe how to leverage TLS and then apply WS-Security to secure the messages. In the context of WS-Security, we'll focus on achieving message integrity and confidentiality. The objective of the article is not to introduce the concepts of WS-Security or TSL. For more information on these concepts, refer to the suggested resources.

To illustrate the working of WS-Security and TSL with IBM BPM acting as web services client, we'll use a mock service running on SoapUI, which will henceforth be referred to as the web services provider.

The test scenario

The test scenario, illustrated in Figure 1 comprises an instance of the web services requester and a web services provider, each configured to support transport and message-level security.

Figure 1. Test scenario
Test scenario

Prerequisites

To complete the steps in this article, you'll need the following software:

  • IBM Business Process Manager V8.0.1 with Process Center configured
  • IBM Process Designer V8.0.1
  • SoapUI 4.5.2

Overview of the steps

Following is a high-level overview of the steps we'll cover in this article:

  1. Set up the keystores required to support secure interaction.
  2. Set up the web services provider:
    • Create a new project and import the sample WSDL into the web services provider.
    • Generate a mock service corresponding to the WSDL in the web services provider.
  3. Configure Transport Layer Security in IBM BPM and in the web services provider.
  4. Create an IBM BPM sample and invoke the web services securely.
  5. Configure IBM BPM to support message-level security for web services interaction.
  6. Configure the web services provider to support message-level security and test the scenarios.

Set up the keystores required to support secure interaction

In this section we'll set up two keystores, one to be used by IBM BPM and the other by the web services provider. For the purposes of this article, we'll use those keystores to contain the personal certificate as well as the signer certificates (public keys) of the interaction partner. In addition, we'll use the keystore in our configuration to support SSL as well as message-level security. In a real-world scenario, you'll have to deal with separate truststores as well as certificate trust chains at each end.

Create the keystore for IBM BPM

To create a keystore, complete the following steps:

  1. From the \bin directory under the IBM BPM installation root directory, run ikeyman.bat.
  2. Select Key => Database File => New.
  3. Select JKS as the key database type, specify clientkeystore.jks as the file name, and choose an appropriate directory for the key file, as shown in Figure 2.
  4. At the password prompt enter a password of your choice, such as WebAS, and click OK.
    Figure 2. Create the keystore
    Create the keystore
  5. Now you need to create a new self-signed certificate. This represents a personal certificate and contains a public and private key pair. The private key is used by IBM BPM to sign the outbound request message and to decrypt the incoming response message.

    The public key will be extracted as the signer certificate and imported into the truststore of the web services provider. This enables the web services provider to verify the digital signature is also used for encrypting the outbound request message. In addition, by adding the IBM BPM public key to the truststore of the web services provider, it can be used to authenticate IBM BPM during SSL handshake (client authentication).

    Select New Self-Signed and specify the following:

    • Key label: ClientCertificate
    • Common Name: bpms.com
    • Organization: MyOrg
  6. Extract the certificate by selecting Extract Certificate, then specify the following:
    • Data type: Base 64 encoded ASCII data
    • Certificate file name: clientcertificate.arm
    • Location: C:\temp3 (or any directory of your choice)

Create the keystore for the web services provider

Repeat the steps in Create the keystore for IBM BPM to create a keystore for the web services provider. The differences are:

  1. In step 3, specify serverkeystore.jks for the keystore name.
  2. In step 5, you need to create a self-signed certificate, which represents a personal certificate and contains a public and private key. The private key is used by the web services provider to sign the outbound response message and to decrypt the incoming request message.

    The public key will be extracted as the signer certificate and imported into the truststore of IBM BPM. This enables IBM BPM to encrypt the request message and verify the digital signature of the incoming response message. In addition, by adding the public key of the web services provider to the truststore of IBM BPM, it can authenticate the web services provider during SSL handshake (server authentication).

  3. In step 6, specify the following values:
    • Key label: ServerCertificate
    • Common Name: serviceprovider.com
    • Organization: MyOrg
  4. In step 7, specify the following values:
    • Data type: Base 64 encoded ASCII data
    • Certificate file name: servercertificate.arm
    • Location: C:\temp3 (or any directory of your choice)

Now you're ready to exchange the certificates and import them into the respective truststores: clientcertificate.arm will be added to serverkeystore.jks and servercertificate.arm to clientstore.jks. Remember that for the purpose of this article we're using the same file for both the keystore and the truststore.

  1. Using ikeyman, open serverkeystore.jks and select Signer Certificates under Key database content.
  2. Select Add and specify the following:
    • File name: clientcertificate.arm
    • Location: C:\temp3
  3. Click OK and enter a label of clientcertificate.
  4. Open clientkeystore.jks and select Signer Certificates under Key database content.
  5. Select Add and specify the following:
    • File name: servercertificate.arm
    • Location: C:\temp3
  6. Click OK and specify a label of servercertificate.

Set up the web services provider

To configure the web services provider, do the following:

  1. Launch SoapUI and create a new workspace called SampleProvider.
  2. Right-click SampleProvider and select New soapUI Project. Download Order.wsdl from the Downloads section and save it to a local directory, such as C:\DevW.
  3. Enter the following information in the New SoapUI Project wizard, as shown in Figure 3:
    • Project Name: OrderProject
    • Initial WSLD/WADL: C:\DevW\Order.wsdl
    • Check Create sample requests for all operations and Create a Web Services Simulation of the imported WSDL, and click OK.
    Figure 3. Create new project
    Create new project
  4. On the Generate MockService dialog, shown in Figure 4, specify the following:
    • Select <create> for MockService.
    • Check Order.
    • Specify /mockPurchaseOrderBinding for the Path.
    • Specify 8088 for the Port.
    • Check Adds the MockServices endpoint to the mocked Interface, then click OK.
    Figure 4. Generate a mock service
    Generate a mock service
  5. Click OK and specify PurchaseOrderBinding MockService as the name for the mock service.
  6. Select SampleProvider => OrderProject => PurchaseOrderBinding MockService > Order > Response1.
  7. Double-click Response1 to open the SOAP Response window and enter the following code, as shown in Figure 5:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:exam="http://example.org">
       <soapenv:Header/>
       <soapenv:Body>
          <exam:OrderConfirmationType>
             <!--Optional:-->
             <exam:orderID>4321</exam:orderID>
             <!--Optional:-->
             <exam:expectedShipDate>25-Oct-2013</exam:expectedShipDate>
          </exam:OrderConfirmationType>
       </soapenv:Body>
    </soapenv:Envelope>
    Figure 5. SOAP response
    SOAP response
  8. Close the SOAP response window.

Configure Transport Layer Security in IBM BPM and in the web services provider

In this section we'll perform steps required to enable SSL (HTTPS) between IBM and the web services provider.

  1. Log in to the WebSphere Integrated Solutions Console.
  2. Select Security => SSL certificate and key management.
  3. Select Key stores and certificates.
  4. Click New to define a new keystore. This keystore will use the clientkeystore.jks that you created earlier using ikeyman.
  5. Enter the following information shown in Figure 6, and click OK:
    • Name: ClientKeyStore
    • Description: An optional description.
    • Management scope: Select the management scope appropriate for your environment. If you are using a standalone profile environment for IBM BPM, select the Node scope. If you are using a Deployment Manager environment, select the Cell scope. In Figure 6, the Node scope corresponding to a standalone profile is selected.
    • Path: The path where the keystore is located.
    • Password:WebAS (this must be the same password you provided earlier while defining the keystore in ikeyman).
    • Type: JKS
    Figure 6. Create the WebSphere Application Server keystore
    Define the WebSphere Application Server keystore
  6. Click OK and save to the master configuration.
  7. Select Security => SSL certificate and key management, then select SSL Configurations.
  8. Click New to create a new SSL configuration and enter the following information, as shown in Figure 7:
    • Name: BPMWSLLConfig
    • Trust store name: Select ClientKeyStore, which you configured in step 5.
    • Keystore name: Select ClientKeyStore.
    • Default server certificate alias: clientcertificate
    • Default client certificate alias: clientcertificate
    • Management scope: Select the management scope appropriate for your environment. If you are using a using a standalone profile environment for IBM BPM, select the Node scope. If you are using a Deployment Manager environment, select the Cell scope. In Figure 7 the Node scope corresponding to a standalone profile is chosen.
    Figure 7. Configure WebSphere Application Server SSL
    Configure WebSphere Application Server SSL
  9. Click OK and save to the master configuration.
  10. As a last step on the BPM side to make SSL work, you need to create a dynamic outbound SSL configuration. To do this, select Security => SSL certificate and key management and select Dynamic outbound endpoint SSL configuration, then click New to create a new configuration entry. Specify the following information, as shown in Figure 8:
    • Name: bmpsweboutbound
    • Management scope: Select the management scope appropriate for your environment. If you are using a using a standalone profile environment for IBM BPM, select the Node scope. If you are using a Deployment Manager environment, select the Cell scope. In Figure 8, the Node scope corresponding to a standalone profile is chosen.
    • Description: A required description.
    • Connection information: Click Add and select the appropriate SSL configuration and certificate aliases are selected. In this case, *,*,8044 is a rule that uses the specified SSL configuration and certificate alias. This rule specifies that, whenever there is an outbound connection using any supported protocol to any host on port 8444, the specified SSL configuration (and its keystore and truststore) and the certificate alias (to identify the client to the server) are used. More details about dynamic SSL configuration are available in Associating a Secure Sockets Layer configuration dynamically with an outbound protocol and remote secure endpoint.
    • SSL configuration: BPMWSSLLConfig
    • Certificate alias: clientcertificate
    Figure 8. Dynamic SSL Configuration
    Dynamic SSL Configuration
  11. Click OK and save to the master configuration.
  12. Restart IBM BPM.
  13. Now we'll switch to web services provider to enable communication using SSL. On SOAP UI, select File => Preferences => SSL Settings.
  14. Specify the following information, as shown in :
    • KeyStore: Provide the full path to the serverkeystore.jks file. This is the keystore file you created in Set up the keystores to support secure interaction section. This keystore is used mainly for outbound SSL requests.
    • KeyStore Password: WebAS
    • Check Enable Mock SSL.
    • Mock Port: 8044
    • Mock KeyStore: Provide the full path to the serverkeystore.jks file. You created this keystore file in Set up the keystores to support secure interaction. For the purposes of this article, we'll use the same file for configuring the keystore and the truststore for the mock service.
    • Mock Password: WebAS
    • Mock Key Password: WebAS
    • Mock TrustStore: Provide the full path to serverkeystore.jks. This is the same value you specified for Mock KeyStore.
    • Mock TrustStore Password: WebAS
    • Check Client Authentication.
    Figure 9. Configure the web services provider SSL
    Configure the web services provider SSL
    We have used WebASas the keystore and truststore password
  15. Click OK. Now the web services provider can accept SSL requests on port 8444.
  16. Select SampleProvider => OrderProject => PurchaseOrderBinding MockService and open the mock service.
  17. Right-click PurchaseOrderBinding MockService and select Restart.

Create an IBM BPM sample and invoke the web services provider securely using SSL

  1. Log into Process Designer and create a sample process application or use an existing application if you prefer.
  2. Open the process application and create a new integration service and name it Web Service Tester.
  3. Go to the Web Service Tester service and add a web Service Integration into the open canvas as shown in Figure 10. Wire the start and end links to this component.
    Figure 10. Create the web service caller in BPM
    Create the web service caller in BPM
  4. Go to the Properties tab of Call Web Services, and under Implementation => Discovery, enter the following for the WSDL URI http://<hostname where SOAP UI is running>:8088/mockPurchaseOrderBinding?wsdl.
  5. Click View and verify that the WSDL file can be accessed.
  6. Click Discover to make the connection to the WSDL file and fetch the operation and service details as shown in Figure 11.
    Figure 11. Configure the caller
    Configure the caller
  7. Verify that the endpoint address URL uses port 8044. This is the port that we had configured for SSL in the web services provider. This port also matches the port configured in our dynamic outbound SSL configuration. The WebSphere runtime will therefore use the keystore and truststore associated with this SSL configuration.
  8. On the Properties tab, in the Input Mapping section of Data Mapping update the following values as shown in Figure 12:
    • 5 for quantity
    • "Chairs" for productName
    Figure 12. Specify Input data
    Input Data
  9. Also in the Input Mapping section, click Auto-map to bring up the wizard to map the web service connector input parameters. Select the displayed items to complete the response mapping.
  10. Now you're ready to test the web service using SSL. Run the service in the debug mode by clicking Debug Service in the top right corner of the service diagram.
  11. Click Step to go to the next step and verify that the web service response set in SOAP UI was received, as shown in Figure 13.
    Figure 13. Verify output data
    Verify output data
  12. Click Run to complete the service execution.
  13. Web services requests and responses are also logged in the web services provider. You can find the details in the mock services message log as shown in Figure 14.
    Figure 14. Incoming SOAP message using SSL
    Incoming SOAP message using SSL

Configure IBM BPM to support message-level security for web services interaction

  1. Open the 100Custom.xml file corresponding to your BPM profile.
  2. Add the code shown in Listing 1 to the 100Custom.xml file and restart IBM BPM server.
Listing 1. Configure 100Custom.xml for message-level security
 <server>    	    	
    <webservice-security merge="mergeChildren"> 
	 <keystore-file merge="replace">C:\temp3\ClientKeyStore.jks</keystore-file> 
	 <keystore-password-encrypted merge="replace"><![CDATA[Bq/GXLNbHz/aMv1FPkGeCQ==:
	 To5WJ7gVecQ+Vx9TtE2K8A==]]>
	 </keystore-password-encrypted> 
	 <private-key> 
	     <alias>clientcertificate</alias> 
	     <keyname>clientcertificate</keyname>
	     <password-encrypted><![CDATA[Bq/GXLNbHz/aMv1FPkGeCQ==:
	     To5WJ7gVecQ+Vx9TtE2K8A==]]>
	     </password-encrypted>
	 </private-key>
	 <private-key> 
	 	     <alias>servercertificate</alias> 
	 	     <keyname>servercertificate</keyname>
	 </private-key>
	 <keystore-type>JKS</keystore-type>
	 <certificate>C:\temp3\clientcertificate.arm</certificate>
    </webservice-security> 
  </server>

In , you'll see the elements shown in Table 1.

Table 1. Message-level security elements
ElementExplanation
keystore-file The keystore file you created earlier for SSL configuration.
keystore-password-encrypted The encrypted password corresponding to the keystore. To encrypt the password, you can use java -cp utility.jar com.lombardisoftware.utility.EncryptPassword <password>
alias (under the first private-key element) This corresponds to the alias of the personal certificate in the keystore. The private key associated with this certificate is used to digitally sign the request and decrypt the SOAP response message.
keyname (under the first private-key element) Same as the alias.
password-encrypted (under the first private-key element) Same as keystore-password-encrypted.
alias (under the second private-key element) This corresponds to the alias of the signer certificate in the keystore. The public key associated with this certificate is used to encrypt the SOAP request and to verify the signature in the SOAP response message.
keyname (under the second private-key element) Same as the alias.
keystore-type JKS (we're using JKS keystore).
certificate Path to the certificate file of the web services requester. This is required to secure outbound communication.

Configure the web services provider to support message-level security and test the scenarios

We'll test the following two scenarios:

  • Scenario 1: IBM BPM sends a signed request and receives an encrypted response from the web services provider.
  • Scenario 2: IBM BPM sends an encrypted request and receives a signed response from the web services provider.

It's possible to test several other scenarios and combinations involving message encryption and signature. However, be aware that you will not be able to simultaneously apply message encryption and signature to the response message because you may run into the issue mentioned here.

Also note that presently it's not possible to encrypt request message parts or accept responses with encrypted message parts. Encryption must be applied to SOAP Body.

Test Scenario 1

  1. Switch to the workspace on SOAP UI.
  2. Double-click OrderProject to open the configuration dialog for the project.
  3. In the Keystores tab of WS-Security Configurations, create a new entry for serverkeystore.jks as shown in Figure 15.
    Figure 15. Server Keystore
    Server Keystore
  4. In the Incoming WS-Security Configuration tab, create a new entry for serverkeystore.jks as shown in Figure 16. Use the password associated with the keystore, such as WebAS.
    Figure 16. Incoming WS Security configuration
    Incoming WSS
  5. In the Outgoing WS-Security Configuration tab, add a new entry for response encryption. First add a new outgoing WSS Configuration with a unique name of client , then add a new WSS Entry for Encyrption. Then specify the following, as shown in Figure 17:
    • Keystore: serverkeystore.jks
    Figure 17. Outgoing WS Security Encryption
    Outgoing WSS Enc
  6. Select Ctrl+S to save the configuration update.
  7. Select SampleProvider => OrderProject => PurchaseOrderBinding MockService and in the MockService Properties section on the bottom left, set Incoming WSS to server as shown in Figure 18
    Figure 18. Configure SOAP Response
    Config Response
  8. Click Ctrl+S to save the configuration update.
  9. Restart the mock service.
  10. Restart Process Designer and open the service you created earlier while testing the SSL configuration.
  11. Go to the Security tab and update the following properties, as shown in Figure 19:
    • Select None for Authentication.
    • Specify clientcertificate for Client certificate alias and check Sign request and Expect encrypted response.
    • Specify servercertificate: serviceprovider.com for Server certificate alias.
    Note: Make sure you clear any existing values for certificate aliases.
    Figure 19. Configure SOAP security for test scenario 1
    Configure SOAP security for test scenario 1
  12. Save the update to the service.
  13. Run the service in the debug mode and verify that the same response is received from the web service provider.
  14. If you received a java.net.ConnectException, restart the mock service again.
  15. Go to the web services provider and under the Message Log, you should see an entry corresponding to the completed web services request, as shown in Figure 20.
    Figure 20. SOAP request message in Scenario 1
    SOAP request message in Scenario 1
  16. Double-click the entry to open the Message Viewer.
  17. Inspect the request and response messages under their respective Raw sections. In the tequest message, you should see a ds:Signature element inside the SOAP Header element. In the response message, you should see an xenc:EncryptedData element inside the SOAP Body element.

Test Scenario 2

  1. Open the WS-Security Configuration tab associated with the mock-service project in SOAP UI.
  2. On the Outgoing WS-Security tab, enter the properties as described below, but first remove the entry for Encryption and add an entry for Signature as shown in Figure 21.
    • Keystore: serverkeystore.jks
    • Alias: servercertificate
    • Password: WebAS
    • Key Identifier Type: Binary Security Token
    • Signature Algorithm, Signature Canonicalization, and Digest Algorithm: <default>
    • Check Use single certificate for signing.
    Figure 21. Outgoing WS-Security signature in Scenario 2
    Outgoing WS-Security signature in Scenario 2
  3. Click Ctrl+S to save the configuration update.
  4. Restart the mock service.
  5. Restart Process Designer and open the service created earlier while testing SSL configuration.
  6. Go to the Security tab and update the properties as as follows, as shown in Figure 22:
    • Select None for Authentication.
    • Specify clientcertificate for Client certificate alias.
    • Specify servercertificate: serviceprovider.com for Server certificate alias, and and check Encrypt request and Expect signed response
    Note: Make sure you clear any existing values for certificate aliases.
    Figure 22. Configure SOAP security for Scenario 2
    Configure SOAP security for Security 2
  7. Save the update to the service.
  8. Run the service in the debug mode and verify that the same response is received from the web service provider.
  9. If you received a java.net.ConnectException, restart the mock service.
  10. Go to the web services provider and under Message Log you should see an entry corresponding to the completed web services request, as shown in .
    Figure 23. SOAP Request Message Scenario 1
    SOAP Message 2
  11. Inspect the Request and Response messages under their respective Raw sections. In the Request message, you should see an enc:EncryptedDataelement element inside SOAP Body. In the Response message, you should see a ds:Signature element inside the SOAP Header.

Conclusion

In this article, you learned how you can configure IBM BPM in order to enable WS-Security and Transport Layer Security when interacting with secure web services using the web services integration component. Using a tool such as SOAP UI, you can easily verify the configuration independent of the availability of an actual web-service provider.


Acknowledgements

The author would like to thank Raj Chaudhary for his thorough review of this article.

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 Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere, Mobile development
ArticleID=946127
ArticleTitle=Enable WS-Security and Transport Layer Security in IBM Business Process Manager Standard
publish-date=08282013