Você está na página 1de 160

Discovering the value of IBM WebSphere

DataPower SOA Appliances


Firmware version 5.0
Lab Exercises

An IBM Proof of Technology


PoT.WebSphere.08.4.060.12

Authors:
Gerry Kaplan, WebSphere DataPower SME
Ray Wilson, WebSphere DataPower SME
Contributors:
Charlie Sumner, WebSphere Transformation Extender SME
Sudhir Mohith, ISSW Partner Services Practice
Lou Rivas, WebSphere IT Specialist
Applicable Firmware: 5.0.0.0 and greater

Copyright IBM Corporation, 2013


US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

IBM Software

Contents
LAB 1

INTRODUCTION TO WEBSPHERE DATAPOWER SOA APPLIANCES ......................................................... 7


1.1
WEBSPHERE DATAPOWER SOA APPLIANCES FAMILY ................................................................................ 7
1.2
ACCESS CONTROL ................................................................................................................................... 8
1.3
APPLICATION DOMAINS ............................................................................................................................ 8
1.4
THE WEBSPHERE DATAPOWER WEBGUI .................................................................................................. 8
1.5
CONFIGURATION PROCEDURES ............................................................................................................... 12
1.6
WEBSPHERE DATAPOWER SERVICES ..................................................................................................... 12
1.7
WEBSPHERE DATAPOWER FLASH-BASED FILE SYSTEM ............................................................................ 16
1.8
TROUBLESHOOTING TOOLS..................................................................................................................... 20
1.9
LOGGING .............................................................................................................................................. 21
1.10
WEBSPHERE DATAPOWER SOA APPLIANCES FIRMWARE ......................................................................... 28
1.11
SUMMARY ............................................................................................................................................. 28

LAB 2

WORKING WITH XML ...................................................................................................................................... 29


2.1
SERVICE PROCESSING PHASES............................................................................................................... 29
2.2
CREATING THE MULTI-PROTOCOL GATEWAY SERVICE ............................................................................... 31
2.3
SCHEMA VALIDATION ............................................................................................................................. 39
2.4
SOAP ENVELOPE SCHEMA VALIDATION .................................................................................................. 43
2.5
CONTENT-BASED FILTERING ................................................................................................................... 44
2.6
TRANSFORMING WITH XSL AND XPATH.................................................................................................... 47
2.7
STYLESHEET CACHING ........................................................................................................................... 50
2.8
IMPLICIT XML THREAT PROTECTION ........................................................................................................ 50
2.9
SUMMARY ............................................................................................................................................. 53

LAB 3

SECURING XML MESSAGE CONTENT USING WS-SECURITY ................................................................... 55


3.1
PUBLIC KEY INFRASTRUCTURE (PKI) ....................................................................................................... 55
3.2
WS-SECURITY DIGITAL SIGNATURES ....................................................................................................... 56
3.3
WS-SECURITY ENCRYPTION & DECRYPTION ............................................................................................ 66
3.4
SUMMARY ............................................................................................................................................. 70

LAB 4

ACCESS CONTROL FRAMEWORK ............................................................................................................... 71


4.1
LDAP AUTHENTICATION ......................................................................................................................... 72
4.2
SUMMARY ............................................................................................................................................. 74

LAB 5

SECURING WITH SSL (OPTIONAL LAB) ....................................................................................................... 75


5.2
SUMMARY ............................................................................................................................................. 80

LAB 6

PROTECTING WEB SERVICES ...................................................................................................................... 81


6.1
WEB SERVICES AND WSDLS .................................................................................................................. 81
6.2
ABOUT THE WEB SERVICE ...................................................................................................................... 82
6.3
VERIFY THE SERVICE IS AVAILABLE.......................................................................................................... 82
6.4
DEFINING THE WEBSPHERE SERVICE REGISTRY AND REPOSITORY SERVER ................................................ 84
6.5
CREATING THE WEB SERVICE PROXY ...................................................................................................... 85
6.6
WS-SECURITYPOLICY ........................................................................................................................... 89
6.7
SERVICE LEVEL MONITORING (SLM) ....................................................................................................... 95
6.8
SUMMARY ............................................................................................................................................. 98

LAB 7

AUTHORIZATION WITH XACML (OPTIONAL LAB) ...................................................................................... 99


7.1
THE XACML POLICY DOCUMENT .......................................................................................................... 100
7.2
THE XACML AUTHORIZATION REQUEST DOCUMENT .............................................................................. 101
7.3
XACML AND WEBSPHERE DATAPOWER ............................................................................................... 102
7.4
HOW ITS DONE.................................................................................................................................... 103
7.5
SUMMARY ........................................................................................................................................... 107

LAB 8

FEDERATION USING SAML (OPTIONAL LAB) ........................................................................................... 109


8.2
SUMMARY ........................................................................................................................................... 116

LAB 9

REST AND JSON (OPTIONAL LAB) ............................................................................................................. 117


9.1
REST OVERVIEW ................................................................................................................................ 117
9.2
EXPOSING REST WITH DATAPOWER ..................................................................................................... 119
9.3
THE PROJECTSERVICE EXAMPLE ........................................................................................................... 120
9.4
VERIFY SERVICE AVAILABILITY ............................................................................................................... 120
9.5
REST MULTI-PROTOCOL GATEWAY ...................................................................................................... 121
9.6
CONCLUSION....................................................................................................................................... 138

Contents

Page 3

IBM Software

LAB 10

MIDDLEWARE AND MAINFRAME INTEGRATION (OPTIONAL LAB) ........................................................ 139


10.1
PROTOCOL BRIDGING: HTTP TO WEBSPHERE MQ ................................................................................ 139
10.2
POT LAB ENVIRONMENT ....................................................................................................................... 140
10.3
CONNECTING TO AN MQ QUEUE MANAGER ............................................................................................ 140
10.4
TRANSFORMING NON-XML PAYLOADS .................................................................................................. 142
10.5
EXECUTING THE MAP ON WEBSPHERE DATAPOWER ............................................................................... 145
10.6
SUMMARY ........................................................................................................................................... 147

APPENDIX A.

COMMON DEPLOYMENT SCENARIOS ....................................................................................................... 149

APPENDIX B.

THE (XML) THREAT IS OUT THERE ......................................................................................................... 151

APPENDIX C.

NOTICES ........................................................................................................................................................ 154

APPENDIX D.

TRADEMARKS AND COPYRIGHTS ............................................................................................................. 156

Page 4

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Overview
This IBM WebSphere DataPower SOA Appliances Proof of Technology (PoT) provides a hands-on
experience for those needing to understand how WebSphere DataPower SOA Appliances can help ease
and accelerate the deployment of enterprise Service Oriented Architecture (SOA) implementations.
Participants gain an appreciation for the ability of WebSphere DataPower to meet the demand for fast,
secure, and reliable XML processing by creating various configurations that demonstrate a rich array of
built-in functionality.

Introduction
IBM WebSphere DataPower SOA Appliances represent an important element in IBM's holistic approach
to Service Oriented Architecture (SOA). IBM 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. These new appliances offer an innovative, pragmatic approach to
harness the power of SOA while simultaneously enabling you to leverage the value of your existing
application, security, and networking infrastructure investments.

Requirements
To complete the labs in this workbook, youll need the following:
A network attached workstation with sufficient memory (2GB minimum).
VMware Workstation or Viewer to run the supplied student VMware image.
An Internet browser.
Access to a WebSphere DataPower Integration Appliance (Physical or Hypervisor) with

Firmware 5.0.0 or greater (XI50, XI52, XI50B, XI50Z).

Overview

Page 5

IBM Software

Icons
The following symbols appear in this document at places where additional guidance is available.
Icon

Page 6

Purpose

Explanation

Important!

This symbol calls attention to a particular step or command.


For example, it might alert you to type a command carefully
because it is case sensitive.

Information

This symbol indicates information that might not be


necessary to complete a step, but is helpful or good to know.

Troubleshooting

This symbol indicates that you can fix a specific problem by


completing the associated troubleshooting information.

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 1

Introduction to WebSphere DataPower SOA Appliances

In this lab, youll gain a high level understanding of the architecture, features, and development concepts
related to the family of WebSphere DataPower SOA Appliances. Throughout the lab, youll get a chance
to use the WebSphere DataPower intuitive Web-based user interface (WebGUI) to explore the various
aspects associated with appliance configuration and operation.
Upon completing this lab, youll have a better understanding of:
The WebSphere DataPower SOA Appliances family.
Access Control.
Application Domains.
WebSphere DataPower Web-based User Interface (WebGUI).
Configuration Procedures.
The various WebSphere DataPower services.
Local file management.
Logging capabilities.
Device management options.
Firmware management.

1.1

WebSphere DataPower SOA Appliances Family

WebSphere DataPower SOA Appliances are a key element in IBM's holistic approach to Service
Oriented Architecture (SOA). These appliances are purpose-built, easy-to-deploy network devices to
simplify, help secure, and accelerate your XML and Web services deployments.
The DataPower appliance family includes the following:
WebSphere DataPower XML Security Gateway XG45 - Capable of offloading overtaxed

Web and application servers by processing XML, XSD, XPath and XSLT at wirespeed,
this appliance enables faster results from application investments. It also delivers a
comprehensive set of configurable security and policy enforcement functions including
support for the latest WS-* standards.
WebSphere DataPower Integration Appliances XI52, XI50B and XI50Z - IBM's hardware

Integration Gateway, this appliance is built for simplified deployment & hardened security.
It includes all of the XML and security functionality found in the DataPower XML Security
Gateway appliance and adds capabilities for bridging multiple protocols.
WebSphere DataPower B2B Appliance XB62 Extends all of the capabilities of the

DataPower Integration Appliance with B2B capabilities by providing AS1/AS2/AS3


messaging & trading partner profile management in a high-performance DMZ-ready
appliance.
WebSphere Hypervisor Edition Appliances XG45 and XI52 Provides the same

integration capabilities as the physical version but lacks the hardware acceleration.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 7

IBM Software

WebSphere DataPower Caching Appliance XC10 This adds elastic caching functionality

that will enable your business-critical applications to scale cost effectively with consistent
performance.

1.2

Access Control

There are three administrative interfaces for configuring WebSphere DataPower SOA Appliances:
Command line interface
Web-based graphical interface
SOAP-based XML management interface

Through the various administrative interfaces, it is possible to access the entire range of configuration
and status data. Access to the various administrative interfaces is tightly controlled through a variety of
access control methods.
Access control list. Only hosts with addresses in a listed range can access the

appliance.
Accounts, groups, and access policies. Local accounts can be created to gain access

to the appliance. Groups facilitate an easy way of managing multiple accounts with similar
access rights. Group access rights are defined using an access policy.
Role-based Management. Extends local access control to use remote authentication and

authorization servers, such as LDAP or RADIUS.

1.3

Application Domains

Application domains allow administrators to partition an appliance into multiple logical configurations. For
example, in a production environment, a domain may represent a business area like shipping or
accounting. In a development environment, each developer may have their own domain for testing.
Configurations that are created in one domain are secure from other domains and are not visible.
By default, a newly initialized WebSphere DataPower appliance will have a single domain named
default. The default domain should only be used for managing the network configuration and the
appliance itself.
Application domains allow for easier porting of development domain configurations among appliances
without affecting the core network for the appliance. A domain can easily be exported from one appliance
and imported into another.

1.4

The WebSphere DataPower WebGUI

The PoT leader will assign a unique student number to you. Your user ID and application domain is
based on your assigned number.
Your User Name is studentNN where NN is your student number. If your student number

is 2, then your user name would be student02.


Your password is: password
Your assigned application domain is the same as your user ID.

Page 8

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Youre now ready to start exploring the WebSphere DataPower WebGUI. Sign into the WebGUI and
change your password using the following steps:
__1.

Navigate your browser to the following secure URL: https://datapower:9090

__2.

Put your user name and password in the appropriate fields.

__3.

Select your domain from the dropdown list of domains, and then click Login.

Since this is the first time you are logging in, youll be requested to change your password.
__4.

In the Old Password field, type your original password: password

__5.

In the remaining two fields, type a new password that you will use for the remainder of this Proof
of Technology.

Important!
The new password is case sensitive so please make sure
to check that the cap lock key is not activated.

__6.

Click the Change User Password button.

__7.

In the confirmation dialog box, click the Confirm button.

__8.

In the success dialog box, click the Close button.

__9.

Log back into the appliance with your user name, new password and domain. Dont forget to
select your student domain from the dropdown domain list.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 9

IBM Software

Upon successful login, the DataPower Appliance Control Panel will be shown.

There are several areas in the WebGUI worth noting:


The top banner section contains some basic status information, such as the current user

and domain.
The Save Config link is used to save all of your changes into the devices flash

memory. When you make changes to a configuration, the changes are immediately
active, but they are not saved to the flash memory until you click this link.
The Logout link will end the current session. Any changes you made will remain

active.
The left side of the browser window is occupied by the navigation tree. At the top is a link

(labeled Control Panel) for quick access to the control panel. The navigation tree is
divided into several sections. Clicking on the section name will expose additional actions
within that section.

Page 10

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Status: provides menu options to view the overall status of the device, network

connections, configurations, and many other objects within the system.


Services: provides options for configuring and managing all of the services

available on the appliance.


Network: provides menu options that help you work with network configuration and

settings.
Administration: provides options that help you administer the device, such as

creating domains, users, exporting and importing configurations, etc.


Objects: contains menu options to create and manage every type of object

supported by WebSphere DataPower.


The navigation tree also includes a search box that helps you quickly navigate to a
specific function or object.
The body of the page shows the Control Panel. Its divided into three sections, each

containing icons for performing frequently used tasks.


Services - provides access to wizards that step you through the creation of a variety

of service objects such as a Web Service Proxy or a Multi-protocol Gateway.


Monitoring and Troubleshooting - provides easy access to system logs,

troubleshooting tools, Web service monitors and device status pages.


File and Administration - provides easy access to the onboard flash-based file

system, a system control panel, import and export tools, and a key and certificates
management tool.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 11

IBM Software

1.5

Configuration Procedures

There are three phases to the setup and configuration of a WebSphere DataPower SOA appliance. Each
of these phases involves a different set of objects, and often each phase is performed by different
enterprise personnel due to separation of duties and access isolation.

1.5.1

Network services and user access configuration phase

In this phase, the various objects that control the Ethernet interfaces, packet routing, time services and
emergency failure notification are configured. The basic networking values, such as IP addresses,
gateways, etc., are setup during this phase. These objects and settings all reside in the default domain
of the appliance and are accessible only to users with administrative privileges.
During the configuration phase, administrators will also setup the various application domains, users,
groups, and access policies. User access policies determine who can access the appliance to view or
alter its configuration.

1.5.2

Application Development Phase

During this phase, architects and developers create the various services that implement the solutions
needed to meet enterprise SOA requirements. This phase is often iterative as more and more top level
services are configured on the appliance.
Services can be created in a variety of ways depending on the developers experience level.
Configuration wizards provide the fastest means of creating a new service and its related objects. More
experienced developers may find it faster to create the configuration objects manually. In this Proof of
Technology, youll create objects both manually and using built-in wizards.

1.5.3

Production Management Phase

This phase occurs when a gateway configuration is moved into a runtime production environment.
Administrators commonly require that the appliance provide the means to produce status updates on a
regular and timely basis. It must also provide a quick, secure, and reliable means of upgrade,
configuration deployment and backup, and that access to the configuration interface is limited. Objects
such as Simple Network Management Protocol (SNMP) communities, statistical monitors, and audit logs
are configured as the appliance goes into production.

1.6

WebSphere DataPower Services

WebSphere DataPower SOA Appliances provide services to process traffic. This section discusses the
various service objects and their typical use cases.
The Services section of the control panel contains a group of icons that represent the most commonly
used services. The following image shows the service icons available on an XI50:

Page 12

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

1.6.1

XSL Accelerator

The XSL Accelerator validates and transforms incoming or outgoing XML documents. An XSL
Accelerator service would proxy a backend service, applying all the necessary schema
validation and transformations to the incoming document before forwarding the message to the
backend service. For response processing (from the server), it can perform similar validation and
transformation of the outbound XML using XSL.

One use case for this service object is XML to HTML rendering visualized in the above diagram. A
browser-based client makes a request to a web application. The XSL Accelerator service acts as a proxy
between the client and the backend web application server. The GET (or POST) is received by the XSL
Accelerator service, and then forwarded to the backend server. The backend server returns raw XML to
the XSL Accelerator, which then transforms the XML to HTML using an XSL template. The template may
reside on the appliance, or be fetched (and cached) from a remote server.

1.6.2

Web Application Firewall

The Web Application Firewall service is designed to provide firewall and security services for
standard HTML over HTTP Web application traffic. In addition to protecting against common
threats, the Web Application Firewall can enforce specific policies against the data flowing
between the browser and the server. For instance, it can enforce cookie existence and value policies, or
require that specific form fields contain only certain values.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 13

IBM Software

1.6.3

XML Firewall

The XML Firewall is a general purpose HTTP(S) service that can process both XML and nonXML payloads. A wide array of actions can be applied to both inbound and outbound
messages, such as encryption/decryption, digital signatures, XSL transformations, filtering,
schema validation, and dynamic routing to name just a few. Checks for XML threats are provided
automatically.

Processing policies have access to all HTTP related details (headers, form fields, payload, status, etc.)
for both the request and the response and can therefore make decisions or process messages based on
the headers existence or contents.
A robust authentication and authorization engine, with built-in integration for a wide variety of policy
servers (LDAP, IBM Tivoli Access Manager, Kerberos/SPNEGO, IBM RACF, etc.) can apply simple
to complex security policies to both inbound and outbound messages. Security protocol mediation, such
as HTTP Basic Authentication to SAML, or Kerberos/SPNEGO to IBM Lightweight Third-Party
Authentication (LTPA), is easily configured through the WebGUI. There is support for the latest security
standards such as XACML, SAML, WS-Security, WS-Policy and WS-I Basic Profile.
The XML Firewall also includes support for some of the latest WS-* standards, including WS-Reliable
Messaging and WS-Addressing.

Page 14

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

1.6.4

Multi-Protocol Gateway

The Multi-Protocol Gateway service builds on the XML Firewalls XML and security functionality
by adding support for multiple protocols. In addition to HTTP and HTTPS, the Multi-Protocol
Gateway supports WebSphere MQ, WebSphere JMS, TibcoEMS, FTP(S), SFTP, NFS and IMS. All of
these protocols can be mixed and matched as necessary. For example, messages received over HTTPS
can easily be routed to WebSphere MQ or JMS.

1.6.5

Web Service Proxy

The Web Service Proxy provides all of the same services as a Multi-Protocol Gateway service;
however it provides automatic configuration based on one or more Web Service Definition
Language (WSDL) files. WSDL files may be obtained through subscriptions to a Universal
Description, Discovery, and Integration (UDDI) or WebSphere Service Registry and Repository. A single
Web Service Proxy object can act as a single point of entry for multiple WSDLs, automatically routing (or
redirecting) the requests to the appropriate backend service.

The Web Service Proxy will automatically apply schema validation to both inbound and outbound
messages, further assuring message validity. Processing and security policies can be applied not only at
the entire service level, but for individual operations within the service as well.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 15

IBM Software

1.7

WebSphere DataPower Flash-based File System

__10.

In the Control Panel, click on the File Management icon.

You should see the file explorer similar to the one below (additional directories may appear depending on
installed hardware options).

The Flash-based file system has a set of predefined directories. Some directories are shared across
domains, such as the store: directory, while others are specific to a single domain such as the local:
directory. The following is a list of only the most common directories and their contents:

Page 16

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Directory

Usage

cert:

This encrypted directory contains private key and certificate files used by services within
the domain. Each application domain contains one cert: directory.

chkpoints:

This directory contains the configuration checkpoint files for the appliance.

config:

This directory contains the configuration files for the appliance. Each application domain
contains one config: directory.

local:

This general-purpose directory contains miscellaneous files that are used by the services
within the domain, such as XSL, XSD, and WSDL files. Each domain includes exactly one
local: directory.

logstore:

This directory contains log files that are stored for future reference.

logtemp:

This directory is the default location of log files, such as the appliance-wide default log.
This directory can hold only 13 MB.

pubcert:

This encrypted directory contains the security certificates that are used commonly by Web
browsers. This directory is shared across domains

sharedcert:

This encrypted directory contains security certificates that are shared with partners. Each
appliance contains only one sharedcert: directory. This directory is shared across
domains.

store:

This directory contains example style sheets, default style sheets, and schemas that are
used by the appliance. Do not modify the files in this directory. Each appliance contains
only one store: directory. By default, this directory is visible to all domains.

temporary:

This directory is used by processing rules as temporary disk space. Each application
domain contains one temporary: directory. This directory is not shared across domains.

The Flash-based file system is used for storing WebSphere DataPower firmware and configuration data
as well as service-related artifacts such as XSL stylesheets, keys, certificates, and schema definitions.
Static files such as schemas, WSDLs and XSL stylesheets are generally hosted off the box and fetched
(and cached) as required. Storing static documents off-box not only reduces flash storage requirements,
but greatly simplifies the deployment process when multiple WebSphere DataPower appliances are
clustered and share common artifacts.
For this Proof of Technology, youll need to upload a few files into your local: directory. The following
steps will guide you through the process.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 17

IBM Software

__11.

Click on the Actions link associated with the local: directory to reveal the actions pop-up menu
(see below).

__12.

Click the Upload Files link.

__13.

Perform the following steps to upload four files.


__a. Click on the Choose File button, and select c:\labs\files\ProductService.wsdl
__b. Click the Add button to add the file to the upload queue.
__c. Repeat the process for c:\labs\files\customFilter.xsl
__d. Repeat the process for c:\labs\files\xacml-policy.xml
__e. Repeat the process for c:\labs\files\xacml-request-binding.xsl

__14.

Click the Upload button (or Browse button, depending on your browser) to upload the files into
the local: directory.

__15.

Click the Continue button to dismiss the upload confirmation page.

Page 18

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__16.

Click on the small plus sign to the left of the local: directory and verify that all files were
uploaded.

Now youll repeat that process and upload several keys and certificates into the cert: directory.
__17.

Click the Actions link to the right of cert:, then select Upload Files.

__18.

Perform the same steps as before and select the following files:
__a. c:\labs\keysAndCerts\ProductService-privkey.pem
__b. c:\labs\keysAndCerts\ProductService-sscert.pem
__c. c:\labs\keysAndCerts\consumer-privkey.pem
__d. c:\labs\keysAndCerts\consumer-sscert.pem
__e. c:\labs\keysAndCerts\soapUI-sscert.pem

__19.

Make sure youve uploaded all pem files into the cert: directory (see below).

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 19

IBM Software

1.8

Troubleshooting Tools

During the development phase, there are often times when a service configuration produces unexpected
results. WebSphere DataPower appliances have a number of built-in troubleshooting tools that can help
pinpoint the cause of problems.
__20.

In the Navigation pane (on the left side), click the Control Panel link to redisplay the control
panel.

__21.

In the Monitoring and Troubleshooting section, click on the Troubleshooting icon to reveal the
troubleshooting tools page.

The Troubleshooting page has several tools used for troubleshooting both configuration and network
problems.
Ping Remote and TCP Connection Test are used primarily for network connectivity

troubleshooting.
Set Log Level is used to change the logging verbosity. This is a domain-wide setting

which increases or decreases the granularity of messages that are written to the log. The
default log level is error.
Generate Log Event is used to write a specific message to the logs. This is often used for

testing log targets (discussed in the next section).


The Generate Error Report and Send Error Report functions are used when it becomes

necessary to engage IBM Support to troubleshoot a problem. Generating an error report


will create a special file containing detailed system and trace information used by support
engineers.
View Running Config allows you to see what parameters are currently in effect for the

domain.

Page 20

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

1.9

Logging

WebSphere DataPower appliances have a built-in publish-subscribe logging mechanism that is robust
and flexible. As transactions flow through the appliance, many events occur. Some of these events occur
as a result of normal processing, while others occur as a result of an exception such as a transaction
being rejected due to an authentication or authorization failure.

1.9.1

Setting the Logging Level to Debug

By default, the logging level is set so that only messages with a maximum priority of Error are written to
the system log. In this section, youll change the default log level to debug, resulting in a much more
granular level of logging. This not only is helpful is seeing what steps are executing, but helps in
troubleshooting when things arent going as expected.
__22.

In the Logging section, change the Log Level dropdown to: debug

__23.

Click the Set Log Level button to activate the change.

__24.

In the Confirmation window, click the Confirm button.

__25.

Click the Close button to dismiss the window.

Throughout the various configuration forms, there are links that enable you to view the logs. For
example, right above the Log Level is a magnifying glass icon that, when clicked, will open a window
showing the system log. You can also view the log from the main control panel.
__26.

Click on the Control Panel link in the upper left corner of the browser window.

__27.

In the Monitoring and Troubleshooting section, click on the View Logs.

Clicking on the View Logs icon will take you to the system log page, which by default shows the last 50
entries in the default log. The interface enables you to filter the entries by category and/or priority, in
order to limit the number of lines.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 21

IBM Software

Since there has been minimal activity in your student


domain, your log will likely contain only one or two
messages. The following image shows a more active log.

For additional filtering, you can click a transaction id (tid), client IP address, or error code. Each of these
opens a new window with messages related to the selected value; for example, clicking a transaction ID
displays only messages from that transaction.

1.9.2

Log targets

The logging subsystem on WebSphere DataPower SOA Appliances is based on the publish-subscribe
paradigm that enables distribution of selected messages to various protocols and destinations.
Publishers include the DataPower appliance itself as well as the various user-configured services and
their supporting objects. For example, the DataPower appliance may log a message to indicate that a
network connection is failing. Similarly, a user-configured MQ front side handler may log a message to
indicate that the queue manager has become unresponsive.
Log targets act as the subscribers to published messages. Log targets can:
Capture messages and forward them to a variety of different logging server types such as

syslog and syslog-ng.


Save messages in DataPowers flash memory or on the built-in logging hard drive.
FTP saved log files off the appliance to an FTP server.
Subscribe or suppress messages by event codes or category.
Filter messages for a specific user-configured object.
Filter messages associated with a specific IP address.
Trigger a set of actions to occur when a specific log message is received.

Page 22

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__28.

Expand the navigation tree to expose the Manage Log Targets option. The path is:
Administration Miscellaneous Manage Log Targets

__29.

Click Manage Log Targets.


Click the Add button to create a new Log Target.

__30.

On the Main tab, locate the Target Type field and click the dropdown to reveal the list of
available log target types that you can create. You should see a list similar to the following
image. After reviewing the drop down click cancel for at this point we will not create a new log
target.

The dropdown list shows the various log target types supported by the logging subsystem.
Cache: Writes log entries to system memory (this is how the default log is setup).

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 23

IBM Software

Console: Writes log entries to the screen when using Telnet, Secure Shell (SSH), or

command line access through the serial port.


File: Writes log entries to a file on the appliance.
NFS: Writes log entries to a file on a remote Network File System (NFS) server.
SMTP: Forwards log entries as email to the configured remote SMTP servers and email

addresses. Before sending, the contents of the log can be encrypted or signed.
SNMP: Forwards log entries as SNMP traps to configured recipients.
SOAP: Forwards log entries as SOAP messages.
syslog-ng: Forwards log entries using Transmission Control Protocol (TCP) to a remote

syslog daemon.
syslog: Forwards log entries using User Datagram Protocol (UDP) to a remote syslog

daemon.

1.9.3

Log Categories

Log targets filter captured messages by event category. The use of categories allows log targets to
subscribe to specific messages, such as appliance messages, network messages, or particular service
messages. In addition to the predefined log categories specific to WebSphere DataPower objects and
operations, you can create your own custom log categories which are more specific to your applications.
__31.

Back in the Administration section of the navigation tree, locate and click on the Configure Log
Categories link.
A list of all predefined log categories will be displayed.

Page 24

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

1.9.4

Appliance management

There are a number of methods that administrators can use to manage WebSphere DataPower SOA
Appliances. These methods include:
Manually exporting and importing configurations. Configurations can include a single

object, an entire service, an entire domain, or an entire appliance. Configurations can be


exported either as zip or XML files. Once exported, a configuration can easily be imported.
Scripting. Command Line interface (CLI) commands can be scripted and executed to

perform DataPower configuration tasks. Scripting can also be accomplished using SOMA
(SOAP management interface) and integrated with high level programming languages.
Appliance Management Protocol (AMP) and WebSphere Appliance Management Toolkit.

This includes a set of Java components that can be leveraged to perform common
management routines such as backup, restore, etc.
WebSphere Appliance Management Center. This separately licensed product provides a

browser-based graphical user interface allowing for the management of clusters of


DataPower appliances. Tasks include configuration synchronization and firmware
maintenance.

1.9.5

Backup and Restore

Administrators can use the Export Configuration utility to export a complete appliance back-up or export
selected portions of the appliance configuration.
The Import Configuration utility is used to restore a complete appliance back-up or selected portions of
an exported configuration.
__32.

At the top of the left navigation pane, click the Control Panel link.

__33.

In the bottom row of icons, click the Export Configuration icon.

__34.

Leave the default selection of Export configuration and files from the current domain and click
the Next button.

__35.

Change the Export File Name field to: MyExport

__36.

Under the heading Select configuration objects to export, make sure All Objects is selected;
then click the right pointing button to move the selected objects into the Selected Objects box.

When you click the right pointing arrow, the right side box will become populated with all of the objects in
your domain. The objects in the right box will be the objects that are exported as shown in the following
image.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 25

IBM Software

__37.

Click the Next button. The export file named MyExport is now created and ready for you to
download to your workstation.

__38.

Click the Download button. Youll be prompted for a location to save the exported file. You can
save the file anywhere on your workstation.

__39.

Click the Done button.

The file you just downloaded contains a complete backup of your application domain. The MyExport.zip
file can now be imported into another WebSphere DataPower appliance to recreate an exact duplicate of
your domain.

1.9.6

Device Status

The built-in monitoring subsystem can provide complete details as to the operational status of the
appliance, including firmware and library information as well as memory usage, CPU utilization and
hardware operational circumstances. All of this information is viewable from within the WebGUI as well
as through remote monitoring tools (discussed in the next section).
__40.

In the navigation tree, expand the Status menu to reveal the various status sections.

__41.

Locate and expand the System section and explore the various status details.

Page 26

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

1.9.7

Remote monitoring

Administrators can monitor the health and activity of the appliance with any of the following protocols:
SNMP
Web Services Distributed Management (WSDM)
WS-Management
Proprietary SOAP application programming interface (API)

Remote consoles such as SNMP console, or an IBM Tivoli Composite Application Manager for SOA
console, can display throughput, CPU and memory usage, transaction latency, and general
responsiveness of an appliance with these protocols. The following image shows a third party SNMP
Management Information Base (MIB) Browser showing memory usage statistics.

1.9.8

Configuration Comparison, Checkpoint, and Restore

Administrators can use the Configuration Comparison utility to determine what has changed between
current and saved configurations, including previously exported configurations.
Configuration checkpoints can be set at any time within an application domain. An administrator can then
compare these checkpoints to any other configuration or roll-back the configuration of a domain to an
existing checkpoint.

Lab 1: Introduction to WebSphere DataPower SOA Appliances

Page 27

IBM Software

1.10 WebSphere DataPower SOA Appliances Firmware


Unlike traditional servers which require an operating system and various layers of installed software,
WebSphere DataPower SOA Appliances rely on a single firmware image that provides all required
functionality. Updating the firmware in a WebSphere DataPower appliance is a fast and simple process.
The firmware image is first downloaded from IBMs support site and then uploaded to the appliance.
Once uploaded, the authenticity of the firmware is verified, then decrypted, and finally applied. The
previously running firmware is maintained on the device in the event a rollback is necessary.

1.11 Summary
In this lab, you learned:
About the various tools and procedures used to configure WebSphere DataPower SOA

Appliances.
Application domains are used to logically partition a DataPower appliance. A domain can

be used for an organizational line of business, or as a location for one or more developers
to collaborate when implementing a solution.
Configuration is accomplished through any of three administrative interfaces: command

line (CLI), WebGUI, and SOAP-based XML interface.


How to upload a file to the local: directory in the Flash-based file system.
How WebSphere DataPower appliances control access to their administrative interfaces

through the use of access control lists, user accounts, groups, and access policies.
About the three configuration phases: network services/user configuration phase,

application development phase, and production management phase.


About the various WebSphere DataPower services that you can use to create simple to

complex processing policies (XSL Accelerator, Web Application Firewall, XML Firewall,
Multi-Protocol Gateway, and Web Service Proxy).
How the built-in logging subsystem is based on the publish-subscribe paradigm, with log

targets acting as subscribers to specific message categories.


How WebSphere DataPower appliances provides complete system status and metrics

from the WebGUI.


That various monitoring protocols such as SNMP, WSDM, and WS-Management are

supported.

Page 28

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 2

Working with XML

Prerequisites: This lab requires the completion of lab 1.


In this lab, youll create a fully functional Multi-Protocol gateway service that will perform various
functions against a request containing an XML (SOAP) payload.
Upon completing this lab, youll have a better understanding of:
How messages are processed
The WebSphere DataPower object-oriented configuration architecture
The Multi-Protocol Gateway service configuration
Front-side protocol handlers
Configuring Processing Policies, Rules, and Actions
Matching Rules
Validating XML documents against a schema
Built-in XML threat protection and virus scanning support
Content-based Message Filtering
Transforming XML with XSL and XPath
XSL caching

2.1

Service Processing Phases

When a service receives a message from a designated IP and port, a sequence of events are set into
motion before the message is ultimately forwarded to its intended destination. The events are separated
into three distinct phases: client-side processing, service processing, and server-side processing.

Lab 2: Working with XML

Page 29

IBM Software

2.1.1

Client-Side (Front) Processing Phase

During this phase, the received message will be directed to the service object that is configured for the IP
address and port combination on which the message was received. Once the service object (such as a
Multi-protocol Gateway or XML Firewall) receives the message, a significant amount of processing of the
message occurs. For example:
If SSL is configured for the service, SSL negotiation and decryption of the data stream will

occur.
SOAP envelope validation.
Protocol-specific actions such as HTTP header suppression or injection.
Inspection for known XML threats.

This is not an exhaustive list, but gives an idea of some of the actions that may occur upon receiving a
message. The results of these pre-processing steps could result in the message being rejected before
any message processing is even attempted.

2.1.2

Service Processing Phase

Once the client-side processing phase has completed and accepted the message, the message will be
passed to the services processing policy. This is often referred to as Multistep processing. A Processing
Policy is a list of rules that contain actions that can be applied to a message. Actions are specific
operations that are applied to a message such as encryption and decryption, message signing,
authentication, etc. As the request message passes through the processing policy, the actions are
applied to the message in a specified sequence, ultimately resulting in the message that will be passed
to the server-side processing phase.

2.1.3

Server-Side (Back) Processing Phase

If the message makes it to this phase, it has been accepted by the client-side phase and processed by
the service phase. Its now ready to be sent to the backend server. Before sending though, some
additional steps may be required. Those steps may include:
Establishing a new SSL connection to the back side server.
Setting additional headers in the request.
Mediating protocol versions (i.e. HTTP 1.1 to HTTP 1.0).
Other protocol related tasks for WebSphere MQ, WebShere JMS, FTP, NFS, etc.

Once all of the server-side processing is complete, the message is sent to the backend destination.

2.1.4

Response Processing

When (and if) a response is received from the backend server, the three phases will occur again to verify
the validity of the response, execute a processing policy, and then forward the response back to the
original client. The processing phase can be configured to have separate rules for request and response
processing.

Page 30

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

2.1.5

WebSphere DataPower Configuration Architecture

A single WebSphere DataPower appliance has the ability to host numerous service configurations. The
following diagram shows a top-level object hierarchy of a WebSphere DataPower service.

This diagram shows some of the objects associated with a given service. For example, the service could
be a Multi-Protocol Gateway that you create for handling requests. The service will use a Front Side
Handler object which identifies an IP address and port. It also includes an SSL Proxy object which
includes the necessary objects for SSL encryption. The service has a Processing Policy (for the service
processing phase), and that policy contains one or more Processing Rules, and each rule contains one
or more Processing Actions. Some of the objects will be created for you as a by-product of configuration
wizards, and others will be created by drag and drop actions within the WebGUI.

2.2

Creating the Multi-Protocol Gateway service

In this section, youll be creating a service that will receive messages posted from your workstation, and
perform a variety of actions against the messages XML payload. There are several steps youll follow to
create the service object:
Specify the basic information about the Multi-Protocol Gateway Service.
Create an HTTP Front Side protocol handler to handle HTTP requests.
Create a Processing Policy and Processing Rule

To get things started, youll create a service proxy that simply acts as a pass-thru. Whatever you post to
the service proxy will get forwarded to an echo service running on the backend server. The response will
pass back through your proxy and then be returned to your workstation.

Lab 2: Working with XML

Page 31

IBM Software

The following steps will guide you through the process of creating and testing your service proxy. If you
logged out from the WebGUI, log back in with your assigned user id and password. Make sure to select
the matching domain for your user id.
__1.

If the control panel is not visible, click on the Control Panel link at the top of the left navigation
pane.

__2.

Click on the Multi-Protocol Gateway icon.

__3.

Click the Add button to create a new Multi-Protocol Gateway service. The Configure
Multi-Protocol Gateway form will be displayed.

__4.

In the Multi-Protocol Gateway Name field, type: ProductServiceProxy

__5.

In Backend URL, type: http://demoserver:9080/ProductService/ProductService


Important!
The URI portion of the URL is case sensitive. Make sure
that you type the URL exactly as shown.

2.2.1

Creating the Front Side Handler (FSH)

The Multi-Protocol Gateway service employs one or more Front Side Handlers (FSH) to manage all
inbound traffic. In a simple configuration, there might be a single HTTP front side handler that listens for
requests on a specific IP address and port.
In the scenario shown in the following illustration, requests arrive over HTTP and are received by the
HTTP front side handler. The HTTP FSH will then pass the request to the Multi-Protocol Gateway
(MPGW) for processing

Page 32

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Its also possible to mix and match different types of protocols on the same multi-protocol gateway. For
example, you can assign one FSH for HTTP, another for HTTPS, and yet another that acts as a
WebSphere MQ client.

The server-side protocol is completely independent of the front-side and can be any of the protocols
supported by the appliance.
For this lab exercise, youll create a single HTTP Front Side Handler and assign it to the multi-protocol
gateway.
__6.

In the middle of the form towards the right is a section labeled Front side settings. Locate and
click the plus (+) button to create a new front side handler.

A pop-up list of front side handlers will be displayed. You can see from this list that the
Multi-Protocol Gateway service supports many different front-side protocols.
__7.

In the pop-up list of front side handlers, click: HTTP Front Side Handler

The options provided in the pop-up window allow you to precisely configure the various settings related
to HTTP connections. In addition to the obvious settings such as IP address and port, you can also
specify which version of HTTP that the listener will accept, or whether or not to use persistent
connections.
__8.

In the Name field, type HTTP_444nn where nn is your student number. For example, if you are
student01, type the name HTTP_44401.

__9.

Leave the Local IP Address field as 0.0.0.0. This will cause the front side handler to listen for
traffic on all IP addresses defined on the appliance.

Lab 2: Working with XML

Page 33

IBM Software

__10.

In the Port Number field, replace the default port 80 with 444nn where nn is your student
number.

__11.

Click the Apply button in the upper left corner of the form. The new HTTP FSH should be
automatically added to the list of Front Side Protocols (see below).

2.2.2

Processing Policies, Rules, and Actions

Each service that you configure will have exactly one Processing Policy. The processing policy defines
what should happen when a message arrives from either the client (request), or the server (response).
A processing policy is comprised of one or more Processing Rules. A processing rule always begins with
a Match Action, followed by one or more Processing Actions. Processing rules are identified as either
request, response, both, or error types. A processing rule that is indicated as a request rule will be
ignored during response processing. A processing rule that is identified as both will be evaluated for both
requests and responses. Error rules are executed only when an error occurs during processing.
Multi-Protocol Gateway
Processing Policy
Processing Rule #1
[ Req | Rsp | Both | Error ]

Processing Rule #2

Processing
Action #1

Processing
Action #2

Processing
Action #N

Match
Action

Processing
Action #1

Processing
Action #2

Processing
Action #N

Processing
Action #1

Processing
Action #2

Processing
Action #N

[ Req | Rsp | Both | Error ]

Match
Action

Processing Rule #N
[ Req | Rsp | Both | Error ]

Match
Action

The Match Action references a Match Rule that contains one or more matching criteria (or expressions)
that are evaluated to determine whether or not to execute the remaining actions in the processing rule.
When more than one match expression is defined, the match rule can specify whether to combine them
with Boolean AND or OR semantics. When the match rule is configured to use OR, only one of the match
expressions must be True; when AND is specified, all expressions must evaluate to True.

Page 34

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Matching expressions can test the message in several ways. For instance, in this lab youll be specifying
a matching expression that inspects the request URI for a specific pattern. Matching rules support the
following types of matching expressions:
URL: A match template that inspects the URL for a specific pattern.
HTTP: A match template that inspects the value of a specified HTTP header for a specific

pattern.
HTTP Method: A match template that compares the specified HTTP method (POST, GET,

DELETE, etc.) against the value of the HTTP request line.


Error Code: A match template that matches against specific error codes that may have

been raised by previously executed processing rules.


XPath: A match template that uses the specified XPath expression to inspect the contents

of the XML message body.


When a message arrives into the processing policy, the policy will look at each processing rule, starting
with the first one, and evaluate its associated match expression. If the match expression evaluates to
True, the actions in that rule will be executed, otherwise the policy will look at the next rule. Once a
match rule evaluates to True, no other match rules will be evaluated. Only one processing rule will be
executed.
__12.

In the General Configuration section of the form on the right side, locate the field labeled
Multi-Protocol Gateway Policy and click the plus (+) to create a new processing policy.

__13.

In the Policy Name field at the top of the policy editor, type: ProductServicePolicy

Lab 2: Working with XML

Page 35

IBM Software

In the following steps, youll create a rule that will process client requests.
__14.

In the Rule section, click on the New Rule button.

__15.

In the Rule Direction dropdown, select: Client to Server

After you click the new rule button, a blank rule will be created that contains a match action.

A yellow box means that


configuration is missing

For this lab, youll create a match rule that will match on any inbound URI.
__16.

Double click the match action to reveal its configuration form in a pop-up window.

__17.

In the Configure a Match Action form, click on the plus (+) button to create a new matching rule.

__18.

In the Configure Matching Rule form, in the Name field, type: MatchAnyURI

__19.

At the top of the form, click on the Matching Rule tab.

__20.

At the bottom of the list of matching rules, click the Add button to create a new expression.

__21.

Leave the Matching Type field as URL.

__22.

In the URL Match field, type: * (The asterisk is a wildcard character that will match anything).

__23.

Click the Apply button, which will close the Edit Matching Rule window.

__24.

In the Configure Matching Rule window, click the Apply button, which will close the Configure
Matching Rule window.

__25.

In the Configure a Match Action window, click the Done button, closing the Configure a Match
Action window. To validate the rule you just created hover your mouse over the match action
icon, the following should be set Type : url and url : *.

In the following steps, youll create a rule that will process server responses.
__26.

In the Rule section, click on the New Rule button.

__27.

In the Rule Direction dropdown, select: Server to Client

Page 36

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__28.

Double click the match action to open its configuration form.

__29.

In the Configure Matching Action form, select the previously created MatchAnyURI rule from the
dropdown list.

__30.

Click the Done button.

__31.

Click the Apply Policy button to save these changes. When you do this a Results action will be
inserted into the processing rule. At this point your screen should look like the following.

__32.

Click the Close Window link in the upper right corner to dismiss the policy editor.

__33.

In the Configure Multi-Protocol Gateway form, click the Apply button to activate this new
configuration.

Lab 2: Working with XML

Page 37

IBM Software

You are now ready to test the service you just created.
__34.

On the desktop, locate and launch the soapUI application.

__35.

In the project tree, expand the ProductService project until SOAP request is visible (see below).

__36.

Double click SOAP request to open the request window.

__37.

In the upper right corner of the soapUI window, click the maximize button to enlarge the request
window.

__38.

In the endpoint dropdown, select: http://datapower:444nn/ProductService/ProductService

__39.

Dropdown the list again, then select [Edit current].

__40.

Update the port number by replacing nn with your student number, then click OK.

__41.

Click the green submit button to POST the request to ProductServiceProxy.

If everything worked properly, you should see <getProductResponse> xml tree in the Response tab.
If you received an error, you can try and determine the cause by looking at the logs. Theres a
convenient View Log link found towards the top of the Multi-Protocol Gateway configuration page. You
can also view the logs from the main control panel by clicking on the View Logs icon.
At this point, you have created a multi-protocol gateway service that acts as a pass-thru and verified that
it works. Now youll add some more interesting functionality to the service.

2.2.3

Save the Running Configuration

Once you have your configuration running properly, its a good idea to save the configuration to the flash
memory. At this point, if the device was shut off or the power was disconnected, all of the work youve
done until now would be lost. Saving the configuration causes your domain to be written to the flash
memory, making it available after the device is restarted.

Page 38

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__42.

At the top of the browser window, click on the Save Config link. You should see a message that
says Configuration successfully saved as shown in the image below.

2.3

Schema Validation

An XML Schema describes the structure of an XML document. Validating an XML document against a
schema is one step to assuring that the structure and content of the document is valid and safe. The
process of validating an XML document against a schema is generally considered to be processor
intensive, resulting in increased server load. For this reason, organizations often disable schema
validation in an effort to reduce load (and cost) on application servers, especially when they are running
on a mainframe. This is generally considered a security risk.
WebSphere DataPower SOA Appliances solve this problem by providing wirespeed schema validation to
messages before they reach the application server. Messages that fail validation are rejected by default
(this behavior can be customized).
In this section, youll add a new processing rule to your service that will ultimately perform a variety of
actions against the SOAP request.
Now youll add a schema validate action to the processing rule. Youll configure the Validate action to
use the embedded schema in the WSDL you uploaded in the first lab.
__43.

Click on the ellipsis () button in the Multi-Protocol Gateway Policy field.

Lab 2: Working with XML

Page 39

IBM Software

__44.

Expand the policy editor so that you can see all the configured rules at the bottom. Make sure
the Client to Server rule is selected (it will be bold).

__45.

Click and drag a Validate action and drop it to the right of the matching action.

__46.

Double click the new validate action (outlined in yellow) to provide the missing configuration
details.

There are several methods listed for the Schema Validation method. This is a good opportunity to see
the appliances online help.
__47.

Move the mouse over the field label Schema Validation Method. You should notice that it is
actually a hyperlink. Almost all field labels in the WebGUI are hyperlinks and when clicked, will
pop up a help window to explain the various options for that field.

__48.

Click the Schema Validation Method label to show the help text. Close the help text window by
clicking its close button.

Page 40

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__49.

Select the radio button associated with: Validate Document via WSDL URL. Selecting this
option causes DataPower to validate the message against the schema found within a WSDL.

__50.

In the WSDL URL, make sure the upper dropdown contains local:///. In the lower dropdown list,
select ProductService.wsdl that you previously uploaded. The Validate configuration window
should look like the following image.

__51.

Click the Done button at the bottom of the window.

__52.

Click the Apply Policy button at the top of the policy editor to activate your changes.

__53.

Click the Close Window link in the upper right corner of the policy editor.

The WSDLs schema looks like the schema in the following listing. Notice that the product-id element
restricts its values to the various WebSphere DataPower SOA Appliances models (XA35, XS40, etc.).
<xsd:element name="product-info">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="product-id">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="XA35"/>
<xsd:enumeration value="XS40"/>
<xsd:enumeration value="XI50"/>
<xsd:enumeration value="XI52"/>
<xsd:enumeration value="XB60"/>
<xsd:enumeration value="XB62"/>
<xsd:enumeration value="XM70"/>
<xsd:enumeration value="XE82"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="brand" type="xsd:string"/>
<xsd:element name="encoded-description" type="xsd:string"/>
<xsd:element name="benefits" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>

</xsd:element>

Lab 2: Working with XML

Page 41

IBM Software

__54.

In soapUI, click the green submit button to POST the request again. The request should be
successful as it was before. This indicates that the message successfully passed schema
validation.

__55.

In the Request tab, change the value of <product-id> to 1234, then click the green submit
button to post the message.

Since 1234 is not a valid product-id, it failed schema validation resulting in a SOAP fault back
to the client.

The returned error message indicates that an internal error occurred but no other details are provided.
This is by design to prevent malicious attackers from gaining detailed information about the underlying
service. You can see detailed information about the failure in the DataPower log.
__56.

In the Multi-Protocol Gateway configuration page, click on the View Log link towards the top right
side of the page.

The log will reveal the underlying reason for the Internal Error message.

__57.

Page 42

Close the log window by clicking on the Windows close button (upper right corner of window).

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

2.4

SOAP Envelope Schema Validation

The Multi-Protocol Gateway service that you configured expects requests and responses to conform to
SOAP standards. This setting is found towards the middle of the Multi-Protocol Gateway main
configuration page (see following image).

Important!
The following steps show you how to reload the request
payload with prebuilt SOAP messages. In future steps,
these detailed steps will be omitted for brevity.

__58.

In the soapUI Request tab, right click within the message body and select: Load from

__59.

In the Load Editor Content dialog, select c:\labs\requests\noSoapEnv.xml; then click


Open.

Lab 2: Working with XML

Page 43

IBM Software

__60.

Click the green submit button to POST the XML to ProductServiceProxy. The request should fail
again. To see details about the failure, click on the View Log link in the Multi-Protocol Gateway
configuration page.

2.5

Content-based Filtering

You can easily extend the built-in threat protection by defining custom filters. A custom filter is an XSL
template that makes an accept or reject decision based on some custom logic that you define.
The accept and reject decision are accomplished using special built-in extension functions for XSL.
The <dp:accept> and <dp:reject> extension functions are used to tell processing rule how to proceed
with the message. The following XSL template inspects the <brand> element to make sure that it
contains the string DataPower.
Listing of file: customFilter.xsl
<xsl:template match="/">
<xsl:choose>
<xsl:when test="contains(//prod:brand,'DataPower')">
<dp:accept/>
</xsl:when>
<xsl:otherwise>
<dp:reject>Missing 'DataPower' trademark</dp:reject>
</xsl:otherwise>
</xsl:choose>
</xsl:template>

Now youll add a filter action to your processing rule.


__61.

In the policy editor window, drag a filter action onto the rule as shown below.

__62.

Double click the yellow outlined filter action to complete its configuration.

__63.

In the Filter section:


__a. In the upper dropdown for XSL style sheet, make sure local:/// is selected.
__b. In the lower dropdown, select customFilter.xsl.

__64.

Page 44

In the Configure Filter Action window, click Done.

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

The processing policy should now look like the following image.

__65.

Click the Apply Policy button to make your changes active.

__66.

In the soapUI request window, load the request from c:\labs\requests\missingDp.xml.


Notice that the brand is missing the word DataPower.

__67.

Click the green submit button to POST the request to ProductServiceProxy. You should receive
a SOAP fault with an error message as shown in the following image.

2.5.1

SQL Injection Threat Filtering

SQL Injection is an attack technique used to exploit Web sites and services that construct SQL
statements from user-supplied input. For example, assume that a web service expects a SOAP request
containing a <last-name> element used for looking up a customer.
<soap:Body>
<customer-lookup>
<last-name>KAPLAN</last-name>
</customer-lookup>
</soap:Body>

The Web service uses an SQL statement with substitution parameters similar to the following SQL
snippet:

SELECT * FROM EMPLOYEE WHERE LASTNAME = ?


After the substitution takes place, the resultant SQL statement will be:

SELECT * FROM EMPLOYEE WHERE LASTNAME = 'KAPLAN'


However, if the value submitted in the <last-name> element contained a malicious SQL injection threat, it
may look like this:
<soap:Body>
<customer-lookup>
<last-name>KAPLAN OR 1=1</last-name>
</customer-lookup>
</soap:Body>

Lab 2: Working with XML

Page 45

IBM Software

The SQL statement would become:

SELECT * FROM EMPLOYEE WHERE LASTNAME = 'KAPLAN' OR '1' =


'1'
The service will return the details about ALL employees, since the WHERE clause will evaluate to true
for every record in the EMPLOYEE table (because of the 1 = 1 clause).
WebSphere DataPower SOA Appliances can protect against such SQL injection threats using a special
SQL injection threat filter. It works the same way as the filter you tried in the previous steps, except that
the logic is a bit more complex.
The SQL Injection Threat filter has two parts: the base stylesheet filter (that uses <accept/> and
<reject/>), and an XML file that contains the various patterns to search for. Keeping the patterns in a
separate XML file allows you to create more customized patterns.
__68.

In the policy editor window, drag another Filter action onto the processing rule to the right of the
previously added filter action.

__69.

Double click the yellow outlined filter action to complete its configuration.

__70.

In the Filter section:


__a. Change the upper dropdown for XSL style sheet to show: store:///
__b. In the lower dropdown box, select: SQL-Injection-Filter.xsl

__71.

Click the Done button.

__72.

Click the Apply Policy button to activate these changes.

Page 46

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

The policy will now protect against malicious SQL injection threats. The file sqlThreat.xml contains a
SOAP message with an SQL Injection Threat in it. The contents of the <brand> element contain the
threat:
<product-info>
<product-id>XI50</product-id>
<brand>DataPower' or '1'='1</brand>
<encoded-description>{omitted}</encoded-description>
<benefits>Security;Integration;Performance</benefits>
</product-info>

__73.

In the soapUI request window, load the request from c:\labs\requests\sqlThreat.xml.

__74.

Click the green submit button to POST the message to ProductServiceProxy. The request
should fail due to Message contains restricted content (from client).

2.6

Transforming with XSL and XPath

At the heart of WebSphere DataPower SOA Appliances is a high speed XSL compiler and execution
engine. In fact, most of the built-in functionality is engineered using XSL. Some of the built-in stylesheets
can be found in the store directory. XSL developers can easily copy and modify the IBM provided
stylesheets to create new functionality or support emerging standards before IBM makes them available.
When a stylesheet is referenced for the first time, it is compiled using a patented optimizing XSL compiler
for execution on specialized WebSphere DataPower hardware, then cached in memory for high-speed
recall and execution.
IBM has augmented XSL with a rich set of extension functions that enable you to easily add complex
processing functionality to your processing rules. For example, there are extension functions for
performing base-64 encoding and decoding, encryption and decryption, and date/time functions. There
are also functions for communicating with off-box web services as well as LDAP servers.
In this section, youll be introduced to how XSL templates are used within processing rules. Youll also
get a chance to see the decode() extension function for decoding base-64 encoded text.
In the following steps, youll add a transform action to the response (server to client) rule instead of the
request rule. Since the transform action will modify the overall structure of the message, it wont match
the schema that the backend service is expecting, therefore the request will fail. To avoid this, youll
modify the response which is destined back to soapUI.
__75.

In the policy editor, towards the bottom, click on the Server to Client rule to make it the active
rule in the editor.

Lab 2: Working with XML

Page 47

IBM Software

__76.

Click and drag a transform action and drop it after the match action.

__77.

Double click the yellow outlined transform action to expose its configuration settings.

For this transform, the stylesheet will be located on a remote HTTP server rather than in your local:
directory.
__78.

In the Transform field:


__a. In the top dropdown, select http://.
Important!
In the next step, the Path is case sensitive and must be
identical as shown.

__b. In the lower text box, type: demoserver/files/productTransform.xsl


__79.

Click the Done button to save the transform action.

__80.

Click the Apply Policy button to apply the changes to the overall policy.

__81.

Click the Close Window link to dismiss the policy editor.

__82.

Click the Apply button in the Configure Multi-Protocol Gateway form.

Youre now ready to run another transaction through your multi-protocol gateway service. Before you do
that, lets take a look at what the XSL template will do to the message.
Heres the SOAP body of the response message. Notice the <encoded-description> tag contains base64 encoded text (some of it has been omitted).

Page 48

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

<soap:Body>
<getProductResponse>
<Product>
<product-id>XI50</product-id>
<brand>WebSphere DataPower</brand>
<encoded-description>SUJNIFdlYlNw {omitted}</encoded-description>
<benefits>Security;Integration;Performance</benefits>
<Product>
</getProductResponse>
</soap:Body>

The productTransform.xsl template looks for two different patterns:


When a <encoded-description> tag is encountered, it will change it into a <description>

tag and then decode the original tags value. dp:decode() is an extension function that will
perform the base-64 decoding.
When a <benefits> tag is encountered, it will use the str:tokenize() function to tokenize the

list of benefits (delimited by semicolons) into a small XML tree.


An identity transform is found at the end of the template, which will match anything else

that hasnt explicitly been matched, and copy it to the output document.
Partial Listing of file: productTransform.xsl
<xsl:template match="encoded-description">
<description>
<xsl:value-of select="dp:decode(.,'base-64')"/>
</description>
</xsl:template>
<xsl:template match="benefits">
<xsl:variable name="benefits" select="str:tokenize(.,';')"/>
<benefits>
<xsl:for-each select="$benefits">
<benefit><xsl:value-of select="."/></benefit>
</xsl:for-each>
</benefits>
</xsl:template>

Lab 2: Working with XML

Page 49

IBM Software

__83.

In the soapUI request window, load the request from c:\labs\requests\soapMsg.xml.

__84.

Click the green submit button to POST the message to ProductServiceProxy, then inspect the
response. Notice that the <encoded-description> tag was replaced with a <description> tag, and
that its contents are no longer base-64 encoded. Also, the benefits list was properly expanded
into a multi-element <benefits> group.

__85.

If youve gotten everything working properly, you can save your configuration by clicking the
Save Config link in the top of the browser window.

2.7

Stylesheet Caching

XSL stylesheets are compiled and then cached to improve performance. Previously you configured your
processing rule to transform the request XML document against productTransform.xsl. The stylesheet
was fetched from a remote server, compiled, and then cached. You can verify this by checking the status
of the document cache.
__86.

In the left hand navigation pane, under the Status menu, scroll down to find and expand the
XML Processing section, and click on Stylesheet Cache.

In the cached stylesheets column, you can see the number of stylesheets that have been compiled and
cached (this value also includes some system stylesheets).
__87.

In the XML Processing section, click on Stylesheet Status

The Stylesheet Status page shows you all of the stylesheets that have been compiled and cached. Since
schema documents (XSD) are compiled like stylesheets, they show up in this list too.

2.8

Implicit XML Threat Protection

Services that are configured to receive XML messages provide a wide array of additional XML threat
protection.

2.8.1

Malformed XML Content Detection

In this next step, youll post malformed XML to your service

Page 50

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__88.

In soapUI, click on the Request tab.

__89.

Load the request body with file c:\labs\requests\malformed.xml.


Notice that the closing <Product> tag is missing the leading slash resulting in the XML to be
malformed. Dont correct the error.

__90.

2.8.2

Click the green submit button to POST the malformed message to ProductServiceProxy. Again,
you should receive a generic SOAP fault. Click the View Log link at the top of the Multi-Protocol
Gateway configuration page and notice the error message pertaining to the mismatched tag.

XML Denial of Service (XDoS)

WebSphere DataPower appliances can protect Web services against both single message denial of
service (XDoS) and multiple message denial of service (MMXDoS) attacks.
Single message XDoS attacks may have any combination of the following characteristics:
Jumbo payloads Sending a very large XML message to exhaust memory and CPU on

the target system.


Recursive elements XML messages that can be used to force recursive entity expansion

(or other repeated processing) to exhaust server resources


MegaTags Otherwise valid XML messages containing excessively long element names,

or an excessive number of tags. This attack may also lead to buffer overruns.
Coercive parsing XML messages specially constructed to be difficult to parse, resulting

in excessive resource consumption in the target machine.


Public key DoS Utilizing the asymmetric nature of public key operations to force

resource exhaustion on the recipient by transmitting a message with a large number of


long-key-length, computationally expensive digital signatures.
Multiple message XDoS (MMXDoS) attacks may have the following characteristics:
XML flood sending thousands of otherwise benign messages per second to tie up a

Web service. This attack can be combined with Replay attack to bypass authentication,
and with Single message XDoS to increase its impact.
Resource hijack sending messages that lock or reserve resources on the target server

as part of a never-completed transaction.


__91.

Return to the ProductServiceProxy configuration page. At the top of the Multi-Protocol Gateway
configuration form is a set of tabs. At the right and left side of the tabs are arrow images. Moving
the cursor over the arrow (without clicking) will cause the tabs to shift left or right. Move the
mouse over the right arrow until the XML Threat Protection tab is visible.

__92.

Click on the XML Threat Protection tab.

Lab 2: Working with XML

Page 51

IBM Software

__93.

In the Single Message XML Denial of Service section, click the on radio button for Gateway
parser limits.

__94.

Notice that the XDoS protection is highly customizable. For now turn this off by togging the
Gateway parser limits back to off.

__95.

In the Multiple Message XML Denial of Service section, click the on radio button for Enable
MMXDoS Protection.

__96.

Again notice the ability to customize and then click the off button for Enable MMXDos Protection.

__97.

Before completing this lab it would be a good time to click on the Save Config link at the top of
the screen

2.8.3

Virus Scanning

Viruses are typically contained in message attachments. XML Virus Protection sets parameters that
handle the following types of attacks in attachments:
XML virus attacks
XML encapsulation attacks
Payload hijack attacks
Binary injection attacks

There are two levels of protection against virus threats.


The first level is to determine whether or not to allow attachments. This is accomplished

on the XML Threat Protection tab that is currently displayed in your browser in the
XML Virus (X-Virus) Protection section.
If attachments are allowed, the second level of protection occurs in the processing rule. A

special Virus Scan action will extract the attachment from the message and send it to an
Internet Content Adaption Protocol (ICAP) compatible virus scanner. If the scanner
responds that a virus exists in the attachment, the virus scanning action will either strip the
attachment or reject the message (based on configuration settings).

Page 52

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

2.9

Summary

In this lab, you learned:


That there are three service processing phases that occur each time a message arrives.

The client-side processing performs all protocol related processing as well as shielding
against a variety of malicious attacks. The service processing phase contains all of the
specific rules and actions that you define. The server-side processing phase is where any
backside protocol tasks are performed before the message is forwarded to the intended
destination.
WebSphere DataPower configurations are built using a pure object-oriented design. Every

configuration object, such as a SSL Proxy Profile or a Processing Policy, can be reused.
How to configure a Multi-Protocol Gateway service, along with an HTTP Front Side

protocol handler, and a Processing Policy.


A Processing Policy contains a set of Processing Rules; each rule begins with a Match

Action that is evaluated to determine whether the rule should be executed. Each
processing rule contains a list of processing actions that are executed against the
message.
Match rules can match on various aspects of a message, including the URL, HTTP

headers, error codes, or an XPath that inspects the XML payload of a message.
Clicking the Save Config link in the top navigation area will save your running

configuration (for your domain) to the flash memory. The running configuration and the
saved configuration are independent.
How to add a schema validate action to the processing rule by dragging it from the action

palette onto the processing rule. WebSphere DataPower appliances can perform schema
validation against messages at near wire-speed, adding minimal latency to the overall
transaction time.
SOAP requests and responses are automatically checked against a SOAP schema,

assuring that the SOAP envelope is well-formed and correct.


Request and response XML documents are checked to assure they are well-formed.

Malformed XML is rejected which assures backend applications receive only well-formed
XML.
Custom Filters can be used for content-based message filtering and SQL injection threat

protection.
How to transform an XML document using a Transform action.
XSD and XSL stylesheets are compiled and cached.

Lab 2: Working with XML

Page 53

IBM Software

Page 54

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 3

Securing XML Message Content using WS-Security

Prerequisites: This lab requires the completion of labs 1 and 2.


In this lab, youll be adding a few new processing rules to your multi-protocol gateways processing policy
to demonstrate various security features.
Upon completing this lab, youll have a better understanding of:
Private keys and public certs.
How WebSphere DataPower handles digital keys and certificates.
Support for WS-Security digital signatures, encryption, and decryption.
Field-level encryption.
The built-in authentication and authorization framework.
Connecting to an LDAP server.
Configuring SSL.

3.1

Public Key Infrastructure (PKI)

In the digital world, public and private keys are often employed to perform cryptographic operations, such
as encryption of message data. The use of key pairs (public/private) is known as asymmetric encryption.
It is vital that the private key is protected, while its public counterpart, the public key (often carried in a
certificate), can be freely distributed. Certificates are typically validated by a Certificate Authority (CA). In
the event that an authority needs to revoke a previously distributed certificate, it adds the revoked
certificate to a globally published certificate revocation list (CRL).
On DataPower, public certificates and private keys are wrapped in crypto objects so that there is one
level of indirection when using them. For example, when you upload a public certificate, it will be
wrapped in a Crypto Certificate object. When a service object needs to use that public certificate, it will
reference it using the crypto certificate instead of the actual certificate file. The following image shows a
signing action that references a crypto key and crypto cert when digitally signing a message.

This single level of indirection allows the underlying key or certificate to be replaced without the need to
reconfigure any services that are using it.

Lab 3: Securing XML Message Content using WS-Security

Page 55

IBM Software

3.2

WS-Security Digital Signatures

The term digital signature refers to something created using public key technology. Two keys are
involved: a private key, which only you know, and a corresponding public key, which you can freely give
to anyone. What makes this key pair interesting is that anything encrypted using one key can only be
decrypted with the other one.
The primary usage of digital signatures is to verify the integrity of a transmitted message. When a
message travels over public networks, it can be intercepted, modified, and then forwarded without
detection. Adding a digital signature to a message enables the recipient of the message to determine
whether the message has been altered along the way.
For example, assume a business partner wants to send you a digitally signed message. First, they will
compute a special checksum on the message they want to send (this is often referred to as a message
digest). Then they encrypt the digest with their private key. The result is a digital signature for the
message. They send this digital signature along with the original message to you.
When you receive the message, youll first compute the message digest on the received message. Youll
then use the senders public key to decrypt the message digest that was sent along with the message. If
the message digest that you calculated and the one that you decrypted are identical, then you can be
certain that the data wasnt changed in transit (integrity) and that the data was signed by the business
partner (authentication).
Creating and verifying digital signatures involve a considerable amount of mathematical computations,
and are thus very processor intensive. WebSphere DataPower employs cryptographic hardware to do
these calculations, thus freeing up costly processor cycles for business-related tasks.
In this section, youll configure your ProductServiceProxy to:
1. Verify a digital signature generated by soapUI. If the verification fails, reject the request.
2. Strip the digital signature from the request before forwarding it to the backend service.
3. Add a digital signature to the services response and return the signed response to soapUI.

3.2.1

Crypto objects

In lab 1, you uploaded several PKI files. Keys and certificates generally have expiration dates, thus
requiring occasional replacement. To avoid the need to change multiple configurations each time a key
or certificate needs updating, keys and certificates are wrapped in Crypto Key and Crypto Certificate
objects. These crypto objects add a level of indirection to the underlying keys and certs, averting the
need to update affected configurations each time key or certificate maintenance occurs.
The following steps will guide you in creating a Crypto Key object that wraps ProductServiceprivkey.pem, and Crypto Certificates that wrap ProductService-sscert.pem and soapUI.pem.

Page 56

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Create the Crypto Key and Cert to represent ProductServiceProxy


In previous steps, you either used the icons in the main control panel, or expanded the navigation tree to
locate a specific object. In the following steps, youll use the search function to quickly find the object
youre interested in.
__1.

In the search field above the navigation tree, type the word crypto (case is not important). As
you type, the results of the search will replace the navigation tree.

__2.

In the search results, locate and select: Crypto Key

__3.

Click the Add button to create a new crypto key.

__4.

In the Name field, type: ProductServiceCryptoKey

__5.

In the File Name field (lower dropdown), select: ProductService-privkey.pem

__6.

Click the Apply button.

__7.

In the left navigation, locate and select Crypto Certificate

__8.

Click the Add button to create a new crypto certificate.

__9.

In the Name field, type: ProductServiceCryptoCert

__10.

In the File Name field (lower dropdown), select: ProductService-sscert.pem

__11.

Click the Apply button.

Create the Crypto Cert that wraps soapUIs certificate


__12.

In the left navigation pane, locate and select Crypto Certificate. If you cannot find it, you can use
the navigation search box.

Lab 3: Securing XML Message Content using WS-Security

Page 57

IBM Software

__13.

Click the Add button to create a new crypto certificate.

__14.

In the Name field, type: SoapUICryptoCert

__15.

In the File Name dropdown, select: soapUI-sscert.pem

__16.

Click the Apply button.

3.2.2

Verifying a Digital Signature

The process of securely verifying a digital signature requires that the recipient of the message have
access to the signers public certificate. The certificate is often included in the signed message, but the
most reliable way of verifying the signature is with a certificate provided by the signer and uploaded to
the cert: directory.

3.2.3

Crypto Validation Credential

Earlier, you created a crypto certificate object


which wrapped a single PKI certificate. Consider
Crypto Validation
Credential
the case where you need to create a processing
rule that will verify a digital signature, but the
signer may be one of many different business
Crypto Certificate
Public Certificate
partners. Creating separate processing rules for
each partner would be cumbersome and subject
Crypto Certificate
Public Certificate
to constant modification when partners were
added or dropped. The crypto validation
credential object has the ability to group many
crypto certificates together into a single object.
Crypto Certificate
Public Certificate
With a crypto validation credential (often referred
to as a valcred), you can create a single
processing rule with a single signature verification action that will accommodate countless public
certificates. Certificates can be added and removed from the validation credential independent of any
verification actions that use it.

Creating a Crypto Validation Credential


__17.

In the search field above the navigation tree, type the word crypto. In the search results, locate
and select: Crypto Validation Credentials

__18.

Click the Add button to create a new validation credential object.

__19.

In the name field, type: ProductSvcConsumersValcred

__20.

In the Certificates field, dropdown the certificate list and choose: SoapUICryptoCert

__21.

Click the Add button to add the certificate to the list of certificates.

__22.

Click Apply to save the new validation credential object.

Page 58

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

3.2.4

Verifying the request signature and signing the response

In the next steps, youll modify the ProductServiceProxy Multi-Protocol Gateway to verify the digital
signature sent by soapUI, and to put a digital signature on the response sent back to soapUI.
__23.

In the search field above the navigation tree, type the word multi.

__24.

In the search results, locate and click on: Edit Multi-Protocol Gateway

__25.

Select ProductServiceProxy from the list.

__26.

As youve done before, open the policy editor window by clicking on the ellipsis in the
Multi-Protocol Gateway Policy field.

Verify the requests digital signature


__27.

Drag a Verify action onto the processing rule after the match action.

__28.

Double click the yellow outlined verify action to complete its configuration.

__29.

In the Validation Credential field's dropdown list, select: ProductdSvcConsumersValcred. This


validation credential contains soapUIs public certificate which will be used when verifying the
digital signature.

__30.

Click Done.

In the following steps, you'll add a transform action that will strip off the digital signature that soapUI
created. This is not required, but is often done in order to reduce the overall message size. WebSphere
DataPower appliances come with a library of pre-built stylesheets that perform various useful tasks such
as stripping a digital signature. These pre-built stylesheets can be found in the store: directory.

Lab 3: Securing XML Message Content using WS-Security

Page 59

IBM Software

__31.

In the policy editor, drag a transform action after the verify action.

__32.

Double click the yellow outlined transform action to complete its configuration.

__33.

In the Transform field:


__a. Select store:/// in the upper dropdown box.
__b. In the lower dropdown, select strip-wssec-signature.xsl

__34.

Click the Done button.

Sign the response


__35.

In the configured rules section in the policy editor (at the bottom), click on the Server to Client
rule to make the response rule active in the editor.

__36.

Drag a Sign action onto the processing rule to the right of the transform action.

__37.

Double click the yellow outlined sign action to show its configuration.

__38.

In the Key dropdown, select ProductServiceCryptoKey

__39.

In the Cert dropdown, select: ProductServiceCryptoCert

__40.

Click the Done button to complete the sign action configuration.

__41.

Click the Apply Policy button to make your changes to the policy effective.

__42.

Click the Close Window link to close the policy editor.

Page 60

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

3.2.5

The Transaction Probe

The transaction probe is a troubleshooting tool that provides insight into the state of a transaction as it
moves through the processing rule. It allows you to see what the input context is to each of the actions
as well as the values of system variables, protocol headers, etc. It is the single most important tool to use
when troubleshooting a services policy.
__43.

In the Configure Multi-Protocol Gateway form, towards the upper right corner, click on the
Show Probe link.

__44.

In the probe window, click on the Enable Probe button.

__45.

Click the Close button in the completion dialog.

__46.

Leave the Transaction List window open so you can easily access it in future steps. If you close
the window by accident, you can always re-open it by clicking on the Show Probe link.

When you run transactions through the ProductServiceProxy gateway, the probe will capture all the
details about the message.
Now youll tell soapUI to add a digital signature over the body of the request.
__47.

In soapUI, use the same request you did in the previous chapter. Expand the ProductService
project until SOAP request is visible (see below), then double click it to open it.

__48.

Reload the request contents from file c:\labs\requests\soapMsg.xml.

Lab 3: Securing XML Message Content using WS-Security

Page 61

IBM Software

__49.

At the bottom, locate and click the Aut button to reveal the authentication dialog.

__50.

Select the following from the Incoming and Outgoing WSS dropdowns:
__a. In the Outgoing WSS dropdown, select Sign.
__b. In the Incoming WSS dropdown, select Verify.

__51.

Click the Aut button to hide the authentication dialog.

__52.

Click the green submit button to POST the request to your service proxy. The request should
succeed.

__53.

In the Transaction List (probe) window, click the Refresh button so you can see the transaction
that you just posted.

The transaction list should now show the request you just posted. The [+] at the left side of the
magnifying glass indicates that there is an associated response with the request.

Page 62

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__54.

Click on the small [+] to show the response.

__55.

Click on the top (request) magnifying glass to show the execution details for that transaction. At
the top of the displayed window will be a set of icons that represent each action in the rule that
was executed. The main part of the window displays the contents of the INPUT context (the
contents of the message sent by soapUI). Notice that soapUI properly added a digital signature
to the message.

Lab 3: Securing XML Message Content using WS-Security

Page 63

IBM Software

3.2.6

DataPower Contexts

While configuring the various actions (sign, transform, etc.), you may have noticed that each action
declares an input and an output context. In the case of a transform action, the input context will be the
document that is fed to the transformer, and the results of the transformation will be written to the output
context.
Some actions may only have an input context. For example, the verify action has an input context, but no
output context; the signature verification either passes or fails. In contrast, some actions may only have
an output context. The fetch action can fetch an XML document from a local file or a remote server, and
the fetched document becomes the output context. Contexts are referred to by the following names:
INPUT represents the original message as it arrived from the client.
OUTPUT represents the outbound message which will be forwarded to the destination. In

the case of client-to-server processing, the OUTPUT context represents what will be sent
to the backend server. In the case of server-to-client processing, the OUTPUT context
represents what will be returned to the client.
NULL indicates that the output is not needed. In other words, the output from the action

is sent to the bit bucket.


PIPE indicates that the output of the action should be piped into the input of the next

action. In this case, the input context of the next action must also specify PIPE.
Named context in this case, you can assign a name to a context and use it at a later

point in the processing rule. For example, a transform action can be configured with an
input context of INPUT and an output context of newRequest. Later in the processing
rule, another action can use newRequest as the input context.
__56.

Click on the magnifying glass in front of the transform action.

The XML document shown in the window shows what will be fed into the transform action as the
context document. In this case, the message with the digital signature will be the input context to
the transformation.
__57.

Click on the magnifying glass after the transform action (in front of the sign action).

The input to the schema validate action is the results of the prior transform action. In the content
section, notice that the digital signature has been removed.

Page 64

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__58.

Click on the last magnifying glass. It contains the contents of the OUTPUT context, which will be
forwarded to the backend service.

__59.

Close the transaction detail window.

__60.

In the transaction list window, click on the magnifying glass to the left of the response.

The INPUT context shown in the transaction window shows the response that came back from the
backend service.
__61.

Click on the magnifying glass after the transform action. In the content section, you should that
the transformation decoded the encoded description and expanded the benefits list into an XML
nodeset.

__62.

Click on the magnifying glass after the sign action. In the content section, you should see that
the message now contains a digital signature.

__63.

Finally, click on the last magnifying glass. It represents the content that will be returned to
soapUI.

Lab 3: Securing XML Message Content using WS-Security

Page 65

IBM Software

__64.

You can verify that soapUI accepted the digital signature by looking at the soapUI log. At the
bottom of the soapUI window is a button to show the soapUI log.

If soapUI could not verify the signature created by DataPower, the log would contain an error
message.

3.3

WS-Security Encryption & Decryption

Similarly to digital signatures, encryption use PKI keys and certificates for encryption and decryption.
When encrypting a message, the recipient's public key is used; only the private key can decrypt the
message.

3.3.1

Decrypting the request and encrypting the response

In the following steps, youll add the necessary actions to decrypt the request (from soapUI) and then
encrypt the response (going back to soapUI).
__65.

Reopen the policy editor by clicking the ellipsis in the Multi-Protocol Gateway page.

__66.

Drag a decrypt action in front of the verify signature action.

__67.

Double click the decrypt action to provide additional details for its configuration.

__68.

In the Decrypt Key dropdown, select ProductServiceCryptoKey.

__69.

Click Done.

Page 66

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__70.

In the list of configured rules at the bottom of the policy editor, click on the Server to Client rule
to make it the active rule in the editor.

__71.

Drag an Encrypt action to the right of the sign action.

__72.

Double click the encrypt action to complete its configuration.

__73.

In the Configure Encrypt Action form, locate the Recipient Certificate field, then select
SoapUICryptoCert.

__74.

Click the Done button.

__75.

Click the Apply Policy button in the policy editor.

__76.

Click the Close Window link in the upper right of the policy editor.

__77.

In soapUI, click the green submit button to test your service gateway.
If you inspect the response closely, youll notice that the contents of the SOAP Body are
completely encrypted.

You just verified that DataPower is signing and encrypting the response. Now configure soapUI to
sign+encrypt the request, and decrypt+verify the response.
__78.

In soapUI, click on the Request tab to make it the active tab.

__79.

Click the Aut button to show the authorization security settings. If the soapUI log is still visible,
you may want to hide that too.

__80.

For Outgoing WSS, select: SignAndEncrypt

Lab 3: Securing XML Message Content using WS-Security

Page 67

IBM Software

__81.

For Incoming WSS, select: DecryptAndVerify

__82.

Click the Aut button to hide the authorization security settings.

__83.

Click the green submit button to submit the request to ProductServiceProxy. Look closely at the
response. This time, soapUI was able to decrypt the contents of the SOAP body.

__84.

Look back at the probe window; click the Refresh button. You should see two transactions in the
list. Feel free to inspect the new transactions that include the encryption steps.

3.3.2

Field Level Encryption

In the previous steps, you saw how to encrypt the entire SOAP body. In some circumstances, it may be
preferable to encrypt only specific elements.
Now youll modify the encrypt action so that only the <brand> tag will be encrypted.
__85.

Reopen the policy editor by clicking on the ellipsis button in the Multi-Protocol Gateway Policy
field.

__86.

In the configured rules section at the bottom, click on the Server to Client rule to make it the
active rule in the editor.

__87.

Double click the encrypt action to open its configuration settings.

__88.

In the Message Type section, choose Selected Elements (Field-Level). When you make this
selection, a new field, Document Crypto Map will appear.

The Document Crypto Map is used to tell the encrypt action which element(s) are to be encrypted. Since
the document will be in XML, the most natural way of selecting the target elements is with XPath
expressions. The Document Crypto Map represents a collection of XPath expressions which identify the
elements to be encrypted.
__89.

Click the plus (+) button next to the Document Crypto Map dropdown.

__90.

For the Name field, type: MyCryptoMap

__91.

For the Operation, make sure Encrypt (WS-Security) is selected.

__92.

In the XPath Expression field, type: //*[local-name()='benefits']

__93.

Click the Add button to add this XPath to the list of expressions.

__94.

Click the Apply button.

Page 68

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__95.

Click the Done button in the Configure Encrypt Action window.

__96.

Click the Apply Policy button in the policy editor.

__97.

Click the Close Window link to close the policy editor.

__98.

In soapUI, click the green submit button to POST the request to the ProductServiceProxy
gateway.
Since soapUI is configured to decrypt the message, you wont have much proof that DataPower
only encrypted the <benefits> element. You can verify this in two ways:
__a. Look at the transaction probe, in the response rule, look at the contents of the OUTPUT
context (the last magnifying glass) to see what is being returned to soapUI. There you will
see that the <benefits> element has been encrypted but the other elements are not.
__b. Modify soapUIs authentication settings by changing the incoming WSS security to either
verify or blank. This will prevent soapUI from decrypting the response.

__99.

Click the Apply button in the main Multi-Protocol Gateway configuration form.
Applying changes disables the probe.
In order to preserve system resources, the probe is
automatically disabled after pressing the Apply button in the
main Multi-Protocol Gateway configuration window.

__100. If your configuration is working properly, click the Save Config link to persist your configuration to
the flash memory.

Lab 3: Securing XML Message Content using WS-Security

Page 69

IBM Software

3.4

Summary

In this lab, you saw a variety of ways in which WebSphere DataPower appliances can help secure data
using its cryptographic capabilities. You learned:
How crypto certificates and crypto keys are used to dereference key and certificate files

for maximum flexibility and ease of maintainability.


Crypto keys and certificates are used when creating and verifying digital signatures, as

well as during encryption and decryption.


You can add a digital signature to an XML message simply by dragging a sign action onto

the processing rule and identifying which key to use.


Field level, as well as message level encryption and decryption can be performed without

sacrificing performance as a result of hardware encryption technology.


The transaction probe is a powerful tool that allows you to visually inspect every aspect of

a transaction, helping to identify configuration or communication problems.

Page 70

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 4

Access Control Framework

Prerequisites: This lab requires the completion of labs 1 through 3.


Up until now, youve seen how WebSphere DataPower can protect XML Web traffic using built-in XML
threat protection, digital signatures, and encryption. This lab will introduce the access control framework
which provides authentication, authorization, and audit services. Collectively, this is referred to as AAA.
An AAA policy identifies a set of resources and procedures used to determine whether or not a
requesting client is granted access to a specific service, file, or document. AAA policies are thus filters in
that they accept or deny a specific client request. Basic AAA processing is depicted in the figure below.

Extract identity & extract resource


The first action that occurs is to extract the claimed identity of the service requester and the requested
resource from an incoming message and its protocol envelope. WebSphere DataPower appliances
provide an extensive list of predefined identity and resource extraction methods. For example, the
identity can be based on IP address, account name/password, SAML assertion, or other criteria, while
the requested resource can be specified by (among others) an HTTP URL, a namespace, or a WSDL
method.

Authenticate
If the identity is successfully extracted from the message, it will then be authenticated. Authentication is
most commonly accomplished via an external service such as Tivoli Access Manager or LDAP. If the
authentication is successful, the process enters the resource and credential mapping phase.

Lab 4: Access Control Framework

Page 71

IBM Software

Credential and resource mapping


Successful server-based authentication generates a set of credentials attesting to the service requesters
identity. These credentials can then be mapped into another set more appropriate for the authorization
method selected. In addition, the extracted resource name can also be optionally mapped to something
more appropriate for the authorization method selected.
The resulting credentials, along with the resulting resource name, form the basis for client authorization,
which determines if the now identified client has access to the requested resource.

Authorize
Like authentication, authorization is most commonly accomplished via an external policy server such as
Tivoli Access Manager or an LDAP. The result of the authorization phase is to either allow or deny the
request to proceed.
If either authentication or authorization denies access, the system generates an error which is returned to
the calling entity. This error may be handled, as with any other errors within multi-step processing, by an
on-error action or an error rule. Either method allows for the creation of custom error messages.

Audit & accounting


The final phase of the AAA policy performs auditing and security mediation tasks such as converting
between WS-Security UsernameToken element and Kerberos/SPNEGO. This phase has the ability to
generate various types of security tokens, including Kerberos/SPNEGO, LTPA, and SAML assertions. A
stylesheet can also be identified for execution to do any custom auditing tasks.

4.1

LDAP authentication

In this section, youll add an AAA action to your processing rule to authenticate requests against an
LDAP.
__1.

Re-open the policy editor by clicking on the ellipsis button in the Multi-Protocol Gateway Policy
field.

__2.

In the Client-to-Server rule, drag an AAA action and drop it after the initial match action.

Page 72

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__3.

Double click the yellow outlined AAA action to configure it.

__4.

The AAA processing action references an AAA Policy. Click the plus (+) sign next to the
AAA Policy dropdown to create a new AAA policy.

__5.

For the AAA Policy Name, type: MyAaaPolicy

__6.

Click the Create button.

The next page identifies how to extract the users identity (and optionally password) from the message.
For this exercise, well indicate that the identity will be in a WS-Security Username Token element.
__7.

Select: Password-carrying UsernameToken Element from WS-Security Header.

__8.

Click the Next button.

Now youll identify how to authenticate the user.


__9.

Select: Bind to Specified LDAP Server. When you make the selection, LDAP specific
configuration parameters will be displayed.

__10.

In the Host field, type: demoserver

__11.

Change the LDAP version to: v3

__12.

In the LDAP Suffix field, carefully type: ou=members,ou=datapower,dc=ibmdemo,dc=com

__13.

Click the Next button.

Now you will define how to extract the resource. Since the message is a SOAP request, you can expect
that the first element in the SOAP body contains the operation being requested. In XPath terms, this is
referred to as the Local Name of the Request Element.
__14.

In the Extract Resource form, check: Local Name of Request Element

__15.

Click the Next button.

__16.

For the authorization phase, leave the default set to: Allow Any Authenticated Client.

__17.

Click the Next button.

The last page of the AAA policy configuration wizard gives you the options of performing various post
processing tasks. One powerful post-processing task is to perform security protocol mediation such as
creating a Kerberos/SPNEGO token or generating a signed SAML assertion. For this lab, just leave
everything with the default values.
__18.

Click the Commit button to save the new AAA policy.

__19.

Click the Done button to dismiss the success window.

__20.

Make sure MyAaaPolicy is selected in the AAA Policy field, and then click Done.

Lab 4: Access Control Framework

Page 73

IBM Software

__21.

In the policy editor, click the Apply Policy button.

__22.

Click the Close Window link to close the policy editor.

__23.

Click the Apply button in the Multi-Protocol Gateway configuration page.

__24.

In the soapUI, click the green submit button to submit the request to your service. The request
should now fail with an error message of Rejected by policy. To resolve this, you need to tell
soapUI to include the WS-Security Usernametoken.

__25.

In soapUI, make sure the request tab is selected then click the Aut button to show the
authentication settings.

__26.

Change the Outgoing WSS dropdown to be UsrtokenSignEncrypt.

__27.

Click the Aut button to close the authentication settings.

__28.

Click the green submit button to submit another request to the service. This time, the request
should succeed. If you want to see the WS-Security UsernameToken that soapUI injected into
the message, you can use the probe to inspect the transaction.

__29.

If you want to see the AAA policy reject a bad password, follow these steps:
__a. In the soapUI request tab, click on the Aut button to show the authentication settings.
__b. Select BadPassword_UNT from the Outgoing WSS dropdown the password is incorrect
for user david.
__c. Click the Aut button to hide the authentication settings.
__d. Click the green submit button to submit the request. The request should fail with the
Rejected by policy message.
__e. Restore the Outgoing WSS setting back to UsrtokenSignEncrypt and verify that the
request succeeds (this is important for future labs).

__30.

If your configuration is working properly, you can click the Save Config link in the upper right part
of the DataPower banner. This will save your configuration to the flash memory.

4.2

Summary

In this lab, you saw how you can further secure your services with DataPowers access control
framework. You learned:
Access Control Policies, also known as AAA policies, are a powerful and flexible way to

prevent unauthorized access to your services. Through the point-and-click WebGUI, you
can easily configure access policies to contact external authentication and policy servers.
AAA policies can also do security mediation, such as converting between HTTP Basic

Authentication and Kerberos/SPNEGO. AAA policies can also create a SAML assertion
based on authenticated credentials extracted from the message.

Page 74

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 5

Securing with SSL (Optional lab)

Prerequisites: This lab requires the completion of labs 1 through 4.


The final steps in this section show how you can easily secure your multi-protocol gateway service using
mutual (two-way) SSL.

The basic process involves adding an HTTPS Front Side Handler to your multi-protocol gateway. The
primary difference between an HTTP and HTTPS front side handlers is that the HTTPS FSH requires an
SSL Proxy Profile object.

The preceding image shows the relationships of various crypto objects that work together to provide
mutual SSL services.

Lab 5: Securing with SSL

Page 75

IBM Software

An SSL Proxy Profile is used as a way of configuring SSL connection details such as caching, direction
(forward, reverse, two-way), and authentication requirements. The SSL Proxy Profile leverages various
other objects that all work together during and after SSL handshaking:
Crypto Profile used to associate a Crypto ID Credential and a Crypto Validation

Credential together in one convenient reusable object. Also defines acceptable ciphers for
encryption.
Crypto ID Credential - during SSL negotiation, it may be necessary for a DataPower

service to provide a certificate that represents its identity to the client. A Crypto ID
Credential will act as this part of the SSL handshake equation. The Crypto ID Credential
will contain both a private key and a public certificate that identifies your service.
Crypto Validation Credential used to define which certificates are acceptable from the

peer during SSL negotiation. If the peers certificate does not exist in the Crypto Valcred,
the connection will be rejected. The validation credential is optional and if not specified,
would result in a one-way SSL negotiation. In other words, DataPower will present its
public certificate to the peer as its identity, but would not require the peer to present a
certificate back.
This may seem like a lot of pieces to configure, but keep in mind that a single WebSphere DataPower
appliance can host multiple services and may need to have multiple identities. This object relationship
provides the maximum flexibility and object re-use.

5.1.1

Create the Crypto Identification Credential

__31.

In the navigation search box, type id crypto, then from the search results, locate and click
Crypto Identification Credentials.

__32.

Click the Add button.

__33.

In the Name field, type: ProductServiceIdCred

__34.

In the Crypto Key dropdown, select: ProductServiceCryptoKey

__35.

In the Certificate dropdown, select: ProductServiceCryptoCert

__36.

Click the Apply button to create the Crypto Identification Credentials.

5.1.2

Create the Crypto Profile

The crypto profile object will now tie together the crypto identification credential and the crypto validation
credential to form a relationship between the two.
__37.

Using either the search results or by starting a new search, locate and click Crypto Profile.

__38.

Click the Add button.

__39.

In the Name field, type: ProductServiceCryptoProfile

__40.

In the Identification Credentials dropdown, select: ProductServiceIdCred

__41.

In the Validation Credentials dropdown, select: ProductSvcConsumersValcred

Page 76

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__42.

5.1.3

Click the Apply button to save the Crypto Profile.

Create the SSL Proxy Profile

The SSL profile object provides the SSL-specific configuration parameters, and references the crypto
profile for any required crypto keys and certificates.
__43.

Using either the navigation search box or the navigation tree, locate and select SSL Proxy
Profile.
If you use the search box, you can type ssl.
If you use the navigation tree, you will find it under: ObjectsCrypto Configuration.

__44.

Click the Add button.

__45.

In the Name field, type: ProductServiceSslProxyProfile

__46.

In the Reverse (Server) Crypto Profile dropdown, select: ProductServiceCryptoProfile

__47.

Click the Apply button to save the new SSL Proxy Profile.

__48.

Click the Control Panel link to redisplay the control panel.

5.1.4

Create an HTTPS Front Side Handler

The final steps are to create the HTTPS front side protocol handler and add it to the multi-protocol
gateway service. The HTTPS front side handler will identify which SSL Proxy Profile to use as well as a
TCP port for communications.
__49.

Click the Multi-Protocol Gateway icon.

__50.

Click ProductServiceProxy to open the configuration for your multi-protocol gateway service.

__51.

In the Front Side Protocol field, click the plus (+) button to create a new front side protocol
handler.

__52.

From the pop-up menu, select HTTPS (SSL) Front Side Handler

__53.

In the Name field, type: HTTPS_443nn where nn is your student number.

__54.

In the Port field, type: 443nn where nn is your student number.

__55.

Towards the bottom of the configuration window, locate the SSL Proxy field and select
ProductServiceSslProxyProfile from the dropdown list.

__56.

Click the Apply button to save the front side handler configuration.

__57.

Click the Apply button at the top of the Configure Multi-Protocol Gateway form.

Lab 5: Securing with SSL

Page 77

IBM Software

The configuration is complete. Now your multi-protocol gateway service is listening on two ports, one
being HTTP and the other HTTPS.

__58.

In soapUI, from the endpoint dropdown list, select the HTTPS endpoint
https://datapower:443nn/ProductService/ProductService.

__59.

Change the port number so it includes your student number.


__a. Dropdown the list again, but this time select: [edit current]
__b. Edit the port, replacing nn with your student number, then click OK

__60.

Perform a test to show ProductServiceProxy is now accepting SSL connections:


__a. In the Request Properties section of soapUI (bottom left section of the soapUI window),
locate SSL Keystore, then from its dropdown list, select: soapUI.jks. This will cause
soapUI to use that keystore when establishing an SSL connection with your proxy service
(on DataPower). If you gont see the request properties make sure the SOAP request is
highlighted in the project tree (Projects->ProductService->ProductServiceSOAP->SOAP
request).

__b. Click the green submit button to POST the request using SSL. The request should succeed
as it did earlier.

Page 78

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__61.

Perform a test to show that ProductServiceProxys SSL is mutual, and that it will only trust
connections from peers whose certificate is included in ProductSvcConsumersValcred.
__a. In the Request Properties section, change the SSL keystore to: untrustedpeer.jks.
__b. Click the green submit button to POST the request using SSL. The request should fail. If
you examine the DataPower system log (accessible from the control panel), you will see
something similar to the following screen capture.

__62.

If your configuration is working properly, click the Save Config link in the upper right corner of the
window to save your configuration to the flash memory.

Lab 5: Securing with SSL

Page 79

IBM Software

5.2

Summary

In this lab, you learned:


SSL leverages several reusable crypto objects and is easily applied to a service by simply

assigning an SSL Proxy Profile to an HTTPS front side handler.


A Multi-Protocol Gateway service object can have more than one front side handler.

Page 80

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 6

Protecting Web Services

Prerequisites: This lab requires the completion of labs 1 through 4.


With the wide-spread adoption of Web services, it has become essential to not only protect Web services
from malicious attacks, but also adhere to standards and specifications (also referred to as WS-*) that
help to assure interoperability while maintaining quality of service levels. The continuous evolution of
WS-* specifications adds an additional challenge to developers.
In this lab, youll learn about the Web Service Proxy, a service object designed specifically to provide
Web services with a centralized location for:
Protection against malicious threats.
Web service definitions (WSDL).
Request authentication and authorization.
Enforcement and compliance of WS-* specifications.
Virtualization of service endpoints.
Application of processing rules and policies.
Application of WS-Security such as encryption and digital signatures.
Enforcement of service level agreements and quality of service.
Web service governance.

6.1

Web Services and WSDLs

A Web service is defined as a self-describing, standalone application that can be consumed by other
applications. Web services use Web Services Description Language (WSDL) to provide the consumer
with the essential details associated with its usage. A WSDL document is generally available to the
consumer, and is used when developing clients that use the service.
The Web Service Proxy (WS Proxy) object fully understands Web Services Description Language. In
fact, a fully functional WS Proxy can be configured simply by providing it with a WSDL document. Once
configured, additional processing requirements and quality of service parameters can be easily
configured using the WebGUI.

6.1.1

WSRR and UDDI Integration

The central element to the configuration of a WS Proxy service is one or more WSDLs. There are several
ways of which a WS Proxy service can gain access to a Web services WSDL:
The WSDL document can be uploaded into the flash-based file system.
The WSDL can be referenced via a URL, such as http://myservice.com/service?WSDL
The WS Proxy can subscribe to a centralized repository such as WebSphere Service

Registry and Repository (WSRR) or a Universal Description Discovery and Integration


(UDDI) server.

Lab 6: Protecting Web Services

Page 81

IBM Software

Using a WSDL repository such as WSRR or UDDI has some distinct advantages. When using a
repository, the WS Proxy service subscribes to a WSDL and periodically checks for service definition or
policy updates. When a new WSDL becomes available, the WS Proxy will obtain it and automatically
reconfigure itself based on the new WSDL.

6.2

About the Web Service

For this lab, youll be protecting a Web service that


provides flight calculations similar to an E6B Flight
Computer. An E6B is a form of circular slide rule used
in aviation. E6Bs are mostly used in flight training, but
many pilots still carry them. Theyre used to aid in
calculating fuel burn, wind correction, time en route,
and other flight-related values. In the air, the flight
computer can be used to calculate ground speed as
well. The back side is designed for wind correction
calculations (determining how much the wind is
affecting one's speed and course).
There are three operations in the Web service:
CalculateFlightLeg given a set of input

parameters, this operation will calculate


elapsed time, fuel required, ground speed
and true heading.
CalculateHeadCrossWind given the wind direction, wind speed, and take-off runway

number, this operation will calculate the headwind and crosswind strengths at take-off.
CalculateCloudBase given the temperature and dew point, this operation will calculate

the altitude of the base of cumulus clouds.

6.3

Verify the Service is Available

Before creating the configurations to protect the service, you can test the service to make sure its up and
running. First, youll request the services WSDL from the actual service.

Page 82

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__1.

Open a new browser window and enter the following URL:


http://demoserver:9080/E6BService/E6BService?WSDL
You should see the WSDL similar to the following image.

If the service returned its WSDL, you know the service is up and running. Now you can submit a SOAP
request to test the service.
__2.

If not already running, locate and launch the soapUI application.

__3.

In the project tree, expand the E6BService project until the CalculateCloudBase requests are
visible (see below).

__4.

Double click Request to open the request window.

__5.

In the upper right corner of the soapUI window, click the maximize button to enlarge the request
window.

Lab 6: Protecting Web Services

Page 83

IBM Software

__6.

In the endpoint dropdown, select: http://demoserver:9080/E6BService/E6BService

__7.

Make sure that the <temperature> and <dewpoint> elements contain integer values. They should
default to temperature 80 and dewpoint 40.

__8.

Click the green submit button to POST the CalculateCloudBase request to the actual
E6BService.

__9.

If everything is working properly, the response window should show the SOAP response that
came back from the Web service. If you submitted 80 and 40 for temperature and dew point, the
service should respond with a cloud base altitude of 9090 feet.

If you did not receive a response, or you receive a SOAP fault, ask the instructor for additional help in
troubleshooting your server connectivity.

6.4

Defining the WebSphere Service Registry and Repository Server

For this Proof of Technology, the instructors workstation (demoserver) has a running instance of
WebSphere Service Registry and Repository. The WSDL for the E6B service has been uploaded and
published into the registry. When you create your Web Service Proxy object, youll configure it to obtain
the WSDL from the registry. Therefore, youll first need to configure a WebSphere Service Registry and
Repository connection object. Youll do that in the following steps.
__10.

In the DataPower navigation search box, type: wsrr

__11.

Locate and select: WSRR Server

__12.

Click the Add button to create a new WebSphere Service Registry and Repository server
connection.

__13.

For the Name field, type: MyWsrrServer

__14.

In the SOAP URL field, make the following changes.


__a. Change https to: http (make sure to remove the s).
__b. Change host to: demoserver
__c. Change the port number to: 9080
The final URL should be: http://demoserver:9080/WSRRCoreSDO/services/WSRRCoreSDOPort

__15.

In the WSRR Server Version, select: 7.5 or later

__16.

Click the Apply button to create the server connection object.

__17.

Verify that the Op-State shows up as seen following:

Page 84

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

6.5

Creating the Web Service Proxy

The first step in create a Web Service Proxy object is to give it a WSDL. For this lab, the WSDL will be
obtained from a registry (WebSphere Service Registry and Repository). In the following steps, youll
create a subscription to WebSphere Service Registry and Repository to obtain the E6B Service WSDL.
__18.

Click on the Control Panel link to display the control panel.

__19.

Click on the Web Service Proxy icon. It is located on the top row of service icons.

__20.

Click the Add button to create a new Web Service Proxy object.

__21.

In the Web Service Proxy Name field, type: E6BServiceProxy

__22.

Click the Create Web Service Proxy button.

__23.

Under the WSDLs heading, locate and click the mini tab labeled: Add WSRR Subscription

__24.

Under WSRR Subscription Name header, select New and type: E6BServiceSubscription

__25.

Leave the Subscription Object field as: WSDL Document

__26.

In the Object Name field, type: E6BService.wsdl


Important!
In the next step, the Namespace is case sensitive and
must be identical as shown. Dont forget the trailing slash
at the end of the namespace!

__27.

In the Namespace field, type: http://www.ibm.com/datapower/E6BService/

__28.

In the WSRR Server dropdown, select: MyWsrrServer

__29.

At the bottom of the form, click the Next button.

Lab 6: Protecting Web Services

Page 85

IBM Software

6.5.1

Defining Local Connection Details

Now youll define how clients will connect to the Web Service Proxy. Youll do this the same way you did
in previous labs when you created an HTTP front side handler (FSH).
__30.

In the Local settings box, click the plus (+) button in the Local Endpoint Handler column to create
a new front side handler.

__31.

In the pop-up list of protocol types, select: HTTP Front Side Handler

__32.

In the Name field, type: HTTP_445nn where nn is your student number.

__33.

In the Port Number field, type: 445nn where nn is your student number.

__34.

In the Allowed Methods and Versions section, click the checkbox to enable GET method.
By default, the HTTP GET verb is disallowed since Web services involve POSTing SOAP
requests. However, in a subsequent step, youll submit a GET to the service in order to see its
WSDL; therefore you need to enable the HTTP GET verb.

__35.

Click the Apply button to create this HTTP FSH.

The 2nd column labeled URI is used to specify what the inbound URI should be for the service. By
default, this is taken from the WSDL; however you can override the URI with a totally different URI for
client requests, thus hiding the actual service URI.
__36.

Page 86

Click the Add button to add the front side configuration to the Web Service Proxy.

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

6.5.2

Defining the Remote Server Details

The final step is to define details associated with the actual backend service. By default, all of the details
will be derived from the retrieved WSDL; however, you do have complete flexibility to override the
backend hostname, port, and remote URI if necessary.

__37.

Click the Next button.

Your service is now created and ready to use. First, verify that everything is up and that the WSDL was
successfully retrieved.
__38.

Towards the middle of the page, verify that the WSDL Status section shows: Okay

__39.

At the top right section of the page, click on the View Operations link to show the details
pertaining to the service operations.

A window will open showing you details about the three operations available in the E6BService.
__40.

6.5.3

Click the close button to close the pop-up window.

Turn on the Transaction Probe

__41.

At the top right section of the page, click on the Show Probe link to open the probe window.

__42.

Click the Enable Probe button to turn on the probe.

__43.

Click the Close button to dismiss the success window.

Lab 6: Protecting Web Services

Page 87

IBM Software

6.5.4

Execute the Service from soapUI

Before you submit another transaction, youll need to change and edit the endpoint that points to
datapower instead of demoserver.
__44.

In the soapUI window, click the endpoint dropdown list and select the datapower:445nn URL to
make it the current endpoint.

__45.

Update the port number with your student number.


__a. Dropdown the endpoint list again and select: [edit current]
__b. Replace the nn with your port number, then click OK.

__46.

Click the green submit button to submit the request to the service. The service will receive the
request, perform XML security checks on the message (schema validation, XML threats, etc.),
then forward the message to the actual E6BService running on demoserver.

You should see a response in the soapUI response pane.


__47.

In the Transaction Probe window, click the Refresh button. If the transaction was successful, it
should appear in the probe similar to the following image:

__48.

Clicking on the little [+] sign next to the magnifying glass will expand the transaction to show the
response. You learned how to use the transaction probe in a previous lab, so feel free to
investigate the different details, headers, etc., about the request and response.

__49.

Close any open browser windows except the main WebGUI.

Page 88

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

6.6

WS-SecurityPolicy

On its own, a WSDL is capable of fully describing a service and its various operations. A consumer can
easily obtain a WSDL and create client code that would know first-hand how to communicate with the
service. The WSDL, however, is not capable of informing the consumer precisely what type of message
or transport level security is required to access the service. WS-Policy and WS-SecurityPolicy were
conceived to solve this problem.
WS-Policy defines a framework for allowing Web services to express their constraints and requirements.
WS-SecurityPolicy expresses security requirements using the WS-Policy framework. For example,
consider a Web service that requires all inbound requests to contain a WS-Security header that contains
a UsernameToken element. This requirement cannot be described in the WSDL. If a consumer were to
inspect the WSDL, they would have no way of knowing the security requirements imposed on the Web
service. This information would have to be conveyed either in embedded comments, or in person-toperson correspondence (documentation, phone, e-mail, etc.). WS-SecurityPolicy provides a way of
expressing these requirements.
WS-SecurityPolicy is not restricted to only service requests; it can also describe constraints and
requirements for responses. For example, WS-SecurityPolicy can dictate that all responses are digitally
signed or encrypted.

6.6.1

Embedded vs. Attached Policy

There are two ways of enforcing WS-SecurityPolicy on a Web service. The first and most obvious way
would be to modify the WSDL to include the WS-SecurityPolicy assertions. In this way, the policy
becomes one and the same with the WSDL. This is referred to as an embedded policy.
There may be times when the WSDL cannot be modified, or a single policy should be applied to many
services (or operations within a service). In this situation, a separate WS-SecurityPolicy document can
be attached to an existing WSDL.

6.6.2

Enforce vs. Filter

There are two ways in which policies can be applied:


Enforce mode The policy will be enforced, and if the policy requirements arent satisfied,

an attempt will be made to satisfy them. If the policy requirements cannot be satisfied, the
message will be rejected.
For requests, all policy requirements must be met; No attempt to satisfy them will be

made. For example, if the policy states that inbound messages must contain a
WS-Security UsernameToken element, and the request does not contain it, the
request will be rejected.
For responses, an attempt will be made to satisfy the requirements if the backend

server did not. For example, if the policy states that all responses must be digitally
signed, but the server returned a response that is not signed, a signature will be
added to the response before it is returned to the client.
Filter mode the policy will be enforced. If the policy requirements arent satisfied, the

message will be rejected.


Requests and responses are handled the same. If the request or the response does

not meet the policy requirements, the entire transaction will be rejected.

Lab 6: Protecting Web Services

Page 89

IBM Software

Earlier in this lab, you configured a WS Proxy service to obtain the E6BService WSDL from the service
registry (WebSphere Service Registry and Repository). A WS-Policy attachment has also been uploaded
into WebSphere Service Registry and Repository and attached to the E6BService WSDL. You can see
the attached policy by fetching the WSDL from your DataPower E6BServiceProxy (not the original
demoserver E6BService, as it does not have any policy attached to it).
__50.

Open a new browser window and navigate to the following URL (insert your student number):
http://datapower:445nn/E6BService/E6BService?WSDL
The services WSDL should be displayed in the browser window. Scroll towards the end of the
WSDL (or use the browsers find function) and locate the <wsp:Policy> element. The WSDL
is being returned from the WS Proxy service, not the actual service on demoserver. The
E6BServiceProxy fetched the WSDL and the Policy and combined them together. You can verify
this by retrieving the WSDL directly from the service and comparing it to the one generated by
the E6BServiceProxy (see step 1 of this lab).

6.6.3

UsernameToken Policy

The CalculateHeadCrossWinds operation has the WS-SecurityPolicy attached to it. The policy specifies
that requests must include either a version 1.0 or a version 1.1 UsernameToken element in the
WS-Security header. The policy looks similar to the following listing:

Page 90

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Testing Policy Enforcement UsernameToken


__51.

In the soapUI E6BService project, locate CalculateHeadCrossWind, then double click the
request labeled: Request

__52.

Make sure the request has valid parameters: WindSpeed is 15, WindDirection is 45, and
RunwayNumber is 1.

__53.

Also, verify that the endpoint selected is still http://datapower:445nn/E6BService/E6BService

__54.

Click the green submit arrow to submit the request. The request should FAIL because it
does not have a WS-Security UsernameToken as required by the WS-SecurityPolicy. The fault
string should read: Rejected by policy. (from client)

Adding the WS-Security UsernameToken to the Request


SoapUI has the ability to add a WS-Security UsernameToken to the request, thus satisfying the policy
requirements. However, youll still need to make a few additional configuration changes to make
everything work properly.
Adding the UsernameToken to the request only satisfies the policy requirements; it

doesnt actually authenticate the user. To authenticate the request, youll add the
previously created AAA policy to the WS-Proxy object so that it will authenticate the user
credentials found in the UsernameToken.
The backend service is not expecting a UsernameToken and will thus complain about it.

Youll add a transform step that will strip the UserName token from the request before
forwarding it to the backend service.

Lab 6: Protecting Web Services

Page 91

IBM Software

6.6.4
__55.

Adding Authentication for CalculateHeadCrossWind


In the WS-Proxy configuration page, click on the Policy tab.

The Policy page allows you to define custom rules that are applied at various levels in the service. For
example, you can create a rule that will apply to all operations in the WSDL, or you can create a rule
specific to just one operation. Rules are created exactly the same way as you did in the previous labs.
__56.

Page 92

In the WSDL Policy Tree Representation section, expand all of the nodes until all port operations
are visible (see below).

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__57.

Locate the CalculateHeadCrossWind operation and then click the Processing Rules button.

__58.

Specify that this rule should only be executed on inbound requests (client to server).
__a. Click on the New Rule button to create a new rule for this policy.
__b. In the Rule Direction dropdown, select: Client to Server

__59.

Drag an AAA action after the match rule.

__60.

Double click the yellow outlined AAA action to complete its configuration.

__61.

In the AAA Policy dropdown, select the previously created AAA policy: MyAaaPolicy

__62.

Click the Done button to save the AAA action.

Lab 6: Protecting Web Services

Page 93

IBM Software

6.6.5

Removing the WS-Security Header

In the following steps, youll add a transform action that will strip the WS-Security Header so that the
backend server wont complain about it.
WebSphere DataPower appliances come with a library of pre-built XSL stylesheets that perform a variety
of common functions. One of the stylesheets will strip the WS-Security header from a message.
__63.

Drag a transform action onto the rule.

__64.

Double click the yellow outlined transform action to complete the configuration.

__65.

In the Transform field:


__a. In the upper dropdown list, select: store:///
__b. In the lower dropdown list, select: strip-security-header.xsl

__66.

Click the Done button.

__67.

At the top of the page, click the Apply button to make these changes active.

__68.

Test the policy with a good username and password:


__a. In soapUI, double click the request labeled: Request_Ariel. This request has been
preconfigured to include a UsernameToken for user ariel with password foobar.
__b. Click the green submit button to post the request to E6BServiceProxy. The request should
succeed.

Page 94

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__69.

Test the policy with a bad password.


__a. In the lower left section of soapUI, in the Request Properties pane, locate the password
and change it to something arbitrary.

__b. Click the green submit button again. This time the request should fail. If youre interested to
see the details of why the request failed, you can look at the transaction probe.

6.7

Service Level Monitoring (SLM)

The service level monitoring facility provides a policy-driven approach to governing web service traffic. At
its simplest level, it allows you to configure thresholds that dictate how many transactions should be
allowed to flow through a service, as well as what action to take should those thresholds be exceeded.
More complex SLM policies can also be defined which have the ability to base activity thresholds on
parameters such as client IP, user identity, and user defined message details to name just a few.
When a threshold is exceeded, the SLM policy can be configured to take one of three actions:
Throttle the request will be rejected.
Shape the request will be queued until the next timeframe window begins. For example,

if the policy says 10 requests per 30 seconds and 11 requests arrive within the first two
seconds, the 11th request will be queued until the next 30 second timeframe begins. Then
it will be processed and forwarded to the final endpoint.
Notify a message will be logged indicating that the threshold was exceeded.

In the following steps, youll configure the CalculateFlightLeg operation to only allow 2 requests per 10
second interval, and throttle any requests that exceed the threshold.

Lab 6: Protecting Web Services

Page 95

IBM Software

__70.

In the WS-Proxy configuration page, click on the SLM Policy tab.

__71.

In the Auto Generated SLM Statements section, expand each level of the tree by clicking the
buttons until the port operations are exposed.

__72.

In the CalculateFlightLeg operation section, click on the Request link, and specify the following
SLM parameters:
__a. Interval: 10
__b. Limit: 2
__c. Action: throttle
__d. Click the Apply button to save the SLM request properties.

__73.

Click the Apply button at the top of the page to apply these changes to the E6BServiceProxy.

__74.

In the soapUI program window, close any open windows and expand the CalculateFlightLeg
operation and then double click Request.

__75.

Make sure that the endpoint shows: http://datapower:445nn/E6BService/E6BService

Page 96

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__76.

Make sure the parameters are valid. You can use the following if they are not automatically filled
in for you:

__77.

Now submit several requests to the web service by clicking the green submit button several
times. Starting with around the 3rd request, you should get a SOAP fault indicating that the
request was rejected by policy. Continue to try submitting requests. Eventually, the 10 second
time window will elapse and requests will be permitted again.

Lab 6: Protecting Web Services

Page 97

IBM Software

6.8

Summary

In this lab, you had a brief introduction to the Web Service Proxy (WSP) and how it can be configured to
protect your web services. You saw how the WSP is self-configuring simply by providing a WSDL, either
through uploading or subscription to a WSDL repository such as UDDI or WebSphere Service Registry
and Repository.
You also learned how a WS Proxy service can understand and enforce WS-Policy, a specification that
helps Web service consumers understand the required policy governing the services usage. Both WSDL
and policy documents can be uploaded into WebSphere Service Registry and Repository and
automatically retrieved by a WS Proxy service through a self-updating subscription.
Finally you saw how WebSphere DataPower appliances can enforce service usage levels through its
SLM facility. Though only a simple SLM policy was demonstrated that limited the request rate, complex
SLM policies can also be defined that consider nearly any aspect of a request when determining whether
or not the request should be processed or rejected.

Page 98

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 7

Authorization with XACML (Optional lab)

Prerequisite: Completion of Labs 1, 2, 3, 4, and 6.


In a previous lab, you created and configured an AAA policy that communicated with an LDAP to do
authentication. In this lab, youll modify that AAA policy to perform authorization using XACML.
The goals of this lab exercise are to:
Gain exposure to DataPowers support for XACML.
Understand the basic fundamentals of XACML based authorization.

XACML, which is short for Extensible Access Control Markup Language, is an OASIS standard that
describes both a policy language and an access control decision request/response language, both which
are encoded using XML.
The policy language is used to describe general access control requirements, and has

standard extension points for defining new functions, data types, combining logic, etc.
The request/response language lets you form a query to ask whether or not a given action

should be allowed. The response always includes an answer about whether the request
should be allowed using one of four values: Permit, Deny, Indeterminate (an error
occurred or some required value was missing, so a decision cannot be made) or Not
Applicable (the request can't be answered by this service).
XACML employs two primary components to carry out authorization requests:
Policy Enforcement Point (PEP), which acts as the gatekeeper and is responsible for

extracting the various bits of information from the inbound request and creating a XACML
authorization request document. The authorization request document contains the subject
(user ID, etc.), the resource (requested URL, SOAP action, etc.) and the action (execute,
read, etc.). The authorization request document is then sent to a policy decision point
which makes the permit or deny decision.
Policy Decision Point (PDP), which acts as the decision maker and contains the enterprise

security policies that govern access to the resource in question. When the XACML
request document arrives, it extracts the subject, resource, and action and determines
whether the user has the necessary privileges. The response is returned in a XACML
authorization response document.

Lab 7: Authorization with XACML

Page 99

IBM Software

There are many existing proprietary and application-specific languages for doing this kind of thing but
XACML has several points in its favor:
It's standard. By using a standard language, you're using something that has been

reviewed by a large community of experts and users, you don't need to roll your own
system each time, and you don't need to think about all the tricky issues involved in
designing a new language. Plus, as XACML becomes more widely deployed, it will be
easier to interoperate with other applications using the same standard language.
It's generic. This means that rather than trying to provide access control for a particular

environment or a specific kind of resource, it can be used in any environment. One policy
can be written which can then be used by many different kinds of applications, and when
one common language is used, policy management becomes much easier.
It's distributed. This means that a policy can be written which in turn refers to other

policies kept in arbitrary locations. The result is that rather than having to manage a single
monolithic policy, different people or groups can manage separate sub-policies as
appropriate, and XACML knows how to correctly combine the results from these different
policies into one decision.
It's powerful. While there are many ways the base language can be extended, many

environments will not need to do so. The standard language already supports a wide
variety of data types, functions, and rules about combining the results of different policies.
In addition to this, there are already standards groups working on extensions and profiles
that will hook XACML into other standards like SAML and LDAP, which will increase the
number of ways that XACML can be used.

7.1

The XACML Policy Document

The XACML policy document describes a security policy and is comprised of a collection of rules, which
either result in a permit or deny decision. Within each rule are targets that contain four sections:
subjects, resources, actions, and conditions. These sections match closely with the details found in a
XACML authorization request. When the authorization request arrives, the subject, resource, and action
are extracted and then looked up within the policy. If the subject is found within the subjects, and the
resource is found within the resource, and the action is found in the actions, and any additional
conditions are met, then the rule will return either permit or deny as specified in the rules effect attribute.
XACML policy documents are not usually coded manually; rather a product such as Tivoli Security Policy
Manager or some other XACML-enabled policy manager will generate the XACML policy document.

Page 100

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

7.2

The XACML Authorization Request Document

When a request arrives at the policy enforcement point, the PEP will create a XACML authorization
request document and send it to the policy decision point (PDP).
The XACML authorization request document contains the subject, resource, and action to be evaluated
by the PDP. The following XACML authorization request is for a subject named david, a resource
named product-info, and an action of execute.
<Request>
<Subject>
<Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:subject:subject-id"
DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>david</AttributeValue>
</Attribute>
</Subject>
<Resource>
<Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:resource:resource-id"
DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>product-info</AttributeValue>
</Attribute>
</Resource>
<Action>
<Attribute
AttributeId="urn:oasis:names:tc:xacml:1.0:action:action-id"
DataType="http://www.w3.org/2001/XMLSchema#string">
<AttributeValue>execute</AttributeValue>
</Attribute>
</Action>
<Environment/>
</Request>

Lab 7: Authorization with XACML

Page 101

IBM Software

7.3

XACML and WebSphere DataPower

WebSphere DataPower has the ability to act as both the policy enforcement point and the policy decision
point. As a policy enforcement point, an AAA action is used to extract the credentials and resource
information from a request and create a XACML authorization request document. The AAA policy will
then send that authorization request document to a XACML policy decision point.
In the following diagram, WebSphere DataPower receives requests from a client, extracts the credential
and resource details, then creates and sends a XACML AuthZ request document to the PDP. The PDP
responds with a XACML AuthZ response document. WebSphere DataPower interprets the response and
either allows or denies the request accordingly.

Since WebSphere DataPower supports XACML policy documents, it can act as a PDP as well. The
following diagram shows how WebSphere DataPower can act as a PDP for many XACML PEPs. When
WebSphere DataPower receives an XACML AuthZ request, it makes the decision based on a cached
XACML policy document and responds accordingly.
= XACML AuthZ Req/Rsp

PEP
PEP
PEP

PEP

Policy Decision Point

XACML Policy
Document (cached)

Page 102

Policy Server

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

WebSphere DataPower can also act as both a PEP and a PDP. In the following diagram, WebSphere
DataPower fetches and caches the XACML policy document from the policy server. When requests
arrive, WebSphere DataPower can make the allow/deny decision independently without additional
communications.

7.4

How its done

The process begins with an AAA policy. As youve seen in previous labs, the AAA policy allows you to
specify exactly how to extract the subject and resource from an inbound request. Once the subject and
resource have been identified, DataPower will create a XACML authorization request document (using
XSLT). That request will be sent to the designated PDP (that youll be creating). This is a simple process
that only requires uploading the XACML policy file.
First, create the Policy Decision Point.
__1.

In the navigation search box, type: xacml

__2.

From the search results, select: XACML Policy Decision Point

__3.

In the Configure XACML Policy Decision Point page, click the Add button.

__4.

In the Name field, type: MyXacmlPDP

__5.

In the General Policy File field, type: local:///xacml-policy.xml


Make sure you type this exactly as shown, with three slashes and all lowercase letters. This file
was uploaded in lab 1.

__6.

Click the Apply button to create the XACML PDP.

Now youll modify the MyAaaPolicy to add authorization using XACML. Your AAA policy will be
configured as follows:
Extract user identity and password from a WS-Security UsernameToken.

Lab 7: Authorization with XACML

Page 103

IBM Software

Authenticate the identity by attempting to bind to an LDAP with the extracted credentials.
Determine the resource by looking at the name of the request element (this is essentially

the SOAP action).


Authorize the request by allowing any authenticated client this is the same as not doing

any authorization.
__7.

In the navigation search box, type: aaa

__8.

From the search results, select: AAA Policy

__9.

In the list of AAA policies, select MyAaaPolicy.

__10.

On the Authorize tab, make the following changes:


__a. Method: Use XACML Authorization Decision
__b. Policy Decision Point: MyXacmlPDP
__c. Custom Stylesheet to bind AAA and XACML:
__i.

Upper dropdown, select: local:///

__ii.

Lower dropdown, select: xacml-request-binding.xsl

The xacml-request-binding.xsl stylesheet will generate the XACML Authorization Request document that
will be sent to the PDP. The stylesheet takes the subject and resource that were extracted in the
previous AAA steps, and inserts them into the appropriate parts of the authorization request document.
__11.

Click the Apply button to save the changes to MyAaaPolicy.

Youre just about ready to test the service. Lets flush the probe of any previous transactions so that the
following requests will be easy to see.
__12.

Click on the Control Panel link to show the main DataPower control panel.

__13.

On the 2nd row of icons, locate the Troubleshooting icon and click it.

__14.

From the top row of tabs, click on the Debug Probe tab.

__15.

In the Web Service Proxy section, locate E6BServiceProxy and then click on the magnifying
glass to show the probe.

__16.

Click the Flush button to clear out the old transactions. Leave the probe window open so that
you can easily find it.

Page 104

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__17.

In soapUI, expand the CalculateHeadCrossWind operation. You should see four pre-populated
requests with names such as Request_David, Request_Sarah, etc. For your convenience, the
username and password have already been specified in these requests.

The following details are important to know before testing MyAaaPolicy:


The LDAP is setup with four users: david, sarah, joshua, and ariel. All four users have a

password of foobar.
The XACML policy document grants execute access to david and sarah for operations

HeadCrossWindDetails, CloudBaseDetails, and product-info. All other users will be


denied.
__18.

Open Request_David and submit it by clicking the green submit button. The request should
succeed.

__19.

In the DataPower probe window, click the Refresh button. You should see a transaction.

__20.

Click the magnifying glass to view the transaction details.

The window shows the contents of the request as it was sent from soapUI. Notice that it contains the
WS-Security UsernameToken.
__21.

Click on the AAA icon to show the details of the AAA action.

Lab 7: Authorization with XACML

Page 105

IBM Software

In the Extension Trace list, there should be three events that occurred:
Ldap-authen this is where the AAA policy contacted the LDAP server to authenticate the

user.
Transform this is where the AAA policy executed the XSL that you uploaded in order to

generate the XACML authorization request document.


Send the XACML authorization request to the XACML Policy Decision Point

__22.

On the MyXacmlPDP row, under the request heading, click (show nodeset). You will see the
completed XACML authorization request document that contains the extracted user, resource,
and action. This is the authorization request that will be sent to the XACML PDP (MyXacmlPDP).

__23.

On the same row, click (show nodeset) under the response heading. This shows the response
that was received from the PDP. In this case, it should say Permit.

__24.

Flush the probe to prepare for testing the unauthorized users.

__25.

In the soapUI window, close any open requests and open Request_Ariel and submit it.

The requests for Ariel should fail. Once again, you can use the probe to inspect the transaction and see
the XACML authorization request and the response. This time, the response should say Deny.
__26.

Click the Save Config link to save all of the changes youve made during this lab exercise.

Page 106

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

7.5

Summary

In this lab exercise, you learned that XACML itself is not a policy server; rather its a standard way of
describing security policies using XML. You learned that a policy enforcement point acts as the
gatekeeper for requests, and that the policy decision point acts as the decision maker as to whether the
request is authorized or not. The PEP will contact the PDP using a predefined XML message that is
described in the XACML specification.
Components that understand XACML are theoretically plug-and-play with each other. A policy
enforcement point is indifferent as to the vendor of the PDP (and visa versa). If a policy server has the
ability to export its policy as XACML, it can be imported into a DataPower PDP object, and DataPower
can act as a PDP without any additional configuration. Tivoli Security Policy Manager (TSPM) is one
such product that can be used to author XACML policies.
You saw that DataPowers AAA policy acts as the PEP and creates the authorization request by
extracting the subject and resource from the inbound request, then passing them to a stylesheet that
creates the authorization request document.
Finally, using the probe, you saw how the various steps were executed.

Lab 7: Authorization with XACML

Page 107

IBM Software

Page 108

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 8

Federation using SAML (Optional lab)

Prerequisite: Completion of Lab 4.


In this lab, youll add federation to the E6BService using Security Assertion Markup Language (SAML).
SAML is an XML-based standard for exchanging authentication and authorization data between security
domains, that is, between an identity provider (a producer of assertions) and a service provider (a
consumer of assertions).
In the context of Web services, SAML is used primarily for federation. The consumer of a Web service
will authenticate a user and create a digitally signed SAML assertion on that users behalf. The digital
signature assures that the assertion is not modified on its way to the service provider.
At the service provider, the digital signature is verified using a validation credential (which could contain
many client certificates). If the signature is valid and the assertion hasnt expired, the request is accepted
as authenticated.
In this lab, youll create a federated environment that will use an XML Firewall as the consumer (aka
partner), and the web service proxy that you created in an earlier lab as the service provider. The
following diagram illustrates how a request will be processed.

In the preceding illustration, the following sequence of events occurs:


The service consumer (soapUI on your workstation) will submit a SOAP request which

contains a WS-Security UsernameToken.

Lab 8: Federation using SAML

Page 109

IBM Software

An XML Firewall acts as the outbound federation point for the consumer. It first

authenticates the client by extracting the credentials from the UsernameToken, and then
authenticates them against an LDAP server. If this succeeds, the AAA policy will generate
a signed SAML assertion and forward the message to its intended service endpoint (the
WS-Proxy E6BService that you created in lab 4).
The message is received by the WS-Proxy which looks for the signed SAML assertion. If it

does not find it, it rejects the request. If it is found, and the signature is valid, then it will
allow the request to pass through to the actual E6BService.
The goal of this lab is for you to see that DataPower can act on behalf of the consumer by generating a
SAML authentication assertion, as well as on behalf of the service provider by accepting the signed
SAML assertion as an acceptable form of identity.

8.1.1

Create the consumer AAA policy

The consumer is responsible for authenticating the request before it is sent to the service provider. In this
section, youll create an AAA policy that will extract the user identity from the requests WS-Security
header, and then authenticate the user using an LDAP. If the authentication is successful, the policy will
inject a SAML authentication assertion into the SOAP header and then digitally sign it.
__1.

In the navigation search box, type aaa and from the search results, select: AAA Policy

__2.

Click Add to create a new AAA policy.

__3.

In the Name field, type: ConsumerAAA

__4.

In the SAML Message Signing Key field, click the plus (+) sign to create a new Crypto Key.

__5.

In the Configure Crypto Key form, use the following values:


__a. In the Name field, type: ConsumerKey
__b. In the File Name field, select consumer-privkey.pem from the dropdown list.
__c. In the Configure Crypto Key form, click the Apply button to save the new crypto key.

__6.

In the SAML Message Signing Certificate field, click the (+) sign to create a new Crypto
Certificate.
__a. For the name, type: ConsumerCert
__b. In the File Name, select consumer-sscert.pem from the dropdown list.
__c. Click the Apply button.

__7.

Towards the bottom of the page, locate LDAP Version and select: v3

__8.

Select the Extract Identity tab and from the Methods list, select: Password-carrying
UsernameToken Element from WS-Security Header

Page 110

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__9.

Select the Authenticate tab and provide the following details:


__a. For the Method, select: Bind to Specified LDAP Server
__b. For Host, type: demoserver
__c. For the port, type: 389
__d. For LDAP DN Suffix, type: ou=members,ou=datapower,dc=ibmdemo,dc=com

__10.

Select the Extract Resource tab and choose: Local Name of Request Element

__11.

Select the Postprocess tab and provide the following details:


__a. Turn on Generate a SAML Assertion with only Authentication Statement.
__b. Turn on Wrap SAML Assertion in a WS-Security Header

__12.

8.1.2

Click the Apply button.

Create the Service Consumer

For this step, youll create an XML Firewall service that will authenticate requests using ConsumerAAA
policy that you just created. SoapUI will send its outbound request to the E6BConsumer outbound
gateway, which will authenticate the username and password, then add a SAML assertion before
forwarding the request to the E6BService.
__13.

Click on the Control Panel link.

__14.

Click on the XML Firewall service icon to start the creation process.

__15.

Click the Add Advanced button.

__16.

In the Configure XML Firewall form, specify the following details:


__a. Firewall Name: E6BConsumer
__b. Remote Host: E6BService
__c. Remote Port: 445nn (where nn is your student number)
__d. Front End Port number: 555nn (where nn is your student number)
__e. Response Type: Pass-Thru

Lab 8: Federation using SAML

Page 111

IBM Software

__17.

In the XML Firewall Processing Policy field, click the plus (+) button to create a new policy.

__18.

In the Policy Editor, specify the Policy Name as: ConsumerPolicy

__19.

Click the New Rule button to create a new rule for this policy.

__20.

In the Rule Direction dropdown, select: Client to Server

__21.

Double click the yellow outlined match action to open its configuration page.

__22.

In the Matching Rule dropdown, select: MatchAnyURI and then click the Done button.

__23.

Drag an AAA action onto the processing rule.

__24.

Double click the yellow outlined AAA action to open its configuration page.

__25.

In the AAA Policy dropdown, select ConsumerAAA and then click the Done button.

__26.

Click the Apply Policy button to save the new policy.

__27.

Click the Close Window link to close the policy editor.

__28.

Click the Apply button to save the XML Firewall configuration.

Page 112

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

8.1.3

Create the service provider AAA Policy

Now youll need to create an AAA policy for the service provider (E6BService). This AAA policy will be
configured to extract the users identity from the SAML authentication assertion and consider it to be
valid if the digital signature is valid. If there is no SAML authentication assertion, or the digital signature
verification fails, then the request will be rejected.
__29.

In the navigation search box, type aaa and from the search results, select: AAA Policy

__30.

Click Add to create a new AAA policy.

__31.

In the Name field, type: E6BSamlAaa

In the next steps, youll create a new validation credential that will contain certificates for the trusted
partners. Youll add the consumer crypto certificate you created earlier in this lab exercise.
__32.

For the SAML Signature Validation Credentials, click the plus (+) sign to create a new validation
credential.
__a. For the Name, type: E6BSvcConsumers
__b. In the Certificates field, in the dropdown list select: ConsumerCert, then click the Add
button to add the certificate to the list.
__c. Click the Apply button.

__33.

Select the Extract Identity tab, then for the Method, select: Name from SAML Authentication
Assertion

__34.

Select the Authenticate tab and from the Method dropdown, select Accept a SAML Assertion
with a Valid Signature.

__35.

Select the Extract Resource tab and choose: Local Name of Request Element

__36.

Click the Apply button.

The final step is to add the new AAA policy to the existing E6BServiceProxy.
__37.

Click on the Control Panel link to display the main DataPower Control Panel.

__38.

Click the Web Service Proxy icon.

__39.

Click on E6BServiceProxy.

__40.

Select the Policy tab (not the SLM Policy tab).

In an earlier lab you added an AAA action to the CalculateHeadCrossWind operation. This time, youll
add the AAA action to the services default request rule.

Lab 8: Federation using SAML

Page 113

IBM Software

The default request rule is executed for all operations except those that explicitly override it. Since you
previously created a request rule for CalculateHeadCrossWind, the default request rule will not apply to
that operation. The default request rule will apply to the remaining operations, CalculateFlightLeg and
CalculateCloudBase.
__41.

At the top of the WSDL policy tree, click on the Processing Rules button.

__42.

Drag an AAA action after the SLM action.

__43.

Double Click the yellow outlined AAA action to open its configuration page.

__44.

In the AAA Policy field, select E6BSamlAaa and then click the Done button.

__45.

Click the Apply button to save these configuration changes.

8.1.4

Testing SAML Federation

Now youll submit several requests to the E6BService to show that the SAML-based federation is
working.
First, youll verify that you can no longer execute the CalculateCloudBase or CalculateFlightLeg
operation without a SAML assertion. To do this, youll have SoapUI go directly to the E6BServiceProxy
without going through the E6BConsumer you just created.
__46.

In SoapUI, under the CalculateCloudBase operation, double click Request.

__47.

In the request properties, assure there is no Username, Password, or WSS-Password Type


specified.

__48.

In the endpoint dropdown list, make sure that http://datapower:445nn/E6BService/E6BService is


selected.

Page 114

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__49.

Click the green submit button to execute the request. It should fail with a SOAP fault: Rejected
by Policy. It is failing because the policy now requires a signed SAML assertion and there isnt
one.

__50.

You can verify the same will occur with the CalculateFlightLeg operation.

Now youll post a message to the E6BConsumer you created. It will act as the outbound gateway from
the consumer (soapUI) by authenticating the user and then adding the SAML authentication assertion.
__51.

In the dropdown endpoint, select the URL that represents the E6BConsumer that is listening on
port 555nn. Edit the URL so that the port correctly shows your student number.

__52.

Click the green submit button to post the request. The request should fail since the
E6BConsumer AAA policy is expecting to extract the username and password from a WSSecurity UsernameToken.

Finally, submit the request with the username and password. The request will pass authentication in the
E6BConsumer gateway, which will then create a signed SAML assertion and forward the request to the
remote E6BServiceProxy thats protecting the real web service. The E6BServiceProxy will consume the
signed SAML assertion and permit the request to go through.
__53.

In SoapUI, under the CalculateCloudBase operation, double click Request_David. This request
has been prepopulated with a username and password for your convenience.

__54.

Click the green submit button. This time, the request should succeed.

To summarize all the pieces, here is the flow of what is happening:


Request is generated by soapUI (representing the consumer). Request contains

username and password in WS-Security UsernameToken.


soapUI sends the request to E6BConsumer (on port 555nn) for authentication and SAML

assertion generation and signing.


E6BConsumer extracts the username and password from the WS-Security

UsernameToken and authenticates it against the local LDAP. If authentication is


successful, it generates a signed SAML assertion and injects it into the SOAP headers.
The new SAML enriched message is then forwarded to the remote E6Bservice on port
445nn.
The E6BServiceProxy receives the message and attempts to extract the users identity

from a SAML assertion. If it cannot find the assertion, it will reject the message. If it finds
the assertion, it will attempt to verify the digital signature over the SAML assertion. If the
digital signature is good, the message will be accepted and forwarded to the real
E6BService running on the application server. If digital signature verification fails, the
message will be rejected.
The application server will process the request and then return the response to the

E6BServiceProxy.
The E6BServiceProxy schema validates the response and then forwards the response

back to the E6BConsumer which passes the response back to soapUI.

Lab 8: Federation using SAML

Page 115

IBM Software

You can see all these steps in action using the probe. The probe should still be enabled for the
E6BServiceProxy.
__55.

If your configuration is working properly, click Save Config.

8.2

Summary

In this lab, you saw how WebSphere DataPower can participate in a federation using SAML by creating a
mock environment for SAML-based federation. You created an XML Firewall with an AAA policy that
authenticates the user against an LDAP and then generates a signed SAML assertion. Then you created
a new AAA policy that looks for a signed SAML authentication assertion and added it to the existing
E6BServiceProxy.

Page 116

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 9

REST and JSON (Optional lab)

Representational State Transfer (REST) is an important Web 2.0 technology that has become a popular
alternative to other Web-based services, such as SOAP-based Web services and Enterprise JavaBeans
(EJB). Many Internet-facing companies provide REST-based services; a common scenario is to expose
a RESTful interface in front of an existing legacy system or peer system (SOAPful services). This lab
briefly explains what it means to be "RESTful," and then provides a comprehensive example of how to
use an WebSphere DataPower appliance to expose a RESTful facade (with JSON as the
representational format) to bridge an existing SOAPful Web service.
Web 2.0 includes a proliferation of new technologies; some of them brand new and others old but newly
invigorated as they are applied to Web 2.0. There is a growing demand to use these new protocols and
technologies to interact with existing enterprise systems. DataPower is uniquely positioned to bridge
Web 2.0 and SOA. DataPower can service Web 2.0 requests, such as an ATOM feed message or a
REST invocation, and bridge to enterprise protocols, such as Web services, JMS, or even mainframe
connectivity (for example, with IMS Connect). The case this lab addresses is that of bridging REST client
requests, which use JSON as the representational format, to a traditional SOAPful Web service back-end
system.

9.1

REST overview

REST is a term coined by Roy Fielding in his Ph.D dissertation, and it denotes an architectural style for
Web services and applications that manipulate media content. It can be considered a set of best
practices for using the HTTP specification (RFC 2616) as an application layer protocol. There are no
standards or APIs, and the primary ingredients are found in all HTTP-based Web applications and
services. A good analogy for REST is "object-oriented" Web programming in which the resource
specified by the URI is the object, the method is specified by the HTTP verb, and the parameters are
specified by the HTTP headers, such as Accept or the URI query. Finally, the HTTP response code is the
return code. For example, the following RESTful HTTP request results in the HTTP 201 (created)
response code:

PUT /library/book/9780596529260 HTTP 1.1


Content-Type: application/json
Accept: text/xml
....
{ "name" : "Treasure Island" }

Lab 9: REST and JSON

Page 117

IBM Software

A Web service provider (and consumer for that matter) will pay close attention to the following RESTful
precepts:
Named resources - Computation is over Web resources that are named through URIs.
A resource is anything important enough to be referenced as a thing in itself, such as

/software/releases/1.0.3.tar.gz, /weblog/jim/2008/12/24/0300, or /bug/12345.


Consumers interact with resources using their URIs and the uniform interface.

Uniform interface - Web resources are accessed through a generic interface that mimics the CRUD
persistent storage pattern:
GET -- Retrieve a resource representation.
POST -- Create a new resource.
PUT -- Modify or create a new resource.
DELETE -- Remove an existing resource.
HEAD -- Retrieve metadata-only representation.

Interconnected resource representations - URL links interconnect resources, thereby driving all state
transfers.
Representations are hypermedia (consider the duality of XHTML and micro-formats).
A web of resources.
Axiom: "Hypermedia as the engine of application state" -- Roy Fielding.
Application state is therefore the pathway the client follows, not an HTTP session on a

server.
Cookies break the REST model of state transfer.

Stateless - Each request stands on its own without correlation to the server-side state.
States of a server are represented by URI addressable resources.
Every HTTP request happens in complete isolation, and is not dependent on previous

requests.
Client moves through states by navigating representational formats (URIs) or going to

known waypoints.
Consider the FTP "working directory" as an analogy.
Easy to distribute a stateless application across load-balanced services.
Client is in charge of managing "application state," while server manages "resource state."

The result of applying RESTful precepts is not only the simplicity and consistency of developing and
invoking Web services, but also an advantage in service performance. When RESTful services are
deployed, they can naturally participate in the HTTP caching mechanism. Therefore caching
intermediaries or response caches can leverage the additional information supplied not only by the HTTP
method, but also by the cache control headers (including the last-modified header) rendered by the
RESTful service provider. Leveraging caching in this way can dramatically improve response time. In
addition, the stateless nature of RESTful service not only makes horizontal scaling trivial, but also eases

Page 118

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

the burden on load balancers (no session affinity is necessary), and allows application-aware caching
intermediaries to execute more efficiently because the payload often does not have to be processed or
parsed.

9.2

Exposing REST with DataPower

The following figure shows an overview of WebSphere DataPower exposing a REST facade against a
SOAPful Web service as the back end. The representational format (media type) used by the REST
facade is JSON. The multi-protocol gateway accepts RESTful method requests (GET, PUT, POST,
DELETE) from the service consumer and then transforms the requests to corresponding SOAP requests,
which are sent to the WS-Proxy. The WS-Proxy is optional; the SOAP requests could be sent directly to
the back end, but this practice is strongly discouraged because the configuration might require
monitoring or security in the future. Thus, a best practice is to include a WS-Proxy as part of a REST
transformation configuration. To save time, you wont be configuring the WS-Proxy.

Topology of a RESTful client passing JSON to DataPower, which mediates a SOAPful Web Service

Lab 9: REST and JSON

Page 119

IBM Software

9.3

The ProjectService example

The remainder of this lab uses a common example to show how DataPower can expose a RESTful Web
service interface, enabled for JSON, for a SOAPful Web service backend. The sample ProjectService
Web service is a simple project organizer with which projects can be created, edited, and queried. The
operations available for ProjectService are shown below:
Operation

Description

createProject

Creates a project on the server consisting of a project name, description, and


identifier. The identifier is generated and returned in the response.

updateProject

Makes a change to a project. The project identifier, name, and description


must be provided.

getProject

Fetches name and description of a project. The identifier of the project must be
provided in the request.

listProject

Returns all projects or filters based on owner name.

deleteProject

Removes a project from the server. The identifier of the project must be
provided in the request.

9.4

Verify service availability

In this section, youll use soapUI to send a SOAP transaction to the actual ProjectService to verify that it
is up and running.
__1.

In soapUI, expand ProjectService SOAP, locate and double click Create Request to open a
request window.

__2.

In the endpoint dropdown, select: http://demoserver:9080/ProjectService/ProjectService.

__3.

Click the green submit button to POST the request to the ProjectService.

Page 120

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__4.

Verify that the successFlag is true and the success message indicates that the project was
created. Also notice that an id was assigned to this project.

Now that youve verified that the service is accessible and operational, youre ready to configure a
Multi-Protocol Gateway that will mediate between REST/JSON and SOAP.

9.5

REST Multi-Protocol Gateway

Since you already have experience (from earlier labs) in creating and configuring a Multi-Protocol
Gateway service, youll import a pre-built configuration for this lab. That will save you plenty of dragging
and dropping since it requires a separate rule (with multiple actions) for each HTTP verb.
__5.

Click on the Control Panel link to display the DataPower control panel.

__6.

In the bottom row of icons, click on Import Configuration.

__7.

Click the Choose File button

__8.

Navigate to c:\labs\rest and select: RESTProjectServiceFacade.zip

__9.

Click the Next button to start the import process. DataPower will read the configuration file and
then show you a summary of the configuration objects it will import.

__10.

At the bottom of the window, click the Import button to import the selected files.

__11.

After the import completes, a summary will be displayed. Click Done to continue.

The Multi-Protocol Gateway is now imported and ready to be used.

9.5.1

Processing messages with empty bodies

__12.

From the DataPower control panel, click on the Multi-Protocol Gateway icon.

__13.

From the list of Multi-Protocol Gateways, select: RESTProjectServiceFacade

__14.

In the upper right area, click on Show Probe.

__15.

Click the Enable button to enable the probe, then click the Close button in the confirm dialog.
Leave the probe window open so you can easily access it later.

__16.

Back in the main browser, in the list of tabs across the top of the page, select the Advanced tab.

Lab 9: REST and JSON

Page 121

IBM Software

On the Advanced tab, you should notice an option towards the bottom labeled "Process messages
whose body is empty" (see the following figure). This option is useful for message patterns that can
include bodiless requests and responses. This is common with RESTful Web services where messages
may or may not include a body, but still require the processing policy to run in order to perform
mediations. Unlike SOAPful Web services, which always have a payload (message body), RESTful Web
services often, but not always, have a message body, as with HTTP DELETE.
Since our RESTful facade will support HTTP DELETE and GET, you must configure the service to
support bodiless messages. If you don't select this option, DataPower defaults to a processing mode
called "One way exchange pattern," in which messages flow straight to the backside server, bypassing
any processing rules. You also have to configure the HTTP front side handler to accept the HTTP
methods that you plan on supporting in your policy. In addition, since you are dealing with JSON as the
representational format, the request and response payload types will be non-XML.
Multi-Protocol Gateway configuration, Advanced Tab

9.5.2

Rewriting the URL

The ProjectService specifies /ProjectService/ProjectService as the service URI, while RESTful Web
services use URI's not as the service end-point but rather as the resource to apply the uniform interface.
Because of this dramatic difference in usage, a URL rewrite policy is associated with the multi-protocol
gateway, as shown in Figure 7-3 below. In this way, all incoming RESTful URI's are rewritten to the
single SOAP service URI.
__17.

From the row of tabs, click on the General tab.

__18.

In the General Configuration section, locate the URL Rewrite Policy dropdown and then click the
ellipsis () button.

Page 122

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__19.

In the Configure Rewrite Policy page, click on the URL Rewrite Rule tab.
You can see the various parameters included in a URL rewrite rule. A single URL Rewrite Policy
can contain multiple rules, so it is possible to share a single policy amongst various services.

__20.

9.5.3

Click the Cancel button to close the policy window.

Using REST verbs

When building a RESTful service, it is a best practice to set up processing rules for each HTTP method.
This is because the REST uniform interface may be applied to each RESTful URI but require different
processing behavior, such as HTTP DELETE on /library/book/12345679001 and HTTP GET on
/library/book/12345679001.

Lab 9: REST and JSON

Page 123

IBM Software

The Multi-Protocol Gateway matches on HTTP methods by creating a Match Action with a Match Rule
that specifies a Matching Type of "HTTP Method" for each REST verb supported by the service. This
matching rule can be combined with any other match criteria to create personalized processing rules
based on URI and/or HTTP headers.
__21.

In the General Configuration section, in the Multi-Protocol Gateway Policy field, click on the
ellipsis () to open the policy editor.

__22.

Enlarge the policy editor so that you can see all of the defined rules (see below).

Notice that there is a Client to Server (request) and Server to Client (response) rule for each of the
four HTTP verbs.

Page 124

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

The first action in each rule is the Match action. The Match action contains some criteria that, if met, will
cause the rest of the rule to execute. Match actions are executed from top to bottom, and once a match
actions criteria is met; no additional match actions are tested.
__23.

In the list of Configured Rule, hover the mouse over the match action
rule (POST) to see the match criteria.

associated with the first

Notice that the Type is method (short for HTTP method), and the Method is POST. In other
words, if the request arrives and has an HTTP method of POST, the match criteria will be met,
the remaining actions in the rule will be executed, and no further match testing will occur. If the
request has a different method, such as DELETE, this matchs criteria will not be met; the next
match action will then be evaluated.
__24.

Hover the mouse over the various match actions to see how they are defined.

The next sections describe the implementation of the REST Multi-Protocol Gateway policy. They can be
used as an exercise in DataPower REST development, as a working configuration to use as a starting
point for other REST projects, or simply as a gauge for what transformation from REST/JSON to SOAP
looks like with DataPower.

9.5.4

POST method processing

The POST processing rule corresponds to the createProject operation for the SOAP API.
Request payload

{ "description":"Research of ancient cultures", "owner":"Alice" }


Response payload
None, but the location HTTP header should give the URL of the newly created resource.

Lab 9: REST and JSON

Page 125

IBM Software

Request Actions

1. Convert-http action: The http-convert action specifies JSON as the message encoding which automatically
parses and transforms the message payload into JSONx, an IBM internal standard for representing JSON as
XML. Once the JSON is transformed into JSONx, the usual DataPower transformation capabilities are
available to further process the message as XML. For the JSON request payload, the resulting JSONx is
shown below:
<json:object xsi:schemaLocation="http://www.d... {omitted} ...2009/jsonx">
<json:string name="description">Research of ancient cultures</json:string>
<json:string name="owner">Alice</json:string>
</json:object>

2. Transform action: Uses a custom stylesheet to transform the JSONx to an equivalent SOAP message. To
view the entire XSL, use the DataPower File Manager to view local:///createProjJSONx2SOAP.xsl.
<xsl:template match="/">
<soapenv:Envelope xmlns:soapenv="htt... {omitted} ...tapower.ibm.com/ProjectService/">
<soapenv:Body>
<tns:createProjectRequest>
<tns:newProject>
<tns:name>
<xsl:value-of select="/json:object/json:string[@name='description']" />
</tns:name>
<tns:owner>
<xsl:value-of select="/json:object/json:string[@name='owner']" />
</tns:owner>
</tns:newProject>
</tns:createProjectRequest>
</soapenv:Body>
</soapenv:Envelope>
</xsl:template>

3. Setvar action: This action sets the SOAPAction header before the message is sent to the actual
ProjectService.

Page 126

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Response Actions

1. Transform action: Uses a custom stylesheet to select the ID from the SOAP response and sets the location
HTTP header with the URL for the newly created resource.
<xsl:template match="/">
<xsl:variable name="quote">'</xsl:variable>
<xsl:variable name="message" select="//*[local-name()='successMessage']/text()" />
<xsl:variable name="id_begin" select="substring-after($message, $quote)" />
<xsl:variable name="id" select="substring-before($id_begin,$quote)" />
<dp:set-http-response-header name="'Location'" value="concat('/projects/',$id)" />
</xsl:template>

Testing createProject using REST and JSON


__25.

In soapUI, collapse the ProjectService SOAP project and expand ProjectService REST to reveal
the Create Project request.

__26.

In the Request tab, carefully change the value of the owner to your name. Feel free to change
the description as well, but be careful to maintain the JSON syntax.

__27.

Update the soapUI URL to include the correct port [446nn] based on your student number.

__28.

Click the green submit button to POST the JSON body to the RESTful faade to the
ProjectService.

Lab 9: REST and JSON

Page 127

IBM Software

__29.

The soapUI response tab should become active, but if its not, click on the Response tab.

__30.

In the response tab, click on the side tab labeled Raw to show the actual response from the
REST faade.

Notice the Location header has been properly set to the URL of the project you just added.
__31.

Bring the probe window back to the front so you can inspect the transaction.

__32.

Click the Refresh button to show the new transaction.

__33.

From the list of transaction, click on the small [+] to show the request and response.

__34.

Click on the magnifying glass for the request.


Notice that the INPUT context is shown as binary data instead of XML. On the right side, you can
see the message payload which contains the JSON createProject request.

__35.

Click on the 2nd magnifying glass in front of the transform

action.

The original JSON payload was successfully transformed into JSONx and is now represented
using XML. Now that the message is in XML, it can be manipulated using XSLT to generate a
true SOAP request.
__36.

Click on the 3rd magnifying glass in front of the set variable


action.
You can now see the results of the transformation using createProjJSONx2SOAP.xsl. The input
to the XSLT was the JSONx, and the output of the XSLT is the SOAP message.

__37.

Click on the 4th magnifying glass.

__38.

Click on the Headers tab. Notice the SOAPAction header was created by the set variable action.

__39.

Close the transaction detail window.

__40.

Back in the Probe Transaction List, click the magnifying glass in front of the response.

Page 128

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__41.

The INPUT context should show the response that was received from the ProjectService
backend.

__42.

Click on the 2nd magnifying glass in front of the results


action, then click on the
Headers tab. Notice that the Location header has been set to show the URI for accessing the
newly created project.

__43.

Make a note of the Location URI so you can use it later (the number is the important part).

__44.

Close the transaction details window.

__45.

In soapUI, create one or two more projects (keep your name as the owner).

Lab 9: REST and JSON

Page 129

IBM Software

9.5.5

GET method processing

The GET processing rule corresponds to the getProject and listProject operations for the SOAP API. It
can either retrieve a single project or a list of projects.
Request payload
None
Response payload
JSON project:

{ "id":2, "name":"Astronomy Project", "owner":"Jennifer" }


JSON project list:
[ { "id":2, "name":"Astronomy Project", "owner":"Jennifer" },
{ "id":3, "name":"Physics Project", "owner":"Gerry" } ]
Request Actions

1. Transform action: This transform generates a SOAP message based on the contents of the URI. If the URI
contains /projects/, it extracts the project id from the URI and generates a getProject request, otherwise it
generates a listProjects request.
2. Method rewrite: Converts the original GET into a POST.
Response Actions

1. Transform action: Uses a custom stylesheet convert the SOAP response into JSONx in preparation for the
next transform.
2. Transform action: Uses an IBM supplied stylesheet that converts JSONx into JSON.

Page 130

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Testing getProject using REST


__46.

In soapUI, close any open windows, then open the Get Project request (see below).

__47.

Update the soapUI URL to include the correct port based on your student number.

__48.

In the Get Project request window, locate the projectId parameter and update it with the number
you saved from the createProject test.

__49.

Click the green submit button to GET the details about the project. Your response should look
similar to the one below.

Lab 9: REST and JSON

Page 131

IBM Software

Testing listProjects using REST


Under the covers, listProjects is also using the HTTP GET method so this is a good opportunity to test
the listProjects operation.
__50.

In soapUI, close any open windows, then open the List Project request (see below).

__51.

Update the soapUI URL to include the correct port based on your student number.

__52.

Click the green submit button to submit the GET request to the REST faade.

Page 132

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

9.5.6

PUT method processing

The PUT processing rule corresponds to the updateProject operation for the SOAP API.
Request payload
JSON project object

{ "id":2, "name":"Astronomy Project", "owner":"Jennifer" }


Response payload
None.
Request Actions

1. Convert-HTTP action: This http-convert action specifies JSON as the message encoding, which
automatically parses and transforms it into JSONx, an IBM internal standard format for representing JSON as
XML. Once the JSON is transformed into JSONx, the usual DataPower transformation capabilities are
available to further process the message as XML if necessary.
2. Transform action: This stylesheet transforms the REST JSONx project payload to the equivalent SOAP
payload. The project ID, project description, and owner are copied from the JSONx REST request (see
local:///updateProjJSONx2SOAP.xsl).
3. Setvar action: This action sets the SOAPAction header before the message is sent to the ProjectService
Web service proxy.
4. Method rewrite: Prior to sending the SOAP message to the back end, you need to rewrite the HTTP method
from the originating PUT to HTTP POST.
Response Actions

1. Transform action: Once the SOAP response is retrieved from the back end, it needs to be transformed into a
RESTful response code, which is typically 204 (No Content) when a PUT is performed.

Lab 9: REST and JSON

Page 133

IBM Software

Testing updateProject using REST


__53.

In soapUI, close any open windows, then open the Update Project request.

__54.

Update the soapUI URL to include the correct port based on your student number.

__55.

In the Update Project request window, locate the projectId parameter and set it to the number
you saved from the createProject test.

__56.

In the request body section, modify the description or owner.

Page 134

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__57.

9.5.7

Click the green submit button to PUT the details about the project. Put does not return a payload,
thus the response will be empty, however it should return an HTTP response 204. You can verify
this by looking at the Raw tab in the soapUI response.

DELETE method processing

The DELETE processing rule corresponds to the removeProject operation for the SOAP API.
Request Payload
None
Response Payload
None
Request Actions

1. Transform action: This stylesheet constructs the SOAP payload to delete a project. It corresponds to the
deleteProject SOAP operation. The project ID is retrieved from the URL and then used to construct the SOAP
payload.
2. Setvar action: Sets the SOAPAction header to deleteProject as expected by ProjectService.
3. Method rewrite: Converts the original DELETE into a POST.
Response Actions

1. Transform action: Uses a custom XSLT to set the HTTP response code to 204 (No Content).

Lab 9: REST and JSON

Page 135

IBM Software

Testing deleteProject using REST


__58.

In soapUI, close any open windows, then open the Delete Project request.

__59.

Update the soapUI URL to include the correct port based on your student number.

__60.

In the Delete Project request window, locate the projectId parameter and replace it with the
number you saved from the createProject test.

Page 136

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

__61.

Click the green submit button to DELETE the project. DELETE does not return a payload, thus
the response will be empty; however it should return an HTTP response 204. You can verify this
by looking at the Raw tab in the soapUI response.

__62.

Optionally, you can execute the listProject command again to see that the project is missing.
Because the whole class is using the same project store, the list may contain more than just your
projects.

Lab 9: REST and JSON

Page 137

IBM Software

9.6

Conclusion

This lab showed how WebSphere DataPower fits in the Web 2.0 space, provided an overview of REST,
described the recommended patterns to use for exposing REST and JSON with WebSphere DataPower,
and included a comprehensive example with a DataPower domain export and the ProjectService Web
service back-end application. You should now have a good understanding of what REST is and how you
can develop REST services on WebSphere DataPower so you can configure your own Web 2.0
appliance.

Page 138

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Lab 10

Middleware and Mainframe Integration (Optional lab)

Prerequisites: Completion of Labs 1 and 2.


In this lab, youll learn how:
WebSphere DataPower integrates with WebSphere MQ.
WebSphere DataPower can bridge between HTTP and WebSphere MQ.
WebSphere Transformation Extender Design Studio is used to design maps that translate

between XML and non-XML formats such as COBOL copybooks.


To configure WebSphere DataPower to execute WebSphere Transformation Extender

maps.

10.1 Protocol Bridging: HTTP to WebSphere MQ


WebSphere DataPowers Multi-Protocol Gateway service provides built-in capabilities for creating
processing policies that support inbound and outbound transactions over a multitude of disparate
protocols, including HTTP(S), WebSphere MQ, WebSphere JMS, IMS, and FTP to name a few. The
inbound and outbound protocol need not be the same. A request can arrive over HTTP and depart over
WebSphere MQ. This is especially useful when exposing legacy applications or off-loading expensive
XML processing (parsing, schema validation, cryptography, etc.) from a mainframe.
As a WebSphere MQ client, the DataPower appliance connects to a WebSphere MQ Queue Manager
and listens for messages to arrive on a designated queue. When the message arrives, the message
body is then extracted from the message and processed through a policy in exactly the same manner as
if it had arrived over HTTP. Internally, WebSphere MQ specific details such as headers, are available for
inspection or modification within a processing policy.
When bridging HTTP to WebSphere MQ (or any messaging protocol), the multi-protocol gateway can
function either synchronously or asynchronously. In a synchronous configuration, the Multi-Protocol
Gateway (MPGW) receives a request over HTTP, processes it, and then forwards the message to a
queue (using a PUT). The MPGW will then listen on another queue for the response (using the
correlation ID). When the message arrives, the MPGW will process it, then convert it to HTTP and return
it as the response to the original message.

Lab 10: Middleware and Mainframe Integration

Page 139

IBM Software

In an asynchronous scenario, the MPGW receives the request over HTTP or WebSphere MQ, processes
it, and then PUTs the message onto the designated queue. No response processing will occur.

10.2 PoT Lab Environment


The instructor machine (demoserver) has a Java application that connects to queue manager
QM_demoserver and waits for messages on a queue named requests. When a message arrives, the
application will copy the contents of the message to a new message, update the correlation ID to be the
original message ID, and then put the new message on a queue named replies. Essentially, this is an
echo service using queues instead of HTTP.

10.3 Connecting to an MQ Queue Manager


A queue manager connection object acts as a reusable proxy between the WebSphere DataPower
appliance and an actual WebSphere MQ Queue Manager. The queue manager object is responsible for
coordinating all communications between the WebSphere DataPower appliance and WebSphere MQ.
In the next steps, youll configure a WebSphere MQ Queue Manager Connection object.
__1.

In the navigation search box, type queue and then from the search results, select MQ Queue
Manager. If multiple results with the same name exist, select any one of them.

__2.

Click the Add button to create a new queue manager connection object.

__3.

In the Name field, type: MyMqManager

__4.

For Host Name, type: demoserver(1414)

__5.

For Queue Manager Name, type: QM_demoserver

__6.

At the top of the form, click the Apply button.

Page 140

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

10.3.1 Create a Multi-Protocol Gateway


__7.

In the navigation search box, type multi and then from the search results, select
New Multi-Protocol Gateway.

__8.

In the General tab, make the following changes.


a. Multi-Protocol Gateway Name: MqGatewaySvc
b. Response Type: Pass-Thru
c. Request Type: Non-XML
d. Propogate URI: off

__9.

In the Backend URL field, click the MQHelper button and provide the following details.
__a. Queue Manager dropdown: MyMqManager
__b. RequestQueue: requests
__c. ReplieQueue: replies
__d. Click the Build URL button
__e. In the Front Side Protocol field, click the (+) button to create a new front side handler, and
then from the list of front side handler types, select: HTTP Front Side Handler

__10.

In the HTTP Front Side Handler form, make the following selections, replacing nn with your
student number.
__a. Name: HTTP_447nn
__b. Port Number: 447nn
__c. Click Apply

__11.

In the Multi-Protocol Gateway Policy field, click the (+) button to create a new policy.

__12.

In the Policy Name field, type: MqGatewayPolicy

__13.

Click the New Rule button to create a new processing rule.

__14.

In the Rule Direction field, select Client to Server.

__15.

Double click the yellow outlined match action to show its configuration page. From the Matching
Rule dropdown, select MatchAnyUri and then click the Done button.

__16.

Click the Apply Policy button to activate the changes to the policy.

__17.

Click the Close Window link to close the policy editor.

Lab 10: Middleware and Mainframe Integration

Page 141

IBM Software

__18.

Click the Apply button to save these changes to the multi-protocol gateway service.

__19.

In soapUI, collapse any open projects. Expand the MQGatewayService project and open Simple
echo request.

__20.

In the endpoint dropdown list, select endpoint: http://datapower:447nn.

__21.

Again, in the endpoint dropdown, select [edit current], then update the port number by
replacing the nn with your student number.

__22.

Feel free to update the Hello, world! message payload to any message, then click the green
submit button to POST the message to MqGatewaySvc. You should see your message echoed
back in the response. Choose the Raw tab to see the response without any XML formatting.

If youd like to see details about how the message travelled from HTTP to WebSphere MQ, you can use
the transaction probe or view the system logs.

10.4 Transforming Non-XML Payloads


Up until now, youve seen how WebSphere DataPower can manipulate XML documents in a variety of
ways including encrypting, decrypting, signing, and transforming. Youve also seen how WebSphere
DataPower appliances can mediate between various types of protocols such as HTTP and WebSphere
MQ. Quite often, it becomes necessary to manipulate requests that are not XML. This is especially
common in service oriented architectures involving legacy systems that havent yet been enabled for
XML. One of the most common scenarios is mapping XML data to COBOL copybooks and back.
The WebSphere Transformation Extender Design Studio enables you to define complex mappings
between nearly any types of data. For example, the map may define conversion from comma separated
fields to XML or from XML to a complex COBOL copybook. Once created, the map definition can be
imported into DataPower and executed against in-flight messages. In DataPower terms, this type of
transformation is referred to as a binary transformation.
The process involves two steps. First, the map definition must be created using WebSphere
Transformation Extender Design Studio. Once the maps are created, a special mapping file is exported
from WebSphere Transformation Extender Design Studio and imported into WebSphere DataPower.

Page 142

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

10.4.1 Creating the WebSphere Transformation Extender Maps


There are three basic steps to building a WebSphere Transformation Extender Map using the
WebSphere Transformation Extender Design Studio
Define the input and output formats.
Map the input to the output and apply any rules or functions to manipulate the data.
Build, test and deploy the map.

10.4.2 Defining the Input and Output Data


When defining a binary transform, WebSphere Transformation Extender uses the notion of Input Cards
and Output Cards. Input cards are used to define the format of the source data to be transformed, and
output cards define how the data should be formatted. A Map contains the associations and rules for
moving the data from the input to the output card.
Input and output cards can be automatically created by importing various types of data descriptions, such
as XML schemas and COBOL copybooks to name just a few. For this lab, the following schema was
imported to create the input card.

Lab 10: Middleware and Mainframe Integration

Page 143

IBM Software

The schema describes an XML document that looks like the following:

The output card was generated by importing a COBOL copybook (shown below).

Page 144

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Once the input and output cards are defined, a map is created by dragging fields from the input card and
dropping them onto the output card. WebSphere Transformation Extender contains a large library of
functions, such as math and string manipulation, that can be used when creating the maps.

10.4.3 Building, testing and deploying your map to WebSphere DataPower


Once the maps have been defined, they are built and tested within WebSphere Transformation Extender
Design Studio. If the map definitions produce the desired results, then they can be uploaded to
WebSphere DataPower for execution.

10.5 Executing the Map on WebSphere DataPower


To execute the COBOL to XML map, youll add a binary transform action to the MQ rule you created
earlier in this lab.
__23.

In the Multi-Protocol Gateway Policy field, click on the ellipsis () to open the policy editor.

__24.

Drag an Advanced action onto the rule after the match action

Lab 10: Middleware and Mainframe Integration

Page 145

IBM Software

__25.

Double click the yellow outlined Advanced action to open its configuration.

__26.

In the list of action types, scroll to the bottom and select: Transform Binary, then click Next.

__27.

In the WTX Map file field:


__a. Click the Upload button.
__b. Click the Choose File button, then browse to c:\labs\wtx and select XMLtoCBL.dpa
__c. Click the Upload button.
__d. Click the Continue button.

__28.

Click the Done button.

The rule should now look like the following image.

__29.

Click the Apply Policy button.

__30.

Click the Close Window link to close the policy editor.

__31.

Click the Apply button to save the changes to the multi-protocol gateway service.

__32.

In soapUI, close any open request windows and then open the WTX transform request. It will be
pre-populated with the XML content described earlier in this lab.

__33.

Update the soapUI URL to include the correct port number [447nn] based on your student
number.

__34.

Click the green submit button to POST the message to the MQGatewayService Gateway. You
should see your message echoed back in the response. Choose the Raw tab to see the
response without any XML formatting.

Page 146

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

10.6 Summary
In this lab, you learned:
WebSphere DataPower act as a WebSphere MQ Client.
WebSphere Transformation Extender Design Studio can be used to create binary

transformations (any to any). WTX uses input cards to define how the input is formatted,
output cards to define how the desired output should be formatted and mapping files to
define the relationship and mapping rules between the input and output cards.
WebSphere DataPower can execute maps built using WebSphere Transformation

Extender Design Studio to perform binary transformations.

Lab 10: Middleware and Mainframe Integration

Page 147

IBM Software

Page 148

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Appendix A. Common Deployment Scenarios


WebSphere DataPower deployments are easily tailored to meet your enterprises requirements
development, testing, production, and disaster recovery requirements. This appendix gives a brief
overview on the most common enterprise deployment scenarios.
There are six basic areas where WebSphere DataPower SOA Appliances are deployed. These six areas
can be mixed and matched as necessary. Pick and choose the categories that apply to your specific
project timelines and risk profiles.
These categories are independent of network segment
considerations such as DMZ vs. internal cloud.

Lab Environment
Isolated environment allows testing of major new firmware features without impacting

ongoing development streams.


Common in mature WebSphere DataPower installations with multiple ongoing

development efforts.

Development Environment
Very common practice to isolate development to a dedicated environment.
Single appliance for developer sandbox as well as project-specific configuration.

Testing Environment
Isolating the test environment from the development environment is a common best

practice.
Unique environments ease the burden of code migration.

Staging Environment
Staging environment allows testing pre-releases, or rolling new releases into production.
Often re-used as a performance test lab to determine peak supported throughput in a

production-like environment.

Production Environment
Appliances can be deployed in active/active (with a load balancer) or active/passive

(without).
Appliances can balance traffic to target servers, so a second load balancer is NOT

required.

Appendix A

Page 149

IBM Software

Disaster Recovery
Many organizations require full data center failover to a second fully equipped site.
Specific project risk profile will dictate this need.

Page 150

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Appendix B. The (XML) Threat is Out There


Bill Hines, Senior Certified Consulting IT Specialist, IBM

New technologies, new temptations


Service-oriented systems are currently all the rage, and rightfully so. It seems like only yesterday that
service-oriented architecture (SOA) was the new buzzword, making us wonder whether this was just
more marketing hype or a technology that would actually become useful -- similar to the thoughts we
may have had about previous buzzword technologies, like Extensible Markup Language (XML) or, more
recently, Web services.
As with XML and Web services, SOA architectures are now bearing fruit across the corporate IT
landscape, thanks to useful enabling technologies, such as the Service Integration Bus in IBM
WebSphere Application Server V6, and its product-ized big brother, the IBM WebSphere Enterprise
Service Bus. As new technologies often do, however, these technologies have invited a whole new class
of attacks on systems that implement them. IT specialists who take security and systems hardening
seriously need to be constantly vigilant about the holes that new technologies can open into their
systems. Hackers have moved their attention past traditional targets, perhaps due to the inevitable
maturity of those platforms, or perhaps because they are now simply pass.
The new frontier for hackers is systems built on Web services and XML, seen as inviting due to their
popularity and immaturity. One class of such attacks is defined as XML threats, where an XML document
that has been structured to do harm is sent to your system. If a system can be accessed by outsiders
(such as through the Internet), someone could send messages to your system in order to damage it, or
even just to consume resources. It is possible that the offending client could even be authorized to use
your system, but is trying to exploit that authorization in some inappropriate way. When XML and SOAP
were described as the new IT "miracle drug," due to their ability to "pass through the firewall," some
savvy computer specialists immediately saw the implications of this from a security perspective. Those
firewalls were put there for a reason, no? Hackers view this "feature" as a free ride on the XMLmobile,
waving at the firewall sentries as they happily pass by.
Often, programmers will leave the door open to attacks by using poor technique, like not strictly defining
the types of data they expect as input to Web services. One example of this would be the use of the
xml:any data type, as opposed to restricting input to an integer or string. This lets attackers send harmful
XML for this attribute -- and as a perfectly legitimate input!
There are four broad classifications of XML threats:

XML Denial of Service (xDoS) -- Slowing down or disabling a Web service so that valid service
requests are hampered or denied.

Unauthorized access -- Gaining unauthorized access to a Web service or its data.

Data integrity/Confidentiality -- Attacks that strike at the data integrity of Web service
responses, requests, or underlying databases.

System compromise -- Corrupting the Web service itself or the servers that host it.

There are several types of attacks within these four broad classifications, which we will look at in a
minute. Also, be aware that these can be single-message or multiple-message attacks.

Appendix B

Page 151

IBM Software

Software-based application servers used to host Web services are generally quite vulnerable to these
attacks; they are often run with XML validation off for performance reasons, and may not be looking out
for most XML attack types. As we will see, once the XML hits the parser, it is too late. Worse, if your
system accepts native XML documents without the complexity of Web services or SOAP, it is even
easier to attack.

Specific types of XML threats


Specific types of attacks within the four broad categories are listed below. Several of these attack types
are familiar; these same types of attack occur with any remotely accessible service (for example,
message tampering). Other attacks, though not really unique to XML-based services, are much more
likely to occur with such services given the nature of XML.

Single message xDoS

Jumbo payloads -- Sending a very large XML message to exhaust memory and CPU on the
target system.

Recursive elements -- XML messages that can be used to force recursive entity expansion (or
other repeated processing) to exhaust server resources. An example of this type of attack would
be the billion laughs attack that is widely available through the Internet.

MegaTags -- Otherwise valid XML messages containing excessively long element names, or an
excessive number of tags. This attack may also lead to buffer overruns.

Coercive parsing -- XML messages specially constructed to be difficult to parse to consume the
resources of the machine.

Public key DoS -- Utilizing the asymmetric nature of public key operations to force resource
exhaustion on the recipient by transmitting a message with a large number of long-key-length,
computationally expensive digital signatures.

Multiple message XDoS

XML flood -- Sending thousands of otherwise benign messages per second to tie up a Web
service. This attack can be combined with Replay attack to bypass authentication, and with
Single message XDoS to increase its impact.

Resource hijack -- Sending messages that lock or reserve resources on the target server as part
of a never-completed transaction.

Unauthorized access

Dictionary attack -- Guessing the password of a valid user using a brute force search through
dictionary words.

Falsified message -- Faking that a message is from a valid user, such as by using Man in the
Middle to gain a valid message, and then modifying it to send a different message.

Replay attack -- Re-sending a previously valid message for malicious effect, possibly where only
parts of the message (such as the security token) are replayed.

Page 152

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

Data integrity/Confidentiality

Message tampering -- Modifying parts of a request or response in-flight; most dangerous when
undetected (less commonly known as Message alteration).

Data tampering -- Exploiting weakness in the access control mechanism that permits the
attacker to make unauthorized calls to the Web service to alter data.

Message snooping -- A direct attack on data privacy by examining all or part of the content of a
message. This can happen to messages being transmitted in the clear, transmitted encrypted but
stored in the clear, or decryption of messages due to stolen key or cryptanalysis.

XPath/XSLT injection -- Injection of expressions into the application logic. Newer modifications
include Blind XPath injection, which reduces the knowledge required to mount the attack.

SQL injection -- Inserting SQL in XML to obtain additional data than what the service was
designed to return.

WSDL enumeration -- Examining the services listed in WSDL to guess and gain access to
unlisted services.

Message snooping -- Using SOAP routing header for access to internal Web services.

Systems compromise

Malicious include -- Causing a Web service to include invalid external data in output or return
privileged files from the server file system. For example, using embedded file: URLs to return
UNIX password files or other privileged data to the attacker.

Memory space breach -- Accomplished via stack overflow, buffer overrun, or heap error,
enables execution of arbitrary code supplied by the attacker with the permissions of the host
process.

XML encapsulation -- Embedding system command in the XML payload, such as through the
CDATA tag.

XML virus (X-Virus) -- Using SOAP with attachments or other attachment mechanisms to
transmit malicious executables, such as viruses or worms.
http://www.ibm.com/developerworks/websphere/techjournal/0603_col_hines/0603_col_hines.html

Appendix B

Page 153

IBM Software

Appendix C. Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES
CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this
statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part
of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have

Page 154

Discovering the value of IBM WebSphere DataPower SOA Appliances

IBM Software

been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction and intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental. All references to fictitious companies or individuals are
used for illustration purposes only.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.

Appendix C

Page 155

IBM Software

Appendix D. Trademarks and copyrights


The following terms are trademarks of International Business Machines Corporation in the United States,
other countries, or both:
IBM

AIX

CICS

ClearCase

ClearQuest

Cloudscape

Cube Views

DB2

developerWorks

DRDA

IMS

IMS/ESA

Informix

Lotus

Lotus Workflow

MQSeries

OmniFind

Rational

Redbooks

Red Brick

RequisitePro

System i

System z

Tivoli

WebSphere

Workplace

System p

Adobe, Acrobat, Portable Document Format (PDF), and PostScript are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, other countries, or both.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other
countries, or both and is used under license therefrom.
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United
States, other countries, or both. See Java Guidelines
Microsoft, Windows, Windows NT, and the Windows logo are registered trademarks of Microsoft
Corporation in the United States, other countries, or both.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel
SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
ITIL is a registered trademark and a registered community trademark of the Office of Government
Commerce, and is registered in the U.S. Patent and Trademark Office.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications
Agency which is now part of the Office of Government Commerce.
Other company, product and service names may be trademarks or service marks of others.

Page 156

Discovering the value of IBM WebSphere DataPower SOA Appliances

NOTES

NOTES

Copyright IBM Corporation 2013.


The information contained in these materials is provided for
informational purposes only, and is provided AS IS without warranty
of any kind, express or implied. IBM shall not be responsible for any
damages arising out of the use of, or otherwise related to, these
materials. Nothing contained in these materials is intended to, nor
shall have the effect of, creating any warranties or representations
from IBM or its suppliers or licensors, or altering the terms and
conditions of the applicable license agreement governing the use of
IBM software. References in these materials to IBM products,
programs, or services do not imply that they will be available in all
countries in which IBM operates. This information is based on
current IBM product plans and strategy, which are subject to change
by IBM without notice. Product release dates and/or capabilities
referenced in these materials may change at any time at IBMs sole
discretion based on market opportunities or other factors, and are not
intended to be a commitment to future product or feature availability
in any way.
IBM, the IBM logo and ibm.com are trademarks or registered
trademarks of International Business Machines Corporation in the
United States, other countries, or both. If these and other IBM
trademarked terms are marked on their first occurrence in this
information with a trademark symbol ( or ), these symbols
indicate U.S. registered or common law trademarks owned by IBM at
the time this information was published. Such trademarks may also be
registered or common law trademarks in other countries. A current
list of IBM trademarks is available on the Web at Copyright and
trademark information at ibm.com/legal/copytrade.shtml
Other company, product and service names may be trademarks or
service marks of others.