Introduction

An increasingly popular ESB processing pattern combines the strengths of WebSphere Message Broker and the WebSphere DataPower XML Security Gateway XS40 appliance, with the DataPower appliance serving as a security gateway to WebSphere Message Broker. This pattern is especially valuable when processing messages over HTTP. DataPower has a well-established reputation for its security capabilities and brings significant value to this processing pattern.

For a DataPower appliance to perform WS-Security processing, you must first create a firewall within it, which requires administration and information from both the Message Broker message flow and the DataPower appliance. You can perform this administration manually on the DataPower appliance, or you can use the new DataPower security wizard, recently added to the WebSphere Message Broker Explorer. This article shows you how to use the DataPower security wizard within the Broker Explorer to configure your DataPower appliance to perform the WS-Security required for message flows containing HTTPS Input Nodes.

This article shows how to use the wizard with a use case in which SOAP messages are received over HTTP and processed by a message flow. The body of the SOAP message has been secured using WS-Security processing and therefore must be decrypted before it can be processed within the message flow. A DataPower appliance is used as a front-end security gateway to decrypt the body of the SOAP message on the way into the message flow. The DataPower appliance is also used to encrypt the output message from the message flow before the reply is sent to the requesting application. Here is the processing sequence:

The message flow, messages, and MQ application used in this case are those of the Web Service Host (WSHOST) application, which is shipped as a sample with WebSphere Message Broker V6. To access it from within the Message Broker toolkit, select Help => Samples Gallery.

For valuable background information on the integration of DataPower and Message Broker, and on the processing taking place in this use case, see Integrating DataPower with WebSphere Message Broker.

In order to have the DataPower appliance perform the security functions outlined above, you need to do the following tasks, which are described in detail below:

1. Perform initial DataPower configuration to perform such tasks as creating a user ID and ensuring that the SSL crypto certificates are in place.
2. Invoke the DataPower Security wizard within Message Broker on the selected message flows and:
1. Specify the selected WS-Security policy sets.
2. Define the DataPower appliance connection parameters.
3. Define the DataPower firewall and DataPower policy.
4. Perform final security processing.

DataPower SOA appliance initial configuration

Configuration starts with engaging the DataPower administrator to:

1. Provide a user ID, password, and domain configured on the DataPower appliance.
2. Ensure that the SSL crypto certificates and validation credentials are available to your domain if you are using SSL to communicate to the Broker or to a client. You will need to know the names of these later on in the configuration.
3. Ensure that the required crypto certificate is available on the DataPower appliance in your domain if you want to use the DataPower appliance to encrypt or decrypt data.

Invoking and customizing the Security wizard

You can run the DataPower Security wizard only against message flows that are already deployed to a Broker. To invoke the security wizard in Message Broker, right-click either an execution group or a specific message flow in the Brokers tree within the Broker explorer, and select DataPower => Security wizard. Figure 2 below shows the wizard being invoked for a message flow running in a broker called FRESH. The broker used for this article has four execution groups: default, newSSlPort, WSHOST and WSHOST_SSL. This article looks at the configuration of the WSHOST message in the WSHOST execution group. Figure 2 shows the DataPower Security wizard being invoked at the execution group level:

If you cannot see this menu option, select Windows => Preferences => Broker Explorer => DataPower and make sure that the Display DataPower menu box is checked in the Broker Explorer.

After invoking the Security wizard, a background task within the wizard interrogates the message flows within the selected execution group and retrieves details about all HTTPS Input Nodes available in these message flows. You will then be presented with the main DataPower Security wizard screen:

The information on this screen is split into three areas:

Flow Details

Shows information retrieved by the wizard for the selected message flows. The information shown is a list of HTTPS node names, the hostname on which they are configured, the URL which they service, the port on which the listener is configured, and whether the node supports SSL. In this example a single HTTP input node named HTTP_Input is available in the Execution Group WSHOST, with the other parameters shown in Figure 3.

WS-Security

Shows which policy set binding and policy set are to be used. A default policy set and policy set binding are created when the wizard is first used with the name conforming to the template WSS10Default-{BrokerName}_n. The name structure is set and cannot be changed. As the broker in this example is called FRESH, the policy set binding name is WSS10Default-FRESH_1. You can edit the policy sets if needed.

DataPower Details

Shows information needed to use the DataPower appliance, including user ID, domain, and XML firewall name. When the wizard is first invoked, you are prompted to supply the user ID and domain that you will be using on the DataPower appliance to perform the security processing. In this example, the user details have already been created: the user name is dstorey, the DataPower appliance domain is crockerp, and the DataPower appliance name is mqx50.hursley.ibm.com.

The next step is to complete the wizard, as described below.

Selecting the required message flows

The wizard will populate the Flow Details section with a list of HTTP and HTTPS input nodes that have been found in the selected execution groups or message flows. To select the message flows for which you want to specify security processing, click on the appropriate entries in the table. You can have a mixture of HTTP and HTTPS Input Nodes in a message flow. The type of input node will determine which type of policy and firewall it will be assigned to.

Specifying WS-Security policy sets

After you have selected the HTTPS Input nodes on which you want the DataPower appliance to perform security processing, you need to specify whether you want a WS-Security policy and if so what it is:

• If you do not want to apply WS-Security, select None in the wizard to create a pass-through scenario, which can be useful to make sure that all of your communication channels are working before adding the encryption/decryption rules at a later stage.
• If you do want to apply WS-Security, you must create a policy set. A default policy set and policy set binding pairing are created for you when you first run the wizard, as shown in Figure 4 below. Each broker has its own store of policy sets available to it via the tooling.

You can alter the default policy set and policy set binding pairs or add your own. Each policy set binding has an associated policy set. The important part for encryption and decryption is the key information table specified within the policy set bindings.

The outbound key defines the encryption rules, while the inbound key defines the decryption rules. The Token Generator column points to the message level protection token, which specifies additional WS-Security parameters. After you have created your policy set and binding, click Finish to return to the Security wizard.

The policy sets and bindings are stored in the Broker Explorer for the DataPower wizard and can be backed up by taking a copy of the Model file stored in your run-time workspace at \.metadata\.plugins\com.ibm.etools.wmadmin.broker.explorer\MB_EMFModel.xmi.

Defining DataPower details

DataPower details include the connection parameters to be used to connect to the DataPower appliance, and the XML firewall to use.

Defining DataPower connection parameters

To define the connection parameters in Message Broker, click Edit Profiles on the main DataPower Security wizard page to open the wizard shown below in Figure 5. Each profile contains a valid username, domain, hostname, management URL, and management port on the DataPower appliance, which lets you store your connection information between sessions so you do not need to reenter this information.

You can add, delete, import, and export sets of connection details. Select Add to add a new row and then click on the cells in the row to change the values to your connection values. Click Finish to save the profile within the Broker Explorer tooling. It will appear in a drop-down list in the Security wizard in future sessions.

Defining the DataPower firewall and DataPower policy

You are now ready to define your DataPower firewall and DataPower policy. The DataPower policy associated with the DataPower firewall initially has the same name as the DataPower firewall, but you can change it. In this case, the broker is called FRESH and so is the XML firewall:

Client ports are initially set using the ports from the Broker run-time listeners, which you can set to whatever port your client wants to use to connect to the DataPower appliance. A separate DataPower firewall, DataPower policy, and client port are needed for SSL and non-SSL Message Broker HTTP nodes, which lets you set up a client connection for both HTTP and HTTPS Input nodes within your message flows.

Recommendation: Select Create new policies when initially setting up this configuration, to overwrite the DataPower firewall and DataPower policy. Select Merge Policies only when you want to add new rules to an existing DataPower policy and DataPower firewall. This option only adds new rules for your HTTPS Input Nodes, and does not overwrite any existing rules in your DataPower policy.

Up to this point, you have made no alterations to your DataPower SOA appliance. The next step is to send that configuration information to the DataPower appliance.

Final security step

When you complete the definition of the DataPower firewall and DataPower policy configuration above, you are returned to the main panel of the DataPower Security wizard:

At this point you can select wither Next or Finish. Select Next if you want to specify the actual certificates for the DataPower appliance. Select Finish to send the configuration information to the DataPower appliance to have it perform the configuration. The processing associated with both of these options is described below.

Specifying the certificates

If you select Next on the DataPower Security wizard main page, you will see this screen:

Using your DataPower connection parameters and password, the DataPower security wizard obtains a list of crypto certificates from your domain on your DataPower appliance, as shown in Figure 8:

• The SSL Front End Client setting value is used to configure the SSL profile, which client application programs use to connect to the DataPower appliance.
• The Back End Broker SSL setting is used to configure your back-end connection for communication from the DataPower appliance to Message Broker. This option is available only if you are using SSL between the broker and the DataPower appliance, which we are not in this case.
• The Decryption and Encryption drop-down boxes are used to configure the decryption and encryption keys in your request and reply rules respectively. Select the required keys for decryption and encryption of the message. In this case, AliceKey is used to decrypt the SOAP message received by the DataPower appliance. and BobKey is used to encrypt the reply message to the requesting application. These are the names of crypto profiles that have been defined on the DataPower appliance.

Sending the configuration information to the DataPower SOA appliance

After you click Finish in the screen in Figure 7 or Figure 8, the following things are created:

• DataPower XML firewalls -- one for HTTPInput Nodes per broker and one for HTTPS Input Nodes per broker
• A DataPower policy for each DataPower XML firewall
• A series of reply and request rules for each HTTPS Input Node that you selected

If you have a WS-Security policy set binding selected:

• Each request rule will have a matching action matching the HTTPS Input Node selector and a decryption rule.
• Each reply rule will have a matching action matching the HTTPS Input Node selector and an encryption rule.

The created DataPower policy

After the configuration information has been sent to the DataPower appliance, rule pairings are created, as shown in Figures 9 and 10:

The DataPower firewall is automatically created with a suppression header to remove the additional connection header, which is not tolerated by Message Broker. For details, see Integrating DataPower with WebSphere Message Broker.

Using the configuration

Configuration of the DataPower appliance is now complete, and you can now send your messages to the DataPower client port using a tool that will let you put HTTP messages. A few tips:

• Any messages sent to the DataPower appliance in this example must be sent to port 7080, the port associated with the firewall.
• The input node of the message flow that receives the message is an HTTPInput node, so messages must be in clear text and not encrypted.
• If you configure a node with an HTTPSInput node, then the input message must be encrypted, and the requesting application needs to do this encryption independently of the wizard.
• To diagnose problems, use the service trace facility in the Broker Explorer and the logs in your DataPower appliance.

Conclusion

This article showed you how to use the new WebSphere Message Broker DataPower security wizard, which is provided as part of Broker Explorer V3, to configure a DataPower SOA appliance so that you can use it to decrypt messages on which WS-Security processing has been applied.

Although the Message Broker DataPower security wizard does not eliminate all interactions with the DataPower appliance, it does simplify administration from within Message Broker. It shows you in detail how to make the DataPower appliance operate as a security gateway for Message Broker message flows. The wizard helps eliminate typos, as the Wizard communicates with both the Message Broker runtime and the DataPower appliance, directly retrieving information such as details about the HTTPInput and HTTPSInput nodes in a message flow, and details of certificates held in the DataPower appliance.

The wizard is focused on one particular use case, in which the DataPower SOA appliance performs WS-Security processing on behalf of a WebSphere Message Broker message flow using an XML firewall. You can use this configuration as the basis for more complex processing if you have more advanced administration skills.

In summary, this wizard gives you a simple and effective way to combine the power of a DataPower SOA Appliance and WebSphere Message Broker for WS-Security processing.

Resources

• 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.
  
  
• WebSphere Message Broker information center
  A single Eclipse-based Web portal to all WebSphere Message Broker V6 documentation, with conceptual, task, and reference information on installing, configuring, and using your WebSphere Message Broker environment.
  
  
• WebSphere Message Broker documentation library
  WebSphere Message Broker specifications and manuals.
  
  
• WebSphere Message Broker forum
  Get answers to your 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, problem tracking, and more.
  
  
• developerWorks WebSphere Business Integration zone
  For developers, access to WebSphere Business Integration how-to articles, downloads, tutorials, education, product info, and more.
  
  
• WebSphere Business Integration products page
  For both business and technical users, a handy overview of all WebSphere Business Integration products
  
  
• WebSphere forums
  Product-specific forums where you can get answers to your technical questions and share your expertise with other WebSphere users.
  
  
• Most popular WebSphere trial downloads
  No-charge trial downloads for key WebSphere products.
  
  
• Trial downloads for IBM software products
  No-charge trial downloads for selected IBM® DB2®, Lotus®, Rational®, Tivoli®, and WebSphere® products.
  
  
• Technical books from IBM Press
  Convenient online ordering through Barnes & Noble.
  
  
• developerWorks technical events and Webcasts
  Free technical sessions by IBM experts that can accelerate your learning curve and help you succeed in your most difficult software projects. Sessions range from one-hour Webcasts to half-day and full-day live sessions in cities worldwide.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• DataPower SOA appliance initial configuration
• Invoking and customizing the Security wizard
• Final security step
• The created DataPower policy
• Using the configuration
• Conclusion
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Message Broker
• Webcast: WebSphere Message Broker: Converting Maps to ESQL using Support Pac IA9Y
• Briefing: WebSphere flexible business processes for a smarter planet
• Buy: WebSphere Message Broker

My developerWorks community

Dig deeper into WebSphere on developerWorks

DB2 pureScale

See how true transparent scaling architecture can be achieved on distributed platforms

Special offers