WebSphere DataPower SOA Appliances


Version 3.7.3

Multi-Protocol Gateway Developers Guide

 WebSphere DataPower SOA Appliances


Version 3.7.3

Multi-Protocol Gateway Developers Guide

 Note
Before using this information and the product it supports, read the information in Notices and trademarks on page 377.

First Edition (May 2009)

This edition applies to version 3, release 7, modification 3 of IBM WebSphere DataPower SOA Appliances and to all
subsequent releases and modifications until otherwise indicated in new editions.
Copyright International Business Machines Corporation 2002, 2009.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . vii Creating for non-expiring, non-password-
Who should read this document . . . . . . . vii protected certificates . . . . . . . . . . 21
How this document is organized . . . . . . . vii Creating for select certificates . . . . . . . 21
Publications . . . . . . . . . . . . . . viii
Installation and upgrade documentation . . . viii Chapter 3. Configuring Multi-Protocol
Administration documentation . . . . . . . ix Gateway services . . . . . . . . . . 25
Development documentation. . . . . . . . ix Creating a Multi-Protocol Gateway . . . . . . 26
Reference documentation . . . . . . . . . ix Configuring basic settings . . . . . . . . 27
Integration documentation . . . . . . . . . x Changing network and cryptographic behavior 31
Problem determination documentation . . . . x Configuring processing parameters . . . . . 34
Supplemental documentation . . . . . . . . x Configuring HTTP header parameters . . . . 34
File naming guidelines . . . . . . . . . . . xi Configuring monitors . . . . . . . . . . 35
Object naming guidelines . . . . . . . . . . xi Configuring Web Services Addressing . . . . 36
Typeface conventions . . . . . . . . . . . xi Configuring Reliable Messaging . . . . . . 42
Configuring XML threat protection . . . . . 48
Chapter 1. WebGUI basics . . . . . . . 1 Using URL builders . . . . . . . . . . . 52
Objects on the appliance . . . . . . . . . . 1 Building an IMS Connect URL . . . . . . . 52
Working with objects . . . . . . . . . . . 1 Building an MQ URL . . . . . . . . . . 53
Accessing the WebGUI . . . . . . . . . . . 1 Building a TIBCO EMS URL. . . . . . . . 54
Welcome screen . . . . . . . . . . . . . 1 Building a WebSphere JMS URL . . . . . . 54
Common WebGUI conventions . . . . . . . . 2 Using a Load Balancer Group as a backend server 55
Working with referenced objects . . . . . . . 2
Working with lists of referenced objects . . . . 3 Chapter 4. Configuring handler objects 57
Viewing and editing local files during configuration 3 FTP Poller Front Side Handler . . . . . . . . 57
Viewing local files . . . . . . . . . . . 4 FTP Server Front Side Handler . . . . . . . . 60
Editing local files . . . . . . . . . . . . 4 Defining as transparent . . . . . . . . . 61
Common WebGUI tasks . . . . . . . . . . 4 Defining as virtual ephemeral . . . . . . . 63
Applying and saving changes . . . . . . . 4 Defining as virtual persistent . . . . . . . 66
Canceling changes . . . . . . . . . . . 4 HTTP Front Side Handler . . . . . . . . . 70
Resetting objects . . . . . . . . . . . . 5 HTTPS (SSL) Front Side Handler . . . . . . . 71
Deleting objects . . . . . . . . . . . . 5 IMS Connect Handler . . . . . . . . . . . 72
Exporting objects . . . . . . . . . . . . 5 MQ Front Side Handler . . . . . . . . . . 73
Viewing object-specific logs . . . . . . . . 5 NFS Poller Front Side Handler . . . . . . . . 75
Viewing object status . . . . . . . . . . 6 SFTP Server Front Side Handler . . . . . . . 77
Cloning services . . . . . . . . . . . . 6 Configuration considerations . . . . . . . 78
Accessing probe captures . . . . . . . . . 7 Authentication and authorization . . . . . . 78
SSH metadata variables . . . . . . . . . 78
Chapter 2. Securing communication . . 9 URL specifications with an SFTP handler . . . 79
Supported cryptographic formats . . . . . . . 9 Configuring an SFTP Server handler . . . . . 79
Working with keys and certificates . . . . . . . 9 Stateful Raw XML Handler . . . . . . . . . 80
Creating key-certificate pairs . . . . . . . . 9 Stateless Raw XML Handler . . . . . . . . . 81
Generating keys and certificates . . . . . . 10 TIBCO EMS Front Side Handler . . . . . . . 82
Exporting keys and certificates . . . . . . . 11 Using topic spaces . . . . . . . . . . . 82
Importing keys and certificates . . . . . . . 12 Configuring a TIBCO EMS handler . . . . . 82
Defining Certificate objects . . . . . . . . . 13 WebSphere JMS Front Side Handler . . . . . . 84
Defining Firewall Credentials objects . . . . . . 14 Using topics spaces . . . . . . . . . . . 84
Defining Identification Credentials objects . . . . 15 Configuring a WebSphere JMS handler . . . . 84
Defining Key objects . . . . . . . . . . . 16
Defining Profile objects . . . . . . . . . . 17 Chapter 5. Defining processing policies 87
Defining Shared Secret Key objects . . . . . . 18 Matching rules . . . . . . . . . . . . . 87
Defining SSL Proxy Profile objects . . . . . . . 19 Processing rules . . . . . . . . . . . . . 87
Creating a forward (or client) proxy . . . . . 19 Processing actions . . . . . . . . . . . . 88
Creating a reverse (or server) proxy . . . . . 19 Contexts . . . . . . . . . . . . . . . 91
Creating a two-way proxy . . . . . . . . 20 Context in processing rules . . . . . . . . 92
Working with Validation Credentials objects . . . 21 Context keywords . . . . . . . . . . . 92

Copyright IBM Corp. 2002, 2009 iii

Creating processing policies . . . . . . . . . 92 Adding a WS-Security UsernameToken . . . . 198
Defining processing actions . . . . . . . . . 94 Generating an LTPA token . . . . . . . . 199
AAA (aaa) action . . . . . . . . . . . 94 Generating a Kerberos SPNEGO token . . . . 200
Antivirus (antivirus) action . . . . . . . . 94 Requesting a TFIM token map. . . . . . . 200
Call processing rule (call) action . . . . . . 96
Checkpoint event (checkpoint) action . . . . . 97 Chapter 7. Managing files . . . . . . 201
Conditional (conditional) action . . . . . . 97 Directories on the appliance . . . . . . . . 201
Convert query parameters to XML (convert-http) Launching the File Management utility . . . . . 203
action . . . . . . . . . . . . . . . 99 Displaying directory contents . . . . . . . . 203
Cryptographic binary (cryptobin) action . . . 100 Creating a subdirectory . . . . . . . . . . 203
Decrypt (decrypt) action. . . . . . . . . 108 Deleting a directory . . . . . . . . . . . 204
Encrypt (encrypt) action . . . . . . . . . 110 Refreshing directory contents . . . . . . . . 204
Event-sink (event-sink) action . . . . . . . 124 Uploading files from the workstation . . . . . 204
Extract using XPath (extract) action . . . . . 125 Working with Java Key Stores . . . . . . . . 205
Fetch (fetch) action . . . . . . . . . . 125 Required software . . . . . . . . . . . 205
Filter (filter) action . . . . . . . . . . 126 Granting permissions. . . . . . . . . . 205
For-each (for-each) action . . . . . . . . 130 Types of key stores . . . . . . . . . . 205
Log (log) action . . . . . . . . . . . 133 Uploading a file from a Java Key Store . . . . 205
MQ header action . . . . . . . . . . . 133 Fetching files . . . . . . . . . . . . . 206
On error (on-error) action . . . . . . . . 138 Copying files . . . . . . . . . . . . . 206
Results actions . . . . . . . . . . . . 139 Renaming files . . . . . . . . . . . . . 207
Rewrite header (rewrite) action . . . . . . 142 Moving files . . . . . . . . . . . . . . 207
Route-type actions. . . . . . . . . . . 142 Viewing files . . . . . . . . . . . . . 208
Set variable (setvar) action . . . . . . . . 145 Editing files . . . . . . . . . . . . . . 208
Sign (sign) action . . . . . . . . . . . 145 Deleting files . . . . . . . . . . . . . 208
SLM (slm) action . . . . . . . . . . . 147
SQL (sql) action . . . . . . . . . . . 147
Chapter 8. Managing the configuration
Strip attachments (strip-attachments) action . . 148
Transform-type actions . . . . . . . . . 149 of the appliance . . . . . . . . . . 209
Validate (validate) action . . . . . . . . 155 Creating Include Configuration File objects . . . 209
Verify (verify) action . . . . . . . . . . 157 Creating Import Configuration File objects . . . 210
Defining reusable rules . . . . . . . . . . 158 Backing up and exporting configuration data . . . 211
Locating remote resources in actions. . . . . . 159 Backing up the entire appliance . . . . . . 212
Supported protocols in attachments . . . . . 159 Backing up domains . . . . . . . . . . 212
Specifying the location of remote resources . . 159 Exporting select objects . . . . . . . . . 213
Using the attachment protocol . . . . . . . 160 Copying or moving select objects . . . . . . 215
Format of the <results> element . . . . . . . 161 Managing configuration checkpoints . . . . . 216
Using the variable builder . . . . . . . . . 162 Defining number configuration checkpoints to
Debugging processing policies. . . . . . . . 163 allow . . . . . . . . . . . . . . . 216
Saving configuration checkpoints . . . . . . 217
Listing configuration checkpoints. . . . . . 217
Chapter 6. Defining an AAA Policy 165
Rolling back to a configuration checkpoint . . 218
Creating a new AAA Policy object . . . . . . 166
Deleting configuration checkpoints . . . . . 218
Defining identity extraction methods . . . . . 167
Importing configuration data . . . . . . . . 218
Defining the authentication method . . . . . . 173
Managing changes in configuration data . . . . 220
Mapping authentication credentials . . . . . . 180
Comparing configurations . . . . . . . . 220
Changing the authentication caching policy . . 181
Reading the change report . . . . . . . . 221
Defining resource extraction methods . . . . . 182
Reverting changes . . . . . . . . . . . 221
Mapping requested resources . . . . . . . . 183
Configuring deployment policies . . . . . . . 222
Defining the authorization method . . . . . . 185
Creating a Deployment Policy object . . . . 222
Changing the authorization caching policy . . 193
Using the deployment policy builder . . . . 223
Defining post processing activities . . . . . . 194
Specifying the matching statement . . . . . 224
Defining counters for authorized and rejected
messages . . . . . . . . . . . . . . 194
Defining logging for authorizations and Chapter 9. Managing monitors . . . . 225
rejections . . . . . . . . . . . . . . 194 Monitor types . . . . . . . . . . . . . 225
Running a custom style sheet . . . . . . . 195 Configuring message monitors . . . . . . . 226
Generating a SAML assertion . . . . . . . 195 Traffic definition . . . . . . . . . . . 227
Including an AP-REQ token to act as Kerberos Message Type . . . . . . . . . . . . 229
client . . . . . . . . . . . . . . . 196 Filter action . . . . . . . . . . . . . 230
Processing a WS-Trust SecurityContextToken Message Count Monitor . . . . . . . . . 230
request . . . . . . . . . . . . . . 196 Message Duration Monitor . . . . . . . . 233

iv IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Using Web services monitors . . . . . . . . 234 Processing Policy . . . . . . . . . . . . 323
Enabling statistics . . . . . . . . . . . 235 Policy Maps tab . . . . . . . . . . . 324
Configuring Web services monitors . . . . . 235 Processing Rule . . . . . . . . . . . . 324
Specifying dual thresholds . . . . . . . . 237 RADIUS Settings . . . . . . . . . . . . 326
NAS-identifier . . . . . . . . . . . . 326
Appendix A. Referenced objects . . . 239 Configuring RADIUS Settings . . . . . . . 326
AAA Policy . . . . . . . . . . . . . . 239 Schema Exception Map . . . . . . . . . . 327
Main tab . . . . . . . . . . . . . . 239 Rules tab . . . . . . . . . . . . . . 327
Identity tab . . . . . . . . . . . . . 242 SLM policies . . . . . . . . . . . . . 328
Authenticate tab . . . . . . . . . . . 244 SLM Credentials Class . . . . . . . . . 328
Map Credentials tab . . . . . . . . . . 250 SLM Resource Class . . . . . . . . . . 330
Resource tab. . . . . . . . . . . . . 251 SLM Action . . . . . . . . . . . . . 332
Map Resource tab . . . . . . . . . . . 252 SLM Schedule . . . . . . . . . . . . 332
Authorize tab . . . . . . . . . . . . 253 SLM Policy . . . . . . . . . . . . . 333
Post Processing tab . . . . . . . . . . 259 SOAP Header Disposition Table . . . . . . . 336
Namespace Mapping tab . . . . . . . . 262 SOAP Header Refine Instruction tab. . . . . 336
SAML Attributes tab . . . . . . . . . . 263 SQL Data Source . . . . . . . . . . . . 337
LTPA Attributes tab . . . . . . . . . . 263 High-level configuration. . . . . . . . . 337
Transaction Priority tab . . . . . . . . . 264 Defining the base configuration . . . . . . 337
Setting namespace mappings (XPath bindings) 264 Defining configuration parameters . . . . . 338
Defining SAML attributes . . . . . . . . 264 URL Rewrite Policy . . . . . . . . . . . 339
Adding LTPA user attributes . . . . . . . 265 URL Rewrite Rule tab . . . . . . . . . 339
Using an AAA Info file . . . . . . . . . 265 User Agent . . . . . . . . . . . . . . 342
IBM Tivoli Access Manager. . . . . . . . 270 Proxy Policy. . . . . . . . . . . . . 342
IBM Tivoli Federated Identity Manager. . . . 272 SSL Proxy Profile . . . . . . . . . . . 343
Working with Kerberos objects . . . . . . 274 Basic HTTP Authentication . . . . . . . . 344
XACML Policy Decision Point . . . . . . . 277 SOAP Action Policy . . . . . . . . . . 345
Conformance Policy . . . . . . . . . . . 279 Public Key Authentication Policy . . . . . . 345
Document Crypto Map . . . . . . . . . . 282 Allow Compression Policy . . . . . . . . 346
Namespace Mappings tab . . . . . . . . 283 Restrict to HTTP 1.0 Policy . . . . . . . . 347
HTTP Input Conversion Map . . . . . . . . 283 Inject Header Policy . . . . . . . . . . 347
Input Encoding tab . . . . . . . . . . 284 Chunked Uploads Policy . . . . . . . . 348
IMS Connect . . . . . . . . . . . . . 284 FTP Client Policies . . . . . . . . . . 349
Defining an LDAP Search Parameters object . . . 286 XML Manager . . . . . . . . . . . . . 352
Load Balancer Group . . . . . . . . . . . 287 Configure XML Manager objects . . . . . . 352
Health of member servers . . . . . . . . 287 Flushing the document cache . . . . . . . 353
Setting the health state with a variable . . . . 288 Flushing the stylesheet cache . . . . . . . 353
Configuring Load Balancer Group objects . . . 288 z/OS NSS Client . . . . . . . . . . . . 353
Matching Rule . . . . . . . . . . . . . 292 Creating the z/OS NSS Client . . . . . . . 354
Multi-Protocol Gateway object. . . . . . . . 294
Main tab . . . . . . . . . . . . . . 294 Appendix B. Cryptographic support in
Proxy Settings tab . . . . . . . . . . . 296 actions . . . . . . . . . . . . . . 357
Monitors tab . . . . . . . . . . . . 301 ID references . . . . . . . . . . . . . 357
Parser Limits tab . . . . . . . . . . . 301 EncryptedData tokens . . . . . . . . . . 357
HTTP Options tab . . . . . . . . . . . 302 Security token references . . . . . . . . . 358
HTTP Header Injection tab . . . . . . . . 304 X.509 certificates . . . . . . . . . . . 358
HTTP Header Suppression tab . . . . . . 304 Kerberos AP-REQ tokens . . . . . . . . 359
WS-Addressing tab . . . . . . . . . . 304 SAML assertions . . . . . . . . . . . 359
WS-ReliableMessaging tab . . . . . . . . 304 Signature confirmation . . . . . . . . . . 359
Stylesheet Parameter tab. . . . . . . . . 310 Generating a signature confirmation . . . . . 360
Peer Group . . . . . . . . . . . . . . 311 Verifying a signature confirmation . . . . . 360
Policy Parameters . . . . . . . . . . . . 312
Main tab . . . . . . . . . . . . . . 312 Appendix C. Working with variables 361
Policy Parameters tab . . . . . . . . . 312
Service variables . . . . . . . . . . . . 362
Processing Action . . . . . . . . . . . . 313
General service variables . . . . . . . . 362
Named Inputs tab . . . . . . . . . . . 321
Multi-Protocol Gateway and Web Service Proxy
Named Outputs tab . . . . . . . . . . 321
service variables . . . . . . . . . . . 362
Stylesheet Parameters tab . . . . . . . . 321
Configuration services service variables . . . 363
Processing Metadata . . . . . . . . . . . 322
Load balancer service variables . . . . . . 364
Main tab . . . . . . . . . . . . . . 322
Legacy MQ-specific service variables . . . . 364
Metadata Items tab . . . . . . . . . . 322

Contents v
 Multistep variables . . . . . . . . . . 365 Appendix D. Getting help and
Transaction variables . . . . . . . . . . . 366 technical assistance . . . . . . . . 375
Asynchronous transaction variables . . . . . 366 Searching knowledge bases . . . . . . . . . 375
Error handling transaction variables . . . . . 367 Getting a fix . . . . . . . . . . . . . . 375
Headers transaction variables . . . . . . . 368 Contacting IBM Support. . . . . . . . . . 376
Persistent connection transaction variables. . . 368
Routing transaction variables . . . . . . . 369
URL-based transaction variables . . . . . . 369
Notices and trademarks . . . . . . . 377
Web Services Management transaction variables 370 Trademarks . . . . . . . . . . . . . . 377
Extension variables . . . . . . . . . . . 370
System variables . . . . . . . . . . . . 372 Index . . . . . . . . . . . . . . . 379
List of available variables . . . . . . . . . 373

vi IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Preface
IBM WebSphere DataPower SOA Appliances are purpose-built, easy-to-deploy
network appliances that simplify, help secure, and accelerate your XML and Web
services deployments while extending your SOA infrastructure. These 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.

Who should read this document

This document is intended for Developers who manage the configuration of
Multi-protocol Gateway services, objects, and associated referenced objects on the
IBM WebSphere DataPower appliance. Developers should have the following
knowledge:
v Network architecture and concepts
v Internet protocols, including HTTP, TCP/IP, MQ
v Lightweight Directory Access Protocol (LDAP) and directory services
v Authentication and authorization
v XML and XSLT
v Web Services
v Web Services Security

Developers should also be familiar with SSL protocol, key exchange (public and
private), digital signatures, cryptographic algorithms, and certificate authorities.

This document assumes that an Administrator has installed and initially

configured the appliance as described in the IBM WebSphere DataPower SOA
Appliances: 9003: Installation Guide or in the IBM WebSphere DataPower SOA
Appliances: Type 9235: Installation Guide, depending on the model type.

How this document is organized

This document is organized across the following broad concepts:
v Chapter 1, WebGUI basics, on page 1
Provides basic informations about using the DataPower graphical interface,
which is referred to as the WebGUI, as well as information about performing
common tasks in the WebGUI.
v Chapter 2, Securing communication, on page 9
Provide information about securing communication to and from the DataPower
appliance. The appliance provide these capabilities with a combination of
utilities and objects.
v Chapter 3, Configuring Multi-Protocol Gateway services, on page 25
Provide detailed information about developing Multi-Protocol Gateway services
on a DataPower appliance.
v Chapter 4, Configuring handler objects, on page 57
Provides information about creating and managing front side protocol handlers.
v Chapter 5, Defining processing policies, on page 87

Copyright IBM Corp. 2002, 2009 vii

 Provides information about creating document processing policies.
v Chapter 6, Defining an AAA Policy, on page 165
Provides information about creating an AAA policy for a processing action.
v Chapter 7, Managing files, on page 201
Provides information about managing files on the appliance.
v Chapter 8, Managing the configuration of the appliance, on page 209
Provide information about managing the configuration of application domains
and importing and exporting configurations.
v Chapter 9, Managing monitors, on page 225
Providing information about managing monitors.
v Appendix A, Referenced objects, on page 239
Provides detailed information about configuring objects that are referenced while
developing services on a DataPower appliance.
v Appendix B, Cryptographic support in actions, on page 357
Provides information about cryptographic support in processing actions.
v Appendix C, Working with variables, on page 361
Provides information about using variables in document processing.
v Appendix D, Getting help and technical assistance
Provides details about contacting IBM Support.

Publications
The IBM WebSphere DataPower library is organized into the following categories:
v Installation and upgrade documentation
v Administration documentation on page ix
v Development documentation on page ix
v Reference documentation on page ix
v Integration documentation on page x
v Problem determination documentation on page x
v Supplemental documentation on page x

Installation and upgrade documentation

v IBM WebSphere DataPower SOA Appliances: 9003: Installation Guide
Provides instructions for installing and powering up the Type 7993 (9003)
appliance, creating a startup configuration script, and placing the appliance in
operation.
v IBM WebSphere DataPower SOA Appliances: Type 9235: Installation Guide
Provides instructions for installing and powering up the Type 9235 appliance,
creating a startup configuration script, and placing the appliance in operation.
v IBM WebSphere DataPower SOA Appliances: Type 9235: Hardware Problem
Determination and Service Guide
Provides information about diagnosing and troubleshooting hardware problems,
ordering consumable replacement parts, and replacing parts.
v IBM WebSphere DataPower SOA Appliances: Upgrade and Rollback Guide: Generation
2 Firmware
Provides instructions for upgrading Generation 2 firmware and for rolling back
firmware upgrades.

viii IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Administration documentation
v IBM WebSphere DataPower SOA Appliances: Appliance Overview
Provides an introduction and understanding of the IBM Websphere DataPower
SOA appliances.
v IBM WebSphere DataPower SOA Appliances: Administrators Guide
Provides instructions for using the DataPower GUI for managing user access,
network access, appliance configuration and system configuration of the
appliance.
v IBM WebSphere DataPower SOA Appliances: Hardware Security Module Guide
A user guide for using a Hardware Security Module (HSM) installed in the
appliance.

Development documentation
v IBM WebSphere DataPower SOA Appliances: XSL Accelerator Developers Guide
Provides instructions for using the WebGUI to configure XSL Proxy and XSL
Co-Processor services.
v IBM WebSphere DataPower SOA Appliances: XML Firewall Developers Guide
Provides instructions for using the WebGUI to configure XML Firewall services.
v IBM WebSphere DataPower SOA Appliances: Web Application Firewall Developers
Guide
Provides instructions for using the WebGUI to configure Web Application
Firewall services.
v IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers
Guide
Provides instructions for using the WebGUI to configure Multiple-Protocol
Gateway services.
v IBM WebSphere DataPower SOA Appliances: Web Service Proxy Developers Guide
Provides instructions for using the WebGUI to configure Web Service Proxy
services.
v IBM WebSphere DataPower SOA Appliances: B2B Gateway Developers Guide
Provides instructions for using the WebGUI to configure B2B Gateway services.
v IBM WebSphere DataPower SOA Appliances: Low Latency Messaging Developers
Guide
Provides instructions for using the WebGUI to configure a DataPower appliance
for low latency messaging.

Reference documentation
v Product-specific documentation for using commands from the command line.
The documentation is specific to each of the following products. Each document
provides an alphabetical listing of all commands with syntactical and functional
descriptions.
IBM WebSphere DataPower XML Accelerator XA35: Command Reference
IBM WebSphere DataPower XML Security Gateway XS40: Command Reference
IBM WebSphere DataPower XML Integration Appliance XI50: Command Reference
IBM WebSphere DataPower B2B Appliance XB60: Command Reference
IBM WebSphere DataPower Low Latency Messaging Appliance XM70: Command
Reference

Preface ix
 v IBM WebSphere DataPower SOA Appliances: Extension Elements and Functions
Catalog
Provides programming information about the usage of DataPower XSLT
extension elements and extension functions.

Integration documentation
The following documents are available for managing the integration of related
products that can be associated with the DataPower appliance:
v Integrating with ITCAM
Provides concepts for integrating the DataPower appliance with IBM Tivoli
Composite Application Management for SOA.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender
Provides concepts for integrating the DataPower appliance with WebSphere
Transformer Extender.
v IBM WebSphere DataPower SOA Appliances: Integrating with WebSphere MQ
Explains the concepts and common use patterns for connecting DataPower
services to WebSphere MQ systems.

Problem determination documentation

v IBM WebSphere DataPower SOA Appliances: Problem Determination Guide
Provides troubleshooting and debugging tools.

Supplemental documentation
v Understanding Web Services Policy
Provides conceptual information about how the DataPower appliance can use
Web Services Policy (WS-Policy).
v Understanding WS-Addressing
Provides conceptual information about how the DataPower appliance can use
WS-Addressing.
v Understanding LTPA
Provides conceptual information about how the DataPower appliance can use
Lightweight Third Party Authentication.
v Understanding SPNEGO
Provides conceptual information about how the DataPower appliance can use
SPNEGO.
v Optimizing through Streaming
Provides conceptual information about and procedures for optimizing the
DataPower appliance through streaming.
v Securing the Last Mile
Provides conceptual information about and procedures for understanding the
DataPower appliance while securing the last mile.
v Configuring the DoD PKI
Provides conceptual information about and procedures for configuring the
DataPower appliance with Department of Defense Public Key Infrastructure.

x IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

File naming guidelines
The maximum length for a file name can be approximately 4128 characters. The
name of the base file can be up to 128 characters in length. The base file is the part
after the name of the DataPower directory. Examples of directories are local:,
store:, and temporary:.

If the directory (or domain) supports subdirectories, the path to the file can have a
length of 4000 characters. When you create a domain, its name is the base file
name in several DataPower directories when viewed from the default domain.

The following characters are valid in directory and file names:

v a through z
v A through Z
v 0 through 9
v _ (underscore)
v - (dash)
v . (period)

Note: Names cannot contain two consecutive periods (..).

Object naming guidelines

The object name must be unique in the object namespace. The following characters
are valid in when specifying the name for an object:
v a through z
v A through Z
v 0 through 9
v _ (underscore)
v - (dash)
v . (period)

Note: Names cannot contain two consecutive periods (..).

Typeface conventions
The following typeface conventions are used in the documentation:
bold Identifies commands, programming keywords, and GUI controls.
italics Identifies words and phrases used for emphasis and user-supplied
variables.
monospaced
Identifies user-supplied input or computer output.

Preface xi
xii IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 1. WebGUI basics
The WebGUI is the primary interface for managing the appliance itself and for
configuring objects.

Objects on the appliance

Objects that can be configured on the appliance range from simple to complex. An
object is any entity that you configure on the appliance. During configuration, an
object can reference another object that can, in turn, reference another object. For
example, the configuration of a service references an instance of the XML Manager
object that references an instance of the User Agent object. The flexibility in
configuration and association of referenced object allow you to meet your
business-processing criteria and security requirements.

Working with objects

When configuring services on the appliance, the WebGUI provides an object view
and a service view. You can use either view to create or edit the service.
Service view
Working in the service view allows less-than-expert level users to build
basic, generic objects.
Object view
Working in the object view allows expert-level users to build specific,
complex and highly detailed objects.

Accessing the WebGUI

To use the WebGUI, the Web Management Interface must be configured. This
interface was defined during the initial firmware setup (during appliance
installation) or afterward with the web-mgmt command.

To access the WebGUI, use the following procedure:

1. Direct your browser to the WebGUI login screen. Use the IP address and port
number assigned during the configuration of the Web Management interface.
The address uses the HTTPS protocol and has the https://address:port
format.
2. In the login fields, specify an account name and password.
3. From the Domain list, select the domain to which to log in.
4. Click Login.

After verifying credentials, the WebGUI displays the Control Panel.

Welcome screen
After successfully logging in, the WebGUI displays its Welcome screen. Visibility of
objects in the WebGUI is controlled by a combination of the Role-based
management (RBM) object and whether the administrator is in the default domain
or an application domain.

Copyright IBM Corp. 2002, 2009 1

 This screen is separated into the following areas:
v The banner shows details about the administrator who logged in to the
appliance and contains the following controls:
The Domain list that allows the administrator to switch domains.
The Save Config button that allows the administrator to persist configuration
changes.
The Logout button that allows the administrator to end the WebGUI session.
v The navigation bar along the left side provides access to related configuration
suites and to related management suites. This area contains the following
menus:
The Control Panel returns the administrator to the Welcome screen.
The Status menu provides access to logs and status providers.
The Services menu provides access to service configuration objects and
objects referenced by service objects. When the administrator selects the item,
the WebGUI displays the service view for the object.
The Network menu provide access to network configuration objects. These
objects are to define the network in which the appliance connects. Many of
these objects are available in the default domain.
The Administration menu provides access to managing access to the
appliance as well as general appliance settings. Many of these objects are
available in the default domain.
The Objects menu provides access to service configuration objects and objects
referenced by service objects. When the administrator selects the item, the
WebGUI displays the object view for the object.
v The dashboard that is separated into the following areas:
The top area contains icons to access top-level objects for the appliance.
The middle area contains icons to access monitoring and troubleshooting
utilities.
The bottom area contains icons to access file management and administration
utilities.
When you click any icon on the dashboard or select any item from the menu,
the WebGUI replaces the dashboard with the details for the selected item.

Common WebGUI conventions

In addition to the standard interface controls, the WebGUI uses custom controls to
help during the configuration of objects. These controls generally pertain to
defining referenced objects.

Working with referenced objects

When using the WebGUI to create and modify objects, the configuration screen
might display an input field to select a referenced object. Figure 1 illustrates this
type of input field.

Input +

Figure 1. Input field for referenced objects

When the WebGUI displays this type of input field, you can specify the referenced
object in the following ways:
v Select the name of an existing referenced object from the list.

2 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 v Use the + button to create a new referenced object. When created, the input field
contains the name of the newly created referenced object.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.

When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.

Working with lists of referenced objects

When using the WebGUI to create or modify objects, the configuration screen
might display an input list to define a group of referenced objects. The input for
this configuration item is the list of referenced objects. Figure 2 illustrates this type
of input list.

Input

Delete Add +

Figure 2. Input list for referenced objects

When the WebGUI displays this type of list, you can manage referenced objects in
the following ways:
v Select the name of an existing referenced object from the list. Click Add to add it
to the list of referenced objects.
v Use the + button to create a new referenced object. When created, the input field
contains the name of the new referenced object. Click Add to add it to the list of
referenced objects.
v Use the ... button to modify the referenced object whose name is in the input
field. When modified, the input field retains the name of the referenced object.
Click Add to add it to the list of referenced objects.
v Select the name of a referenced object from the list (either the input field or the
list of referenced objects). Click Delete to remove it from the list of referenced
objects.

When you click the + button or ... button, the WebGUI launches a new window
that displays the configuration screen for that type of object.

Viewing and editing local files during configuration

As you use the WebGUI to select a local file during configuration, the
configuration screen might display the View and Edit buttons beside the selection
lists.

Working with files in this way has the following advantages:

v Ensure that the file is the one that you want
v Ability to edit the file to address errors found while defining a configuration
v Use a single session instead of opening another session to manage files through
the File Management utility

You cannot view or edit remote files.

Chapter 1. WebGUI basics 3

 Viewing local files
To view a local file, use the following procedure:
1. Select the file from the lists.
2. Click View to open the file editor in view mode.
3. Review the file.
4. Click Cancel.

Editing local files

The edited file overwrites the original file.

To edit a local file, use the following procedure:

1. Select the file from the lists.
2. Click Edit to open the file editor in edit mode.
3. Edit the file as required.
4. Click Submit to save changes.
5. Click Close.

Common WebGUI tasks

The majority of objects provide the following common tasks. Not all of these tasks
are available to all objects.
v Applying and saving configuration changes
v Canceling changes before saving to the running configuration
v Resetting changes to an object
v Deleting an object
v Exporting the configuration of an object
v Viewing object-specific logs
v Viewing object status
v Cloning a service
v Accessing probe captures

Applying and saving changes

As you use the WebGUI to manage object and service configurations, click Apply
to save these changes to the running configuration. Changes that are made to the
running configuration take effect immediately, but are not persisted to the startup
configuration. During an appliance restart these changes are lost.

To retain applied changes across an appliance restart, click Save Config. The
changes are saved to the startup configuration. The startup or persistent
configuration is persisted across an appliance restart. By default, the appliance
reads the startup configuration from the auto-config.cfg file.

Canceling changes
As you use the WebGUI to manage objects, click Cancel to not save the current
changes to the running configuration. If you click Cancel, you return to object
catalog and lose all changes.

4 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Resetting objects
Independent of whether the settings are saved to the configuration, you can reset
an object to its default configuration.

Use the following procedure to revert changes to a specific object:

1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object for which to reset to display the configuration
screen.
3. Click Undo.
4. Follow the prompts.

Deleting objects
You might want to delete objects that are no longer needed. If no other object
depends on the object to be deleted, you can delete it at any time. Because a
DataPower service is a top-level object, you can delete it at any time. Conversely,
you cannot delete an object that is active and that is in use by a higher-level object.

Use the following procedure to delete an object:

1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object to delete to display the configuration screen.
3. Click Delete.
4. Follow the prompts.

Deleting an object deletes that object only. Deleting an object does not delete any
referenced object.

Exporting objects
Use the following procedure to export an object:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object to export to display the configuration screen.
3. Click Export.
4. Follow the prompts.

Viewing object-specific logs

Instead of filtering the log for the default log or a configured log target, you can
view log messages that are specific to an object.

Viewing log files from the catalog

To view object-specific logs from the catalog, use the following procedure:
1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the magnifying glass icon.

Viewing log files from the configuration screen

To view object-specific logs from the configuration screen, click View Logs.

Chapter 1. WebGUI basics 5

 Viewing object status
You can view the status of an object and all its referenced objects to help determine
why a configuration object is in a down state. When you view the object status, the
WebGUI opens a new window. This window provides the ability to show or hide
unused properties.
v To show the unused properties, click Show.
v If the display lists unused properties, click Hide to hide these properties. Hiding
unused properties is the default behavior.

When viewing the object status, the window provides the following information:
v The name of the instance and its type with a control to collapse (hide) or expand
(show) referenced objects
v Its configuration state: New, Modified, or Saved
v It operational state: up or down
v Its administrative state: enabled or disabled
v Details about the detected error, if applicable
v A link (magnifying glass icon) to view the logs for this object

Use the following procedure to view the status for an object:

1. Display the catalog for the object. The catalog lists the available instances of
this object.
2. Click the name of the object to view to display the configuration screen.
3. Click View Status.

Cloning services
You might want to create a service that is similar to an existing service. For
example, you need two equivalent services, but each service communicates with a
different remote server. In these cases, you can create a clone of an existing service
and edit the clone. The cloning process can expedite the creation of a similar
service.

Use the following procedure to clone a server:

1. Display the catalog for the service. The catalog lists the available instances of
this service.
2. Click the name of the service to clone to display the configuration screen.
3. Click Clone.
4. When the screen refreshes, specify the name of the clone.
5. Specify the Ethernet interface that the service monitors for incoming client
requests in the Device Address field. Use the default address (0.0.0.0) to specify
all interfaces.
6. Specify the Ethernet port that the service monitors for incoming client requests
in the Device Port field.
7. As necessary, edit the other properties.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

6 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Accessing probe captures
After enabling the probe, defining the triggers, and sending transactions that
match the conditions defined by the triggers, you can view the captured
transactions.

Use the following procedure to access probe captures:

1. Display the catalog for the service object. The catalog lists the available
instances of this object.
2. Click the name of the service for which to view the probe captures to display
the configuration screen.
3. Click Show Probe.
4. Click the magnifying glass icon to view details about that captured
transactions.

For complete details about using the probe, refer to the IBM WebSphere DataPower
SOA Appliances: Problem Determination Guide.

Chapter 1. WebGUI basics 7

8 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 2. Securing communication
This chapter provide information about securing communication to and from the
DataPower appliance. The appliance provide these capabilities with a combination
of utilities and objects.

Supported cryptographic formats

Private key objects support the following formats:
v DER
v PEM
v PKCS #8
v PKCS #12

Certificate objects support the following formats:

v DER
v PEM
v PKCS #7
v PKCS #12

Neither key objects nor certificate objects directly support JKS or KDB formats.

Working with keys and certificates

The DataPower appliance provides actions that allow you to work with keys and
certificates. With the provided cryptographic tools, you can perform the following
actions:
v Create key-certificate pairs
v Generate keys and certificates
v Export keys and certificates
v Import keys and certificates

Unless you are using an appliance with HSM hardware, you cannot export or
import keys. For details about using an HSM-enabled appliance, refer to the IBM
WebSphere DataPower SOA Appliances: Hardware Security Module Guide.

Creating key-certificate pairs

When you generate a key, you get a key file and a Certificate Signing Request
(CSR) file. The CSR file from the initial key generation is not a signed certificate.
Send the CSR to a Certificate Authority (CA), such as VeriSign. The CA signs the
CSR and returns it to you, which effectively creates the certificate. Load this
certificate on the box.

In other words, use the following procedure to create the key-certificate pair:
1. Use the Crypto Tool to create the key and CSR
2. Store the private key on the box and create a Key object that references it.
3. Send the CSR to VeriSign. Do not store it on the box (except in the temporary:
directory).

Copyright IBM Corp. 2002, 2009 9

 4. VeriSign returns the signed certificate.
5. Store the signed certificate on the box and create a Certificate object that
references it.
6. Optionally, create an Identification Credentials object that references the key
and certificate objects.
When you create the Identification Credentials object, the key-certificate pair is
validated to ensure that pair is ready for use.

Generating keys and certificates

You can generate a private cryptographic key and optionally a self-signed
certificate from the Crypto Tools page. The Certificate Signing Request (CSR)
needed by a certificate authority (CA) is created by default.

If the file is stored in the cert: directory, it cannot be deleted or edited. If a file is
stored in the local: directory or in the temporary: directory, it can be deleted and
edited.

To generate a key, use the following procedure:

1. Select Administration Miscellaneous Crypto Tools to display the
Generate Key page.
2. Define the LDAP entry.
a. Use the LDAP (reverse) Order of RDNs toggle to indicate whether to
create the LDAP entry in reverse RDN order.
on Creates the entry in reverse RDN order.
off (Default) Create the entry in forward RDN order.
b. Optionally specify a country name in the Country Name (C) field.
c. Optionally specify a state or province name in the State or Province (ST)
field.
d. Optionally specify a locality name in the Locality (L) field.
e. Optionally specify the name of an organization in the Organization (O)
field.
f. Optionally specify the name of an organizational unit in the Organizational
Unit (OU) field.
g. Optionally specify the names of additional organizational units in the
Organizational Unit 2 (OU), Organizational Unit 3 (OU), and
Organizational Unit 4 (OU) fields.
h. Specify a common name in the Common Name (CN) field.
3. Select a key length from the RSA Key Length list. This defaults to 1024.
4. Specify the name of the key file to generate in the File Name field. The value
takes the directory:///name form. Leave blank to allow the action to create
the name.
5. Specify the number of days that the key is valid in the Validity Period field.
6. Specify a password to access the key file in the Password field. The password
must be at least 6 characters in length.
7. Specify a password alias to access the key file in the Password Alias field.
8. Use the Export Private Key toggle to indicate whether the action writes the
key file to the temporary: directory.
on Writes the key file to the temporary: directory.
off (Default) Does not write the key file to the temporary: directory.

10 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 9. Use the Generate Self-Signed Certificate toggle to indicate whether the action
creates a self-signed certificate that matches the key.
on (Default) Creates a self-signed certificate.
off Does not create a self-signed certificate.
10. Use the Export Self-Signed Certificate toggle to indicate whether the action
writes the self-signed certificate to the temporary: directory.
on (Default) Writes the self-signed certificate to the temporary: directory.
off Does not write the self-signed certificate to the temporary: directory.
11. Use the Generate Key and Certificate Objects toggle to indicate whether the
action automatically creates the objects from the generated files.
on (Default) Creates the objects from the generated files.
off Does not create the objects from the generated files.
12. Specify the name for the Key and Certificate objects in the Object Name field.
Leave blank to allow the action to generate the names from from the input
information (based on the Common Name (CN) or File Name property).
13. Specify the name of an existing Key object in the Using Existing Key Object
field. If supplied and valid, the action generates a new certificate and a new
Certificate Signing Request (CSR) that is based on the key in the identified
Key object. In this case, the appliance does not generate a new key.
14. Click Generate Key to generate a private key and, if requested, a self-signed
certificate. A CSR is created automatically.
15. Follow the prompts.

The CSR can be submitted to a certificate authority (CA) to receive a certificate that
is based on this private key. This action creates the following files and objects:
v Creates the private key file in the cert: directory; for example,
cert:///sample-privkey.pem
v Creates the CSR in the temporary: directory; for example, temporary:///
sample.csr
v If Generate Self-Signed Certificate is enabled, creates a self-signed certificate in
the cert: directory; for example, cert:///sample-sscert.pem
v If Export Self-Signed Certificate is enabled, creates a copy of the self-signed
certificate in the temporary: directory; for example, temporary:///sample-
sscert.pem
v If Generate Key and Certificate Objects is enabled, creates a Key object and a
Certificate object

If the action creates a self-signed certificate, you can use this certificate-key pair for
the following purposes:
v Establish Identification Credentials
v Encrypt or decrypt XML documents

Exporting keys and certificates

Use the Export Crypto Objects tab of the Crypto Tools screen to export key and
certificate objects.

Note: If the appliance has HSM hardware, you can export Key objects. For details,
refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module
Guide.

Chapter 2. Securing communication 11

 1. Select Administration Miscellaneous Crypto Tools to display the Crypto
Tools screen.
2. Click the Export Crypto Object tab.
3. Provide the following information:
Object Type
Select the type of object to export. Any appliance can export certificates.
Devices with HSM hardware can export private keys.
Object Name
Type the exact name of the object. To view a list of all such objects,
select Objects Crypto Objects Cryptographic Certificate (or Key).
Output File Name
Specify the name of a export package to contain the exported objects.
Do not specify a local directory or file extension. The appliance writes
the file to the temporary: directory.
Encryption Mechanism
Select Key-Wrapping-Key.

Note: Available when the appliance has HSM hardware to specify the
encryption mechanism to export private keys.
4. Click Export Crypto Object to create the export package with the selected
object.

Use the File Management utility to access the file.

Importing keys and certificates

Use the Import Crypto Objects tab of the Crypto Tools screen to import key and
certificate objects.

Objects that are exported from one DataPower appliance can be imported to
another appliance. Importing objects, rather than uploading files, eliminates the
need to create objects from files.

Note: If the appliance has HSM hardware, you can import Key objects. For details,
refer to IBM WebSphere DataPower SOA Appliances: Hardware Security Module
Guide.
1. Select Administration Miscellaneous Crypto Tools to display the Crypto
Tools screen.
2. Click the Import Crypto Object tab.
3. Provide the following information:
Object Type
Select the type of object to import. Any appliance can import
certificates. Devices with HSM hardware can import private keys.
Object Name
Specify the name of the object to create on import. This name must be a
unique in the object namespace.
Input File Name
Use the controls to select the export package. If the file does not reside
on the DataPower appliance, click Upload or Fetch to transfer the file.

12 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 Password
Optionally specify a password for accessing the file. Any entity or
agent needing to access the file must supply this password.
Password Alias
The password can optionally be given an alias, providing a level of
indirection and thus additional security. If an alias is established, use
the alias instead of the actual password.
4. Click Import Crypto Object.

An object with the specified name is created. Otherwise, an error is returned.

Defining Certificate objects

A Certificate object that provides an added layer of security by supplying a
indirect reference (or alias) to a certificate file. The alias provided by the Certificate
object is later used in the creation of a Firewall Credentials, an Identification
Credentials, or a Validation Credentials.

To create and configure a Certificate, use the following procedure:

1. Select Objects Crypto Crypto Certificate.
2. Click Add.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
File Name
Access a list of files, contained in the cert: or pubcert: file repository, and
select the file that contains the certificate referenced by this Certificate
object.
You can click Upload or Fetch to transfer the file.
You can also click Details to display information about the selected
certificate file.
Password
Depending of business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
v If key files are protected by a plaintext password, specify the password.

Note: Plaintext passwords appear as such in the configuration script.

v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a
locally-generated key to 3DES encrypt a password used to access a
private key file. The command maps the encrypted password to a
password alias in a password map file. The password map and the
locally-generated key are saved to separate files on the appliance.
Plaintext passwords are not stored in memory or saved on the appliance.

Chapter 2. Securing communication 13

 Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on Identifies the text as a password alias for an encrypted password.
off (Default) Identifies the text as a plaintext password.
Ignore Expiration Dates
Use these toggle to allow the creation of a certificate prior to its activation
date (the NotBefore value in the certificate) or after its expiration date (the
NotAfter value in the certificate).
off (Default) Prevents the creation of certificates outside of their
internal expiration values.
on Creates the certificate and places it in the up state. Although the
certificate is in the up state, objects that reference the certificate
use the internal expiration values. In other words, the certificate
itself is in the up state, but Validation Credentials, Firewall
Credentials, or Identification Credentials that references the
certificate adhere to the internal expiration values.
In other words, the certificate itself is in the up state, but
Validation Credentials, Firewall Credentials, or Identification
Credentials that references the certificate adhere to the internal
expiration values. If the certificate is used for a certificate chain
validation from a Validation Credentials and the certificate is not
valid, validation fails. Similarly, if the certificate is used from an
Identification Credentials, the DataPower appliance sends the
certificate to the SSL peer for an SSL connection, but the peer can
reject the certificate as not valid.
4. Click Apply to save the object to the running configuration and return to the
object catalog.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining Firewall Credentials objects

A Firewall Credentials consists of a list of Key objects and Certificate objects. A
Firewall Credentials provides a list of Key objects and Certificate objects.
Certificates and keys not referenced in the Firewall Credentials are unavailable. If
no Firewall Credentials exist, all keys and certificates stored locally are available.

To create a Firewall Credentials, use the following procedure:

1. Select Objects Crypto Crypto Firewall Credentials to display the Crypto
Firewall Credentials catalog.
2. Click Add to display the Crypto Firewall Credentials Configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Private Key
Use the list to add Key objects to the Firewall Credentials. Refer to
Defining Key objects on page 16 for more information.

14 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 Shared Secret Key
Use the list to add Shared Secret Key objects to the Firewall Credentials.
Refer to Defining Shared Secret Key objects on page 18 for more
information.
Certificates
Use the list to add Certificate objects to the Firewall Credentials. Refer to
Defining Certificate objects on page 13 for more information.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining Identification Credentials objects

An Identification Credentials consists of a Key object and a Certificate object. An
Identification Credentials identifies the matched public key cryptography public
and private keys used by an object for SSL authentication. An Identification
Credentials can be used in document encryption, document decryption, and digital
signature operations.

To create an Identification Credentials, use the following procedure:

1. Select Objects Crypto Crypto Identification Credentials to display the
Crypto Identification Credentials catalog.
2. Click Add to display the Crypto Identification Credentials Configuration
screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Crypto Key
Access a list of all Key objects, and select the Key object for this
Identification Credentials. Refer to Defining Key objects on page 16 for
more information.
Certificate
Access a list of all Certificate objects, and select the Certificate object for
this Identification Credentials. Refer to Defining Certificate objects on
page 13 for more information.
Intermediate CA Certificate
Intermediate CA certificates might be required when the CA that is
signing this certificate is not widely-recognized. If the intermediate CA
certificate is also signed by a less recognized CA, an additional
intermediate CA certificate might be required for that CA. You can specify
as many intermediate certificates as are required.
If necessary, use the list of available Certificate objects to establish a
verifiable trust-chain. A trust-chain consists of one or more Certification
Authority (CA) certificates and provides a linked path from the certificate
that is in the Identification Credentials to a CA that is trusted by a remote
appliance. The trust chain enables the appliance to authenticate the
certificate.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Chapter 2. Securing communication 15

Defining Key objects
A key is an object that provides an added layer of security by supplying a indirect
reference (or alias) to a file that contains a private key. The alias provided by the
Key object is later used in the creation of a Firewall Credentials object or an
Identification Credentials object.

To create and configure a Key object, use the following procedure:

1. Select Objects Crypto Crypto Key to display the Crypto Key catalog.
2. Click Add to display the Crypto Key Configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
File Name
Access a list of files (contained in the cert: file repository) and select the
file that contains the private key aliased by this Key object.
You can click Upload or Fetch to transfer the file.

Note: Keys can be retrieved from a Java Key Store residing on the local
workstation. Click Java Key Store on the Upload field. Refer to
IBM WebSphere DataPower SOA Appliances: Appliance Overview for
more information.
Password
Depending on business security policies, provide one of the following:
v If local security policies provide for password-protected keys, specify
the password (or a password alias).
v If local polices do not support password protection, leave blank.
v If key files are protected by a plaintext password, specify the password.

Note: Plaintext passwords appear as such in the configuration script.

v If key files are protected by an aliased password, specify the alias.
The CLI provides a password-map command that uses a locally-generated
key to 3DES encrypt a password used to access a private key file. The
command maps the encrypted password to a password alias in a
password map file. The password map and the locally-generated key are
saved to separate files on the appliance. Plaintext passwords are not
stored in memory or saved on the appliance.
Password Alias
Use the toggle to specify if the text entered in the Password field is a
plaintext password or a password alias.
on Identifies the text as a password alias for an encrypted password.
off (Default) Identifies the text as a plaintext password.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

16 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Defining Profile objects
A Profile object identifies a collection of SSL resources that support SSL
connections with remote peer appliances.

To create and configure a Profile object, use the following procedure:

1. Select Objects Crypto Crypto Profile to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Identification Credentials
Select the Identification Credentials to assign to this Profile object, or
retain the default value, none, when no Identification Credentials is
needed.
The Identification Credentials provides the PKI certificate-key pair that
will be used to authenticate the appliance during the SSL handshake.
Refer to Defining Identification Credentials objects on page 15 for more
information.
Validation Credentials
Select the Validation Credentials for this Profile object, or retain the
default value, none, when no Validation Credentials is needed. Refer to
Working with Validation Credentials objects on page 21 for more
information.
Ciphers
Use the field to identify the symmetric key-encryption algorithms for this
Profile object. Common cipher values are as follows:
ALL Includes all cipher suites, except the eNULL ciphers.
DEFAULT
Includes all cipher suites, except for the following ciphers and
cipher suites:
v eNULL ciphers
v Cipher suites that use DH authentication
v Cipher suites that contain the RC4, RSA, and SSL version 2
ciphers
HIGH Includes all high encryption cipher suites. These ciphers
support a key length in excess of 128 bits.
MEDIUM
Includes all medium encryption cipher suites. These ciphers
support a key length of 128 bits.
LOW Includes all low encryption cipher suites. These ciphers support
a key length of 56 or 64 bits, but exclude EXPORT cipher suites.
EXPORT
Includes all cipher suites that support a key length of 40 or 56 bits
and are eligible for export outside of the United States.

Chapter 2. Securing communication 17

 For a detailed list of ciphers, refer to the profile command in the
product-specific version of the Command Reference.
Options
Use the check boxes to disable support for SSL versions and variants. By
default, SSL Version 2, SSL Version 3, and Transaction Level Security
(TLS) Version 1 are enabled.
v To disable SSL Versions 2, click Disable-SSLv2.
v To disable SSL Version 3, click Disable-SSLv3.
v To disable TLS Version 1, click Disable-TLSv1.
Send Client CA List
Use the toggle to enable the transmission of a Client CA List during the
SSL handshake.

Note: Transmission of a Client CA List is meaningful only when this

Profile object supports a reverse (or server) proxy and when this
Profile object has an assigned Validation Credentials.
on Enables transmission of a Client CA List.
off (Default) Disables transmission of a Client CA List.
A Client CA List consists of a listing of the CA certificates in the
Validation Credentials for this Profile object. A Client CA List can be sent
by an SSL server as part of the request for a client certificate. The Client
CA list provides the client with a list of approved CAs whose signatures
are acceptable for authentication purposes.

Note: SSL servers are not required by the protocol to send a Client CA
List. Generally, SSL servers do not send a Client CA list.

Some implementations or local policies, however, might mandate

the use of Client CA lists.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining Shared Secret Key objects

A Shared Secret Key objects provides an added layer of security by supplying an
indirect reference (or alias) to a shared secret key. A shared secret key is used by
mutual agreement between a sender and receiver for encryption, decryption, and
digital signature purposes.

To create and configure a Shared Secret Key, use the following procedure:
1. Select Objects Crypto Crypto Shared Secret Key to display the Crypto
Shared Secret Key catalog.
2. Click Add to display the Crypto Shared Secret Key Configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.

18 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 File Name
Access a list of files (contained in the cert: file repository) and select the
file that contains the shared secret key aliased by this Shared Secret
Key.
You can click Upload or Fetch to transfer the file.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Defining SSL Proxy Profile objects

An SSL Proxy Profile defines a level of SSL service when operating as an SSL
proxy. The SSL proxy has the following modes:
forward
The SSL proxy acts as an SSL client (or acts in the forward direction). In
client proxy mode, SSL is used over the appliance-to-server connection.
reverse
The SSL proxy acts as an SSL server (or acts in the reverse direction). In
server proxy mode, SSL is used over the appliance-to-client connection.
two-way
The SSL proxy acts as both an SSL client and SSL server (or acts in both
directions). In two-way mode, SSL is used over the appliance-to-server
connection and the appliance-to-client-connection.

Creating a forward (or client) proxy

To create a forward SSL Proxy Profile, use the following procedure:
1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile
catalog.
2. Click Add to display the SSL Proxy Profile Configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Select Forward from the SSL Direction list.
6. Select the profile that defines SSL service to the backend server from the
Forward (Client) Crypto Profile list.
7. Use the Client-side Session Caching toggle to enable or disable client side
caching.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

Creating a reverse (or server) proxy

To create a reverse SSL Proxy Profile, use the following procedure:
1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile
catalog.
2. Click Add to display the SSL Proxy Profile Configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Select Reverse from the SSL Direction list.

Chapter 2. Securing communication 19

 6. Select the profile that defines SSL service to frontend clients from the Reverse
(Server) Crypto Profile list.
7. Use the Server-side Session Caching toggle to enable or disable server side
caching.
8. Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
9. Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
10. Use the Client Authentication is optional toggle to control when SSL client
authentication is optional.
on Client authentication is not required. When there is no client
certificate, the request does not fail.
off (Default) Requires client authentication only when the server
cryptographic profile has an assigned Validation Credentials.
11. Use the Always Request Client Authentication toggle to control when to
request SSL client authentication.
on Always requests client authentication.
off (Default) Requests client authentication only when the server
cryptographic profile has an assigned Validation Credentials.
12. Click Apply to save the object to the running configuration.
13. Optionally, click Save Config to save the object to the startup configuration.

Creating a two-way proxy

To create an SSL Proxy Profile, use the following procedure:
1. Select Objects Crypto SSL Proxy Profile to display the SSL Proxy Profile
catalog.
2. Click Add to display the SSL Proxy Profile Configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Select Two Way from the SSL Direction list.
6. Select the profile that defines SSL service to the backend server from the
Forward (Client) Crypto Profile list.
7. Select the profile that defines SSL service to frontend clients from the Reverse
(Server) Crypto Profile list.
8. Use the Server-side Session Caching toggle to enable or disable server side
caching.
9. Specify the time that session-specific state data is maintained in the server
cache in the Server-side Session Cache Timeout field.
10. Specify the maximum size of the server-side cache in the Server-side Session
Cache Size field.
11. Use the Client-side Session Caching toggle to enable or disable client side
caching.
12. Use the Client Authentication is optional toggle to control when SSL client
authentication is optional.
on Client authentication is not required. When there is no client
certificate, the request does not fail.

20 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 off (Default) Requires client authentication only when the server
cryptographic profile has an assigned Validation Credentials.
13. Use the Always Request Client Authentication toggle to control when to
request SSL client authentication.
on Always requests client authentication.
off (Default) Requests client authentication only when the server
cryptographic profile has an assigned Validation Credentials.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

Working with Validation Credentials objects

A Validation Credentials consists of a list of certificate objects. Validation
Credentials are used to validate the authenticity of received certificates and digital
signatures. You can create Validation Credentials with the following types of
credentials:
v All non-expiring, non-password-protected credentials
v Select credentials

Independent of which type of Validation Credentials, the creation starts at the

same location. To create any Validation Credential, select Objects Crypto
Crypto Validation Credentials.

Creating for non-expiring, non-password-protected certificates

You can create a Validation Credential includes all valid, non-expired,
non-password-protected certificates in the pubcert: file repository. The following
procedure silently creates a Certificate object for each valid certificate file in the
pubcert: file repository

To create this type of Validation Credentials, use the following procedure:

1. Select Objects Crypto Crypto Validation Credentials.
2. Click Create Validation Credential from pubcert: to display a confirmation
screen.
3. Click Confirm to create the Validation Credentials, with the appliance-supplied
name of pubcert.
4. After the WebGUI reports successful completion, click Close.

To refresh the Crypto Validation Credentials catalog, select Objects Crypto

Crypto Validation Credentials. Click Refresh List.

To save the Validation Credentials to the startup configuration, click Save Config.

Creating for select certificates

To prepare a Validation Credentials that contains selected certificate objects from
the pubcert: file repository, use the following procedure:
1. Select Objects Crypto Crypto Validation Credentials.
2. Click Add.
3. Provide the following inputs:
Name
Specify the name of the object.

Chapter 2. Securing communication 21

 Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Certificates
Use the list to add select Certificate objects to the Validation Credentials.
Certificate Validation Mode
Select one of the following modes:
Match exact certificate or immediate issuer
(Default) The behavior is that the Validation Credentials contains
either the exact peer certificate to match or the certificate of the
immediate issuer, which could be an intermediate CA or a root
CA. This mode is useful when you want to match the peer
certificate exactly, but that certificate is not a self-signed (root)
certificate.
Full certificate chain checking (PKIX)
The complete certificate chain is checked from subject to root
when using this Validation Credentials for certificate validation.
Validation succeeds only if the chain ends with a root certificate
in the Validation Credentials. Non-root certificates in the
Validation Credentials will be used as untrusted intermediate
certificates. Additional untrusted intermediate certificates will be
obtained dynamically from the context at hand (SSL handshake
messages, PKCS#7 tokens, PKIPath tokens, and so forth).
Use CRLs
Determines whether each Certificate Revocation List (CRL) is checked
during the processing of the certificate chain.
on (Default) Checks the CRLs.
off Does not check CRLs.
Require CRLs
When CRLs are checked during processing of the certificate chain,
determines whether the processing should fail when no CRL is available.
on Processing fails.
off (Default) Processing succeeds.
CRL Distribution Points Handling
Determines how to handle Certificate Revocation List (CRL) checking of
X.509 CRL Distribution Points extensions during processing of the
certificate chain and controls how to handle certificates in the Validation
Credentials.
Ignore Ignores extensions.
Require
Checks, but does not retrieve, extensions.
Initial Certificate Policy Set
When the mode is PKIX, defines the certificate chain validation input that
RFC 3280 calls the user-initial-policy-set. This set of OIDs specifies the
only allowable values of Certificate Policies at the end of chain
processing.

22 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 If you define an initial certificate policy set, you will want to enable the
Require Explicit Certificate Policy field. Otherwise, these certificate
policy sets will be used only when there are Policy Constraints extensions
in the certificate chain.
The default contains the OID for anyPolicy.
Require Explicit Certificate Policy
When the mode is PKIX, controls whether the validation chain
(algorithm) can end with an empty policy tree (that RFC 3280 calls the
initial-explicit-policy).
on The algorithm must end with a non-empty policy tree.
off The algorithm can end with an empty policy tree unless Policy
Constraints extensions in the chain require an explicit policy.
4. Click Apply to save the object to the running configuration and return to the
object catalog.
5. Optionally, click Save Config to save the object to the startup configuration.

Chapter 2. Securing communication 23

24 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 3. Configuring Multi-Protocol Gateway services
This chapter describes the Multi-Protocol Gateway service. A Multi-Protocol
Gateway service can accept client-originated messages in a variety of protocols.
The service can subsequently pass messages to a backend server using a variety of
protocols. The protocols that the client side uses do not need to be the same
protocols as those on the back side. A Multi-Protocol Gateway service supports the
following protocols:
FTP The service acts as either an FTP client, which polls a remote FTP server
for requests, or as an FTP server, which accepts incoming FTP connections.
This protocol is available on all appliances except Low Latency Appliance
XM70 appliances.
HTTP Including GET and POST. POST can contain XML, SOAP, DIME, SOAP
with Attachments. This protocol is available on all appliances.
HTTPS
Including GET and POST. POST can contain XML, SOAP, DIME, SOAP
with Attachments. This protocol is available on all appliances.
IMS The service can accept incoming IMS protocol requests and can initiate IMS
connections on the back side. This protocol requires the IMS license and is
available on XML Integration Appliance XI50 and B2B Appliance XB60
appliances.
MQ The service can use GET and PUT queues to communicate with MQ
queues. This protocol requires the MQ license and is available on all
appliances except XML Security Gateway XS40 appliances.
NFS The service can poll an NFS-mounted directory for the presence of new
files and can place responses on an NFS mounted directory. This protocol
is available on all appliances except Low Latency Appliance XM70
appliances.
SFTP The service can act as an SFTP server which allows SFTP clients to post to
and retrieve files from a backend file system. This protocol is available on
XML Integration Appliance XI50 and B2B Appliance XB60 appliances.
Stateful Raw XML
A stateful implementation that allows messages to flow from client to
backend server and back again using persistent connections. This protocol
is available on XML Security Gateway XS40 and XML Integration
Appliance XI50 appliances.
Stateless Raw XML
A stateless implementation that allows messages to flow from client to
backend server and back again using persistent connections. This protocol
is available on XML Security Gateway XS40 and XML Integration
Appliance XI50 appliances.
TIBCO EMS
Supports TIBCO Enterprise Messaging Service (EMS) messaging. This
protocol requires the TIBCO-EMS license and is available on all appliances
except XML Security Gateway XS40 appliances.

Copyright IBM Corp. 2002, 2009 25

 WebSphere JMS
Supports the WebSphere JMS messaging. This protocol requires the
WebSphere-JMS license and is available on all appliances except XML
Security Gateway XS40 appliances.

A Multi-Protocol Gateway service can support more than one client, or front side,
protocol. Similarly, the service can support more than one backend, or server,
protocol.

Figure 3 provides an illustration of the static backend architecture that the service
supports.

HTTP
HTTPS
HTTP or
MQ HTTPS or
Multi-Protocol Gateway MQ
Back End Server

Figure 3. Static backend architecture

Multi-Protocol Gateway services can accept client requests through any of the
protocol handlers that are shown (HTTP, HTTPS, or MQ). A static URL determines
the destination for all traffic. This server-side traffic can employ one of the
protocols that are shown (HTTP, HTTPS, or MQ).

When the backend service endpoint is dynamically determined, the gateway

supports a Stateful Raw XML protocol handler. Because the connection is stateful,
this protocol handler can only communicate with a backend service that also
employs the same protocol. Figure 4 shows other protocol handlers that the same
gateway can use to dynamically route to the other protocols.

HTTP

HTTP
HTTPS
HTTPS
MQ
MQ
Stateful
Multi-Protocol Gateway
Stateful

Back End Servers

Figure 4. Dynamic backend architecture

The messages can be processed and routed using any of the standard processing
actions that are available to a service.

Creating a Multi-Protocol Gateway

Creating a Multi-Protocol Gateway consists of the following tasks:
1. Configure the basic settings
2. Optionally modify the advanced Networking and cryptographic behavior
3. Optionally configure processing parameters

26 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 4. Optionally configure header and parameter settings, which includes adding
header injection parameters, adding header suppression parameters, and
defining stylesheet parameters
5. Optionally configure monitors
6. Optionally configure the mediation for Web Services Addressing between the
requesting clients and the responding server.
7. Optionally configure for Reliable Messaging
8. Optionally configure XML threat protection

Configuring basic settings

To configure a Multi-Protocol Gateway, use the following procedure:
1. Select the Multi-Protocol Gateway icon from the Control panel to display the
Multi-Protocol Gateway catalog.
2. Click Add to display the General configuration page.
3. Specify the gateway name in the Multi-Protocol Gateway Name field.
4. Optionally specify a brief description of this service in the Summary field.
5. Use the Type radio buttons to select the gateway type.
static-backend
(Default) Indicates support for a single backend server or for a load
balancer.
dynamic-backend
Indicates support for multiple backend servers. Backend servers are
configured with a route-action or route-set action in the processing
policy.
6. Select an XML Manager from the XML Manager list to assign an XML
manager. The XML Manager assigns capabilities such as load balancing and
the compile options policy. Refer to XML Manager on page 352 for
information about creating XML managers.
7. Optionally select a processing policy from the Multi-Protocol Gateway Policy
list.
Refer to Chapter 5, Defining processing policies, on page 87 for information
about creating or editing processing policies. Refer to Processing Policy on
page 323 for information about creating standalone, reusable processing
policies.
8. Optionally select a rewrite policy from the URL Rewrite Policy list.
This policy defines rules to rewrite the entire URL or a portion of the URL, to
replace a header value in the message, or to rewrite the HTTP POST body in
the message. The rewrite rules are applied before document processing.
Therefore, the evaluation criteria in the Matching Rule is against the rewritten
value.
Refer to URL Rewrite Policy on page 339 for more information.
9. If Type is static-backend, specify the URL of the backend server in the
Backend URL field. The URL is parsed to determine the protocol to use. To
use a load balancer, specify the name of an existing Load Balancer Group
instead of the host-port pair in the URL.
v If the URL starts with https://, the service uses the HTTPS protocol. This
protocol requires an SSL Proxy Profile.
v If the URL start with dpims:// or dpimsssl://, the service uses the IMS
Connect protocol.

Chapter 3. Configuring Multi-Protocol Gateway services 27

 v If the URL start with dpmq:// , the service uses the MQ protocol. If the URL
starts with mq://, the protocol is for a dynamic backend.
v If the URL start with dptibems:// or dptibemss://, the service uses the
TIBCO EMS protocol. If the URL starts with tibems://, the protocol is for a
dynamic backend.
v If the URL starts with dpwasjms:// or dpwasjmss://, the service uses the
WebSphere JMS protocol.
Click the IMS Connect Helper, MQ Helper, TIBCO EMS Helper, or
WebSphere JMS Helper button to launch a utility that assists in building the
protocol-specific, static URL.
v For information about using the utility to build an IMS Connect URL, refer
to Building an IMS Connect URL on page 52.
v For information about using the utility to build an MQ URL, refer to
Building an MQ URL on page 53.
v For information about using the utility to build a TIBCO EMS URL, refer to
Building a TIBCO EMS URL on page 54.
v For information about using the utility to build a WebSphere JMS URL,
refer to Building a WebSphere JMS URL on page 54.
10. Use the Front Side Protocol controls to assign one or more front side
handlers.
Protocol handlers establish the protocol for network communications and
assign an address and port number to which the service listens for incoming
requests. Refer to Chapter 4, Configuring handler objects, on page 57 for
more information.
11. Optionally select an SSL Crypto Profile from the SSL Client Crypto Profile
list. The service uses this cryptographic profile when acting as an SSL client
(that is, when using a secure connection to the backend). The cryptographic
profile provides the credentials that the service uses for secure communication.

Note: If a User Agent is in use by the selected XML Manager, that User Agent
might contain settings that override these SSL settings. Edit the XML
Manager to modify the User Agent that is in use. Refer to User Agent
on page 342 for more information.
12. Use the Response Type radio buttons to characterize the server-generated
response.
Non-XML
Does not directly characterize the server response, but indicates that
the service does not filter or transform the response. In other words,
the actions in the associated processing policy will not operate directly
on the message content. However, the processing policy will perform
such actions as authentication or routing. For SAML artifact
authentication or authorization, select this option.
Pass-Thru
Does not directly characterize the server response, but indicates that
the service does not filter or transform the response. The response is
passed to the target client.
SOAP (Default) Identifies the server response as a SOAP message.
XML Identifies the server response as unencapsulated XML.
13. Use the Back Attachment processing format radio buttons to specify the
attachment format.

28 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 Dynamic
(Default) Allows the service to read and determine the format of the
message that contain attachments. Conversion between MIME and
DIME is possible provided that attachments are available for
processing.
MIME Messages adheres to the MIME format. Conversion to DIME is
possible provided that attachments are available for processing.
DIME Messages adhere to the DIME format. Conversion to MIME is possible
provided that attachments are available for processing.
Detect Allows the service to read and determine the format of the message
data.
14. Specify the number of seconds that a connection with a server can remain idle
in the Back Side Timeout field. After the defined interval, the service closes
the connection. Use an integer in the range of 10 through 86400. The default is
120.
When using a Stateful Raw XML handler, specify a high timeout value to
ensure that the connection is not closed due to a timeout.
15. Use the Stream Output to Back radio buttons to select the desired streaming
behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the appropriate
backend.
Stream Messages
Begins to send the message to the backend before all processing is
complete. This behavior potentially increases processing speed. Select
this option when the assigned XML Manager has streaming enabled
or when streaming of attachments is enabled.
16. Use the HTTP Version to Server radio buttons to specify the HTTP protocol
version (HTTP 1.0 or HTTP 1.1) for server-side connections. The default is
HTTP 1.1.
17. Use the Propagate URI toggle to control the URI propagation behavior.
on (Default) Enables URI propagation. Enabling URI propagation is
meaningful in the following situations only:
v When the service is configured to use a static backend.
v When the service is configured to use a dynamic backend and
dynamic routing is set with a route with style sheet (route-action)
action in the processing policy. In this case, use the dp:set-target()
extension element to define that target backend server.
For the other dynamic routing options that are available with the
route-action and route-set actions, the URI is absolute.
off Disables URI propagation.
When enabled, the service rewrites the URI of the backend URL to the URI in
the client request. If URI propagation is enabled and the client submits
http://host/service and the backend URL is http://server/listener, the
URL is rewritten to http://server/service.

Notes:
v When enabled, any Matching Rule in a response processing rule
must match the rewritten URL.

Chapter 3. Configuring Multi-Protocol Gateway services 29

 v Any action in the processing policy can change the URI that is sent
to the backend server. The rewritten URI could override the
intended effect of this setting.
18. Use the Compression toggle to enable (on) or disable (off, the default) GZIP
compression negotiation with the backend server.
19. Use the Request Type radio buttons to characterize the client-generated
request.
Non-XML
Does not directly characterize the client request, but indicates that the
service does not filter or transform the response. In other words, the
actions in the associated processing policy will not operate directly on
the message content. However, the processing policy will perform
such actions as authentication or routing. For SAML artifact
authentication or authorization, select this option.
Pass-Thru
Does not directly characterize the client request, but indicates that the
service does not filter or transform the response. The request is passed
to the target server.
SOAP (Default) Identifies the client request as a SOAP message.
XML Identifies the client request as unencapsulated XML.
20. Use the Front attachment processing format radio button set to determine the
desired format.
Dynamic
(Default) Allows the service to read and determine the format of the
message that contain attachments. Conversion between MIME and
DIME is possible provided that attachments are available for
processing.
MIME Messages adheres to the MIME format. Conversion to DIME is
possible provided that attachments are available for processing.
DIME Messages adhere to the DIME format. Conversion to MIME is possible
provided that attachments are available for processing.
Detect Allows the service to read and determine the format of the message
data.
21. Specify the number of seconds that a connection with a client can remain idle
in the Front Side Timeout field. After the defined interval, the service closes
the connection. Use an integer in the range of 10 through 86400. The default is
120.
When using a Stateful Raw XML handler, specify a high timeout value to
ensure that the connection is not closed due to a timeout.
22. Use the Stream Output to Front radio buttons to select the desired streaming
behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the appropriate
client.
Stream Messages
Begins to send the message to the client before all processing is
complete. This behavior potentially increases processing speed. Select

30 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 this option when the assigned XML Manager has streaming enabled
or when streaming of attachments is enabled.
23. Click Apply to save the changes to the running configuration.
24. Optionally, click Save Config to save the object to the startup configuration.

All other configuration options have default values. A Multi-Protocol Gateway

service can be configured with only the options on the General page.

Changing network and cryptographic behavior

The configuration options on the Advanced page allow you to change advanced
Networking and cryptographic behavior. All of these options are optional, and all
have default values.

To modify these configuration options, use the following procedure:

1. Click the Advanced tab to display the Advanced configuration page.
2. Modify the following advanced Networking and cryptographic behaviors as
necessary:
Persistent Connections
Use this toggle to enable (on) or disable (off) HTTP persistent
connections. By default, persistent connections are enabled.
Loop Detection
Use this toggle to enable (on) or disable (off) loop-detection. Some
protocols allow loop-detection between hosts. Enable loop detection to
include the HTTP Via: header field. The value of this header field is
the name of the Web Service Proxy. By default, loop-detection is
disabled.
Follow Redirects
Use this toggle to enable (on) or disable (off) the following of
server-side redirects (such as HTTP 302) by the service. By default, the
service does not follow redirects. The number of redirects can be
limited by a User Agent that matches the backend URL that is in use.
Allow Chunked Uploads
Use this toggle to enable (on) or disable (off) the ability to send
Content-Type Chunked Encoded documents to the backend server.
When the service employs the HTTP 1.1 protocol, the body of the
document can be delimited by either Content-Length or chunked
encodings. While all servers will understand how to interpret
Content-Length, many applications will fail to understand Chunked
encoding. For this reason, Content-Length is the standard method used.
However doing so interferes with the ability of the service to fully
stream. To stream full documents towards the backend server, this
property should be turned on. However, the backend server must be
RFC 2616 compatible, because this feature cannot be renegotiated at run
time, unlike all other HTTP 1.1 features which can be negotiated down
at runtime if necessary. This property can also be enabled by
configuring a User Agent to enable it on a per-URL basis.
Process Backend Errors
Indicates whether to processing errors from the backend server.
Depending on the protocol, the backend service might return a
response code that indicates an error condition. For HTTP messages,
the response from the backend server might include a response body

Chapter 3. Configuring Multi-Protocol Gateway services 31

 that contains XML that provides more details about the error. For MQ
messages, the response from the backend MQ server does not provide a
response message.
on (Default) Ignores the error condition, and processes the
response rule.
off Notices the error condition during request processing, and
processes the error rule.
Front Persistent Connection Timeout
Sets the amount of time, in seconds, that a persistent connection can
remain idle on the front side before the service closes the connection.
Use an integer in the range of 0 through 18400. The default is 180.
Back Persistent Connection Timeout
Sets the amount of time, in seconds, that a persistent connection can
remain idle on the back side before the service closes the connection.
Use an integer in the range of 0 through 18400. The default is 180.
MIME Back Header Processing
Use this toggle to enable (on) or disable (off) MIME (Multi-Purpose
Internet Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any
protocol headers) can sometimes contain MIME headers before any
preamble and before the first MIME boundary in the body of the
message. These MIME headers can contain important information that
is not available in the protocol headers, such as the string identifying
the MIME boundary.
v When enabled, the Web Service Proxy processes these MIME headers.
v When enabled and there are no MIME headers, the Web Service
Proxy continues to try and parse the message with the available
protocol header information.
v When disabled and MIME headers are present in the body of the
message, these MIME headers are considered part of the preamble
and not used to parse out the message. If the protocol headers (such
as HTTP) indicate the MIME boundaries, the service can parse and
process individual attachments. If such information is not available,
no attachments can be parsed from the body of the message.
By default, MIME support is enabled.
MIME Front Header Processing
Use this toggle to enable (on) or disable (off) MIME (Multi-Purpose
Internet Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any
protocol headers) can sometimes contain MIME headers before any
preamble and before the first MIME boundary contained in the body of
the message. These MIME headers can contain important information
not available in the protocol headers, such as the string identifying the
MIME boundary.
v When enabled, the Web Service Proxy processes these MIME headers.
v When enabled and there are no MIME headers in the message, the
Web Service Proxy continues to try and parse the message with the
available protocol header information.
v When disabled and MIME headers are present in the body of the
message, these MIME headers are considered part of the preamble

32 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 and not used to parse out the message. If the protocol headers (such
as HTTP) indicate the MIME boundaries, the service can parse and
process individual attachments. If such information is not available,
no attachments can be parsed from the body of the message.
By default, MIME support is enabled.
Gateway Credentials
Optionally assign a Firewall Credentials List. Refer to Defining
Firewall Credentials objects on page 14 for more information.
Default parameter namespace
Optionally specify the default XML namespace for parameters made
available to this Gateway via the CLI or WebGUI. The default
namespace is http://www.datapower.com/param/config.
Query parameter namespace
Optionally use this field to identify the default XML namespace for
parameters made available to this gateway via a URL query string. The
default namespace is http://www.datapower.com/param/query.
SOAP Schema URL
When the traffic type is SOAP, the SOAP Schema URL field appears.
Use this field to specify the full URL to the schema to validate the
SOAP schema for SOAP-formatted messages. When a service is in
SOAP mode, either on the request or response side, it validates
incoming messages against a W3C Schema for SOAP messages. You can
customize the schema to use by changing this property. Change the
schema to accommodate nonstandard configurations or special cases.
Message Processing Modes
Optionally select the check box for one or more message processing
modes.
Request rule in order
Enforces first-in first-out serial processing of messages for
actions in the request rule. The appliance initiates and
completes request rule processing for messages in the order
that they were pulled from the frontend request queue. The
appliance starts the request rule for the second message in the
request queue only after it completes the processing of the first
message. The backend request queue accepts whatever message
arrives first, except when you enforce Backend in order serial
processing. In that case, the appliance buffers messages so that
it sends messages to the backend request queue in the same
order that they were pulled from the frontend request queue.
Backend in order
Enforces the serial processing of messages delivered to the
backend request queue. If needed, the appliance will buffer
messages that complete request rule processing out of order
and only deliver messages to the backend request queue in the
same order that they were pulled from the frontend request
queue.
Response rule in order
Enforces serial processing of messages for actions in the
response rule. The appliance initiates and completes response
rule processing for messages in the order that they were pulled
from the backend reply queue. The appliance starts the

Chapter 3. Configuring Multi-Protocol Gateway services 33

 response rule for the second message in the reply queue only
after it completes the processing of the first message. The
appliance always buffers messages so that it sends messages to
the frontend reply queue in the same order that they were
pulled from the backend reply queue.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Configuring processing parameters

Some style sheets that are used during processing might take parameter inputs.
You can specify parameter-value pairs and make these pairs available to processing
resources (for example, style sheets) that are used by this gateway.

To specify parameter-value pairs used to process resources, use the following

procedure:
1. Click the Stylesheet Params tab to display the Stylesheet Parameters catalog.
2. If required, use the following procedure to define additional processing
parameters:
a. Click Add.
b. Use either the Parameter Name list or the Custom Name field to provide
the parameter name.
The Parameter Name list provides the following list of common parameters
used by the supplied style sheets for cryptographic processing:
decryptkey
Identifies the private key used for decryption operations
keypair-cert
Identifies the certificate used for signing operations
keypair-key
Identifies the private key used for signing operations
recipient
Identifies the certificate used for encryption operations
valcred
Identifies the Validation Credentials Set used for authentication
c. Use the Custom Name field to provide the name of an unlisted parameter.
d. Use the Parameter Value field to specify the value for the target parameter.
e. Click Submit to return to the Stylesheet Parameters catalog.
3. To specify additional parameter, repeat step 2.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Configuring HTTP header parameters

To configure the ability to inject HTTP protocol headers or suppress HTTP protocol
headers, use the configuration options available on the Headers configuration
page.

Adding Header Injection parameters

To add a proprietary header field into the gateway-to-client or gateway-to-server
HTTP stream, use the following procedure:
1. Click the Headers tab to display the headers settings.

34 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 2. In the Header Injection Parameter section, click Add to display the Header
Injection Property window.
3. To define a header injection parameter, provide the following inputs:
Direction
Select the direction of the message.
Back
(Default) Indicates a request that travels from the DataPower
appliance to the server.
Front
Indicates a response that travels from the DataPower appliance to
the client
Header Name
Specify the name of the proprietary header.
Header Value
Specify the value for the proprietary header.
4. Click Submit to return to the Header Injection Panel, which now list the data
for the new header field.
5. To specify additional header injection parameters, repeat steps 2 and 4.
6. Click Apply to save the changes to the running configuration.
7. Optionally, click Save Config to save the object to the startup configuration.

Adding Header Suppression parameters

To delete a header field from the gateway-to-client or gateway-to-server HTTP
stream, use the following procedure:
1. If not on the header configuration page, click the Headers tab to display the
HTTP Headers settings.
2. In the Header Suppression Parameters section, click Add to display the New
Header Suppression Parameter window.
3. To define a header suppression parameter, provide the following inputs:
Direction
Select the direction of the message.
Back
(Default) Indicates a request that travels from the DataPower
appliance to the server.
Front
Indicates a response that travels from the DataPower appliance to
the client
Header Tag
Specify the name of the target header (the header field to be deleted).
4. Click Submit to return to the Proxy Header Suppression Panel, which now list
the newly specified header field data.
5. To specify additional header suppression parameters, repeat steps 2 and 3.
6. Click Apply to save the changes to the running configuration.
7. Optionally, click Save Config to save the object to the startup configuration.

Configuring monitors
You can optionally assign traffic monitors to the gateway. Monitors provide the
ability to track and respond to load conditions.

Chapter 3. Configuring Multi-Protocol Gateway services 35

 Note: When you configure a monitor i to disallow inbound traffic after reaching a
defined threshold, the gateway continues to accepts messages and discards
them.

To assign traffic monitors to the service, use the following procedure:

1. Click the Monitors tab to display the monitors configuration page.
2. Use the Message Count Monitor list with the Add and Delete buttons to
assign a Message Count Monitor to the service. Refer to Message Count
Monitor on page 230 for more information.
3. Use the Message Duration Monitor list with the Add and Delete buttons to
assign a Message Duration Monitor to the service. Refer to Message Duration
Monitor on page 233 for more information.
4. Use the Gateway Service Level Monitor list with the Add and Delete buttons
to assign a Service Level Monitor to the service. Refer to SLM policies on
page 328 for more information.
5. Use the Monitors Evaluation Method list to determine how the monitors
interact with each other when a service uses more than one monitor.
Terminate at First Throttle
(Default) Allows all monitors to take effect on a message until a
monitor takes a Shape or Reject action. No further monitors will take
effect after this point. The order of monitors thus matters. If three
monitors are included, and the first monitor in the list either Shapes or
Rejects a message, no other monitors will execute.
Terminate at First Match
Allows all monitors to take effect until a monitor matches a message.
At that point, all monitor processing of the message stops. In this way,
only one monitor increments its counters.
6. Click Apply to the monitor configuration (or click Cancel to revert to the last
set of settings) and return to the general configuration page.

Configuring Web Services Addressing

To enable support for Web Services Addressing (WS-Addressing), click the
WS-Addressing tab to display the WS-Addressing screen. On this screen, specify
the WS-Addressing mode to provide. The level of support is determined by the
WS-Addressing capabilities of the associated clients and servers. The DataPower
service provides the mediation, if any, between clients and servers.

Support for a specific level of WS-Addressing does not preclude simultaneous

support for traditional addressing formats.

Select the mode from the WS-Addressing Mode list.

No WS-Addressing
(Default) Disables WS-Addressing support. Both clients and servers use
traditional addressing. Requires no additional configuration.
Synchronous Gatewayed to WS-Addressing
Specifies that the DataPower service mediates addressing between clients
that use traditional addressing and servers that use WS-Addressing. Refer
to Configuring Traditional to WS-Addressing on page 37 for
configuration details.
WS-Addressing Gatewayed to Synchronous
Specifies that the DataPower service mediates addressing between clients

36 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 that use WS-Addressing and servers that use traditional addressing. Refer
to Configuring WS-Addressing to Traditional on page 38 for
configuration details.
Pure WS-Addressing
Specifies that the DataPower service mediates addressing between clients
and servers that use WS-Addressing. Refer to Configuring WS-Addressing
to WS-Addressing on page 40 for configuration details.

Configuring Traditional to WS-Addressing

When Synchronous Gatewayed to WS-Addressing, provide the following inputs:
Strip WS-Addressing Headers
Determines whether to remove all WS-Addressing headers from
server-generated responses before forwarding them to the client.

Note: WS-Reliable Messaging requires the termination of WS-Addressing

sequences. Changing the default value can break interoperability.
on (Default) Strips WS-Addressing headers.
off Forwards WS-Addressing headers as is.
WS-Addressing Message Generation Pattern
Specifies the request/response transmission model between the DataPower
service and the target server.
Synchronously
(Default) Identifies a synchronous exchange pattern in which the
server response is received over the same channel used by the
DataPower service to convey the client request.
Out-of-Band
Identifies an out-of-band exchange pattern in which the routing of
the response to the original client is handled by the target server
and does not pass through the DataPower service.
If selected, ensure that explicit (non-anonymous) client-originated
ReplyTo and FaultTo element values are preserved by the
DataPower service and passed intact to the server.
Asynchronously
Identifies an asynchronous exchange pattern in which the server
response is received over a different channel than the one used by
the DataPower service to convey the client request.
v Use the WS-Addressing Reply Point property to identify the
Front Side Handler to convey asynchronous server responses to
the original requesting clients.
v Use the WS-Addressing Asynchronous Reply Timeout property
to specify the maximum time for a server response.
Asynchronous HTTP Response Code
Specifies the HTTP Response Code sent to a client prior to transmitting the
actual asynchronous server response to close the original client channel.
If the server response to an HTTP client request is asynchronous, the
DataPower service must close the original HTTP channel with a valid
response code. After the channel is closed, the DataPower service forwards
the server-generated response or fault message to the client over a new
channel.
Use an integer in the range of 200 through 599. The default is 204.
Chapter 3. Configuring Multi-Protocol Gateway services 37
 WS-Addressing Asynchronous Reply Point
Select the Front Side Handler to receive asynchronous server responses,
and forward responses to the original client.
Use this property to specify the Front Side Handler that will receive the
asynchronous server response, and then forward the response to the
original client.
The Front Side Handler specified by this property can be programmatically
overridden by the var://context/__WSA_REQUEST/replyto variable.
WS-Addressing Asynchronous Reply Timeout
Specifies the maximum period of time to wait for an asynchronous
response before abandoning the transaction. Use an integer in the range of
1 through 4000000. The default is 120.
The timer value specified by this property can be programmatically
overridden by the var://service/wsa/timeout variable.

Click Apply to save the object to the running configuration and return to the object
catalog.

Optionally, click Save Config to save the object to the startup configuration.

Configuring WS-Addressing to Traditional

When WS-Addressing Gatewayed to Synchronous, provide the following inputs:
Rewrite WS-Addressing Reply To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing ReplyTo header. Use this property to modify the contents
of an incoming ReplyTo header that identifies the recipient endpoint of
response messages.
Select the URL Rewrite Policy used to manipulate the contents of the
original ReplyTo header.
Rewrite WS-Addressing Fault To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing FaultTo header. Use this property to modify the contents
of an incoming FaultTo header that identifies the recipient endpoint of
fault messages.
Select the URL Rewrite Policy used to manipulate the contents of the
original FaultTo header.
Rewrite WS-Addressing To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing To header. Use this property to modify the contents of an
incoming To header that identifies the message destination.
Select the URL Rewrite Policy used to manipulate the contents of the
original To header.
Strip WS-Addressing Headers
Determines whether to remove all WS-Addressing headers from
server-generated responses before forwarding them to the client.

Note: WS-Reliable Messaging requires the termination of WS-Addressing

sequences. Changing the default value can break interoperability.
on (Default) Strips WS-Addressing headers.
off Forwards WS-Addressing headers as is.
38 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Default WS-Addressing Reply-To
Forces the inclusion of the optional ReplyTo header in WS-Addressing
messages. Use this property to ensure that all messages contain the
optional WS-Addressing ReplyTo header that identifies the recipient
endpoint of a response message.
Because the WS-Addressing specifications do not require the inclusion of
the ReplyTo header, the DataPower service might receive messages that do
not contain a ReplyTo header or that contain the header with no value.
When this happens, the DataPower service modifies the WS-Addressing
message to include a ReplyTo header that contains the URL value specified
by this property.
If a default recipient endpoint of response messages is not explicitly
identified by this command, the DataPower service provides
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous (the
default value).
Default WS-Addressing Fault-To
Forces the inclusion of the optional FaultTo header in WS-Addressing
messages. Use this property to ensure that all messages contain the
optional WS-Addressing FaultTo header that identifies the recipient
endpoint of a response message.
Because the WS-Addressing specifications do not require the inclusion of
the FaultTo header, the service could receive messages that do not contain
a FaultTo header, or that contain the header with no value.
When this happens, the DataPower service modifies the WS-Addressing
message to include a FaultTo header that contains the URL value specified
by this property.
If a default recipient endpoint of response messages is not explicitly
identified by this command, the DataPower service provides
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous (the
default value).
Force Incoming WS-Addressing
Forces the inclusion of WS-Addressing headers into server-originated
traditionally addressed messages.
In WS-Addressing to Synchronous Mode, the DataPower service generally
handles a mix of Web Service addressed and traditionally addressed
messages. Use this property to ensure that all messages use
WS-Addressing.
on Converts traditionally addressed messages to WS-Addressing format
through the addition of reply-to and fault-to WS-Addressing
headers.
v The ReplyTo header will contain http://schemas.xmlsoap.org/ws/
2004/08/addressing/role/anonymous (the default value).
v The FaultTo header will contain http://schemas.xmlsoap.org/ws/
2004/08/addressing/role/anonymous (the default value).
off (Default) Disables the inclusion of WS-Addressing headers into
incoming client requests
Asynchronous HTTP Response Code
Specifies the HTTP Response Code sent to a client prior to transmitting the
actual asynchronous server response to close the original client channel.

Chapter 3. Configuring Multi-Protocol Gateway services 39

 If the server response to an HTTP client request is asynchronous, the
DataPower service must close the original HTTP channel with a valid
response code. After the channel is closed, the DataPower service forwards
the server-generated response or fault message to the client over a new
channel.
Use an integer in the range of 200 through 599. The default is 204.

Click Apply to save the object to the running configuration and return to the object
catalog.

Optionally, click Save Config to save the object to the startup configuration.

Configuring WS-Addressing to WS-Addressing

When Pure WS-Addressing, provide the following inputs:
Rewrite WS-Addressing Reply To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing ReplyTo header. Use this property to modify the contents
of an incoming ReplyTo header that identifies the recipient endpoint of
response messages.
Select the URL Rewrite Policy used to manipulate the contents of the
original ReplyTo header.
Rewrite WS-Addressing Fault To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing FaultTo header. Use this property to modify the contents
of an incoming FaultTo header that identifies the recipient endpoint of
fault messages.
Select the URL Rewrite Policy used to manipulate the contents of the
original FaultTo header.
Rewrite WS-Addressing To Header
Identifies the URL Rewrite Policy used to rewrite the contents of the
WS-Addressing To header. Use this property to modify the contents of an
incoming To header that identifies the message destination.
Select the URL Rewrite Policy used to manipulate the contents of the
original To header.
Default WS-Addressing Reply-To
Forces the inclusion of the optional ReplyTo header in WS-Addressing
messages. Use this property to ensure that all messages contain the
optional WS-Addressing ReplyTo header that identifies the recipient
endpoint of a response message.
Because the WS-Addressing specifications do not require the inclusion of
the ReplyTo header, the service could receive messages that do not contain
a ReplyTo header, or that contain the header with no value.
When this happens, the DataPower service modifies the WS-Addressing
message to include a ReplyTo header that contains the URL value specified
by this property.
If a default recipient endpoint of response messages is not explicitly
identified by this command, the DataPower service provides
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous (the
default value).

40 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Default WS-Addressing Fault-To
Forces the inclusion of the optional FaultTo header in WS-Addressing
messages. Use this property to ensure that all messages contain the
optional WS-Addressing FaultTo header that identifies the recipient
endpoint of a response message.
Because the WS-Addressing specifications do not require the inclusion of
the FaultTo header, the service could receive messages that do not contain
a FaultTo header or that contain the header with no value.
When this happens, the DataPower service modifies the WS-Addressing
message to include a FaultTo header that contains the URL value specified
by this property.
If a default recipient endpoint of response messages is not explicitly
identified by this command, the DataPower service provides
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous (the
default value).
Force Incoming WS-Addressing
Forces the inclusion of WS-Addressing headers into server-originated
traditionally addressed messages.
In WS-Addressing to Synchronous Mode, the DataPower service generally
handles a mix of Web Service addressed and traditionally addressed
messages.
Use this property to ensure that all messages use WS-Addressing.
on The DataPower service converts traditionally addressed messages to
WS-Addressing format through the addition of reply-to and
fault-to WS-Addressing headers.
v The ReplyTo header will contain http://schemas.xmlsoap.org/ws/
2004/08/addressing/role/anonymous (the default value).
v The FaultTo header will contain http://schemas.xmlsoap.org/ws/
2004/08/addressing/role/anonymous (the default value).
off (Default) Disables the inclusion of WS-Addressing headers into
incoming client requests
WS-Addressing Message Generation Pattern
Specifies the request/response transmission model between the DataPower
service and the target server.
Synchronously
(Default) Identifies a synchronous exchange pattern in which the
server response is received over the same channel used by the
DataPower service to convey the client request.
Out-of-Band
Identifies an out-of-band exchange pattern in which the routing of
the response to the original client is handled by the target server and
does not pass through the DataPower service.
If selected, ensure that explicit (non-anonymous) client-originated
ReplyTo and FaultTo element values are preserved by the DataPower
service and passed intact to the server.
Asynchronously
Identifies an asynchronous exchange pattern in which the server
response is received over a different channel than the one used by
the DataPower service to convey the client request.

Chapter 3. Configuring Multi-Protocol Gateway services 41

 v Use the WS-Addressing Reply Point property to identify the Front
Side Handler to convey asynchronous server responses to the
original requesting clients.
v Use the WS-Addressing Asynchronous Reply Timeout property to
specify the maximum time for a server response.
Asynchronous HTTP Response Code
Specifies the HTTP Response Code sent to a client prior to transmitting the
actual asynchronous server response to close the original client channel.
If the server response to an HTTP client request is asynchronous, the
DataPower service must close the original HTTP channel with a valid
response code. After the channel is closed, the DataPower service forwards
the server-generated response or fault message to the client over a new
channel.
Use an integer in the range of 200 through 599. The default is 204.
WS-Addressing Asynchronous Reply Point
Select the Front Side Handler that receives asynchronous server responses,
and forwards such responses to the original client. Use this property to
specify the Front Side Handler that will receive the asynchronous server
response, and then forward the response to the original client.
The Front Side Handler specified by this property can be programmatically
overridden by the var://context/__WSA_REQUEST/replyto variable.
WS-Addressing Asynchronous Reply Timeout
Specifies the maximum period of time to wait for an asynchronous
response before abandoning the transaction. Use an integer in the range of
1 through 4000000. The default is 120.
The timer value specified by this property can be programmatically
overridden by the var://service/wsa/timeout variable.

Click Apply to save the object to the running configuration and return to the object
catalog.

Optionally, click Save Config to save the object to the startup configuration.

Configuring Reliable Messaging

To enable support for Web Service Reliable Messaging (WS-ReliableMessaging) for
this DataPower service, click the WS-ReliableMessaging tab to display the
WS-ReliableMessaging screen.

Use this screen to specify the WS-ReliableMessaging configuration that this

DataPower service is to provide.
Use WS-ReliableMessaging
Enable or disables Web Services Reliable Messaging.
on Enables Reliable Messaging.
off (Default) Disables Reliable Messaging

When enabled, the WebGUI displays the following inputs:

Target Sequence Expiration Interval
Sets the target expiration lifetime in seconds for all Reliable Messaging
sequences.

42 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 If an incoming CreateSequence SOAP message has an Expires lifetime that
is longer than this value, the value in the SequenceResponse SOAP message
is reduced to this value. The same process applies to the Expires lifetime
in any accepted Offer in an incoming CreateSequence and for the
requested Expires value in any CreateSequence SOAP call that is made to
the client or server from a Reliable Messaging source. This implementation
never requests or accepts a non-expiring sequence (a value of PT0S that
represents zero seconds).
The default is 3600.
AAA Policy
Selects the AAA Policy to perform authentication of incoming Reliable
Messaging messages. This AAA Policy can be the same one that is used in
later processing by the request or response rule. The results are cached, so
it is not evaluated again.
While this is focused on protecting the Reliable Messaging control
messages, such as CreateSequence and TerminateSequence, it is also run on
incoming Reliable Messaging data messages, with a Sequence header. This
prevents unauthorized clients from using appliance resources by issuing
CreateSequence requests, or from disrupting existing Reliable Messaging
sequences with CloseSequence or TerminateSequence messages, or from
falsely acknowledging messages with SequenceAcknowledgement messages.
SSL session binding
Indicates whether to use an SSL session binding to protect sequence
lifecycle messages.
All Reliable Messaging control messages and sequence messages are bound
to the original SSL/TLS session that is created by the Reliable Messaging
source to transmit the CreateSequence control message. Sequence messages
that are received by the Reliable Messaging destination with the correct
identifier but on a different SSL/TLS session are rejected.
The lifetime of a SSL/TLS protected sequence is bound by the lifetime of
the SSL/TLS session this is used to protect that sequence.
on Uses an SSL session binding.
off (Default) Does not use an SSL session binding.
Destination Accept Incoming CreateSequence
Indicates whether to accept incoming CreateSequence SOAP requests and
create a Reliable Messaging destination when one is received.
on (Default) Enables this feature. If enabled, both the client and the
server can use Reliable Messaging to send messages to this
DataPower service.
off Disables this feature. If disabled, the client cannot use Reliable
Messaging to communicate with this DataPower service. If
disabled, the only way that a Reliable Messaging destination can
be created on this DataPower service is when the Reliable
Messaging source is configured to make offers. In this case an
Offer and Accept can create a Reliable Messaging destination for
the server to send Reliable Messaging messages to the client.
Destination Maximum Simultaneous Sequences
Sets a limit on the maximum number of simultaneously active sequences to
Reliable Messaging destinations of this DataPower service. Attempts by

Chapter 3. Configuring Multi-Protocol Gateway services 43

 clients to create sequences in excess of this limit result in a SOAP Faults.
This property controls memory resource utilization.
The default is 400.
Destination InOrder Delivery Assurance
Indicates whether to enable InOrder delivery assurance for Reliable
Messaging destinations in addition to the standard ExactlyOnce delivery
assurance. No messages will be passed from the receive queue for further
processing unless their sequence number as assigned by the client is one
greater than the last one that was processed. InOrder delivery assurance
increases memory and resource utilization by the Reliable Messaging
destination.
on Enables InOrder and ExactlyOnce delivery assurance.
off (Default) Enables ExactlyOnce delivery assurance only.
When enabled, the WebGUI displays the following input:
Destination Maximum InOrder Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue beyond a gap in the received sequence numbers.
Use an integer in the range of 1 through 256. The default is 10.
This property controls memory utilization.
Destination Accept Two-Way Offers
Indicates whether to accept offers for two-way Reliable Messaging in
CreateSequence SOAP requests. If the request includes an offer, the
creation of a Reliable Messaging destination creates a Reliable Messaging
source to send responses to the client.
on Accepts two-way requests.
off (Default) Does not accept two-way requests.
When enabled, the WebGUI displays the following inputs:
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets the initial timeout.
off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.

44 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 30.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.
The default is 3.
Required on Request
Indicates whether to require the use of Reliable Messaging for all SOAP
messages that request rules process. The client must establish a sequence
with a CreateSequence SOAP call and must include a Sequence in each
SOAP header. Any SOAP message without a Sequence results in a SOAP
fault.
on Requires Reliable Messaging for all requests.
off (Default) Does not require Reliable Messaging for all requests.
Required on Response
Indicates whether to require the use of Reliable Messaging for all SOAP
messages that response rules process. Any SOAP message without a
Sequence results in a SOAP fault.

Note: When WS-Addressing is in use, SOAP messages without a

WS-Addressing RelatesTo SOAP Header are processed by the
request rule, not the response rule, even if the message come from
the backend server.
on Requires Reliable Messaging for all responses.
off (Default) Does not require Reliable Messaging for all responses.
Source Create Sequence on Request
Indicates whether to create a Reliable Messaging source from the back side
to the server when there is SOAP data to sent to the server and when there
is no Reliable Messaging source that was created by a MakeOffer from the
server. The Reliable Messaging source is created by sending a
CreateSequence SOAP request to the server address.
on Creates a Reliable Messaging source.
off (Default) Does not create a Reliable Messaging source.
When enabled, the WebGUI displays the following inputs:
Source Make Two-Way Offer
Indicates whether to include an offer for two-way Reliable
Messaging in CreateSequence SOAP requests that are made as the

Chapter 3. Configuring Multi-Protocol Gateway services 45

 result of request processing. Including an offer can result in the
creation of a Reliable Messaging destination for the server to send
responses on when the DataPower service creates a Reliable
Messaging source to send requests to the server. If the server does
not accept the offer, DataPower server does not create a Reliable
Messaging destination.
on Include an offer.
off (Default) Does not include an offer.
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets with the initial
timeout.
off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.
The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 10.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.
The default is 3.
Source Create Sequence on Response
When the WS-Addressing mode is WS-Addressing Gatewayed to
Synchronous or Pure WS-Addressing indicates whether to create a
Reliable Messaging source from the front side to the client when there is

46 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 SOAP data to send to the client and there is no Reliable Messaging source
that was created by a MakeOffer from the client by sending a
CreateSequence SOAP request to the WS-Addressing ReplyTo address.
on Creates a Reliable Messaging source.
off (Default) Does not create a Reliable Messaging source.
When enabled, the WebGUI displays the following inputs:
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets with the initial
timeout.
off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.
The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 10.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.
The default is 3.
Source Front Reply Point
Identifies the Front Side Protocol Handler to receive the asynchronous
Reliable Messaging SequenceAcknowledgement SOAP responses from the

Chapter 3. Configuring Multi-Protocol Gateway services 47

 client. The Front Side Protocol Handler must be associated with the same
DataPower service where the corresponding Reliable Messaging sequence
is occurring.
This property controls whether a front-side Reliable Messaging source uses
a unique URL to receive asynchronous Acks from the client Reliable
Messaging destination or whether Acks are sent synchronously in future
requests to the front-side client.
v With a specified Front Side Protocol Handler and the client includes an
Offer in a CreateSequence SOAP message sent due to response
processing, there will be a non-anonymous URL specified in the AcksTo
element of the Accept element of the CreateSequenceResponse SOAP
reply.
v With a specified Front Side Protocol Handler and the front-side sends a
CreateSequence SOAP message to establish a reliable back channel, there
will be a non-anonymous URL specified in the AcksTo element of the
CreateSequence SOAP request.
v Without a Front Side Protocol Handler, the AcksTo elements has the
value http://www.w3.org/2005/08/addressing/anonymous, which
indicates synchronous Acks.
Source Back AcksTo Reply Point
Identifies the Front Side Protocol Handler to receive the asynchronous
Reliable Messaging SequenceAcknowledgement SOAP responses from the
server. The Front Side Protocol Handler must be associated with the same
DataPower service where the corresponding Reliable Messaging sequence
is occurring.
This property controls whether the backside Reliable Messaging source
uses a unique URL to receive asynchronous Acks from the server Reliable
Messaging destination, or whether Acks are sent synchronously in future
responses to the backside server.
v With a specified Front Side Protocol Handler and the response process
causes a CreateSequence SOAP message to be sent, the AcksTo element
of the CreateSequence SOAP message will be set to the URL that is
specified in back AcksTo.
v Without a Front Side Protocol Handler, the AcksTo element has the value
http://www.w3.org/2005/08/addressing/anonymous, which indicates
synchronous Acks.
Source Maximum Simultaneous Sequences
Sets a limit on the maximum number of simultaneously active sequences
from Reliable Messaging sources of this DataPower server. Each remote
Reliable Messaging destination endpoint reference (URL) requires one
sequence. Transactions that request the creation of sequences in excess of
this limit result in a SOAP Fault. This property controls memory resource
utilization.
The default is 400.

Configuring XML threat protection

Using a coordinated set of objects and configuration values, it is possible to
maximize protection against XML threats. Threats are malicious attempts to disrupt
service. The XML Threat Protection screen provides a single place to configure
against the following threats:
v Single message XML Denial-of-Service (XDoS)

48 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

v Multiple message XML Denial-of-Service (MMXDoS)
v Message tampering
v SQL injections
v XML viruses (X-Virus)
v Dictionary attacks

To configure against XML threats, perform the following steps:

1. Click XML Threat Protection.
2. Defines all of the properties for threat protection, as needed.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Single message XML denial-of-service

These settings provide protection against a single malicious XML message. A
number of the parameters used to provide this kind of protection are set in the
XML Manager; this page offers the opportunity to override the XML Manager with
service-level settings.
Max Message Size
The maximum allowed size, in kilobytes, of any given message. Use an
integer in the range of 0 through 2097151. The default is 0. A value of 0
specifies unlimited size.
Override parser limits
When left at the default of off, the parser limits set in the XML Manager
used by this service remain in effect. Settings for the XML Manager apply
to all services that use the XML Manager.
When set to on, the following additional fields are displayed:
XML Attribute Count
Limits the number of attributes for any given element. Specify an
integer.
XML Bytes Scanned
Limits the number of bytes contained in any given XML message. A
value of 0 enforces no limit.
XML Element Depth
Limits the depth of nested elements in an XML message.
XML Node Size
Limits the size of any one XML node. The minimum allowed value is
1. The defined value can be larger than the value for the XML Bytes
Scanned property. However, the value for the XML Bytes Scanned
property takes precedence.
Attachment Byte Count Limit
Limits the size, in bytes, of any single attachment to the message.
Specify 0 to enforce no limit. This property setting is not available in
the XML Manager parser limits.
XML External Reference Handling
Specifies how the XML parser continues processing when an input
document seeks to resolve an external reference such as an external
entity or external DTD definition. The default is Forbid.

Chapter 3. Configuring Multi-Protocol Gateway services 49

 Multiple message XML denial-of-service
These settings provide protection against a denial-of-service (DoS) attack when
multiple XML messages are sent to the service. When Enable MMXDos Protection
is set to on, the WebGUI displays the following fields:
Max Duration for a Request
Specify an integer setting the maximum number of milliseconds allowed
for processing any one request.
Interval for Measuring Request Rate from Host
Specify an integer setting the interval, in milliseconds, used for measuring
the rate of requests from any given host. The default of 1000 measures how
many requests per second are received from any given host.
Max Request Rate from Host
Specify an integer setting the maximum number of requests that can be
received, in the interval period, from any one host.
Interval for Measuring Request Rate for Firewall or Interval for Measuring
Request Rate for Gateway
Specify an integer setting the interval, in milliseconds, for measuring the
request rate for the entire service. The default of 1000 sets the interval at
requests per second.
Max Request Rate for Firewall or Max Request Rate for Gateway
Specify an integer setting the maximum number of requests that can be
received, in the interval period, by the service.
Block Interval
Specify an integer setting the period of time, in milliseconds, that the
service will block access after one of the other thresholds have been
reached.
Log Level
Select the log level at which log messages are generated by these threat
protection thresholds. When a threshold is reached, the service generates a
log message. This level determines the severity. Log targets capture
messages at or above a configured level. The default level for the default
log is notify.

Message tampering
Message tampering protection employs schema validation. Validation is performed
against submitted messages. Validation prevents messages that have been altered
and that no longer pass validation from reaching the backend service endpoints.

To protect against message tampering, create a validate action. You can add this
action to an existing or new processing policy. Refer to Validate (validate) action
on page 155 for more information.

SQL injections
To protect against SQL injections, create a filter action. You can add this filter
action to an existing or new processing policy. When creating the filter action,
define the following properties:
Processing Control File
Use store:///SQL-Injection-Filter.xsl
Stylesheet Parameter Name
Use {http://www.datapower.com/param/config}SQLPatternFile

50 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Stylesheet Parameter Value
Use store:///SQL-Injection-Patterns.xml or use a reference that points to
a custom SQL Injection Pattern File. This file is typically in the local:///
directory.

Refer to Filter (filter) action on page 126 for more information.

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

First determine whether to process attachments. If you process attachments, define

an antivirus action to check attachments for viruses.

Controlling the processing of attachments: When the message type is SOAP or

XML, configure how to process attachments in the message. To configure a service
for XML virus protection, provide the following inputs:
Request attachment processing mode or Request Attachments
Specifies the processing mode for attachments in client requests.
Allow Processes the message root and needed XML and non-XML
attachments. Needed attachments are buffered. Attachments that
are not needed might be streamed directly to output.
Reject Rejects messages that contain attachments.
Strip (Default) Removes attachments from the message and changes the
value of the Content-Type header to that of the root part.
Streaming
Provides limited processing of XML attachments, and streams XML
and non-XML attachments to output.
Unprocessed
Allows messages that contain attachments, but does not process
attachments.
For additional information about streaming attachments, refer to
Optimizing through Streaming.
Response attachment processing mode or Response Attachments
Specifies the processing mode for attachments in server responses.
Allow Processes the message root and needed XML and non-XML
attachments. Needed attachments are buffered. Attachments that
are not needed might be streamed directly to output.
Reject Rejects messages that contain attachments.
Strip (Default) Removes attachments from the message and changes the
value of the Content-Type header to that of the root part.
Streaming
Provides limited processing of XML attachments, and streams XML
and non-XML attachments to output.

Chapter 3. Configuring Multi-Protocol Gateway services 51

 Unprocessed
Allows messages that contain attachments, but does not process
attachments.
For additional information about streaming attachments, refer to
Optimizing through Streaming.

For the XML Firewall services only, these properties are on both the General tab
and the XML Threat Protection tab. A change on either tab affects the property on
both tabs.

Checking for viruses in attachments: To protect against viruses in attachments

create an antivirus action. Refer to Antivirus (antivirus) action on page 94 for
more information.

Dictionary attack
Dictionary attacks are detected by repeatedly denying requests for access, which is
typically a visible symptom of someone probing for data dictionary definitions to
exploit. The DataPower service can monitor access requests through an aaa action
that is activated on each request for service. When the count of rejected access
requests reaches a certain level, the service can send notification and even deny
service for a period of time.

To protect against dictionary attacks, create a Count Monitor object and create an
aaa action. The Count Monitor must have its Measure property set to xpath. Refer
to Message Count Monitor on page 230 for more information.

The aaa action can be added to an existing or new processing policy. When
creating this action, define the following property:
Counter Monitor
Select the defined Count Monitor object.

Refer to AAA (aaa) action on page 94 for more information.

Using URL builders

To use a URL builder, click the protocol-specific button. The WebGUI launches a
utility that assists in building the protocol-specific URL.
v For information about using the utility to build an IMS Connect URL, refer to
Building an IMS Connect URL.
v For information about using the utility to build an MQ URL, refer to Building
an MQ URL on page 53.
v For information about using the utility to build a TIBCO EMS URL, refer to
Building a TIBCO EMS URL on page 54.
v For information about using the utility to build a WebSphere JMS URL, refer to
Building a WebSphere JMS URL on page 54.

Building an IMS Connect URL

To use the IMS Connect URL builder for assistance in the construction of a URL,
use the following procedure:
1. Click IMS Connect Helper.
2. Select an existing instance of the IMS Connect object from the IMS Connect
Config list.

52 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 3. Specify the transaction name for the connection in the Transaction Name field.
This property sets the TranCode parameter. This property overrides the value of
the Transaction Code property for the IMS Connect object.
4. Specify the datastore name (IMS destination ID) for the connection in the Data
Store ID field. This property sets the DataStoreID parameter. This property
overrides the value of the Data Store ID property for the IMS Connect object.
5. Click Build.

The utility creates a URL in the following format:

dpims://object?TranCode=code;DataStoreID=ID

Refer to the url-open extension element in the IBM WebSphere DataPower SOA
Appliances: Extension Elements and Functions Catalog for details about changing the
URL for a secure connection or for adding other query parameters.

Building an MQ URL
When constructing a service that uses MQ for the backend URL, the URL of the
response from the backend often contains the query string. The matching criteria in
the response rule for the processing policy must allow for this query string. For
example, if the request to the service is http://gwaddr/SomeURL and the response
from the backend is http://gwaddr/
SomeURL?RequestQueue=1;ResponseQueue=2;PMO=2048, matching criteria of */SomeURL
will fail for the response.

To use the MQ URL builder for assistance in the construction of a URL, use the
following procedure:
1. Click MQ Helper.
2. Select an existing instance of the MQ Queue Manager object from the Queue
Manager list.
3. Specify a string, such as /SomeBank/Services/checking to include in the URL in
the URI field.
4. Specify the name of a queue that the Queue Manager manages in the Request
Queue field. The service puts requests on this queue.
5. Specify the name of a queue that the Queue Manager manages in the Reply
Queue field. The service polls this queue for responses.
6. Use the Transactionality toggle to indicate whether communications must use
transactional unit-of-work. When enabled (on), the service enforces
transactional unit-of-work in the communication by inserting
Transactional=true in the URL and does not consider a message to be
successfully posted until it receives a response.
7. Use the User Identifier to indicate whether to set the UserIdentity value in the
MQ header.
v If enabled (on), the builder inserts PMO=2052 in the URL. This value assumes
the following MQPMO options:
MQPMO_NO_SYNCPOINT (decimal 4, hexadecimal 0x00000004)
MQPMO_SET_ALL_CONTEXT (decimal 2048, hexadecimal 0x00000800)
v If disabled (off), the builder does not insert a value. The service assumes
MQPMO_NO_SYNCPOINT only.
8. Use the ReplyToQ to indicate whether to set the ReplyToQ value in the MQMD
header for a request message.
v If enabled (on, inserts SetReplyTo=true in the URL. The processing policy
overwrites the ReplyToQ value with the value of the Reply Queue option.
Chapter 3. Configuring Multi-Protocol Gateway services 53
 v If disabled (off), the processing policy does not change the value of ReplyToQ
in the MQMD header.
9. Click Build.

The utility creates a URL in the following format, which becomes the value for the
Backend URL field:
dpmq://server/URI?RequestQueue=queue;ReplyQueue=queue;
Transactional=true;PMO=2052;SetReplyTo=true

Refer to the url-open extension element in the IBM WebSphere DataPower SOA
Appliances: Extension Elements and Functions Catalog for details about changing the
URL for a secure connection, for using another MQPMO value, or for adding other
query parameters.

Building a TIBCO EMS URL

To use the TIBCO EMS builder for assistance in the construction of a URL, use the
following procedure:
1. Click TIBCO EMS Helper.
2. Select an existing instance of the TIBCO Server object from the Server list.
3. Identify the queue or topic space for the request in the Request Queue field.
v To specify a queue, use the queue format.
v To specify a topic space, use the topic:topic-space format.
4. Identify the queue or topic space for the reply in the Reply Queue field.
v To specify a queue, use the queue format.
v To specify a topic space, use the topic:topic-space format.
5. Specify an SQL 92 conditional expression to identify messages of interest in the
Selector field.
6. Use the Request Reply Queue toggle to indicate whether to use a temporary
queue for the reply from the server. The default is off.
7. Click Build.

The utility creates a URL in the following format:

dptibems://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestReply=queue

Refer to the url-open extension element in the IBM WebSphere DataPower SOA
Appliances: Extension Elements and Functions Catalog for details about changing the
URL for a secure connection or for adding other query parameters.

Building a WebSphere JMS URL

To use the WebSphere JMS URL builder for assistance in the construction of a URL,
use the following procedure:
1. Click WebSphere JMS Helper.
2. Select an existing instance of the WebSphere JMS object from the Server list.
3. Identify the queue for the request in the Request Queue field.
4. Identify the queue for the reply in the Reply Queue field.
5. Optionally identify a nondefault request topic space in the Request Topic
Space field.
6. Optionally identify a nondefault reply topic space in the Response Topic
Space field.

54 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 7. Specify an SQL 92 conditional expression to identify messages of interest in
the Selector field.
8. Optionally specify the timeout for the connection in the Timeout field.
9. Use the Request Reply Queue toggle to indicate whether to use a temporary
queue for the reply from the server. The default is off.
10. Click Build.

The utility creates a URL in the following format:

dpwasjms://server/?RequestQueue=queue&ReplyQueue=queue&
Selector=expression&RequestTopicSpace=topic-space&
ResponseTopicSpace=topic-space&TimeOut=timeout&RequestReply=queue

Refer to the url-open extension element in the IBM WebSphere DataPower SOA
Appliances: Extension Elements and Functions Catalog for details about changing the
URL for a secure connection or for adding other query parameters.

Using a Load Balancer Group as a backend server

The following example explains how to use a Load Balancer Group as the backend
server of a DataPower service. This example creates new objects and provides
information about only the configuration that is required for load balancing.
However, you can modify existing objects.
1. Create the LBGroup Load Balancer Group and define Server-1 and Server-2 as
members that reference the actual servers.
The configuration of a DataPower service defines the default port on the
backend servers. You can override the default server port for one or more
members with the Mapped Server Port property.
Refer to Configuring Load Balancer Group objects on page 288 for more
information.
2. Create the LBManager XML Manager and add the LBGroup group to the Load
Balancer Groups list. Refer to XML Manager on page 352 for more
information.
3. Create a DataPower service, for example the LBFirewall XML Firewall, and
configure the following properties:
a. Select the LBManager XML Manager from the XML Manager list.
b. Specify LBGroup (the Load Balancer Group) as the address of the backend
server for the DataPower service. Depending on the DataPower service or
the view of that DataPower service, the field could be Remote Address,
Server Address, or something similar.
With a Web Service Proxy that is configured statically from a WSDL file, the
field is part of the configuration of the Remote Rewrite Rules of the
WS-Proxy Endpoint Rewrite object. The field is either Remote Endpoint
Host (object view) or Hostname (IP Address) (task template view).

For complete information about creating an instance of a Load Balancer Group

object, refer to Load Balancer Group on page 287.

Chapter 3. Configuring Multi-Protocol Gateway services 55

56 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 4. Configuring handler objects
You can create and manage the following handler objects:
FTP Poller Front Side Handler
Creates an FTP poller handler to poll for available input.
FTP Server Front Side Handler
Creates an FTP traffic handler.
HTTP Front Side Handler
Creates an HTTP traffic handler
HTTPS (SSL) Front Side Handler
Creates an HTTPS traffic handler
IMS Connect Handler
Creates an IMS traffic handler.
MQ Front Side Handler
Creates an MQ traffic handler
NFS Poller Front Side Handler
Creates an NFS poller handler to poll for available input.
SFTP Server Front Side Handler
Creates an SFTP traffic handler
Stateful Raw XML Handler
Creates a nonsecure TCP-based relay or forwarding service.
Stateless Raw XML Handler
Creates a secure SSL-based relay or forwarding service.
TIBCO EMS Front Side Handler
Creates a TIBCO EMS traffic handler
WebSphere JMS Front Side Handler
Creates a default WebSphere JMS traffic handler

These handlers can be used with a DataPower service. To access these handlers,
use the Objects Protocol Handlers menu.

FTP Poller Front Side Handler

An FTP Poller Front Side Handler object manages the polling of the remote FTP
server for available input with DataPower services.

This handler is available on the following appliances only:

v XML Security Gateway XS40
v XML Integration Appliance XI50
v B2B Appliance XB60

To configure an FTP Poller Front Side Handler, use the following procedure:
1. Select Objects Protocol Handlers FTP Poller Front Side Handler to
display the catalog.
2. Click Add to display the configuration screen.

Copyright IBM Corp. 2002, 2009 57

 3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the directory to poll in the Target Directory field. The path must end
in a slash. The slash denotes a directory.
For an absolute path to the root directory
ftp://user:password@host:port/%2Fpath/

Note: If the user name or password contains the characters :, @,

or /, use their URL-encoded values in accordance with the
specification.
For a relative path to the home directory of the specified user
ftp://user:password@host:port/path/
Do not configure one FTP poller to point at a host name that is a virtual name
of a load balancer group. This configuration is not the correct way to poll
multiple hosts. To poll multiple hosts, use the same DataPower service and
configure one FTP poller object for each real host.
7. Specify the number of milliseconds to wait after the completion of one poll
before starting the next interval in the Delay Between Polls field. Use an
integer in the range of 25 through 100000. The default is 60000.
8. Specify the PCRE to use to match the contents of the directory being polled in
the Input File Match Pattern field. If there is file-renaming or there is a
response, this PCRE must create PCRE back references using () pairs.
For example, if the input files are NNNNNN.input, then the match pattern would
be ([0-9] {6})\.input.
9. Specify the PCRE to use to rename a file that is being processed in the
Processing File Renaming Pattern field. This functionality allows multiple
poller objects to poll the same directory with the same match pattern. There is
no lack of atomicity if the rename operation on the server is atomic. The
poller that succeeds in renaming the input file will proceed to process the file.
Any other poller that tries to rename the file at the same time will fail to
rename the file and will proceed to try the next file that matches the specified
match pattern.
To ensure uniqueness, the resulting file name will be in the following format:
filename.serial.domain.poller.timestamp
where:
filename
The file name for the renamed input file.
serial The serial number of the configured DataPower appliance.
domain The domain of the polling object.
poller The name of the polling object.
timestamp
The timestamp.

Note: File renaming cannot be used with an FTP server that supports only 8.3
file names.

58 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 For example if the input files are NNNNNN.input and you want to rename them
to NNNNNN.processing, then the match pattern would be ([0-9] {6})\.input$
and the processing pattern would be $1.processing. The resultant file name of
the server would be:
NNNNNN.processing.serial.domain.poller.timestamp

Note: If no processing rename pattern is configured, the file will still be

renamed. The only difference is that the filename portion of the resulting
file is the name of the original input file, not the renamed input file.
10. Define the process for deleting files on success.
a. Use the Delete File on Success toggle to select whether to delete the input
file after successful processing.
on Deletes the input file.
off (Default) Renames the input file using the renaming pattern
specified by the Success File Renaming Pattern property.
b. When off, specify the PCRE to use to rename the input file on success in
the Success File Renaming Pattern field. This PCRE will normally have a
back reference for the base input file. For instance, if input files are
NNNNNN.input and you want to rename them to NNNNNN.processed, the
match pattern would be ([0-9] {0-6})\.input$ and the rename pattern
would be $1.processed.
Some servers might allow this pattern to indicate a path that puts the file
in a different directory, if it allows cross-directory renames. For instance,
the match pattern would be (.*) and the rename pattern would be
../processed/$1.
11. Define the process for deleting files on processing error.
a. Use the Delete File on Processing Error toggle to select whether to delete
the input or processing rename file when it could not be processed.
on Deletes the file.
off (Default) Renames the input or processing rename file using the
renaming pattern specified by the Error File Renaming Pattern
property.
b. When off, specify the PCRE to use to rename a file when it could not be
processed in the Error File Renaming Pattern field.
12. Define the process for creating result files.
a. Use the Generate Result File toggle to select whether to create a result file
after processing an input file.
on (Default) Creates the result file using the naming pattern specified
by the Result File Name Pattern property.
off Does not create the result file.
b. on, specify the PCRE to use as the match pattern to build the name of the
result file in the Result File Name Pattern field. This PCRE will normally
have a back reference for the base input file. For instance, if input files are
NNNNNN.input and you want to rename them to NNNNNN.result, the match
pattern would be ([0-9] {0-6})\.input$ and the rename pattern would
be $1.result.
Some servers might allow this pattern to indicate a path that puts the file
in a different directory, if it allows cross-directory renames. For instance,
the match pattern would be (.*) and the rename pattern would be
../result/$1.

Chapter 4. Configuring handler objects 59

 13. Define the processing seize behavior.
a. Specify the time to wait in seconds before processing a file that is already
in the processing state in the Processing Seize Timeout field. Use an
integer in the range of 0 through 1000. The default is 0.
Processing seize allows failure handling of a poller when multiple data
routers are polling the same target. If another data router renames a file
and does not process (and rename or delete) it in the specified number of
seconds, this system attempts to take over processing. This system will
attempt to take over processing when all of these three conditions are met
when compared to the processing seize pattern. 1) The base file name (first
match phrase) is the processing seize pattern, 2) The host name (second
match phrase) is not the name of this system, 3) The timestamp (third
match phrase) is further in the past than the wait time specified by this
timeout. When these three conditions are met, this system renames the file
(with its host name and fresh timestamp) and locally processes the file.
This processing assumes that the rename succeeded.
b. Specify the PCRE to use to find files that were renamed to indicate that
they are in the being processed state but the processing was never
completed in the Processing Seize Pattern field.
The processing seize pattern contains three phrases that must be in \(\)
pairs. The first phrase is the base file name that includes the configured
processing suffix. The second phrase is the host name. The third phrase is
the timestamp.
14. Select the XML Manager that contains the User Agent configuration to use
from the XML Manager list.
15. Click Apply to save the object to the running configuration.
16. Optionally, click Save Config to save the object to the startup configuration.

FTP Server Front Side Handler

An FTP Server Front Side Handler object handles FTP protocol communications
with DataPower services.

This handler is available on the following appliances only:

v XML Security Gateway XS40
v XML Integration Appliance XI50
v B2B Appliance XB60

An instance of this object can have one of the following configurations:

Transparent
The FTP server has a transparent file system. The files and directories
shown are those on the FTP server.
Virtual ephemeral
The FTP server will have an ephemeral virtual file system with
subdirectories created by configuration. The contents of this file system are
private to an individual FTP control connection to the FTP server.
The contents of this file system will not persist after this FTP control
connection ends.
Virtual persistent
The FTP server will have a persistent virtual file system with
subdirectories created by configuration. The contents of this file system are

60 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 shared by all FTP control connections to this FTP server with the same
authenticated user identity. The user identity is determined by the FTP
user name and, if used, by the TLS/SSL certificate.
The contents of this file system will persist (for the duration defined by the
Persistent Filesystem Timeout) property after all FTP control connections
end.
This mode is required to support checkpoint/restart with the REST
command.

Defining as transparent
To configure an instance of the FTP Server Front Side Handler object to access a
transparent file system, use the following procedure:
1. Select Objects Protocol Handlers FTP Server Front Side Handler to
display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.
a. Specify the IP address on which the FTP server listens in the Local IP
Address field. Defaults to 0.0.0.0, which indicates that the service is active
on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the port that the FTP Server service monitors in the Port field. This
port is the port on which FTP control connections can be established. This
port does not control the TCP port that is used for the data connections. If
the FTP client uses the PASV command, data connections will use an
arbitrary, unused TCP port. The default is 21.
7. Define the characteristics of the file system.
a. Select Transparent from the Filesystem Type list.
b. Retain the default value in the Default Directory field.
c. Specify the maximum file name length on the FTP server in the Maximum
Filename Length field. Use an integer in the range of 1 through 4000. The
default is 256.
8. Select an instance of the Access Control List object to apply from the Access
Control List list.
9. Define secure connection.
a. Use the Require TLS toggle to select whether FTP control connections
require explicit TLS encryption. If required, the FTP client must use the
FTP AUTH TLS command before any other command. This setting does
not control encryption of data transfers. The default is off.
b. Select an instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
10. Define user authentication.
a. Select an instance of the AAA Policy object from the Password AAA
Policy list. This instance performs authentication of user names and

Chapter 4. Configuring handler objects 61

 passwords provided to the FTP server by the client with the USER and
PASS commands. If the authentication succeeds, the FTP client can use all
of the features of the FTP server. If the authentication fails, a 530 error is
returned, and the user can attempt to authenticate again. If no Password
AAA Policy is configured, any user name and password is accepted.
b. Select an instance of the AAA Policy object from the Certificate AAA
Policy list. This instance performs secondary authentication of the
information in the TLS/SSL certificate that is provided during TLS
negotiation after the AUTH TLS command to the FTP server. Primary
authentication is done by the SSL Proxy Profile, which can completely
reject a certificate. This authentication stage controls whether an FTP
password will be demanded or not. If the result of this authentication
succeeds, the FTP client will only have to use the USER command to login
after the AUTH TLS. If this authentication fails, the FTP client will have to
use both the USER and PASS commands to complete the login process. If
no Certificate AAA Policy is configured, USER and PASS will always be
required. If the AUTH TLS command is not used by the FTP client, USER
and PASS will always be required.
11. Define FTP support.
a. Use the Allow CCC Command toggle to select whether the FTP CCC
command can be used to turn off TLS encryption of the FTP control
connection after user authentication. If allowed, the CCC command can be
used to turn off encryption after authentication. Turning off encryption is
necessary when the FTP control connection crosses a firewall or NAT
device that needs to sniff the control connection. Turning off encryption
eliminates the secrecy of the files being transferred and allows TCP packets
injection attacks. The default is on.
b. Define behavior for passive command support.
1) Select the support behavior for passive commands from the Passive
(PASV) Command list. Without the PASV command, the STOR,
SOUT, and RETR commands will fail when issued by the FTP client.
When not allowing passive mode, the FTP client must use the FTP
PORT command. The default is Allow Passive Mode.
2) If allowing or requiring support, use the Limit Port Range for Passive
Connections toggle to control whether to limit the TCP port range that
the FTP server can dynamically allocate.
3) If limiting the port range, define the port range and define the timeout
for establishing a data connection.
a) Specify the lower end of the range in the Minimum Passive Port
field. The default is 1024.
b) Specify the upper end of the range in the Maximum Passive Port
field. The default is 1050.
c) Specify the number of seconds that the server waits for a client to
establish a passive data connection in the Passive Data Connection
Idle Timeout field.
c. Select the use of encryption for data connections (file transfers) from the
File Transfer Data Encryption list. Data encryption is controlled by the
FTP PROT P command. The default is Allow Data Encryption.
d. Use the Allow Compression toggle to select whether the FTP client can
use FTP MODE Z compression. After enabling FTP compression, the FTP
client can use the zlib method to compress data transfers. The default is
on.
e. Define behavior for unique file names

62 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 1) Use the Allow Unique File Name (STOU) toggle to select whether the
FTP client can use the FTP STOU command. When enabled, the FTP
server generates a unique file name for each transferred file. The
default is off.
2) If enabled, specify the prefix for file names that are generated when
using the FTP STOU command in the Unique File Name Prefix field.
When defining the prefix, use the ^[^/]*$ format. The directory
separator (/) is not allowed. The default is to not add a prefix, which is
an empty string.
12. Specify the number of seconds that the FTP control connection can be idle in
the Idle Timeout field. After the specified duration elapses, the FTP server
closes the control connection. Defaults to 0, which disables the timeout.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

Defining as virtual ephemeral

To configure an instance of the FTP Server Front Side Handler object to access a
virtual ephemeral file system, use the following procedure:
1. Select Objects Protocol Handlers FTP Server Front Side Handler to
display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.
a. Specify the IP address on which the FTP server listens in the Local IP
Address field. Defaults to 0.0.0.0, which indicates that the service is active
on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the port that the FTP Server service monitors in the Port field. This
port is the port on which FTP control connections can be established. This
port does not control the TCP port that is used for the data connections. If
the FTP client uses the PASV command, data connections will use an
arbitrary, unused TCP port. The default is 21.
7. Define the characteristics of the file system.
a. Select Virtual Ephemeral from the Filesystem Type list.
b. Specify the initial working directory on the FTP server (after users connect
and authenticate) in the Default Directory field. When the working
directory is not the root directory, the specified directory must be one of
the configured virtual directories. The default is the root directory (/).
c. Specify the maximum file name length on the FTP server in the Maximum
Filename Length field. Use an integer in the range of 1 through 4000. The
default is 256.
8. Select an instance of the Access Control List object to apply from the Access
Control List list.
9. Define secure connection.

Chapter 4. Configuring handler objects 63

 a. Use the Require TLS toggle to select whether FTP control connections
require explicit TLS encryption. If required, the FTP client must use the
FTP AUTH TLS command before any other command. This setting does
not control encryption of data transfers. The default is off.
b. Select an instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
10. Define user authentication.
a. Select an instance of the AAA Policy object from the Password AAA
Policy list. This instance performs authentication of user names and
passwords provided to the FTP server by the client with the USER and
PASS commands. If the authentication succeeds, the FTP client can use all
of the features of the FTP server. If the authentication fails, a 530 error is
returned, and the user can attempt to authenticate again. If no Password
AAA Policy is configured, any user name and password is accepted.
b. Select an instance of the AAA Policy object from the Certificate AAA
Policy list. This instance performs secondary authentication of the
information in the TLS/SSL certificate that is provided during TLS
negotiation after the AUTH TLS command to the FTP server. Primary
authentication is done by the SSL Proxy Profile, which can completely
reject a certificate. This authentication stage controls whether an FTP
password will be demanded or not. If the result of this authentication
succeeds, the FTP client will only have to use the USER command to login
after the AUTH TLS. If this authentication fails, the FTP client will have to
use both the USER and PASS commands to complete the login process. If
no Certificate AAA Policy is configured, USER and PASS will always be
required. If the AUTH TLS command is not used by the FTP client, USER
and PASS will always be required.
11. Define FTP support.
a. Use the Allow CCC Command toggle to select whether the FTP CCC
command can be used to turn off TLS encryption of the FTP control
connection after user authentication. If allowed, the CCC command can be
used to turn off encryption after authentication. Turning off encryption is
necessary when the FTP control connection crosses a firewall or NAT
device that needs to sniff the control connection. Turning off encryption
eliminates the secrecy of the files being transferred and allows TCP packets
injection attacks. The default is on.
b. Define behavior for passive command support.
1) Select the support behavior for passive commands from the Passive
(PASV) Command list. Without the PASV command, the STOR,
SOUT, and RETR commands will fail when issued by the FTP client.
When not allowing passive mode, the FTP client must use the FTP
PORT command. The default is Allow Passive Mode.
2) If allowing or requiring support, use the Limit Port Range for Passive
Connections toggle to control whether to limit the TCP port range that
the FTP server can dynamically allocate.
3) If limiting the port range, define the port range and define the timeout
for establishing a data connection.
a) Specify the lower end of the range in the Minimum Passive Port
field. The default is 1024.
b) Specify the upper end of the range in the Maximum Passive Port
field. The default is 1050.

64 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 c) Specify the number of seconds that the server waits for a client to
establish a passive data connection in the Passive Data Connection
Idle Timeout field.
c. Select the use of encryption for data connections (file transfers) from the
File Transfer Data Encryption list. Data encryption is controlled by the
FTP PROT P command. The default is Allow Data Encryption.
d. Use the Allow Compression toggle to select whether the FTP client can
use FTP MODE Z compression. After enabling FTP compression, the FTP
client can use the zlib method to compress data transfers. The default is
on.
e. Define behavior for unique file names
1) Use the Allow Unique File Name (STOU) toggle to select whether the
FTP client can use the FTP STOU command. When enabled, the FTP
server generates a unique file name for each transferred file. The
default is off.
2) If enabled, specify the prefix for file names that are generated when
using the FTP STOU command in the Unique File Name Prefix field.
When defining the prefix, use the ^[^/]*$ format. The directory
separator (/) is not allowed. The default is to not add a prefix, which is
an empty string.
12. Specify the number of seconds that the FTP control connection can be idle in
the Idle Timeout field. After the specified duration elapses, the FTP server
closes the control connection. Defaults to 0, which disables the timeout.
13. Define response behavior and storage for responses.
a. Select how to make response files available for gateway transactions
started the FTP STOR or SOUT operation from the Response Type list.
The default is No Response.
b. If FTP Client, which indicates that the response is written by the FTP
client:
1) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed. The
suffix should be in the ^[^/]*$ format. Defaults to an empty string.
2) specify the URL to use when generating response files in the Response
URL field. This URL enables a response to be written using FTP
commands. The URL must be an FTP URL that starts with ftp://. The
URL should include a directory, but not a file name. The URL cannot
include query parameters. The URL should be in the
^(|ftp://[^/]+(/[^/]+)*)$ format. The default is to have no response
generated (an empty string).
3) Specify the maximum size in megabytes for the temporary file system
in the Temporary Storage Size field. Use an integer in the range of 1
through 2048. The default is 32.
c. If Virtual Filesystem, which indicates that the response is made available
as a file in the virtual file system that can be read by the FTP client:
1) Specify the directory to store the response in the Response Storage
field.
2) If NFS:
a) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed.
The suffix should be in the ^[^/]*$ format. Defaults to an empty
string.

Chapter 4. Configuring handler objects 65

 b) Select an NFS static mount to apply. Each response file will have a
unique file name in the NFS directory from the Response NFS
Mount list. The name of the response file is not related to the file
name that the virtual file system presents to the FTP client.
Generally, this NFS directory is not made available through the FTP
server. This directory should not be used for any other purpose.
3) If Temporary:
a) Specify the suffix to add to the end of the input file name in the
Response Suffix field.
b) Specify the maximum size in megabytes for the temporary file
system in the Temporary Storage Size field. Use an integer in the
range of 1 through 2048. The default is 32.
14. Define virtual directories. The FTP client can use all of these directories to
write file to be processed. The root directory (/) is always present and cannot
be created. Its response directory is always the root directory.
a. Click the Virtual Directories tab.
b. Create a virtual directory.
1) Click Add.
2) Specify the directory in the virtual file system of the FTP server where
the FTP client can find this directory in the Virtual Directory field.
3) Specify the directory in the virtual file system of the FTP server where
the responses to files are stored in this directory will go in the
Response Directory field.
4) Click Save.
c. Repeat the previous step to define another virtual directory.
15. Click Apply to save the object to the running configuration.
16. Optionally, click Save Config to save the object to the startup configuration.

Defining as virtual persistent

To configure an instance of the FTP Server Front Side Handler object to access a
virtual persistent file system, use the following procedure:
1. Select Objects Protocol Handlers FTP Server Front Side Handler to
display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.
a. Specify the IP address on which the FTP server listens in the Local IP
Address field. Defaults to 0.0.0.0, which indicates that the service is active
on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the port that the FTP Server service monitors in the Port field. This
port is the port on which FTP control connections can be established. This
port does not control the TCP port that is used for the data connections. If

66 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 the FTP client uses the PASV command, data connections will use an
arbitrary, unused TCP port. The default is 21.
7. Define the characteristics of the file system.
a. Select Virtual Persistent from the Filesystem Type list.
b. Specify the duration in seconds that a connection to a virtual file system is
retained after all FTP control connections from user identities are
disconnected in the Persistent Filesystem Timeout field. When the timeout
expires, the virtual file system object is destroyed. All of the response files
that were not deleted by the FTP client are deleted from their storage area.
Use an integer in the range of 1 to 43200. The default is 600.
c. Specify the initial working directory on the FTP server (after users connect
and authenticate) in the Default Directory field. When the working
directory is not the root directory, the specified directory must be one of
the configured virtual directories. The default is the root directory (/).
d. Specify the maximum file name length on the FTP server in the Maximum
Filename Length field. Use an integer in the range of 1 through 4000. The
default is 256.
8. Select an instance of the Access Control List object to apply from the Access
Control List list.
9. Define secure connection.
a. Use the Require TLS toggle to select whether FTP control connections
require explicit TLS encryption. If required, the FTP client must use the
FTP AUTH TLS command before any other command. This setting does
not control encryption of data transfers. The default is off.
b. Select an instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
10. Define user authentication.
a. Select an instance of the AAA Policy object from the Password AAA
Policy list. This instance performs authentication of user names and
passwords provided to the FTP server by the client with the USER and
PASS commands. If the authentication succeeds, the FTP client can use all
of the features of the FTP server. If the authentication fails, a 530 error is
returned, and the user can attempt to authenticate again. If no Password
AAA Policy is configured, any user name and password is accepted.
b. Select an instance of the AAA Policy object from the Certificate AAA
Policy list. This instance performs secondary authentication of the
information in the TLS/SSL certificate that is provided during TLS
negotiation after the AUTH TLS command to the FTP server. Primary
authentication is done by the SSL Proxy Profile, which can completely
reject a certificate. This authentication stage controls whether an FTP
password will be demanded or not. If the result of this authentication
succeeds, the FTP client will only have to use the USER command to login
after the AUTH TLS. If this authentication fails, the FTP client will have to
use both the USER and PASS commands to complete the login process. If
no Certificate AAA Policy is configured, USER and PASS will always be
required. If the AUTH TLS command is not used by the FTP client, USER
and PASS will always be required.
11. Define FTP support.
a. Use the Allow CCC Command toggle to select whether the FTP CCC
command can be used to turn off TLS encryption of the FTP control
connection after user authentication. If allowed, the CCC command can be
used to turn off encryption after authentication. Turning off encryption is

Chapter 4. Configuring handler objects 67

 necessary when the FTP control connection crosses a firewall or NAT
device that needs to sniff the control connection. Turning off encryption
eliminates the secrecy of the files being transferred and allows TCP packets
injection attacks. The default is on.
b. Define behavior for passive command support.
1) Select the support behavior for passive commands from the Passive
(PASV) Command list. Without the PASV command, the STOR,
SOUT, and RETR commands will fail when issued by the FTP client.
When not allowing passive mode, the FTP client must use the FTP
PORT command. The default is Allow Passive Mode.
2) If allowing or requiring support, use the Limit Port Range for Passive
Connections toggle to control whether to limit the TCP port range that
the FTP server can dynamically allocate.
3) If limiting the port range, define the port range and define the timeout
for establishing a data connection.
a) Specify the lower end of the range in the Minimum Passive Port
field. The default is 1024.
b) Specify the upper end of the range in the Maximum Passive Port
field. The default is 1050.
c) Specify the number of seconds that the server waits for a client to
establish a passive data connection in the Passive Data Connection
Idle Timeout field.
c. Select the use of encryption for data connections (file transfers) from the
File Transfer Data Encryption list. Data encryption is controlled by the
FTP PROT P command. The default is Allow Data Encryption.
d. Use the Allow Compression toggle to select whether the FTP client can
use FTP MODE Z compression. After enabling FTP compression, the FTP
client can use the zlib method to compress data transfers. The default is
on.
e. Define behavior for unique file names
1) Use the Allow Unique File Name (STOU) toggle to select whether the
FTP client can use the FTP STOU command. When enabled, the FTP
server generates a unique file name for each transferred file. The
default is off.
2) If enabled, specify the prefix for file names that are generated when
using the FTP STOU command in the Unique File Name Prefix field.
When defining the prefix, use the ^[^/]*$ format. The directory
separator (/) is not allowed. The default is to not add a prefix, which is
an empty string.
f. Define the restart behavior:
1) Use the Allow Restart (REST) toggle to indicate whether to support the
REST command to continue the transfer of a file after an interruption in
the data transfer. The default is off.
For written files, the server delays the actual processing until a timeout
expires or until the next FTP command (other than SIZE or REST). The
FTP client can return and resume the transfer with the SIZE, REST, and
STOR commands. The argument to the REST command must be the
same as the byte count returned by the SIZE command.
2) If supported, specify the number of seconds that the FTP client has to
reconnect to the server in the Restart Timeout field. The FTP client
needs to use SIZE, REST, and STOR commands to continue an
interrupted file transfer. If this period of time elapses, the data that was

68 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 received to this point on the TCP data connection will be passed to the
DataPower service. This timeout is canceled if another command (other
than SIZE or REST) is received on the FTP control connection.
12. Specify the number of seconds that the FTP control connection can be idle in
the Idle Timeout field. After the specified duration elapses, the FTP server
closes the control connection. Defaults to 0, which disables the timeout.
13. Define response behavior and storage for responses.
a. Select how to make response files available for gateway transactions
started the FTP STOR or SOUT operation from the Response Type list.
The default is No Response.
b. If FTP Client, which indicates that the response is written by the FTP
client:
1) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed. The
suffix should be in the ^[^/]*$ format. Defaults to an empty string.
2) specify the URL to use when generating response files in the Response
URL field. This URL enables a response to be written using FTP
commands. The URL must be an FTP URL that starts with ftp://. The
URL should include a directory, but not a file name. The URL cannot
include query parameters. The URL should be in the
^(|ftp://[^/]+(/[^/]+)*)$ format. The default is to have no response
generated (an empty string).
3) Specify the maximum size in megabytes for the temporary file system
in the Temporary Storage Size field. Use an integer in the range of 1
through 2048. The default is 32.
c. If Virtual Filesystem, which indicates that the response is made available
as a file in the virtual file system that can be read by the FTP client:
1) Specify the directory to store the response in the Response Storage
field.
2) If NFS:
a) Specify the suffix to add when generating response files in the
Response Suffix field. The directory separator (/) is not allowed.
The suffix should be in the ^[^/]*$ format. Defaults to an empty
string.
b) Select an NFS static mount to apply. Each response file will have a
unique file name in the NFS directory from the Response NFS
Mount list. The name of the response file is not related to the file
name that the virtual file system presents to the FTP client.
Generally, this NFS directory is not made available through the FTP
server. This directory should not be used for any other purpose.
3) If Temporary:
a) Specify the suffix to add to the end of the input file name in the
Response Suffix field.
b) Specify the maximum size in megabytes for the temporary file
system in the Temporary Storage Size field. Use an integer in the
range of 1 through 2048. The default is 32.
14. Define virtual directories. The FTP client can use all of these directories to
write file to be processed. The root directory (/) is always present and cannot
be created. Its response directory is always the root directory.
a. Click the Virtual Directories tab.
b. Create a virtual directory.

Chapter 4. Configuring handler objects 69

 1) Click Add.
2) Specify the directory in the virtual file system of the FTP server where
the FTP client can find this directory in the Virtual Directory field.
3) Specify the directory in the virtual file system of the FTP server where
the responses to files are stored in this directory will go in the
Response Directory field.
4) Click Save.
c. Repeat the previous step to define another virtual directory.
15. Click Apply to save the object to the running configuration.
16. Optionally, click Save Config to save the object to the startup configuration.

HTTP Front Side Handler

An HTTP Front Side Handler object handles HTTP protocol communications with
DataPower services.

To configure an instance of the HTTP Front Side Handler object, use the following
procedure:
1. Select Objects Protocol Handlers HTTP Front Side Handler.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.
a. Specify the host alias or IP address on which the service listens in the
Local IP Address field. The default is 0.0.0.0, which indicates that the
service is active on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the listening port in the Port Number field. The default is 443.
7. Select the HTTP version to use on the client connection from the HTTP
Version to Client list. The default is HTTP 1.1
8. Use the Allowed Methods and Versions check boxes to select the allowed
methods and versions for incoming HTTP requests.
9. Use the Persistent Connections toggle to enable or disable the negotiation of
persistent connections.
10. Use the Compression toggle to enable or disable the negotiation of GZIP
compression
11. Define HTTP header and URL limits.
a. Specify the length of the longest incoming URL to accept in bytes in the
Maximum Allowed URL Length field. The length includes any query
string or fragment identifier. Use an integer in the range of 1 through
128000. The default is 16384.
b. Specify the maximum aggregate byte size of incoming HTTP headers in
the Maximum Allowed Total Header Length field. Use an integer in the
range of 5 through 128000. The default is 128000.

70 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 c. Specify the maximum number of headers allowed in the request message
in the Maximum Number of HTTP Request Headers Allowed field. The
default is 0, which means unlimited.
d. Specify the maximum length of the name part of a header in Maximum
Allowed Length of HTTP Header Name field. Each HTTP Header is
expressed as a name-value pair. The default is 0, which means unlimited.
e. Specify the maximum length of the value part of a header in Maximum
Allowed Length of HTTP Header Value field. Each HTTP Header is
expressed as a name-value pair. The default is 0, which means unlimited.
f. Specify the maximum length of the query string in Maximum Allowed
Length of HTTP Query String field. The default is 0, which means
unlimited.
12. Select the instance of the Access Control List object to apply from the Access
Control List list.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

HTTPS (SSL) Front Side Handler

An HTTPS Front Side Handler object handles HTTPS protocol communications
with DataPower services.

To configure an HTTPS Front Side Handler, use the following procedure:

1. Select Objects Protocol Handlers HTTPS Front Side Handler to display
the HTTPS (SSL) Front Side Handler catalog.
2. Click Add to display the HTTPS (SSL) Front Side Handler configuration
screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.
a. Specify the host alias or IP address on which the service listens in the
Local IP Address field. The default is 0.0.0.0, which indicates that the
service is active on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the listening port in the Port Number field. The default is 80.
7. Select the HTTP version to use on the client connection from the HTTP
Version to Client list. The default is HTTP 1.1
8. Use the Allowed Methods and Versions check boxes to select the allowed
methods and versions for incoming HTTP requests.
9. Use the Persistent Connections toggle to enable or disable the negotiation of
persistent connections.
10. Use the Compression toggle to enable or disable the negotiation of GZIP
compression
11. Define HTTP header and URL limits.

Chapter 4. Configuring handler objects 71

 a. Specify the length of the longest incoming URL to accept in bytes in the
Maximum Allowed URL Length field. The length includes any query
string or fragment identifier. Use an integer in the range of 1 through
128000. The default is 16384.
b. Specify the maximum aggregate byte size of incoming HTTP headers in
the Maximum Allowed Total Header Length field. Use an integer in the
range of 5 through 128000. The default is 128000.
c. Specify the maximum number of headers allowed in the request message
in the Maximum Number of HTTP Request Headers Allowed field. The
default is 0, which means unlimited.
d. Specify the maximum length of the name part of a header in Maximum
Allowed Length of HTTP Header Name field. Each HTTP Header is
expressed as a name-value pair. The default is 0, which means unlimited.
e. Specify the maximum length of the value part of a header in Maximum
Allowed Length of HTTP Header Value field. Each HTTP Header is
expressed as a name-value pair. The default is 0, which means unlimited.
f. Specify the maximum length of the query string in Maximum Allowed
Length of HTTP Query String field. The default is 0, which means
unlimited.
12. Select the instance of the SSL Proxy Profile object to assign from the SSL
Proxy list.
13. Select the instance of the Access Control List object to apply from the Access
Control List list.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

IMS Connect Handler

An IMS Connect Handler object handles IMS protocol communications with
DataPower services.

This handler is available on the following appliances only:

v XML Integration Appliance XI50
v B2B Appliance XB60

To configure an IMS Connect Handler, use the following procedure:

1. Select Objects Protocol Handlers Connect Handler to display the IMS
Connect Handler catalog.
2. Click Add to display the IMS Connect Handler configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the host alias or IP address on which the service listens in the Local IP
Address field. The default is 0.0.0.0, which indicates that the service is active
on all addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to a
static IP address. Aliasing can help when moving configurations across
systems.

72 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 7. Specify the port that the IMS listener monitors in the Port Number field. The
default is 3000.
8. Select an SSL Proxy Profile to assign from the SSL Proxy list.
9. Use the Persistent Connections toggle to select whether to use persistent
connections on the frontend, when appropriate.
on (Default) Enables persistent connections.
off Disables persistent connections.
10. Use the EBCDIC Input Header Encoding toggle to select the encoding for
input headers as EBCDIC or ASCII. This setting does not affect payload
processing. Payload is not automatically processed.
on Indicates the input headers are in EBCDIC encoding.
off (Default) Indicates that input headers are in ASCII encoding.
11. Select an Access Control List from the Access Control List list.
12. Click Apply to save the object to the running configuration.
13. Optionally, click Save Config to save the object to the startup configuration.

MQ Front Side Handler

An MQ Front Side Handler object handles MQ protocol communications with
DataPower services.

This handler is available on the following appliances only:

v XML Integration Appliance XI50
v B2B Appliance XB60
v Low Latency Appliance XM70

To configure an MQ Front Side Handler, use the following procedure:

1. Select Objects Protocol Handlers MQ Front Side Handler to display the
MQ Front Side Handler catalog.
2. Click Add to display the MQ Front Side Handler Configuration screen. Use
this screen to specify operational parameters.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Select a queue manager from the Queue Manager list.
7. Specify the name of the GET queue in the Get Queue field.
8. Specify the name of the PUT queue in the Put Queue field.
9. Specify the Coded Character Set Identifier that the remote MQ queue manager
converts output data in the CCSI field. The default CCSI is for ISO-8859-1
(latin-1). Refer to the IBM Code Pages on the Web for a list of CCSI
identifiers.
This property is meaningful only when the MQ Queue Manager object has the
Convert Input property set to on.
10. Specifies the cumulative value of the MQGET options that are applicable to
an MQ message in decimal or hexadecimal format in the Get Message
Options field. The value is passed directly to the MQ API. The default is 4097
(decimal value for the MQGMO_WAIT and the MQGMO_SYNCPOINT_IF_PERSISTENT
options).

Chapter 4. Configuring handler objects 73

 Refer to the MQGMO_* (Get Message Options) topic in the Constants
section of the WebSphere MQ Information Center for details.
When a message is too large for a queue, an attempt to put the message on
the queue fails. Segmentation is a technique that allows the queue manager or
application to split the message into smaller pieces, and place each segment
on a queue as a separate physical message. The application that retrieves the
message can either handle the multiple segments one-by-one, or request the
queue manager to reassemble the segments into a single message that is
returned by the MQGET call. The reassembly request is achieved by
specifying the MQGMO_COMPLETE_MSG option (65536) on the MQGET call, and by
providing a buffer large enough to accommodate the entire message.

Note: Ensure that the associated queue manager supports the

MQGMO_COMPLETE_MSG option. On z/OS, MQ queue managers do not
support segmentation. On other operating systems, MQ queue
managers might not be configured to support segmentation.
11. Use the Exclude Message Headers check boxes to select which types of MQ
headers after the MQMD to remove from the message. By default only the MQMD
header is parsed. The following headers after MQMD, when selected, can be
removed:
v CICS Bridge Header (MQCIH)
v Dead Letter Header (MQDLH)
v IMS Information Header (MQIIH)
v Rules and Formatting Header (MQRFH)
v Rules and Formatting Header (MQRFH2)
v Working Information Header (MQWIH)
12. Specify the number of concurrent MQ connections to allocate in the The
number of concurrent MQ connections field. The minimum is 1. The default
is 1.
13. Specify the number of seconds before an MQGET operation returns if no
messages are available in the Polling Interval field. The next attempt will be
performed immediately. Setting a low value will help to detect quickly
network connectivity issues and queue manager power shutdown. At the
same time, a low value will increase network traffic. The minimum is 1. The
default is 30.
14. Select the MQ header structure from which to extract the Content-Type header
from the Header to Extract Content-Type list.
None (Default) No header
MQRFH
MQRFH header
MQRFH2
MQRFH2 header
15. If Header to Extract Content-Type is not None, specify the XPath expression
to extract the value of the Content-Type header in the XPath expression to
extract Content-Type from MQ header field. Click XPath Tool for help
building the XPath expression.
16. Use the Retrieve Backout Settings to determine whether to retrieve the
backout threshold and backout queue name from the MQ server.
on Retrieves backout settings from the MQ server and compares to the
backout values set in the MQ Queue Manager object. On retry, the
DataPower appliance uses the higher priority backout settings from

74 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 the MQ server. If MQ server does not contain backout settings, the
appliance uses existing backout properties, either empty or populated,
that are stored in the MQ Queue Manager object. If there are no
backout properties, backout is disabled.
off (Default) Do not retrieve backout settings from the MQ server. If these
properties already exist in the MQ Queue Manager object, the
appliance use those values.
17. Click Apply to save the object to the running configuration.
18. Optionally, click Save Config to save the object to the startup configuration.

NFS Poller Front Side Handler

An NFS Poller Front Side Handler object manages the polling of the remote NFS
server for available input with DataPower services.

This handler is available on the following appliances only:

v XML Security Gateway XS40
v XML Integration Appliance XI50
v B2B Appliance XB60

To configure an NFS Poller Front Side Handler, use the following procedure:
1. Select Objects Protocol Handlers NFS Poller Front Side Handler to
display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the directory to poll in the Target Directory field. The path must end
in a slash. The slash denotes a directory. For example, dpnfs://static-mount-
name/path/. Do not configure one NFS poller to point at a host name that is a
virtual name of a load balancer group. This configuration is not the correct
way to poll multiple hosts. To poll multiple hosts, use the same DataPower
service and configure one NFS poller object for each real host.
7. Specify the number of milliseconds to wait after the completion of one poll
before starting the next interval in the Delay Between Polls field. Use an
integer in the range of 25 through 100000. The default is 60000.
8. Specify the PCRE to use to match the contents of the directory being polled in
the Input File Match Pattern field. If there is file-renaming or there is a
response, this PCRE must create PCRE back references using () pairs.
For example, if the input files are NNNNNN.input, then the match pattern would
be ([0-9] {6})\.input.
9. Specify the PCRE to use to rename a file that is being processed in the
Processing File Renaming Pattern field. This functionality allows multiple
poller objects to poll the same directory with the same match pattern. There is
no lack of atomicity if the rename operation on the server is atomic. The
poller that succeeds in renaming the input file will proceed to process the file.
Any other poller that tries to rename the file at the same time will fail to
rename the file and will proceed to try the next file that matches the specified
match pattern.
To ensure uniqueness, the resulting file name will be in the following format:

Chapter 4. Configuring handler objects 75

 filename.serial.domain.poller.timestamp
where:
filename
The file name for the renamed input file.
serial The serial number of the configured DataPower appliance.
domain The domain of the polling object.
poller The name of the polling object.
timestamp
The timestamp.

Note: File renaming cannot be used with an NFS server that supports only 8.3
file names.
For example if the input files are NNNNNN.input and you want to rename them
to NNNNNN.processing, then the match pattern would be ([0-9] {6})\.input$
and the processing pattern would be $1.processing. The resultant file name of
the server would be:
NNNNNN.processing.serial.domain.poller.timestamp

Note: If no processing rename pattern is configured, the file will still be

renamed. The only difference is that the filename portion of the resulting
file is the name of the original input file, not the renamed input file.
10. Define the process for deleting files on success.
a. Use the Delete File on Success toggle to select whether to delete the input
file after successful processing.
on Deletes the input file.
off (Default) Renames the input file using the renaming pattern
specified by the Success File Renaming Pattern property.
b. When off, specify the PCRE to use to rename the input file on success in
the Success File Renaming Pattern field. This PCRE will normally have a
back reference for the base input file. For instance, if input files are
NNNNNN.input and you want to rename them to NNNNNN.processed, the
match pattern would be ([0-9] {0-6})\.input$ and the rename pattern
would be $1.processed.
Some servers might allow this pattern to indicate a path that puts the file
in a different directory, if it allows cross-directory renames. For instance,
the match pattern would be (.*) and the rename pattern would be
../processed/$1.
11. Define the process for deleting files on processing error.
a. Use the Delete File on Processing Error toggle to select whether to delete
the input or processing rename file when it could not be processed.
on Deletes the file.
off (Default) Renames the input or processing rename file using the
renaming pattern specified by the Error File Renaming Pattern
property.
b. When off, specify the PCRE to use to rename a file when it could not be
processed in the Error File Renaming Pattern field.
12. Define the process for creating result files.
a. Use the Generate Result File toggle to select whether to create a result file
after processing an input file.

76 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 on (Default) Creates the result file using the naming pattern specified
by the Result File Name Pattern property.
off Does not create the result file.
b. on, specify the PCRE to use as the match pattern to build the name of the
result file in the Result File Name Pattern field. This PCRE will normally
have a back reference for the base input file. For instance, if input files are
NNNNNN.input and you want to rename them to NNNNNN.result, the match
pattern would be ([0-9] {0-6})\.input$ and the rename pattern would
be $1.result.
Some servers might allow this pattern to indicate a path that puts the file
in a different directory, if it allows cross-directory renames. For instance,
the match pattern would be (.*) and the rename pattern would be
../result/$1.
13. Define the processing seize behavior.
a. Specify the time to wait in seconds before processing a file that is already
in the processing state in the Processing Seize Timeout field. Use an
integer in the range of 0 through 1000. The default is 0.
Processing seize allows failure handling of a poller when multiple data
routers are polling the same target. If another data router renames a file
and does not process (and rename or delete) it in the specified number of
seconds, this system attempts to take over processing. This system will
attempt to take over processing when all of these three conditions are met
when compared to the processing seize pattern. 1) The base file name (first
match phrase) is the processing seize pattern, 2) The host name (second
match phrase) is not the name of this system, 3) The timestamp (third
match phrase) is further in the past than the wait time specified by this
timeout. When these three conditions are met, this system renames the file
(with its host name and fresh timestamp) and locally processes the file.
This processing assumes that the rename succeeded.
b. Specify the PCRE to use to find files that were renamed to indicate that
they are in the being processed state but the processing was never
completed in the Processing Seize Pattern field.
The processing seize pattern contains three phrases that must be in \(\)
pairs. The first phrase is the base file name that includes the configured
processing suffix. The second phrase is the host name. The third phrase is
the timestamp.
14. Select the XML Manager that contains the User Agent configuration to use
from the XML Manager list.
15. Click Apply to save the object to the running configuration.
16. Optionally, click Save Config to save the object to the startup configuration.

SFTP Server Front Side Handler

An SFTP Server Front Side Handler object handles SSH File Transfer Protocol
(SFTP) communications protocol communications with DataPower services. These
services support client-side, SFTP communications when configured with an
instance of the SFTP Server Front Side Protocol Handler object. SFTP uses Secure
Shell version 2, which is known as SSH-2. This program provides the secure
channel between the SFTP client and the SFTP Server Front Side Handler
associated with a DataPower service.

This handler is available on the following appliances only:

v XML Integration Appliance XI50

Chapter 4. Configuring handler objects 77

 v B2B Appliance XB60

The Multi-Protocol Gateway service in this configuration is the SFTP server and
can receive transfers from the SFTP client and can support the transparent
operational mode. The communication between the Multi-Protocol Gateway service
and the remote FTP server uses the FTP protocol. The Multi-Protocol Gateway
service presents the directories and files as shown on the remote FTP server and
handles the protocol-specific commands.

Note: The only valid configuration with an SFTP Server handler is to manage files
on a remote FTP server.

Configuration considerations
Consider the following settings when configuring a Multi-Protocol Gateway
service:
v When transferring large files, use the streaming setting. To support bidirectional
streaming, set both the Stream Output to Back and Stream Output to Front
toggles to Stream Messages. For complete information, refer to Optimizing
through Streaming.
v For large files, set the back and front timeout values appropriately with the Back
Side Timeout and Front Side Timeout fields, respectively.

Authentication and authorization

Authentication is handled by the AAA Policy configured for the SFTP Server Front
Side Handler. The AAA Policy uses the information from the SSH key exchange.
Without an AAA Policy, any user is authenticated.

Authentication of the SFTP client with the SFTP Server Front Side Handler can be
either password or public key or both password and public key. If the
configuration includes both authentication methods, public key authentication is
attempted first.
v Host authentication public/private key needs to be and are stored on the
appliance.
v If a configuration does not specify the public/private key for host
authentication, the configuration uses the keys that are shipped with the
appliance.

Because at connection time the client does not specify which resource to access,
this AAA Policy can perform authentication only, not authorization.

To provide authorization, configure an AAA Policy in a processing rule. For this

AAA Policy, extract the identity using the ssh-password-metadata instance of the
Processing Metadata object.

SSH metadata variables

To support SSH-2 cryptographic and authentication on the DataPower appliance,
the SFTP Server Front Side Handler object requires an AAA Policy. The handler
uses the following read-only context variables as processing metadata with AAA
authentication:
v var://context/INPUT/ssh/username
v var://context/INPUT/ssh/password
v var://context/INPUT/ssh/publickey

78 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 These read-only variables allow AAA Policy objects to validate authentication
information from the SSH client to the handler.

The username and password variables are also available as processing metadata for
custom authentication in an AAA Info file.

None of these variables can be used by processing actions.

URL specifications with an SFTP handler

The use of SFTP URLs within custom style sheet is supported for communication
between the SFTP client and the SFTP Server Front Side Handler. SFTP URLs are
not supported for communication between the Multi-Protocol Gateway service and
the FTP server. In other words, the dp:url-open() extension element does not
support the SFTP protocol.

The URL has the following syntax:

sftp://address:port/path

Where:
address The IP address of the DataPower Ethernet interface
port The SFTP Server Front Side Handler listening port
path The fully qualified name of the file to transfer

When the client requests a directory listing, the URL contains a query parameter to
flag the request type. For example, a DIR request might generate the following
URL:
sftp://host.example.com:22/;type=d

The ;type=d query parameter is appended to the URL to designate the DIR request.
v If the Multi-Protocol Gateway service uses a static backend, the service adds the
?Listing=LIST query parameter before forwarding the request to the remote FTP
server.
v If the Multi-Protocol Gateway service uses either a dynamic backend or the
Propagate URI toggle is set to off, use a custom style sheet to modify the URL
before passing the request to the remote FTP server. For example, the style sheet
might test whether the value of the var://service/URI variable contains
;type=d. If it contains this query parameter, the style sheet replaces ;type=d with
?Listing=list and sets the value of the var://service/routing-url variable to
the resultant URL.

Configuring an SFTP Server handler

To configure an instance of an SFTP Server Front Side Handler object, use the
following procedure:
1. Select OBJECTS Protocol Handlers SFTP Server Front Side Handler to
display the catalog.
2. To display the configuration screen, click Add.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Define the connection from the client to the appliance.

Chapter 4. Configuring handler objects 79

 a. Specify the IP address on which the SFTP server listens in the Local IP
Address field. Defaults to 0.0.0.0, which indicates that the service is active
on all IP addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to
a static IP address. Aliasing can help when moving configurations across
systems.
b. Specify the port that the SFTP Server service monitors in the Port Number
field. This port is the port on which SSH connections can be established.
The default is 22.
7. Select an Access Control List from the Access Control List list.
8. Define the user authentication method.
a. Optionally, use the Host Private Keys controls to assign one or more Key
objects to use for host authentication.
Without keys, the configuration uses the default RSA and DSA keys
shipped on the appliance. Keys highest in the list are used first. There is a
limit of 256 keys. Only SSH-2 RSA and DSA keys are allowed.
b. Select Public Key or Password for the SSH User Authentication methods
available to the client. At least one method is required. If both are selected,
public key authentication is attempted first.
9. Use the Allow Backend Listings toggle to specify whether to allow directory
listings of the remote FTP server.
on (Default) Allows directory listings.
off Do not allow directory listings.
10. Select the AAA policy from the AAA Policy list.

Note: Although optional, without an AAA Policy, all users are authenticated.
11. Define the characteristics of the file system.
a. Retain the default setting of Transparent from the Filesystem Type list.
b. Specify the initial directory on the SFTP server (after users connect and
authenticate) in the Default Directory field. The default is the root
directory (/).
12. Specify the number of seconds that the SSH connection can be idle in the Idle
Timeout field. After the specified duration elapses, the SSH server closes the
connection. The default is 0, which disables the timeout.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

Stateful Raw XML Handler

A Stateful Raw XML Handler object handles raw XML messages that travel over a
stateful protocol communications link with clients (frontend) and servers
(backend). The messages begin and end with the root XML node. As with HTTP,
no headers are included.

Note: A DataPower service that uses a Stateful Raw XML Handler must employ a
dynamic backend.
1. Select Objects Services Stateful Raw XML Handler to display the Stateful
Raw XML Handler catalog.
2. Click Add to display the Stateful Raw XML Handler configuration screen.

80 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the host alias or IP address on which the service listens in the Local IP
Address field. The default is 0.0.0.0, which indicates that the service is active
on all addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to a
static IP address. Aliasing can help when moving configurations across
systems.
7. Specify the port monitored by the handler in the Port Number field. The
default is 3000.
8. Specify the host name or IP address of the backend Stateful Raw XML server
in the Remote Host field.
9. Specify the remote TCP port of the Stateful Raw XML server in the Remote
Port field. The default is 12000.
10. Use the Terminate Session On Fault toggle to select the behavior of closing
TCP connections on a fault. If enabled (on), both the front and back TCP
connections are closed when the DataPower appliance generates a fault. If
disabled (off), the default, only a connection termination, timeout, or error
close the session.
11. Select an SSL Proxy Profile to assign from the SSL Proxy Profile list.
12. Select an Access Control List to apply from the Access Control List list.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

Stateless Raw XML Handler

A Stateless Raw XML Handler object handles raw XML messages traveling over a
stateless protocol communication link with clients. The messages begin and end
with the root XML node. As with HTTP, the message does not include headers.
1. Select Objects Services Stateless Raw XML Handler to display the
Stateless Raw XML Handler catalog.
2. Click Add to display the Stateless Raw XML Handler Configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the host alias or IP address on which the service listens in the Local IP
Address field. The default is 0.0.0.0, which indicates that the service is active
on all addresses.
To use a local Host Alias instead of a static IP address, click Host Alias. A
Host Alias allows you to specify a locally configured alias that resolves to a
static IP address. Aliasing can help when moving configurations across
systems.
7. Specify the port monitored by the handler in the Port Number field. The
default is 4000.
8. Use Persistent Connections toggle to enable (on) or disable (off) persistent
TCP connections. When on, more than one transaction could be contained in

Chapter 4. Configuring handler objects 81

 the same TCP session. Persistent connections can speed end-to-end processing
when many small transactions flow through the appliance.
9. Select an SSL Proxy Profile to assign from the SSL Proxy Profile list.
10. Select an Access Control List to apply from the Access Control List list.
11. Click Apply to save the object to the running configuration.
12. Optionally, click Save Config to save the object to the startup configuration.

TIBCO EMS Front Side Handler

A TIBCO EMS Front Side Handler object enables support for the processing of
messages in TIBCO EMS format. TIBCO EMS supports queues and topic spaces.

This handler requires the TIBCO-EMS license and is available on the following
appliances only:
v XML Integration Appliance XI50
v B2B Appliance XB60
v Low Latency Appliance XM70

While the protocol handler does not provide native support for TIBCO
Rendezvous and TIBCO SmartSockets (TIBCO legacy messaging systems), TIBCO
EMS has built-in transports for these messaging implementations, which enables
message transfers.

Using topic spaces

A topic space is a hierarchy of topics used for publish-subscribe messaging. Topics
with the same name can exist in multiple topic spaces, but there can be only one
topic space with a given name in a service integration bus.

For example, consider a topic hierarchy split into the following topic spaces:
v library topics for document management
v sales topics for marketing and sales tracking
v engineering topics for engineering and technology

The topic volumes can appear in all three topic spaces, and have a very different
meaning in each.

Configuring a TIBCO EMS handler

To configure a TIBCO EMS Front Side Handler, use the following procedure:
1. Select Objects Protocol Handlers TIBCO EMS Front Side Handler to
display the TIBCO EMS Front Side Handler catalog.
2. Click Add to display the TIBCO EMS Front Side Handler configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the name of the GET queue in the Get Queue field. This queue is
where the handler gets messages.
7. Optionally specify the name of the PUT queue in the Put Queue field. This
queue is where the handler puts response messages.
If blank, no response is expected or wanted.

82 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 8. Optionally specify a an SQL-like expression to select messages from the GET
queue in the Selector field.
The message selector is a conditional expression based on a subset of SQL 92
conditional expression syntax. The conditional expression enables the handler
to identify messages of interest.
v If blank, all incoming client request messages are transferred by the handler
to the server object for processing.
v If specified, only those client requests that match the criteria specified by
the expression are forwarded to the server object for processing. All other
messages are dropped from the GET queue.
The conditional expression does not operate on the body of the message,
rather it examines the required headers and properties (proprietary
user-created headers that could appear between the required headers and the
message body).
The following headers are required:
Destination
Contains the destination (queue) to which the message is being sent
DeliveryMode
Contains the delivery mode (PERSISTENT or NON_PERSISTENT)
Expiration
Contains a message TTL or a value of 0 indicating an unlimited TTL
Priority
Contains the message priority expressed as a digit from 0 (lowest
priority) to 9 (highest priority)
MessageID
Contains a unique message identifier starting with the ID: prefix or a
null value. A null value effectively disables the message ID
Timestamp
Contains the time the message was handed off for transmission, not
the time it was actually sent
CorrelationID
Contains a means of associating one message (for example, a
response) with another message (for example, the original request)
ReplyTo
Contains the destination (queue) to which a reply to this message
should be sent
Type Contains a message identifier provided by the application
Redelivered
Contains a Boolean indicating that the message has been delivered in
the past, but not yet acknowledged
9. Select the TIBCO EMS server to associate from the TIBCO EMS Server list.
10. Select an SSL Proxy Profile to assign from the SSL Proxy Profile list.
11. Select an Access Control List to apply from the Access Control List list.
12. Click Apply to save the object to the running configuration.
13. Optionally, click Save Config to save the object to the startup configuration.

Chapter 4. Configuring handler objects 83

WebSphere JMS Front Side Handler
A WebSphere JMS Front Side Handler object enables support for the processing of
messages in default WebSphere JMS format. WebSphere JMS supports queues and
topic spaces.

This handler is available on the following appliances only:

v XML Integration Appliance XI50
v B2B Appliance XB60
v Low Latency Appliance XM70

Using topics spaces

A topic space is a hierarchy of topics used for publish-subscribe messaging. Topics
with the same name can exist in multiple topic spaces, but there can be only one
topic space with a given name in a service integration bus.

For example, consider a topic hierarchy split into the following topic spaces:
v library topics for document management
v sales topics for marketing and sales tracking
v engineering topics for engineering and technology

The topic volumes can appear in all three topic spaces, and have a very different
meaning in each.

Configuring a WebSphere JMS handler

To configure a WebSphere JMS Front Side Handler, use the following procedure:
1. Select the Objects Protocol Handlers WebSphere JMS Front Side Handler
to display the WebSphere JMS Front Side Handler catalog.
2. Click Add to display the WebSphere JMS Front Side Handler configuration
screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the name of the GET queue in the Get Queue field. This queue
contains client-originated WebSphere JMS request messages.
The WebSphere JMS handler monitors the GET queue for incoming client
requests. On receipt, the handler forwards the extracted message to the a local
WebSphere JMS object that will gateway the message to a remote WebSphere
JMS default message provider.
7. Optionally specify the name of the PUT queue in the Put Queue field. This
queue contains server-originated WebSphere JMS reply messages.
These messages are originated by a remote WebSphere JMS default message
provider and put into this queue by a local WebSphere JMS object
If blank, no response is expected or wanted.
8. Select the WebSphere JMS object to associate from the WebSphere JMS Server
list.
9. Optionally specify a nondefault topic space in the WebSphere JMS Topic
Space for Request field. Use this property to disambiguate a topic if the
request destination is a topic whose name appears in multiple topic spaces.

84 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

10. Optionally specify a nondefault topic space in the WebSphere JMS Topic
Space for Reply field. Use this property to disambiguate a topic if the
response destination is a topic whose name appears in multiple topic spaces.
11. Optionally specify a an SQL-like expression to select messages from the GET
queue in the Selector field.
The message selector is a conditional expression based on a subset of SQL 92
conditional expression syntax. The conditional expression enables the handler
to identify messages of interest.
v If blank, all incoming client request messages are transferred by the handler
to the server object for processing.
v If specified, only those client requests that match the criteria specified by
the expression are forwarded to the server object for processing. All other
messages are dropped from the GET queue.
The conditional expression does not operate on the body of the message,
rather it examines the required headers and properties (proprietary
user-created headers that could appear between the required headers and the
message body).
The following headers are required:
Destination
Contains the destination (queue) to which the message is being sent
DeliveryMode
Contains the delivery mode (PERSISTENT or NON_PERSISTENT)
Expiration
Contains a message TTL or a value of 0 indicating an unlimited TTL
Priority
Contains the message priority expressed as a digit from 0 (lowest
priority) to 9 (highest priority)
MessageID
Contains a unique message identifier starting with the ID: prefix or a
null value. A null value effectively disables the message ID
Timestamp
Contains the time the message was handed off for transmission, not
the time it was actually sent
CorrelationID
Contains a means of associating one message (for example, a response)
with another message (for example, the original request)
ReplyTo
Contains the destination (queue) to which a reply to this message
should be sent
Type Contains a message identifier provided by the application
Redelivered
Contains a Boolean indicating that the message has been delivered in
the past, but not yet acknowledged
12. Click Apply to save the object to the running configuration.
13. Optionally, click Save Config to save the object to the startup configuration.

Chapter 4. Configuring handler objects 85

86 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 5. Defining processing policies
This chapter describes how to create basic processing policies that operate on
documents that are presented to DataPower services.

Processing policies define many, if not all, of the actions that are taken against
documents that pass through the service.
v A processing policy consists of one or more rules.
v A rule consists of a matching rule and a processing rule.
v A matching rule defines the criteria to determine whether incoming traffic is
processed by its processing rule.
v A processing rule identifies the actions to perform against the incoming traffic.

The hierarchy of rules in a processing policy is important. The configuration screen

lists the sequence in which rules can be applied and provides directional arrows to
reorder the hierarchy. The service applies the first rule in the hierarchy that meets
the criteria in its matching rule.

When no rule in the processing policy meets the criteria in any of its matching
rules, a style sheet can be defined to process the incoming traffic. Defining a
default style sheet is not part of the processing policy. The default style sheet is
part of the service configuration.

Matching rules
A matching rule determines whether candidate traffic is subject to an associated
processing rule. Matching rules come in the following flavors:
v An HTTP matching rule tests HTTP header content. Simple matching expressions
enable the identification of specific HTTP header fields and header field
contents. These expressions are similar to those that define a Compile Options
Policy or a URL Refresh Policy.
v A URL matching rule uses simple matching patterns to test incoming URLs.
v An XPath matching rule uses an XPath expression applied to the incoming
message to determine a match. If the expression evaluates to true, a match is
made. The XPath Tool is available to help construct this expression.

While HTTP, URL, and XPath matching rules determine if incoming traffic is
subject to a processing rule, an error code rule provides the ability to provide
custom, user-defined error processing.

Processing rules
A processing rule specifies the processing actions to apply to incoming documents.
A processing rule can be as simple as a single action to transform of an incoming
XML document using a style sheet. On the other hand, a processing rule can be as
complex as an action that performs the following actions:
v Use several schema validations and style sheet filters to ensure that the
client-generated payload is not malicious.
v Transform the document to remove elements that are not needed by the backend
server.

Copyright IBM Corp. 2002, 2009 87

 v Route the transformed document to a dynamically determined server.

Processing rules are characterized by their direction.

v A client-to-server rule is applied to client requests
v A server-to-client rule is applied to server responses
v A two way rule is applied to both client request and server responses
v An error rule is applied only when an error occurs during document processing

Processing actions
Processing rules can contain the following actions. For details about defining the
listed actions within a processing rule, refer to Defining processing actions on
page 94.
AAA An aaa (Authentication, Authorization, Audit) action invokes an Access
control policy. An access control policy identifies a set of resources and
procedures that determine whether a requesting client is granted access to
a specific service, file, or document. Access control policies are filters in
that they accept or deny requests for specific clients. Refer to AAA (aaa)
action on page 94 for details.
Antivirus
An antivirus action invokes a named, reusable rule. This action sends
messages to a virus scanning server at a defined host/port or URI. This
action calls a style sheet that corresponds to the ICAP Host Type selected
to perform the scanning, sets the type of virus handling and error handling
to perform on the message after scanning, and sets the level of Virus
Scanner logs. Refer to Antivirus (antivirus) action on page 94 for details.
Call processing
A call action invokes a named, reusable rule. After the action completes,
processing continues to the next action, if any. Refer to Call processing
rule (call) action on page 96 for details.
Checkpoint event
A checkpoint action specifies an event to trigger the collection of
information for WS-Management agents and Service Level Monitors. This
action is available for Web Service Proxy services only. Refer to
Checkpoint event (checkpoint) action on page 97 for details.
Conditional
A conditional action implements programmatic if-then-else processing. If an
XPath expression returns true when applied to the input context of the
action, a designated processing action runs. Any number of if-then clauses
can be configured. A final else clause that uses an empty XPath expression
() runs a designated action when no other XPath expression matches the
input. You can designate a call action. The call action provides the ability
to run a complete processing rule that contains one or more actions. You
can configure a conditional action to provide the same service as a
complete processing policy, which gives you the ability to conditionally
invoke different processing policies on input.
Convert query parameters to XML
A convert-http action converts non-XML CGI-encoded input (an HTTP
POST, an HTML form, or URI parameters) into an equivalent XML
message. This action in the active rule alerts the service to treat input as
non-XML CGI-encoded input. For a service to use this action, the request

88 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 type for that service must be set to XML. Refer to Convert query
parameters to XML (convert-http) action on page 99 for details.
Crypto binary
A cryptobin action signs, verifies, encrypts, or decrypts binary data. This
action uses the syntax and methodologies that are described in RFC 2311,
S/MIME Version 2 Message Specification, dated March 1988, and RFC 2315,
PKCS #7: Cryptographic Message Syntax 1.5, dated March 1998. This action
requires that the appliance has the PKCS7-SMIME license. Refer to
Cryptographic binary (cryptobin) action on page 100 for details.
Decrypt
A decrypt action performs full or field-level document decryption. The
decrypt action requires that certain parameters be supplied during the
configuration of the service. Refer to Decrypt (decrypt) action on page
108 for details.
Encrypt
A encrypt action performs complete or field-level document encryption
using either WS-Security or XML encryption standards. The encrypt action
requires that certain parameters be supplied during the configuration of
the service. Refer to Encrypt (encrypt) action on page 110 for details.
Extract
An extract action applies an XPath expression to a specified context and
stores the result in another context. Refer to Extract using XPath (extract)
action on page 125 for details.
Event-sink
An event-sink action causes processing to wait until designated
asynchronous actions complete. The outputs of these asynchronous actions
can then be safely used by subsequent actions that are contained in the
processing rule. This action is useful for the parallel processing of actions.
For example, the appliance can parallelly contact remote resources, such as
an authentication server or a Web server, that located on the network. With
parallel processing, the processing time is reduced to the latency of the
slowest response. With serial processing, the appliance waits for network
operations to complete and therefore incur the latency of network
operations. By including network-oriented actions in this action, their
results become available for subsequent processing.
Fetch A fetch action uses a user agent to retrieve a document from a specified
location. Refer to Fetch (fetch) action on page 125 for details.
Filter A filter action accepts or rejects check on incoming documents. Refer to
Filter (filter) action on page 126 for details.
For-each
The for-each action implements a programmatic loop for each of the defined
actions. Each time an XPath expression returns true, a designated action
runs. The for-each can be used to apply a series of style sheets to input
data, if desired. Instead of using XPath expressions, the loop can be
processed a specific number of times. Each iteration of the loop stores its
results in a separate output context. These output contexts are available to
any other action in the processing policy. Refer to For-each (for-each)
action on page 130 for details.
Log The log action sends the contents of the input context as a log message to
the identified location. The contents are sent with the log level and log

Chapter 5. Defining processing policies 89

 type that are specified. The response, if any, is stored in the output context,
if one is defined. Refer to Log (log) action on page 133 for details.
On error
An on-error action defines a named rule that enables user-defined error
handling when subsequent processing encounters errors. The on-error
action either stops processing or continues to the next processing step.
Optionally the action calls the named rule to handle the error condition.
Without an on-error action, the default error handling is to stop processing
and log a message.
A processing rule can contain one or more on-error actions. Each action
defines error handling for subsequent actions until another on-error action
is found. When another action is found, error-handling procedures are set
to the new on-error action. As such, this action enables conditional error
handling in a processing context.
Refer to On error (on-error) action on page 138 for details.

Note: A processing policy can contain on-error actions and an error rule.
When a processing policy contains both on-error actions and an
error rule, the on-error action overrides the error rule. An error rule,
if the processing policy contains one, is invoked when an error
occurs during processing. In this case, the error rule acts as an error
handler.
Results
A results action sends a message to a URL. A results action can optionally
specify a context in which to store the response. Refer to Results (results)
action on page 140 for details.
Results asynchronous
A results-async action asynchronously sends a message to a URL. This
action does not support sending a message to an output context. With this
action, processing continues without waiting for a response. Refer to
Results Asynchronous (results-async) action on page 141 for details.
Rewrite header
A rewrite action rewrites HTTP headers or URLs using a URL rewrite
policy. Refer to Rewrite header (rewrite) action on page 142 for details.
Route with style sheet or XPath
A route-action action performs style sheet-based routing or XPath
expression-based routing. Refer to Route with style sheet (route-action)
action on page 143 and Route with XPath expression (route-action)
action on page 143, respectively, for details.
Route with variables
A route-set action performs dynamic, variable-based routing. Refer to
Route with variables (route-set) action on page 144 for details.
Set variable
A setvar action creates a variable for use in subsequent processing in a
specified context. Variables are expressed in the var://URL format.
Variables cannot be set when the context is the PIPE keyword. This
keyword is used for streaming. Refer to Set variable (setvar) action on
page 145 for details.
Sign A sign action attaches a digital signature to the document. This action
requires that certain parameters be supplied during the configuration of
the service. Refer to Sign (sign) action on page 145 for details.

90 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 Enforce SLM policy
An slm action assigns and enforces an SLM policy statement. The SLM
policy operates on the content of the input context. This action is available
for Web Service Proxy or Multi-Protocol Gateway services only. Refer to
SLM (slm) action on page 147 for details.
Run SQL statement
An sql action establishes a connection to a configured database and runs
SQL statements against the configured SQL data source. The results can be
used for further processing. This action requires that the appliance has the
SQL-ODBC license. Refer to SQL (sql) action on page 147 for details.
Strip attachments
A strip-attachments action removes all or specified MIME attachments from
a specified context. Refer to Strip attachments (strip-attachments) action
on page 148 for details.
Transform
An xform action transforms an XML document using a specified XSLT style
sheet. Refer to Defining a transform for XML messages on page 149 for
details.
Transform binary
The xformbin action transforms a non-XML document, such as binary or
flat text, using a processing control file. The control file, in turn, uses a flat
file descriptor (FFD) file. This action requires that the appliance has the
DataGlue license. Refer to Defining a transform for non-XML messages
on page 150 for details.
Transform using processing instruction
An xformpi action uses a processing instruction in an XML document to
transform that XML document. The xformpi action passes embedded
parameters to the specified XSLT style sheet. The style sheets and
parameters are embedded in the document to be processed. For example, if
the document contains the following declaration:
<?xml-stylesheet type="text/xsl" href="reformat.xsl?target=mainframe"/>

The action passes the target=mainframe parameter to the reformat.xsl

style sheet.

Refer to Defining a processing instruction-based transform for XML

messages on page 151 for details.
Validate
A validate action performs schema-based validation against XML
documents using a user-specified method. Refer to Validate (validate)
action on page 155 for details.
Verify A verify action validates the digital signature on an incoming document.
The verify action requires that certain parameters be supplied during the
configuration of the service. Refer to Verify (verify) action on page 157
for details.

Contexts
A context can be described as a temporary variable that contains data used by a
processing action. The input context, the context specified for the Input field,
contains the data to be processed. The output context, the context specified for the
Output field, receives the data produced by the action.

Chapter 5. Defining processing policies 91

 v Some actions require both an input context and an output context.
v Some actions require an input context only.
v Some actions require an output context only.
v Some actions require neither an input context or an output context.

The data for the contexts can be XML or non-XML. XML data is expressed in a tree
format. Non-XML data is binary. When the data is XML, the XML tree can include
lists of variables and attached documents.

The context can also be a variable. Refer to Set variable (setvar) action on page
145 for more information.

Context in processing rules

A processing rule can contain multiple actions. A processing rule sequentially
performs, left to right, the actions that are defined in the scope of this single rule.
Subsequent actions in a processing rule can access the output context of any of the
prior actions.

Context keywords
Processing rules recognize the following keywords and apply special context to
them:
INPUT The input to the processing action.
v For a client-to-server rule, the INPUT context is the data that is associated
with the request; for example, a client-generated POST body.
v For a server-to-client rule, the INPUT context is the server-generated data
that is sent in response to a client request.
OUTPUT The product of the processing action.
v For a client-to-server rule, the OUTPUT context is the data that is sent to
the server.
v For a server-to-client rule, the OUTPUT context is the data that is sent to
the client.
NULL Can be used as an input or output.
v As the input for an action, the NULL context indicates that the action
processes an empty XML document.
v As the output for an action, the NULL context indicates that the action
discards any data that it receives from processing.
PIPE The output of an action becomes the input to the next action. As such, any
action that uses the PIPE context as output must be followed by an action
that uses the PIPE context as input. The PIPE context is useful in certain
instances to reduce processing latency. The PIPE context is the correct
choice for streaming operations.

Creating processing policies

A Processing Policy consists of one or more processing rules. Each individual
processing rule is associated with a Matching action that specifies a document set
subject to the rules directives. The Matching action acts as a gatekeeper at the start
of the rule to determine which documents the rule should handle. Matches can be
based on HTTP header tag values, URLs, XPath expressions, or error codes.

92 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

Rules are maintained in a particular order in a single policy. Candidate documents
presented to the processing policy are sequentially evaluated against each of the
rules in the policy. Consequently the order of rules is critical to ensure the
intended behavior.

Error rules are the exception to this behavior. Regardless of where the error rule is
in the processing policy, an error rule runs last and only when there are errors
during the processing of any the other rules.

For example, Figure 5 illustrates a rule that employs multiple actions. The
transform occurs before the validation. Changing the sequence of actions could
have significant impact on the results of this rule.

Figure 5. Rule Action ordering

To create a processing policy, use the following procedure:

1. Display the processing policy catalog for the DataPower service:
v For an XSL Proxy service, select Services XSL Service XSL Proxy Policy.
v For an XML Firewall service, select Services XML Firewall XML Firewall
Policy
v For a Multi-Protocol Gateway service, select Services Multi-Protocol
Gateway Multi-Protocol Gateway Policy
v For a Web Service Proxy service, select Services Web Service Proxy Edit
Web Service Proxy to display the configuration screen. Select the Policy tab.
Continue with step 4.
2. Click Add New Policy to display the processing policy configuration screen.
3. Specify the name of the processing policy in the Policy Name field.
4. In the Rules section, click New Rule to define a processing rule for this
Processing Policy. For Web Service Proxy services, click Add Rule. The Rule
Name field contains an auto-generated name.
5. Modify the name of the rule as appropriate.
6. Select the directory of the rule or indicate that the rule is an error-handling rule
from the Rule Direction list.
Both Directions
The rule applies to all traffic going through the service.
Error Identifies the rule as an error-handling rule. This rule is invoked only
when an error occurs during processing.
Client to Server
The rule applies to client-generated requests that go through the
service. Client requests arrive at the front end addresses of the service.

Chapter 5. Defining processing policies 93

 Server to Client
The rule applies to server-generated responses that go through the
service. Server responses arrive at the backend addresses of the service.
7. Double-click the Match icon to display the Match Assignment window.
a. From the Matching Rule list, select a matching rule. Refer to Matching
Rule on page 292 for more information.
b. Click Done to assign the matching rule to the processing rule.
8. Create the processing rule by dragging action icons to the configuration path.
9. After adding the last action to the processing rule, click Apply to add the
completed rule to the processing policy.

To add additional processing rules to the processing policy, repeat step 4 on page
93 through step 9.

All candidate documents are processed by the rule that conforms to the defined
direction and matching rule.

Defining processing actions

This sections contains the procedures for defining each of the available processing
actions.

AAA (aaa) action

To add an aaa action, use the following procedure:
1. Drag the AAA icon to the configuration path (the horizontal line).
2. Double-click the AAA icon to display the AAA action window.
3. Specify or select the context for the data to be processed in the Input field.
4. From the AAA Policy list, select an instance of the AAA Policy. Refer to
Chapter 6, Defining an AAA Policy, on page 165 for complete information
about creating an AAA Policy.
5. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
6. Optionally specify or select the context for the data produced in the Output
field.
7. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Antivirus (antivirus) action

To add an antivirus action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).

94 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Anti-Virus radio button.
4. Click Next to display the Configure Anti-Virus action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Determine the type of antivirus scan with the Anti-Virus Scan Type radio
buttons.
v To scan the message body and attachments, click Scan Entire Message.
v To scan attachments only, click Scan All Attachments.
v To scan attachments only when the Content-Type header matches a PCRE:
a. Click Scan Attachments by Content Type
b. Specify the PCRE in the Attachment Content-Type (PCRE) field.
v To scan attachments only when the URI matches a PCRE:
a. Click Scan Attachments by URI
b. Specify the PCRE in the Attachment URI (PCRE) field.
v To scan only the contents of a message that matches an XPath expression:
a. Click Scan by XPath Expression
b. Specify the XPath expression in the XPath field.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression by
selecting the desired mode.
8. Determine which ICAP Host to use for the Virus Scanner server with the
ICAP Host Type radio button.
v To use a Clam ICAP host on a Virus Scanner server, click Clam.
v To use a Symantec ICAP host on a Virus Scanner server, click Symantec.
v To use a Trend Micro ICAP host on a Virus Scanner server, click Trend
Micro.
v To use a Webwasher ICAP host on a Virus Scanner server, click Webwasher.
v To use a Custom ICAP client on a Virus Scanner server:
a. Click Custom.
b. (Scroll to the top of the screen.) Use the Processing Control File field or
specify the style sheet to perform document filtering and
transformations.
If the style sheet is not stored on the appliance, specify its location or
a variable that expands to a URL. If a variable, use the
var://context/name form.
If the style sheet is in the store: or local: directory, select the style
sheet.

Chapter 5. Defining processing policies 95

 You can click Upload or Fetch to obtain the file.
9. Specify the host name of the Virus Scanner in the Remote Host Name field.
10. Optionally specify the Remote Port of the Virus Scanner in the Remote Port
field.
11. Optionally specify the Remote URI of the Virus Scanner in the Remote URI
field.
12. Determine the behavior of the Antivirus Policy with the AntiVirus Policy
radio buttons:
v To have the Antivirus Policy log but not reject messages or strip
attachments, click Log.
v To have the Antivirus Policy reject the message, click Reject.
v To have the Antivirus Policy strip offending attachments, click Strip.
13. Determine the behavior of the Antivirus Error Policy with the AntiVirus Error
Policy radio buttons.
v To have the Antivirus Error Policy log but not reject messages or strip
attachments, click Log.
v To have the Antivirus Error Policy reject the message, click Reject.
v To have the Antivirus Error Policy strip offending attachments, click Strip.
14. Use the Log Category list to assign a Log Category.
15. Specify or select the context for the data produced in the Output field.
16. Click Done to complete the action. The configuration path shows the
Antivirus icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Call processing rule (call) action

To add a call action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Call Processing Rule radio button.
4. Click Next to display the Configure Call Processing Rule action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Use the Processing Rule controls to select the target rule. The target rule is the
rule that this action calls. For information about creating reusable processing
rules, refer to Defining reusable rules on page 158.
To define a target rule, do one of the following:
v Select a processing rule from the list of available processing rules.
v Click Var Builder to use the variable builder to define a custom context
variable for a processing rule. Refer to Using the variable builder on page
162 for details.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.

96 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify or select the context for the data produced in the Output field.
9. Click Done to complete the action. The configuration path shows the Call
Processing icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

After you click Apply or Apply Policy, the Call Processing icon expands to the
icons for the actions in the reusable rule.

Checkpoint event (checkpoint) action

To add a checkpoint action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Checkpoint Event radio button.
4. Click Next to display the Checkpoint Event action window.
5. Specify or select the context for the data to be processed in the Input field.
6. From the Checkpoint Event list, select the type of event that triggers the
checkpoint.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Click Done to complete the action. The configuration path shows the
Checkpoint Event icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Conditional (conditional) action

To add a conditional action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Conditional radio button.

Chapter 5. Defining processing policies 97

 4. Click Next to display the Configure Conditional action window.
5. Specify or select the context in the Input field. The XPath expressions used for
Match Conditions apply to the data in the context selected.
6. Enter an XPath expression in the Match Condition field. Click the XPath Tool
button to use a graphic tool to construct the expression.
7. Create the action to run when the Match Condition evaluates to true. This
action is known as the conditionally invoked action.
a. Select the action type from the Action list.
b. Click Create Action. The WebGUI displays the configuration panel for the
selected action type in a new window.
c. Configure the newly created action as needed. Consider the following
points when configuring this action.
v The input context of the conditionally invoked action can be different
from the input context of the conditional action itself. Typically, the
input context of the conditionally invoked action is the same as the
conditional action.
v This action can operate in any manner, including as a filter that either
accepts or rejects the message, thus continuing or halting the processing
of the processing rule. Examples include signature verification, custom
filtering style sheets and AAA actions.
v This action can be a call action, allowing the processing of an entire
Processing Rule.
v This action cannot be the conditional action. A recursive conditional
action cannot be invoked. This action can be a different conditional
action that does not contain a loop back to this conditional action.
v The output context of this action can take any valid value, including
OUTPUT.
v This action can run asynchronously. However, when this action is
configured to run asynchronously, the action that follows the
conditional action is run immediately. Any action that follows the
conditional action cannot use the output context of the asynchronous
action as its input context.
d. Click Done to complete the action. The window closes. The Configure
Conditional Action panel lists the new statement.
8. Repeat the previous step as many times as desired. Note the following points:
v The action evaluates the statements in the order given, top to bottom. Only
the first matching statement runs. Use the arrow icons to reorder the list, or
click the X icon to delete a statement from the list.
v To create an else condition, create the last statement using a universal
matching condition, such as /*. This guarantees that if all other matching
conditions fail to match, the last statement runs.
v If no statement matches, the conditional action completes without running
any action.
9. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.

98 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide

 When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
10. Click Done to complete the action.

The conditional action requires no output context. To use the output of the
conditionally invoked action, a processing action that follows the conditional
action must use, as its input context, the output context of the conditionally
invoked action. For example, a conditional action can run one of a range of
Transform actions based on the match condition that applies to the request
message. Each of the Transform actions uses custvar1 as the output context. The
first action in the processing rule after the conditional then uses custvar1 as the
input context.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Convert query parameters to XML (convert-http) action

To add a convert-http action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Convert Query Parameters to XML radio button.
4. Click Next to display the Convert Query Parameters to XML action window.
5. Specify or select the context for the data to be processed in the Input field.
6. From the Input Conversion list, select the map that contains the conversion
rules.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify or select the context for the data produced in the Output field.
9. Click Done to complete the action. The configuration path shows the Convert
Query Param to XML icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Chapter 5. Defining processing policies 99

 Cryptographic binary (cryptobin) action
Use the procedures in this section to add cryptobin actions of for the following
cryptographic operations:
v Signing documents
v Verifying signed documents
v Encrypting documents
v Decrypting documents

Signing PKCS #7 documents

To define a cryptobin action that signs PKCS #7 documents, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Crypto Binary radio button.
4. Click Next to display the Crypto Binary action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Check the PKCS#7 Sign radio button to select document signature.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Define the Signers settings. Use the Signers list with the Add and Delete
buttons to identify the document signatories.
PKCS supports one or multiple document signatories; add the Identification
Credentials Set for each signer to the Signers list.
9. Use the Include Content Data toggle to specify an enveloped or detached
signature.
on (Default) Specifies the commonly-used enveloped signature in which
the signed data is included in the PKCS #7 SignedData type.
off Specifies the less-commonly-used detached signature in which the
signed data is not included in the PKCS #7 SignedData type. This
signature format is used with S/MIME documents.
10. From the Input Encoding Format list, select the input format to characterize
the data to sign.
None (Default) use this value for all inputs other than Base64.
Base64
Use this value to characterize the data to be signed using Base64
encoding.
11. Select the output format to characterize the signed PKCS #7 object (SignedData
produced by the signature process) from the Output Encoding Format list.

100 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
12. Use the Binary Data toggle to indicate whether the input data is true binary
and should be canonicalized. This finer characterization enables or disables
the canonicalization of line endings in the input data.
on Characterizes input data as true binary, that is consisting of
meaningful 8-bit data units, and is not canonicalized before signing.
Canonicalization can corrupt the data.
off Indicates that the input data is not true binary and can be
canonicalized. Use this setting if the input data is a raw-text string
that consists of meaningful 7-bit data units.
When creating a detached S/MIME signature (where Output Encoding
Format is S/MIME and Include Content Data is off), setting Binary Data to
off can produce an unverifiable signature since the data is not canonicalized
as expected for an S/MIME message.
True binary data should be Base64 encoded before signing with a detached
S/MIME signature.
Binary Data can be set to off for Base64 encoded data.
13. Specify or select the context for the data produced in the Output field.

By default, this action uses the pkcs7-sign.xsl style sheet to sign documents. To use
another style sheet, use the Advanced panel to identify the style sheet and any
parameter that is required by that style sheet.
14. If the action is complete, click Done. The configuration path shows the Crypto
Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
1. Click the Advanced tab to display the Advanced screen.
2. Confirm the Input setting.
3. Confirm that the Action Type is cryptobin.
4. Confirm that the PKCS#7 Sign radio button is selected.
5. Confirm the Asynchronous setting.
6. Use the Processing Control File field or select the style sheet to perform
PKCS #7 signing.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
7. To define parameters for the style sheet, click Add Parameter (at the bottom
of the window).
a. In the Stylesheet Parameter Name field, specify the name of the
parameter.
b. In the Stylesheet Parameter Value field, specify the value for the
parameter.
c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.

Chapter 5. Defining processing policies 101

 Repeat this step to define each additional parameter.
8. Confirm the Signers setting.
9. Confirm the Include Content Data setting.
10. Confirm the Input Encoding Format setting.
11. Confirm the Output Encoding Format setting.
12. Confirm the Binary Data setting.
13. If necessary, define the following settings:
Include text/plain Header
When the Output Encoding Format is S/MIME and the Binary Data
is off, adds a Content-Type:text/plain MIME header to the input
data prior to the signature process. The added header is part of the
signed data.
By default, the header is not added. Some S/MIME clients, however,
require such a header as part of the data.
Include Signers Certificate
By default, the public certificate of each message signer is included
with the signed document. PKCS #7 supports multiple signing entities.
When set to off, signer certificates are not included. The verifying
entity must procure them through other means.
Include CA Certificates
By default, the Intermediate CA certificates of each message signer are
included with the signed document. PKCS #7 supports multiple
signing entities.
When set to off, CA certificates are not included. The verifying entity
must procure them through other means.
Include Authenticated Signed Attributes
By default, the action includes contentType, signingTime, and
messageDigest attributes in the signature.
When set to off, these attributes are not added to the signature.
Additional Certificates
Refer to Include Certificates Only.
Include Certificates Only
Used with Additional Certificates, and only if the PKCS #7 file
consists solely of a group of certificates. Any input data is ignored.
When set to off, the unsigned output produced by the action consists
of the certificates that are identified by Additional Certificates and
any certificate that is identified by Signers and Include CA
Certificates, although certificate identification by these last two
properties is optional.
Name of Context Variable Holding Output Metadata
Specifies the name of the context variable to which the output of this
operation (including error strings, if any) is written. The string
var://context/ is prepended to the specified name.
14. Click Done to complete the action. The configuration path shows the Crypto
Binary icon.

102 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Verifying PKCS #7 signed documents

To define a cryptobin action that verifies PKCS #7 signatures, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Crypto Binary radio button.
4. Click Next to display the Crypto Binary action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Check the PKCS#7 Verify radio button. The display refreshes with
operational-specific parameters.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Select the validation credentials list that contain certificates for all signatories
from the Validation Credential list.
9. Select the input format to characterize the data (SignedData type) to be
verified from the Input Encoding Format list.
10. Select the output format of the verified data from the Output Encoding
Format list.
11. Specify or select the context for the data produced in the Output field.

By default, this action uses the pkcs7-verify.xsl style sheet to verify signatures. To
use another style sheet, use the Advanced panel to identify the style sheet and any
parameter that is required by that style sheet.
12. If the action is complete, click Done. The configuration path shows the Crypto
Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
1. Click the Advanced tab to display the Advanced screen.
2. Confirm the Input setting.
3. Confirm that the Action Type is cryptobin.
4. Confirm that the PKCS#7 Verify radio button is selected.
5. Confirm the Asynchronous setting.

Chapter 5. Defining processing policies 103

 6. Use the Processing Control File field or select the style sheet used by this
cryptobin verify action to perform signature verification.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
7. To define parameters for the style sheet, click Add Parameter (at the bottom
of the window).
a. In the Stylesheet Parameter Name field, specify the name of the
parameter.
b. In the Stylesheet Parameter Value field, specify the value for the
parameter.
c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.
Repeat this step to define each additional parameter.
8. Confirm the Validation Credential setting.
9. Confirm the Input Encoding Format setting.
10. Confirm the Output Encoding setting.
11. If necessary, define the following settings:
Maximum Number of Signatures to Verify
By default, the action verifies a maximum of 10 signatures. This
limitation guards against a Denial of Service (DoS) attack launched by
a document that contains an exceedingly large number of signatures.
You can change the default to any integer between 1 and 25.
Additional Certificates to Check for Signers
Certificates of PKCS #7 signers are identified by the issuing CAs
distinguished name and by the issuer-specific serial number that is
contained in the PKCS #7 SignerInfo type. The standard does not
specify that the certificate itself be included with the signed content.
You can use the Add and Delete buttons with the list to create a list of
certificates used to validate the certificates presented or referenced by
document signatories.
Allow Internal Signers Certificates
Certificates providing a chain-of-trust for signatories can be optionally
included in the PKCS #7 SignedData type; certificates need not be
included.
By default, the action uses included certificates in its efforts to verify
signatures, in addition to the certificates that are specified by the
Additional Certificates to Check for Signers property.
Setting Allow Internal Signers Certificates to off, prohibits the action
from using included certificates, thus limiting its verification efforts to
the certificate set that is specified by Additional Certificates to Check
for Signers.
URL Location of Detached Data
Specifies the location of the detached data that was signed by the
PKCS #7 SignedData type. Used only when verifying a detached
signature where the encoding format of the input data not S/MIME.

104 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Detached Data Encoding Format
Specifies the encoding format of the detached data that was signed.
Base64 encoded binary
Specifies that the data is Base64 encoded
Binary
Specifies binary data
Name of Context Variable Holding Output Metadata
Specifies the name of the context variable to which the output
of this operation (including error strings, if any) is written.
The string var://context/ is prepended to the specified name.
12. Click Done to complete the action. The configuration path shows the Crypto
Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Encrypting PKCS #7 documents

To define a cryptobin action that encrypts PKCS #7 documents, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Crypto Binary radio button.
4. Click Next to display the Crypto Binary Action (Basic) window.
5. Specify or select the context for the data to be processed in the Input field.
6. Click the PKCS#7 Encrypt radio button to select document encryption, and
display operational-specific parameters.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Select the encryption method from Encryption Algorithm list and click
9. Select the format to characterize the data to be encrypted from the Input
Encoding Format list.
10. Select the format to characterize the encrypted PKCS #7 object (EnvelopedData
type produced by the encryption process) from the Output Encoding Format
list.
11. Use the Binary Data toggle to further characterize the input data to be
encrypted. This finer characterization enables or disables the canonicalization
of line endings.
on Characterizes input data as true binary, that is consisting of
meaningful 8-bit data units. Such data is not canonicalized before
encryption.
Chapter 5. Defining processing policies 105
 off Indicates that the input data is not true binary and can be
canonicalized. Use this setting if the input data is a raw-text string
consisting of meaningful 7-bit data units.
12. Specify the Recipients settings.
Use the Add and Delete buttons with the associated list to specify the
recipients (one or more) of the encrypted message. The certificates of the
message recipients are required to encrypt the key wrapping key.

By default, this action uses the pkcs7-encrypt.xsl style sheet to encrypt documents.
To use another style sheet, use the Advanced panel to identify the style sheet and
any parameter that is required by that style sheet.
13. If the action is complete, click Done to complete the action. The configuration
path shows the Crypto Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
1. Click the Advanced tab to display the Advanced screen.
2. Confirm the Input setting.
3. Confirm that the Action Type is cryptobin.
4. Confirm that the PKCS#7 Encrypt radio button is selected.
5. Confirm the Asynchronous setting.
6. Use the Processing Control File field or specify the style sheet used by this
cryptobin encrypt action to perform document encryption.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
7. To define parameters for the style sheet, click Add Parameter (at the bottom
of the window).
a. In the Stylesheet Parameter Name field, specify the name of the
parameter.
b. In the Stylesheet Parameter Value field, specify the value for the
parameter.
c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.
Repeat this step to define each additional parameter.
8. Confirm the Encryption Algorithm setting.
9. Confirm the Input Encoding Format setting.
10. Confirm the Output Encoding Format setting.
11. Confirm the Binary Data setting.
12. Confirm the Recipients setting.
13. If necessary, define the following settings.
Include text/plain Header
Adds a Content-Type:text/plain MIME header to the input data

106 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 prior to the encryption process. Used only when Output Encoding
Format is S/MIME and Binary Data is off. The added header becomes
part of the encrypted data.
By default, the header is not added. Some S/MIME clients, however,
require such a header as part of the data.
Name of Context Variable Holding Output Metadata
Specifies the name of the context variable to which the output of this
operation (including error strings, if any) is written. The string
var://context/ is prepended to the specified name.
14. Click Done to complete the action. The configuration path shows the Crypto
Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Decrypting PKCS #7 documents

To define a cryptobin action that decrypts PKCS #7 documents, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Crypto Binary radio button.
4. Click Next to display the Crypto Binary action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Click the PKCS#7 Decrypt radio button to select document encryption and
display operational-specific parameters.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. From the Input Encoding Format list, select the input format to characterize
the encrypted PKCS #7 object (EnvelopedData type) to be decrypted.
9. From the Output Encoding Format list, select to output format of the
decrypted data.
10. Specify the Recipients settings. Use the Add and Delete buttons to select the
ID credentials, certificate, and private key for each message recipient. The
private key decrypts the key wrapping key.

By default, this action uses the pkcs7-decrypt.xsl style sheet to decrypt documents.
To use another style sheet, use the Advanced panel to identify the style sheet and
any parameter that is required by that style sheet.
11. If the action is complete, click Done. The configuration path shows the Crypto
Binary icon.

Chapter 5. Defining processing policies 107

 If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Advanced settings: Use the Advanced screen to identify the style sheet and
define less commonly used settings.
1. Click the Advanced tab to display the Advanced screen.
2. Confirm the Input setting.
3. Confirm that the Action Type is cryptobin.
4. Confirm that the PKCS#7 Decrypt radio button is selected.
5. Confirm the Asynchronous setting.
6. Use the Processing Control File field or specify the style sheet used by this
cryptobin decrypt action to perform document decryption.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
7. To define parameters for the style sheet, click Add Parameter (at the bottom
of the window).
a. In the Stylesheet Parameter Name field, specify the name of the
parameter.
b. In the Stylesheet Parameter Value field, specify the value for the
parameter.
c. Click Submit to return to the Advanced window, which now lists the
newly defined parameter.
Repeat this step to define each additional parameter.
8. Confirm the Input Encoding Format setting.
9. Confirm the Output Encoding Format setting.
10. Confirm the Recipients setting.
11. If necessary, define the following settings.
Remove text/plain Header
Removes a Content-Type:text/plain MIME header from the plaintext,
decrypted data. Used only when Input Encoding Format is S/MIME.
By default, the header (if present) is not removed.
Name of Context Variable Holding Output Metadata
Specifies the name of the context variable to which the output of this
operation (including error strings, if any) is written. The string
var://context/ is prepended to the specified name.
12. Click Done to complete the action. The configuration path shows the Crypto
Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Decrypt (decrypt) action

This action might require that certain parameters be supplied during the
configuration of the service.

108 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
To add a decrypt action, use the following procedure:
1. Drag the Decrypt icon to the configuration path (the horizontal line).
2. Double-click the Decrypt icon to display the Decrypt action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Use the Message Type radio buttons to characterize the decryption.
Entire Message/Document
(Default) Decrypts the entire document
Selected Elements (Field-level)
Decrypts specific fields in the document
5. If the Message Type is Selected Elements (Field-level), from the Document
Crypto Map list, select the Document Crypto Map to identify the message
fields that were encrypted. Refer to Document Crypto Map on page 282 for
more information.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. If the Message Type is Entire Message/Document, optionally select a Key to
use for decrypting the contents from the Decrypt Key list.

Note: If you do not specify a decrypt key, you must create a Crypto
Identification Credentials set that identifies the cryptographic key to use
to decrypt the document. This credential set associates the certificate that
was used to encrypt the document with the key that can decrypt the
document. Without this credential set, the action cannot decrypt the
document.
8. Specify or select the context for the data produced in the Output field.

By default, this action uses the decrypt.xsl style sheet to decrypt documents. To use
another style sheet, use the Advanced tab to identify the style sheet and any
parameter that is required by that style sheet.
9. If the action is complete, click Done.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Advanced settings
Use the Advanced screen to identify the style sheet and define less commonly used
settings.
1. Click the Advanced tab to display the Advanced screen.
2. Use the Processing Control File field or select the style sheet used by this
decrypt action.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
Chapter 5. Defining processing policies 109
 v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
3. Use the Optimize Element Description toggle to enable or disable optimization
of the decrypted data.
According to the encryption specifications, decrypting element-encrypted data
(instead of content-encrypted) should result in valid XML. The decrypted data
should contain all of the required namespace prefix bindings that are needed to
parse the resulting XML data.
on Enables optimization. If you know that the source of the encrypted data
follows this specification, use this setting. Enabling optimization might
improve performance. Decryption does not require extra
canonicalization.
off (Default) Disables optimization. For compatibility, optimization might
need to be disabled. Not all XML encryption appliances follow the
rules for preparing data before encryption.
4. To define parameters for the style sheet, click Add Parameter (at the bottom of
the window).
a. In the Stylesheet Parameter Name field, specify the name of the parameter.
b. In the Stylesheet Parameter Value field, specify the value for the parameter.
c. Click Submit to return to the Advanced window, which now lists the newly
defined parameter.
Repeat this step to define each additional parameter.
5. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Encrypt (encrypt) action

You can define an encrypt action to perform the following types of encryption:
v Encrypt a SOAP message (with or without attachments) with WS-Security
encryption. This action encrypts the child element of the SOAP body.
v Encrypt a SOAP message (without attachments only) with standard XML
encryption. This action encrypts each child of the SOAP body.
v Encrypt a raw XML message with standard XML encryption.
v Encrypt select elements of a SOAP message or an XML message. This action
requires a Document Crypto Map. The Crypto Map operation must agree with
the encryption method.

The encrypt action might require that certain parameters be supplied during the
configuration of the service.

Encrypting a SOAP message with WS-Security encryption

To add an encrypt action to encrypt a SOAP message (with or without
attachments) with WS-Security encryption. This action encrypts the child element
of the SOAP body, use the following procedure:
1. Drag the Encrypt icon to the configuration path (the horizontal line).
2. Double-click the Encrypt icon to display the Encrypt action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Select WSSec Encryption from the Envelope Method list.

110 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 5. Select SOAP Message from the Message Type list.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select the encryption scope from the Message and Attachment Handling list.
Attachments Only
Encrypt only the attachments to the message.
Message Only
Encrypt only the message, which is the root part.
Message and Attachments
Encrypt the message and attachments.
8. Determine whether to use the certificate in the signature that is provided by
the remote client to encrypt the response.
v To use this certificate, change the setting of the Use Dynamically
Configured Recipient Certificate property to on.
v To not use this certificate, retain the setting for the Use Dynamically
Configured Recipient Certificate property.
When enabled, the encrypt action performs encryption with the certification
from the last verify action. The certificate in the signature is saved in the
var://context/transaction/encrypting-cert variable.
9. Determine whether to use the same ephemeral key for all encryptions in this
action.
v To use the same key, change the setting of the One Ephemeral Key
property to on.
v To not use the same key, retain the setting of the One Ephemeral Key
property.
When enabled, there is only one ephemeral key encryption. Its corresponding
EncryptedKey adds a DataReference URI for each EncryptedData. Using one
ephemeral key provides better performance.
10. Optionally select a Crypto Certificate from the Recipient Certificate list.
The selected certificate overrides any setting that is established for the service.
For example, this certificate can override the XML Firewall Credentials setting
by referencing a certificate that is not in those credentials.
Additional certificate and encryption settings are available on the Advanced tab.
11. Optionally click the Advanced tab configure advanced properties.
a. Confirm the Input property.
b. Confirm the Action Type property.
c. Confirm the Envelope Method property.
d. Confirm the Message Type property.

Chapter 5. Defining processing policies 111

 e. Specify or select the name and location of the encryption style sheet in the
Processing Control File field. The default is the encrypt-wssec.xsl file in
the store: directory.
f. Select how to interpret the response from the server from the Output Type
list.
v Binary
v Default
v XML
The default is Default.
g. Confirm the Asynchronous property.
h. Confirm the Message and Attachment Handling property.
i. Confirm the Use Dynamically Configured Recipient Certificate property.
j. Confirm the One Ephemeral Key property.
k. Confirm the Recipient Certificate property.
l. Select the algorithm to use for encryption from the Encryption algorithm
list. The default is 3DES-CBC.
m. Type the identifier for the SOAP 1.1 actor or SOAP 1.2 role in processing a
WS-Security security header in the SOAP Actor/Role Identifier field. This
identifier is effective only when a SOAP message is being used for
WS-Security 1.0 or 1.1. Use one of the following well-known values:
http://schemas.xmlsoap.org/soap/actor/next
Everyone, including the intermediary and ultimate receiver, receives
the message and should be able to process the security header.
http://www.w3.org/2003/05/soap-envelope/role/none
No one should process the security header.
http://www.w3.org/2003/05/soap-envelope/role/next
Everyone, including the intermediary and ultimate receiver, receives
the message and should be able to process the security header.
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
(Default) The ultimate receiver can process the security header.
Blank or an empty string
No actor/role identifier is configured. The ultimate receiver is
assumed when processing the message, and no actor/role attribute is
added when generating the security header.

Note: There should not be more than one security header that omit
the actor/role identifier.
USE_MESSAGE_BASE_URI
Indicates that the actor/role identifier is the base URI of the
message. If the SOAP message is transported using HTTP, the base
URI is the request-URI of the HTTP request.
Any other string
Indicates the actor or role of the security header.
n. Select the version of WS-Security to use from the WS-Security Version list.
v 1.0
v 1.1
v draft-12
v draft-13

112 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 The default is 1.0.
o. Determine whether to security header contains the mustUnderstand SOAP
attribute. When enabled, the security header includes the
SOAP:mustUnderstand="1" attribute.
v To include, retain the setting of the Include SOAP mustUnderstand
property.
v To not include, change the setting of the Include SOAP
mustUnderstand property to no.
p. Select how to generate the ID type for the new element node from the
WS-Sec ID Reference Type list.
v xml:id
v wsu:Id
The default is wsu:Id (for backward compatibility).
q. Select the method to reference the security token from the Token
Reference Mechanism list:
Direct Reference
A BinarySecurityToken is placed in the message and a Reference
element with a URI fragment that points to the BinarySecurityToken
is used to refer to it.
When selected, the WebGUI refreshes with additional fields.
1) For WS-Security version 1.0 or 1.1 only, select how to control the
value of BinarySecurityToken/@ValueType and of
SecurityTokenReference/Reference/@ValueType when referring to
a BinarySecurityToken that is an X.509 token from the X.509
Token Profile 1.0: BinarySecurityToken ValueType list.
Because of the differences between the final WS-Security 1.0
standards and the multiple draft versions of its errata document,
different values of the ValueType attribute are used by different
WS-Security implementations.
#X509
Compatibility with certain versions of .NET Web services
enhancements (WSE) might require this setting. Generates
http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-x509-token-profile-1.0#X509
X509v3
Compatibility with certain versions of WebSphere might
require this setting. Generates http://docs.oasis-open.org/
wss/2004/01/ oasis-200401-wss-x509-token-profile-
1.0#X509v3
EncryptedKeySHA1
A reference is made using a KeyIdentifier element with an
EncryptedKeySHA1 ValueType and content. This value type was
introduced as a WS-Security 1.1 feature and should be used only
with this version of WS-Security or newer.
When selected, the WebGUI refreshes with additional fields.
Select whether a Key Derivation is needed and where to find the key
from the WS-SecureConversation DKT Derivation Base list.
Derive Key from an Existing Designated DKT Token
Searches the specified wsc:DerivedKeyToken instead of a

Chapter 5. Defining processing policies 113

 SecurityContextToken and uses the corresponding label and
nonce to generate the new derived key.
1) Optionally specify the name of the base DKT in the Name
of the Base DKT to Derive a Key field. If not specified,
uses the SecurityContextToken to generate the key.
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
Use Key Derivation without a SCT, and issue an Encrypted Key for
the DKT
1) Select the version of WS-SecureConversation to use from the
WS-SecureConversion Version list.
v 1.1
v 1.2 (Default)
v 1.3
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
4) Specify the label of the derived key in the Label of the
Derived Key field.
No WS-SecureConversation Key Derivation
Does not derive a key.
Use Key Derivation if a SCT Token is Available
Checks for an existing wsc:SecurityContextToken and derives a
key from it. Otherwise, uses the generated asymmetric key
without key derivation.
1) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
2) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
3) Specify the label of the derived key in the Label of the
Derived Key field.

114 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Key Identifier
(Default) A reference is made using a KeyIdentifier element with a
SubjectKeyIdentifier ValueType and content.
When selected, the WebGUI refreshes with additional fields.
1) For WS-Security version 1.0 only, select how to control the value
of KeyIdentifier/@ValueType from the X.509 Token Profile 1.0:
KeyIdentifier ValueType list.
Because of the differences between the final WS-Security 1.0
standards and the multiple draft versions of its errata document,
different values of the ValueType attribute are used by different
WS-Security implementations.
#X509SubjectKeyIdentifier
Compatibility with certain versions of .NET Web services
enhancements (WSE) might require this setting. Generates
http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-x509-token-profile-
1.0#X509SubjectKeyIdentifier
X509v3SubjectKeyIdentifier
Compatibility with certain versions of WebSphere might
require this setting. Generates http://docs.oasis-open.org/
wss/2004/01/ oasis-200401-wss-x509-token-profile-
1.0#X509v3SubjectKeyIdentifier
2) For WS-Security version 1.0 and 1.1 only, select the form of the
Subject Key Identifier from the SKI list.
MS-WSE
Form that is used in Microsoft WSE version 1.
PKIX
(Default) Public Key Infrastructure (PKIX) standard.
3) For WS-Security version 1.1 only, specify the number of seconds
to cache the generated key in the EncryptedKeySHA1 Cache
Lifetime for Derived Key field. A value of 0 means that the
generated key is not cached. The default is 0.
4) Select whether a Key Derivation is needed and where to find the
key from the WS-SecureConversation DKT Derivation Base list.
Derive Key from an Existing Designated DKT Token
Searches the specified wsc:DerivedKeyToken instead of a
SecurityContextToken and uses the corresponding label and
nonce to generate the new derived key.
a) Optionally specify the name of the base DKT in the
Name of the Base DKT to Derive a Key field. If not
specified, uses the SecurityContextToken to generate the
key.
b) Specify where in the byte stream of a lengthy generated
key sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of
the Derived Key in the Key Sequence field.
c) If you removed the offset setting, specify which
generation of the key to use in the Generation of the

Chapter 5. Defining processing policies 115

 Derived Key in the Key Sequence field. The generation
is the index number of the fixed key in the lengthy key
sequence.
Use Key Derivation without a SCT, and issue an Encrypted Key
for the DKT
a) Select the version of WS-SecureConversation to use from
the WS-SecureConversion Version list.
v 1.1
v 1.2 (Default)
v 1.3
b) Specify where in the byte stream of a lengthy generated
key sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of
the Derived Key in the Key Sequence field.
c) If you removed the offset setting, specify which
generation of the key to use in the Generation of the
Derived Key in the Key Sequence field. The generation
is the index number of the fixed key in the lengthy key
sequence.
d) Specify the label of the derived key in the Label of the
Derived Key field.
No WS-SecureConversation Key Derivation
Does not derive a key.
Use Key Derivation if a SCT Token is Available
Checks for an existing wsc:SecurityContextToken and
derives a key from it. Otherwise, uses the generated
asymmetric key without key derivation.
a) Specify where in the byte stream of a lengthy generated
key sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of
the Derived Key in the Key Sequence field.
b) If you removed the offset setting, specify which
generation of the key to use in the Generation of the
Derived Key in the Key Sequence field. The generation
is the index number of the fixed key in the lengthy key
sequence.
c) Specify the label of the derived key in the Label of the
Derived Key field.
ThumbPrintSHA1
A reference is made using a KeyIdentifier element with a
ThumbPrintSHA1 ValueType and content. This value type is a
WS-Security 1.1 feature and should be used only with this version of
WS-Security.
When selected, the WebGUI refreshes with additional fields.
Select whether a Key Derivation is needed and where to find the key
from the WS-SecureConversation DKT Derivation Base list.

116 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Derive Key from an Existing Designated DKT Token
Searches the specified wsc:DerivedKeyToken instead of a
SecurityContextToken and uses the corresponding label and
nonce to generate the new derived key.
1) Optionally specify the name of the base DKT in the Name
of the Base DKT to Derive a Key field. If not specified,
uses the SecurityContextToken to generate the key.
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
Use Key Derivation without a SCT, and issue an Encrypted Key for
the DKT
1) Select the version of WS-SecureConversation to use from the
WS-SecureConversion Version list.
v 1.1
v 1.2 (Default)
v 1.3
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
4) Specify the label of the derived key in the Label of the
Derived Key field.
No WS-SecureConversation Key Derivation
Does not derive a key.
Use Key Derivation if a SCT Token is Available
Checks for an existing wsc:SecurityContextToken and derives a
key from it. Otherwise, uses the generated asymmetric key
without key derivation.
1) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
2) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.

Chapter 5. Defining processing policies 117

 3) Specify the label of the derived key in the Label of the
Derived Key field.
ThumbprintSHA1
A reference is made using a KeyIdentifier element with a
ThumbprintSHA1 ValueType and content. This value type is a
WS-Security 1.1 feature and should be used only with this version of
WS-Security.
When selected, the WebGUI refreshes with additional fields.
Select whether a Key Derivation is needed and where to find the key
from the WS-SecureConversation DKT Derivation Base list.
Derive Key from an Existing Designated DKT Token
Searches the specified wsc:DerivedKeyToken instead of a
SecurityContextToken and uses the corresponding label and
nonce to generate the new derived key.
1) Optionally specify the name of the base DKT in the Name
of the Base DKT to Derive a Key field. If not specified,
uses the SecurityContextToken to generate the key.
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
Use Key Derivation without a SCT, and issue an Encrypted Key for
the DKT
1) Select the version of WS-SecureConversation to use from the
WS-SecureConversion Version list.
v 1.1
v 1.2 (Default)
v 1.3
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
4) Specify the label of the derived key in the Label of the
Derived Key field.
No WS-SecureConversation Key Derivation
Does not derive a key.

118 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Use Key Derivation if a SCT Token is Available
Checks for an existing wsc:SecurityContextToken and derives a
key from it. Otherwise, uses the generated asymmetric key
without key derivation.
1) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
2) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
3) Specify the label of the derived key in the Label of the
Derived Key field.
X509IssuerSerial
A reference is made using an X509IssuerSerial element that
identifies a certificate by its X.509 issuer and serial number.
When selected, the WebGUI refreshes with additional fields.
Select whether a Key Derivation is needed and where to find the key
from the WS-SecureConversation DKT Derivation Base list.
Derive Key from an Existing Designated DKT Token
Searches the specified wsc:DerivedKeyToken instead of a
SecurityContextToken and uses the corresponding label and
nonce to generate the new derived key.
1) Optionally specify the name of the base DKT in the Name
of the Base DKT to Derive a Key field. If not specified,
uses the SecurityContextToken to generate the key.
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
Use Key Derivation without a SCT, and issue an Encrypted Key for
the DKT
1) Select the version of WS-SecureConversation to use from the
WS-SecureConversion Version list.
v 1.1
v 1.2 (Default)
v 1.3
2) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.

Chapter 5. Defining processing policies 119

 3) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
4) Specify the label of the derived key in the Label of the
Derived Key field.
No WS-SecureConversation Key Derivation
Does not derive a key.
Use Key Derivation if a SCT Token is Available
Checks for an existing wsc:SecurityContextToken and derives a
key from it. Otherwise, uses the generated asymmetric key
without key derivation.
1) Specify where in the byte stream of a lengthy generated key
sequence the derived key starts in the Offset of the
Derived Key in the key sequence field. The default is 0.
This field is mutually exclusive with the Generation of the
Derived Key in the Key Sequence field.
2) If you removed the offset setting, specify which generation
of the key to use in the Generation of the Derived Key in
the Key Sequence field. The generation is the index number
of the fixed key in the lengthy key sequence.
3) Specify the label of the derived key in the Label of the
Derived Key field.
12. If you configured advanced properties, click the Basic tab.
13. Specify or select the context for the data produced in the Output field.
14. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Encrypting a SOAP message with XML encryption

To add an encrypt action to encrypt a SOAP message, use the following procedure:
1. Drag the Encrypt icon to the configuration path (the horizontal line).
2. Double-click the Encrypt icon to display the Encrypt action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Select Standard XML Encryption from the Envelope Method list.
5. Select SOAP Message from the Message Type list.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Determine whether to use the certificate in the signature that is provided by
the remote client to encrypt the response.

120 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v To use this certificate, change the setting of the Use Dynamically
Configured Recipient Certificate property to on.
v To not use this certificate, retain the setting for the Use Dynamically
Configured Recipient Certificate property.
When enabled, the encrypt action performs encryption with the certification
from the last verify action. The certificate in the signature is saved in the
var://context/transaction/encrypting-cert variable.
8. Optionally select a Crypto Certificate from the Recipient Certificate list.
The selected certificate overrides any setting that is established for the service.
For example, this certificate can override the XML Firewall Credentials setting
by referencing a certificate that is not in those credentials.
Additional certificate and encryption settings are available on the Advanced tab.
9. Optionally click the Advanced tab configure advanced properties.
a. Confirm the Input property.
b. Confirm the Action Type property.
c. Confirm the Envelope Method property.
d. Confirm the Message Type property.
e. Specify or select the name and location of the encryption style sheet in the
Processing Control File field. The default is the encrypt-soap.xsl file in the
store: directory.
f. Select how to interpret the response from the server from the Output Type
list.
v Binary
v Default
v XML
The default is Default.
g. Confirm the Asynchronous property.
h. Select the algorithm to use for encryption from the Encryption algorithm
list. The default is 3DES-CBC.
i. Select how to encrypt from the Encryption Type list.
Content
(Default) Encrypts the contents of an XML element but not the
element itself.
Element
Encrypts an XML element and its contents.
10. If you configured advanced properties, click the Basic tab.
11. Specify or select the context for the data produced in the Output field.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Encrypting a raw XML message with XML encryption

To add an encrypt action to encrypt a raw XML message, use the following
procedure:
1. Drag the Encrypt icon to the configuration path (the horizontal line).
2. Double-click the Encrypt icon to display the Encrypt action window.
3. Specify or select the context for the data to be processed in the Input field.

Chapter 5. Defining processing policies 121

 4. Select Standard XML Encryption from the Envelope Method list.
5. Select Raw XML Document from the Message Type list.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Determine whether to use the certificate in the signature that is provided by
the remote client to encrypt the response.
v To use this certificate, change the setting of the Use Dynamically
Configured Recipient Certificate property to on.
v To not use this certificate, retain the setting for the Use Dynamically
Configured Recipient Certificate property.
When enabled, the encrypt action performs encryption with the certification
from the last verify action. The certificate in the signature is saved in the
var://context/transaction/encrypting-cert variable.
8. Optionally select a Crypto Certificate from the Recipient Certificate list.
The selected certificate overrides any setting that is established for the service.
For example, this certificate can override the XML Firewall Credentials setting
by referencing a certificate that is not in those credentials.
Additional certificate and encryption settings are available on the Advanced tab.
9. Optionally click the Advanced tab configure advanced properties.
a. Confirm the Input property.
b. Confirm the Action Type property.
c. Confirm the Envelope Method property.
d. Confirm the Message Type property.
e. Specify or select the name and location of the encryption style sheet in the
Processing Control File field. The default is the encrypt.xsl file in the
store: directory.
f. Select how to interpret the response from the server from the Output Type
list.
v Binary
v Default
v XML
The default is Default.
g. Confirm the Asynchronous property.
h. Select the algorithm to use for encryption from the Encryption algorithm
list. The default is 3DES-CBC.
i. Select how to encrypt from the Encryption Type list.
Content
(Default) Encrypts the contents of an XML element but not the
element itself.

122 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Element
Encrypts an XML element and its contents.
j. If the Encryption Type property is set to Element, determine whether to
generate SAML encryption for SAML elements. For SAML 2.0, generates
the EncryptedAssertion or EncryptedAttribute element for Assertions or
Attributes, respectively. For SAML 1.x, generates EncryptedData directly.
Setting to on generates the if it is a SAML 2.0 Assertion or Attribute. For
SAML 1.x message, the SAML schema does not define EncryptedAssertion
or EncryptedAttribute types, so the standard XML Encryption is applied.
v To generate SAML encryption, retain the setting for the Use SAML
Encryption for SAML Elements property.
v To not generate SAML encryption, change the setting for the Use SAML
Encryption for SAML Elements toggle to off.
10. If you configured advanced properties, click the Basic tab.
11. Specify or select the context for the data produced in the Output field.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Encrypting select elements of a message

To add an encrypt action to encrypt select elements, use the following procedure:
1. Drag the Encrypt icon to the configuration path (the horizontal line).
2. Double-click the Encrypt icon to display the Encrypt action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Select the encryption type with the Envelope Method radio buttons.
v Standard XML Encryption
v WSSec Encryption
5. Select Selected Elements (Field-level) from the Message Type list.
6. Select the Document Crypto Map that identifies the message fields to be
encrypted from the Document Crypto Map list. The list displays only maps
that conform to the selected Envelope Method.
The Operation property of the Document Crypto Map must agrees with the
selected Envelope Method property of the encrypt action. Refer to
Document Crypto Map on page 282 for more information.
7. Optionally click the Advanced tab configure advanced properties.
a. Confirm the Input property.
b. Confirm the Action Type property.
c. Confirm the Envelope Method property.
d. Confirm the Message Type property.
e. Confirm the Document Crypto Map property.
f. Select how to interpret the response from the server from the Output Type
list.
v Binary
v Default
v XML
The default is Default.
8. If you configured advanced properties, click the Basic tab.

Chapter 5. Defining processing policies 123

 9. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
10. Specify or select the context for the data produced in the Output field.
11. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Event-sink (event-sink) action

The event-sink action does not employ an output context. To use the results from
an asynchronous action in an event-sink action, you must configure any of the
subsequent actions to use the output context of the asynchronous action. For
example, the processing rule can run a fetch action and a results action in
parallel. Both of these actions are included in an event-sink action. Processing
waits until both actions complete successfully.

To add an event-sink action, use the following procedure:

1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Event-sink radio button.
4. Click Next to display the Configure Event-sink window.
5. Use the default value for the Input field. This context is not used in any way.
6. Select the desired asynchronous action from the list of actions available in the
Action property. Only asynchronous actions are in this list. Asynchronous
actions that were created during the configuration of a conditional or for-each
action are not in this list and cannot be affected by an event-sink action. Click
Add to add the action to the list of actions.
7. Repeat step 6 as many times as needed to include the desired asynchronous
actions. The actions can be in any order.
8. Set the desired Timeout value. The default of 0 means that processing waits
indefinitely for the included actions to complete.
9. Click Done to complete the action.

For a transform to use the data from a results action that follows the event-sink
action, the transform must use the output context of the results action as its input
context. You can create a style sheet to access and combine all of the contexts that
are created by multiple asynchronous actions.

When the event-sink action includes actions that can reject the message, a rejection
by any of the included actions causes the message to be rejected as if the actions
were processed in sequence. When more than one such action rejects the message,

124 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 any Error Rule that is in the policy has access to the detailed error messages that
were generated for the last asynchronous action to complete only.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Extract using XPath (extract) action

To add an extract action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Extract Using XPath radio button.
4. Click Next to display the Extract using XPath action window.
5. Specify or select the context for the data to be processed in the Input field.
6. Use the XPath field to specify the XPath expression applied to the source
context.
7. Optionally use the Variable field to identify a variable (which might be
located in the context identified by Output) in which to store the results of the
XPath expression. Use a variable of type var://context/contextname/varname
to store the results in a context that is easily addressable by all actions in the
scope of this processing rule. Refer to Set variable (setvar) action on page
145 for more information.
8. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
9. Specify or select the context for the data produced in the Output field.
10. Click Done to complete the action. The configuration path shows the Extract
using XPath icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Fetch (fetch) action

To add a fetch action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Fetch radio button.
4. Click Next to display the Fetch action window.
5. In the Source field, specify the location of the resource to retrieve. Refer to
Locating remote resources in actions on page 159 for details.

Chapter 5. Defining processing policies 125

 6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Specify or select the context for the data produced in the Output field.
8. Click Done to complete the action. The configuration path shows the Fetch
icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Filter (filter) action

A processing policy provides following implementations:
Standard filter
Creates a filter that checks the document for user-defined elements. A
standard filter uses the specified style sheet to accept or reject the
submitted document. You can use the filter-accept-all.xsl or
filter-reject-all.xsl style sheets in the store: directory.
Replay filter
Creates a filter that checks the document for replay attacks. A replay filter
uses the replay-filter.xsl style sheet in the store: directory to cache a
selected value from submitted documents. When that value occurs in any
subsequent requests, the request is rejected.
Required elements filter
Creates a filter that checks the document for the presence of required
elements in the SOAP header. A required elements filter uses the
required-elements-filter.xsl style sheet in the store: directory.
Message layout filter
Creates a filter that checks the document for WS-Security message layout.
A message layout filter uses the wssecurity-message-layout-filter.xsl style
sheet in the store: directory.
Conformance filter
Creates a filter that checks the document for conformance against the
define Conformance Policy. A conformance filter uses the
conformance-filter.xsl style sheet in the store: directory.

Defining a standard filter

To add a standard filter, use the following procedure:
1. Drag the Filter icon to the configuration path (the horizontal line).
2. Double-click the Filter icon to display the Filter action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Specify or select the style sheet to accept or reject XML documents with the
Processing Control File fields. You can use the filter-accept-all.xsl or
filter-reject-all.xsl style sheet in the store: directory.

126 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to retrieve the file.
5. Click WSDL Tool to invoke the WSDL Tool wizard. This wizard reads a
specified WSDL file and creates the necessary style sheet to filter on particular
operations. The files are stored in the local: directory.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Specify or select the context for the data produced in the Output field.
8. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a replay filter

To add a replay filter, use the following procedure:
1. Drag the Filter icon to the configuration path (the horizontal line).
2. Double-click the Filter icon to display the Filter action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Click the Advanced tab.
5. Select the Replay Filter radio button from the Filter Method list.
6. Retain the value of store:///replay-filter.xsl in the Processing Control
File field.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Select the type of filter from the Replay Filter Type list:
v WS-Security Password Digest Nonce
v WS-Addressing Message ID (Default)
v Custom XPath
9. Specify, in milliseconds, the duration to use the extracted value in the Replay
duration field. Use an integer greater than 0.
Chapter 5. Defining processing policies 127
 10. If the filter type is Custom XPath, specify the XPath expression in the Custom
XPath Expression field.
For assistance in creating the XPath expression, click XPath Tool. This tool
allows you to load an XML document and build the expression by selecting
the desired mode.
11. Specify or select the context for the data produced in the Output field.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a required elements filter

To add a required elements filter, use the following procedure:
1. Drag the Filter icon to the configuration path (the horizontal line).
2. Double-click the Filter icon to display the Filter action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Click the Advanced tab.
5. Select the Required Elements Filter radio button from the Filter Method list.
6. Retain the value of store:///required-elements-filter.xsl in the Processing
Control File field.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify the XPath expression in the XPath Expression field.
For assistance in creating the XPath expression, click XPath Tool. This tool
allows you to load an XML document and build the expression by selecting
the desired mode.
9. Specify or select the context for the data produced in the Output field.
10. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a message layout filter

To add a message layout filter, use the following procedure:
1. Drag the Filter icon to the configuration path (the horizontal line).
2. Double-click the Filter icon to display the Filter action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Click the Advanced tab.
5. Select the WS-Security Message Layout Filter radio button from the Filter
Method list.

128 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 6. Retain the value of store:///wssecurity-message-layout-filter.xsl in the
Processing Control File field.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Select which WS-Security assertion to apply from the WS-Security Message
Layout Policy list. This policy determines whether to accept or request
documents based on the order of elements in the WS-Security header.
Lax Does not require that tokens be declared before use.
Lax - Timestamp First
Requires that the timestamp be the first element in the header.
Lax - Timestamp Last
Requires that the timestamp be the last element in the header.
Strict Requires that tokens, in general, be declared before use.
9. Specify or select the context for the data produced in the Output field.
10. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a conformance filter

To add a conformance filter, use the following procedure:
1. Drag the Filter icon to the configuration path (the horizontal line).
2. Double-click the Filter icon to display the Filter action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Specify or select the store:///conformance-filter.xsl style sheet with the
Processing Control File fields.
5. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
6. Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 279 for details.
7. Specify or select the context for the data produced in the Output field.
8. Click Done to complete the action.

Chapter 5. Defining processing policies 129

 If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

For-each (for-each) action

The for-each action supports the following use cases:
Process a nodeset with a series of style sheets and generate results as a single
output This use case loops through an XML file that contains a list of the URLs for
style sheets. The input context of the for-each action contains this XML
file. Refer to Specifying the location of remote resources on page 159 for
details about the content for the style sheet.
The Loop Action in this case is a transform action. The transform uses the
value of the var://service/multistep/loop-iterator variable. This
variable evaluates to the URL of a style sheet to use for the transform. This
Loop Action operates on an input context that is not the input context of
the for-each loop. The input context of the Loop Action typically contains
the message that is submitted by the service client. The output context of
the transform is set to the same context as the input context. In this way,
each subsequent style sheet operates on the output of the previous style
sheet. The output context of the transform could be the same as that of the
for-each loop itself. The action that immediately follows the loop takes as
its input context the output context of the Loop Action.
This configuration method avoids memory requirements of many included
style sheets in a single style sheet. Instead, the use of output contexts
clarifies data and memory management.
Distribute data to a range of destinations
This use case loops through an XML file that contains a list of destination
URLs. A results action sends the data in the processing context to each
destination. If the return from each iteration of the results action is not
important, the results action can be asynchronous. If the return from each
iteration is needed for further processing, the for-each loop can be
configured to place the return for each iteration in a unique output context.
A style sheet can then recombine the contents of the contexts.
Data enrichment
This use case loops through repeating elements in a message and uses the
values in each element as inputs to a data-enriching action, such as a
fetch, results, or sql action. This method can also be used to authenticate
a list of identities.

To add a for-each action, use the following procedure:

1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the For-each radio button.
4. Click Next to display the Configure Event-sink action window.
5. Set the desired Input context. Select auto to cause the service to use the best
available choice (typically the output context of the previous action). All XPath
expressions are applied to the data in this context.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:

130 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select the desired method of iteration from the Iterator Type list.
Count Runs the Loop Action on the entire message in the input context for
the number of times set in the Iterator Count field. The screen
refreshes to display the Iterator Count field. Use an integer in the
range of 1 through 32768.
XPath Expression
Runs the Loop Action on each node set that is returned by the XPath
expression in the XPath Expression field. The screen refreshes to
display the XPath Expression field.
If the XPath expression is /*[namespace-uri()='http://joe.com' and
local-name()='Order']/*[namespace-uri()='http://joe.com' and
local-name()='Item'], the loop runs three times for the following input:
<joe:Order xmlns:joe="http://schemas.joes.com/schemas">
<joe:Item>
<joe:Qty>5</joe:Qty>
<joe:ProdID>32145-12</joe:ProdID>
</joe:Item>
<joe:Item>
<joe:Qty>10</joe:Qty>
<joe:ProdID>78-697-24</joe:ProdID>
</joe:Item>
<joe:Item>
<joe:Qty>10</joe:Qty>
<joe:ProdID>091356-3</joe:ProdID>
</joe:Item>
</joe:Order>
8. Create a Loop Action to run for each iteration of the loop.
a. Select an action type from the Action list.
b. Click Create Action.
The WebGUI displays a configuration window for the selected action type.
c. Configure the action. When configuring this action, consider the following
points:
v The input context of the conditionally invoked action can be different
from the input context of the conditional action itself. Typically, the
input context of the conditionally invoked action is the same as the
conditional action.
v This action can operate in any manner, including as a filter that accepts
or rejects the message, thus continuing or halting processing. Examples
include signature verification, custom filtering style sheets, and AAA
actions.
v This action can be a call action to allow processing of an entire
processing rule.
v This action cannot be the conditional action. A recursive conditional
action cannot be processed. This action can be a different conditional
action that does not contain a loop back to this conditional action.

Chapter 5. Defining processing policies 131

 v The output context of this action can take any valid value, except PIPE.
v This action can run asynchronously. When asynchronous, the action that
follows the conditional action is run immediately. Any action that
follows the conditional action cannot use the output context of the
asynchronous action as its input context.
9. Click the Advanced tab to optionally configure the Use Multiple Outputs and
Multi-Way Results Mode properties.
a. Select the behavior of the action from the Multi-Way Results Mode list.
Attempt All
Sends the results in the input context to all potential destinations
and succeeds even if all of the remote servers fail.
First Available
(Default) Sends the results in the input context to each of the
potential destinations one at a time and stops with success after
sending the input to at least one of the remote servers.
Require All
Sends the results in the input context to all potential destinations
and fails if any of the remote servers fails.
b. Use the Use Multiple Outputs toggle to determine whether to write
parallel outputs into separate contexts.
on Creates a series of output contexts that are based on the value in
the Output field. Refer to Locating remote resources in actions
on page 159 for details.
If the value is out, the output contexts are named to out_1, out_2,
out_3 and so forth. You can then use a custom style sheet to
combine the multiple output contexts into a single nodeset. Such a
style sheet would include code that is similar to the following
excerpt:
<tns:Combined>
<tns:Item from="a">
<xsl:copy-of select="dp:variable('var://context/out_1/')"/>
</tns:Item>
<tns:Item from="b">
<xsl:copy-of select="dp:variable('var://context/out_2/')"/>
</tns:Item>
</tns:Combined>
off (Default) The output context contains the result of the last iteration
only, not the aggregated results of each iteration.
10. Specify or select the context for the data produced in the Output field. The
value cannot be PIPE.
11. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Related service variables

The following variables provide dynamically updated information that might be
useful for creating for-each loops. Style sheets that are run by the loop can access
these read-only variables at any time. These variables are not available outside the
context of the loop.

132 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 var://service/multistep/loop-iterator
This variable contains the value or nodeset of the current iteration through
the input context of the for-each action when the Iterator Type is XPath
Expression. For example, an input message could contain five repeated
elements, such as a URL. As the loop iterates through the message, the
variable contains the value or nodeset of the current line item. It is then
possible to use this variable as a value needed by the Loop Action, such as
the source URL for the style sheet used by a transform-type action, or as
the destination address for a fetch action.
var://service/multistep/loop-count
This variable returns the number of times the loop has iterated.

Log (log) action

To add a log action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Log radio button.
4. Click Next to display the Log action window.
5. Optionally select the Input context. If this is left at the default value of auto,
processing inserts the correct context identifier. The contents of the selected
context are sent as a log message to the destination.
6. Specify a valid URL in the Destination field. Refer to Locating remote
resources in actions on page 159 for details.
7. Select a logging level from the Log Level list. The level might be meaningful
to the entity that receives the log message.
8. Select a logging type from the Log Type list. You can create new types by
clicking the + button.
9. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
10. Select an Output context or specify a new context name. Select auto to allow
the processing policy to determine the output context automatically. If this is
left blank, no response is captured from the log action.
11. Click Done to complete the action. The configuration path shows the Log
icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

MQ header action
The MQ Header action can perform the following header and queue modifications:

Chapter 5. Defining processing policies 133

 Modify MQMD Request Message Headers
Selectively override specified headers values in a request message or drops
all header values from the request message and replaces with new or
auto-generated values.
Retrieve Responses using Message Id or Correlation Id
Modify how the service retrieves response messages from a backend reply
queue by specifying a message ID or Correlation ID. By default, the service
looks in the backend reply queue for response messages that have a
Correlation Id that matches the Message Id of the request message.
Modify MQMD Response Message Headers
Selectively override specified header values in a response message or
drops all header values from the response message and replaces with new
or auto-generated values.
Modify Reply Queue for Response Messages
Modify the destination reply queue for response messages. By default, the
service sends responses to the reply queue specified in the MQ Front Side
Handler.
Modify Queue Manager for Response Messages
Modify the destination MQ Queue Manager for response messages. By
default, the service sends responses to the MQ Queue Manager specified in
the MQ Front Side Handler.

Modifying MQMD request headers

To modify MQMD header values for request messages placed to the backend, use
the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.
5. Optionally select the Input context. If this is left at the default value of auto,
processing inserts the correct context identifier.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select request as the MQ Processing Type.
8. Select MQMD for Put from the MQ Request Header Processing list.
9. Use the Override Existing MQMD toggle to choose a mode for overriding the
MQMD headers in the request message:
on Overrides existing MQMD header values on the request message with
these values. If blank, the service retains the header value from the
original request message.

134 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 off (Default) Ignores all MQMD header values from the original request
message. The new header values are inserted into the request
message. If blank, the service populates those fields with
auto-generated defaults.
10. Specify an override value for any of the following MQMD header fields:
v Message Id
v Correlation Id
v Character Set Id
v Format Name
v ReplyToQ
v ReplyToQMgr
11. Select an Output context or specify a new context name. Select auto to allow
the processing policy to determine the output context automatically.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Retrieving responses by message ID or by correlation ID

To retrieve response messages from the backend reply queue, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.
5. Optionally select the Input context. If this is left at the default value of auto,
the service inserts the correct context identifier.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select request as the MQ Processing Type.
8. Select MQMD for Get from the MQ Request Header Processing list.
9. To specify how the service pulls messages from the backend reply queue, use
the following fields:
v Specify the message ID in the Message Id field. The service pulls messages
from the backend reply queue with the specified message ID.
v Specify the correlation ID in the Correlation Id field. The service pulls
messages from the backend reply queue with the specified correlation ID.
10. Select an output context or specify a new context name. Select auto to allow
the processing policy to determine the output context automatically.

Chapter 5. Defining processing policies 135

 11. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Modifying MQMD response headers

To modify MQMD header values for response messages placed to the backend
reply queue, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.
5. Optionally select the Input context. If this is left at the default value of auto,
the service inserts the correct context identifier.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select response as the MQ Processing Type.
8. Select MQMD from the MQ Response Header Processing list.
9. Use the Override Existing MQMD toggle to choose a mode for overriding the
MQMD headers in the response message:
on Overrides existing MQMD header values on the response message
with the values specified here. If blank, the service retains the header
values from the original request message.
off (Default) Ignores all MQMD header values from the response
message. The new header values are inserted into the response
message. If blank, the service populates these fields with
auto-generated default values.
10. Specify an override value for any of the following MQMD header fields:
v Message Id
v Correlation Id
v Character Set Id
v Format Name
v ReplyToQ
v ReplyToQMgr
11. Select an output context or specify a new context name. Select auto to allow
the processing policy to determine the output context automatically.
12. Click Done to complete the action.

136 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Modifying reply queue for response

To change the destination reply queue for response messages, use the following
procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.
5. Optionally select the Input context. If the default, the service inserts the
correct context identifier.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select response as the MQ Processing Type.
8. Select ReplyToQ from the MQ Response Header Processing list.
9. Select the processing method for the response message from the ReplyToQ
Processing Type list.
Empty Forces the service to not send a response message to a reply queue.
Specified
(Default) Overrides default response message processing. The service
routes response messages to the specified reply queue.
10. Optionally specify a value in the ReplyToQ field.
11. Select an output context or specify a new context name. Select auto to allow
the service to determine the output context.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Modifying the queue manager for response

To change the destination MQ Queue Manager for response messages, use the
following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the MQ Header radio button.
4. Click Next to display the MQ Header action window.

Chapter 5. Defining processing policies 137

 5. Optionally select the Input context. If the default, processing inserts the
correct context identifier.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Select response as the MQ Processing Type.
8. Select ReplyToQM from the MQ Response Header Processing list.
9. Select the processing method for the response message from the ReplyToQM
Processing Type list.
Empty Forces the service to direct responses to the MQ Queue Manager
specified in the MQ Front Side Handler (default behavior).
Specified
(Default) Overrides default MQ Queue Manager processing. The
service routes response messages to the specified MQ Queue Manager.
10. Optionally specify a value in the ReplyToQMgr field.
11. Select an output context or specify a new context name. Select auto to allow
the processing policy to determine the output context automatically.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

On error (on-error) action

To add an on-error action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the On Error radio button.
4. Click Next to display the On Error action window.

Note: When defining an on-error action, you can use variables to specify the
processing rule, the input context, and the output context. Refer to Set
variable (setvar) action on page 145 for more information.
5. From the Error Mode list, select the operational response to an error
condition.
Cancel
Stop the processing of the current processing rule.
Alternative
Invoke an alternative processing rule.

138 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Continue
Continue with the next sequential processing action.
6. Optionally use the Processing Rule controls to select the target rule. The
target rule is the rule that this action calls. For information about creating
reusable processing rules, refer to Defining reusable rules on page 158.
To define a target rule, do one of the following:
v Select a processing rule from the list of available processing rules.
v Click Var Builder to use the variable builder to define a custom context
variable for a processing rule. Refer to Using the variable builder on page
162 for details.
7. Optionally use the Error Input field or select the input context to the invoked
error rule. If no input context is specified, the input context of the failed
action is provided as a default context to the error rule.
8. Optionally use the Error Output field or select the output context from the
invoked error rule. If no output context is specified, the output context of the
failed action is provided as a default context to the error-rule.
Select OUTPUT to transmit the error message to the requesting client.
9. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
10. Click Done to complete the action. The configuration path shows the On
Error icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Results actions
A processing policy provides two actions that can send results in the input context
to remote servers:
results
Optionally sends results to one or more remote servers and, when
processing in synchronous mode, waits for a response from the remote
servers. When configured to process in asynchronous mode, the results
action is equivalent to the results-async action. However with the results
action, you can include an event-sink action in the processing rule to wait
for the response from the remote servers. Refer to Results (results) action
on page 140 for configuration details.
results-async
Sends results to one or more remote server and does not wait for a
response from the remote servers. Refer to Results Asynchronous
(results-async) action on page 141 for configuration details.

Both of the results-type actions offer the following options:

Chapter 5. Defining processing policies 139

 v The ability to send results to multiple destinations. For the results action, the
specification of a destination is optional. For a results-async action, the
specification of a destination is required.
v Can control the number of connection retries.

Because a results-async action does not support an output context, the results
action provides the following options that are not available for a results-async
action. These options are meaningful only when processing in synchronous mode
or when processing in asynchronous mode and the processing rule contains a
subsequent event-sink action.
v The ability to create multiple output contexts.
v The ability to control the aggregation of multiple output contexts.
v The ability to control the interpretation of the server response, if any.

Results (results) action

To add a results action, use the following procedure:
1. Drag the Results icon to the configuration path (the horizontal line).
2. Double-click the Results icon to display the Results action window.
3. Enter or select the context for the data to be processed in the Input field.
4. Optionally specify the URL to send the input context in the Destination field.
If omitted, the input context is written to the specified output context.
This value might resolve to more than one remote location. Refer to Locating
remote resources in actions on page 159 for details.
5. Retain the setting off for the Asynchronous toggle.
If set to on, the action is asynchronous. The action does not need to complete
for the next action in the processing rule to begin. When marked
asynchronous, the action behaves like a results-async action, except you can
use a subsequent event-sink action in the same processing rule to cause
processing to wait for specific asynchronous actions to complete. Refer to
Event-sink (event-sink) action on page 124 for details.
6. When the Destination field represents a list rather than a single target, select
the behavior of the action from the Multi-Way Results Mode list.
Attempt All
Sends the results in the input context to all potential destinations and
succeeds even if all of the remote servers fail.
First Available
(Default) Sends the results in the input context to each of the potential
destinations one at a time and stops with success after sending the
input to at least one of the remote servers.
Require All
Sends the results in the input context to all potential destinations and
fails if any of the remote servers fails.
7. Enter an integer in the Number of Retries field to set the number of times the
service retries a failed connection to the destination. The default is 0.
8. Enter an integer in the Retry Interval field to set the number of milliseconds
the service waits before retrying a connection. The default is 1000.
9. Click the Advanced tab to optionally configure the Output Type and Use
Multiple Outputs properties.
a. Select how to interpret the response from the server, if any, from the
Output Type list.

140 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Binary
Stores the response without parsing.
Default
(Default) Examines the content-type in the response. If it indicates
XML or does not exist, parses the response as XML. For any other
value, treats the response as Binary and stores the response
without parsing.
XML Parses the response as XML.
b. Use the Use Multiple Outputs toggle to determine whether to write
parallel outputs into separate contexts.
on Creates a series of output contexts that are based on the value in
the Output field. If the value is out, the output contexts are named
to out_1, out_2, out_3 and so forth. You can then use a custom
style sheet to combine the multiple output contexts into a single
nodeset. Such a style sheet would include code that is similar to
the following excerpt:
<tns:Combined>
<tns:Item from="a">
<xsl:copy-of select="dp:variable('var://context/out_1/')"/>
</tns:Item>
<tns:Item from="b">
<xsl:copy-of select="dp:variable('var://context/out_2/')"/>
</tns:Item>
</tns:Combined>
off (Default) The output context contains the result of the last iteration
only, not the aggregated results of each iteration.
10. Optionally enter or select the context for the data produced in the Output
field.
Leave blank if no response is expected or if the response can be ignored. A
value is required when the Use Multiple Outputs toggle is set to on.
11. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Results Asynchronous (results-async) action

To add a results-async action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Results Asynchronous radio button.
4. Click Next to display the Results Asynchronous action window.
5. Enter or select the context for the data to be processed in the Input field.
6. Specify the URL to send the input context in the Destination field. This value
might resolve to more than one remote location. Refer to Locating remote
resources in actions on page 159 for details.
7. When the Destination field represents a list rather than a single target, select
the behavior of the action from the Multi-Way Results Mode list.
Attempt All
Sends the results in the input context to all potential destinations and
succeeds even if all of the remote servers fail.

Chapter 5. Defining processing policies 141

 First Available
(Default) Sends the results in the input context to each of the potential
destinations one at a time and stops with success after sending the
input to at least one of the remote servers.
Require All
Sends the results in the input context to all potential destinations and
fails if any of the remote servers fails.
8. Enter an integer in the Number of Retries field to set the number of times the
service retries a failed connection to the destination. The default is 0.
9. Enter an integer in the Retry Interval field to set the number of milliseconds
the service waits before retrying a connection. The default is 1000.
10. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Rewrite header (rewrite) action

To add a rewrite action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Header Rewrite radio button.
4. Click Next to display the Header Rewrite action window.
5. From the URL Rewrite Policy list, select a URL Rewrite Policy. Refer to URL
Rewrite Policy on page 339 for more information.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Click Done to complete the action. The configuration path shows the Header
Rewrite icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Route-type actions
A processing policy provides three routing implementations using two actions to
select the destination:
Stylesheets
Uses the route-set action to implement style sheet-based routing. Refer to
Route with style sheet (route-action) action on page 143 for details.

142 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
XPath expressions
Uses the route-set action to implement XPath expression-based routing.
Refer to Route with XPath expression (route-action) action for details
Variables
Uses the route-set action to implement variable-based routing. Refer to
Route with variables (route-set) action on page 144 for details.

Route with style sheet (route-action) action

To add a route with style sheet (route-action) action, use the following procedure:
1. Drag the Route icon to the configuration path (the horizontal line).
2. Double-click the Route icon to display the Route (Using Stylesheet or XPath
Expression) action window.
3. Specify or select the context for the data to be processed in the Input field.
4. For the Selection Method radio buttons, retain the default selection (Use
Stylesheet to Select Destination).
5. Use the Processing Control File field to identify the style sheet to process
documents.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.

Note: The style sheet must use the dp:set-target() extension function to set the
routing destination.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Optionally specify or select the context for the data produced in the Output
field.
8. Click Done to complete the action and return to the rule configuration window.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Route with XPath expression (route-action) action

To add a route with XPath expression (route-action) action, use the following
procedure:
1. Drag the Route icon to the configuration path (the horizontal line).
2. Double-click the Route icon to display the Route (Using Stylesheet or XPath
Expression) action window.
3. Specify or select the context for the data to be processed in the Input field.

Chapter 5. Defining processing policies 143

 4. For the Selection Method radio buttons, select Use XPath to Select
Destination. The window refreshes.
5. From the XPath Routing Map list, select the map that contains the routing
information.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Optionally specify or select the context for the data produced in the Output
field.
8. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Route with variables (route-set) action

To add a route with variables (route-set) action, use the following procedure:
1. Drag the Route icon to the configuration path (the horizontal line).
2. Double-click the Route icon to display the Route (Using Stylesheet or XPath
Expression) action window.
3. Ignore the Input field.
4. For the Selection Method radio buttons, select Use Variable to Select
Destination to refresh the window with the Route (Using Variable) action
window.
5. Specify a URL in the Destination field. Refer to Locating remote resources in
actions on page 159 for details.
6. Optionally specify the name of a valid SSL Proxy Profile in the SSL Cred field.
The SSL Proxy Profile is used to connect with the identified destination.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

144 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Set variable (setvar) action
To add a setvar action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Set Variable radio button.
4. Click Next to display the Set Variable action window.
5. Use the Context field to specify the context in which the variable is set. For
example, tmp1 identifies the tmp1 context.
6. Specify the name of the variable in the Variable Name field or click Var
Builder to use the variable builder to specify a variable to use as the name.
Refer to Using the variable builder on page 162 for details.
7. Specify the value for the variable in the Variable Assignment field.
8. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
9. Click Done to complete the action. The configuration path shows the Set
Variable icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Sign (sign) action

To add a sign action, use the following procedure:
1. Drag the Sign icon to the configuration path (the horizontal line).
2. Double-click the Sign icon to display the Sign action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Select the signature method with the Envelope Method radio buttons.
Enveloped Method
The signature is over the XML content that contains the signature as
an element. The content provides the root XML document element.
Enveloping Method
The signature is over the XML content found in an Object element or
the signature itself. The Object is identified with a Reference. The
contents of the Object is identified with a URI fragment identifier or
transform.
SOAPSec Method
The signature is included in a SOAP header entry.
WSSec Method
(Default) The signature is included in a WS-Security security header.

Chapter 5. Defining processing policies 145

 Refer to http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/ for more
information about envelope methods.
5. Select the type of document to sign with the Message Type radio buttons.
SOAP Message
(Default) The message conforms to the SOAP schema.
SOAP with Attachments
The message conforms to the SOAP with Attachments schema. The
signature method must be WS-Security.
Raw XML Document
The message is in raw XML format. The signature method must be
enveloped or enveloping.
Selected Elements (Field-level)
Sign select elements of a SOAP message or an XML message. This
action requires a Document Crypto Map. The Operation property of
the Crypto Map must agree with the signature method.
6. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. If the Message Type is Selected Elements (SOAP Fields) or SOAP with
Attachments, from the Document Crypto Map list, select the Document
Crypto Map to identify the message fields to encrypt. Refer to Document
Crypto Map on page 282 for more information.
8. Select an instance of the Key object from the Key list.
9. Select an instance of the Certificate object from the Certificate list.
10. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
11. Use the Output field to specify the destination context for the signed XML.
12. Optionally click the Advanced tab to define greater control of X.509
compatibility, optional WS-Security Version and Timestamp settings, and other
advanced features.
v To generate Signature Confirmation (frontend), change the Include
SignatureConfirmation to on (response side).

146 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v To verify Signature Confirmation (backend), change the Expect Verifier to
Return wsse11:SignatureConfirmation to on (request side).
This setting saves the generated value. A verify action can process the
response to verify the returned WS-Security 1.1 SignatureConfirmation.
For details about other advanced settings, refer to the online help.
13. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

SLM (slm) action

To add an slm action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the SLM radio button.
4. Click Next to display the Enforce SLM policy action window.
5. Specify or select the context for the data to be processed in the Input field.
6. From the SLM Policy list, select the policy to monitor transactions. Refer to
SLM policies on page 328 for configuration details.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify or select the context for the data produced in the Output field.
9. Click Done to complete the action. The configuration path shows the SLM
icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

SQL (sql) action

This action requires that the DataPower appliance be licensed for SQL-ODBC.

To add an sql action, use the following procedure:

1. Drag the Advanced icon to the configuration path (the horizontal line).
2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the SQL radio button.
4. Click Next to display the SQL Action window.
5. Specify or select the context for the data to be processed in the Input field.

Chapter 5. Defining processing policies 147

 6. Provide the context name, the string PIPE (for streaming mode) or the string
INPUT (identifies the original input into this rule).
7. Retain the default value (auto) to allow the processing policy to determine the
input context needed to connect this action to the previous output.
8. Use the SQL Data Source list to identify the database accessed by this sql
action. Refer to SQL Data Source on page 337 for SQL Data Source
configuration details.
9. Use the SQL Input Method list to identify the source of the SQL statement
that is invoked by the SQL Action.
Static (Default) Indicates that the SQL statement is contained in the SQL Text
field.
Stylesheet
Indicates that the SQL statement is derived by executing the style
sheet specified by the Transform field against the contents on the
context specified by the Input field.
Variable
Indicates that the SQL statement is contained in the variable specified
by the Variable Name field.
10. If the SQL Input Method is Static, use the SQL Text field to provide an SQL
statement. This setting indicates that the SQL statement that is used by the
action is provided by this property.
11. If the SQL Input Method is Stylesheet, use either the Processing Control File
dialog or the Variable Name field to identify a style sheet. This setting
indicates that the SQL statement that is used by the action is constructed by
executing the specified style sheet against the contents of the Input context.
12. If the SQL Input Method is Variable, use the Variable Name field to identify
a style sheet. This setting indicates that the SQL statement that is used by the
action is the contents of the specified variable.
13. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
14. Optionally specify or select the context for the data produced in the Output
field.
15. Click Done to complete the action. The configuration path shows the SQL
icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Strip attachments (strip-attachments) action

To add a strip-attachments action, use the following procedure:
1. Drag the Advanced icon to the configuration path (the horizontal line).

148 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 2. Double-click the Advanced icon to display a window that lists the advanced
action types.
3. Click the Strip Attachments radio button.
4. Click Next to display the Strip Attachments action window.
5. In the Attachment URI field, specify the attachment to strip. If omitted, all
attachments are stripped from the specified context.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Click Done to complete the action. The configuration path shows the Strip
Attachments icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Transform-type actions
A processing policy provides the following transform implementations:
Transform for XML messages
Uses the xform action to transform XML documents. The action identifies
the XSLT style sheet to use to perform the transform.
Transform for non-XML messages
Uses the xformbin action to transform non-XML documents. The action
identifies the XSLT style sheet to use to perform the transform.
Processing instruction-based transform for XML messages
Uses the xformpi action to transform XML documents. The XML document
is the source of the processing instruction. The action uses the processing
instruction in the presented XML documents to perform the transform.
SOAP refinement transform
Transforms the SOAP header and child elements of a SOAP document in
accordance with the defined SOAP Header Disposition table. This
transform uses the soap-refine.xsl style sheet in the store: directory.
Buffer attachments transform
Transforms an attachment manifest to ensure that all attachments are
buffered, not streamed. This transform uses the buffer-attachments.xsl style
sheet in the store: directory.
Conformance transform
Transforms an XML document to conform to the define Conformance
Policy. This transform uses the conformance-xform.xsl style sheet in the
store: directory.

Defining a transform for XML messages

To add an xform action, use the following procedure:
1. Drag the Transform icon to the configuration path (the horizontal line).
Chapter 5. Defining processing policies 149
 2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Retain the default (Use XSLT specified in this action) from the Use Document
Processing Instructions radio buttons.
5. In the Processing Control File field, specify or select the style sheet to use.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
6. Optionally from the URL Rewrite Policy list, select the rewrite policy to rewrite
the style sheet URL that is extracted from the incoming document. Refer to
URL Rewrite Policy on page 339 for more information.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify or select the context for the data produced in the Output field.
9. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a transform for non-XML messages

This action requires that the DataPower appliance be licensed for DataGlue.

To add an xformbin action, use the following procedure:

1. Drag the Transform icon to the configuration path (the horizontal line).
2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Select the Use XSLT specified in this action on a non-XML message radio
button from the Use Document Processing Instructions radio buttons. The
Transform action window refreshes and displays the Transform Binary action
window.
5. In the Processing Control File field, specify or select the style sheet to use.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
6. In the WTX Map File field, specify the URL of the map file that you
previously uploaded. Use this field only when you are using a map file that
was generated by WebSphere Design Studio.

150 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 7. Optionally from the URL Rewrite Policy list, select the rewrite policy to
rewrite the style sheet URL that is extracted from the incoming document.
Refer to URL Rewrite Policy on page 339 for more information.
8. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
9. Specify or select the context for the data produced in the Output field.
10. Click Done to complete the action. The configuration path shows The
Transform Binary icon.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a processing instruction-based transform for XML

messages
To add an xformpi action, use the following procedure:
1. Drag the Transform icon to the configuration path (the horizontal line).
2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. In the Processing Control File field, specify or select the style sheet to use.
v If the style sheet is not stored on the appliance, specify its location or a
variable that expands to a URL. If a variable, use the var://context/name
form.
v If the style sheet is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
5. Optionally from the URL Rewrite Policy list, select the rewrite policy to rewrite
the style sheet URL that is extracted from the incoming document. Refer to
URL Rewrite Policy on page 339 for more information.
6. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
7. Specify or select the context for the data produced in the Output field.
8. Click Done to complete the action. The configuration path shows the
Transform Using Processing Instruction icon.

Chapter 5. Defining processing policies 151

 If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a SOAP refinement transform

To add a SOAP refinement transform action, use the following procedure:
1. Drag the Transform icon to the configuration path (the horizontal line).
2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Retain the default (Use XSLT specified in this action) from the Use
Document Processing Instructions radio buttons.
5. In the Processing Control File field, specify or select the store:///soap-
refine.xsl style sheet.
6. Optionally select the rewrite policy to rewrite the style sheet URL that is
extracted from the incoming document from the URL Rewrite Policy list.
Refer to URL Rewrite Policy on page 339 for more information.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Click the Advanced tab.
9. Use the Enforce One SOAP Actor/Role toggle to determine whether to
enforce the S11:actor or S12:role) attribute in the SOAP header.
on (Default) Enforces the S11:actor or S12:role attribute.
When on, type the identifier for the actor or role that the action works
as in processing SOAP headers in the SOAP Actor/Role Identifier
field. Use one of the following well-known values:
http://schemas.xmlsoap.org/soap/actor/next
Everyone, including the intermediary and ultimate receiver,
receives the message and should be able to process the security
header.
http://www.w3.org/2003/05/soap-envelope/role/none
No one should process the security header.
http://www.w3.org/2003/05/soap-envelope/role/next
Everyone, including the intermediary and ultimate receiver,
receives the message and should be able to process the security
header.
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
(Default) The ultimate receiver can process the security header.
Blank or an empty string
No actor/role identifier is configured. The ultimate receiver is
assumed when processing the message, and no actor/role
attribute is added when generating the security header.

152 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Note: There should not be more than one security header that
omit the actor/role identifier.
USE_MESSAGE_BASE_URI
Indicates that the actor/role identifier is the base URI of the
message. If the SOAP message is transported using HTTP, the
base URI is the request-URI of the HTTP request.
Any other string
Indicates the actor or role of the security header.
off Cause the action to ignore S11:actor and S12:role attributes, which
allows the action to work as any actor or role.
When off, the screen refreshes to display the SOAP Service Type
field. Select the service provider type of the DataPower appliance in
the message flow from the SOAP Service Type list.
Intermediary SOAP service
Applies the following processing rules:
v Remove SOAP headers when the S11:actor or S12:role
attribute is "next".
v Keep SOAP headers when the S11:actor or S12:role attribute
is "none".
v Issue a SOAP Fault in the following cases:
For all unprocessed headers when the S11:mustUnderstand
or S12:mustUnderstand attribute is effectively true
For SOAP 1.2 messages with the S12:notUnderstood
attribute
v Remove processed SOAP headers unless the S12:relay
attribute is effectively true, but keep unprocessed SOAP
headers.
Ultimate SOAP service
(Default) Applies the following processing rules:
v Remove SOAP headers, if the S11:actor or S12:role attribute
is "next".
v Keep SOAP headers, if the S11:actor or S12:role attribute is
"none".
v Issue a SOAP Fault in the following cases:
For all unprocessed headers when the S11:mustUnderstand
or S12:mustUnderstand attribute is effectively true
For SOAP 1.2 messages with the S12:notUnderstood
attribute
v Remove processed and unprocessed SOAP headers.
10. Use the Detect ID References while Deleting toggle to control whether SOAP
headers or their direct child elements can be removed when an XML elements
references them.
on (Default) Delete SOAP headers only when no other XML element
being kept references this header or one of its direct child elements.
Local ID references are detected with #ID.
This setting protects xenc:EncryptedKey when it references
EncryptedData or EncryptedHeader although there is no @URI that
points to xenc:EncryptedKey.

Chapter 5. Defining processing policies 153

 This setting does not impact defined remove instruction in the SOAP
Header Disposition Table.
off Delete SOAP headers without checking for ID references.
11. Select the disposition table from the SOAP Header Disposition Table list.
This table contains a list of instructions that controls how to handle SOAP
headers, child elements, or both SOAP headers and child elements. Refer to
SOAP Header Disposition Table on page 336 for information.
12. Specify or select the context for the data produced in the Output field.
13. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a buffer attachment transform

With allow-mode streaming, the DataPower appliance buffer only attachments that
are needed to process the rule. If an input package contains parts multiple
attachments and the request rule needs only one of the attachments, the
attachments that are not needed can be streamed to the output without buffering.

The request rule cannot know the behavior of subsequent rules in the same scope.
If a request rule streams all attachments, a response rule cannot access attachments
in the intermediate contexts that are created by the request rule. If a response rule
needs access to the attachments that were streamed by the request rule, add a
transform action with the buffer-attachments.xsl style sheet in the store: directory.
This style sheet gets the attachment manifest to ensure that all attachments are
buffered and not streamed.

To add a buffer attachment transform action, use the following procedure:

1. Drag the Transform icon to the configuration path (the horizontal line).
2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Retain the default (Use XSLT specified in this action) from the Use Document
Processing Instructions radio buttons.
5. In the Processing Control File field, specify or select the store:///buffer-
attachments.xsl style sheet.
6. Optionally select the rewrite policy to rewrite the style sheet URL that is
extracted from the incoming document from the URL Rewrite Policy list. Refer
to URL Rewrite Policy on page 339 for more information.
7. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Specify or select the context for the data produced in the Output field.
9. Click Done to complete the action.

154 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining a conformance transform

To add a conformance transform action, use the following procedure:
1. Drag the Transform icon to the configuration path (the horizontal line).
2. Double-click the Transform icon to display the Transform action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Retain the default (Use XSLT specified in this action) from the Use
Document Processing Instructions radio buttons.
5. In the Processing Control File field, specify or select the store:///
conformance-xform.xsl style sheet.
6. Optionally select the rewrite policy to rewrite the style sheet URL that is
extracted from the incoming document from the URL Rewrite Policy list.
Refer to URL Rewrite Policy on page 339 for more information.
7. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
8. Select the conformance policy from the Conformance Policy list. Refer to
Conformance Policy on page 279 for details.
9. Specify or select the context for the data produced in the Output field.
10. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Validate (validate) action

The processing of a validate action can change the document in the input context.
For example, processing could add values for default attributes. In other words,
the document is the input context might not be the exact same document in the
output context. Therefore, exercise extreme caution if you need to use the output
context of the validate action as the input context for subsequent processing.

To add a validate action, use the following procedure:

1. Drag the Validate icon to the configuration path (the horizontal line).
2. Double-click the Validate icon to display the Validate action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Use the Schema Validation Method radio buttons to specify the schema
validation methodology.

Chapter 5. Defining processing policies 155

 Validate Document via Schema URL
Requires the use of a specific schema regardless of any validation
processing instruction in the XML document undergoing validation
Validate Document via Schema Attribute
(Default) Specifies that candidate documents are verified in
accordance with validation instructions contained with the document.
Documents that lack such instructions are considered to be validated.
Validate Document via Attribute Rewrite Rule
Rewrites the schema reference (if any) contained in the XML
document undergoing validation, and then validates the document
against the rewritten schema reference. The rewritten reference usually
points to the location of a local trusted copy of the schema.
Validate Document with Encrypted Sections
Uses a schema exception map to validate a partially encrypted
document. The Schema Exception Map contains a reference to a base
schema used with the map to generate the dynamic schema required
for this action.
Validate Document via WSDL URL
Uses a WSDL file to validate the message, When selected, a WSDL
URL field is displayed.
5. If the schema validation method is Validate Document via Attribute Rewrite
Rule, from the Policy list, select the URL Rewrite Policy to rewrite the internal
schema reference. Refer to URL Rewrite Policy on page 339 for more
information.
6. If the schema validation method is Validate Document via Schema URL, use
the Schema URL field to identify the XML schema used by this validate
action.
v If the schema is not stored on the appliance, specify its location.
v If the schema is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
Click WSDL Tool to invoke the WSDL Tool. This tool reads a designated
WSDL file and creates the necessary schema file. The tool can also create the
necessary Processing Control File for a Filter action. The files are stored in the
local: directory.
7. If the schema validation method is Validate Document with Encrypted
Sections, from the Schema Exception Map list, select the Schema Exception
Map to generate the required dynamic schema. Refer to Schema Exception
Map on page 327 for more information.
8. If the schema validation method is Validate Document via WSDL URL, use
the WSDL URL field to identify the WSDL file used by this validate action.
v If the WSDL file is not stored on the appliance, specify its location.
v If the WSDL file is in the store: or local: directory, select the style sheet.
You can click Upload or Fetch to obtain the file.
9. Use the SOAP Validation list to determine which parts of the message to
validate.
Envelope
Apply the schema to the entire message, including the SOAP
Envelope.
Body (Default) Validate the contents of the SOAP Body element, without
special processing for SOAP faults.

156 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Body or Detail
Apply the schema against the contents of the detail element for SOAP
faults, and the contents of the Body otherwise.
Ignore Faults
If the document is a SOAP fault, pass it through without further
validation; otherwise, validate the contents of the SOAP Body.
This setting does not affect validating the INPUT context to ensure that it is a
valid document. If you are validating an intermediate context, such as the
result of an XSLT transform or an externally retrieved document, this content
is not implicitly validated as SOAP. You might want to select Envelope to
validate the entire document.
10. Use the Asynchronous toggle to determine whether the action is
asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action
to complete by adding this action to a subsequent event-sink action
in the same processing rule. Refer to Event-sink (event-sink) action
on page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
11. Specify or select the context for the data produced in the Output field.
12. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Verify (verify) action

To add a verify action, use the following procedure:
1. Drag the Verify icon to the configuration path (the horizontal line).
2. Double-click the Verify icon to display the Verify action window.
3. Specify or select the context for the data to be processed in the Input field.
4. Use the Asynchronous toggle to determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the action to
complete by adding this action to a subsequent event-sink action in
the same processing rule. Refer to Event-sink (event-sink) action on
page 124 for details.
off (Default) Marks the action as synchronous. This action must complete
for the next action in the processing rule to begin.
5. Optionally from the Validation Credential list, select the validation credential
to use to validate the certificate of the signer.
6. Optionally specify or select the context for the data produced in the Output
field.
7. Optionally click the Advanced tab to define advanced settings.

Chapter 5. Defining processing policies 157

 v To use a certificate not taken from the signature information, specify the
action-specific signer certificate that validates the signature in the Signer
Certificate field. Specify %url% to use the dpquery:signer query parameter.
The action can find the certificate based on the SubjectKeyIdentifier rather
than a Direct reference. It accepts both forms of the KeyIdentifier ValueType
for WS-Sec v1.0, and also handles draft-13 and draft-12.
v To disable the check for the expiration of the WS-Security timestamp, change
the Check Timestamp Expiration toggle to off.
v To generate Signature Confirmation (frontend), change the Save Verified
Signatures for Later wsee11:SignatureConfirmation toggle to on (request
side).
Change this setting when the client sends a signed request and expects to
receive a WS-Security 1.1 Signature Confirmation that ensures that a signed
request from the client is an original, verified signature, A sign action can
process the response message to insert WS-Security 1.1
SignatureConfirmation elements in the reply to the client.
v To verify Signature Confirmation (backend), change the Must check
SignatureConfirmation (WS-Security 1.1) toggle to on (response side).
v To facilitate in the retrieval of remote tokens change the WS-Security 1.1:
Retrieve Remote Token toggle to on. Refer to Security token references on
page 358 for details.
When enabled, the following properties are available:
WS-Security 1.1: Remote Token SSL Proxy Profile
If the remote side requires a secure connection, select the SSL Proxy
Profile from the list.
WS-Security 1.1: Remote Token Identity Credentials
If an identity credential is required to sign the retrieval method,
select the Crypto Identification Credentials from the list.
WS-Security 1.1: URL to Process the Remote Token
The remote token could be signed, encrypted, or encoded. A firewall
or proxy service with different actions must be used to process the
remote token. The processing could be decrypting pieces of a remote
SAML assertion, performing a transform, or using an AAA policy to
assert the token.
Specify the URL for the firewall or proxy service. This service accepts
the security token as the request of the SOAP call. If the request is
successful, the service responds with the final security token.
8. Click Done to complete the action.

If this is the last action to add to the rule, click Apply Policy to add the completed
rule to the processing policy. Otherwise, drag another action icon to the
configuration path.

Defining reusable rules

A reusable rule is a Processing Rule object that a call or on-error action can
define as its processing rule to perform the configured series of action.

To define a reusable rule within the context of defining the processing policy, use
the following procedure:
1. Select an existing rule in the policy.

158 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 2. Click Create Reusable Rule. The cursor changes to a + shape.
3. Click and drag the cursor around one or more actions in the current rule. A
blue highlighted box is drawn around the selected action.
4. Depending on the DataPower service, click Apply or Apply Policy to create the
reusable rule.

After the screen redraws, the reusable rule is displayed as a highlighted group in
the policy hierarchy.

Locating remote resources in actions

Table 1 lists the actions that can specify the location of a resource on a remote
server, the name of the field as shown through the WebGUI, whether this
specification is required or optional, and the number of remote server from which
the resource can be retrieved or to which the data can be sent.
Table 1. Actions and remote resources
Optional or
Action type WebGUI label Required Number of servers
fetch Source Required Only one
for-each Source Required One or more
log Destination Required One or more
results Destination Optional One or more
results-async Destination Required One or more
route-set Destination Required Only one

Supported protocols in attachments

You can access resources on remote servers using one of the following protocols:
v dpmq (MQ protocol to a static backend)
v dptibems (not secure) or dptibemss (secure), if licensed
v dpwasjms (not secure) or dpwasjmss (secure)
v ftp
v http
v https
v ims (not secure) or imsssl (secure), if licensed
v mq (MQ protocol to a dynamic backend)
v smtp
v sql, if licensed
v tcp
v tcps

In addition to the previous protocols, the fetch, results, and results-async

actions support the attachment protocol. Refer to Using the attachment protocol
on page 160 for details.

Specifying the location of remote resources

To specify the location, use one of the following methods:

Chapter 5. Defining processing policies 159

 URL Specify the URL. For example, you could specify http://
server1.domain.com:2222 in the Source or Destination field.
Predefined variable
Use a predefined variable in the var://context/name form that expands to
a URL (Source or Destination field) or to multiple URLs (Destination field
only).
For a single URL
Use the setvar action to define the var://context/remote1 variable
with a value of http://server1.domain.com:2222. Then, specify
var://context/remote1 in the Source or Destination field.
For multiple URLs
Use the setvar action to define the var://context/results/
remote-multi variable with the following value:
<results mode="require-all" multiple-outputs="true">
<url input="context1">http://127.0.0.1:22223</url>
<url input="context2">http://127.0.0.1:22224</url>
<url input="context3">http://127.0.0.1:22225</url>
<url input="context4">http://127.0.0.1:22226</url>
</results>

Then, specify var://context/results/remote-multi in the

Destination field.
For information about constructing the <results> node, refer to
Format of the <results> element on page 161.
Custom style sheet
Use a custom style sheet that defines a variable that expands to multiple
URLs. For example, you could create a style sheet with the following
declarations:
<xsl:variable name="URLs">
<results mode="require-all" multiple-outputs="true">
<url input="context1">http://127.0.0.1:22223</url>
<url input="context2">http://127.0.0.1:22224</url>
<url input="context3">http://127.0.0.1:22225</url>
<url input="context4">http://127.0.0.1:22226</url>
</results>
</xsl:variable>
<dp:set-variable name="'var://context/results/remoteMany'" value="$URLs"/>

Then, specify var://context/results/remoteMany in the Destination field.

The input="context" attribute tells the multi-way for-each or results

action to use the specified context for sending results to the appropriate
target (value of Output field for for-each and value of Destination field
for results.
For information about constructing the <results> node, refer to Format of
the <results> element on page 161.

Using the attachment protocol

The fetch, results, and results-async actions support the attachment protocol.
This protocol identifies a SOAP attachment and has the following format:
attachment://context/cid:content_id[?query_param_1[&query_param_2]]

The fetch action supports the following query parameters:

v Encode=base64

160 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v Compress=gzip
v Archive=tar or Archive=zip
v Filename=file_name

The results and results-async actions support the following query parameters:
v Decode=base64 or Decode=hexbin
v Compress=gzip
v Archive=tar or Archive=zip
v Filename=file_name
v Parsable=true
v Manifest=true

The following code excerpt shows a configuration that uses the attachment and
cid protocols:
rule swa-zip-003
# fetch base64 encoded zip file into archive-base64
fetch
cid:contract123.zip
archive-base64
strip-attachments INPUT

# add archive-base64 as a new attachment to input and decode

results
archive-base64
attachment://INPUT/cid:archive-zip?Decode=base64

# fetch binary file into context x

fetch
http://zoostation/clitest-importpackage.zip
new-file-to-add

# add file to archive

results
new-file-to-add
attachment://INPUT/cid:archive-zip?Archive=zip&Filename=testfile

# return context with new archive (3 files)

results INPUT
exit

Format of the <results> element

The XML for the <results> element can be stored as value in a variable, whose
name, in turn, can be specified as the destination of a result or result-async
action. The XML can be store as the value, for example in var://context/foobar/
dest variable, through either a style sheet or setvar action. Then, the
var://context/foobar/dest variable can be specified as the destination of a result
action. The result action will then parse the XML in the variable and act
accordingly.

The <results> element can have the following attributes:

<results mode="first-available | require-all | attempt-all"
transactional="true | false"
retry-interval="duration"
asynchronous="true | false"
multiple-outputs="true | false">
<url>...</url>
<url>...</url>
<results>

Chapter 5. Defining processing policies 161

 The <url> element can have the following attributes:
<url retry-count="count"
synchronous="true | false
input="context">
URL
</url>

The context value for the input argument cannot be INPUT, OUTPUT, or PIPE.

Using the variable builder

When defining the following actions, you can access the variable builder to define
variables for the name or value of a variable:
v Call processing rule (call)
v On error (on-error)
v Set variable (setvar)

For the call and on-error actions, you can create a custom context variable only.
After clicking Var Builder the area shown in Figure 6 is visible.

Figure 6. Variable builder for custom context variables

For the setvar action, you can create a custom context variable or select an existing
service, extension, or system variable. The created or selected variable must be a
write-only or read-write variable. After clicking Var Builder the area shown in
Figure 7 is visible.

Figure 7. Variable builder for custom context, service, extension, and system variables

After defining a custom context variable, click Use Custom. The variable builder
closes, and the field contains the defined variable.

162 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Debugging processing policies
The DataPower appliance provides a powerful debugging utility for use during the
development of processing policies. This utility is called the multistep probe. The
probe displays the contents of contexts, the value of variables, the results of actions
and the output of the policy. The administrator can step through the policy to view
the action taken on a message.

The probe is enabled through the Troubleshooting icon on the Control Panel. Refer
to IBM WebSphere DataPower SOA Appliances: Problem Determination Guide for more
information.

Chapter 5. Defining processing policies 163

164 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 6. Defining an AAA Policy
An Authentication, Authorization, Audit (AAA) policy, sometimes referred to as an
Access Control Policy, identifies a set of resources and procedures that can be used
to determine whether a requesting client is granted access to a specific service, file,
or document. AAA policies can be considered a type of filter in that they accept or
deny a specific client request.

AAA policies are powerful and flexible. They can support a range of authentication
and authorization mechanisms to include SAML, Netegrity, and RADIUS. Multiple
authentication and authorization mechanisms can be mixed and matched in a
single policy. For example, one AAA policy can use a single RADIUS server to
provide authentication and authorization services, while a second policy can use a
RADIUS server for authentication, use a local XML file to map the RADIUS
authentication credentials to an LDAP group name, and finally use an LDAP
server to authorize the LDAP group.

Figure 8 shows the basic processing for an AAA Policy. Initial processing (common
to all policies) consists of extracting the claimed identity of the service requester
and the requested resource from an incoming message and its protocol envelope.
As you define an AAA Policy, extraction methods are specified by a series of check
boxes that enable one or more identity and resource extraction methods. A wide
range of identity and resource extraction methods are supported. For example,
identity can be based on IP address, form (account name and 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.

Extract Identity Extract Resource Authenticate Allow | Deny

Map Credentials Map Resource Authorize Allow | Deny

Post Processing

Output Generate
Message Error

Figure 8. AAA Policy Processing

After extracting the service requester identity and resource, the policy authenticates
the claimed identity. Authentication is most commonly accomplished via an
external service (for example, a RADIUS or LDAP server), but other custom
processing methods, such as site-specific XML- or XPath-based solutions, are
readily supported. During policy definition, you select a single authentication
method from a menu of supported methods, and (depending upon the selected
method) provide a few items of additional required information, such as a server
address or the URL of a custom processing resource.

Copyright IBM Corp. 2002, 2009 165

 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. This optional mapping
can be accomplished by an XPath expression, an XML mapping file or a custom
method.

As with identity credentials, the extracted resource name can also be mapped to
something more appropriate for the authorization method selected. The methods
for achieving this optional mapping are the same as those for credential mapping.

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.

While you can use the same method for both authentication and authorization, you
need not do so. In fact, different authentication and authorization methods are
often employed in real-world situations. If different methods are used, it might be
necessary to map credentials from the authentication phase to a format that is
congruent with a different authorization method. For example, you might want to
map an authenticated account name-password to an LDAP group.

Like authentication, authorization is most commonly accomplished through an

external service (for example, an LDAP server), but other custom processing
methods, such as site-specific XML- or XPath-based solutions, are supported.
Authorization definition mirrors that of authentication. During policy definition,
you select a single authorization method and provide a minimum of
method-specific data.

If either authentication or authorization denies access, the AAA policy generates an

error, which is returned to the calling entity (which might be the client submitting
the request). This error can be handled, as with any other errors in multistep
processing, by an on-error action or an Error rule. Either method allows for the
creation of custom error messages.

Note: The AAA framework does not stop processing after an unsuccessful
authentication to leave flexibility for unauthenticated access and ensure post
processing, auditing, and accounting can continue. If you are customizing
AAA, be sure that you produce appropriate output for failed authentication
and your custom authorization recognizes unauthenticated requests to avoid
creating a security vulnerability.

Creating a new AAA Policy object

The AAA Policy Editor steps through the creation or editing of an AAA Policy
from a Processing Policy. The editor is launched from the AAA action. When
invoked, the initial AAA Policy window is displayed.

Specify the name of this new AAA Policy in the AAA Policy Name field.

Click Create to create the policy with the name provided and displays the Identity
Extraction window.

Note: All selected methods will be implemented. The firmware executes the
methods in the order presented by the list. The AAA policy concatenates all
identities found for authentication.

166 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 It is possible use one authentication policy to support submissions from
multiple different sources that employ different identification methods. For
example, client partner A might use HTTP Basic Authentication, client
partner B might use a WS-Security UsernameToken, and client partner C
might rely on SAML. All three methods would be selected. One policy can
support all three identification methods.

Defining identity extraction methods

The initial processing performed by the AAA Policy consists of extracting
information from an incoming message and its protocol envelopes about the
claimed identity of the service requester.

Use the Identity Extraction window to provide required details

1. Set the Identification Methods check boxes to enable one or more identification
extraction methods.
HTTP Authentication Header
The claimed identity of the requester is extracted from the HTTP
Authorization header (name and password, base64 encoded). Here is an
example submission. The relevant header appears in bold.
POST /InStock HTTP/1.1
Host: www.stock.org
Content-Type: text/xml; charset=utf-8
Content-Length: nnn
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Password-carrying UsernameToken Element from WS-Security Header
The claimed identity of the requester is extracted from the WS-Security
UsernameToken element (Username and Password) in the security header.
Password digests are supported. The following header illustrates a
SOAP document with the values of the Username and Password
elements highlighted in bold.
<?xml version="1.0" encoding="UTF-8"?>
<S11:Envelope
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/">
<S11:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>Fred</wsse:Username>
<wsse:Password>Flintstone</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</S11:Header>
Derived-key UsernameToken Element from WS-Security Header
The password for the user must be obtained to calculate the derived
symmetric key. If selected, the WebGUI displays the following
properties:
Password Retrieval Method
Choose the method to obtain the password:
AAA Info file
The password is in an AAA Info file. When selected, the
WebGUI displays the following property:

Chapter 6. Defining an AAA Policy 167

 Specify the URL of the Password Retrieval AAA Info
file Specifies the location of the DataPower AAA Info
file that provides the password.
Custom Template
The password is retrieved by a custom or proprietary
identification resource (for example, a style sheet). When
selected, the WebGUI displays the following property:
Specify the URL of the Password Retrieval Stylesheet
v If the resource is stored in the local: or store:
directory, select the resource.
v If the resource is remote to the local: or store
directory, specify the location of the resource.
v If the resource is stored on the WebGUI
workstation, click Upload to transfer the file.
v If the resource is stored on a remote server, click
Fetch to transfer the file.
BinarySecurityToken Element from WS-Security Header
The claimed identity of the requester is extracted from the WS-Security
BinarySecurityToken element (using the tokens string value as the
claimed identity) contained in a SOAP header. Here is an example, with
the BinarySecurityToken highlighted in bold.
<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://www.w3.org/2001/12/soap-envelope"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
xmlns:xenc="http://www.w3.org/2001/04/xmlenc"
xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">
<SOAP-ENV:Header>
<wsse:Security
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/secext">
<wsse:BinarySecurityToken
wsu:Id="HotelX509Token"
ValueType="wsse:X509v3"
EncodingType="wsse:Base64Binary">
FIfB3sgwMzA9CgWaxIBASysgEmtLhrrqaQrKhi...
</wsse:BinarySecurityToken>
WS-SecureConversation Identifier
The claimed identity of the requester is extracted from a
WS-SecureConversation Identifier. A client that has established a
security context could provide credentials in addition to the security
context identifier to help with authentication; if present, the <wst:Base>
or <wst:Supporting> or both elements in the SOAP body serve this
purpose. AAA policies that have this method selected should look for
these elements, if present.
<?xml version="1.0" encoding="utf-8"?>
<S11:Envelope xmlns:S11="..." xmlns:ds="..." xmlns:wsse="..."
xmlns:wsu="..." xmlns:wsc="...">
<S11:Header>
...
<wsse:Security>
<wsc:SecurityContextToken wsu:Id="MyID">
<wsc:Identifier>uuid:...</wsc:Identifier>
</wsc:SecurityContextToken>
<ds:Signature>
...

168 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
WS-Trust Base or Supporting Token
The claimed identity of the requester is extracted from a WS-Trust base
or supporting token.
<wst:Base>, if present, contains a token that can be used to verify the
integrity of the message. Since the initial client request (before
establishment of the security context) will likely be over a secured
transport, this element is relevant only when the initial request is over
an unsecured channel. In that case, <wst:Base> points to the X.509
certificate (via a <wsse:SecurityTokenReference> child element) whose
private key has secured the authentication information (for instance,
encrypting a <wsse:UsernameElement> in the header).
The following example presents a complete SOAP Envelope with a
WS-Trust Base token highlighted in bold.
<?xml version="1.0" encoding="us-ascii"?>
<S11:Envelope xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wse="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-secext-1.0.xsd"
xmlns:wst="http://schemas.xmlsoap.org/ws/2004/04/trust"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd">
<S11:Header> <wsa:MessageID wsu:Id="msg">message1</wsa:MessageID>
...
<wse:Security>
<wse:UsernameToken wsu:Id="username">
<wse:Username>John</wse:Username>
<wse:Password>nhoJ</wse:Password>
</wse:UsernameToken>
</wse:Security>
</S11:Header>
<S11:Body>
<wst:RequestSecurityToken wst:Context="context1">
...
<wst:Base>
<wse:SecurityTokenReference>
<wse:Reference URI="#username" />
</wse:SecurityTokenReference>
</wst:Base>
</wst:RequestSecurityToken>
</S11:Body>
</S11:Envelope>
Kerberos AP-REQ from WS-Security Header
The claimed identity of the requester is extracted from a Kerberos
AP-REQ (containing a ticket and an authenticator) contained in the
WS-Security header.
Kerberos AP-REQ from SPNEGO
The claimed identity of the requester is extracted from a Kerberos
AP-REQ (containing a ticket and an authenticator) contained in a
SPNEGO token.
Token Subject DN of the SSL Certificate from the Connection Peer
The claimed identity of the requester is extracted from the SSL client
certificate presented during the SSL handshake.
Name from SAML Attribute Assertion
The claimed identity of the requester is extracted from a SAML
assertion that contains a SAML attribute statement the name contained
in the Subject element of the attribute statement is used as the claimed
identity.

Chapter 6. Defining an AAA Policy 169

 <saml:Assertion
MajorVersion="1"
MinorVersion="0"
AssertionID="http://www.myEMarketplace.com/
AuthenticationService/SAMLAssertions/786"
Issuer="http://www.myEMarketplace.com"
IssueInstant="2003-06-11T02:00:00Z">
<saml:Conditions
NotBefore="2003-03-11T02:00:00Z"
NotOnOrAfter="2003-06-12T02:00:00Z"/>
<saml:AttributeStatement>
<saml:Subject>
<saml:NameIdentifier
NameQualifier="http://www.myEMarketplace.com">MyTourOperator
</saml:NameIdentifier>
...
Name from SAML Authentication Assertion
The claimed identity of the requester is extracted from a SAML
assertion that contains a SAML authentication statement the name
contained in the Subject element of the authentication statement is used
as the claimed identity.
<soap:Envelope>
<soap:Header>
<ws:Security>
<saml:Assertion
AssertionID="2se8e/vaskfsdif="
Issuer="www.sts.com"
IssueInstant="2002-06-19T16:58:33.173Z">
<saml:Conditions
NotBefore="2002-06-19T16:53:33.173Z"
NotOnOrAfter="2002-06-19T17:08:33.173Z"/>
<saml:AuthenticationStatement
AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:X.509"
AuthenticationInstant="2002-06-19T16:57:30.000Z">
<saml:Subject>
<saml:NameIdentifier>Client</saml:NameIdentifier>
<saml:SubjectConfirmation>
<saml:ConfirmationMethod>
urn:oasis:names:tc:SAML:1.0:cm:sender-vouches
</saml:ConfirmationMethod>
</saml:SubjectConfirmation>
</saml:Subject>
</saml:AuthenticationStatement>
<ds:Signature>
<-- calculated by STS -->
</ds:Signature>
</saml:Assertion>
</ws:Security>
SAML Artifact
The AAA policy captures a SAML artifact, which is then used during
the Authenticate step to provide an authenticated identity. An artifact
might appear in the URL used by the client.
https://server.domain.com/service?SAMLART=h48ck4klje
Client IP Address
The IP address of the client is used for authentication.
Subject DN from Certificate in the Messages signature
The claimed identity of the requester is extracted from a certificate used
to validate a digitally-signed message. The AAA policy verifies the
validity of the signature. If valid, uses the Subject DN that is extracted
from the certificate that is associated with the signature as the claimed
identity.
170 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
<?xml version="1.0" encoding="UTF-8"?>
<message xmlns="http://www.example.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.com message.xml">
<to>Alice</to>
<from>Bob</from>
<subject>Important</subject>
<body>
Traveling to San Francisco, Honolulu, and Ashtabula.
See you in the sky.
</body>
<method>Fax</method>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SignedInfo>
...
</SignedInfo>
<SignatureValue>MBwxXIuY2...</SignatureValue>
<KeyInfo>
<X509Data>
<X509Certificate>MIICMjCCTfMCFB9mFK6vs= </X509Certificate>
<X509IssuerSerial>
<X509IssuerName>CN=jrb@somedomain.com</X509IssuerName>
<X509SerialNumber>0</X509SerialNumber>
</X509IssuerSerial>
</X509Data>
</KeyInfo>
</Signature>
</message>

If selected, the WebGUI displays the following properties:

Validation Credentials for Signing Certificate
Select a Validation Credentials to validate the presented
certificate. Refer to Working with Validation Credentials objects
on page 21 for more information.
Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security
token references on page 358 for details.
off (Default) Processes the signer DN as part of the map
credentials phase.
on Retrieves the remote token. When enabled, the following
properties are available:
SSL Proxy Profile
If the remote side requires a secure connection, select
the SSL Proxy Profile from the list.
URL to Process the Remote Token
The remote token could be signed, encrypted, or
encoded. A firewall or proxy service with different
actions must be used to process the remote token. The
processing could be decrypting pieces of a remote
SAML assertion, performing a transform, or using an
AAA policy to assert the token.
Specify the URL for the firewall or proxy service. This
service accepts the security token as the request of the
SOAP call. If the request is successful, the service
responds with the final security token.

Chapter 6. Defining an AAA Policy 171

 Token Extracted from the Message
The claimed identity of the requester is extracted using an XPath
expression.
<message xmlns="http://www.example.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.com message.xml">
<to>Alice</to>
<from>Bob</from>
<subject>Important</subject>
<body>
Traveling to San Francisco, Honolulu, and Ashtabula.
See you in the sky.
</body>
<method>Fax</method>
</message>

If selected, the WebGUI displays the following property:

XPath expression
Specify the operative XPath expression to be applied to the entire
message.
To assist in creating the XPath expression, click XPath Tool. This
tool allows you to upload an XML document and build the
expression by pointing at the desired node. If the defined
expression contains namespace elements, click XPath Binding to
provide namespace or prefix data. Refer to Setting namespace
mappings (XPath bindings) on page 264 for information on
providing namespace binding properties.
Token Extracted as Cookie Value
The claimed identity of the requester is extracted from a Cookie value.
If selected, the WebGUI displays the following property:
Cookie name
Specify the cookie name.
LTPA Token
The claimed identity of the requester is extracted from an LTPA
(Lightweight Third Party Authentication) token value.
LTPA tokens, which are opaque, signed and encrypted strings, are
carried via HTTP, specifically in the Set-Cookie response and Cookie
request headers. Refer to Understanding LTPA for more information.
Processing Metadata
Extract the identity from the processing metadata, such as protocol
headers, system variables, and other custom metadata sources. If
selected, the WebGUI displays the following property:
Processing Metadata Item
Select a Processing Metadata object to identify extracted items.
Refer to Processing Metadata on page 322 for more information.
You must use custom style sheet for authentication.
Custom Template
The claimed identity of the requester is extracted by a custom or
proprietary identification resource (for example, a style sheet).
If selected, the WebGUI displays the following property:
Specify a URL

172 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v If the resource is stored in the local: or store: directory, select
the resource.
v If the resource is remote to the local: or store directory, specify
the location of the resource.
v If the resource is stored on the WebGUI workstation, click
Upload to transfer the file.
v If the resource is stored on a remote server, click Fetch to
transfer the file.
2. After enabling one or more identity extraction methods, click Next to display
the Authentication window and continue with the Authentication phase of the
AAA Policy definition.

Defining the authentication method

After identifying a service requester, the AAA Policy references an external service
or internal process to validate the identity and obtain a set of credentials that attest
to the identify of the client. Use the Authentication window to provide required
details.

Use the Method radio buttons to select the authentication method. You can select
only one authentication method. The selected method should not conflict with the
methods that are used to extract an identity.
Accept a SAML Assertion with a Valid Signature
The requester is authenticated by a SAML assertion with a valid signature.
An optional field appears to identify validation credentials. If selected, the
WebGUI displays the following properties:
SAML signature validation credentials
Optionally select the Validation Credentials set used to validate a
digitally-signed SAML assertion. The AAA policy validates the
signature against these credentials. If the certificate cannot be
validated, authentication fails. For information on compiling a
Validation Credentials List, refer to Working with Validation
Credentials objects on page 21.
Accept an LTPA token
The requester is authenticated by an encrypted LTPA token. Refer to
Understanding LTPA for more information. If selected, the WebGUI displays
the following properties:
Acceptable LTPA Versions
Select the LTPA formats to support:
Domino LTPA
Used in Lotus Domino environments
WebSphere Version 1 LTPA
Used in WebSphere environments
WebSphere Version 2 LTPA
(Default) Used in WebSphere environments. This version was
introduced in WebSphere Application Server for z/OS version
5.1.0.2; for other platforms, version 5.1.1.
You must select at least one, or all LTPA-based authentication fail.
Because the LTPA token must be decrypted before authentication, define
the following properties:

Chapter 6. Defining an AAA Policy 173

 LTPA Key File
Specify the name of the file that contains the cipher keys used for
encryption and decryption.
LTPA Key File Password
Specify the cleartext password for the key file.
Bind to Specified LDAP Server
The requester is authenticated by an LDAP server. The identity string that
is extracted from the message should conform to the LDAP DN format
(such as, CN=Alice). If selected, the WebGUI displays the following
properties:
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If you select a group, LDAP
queries will be load balanced in accordance with the settings in the
group. Load balancing allows for failover. Refer to Load Balancer
Group on page 287 for more information.
When specified, this property overrides the settings for the Host and
Port properties.
Host
Specify the IP address or host name of the LDAP server.
Port Specify the port number of the LDAP server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
LDAP Bind DN
Specify the Distinguished Name for the LDAP bind operation.
LDAP Bind Password
Specify the password for the specified DN.
LDAP Search Attribute
Specify the name of the LDAP attribute that contains the cleartext
password. The default is userPassword.
This property is meaningful only when the identity extraction
method is Password-carrying UsernameToken Element from
WS-Security Header and the <Username> element in the header has
the Type attribute set to PasswordDigest. In this case, the LDAP
server returns the text in the specified LDAP attribute for the user in
the UsernameToken. If the hashed value of the returned text does not
match the value in the <Password> element, authentication fails.
LDAP Version
Select the LDAP protocol version (2, the default version, or 3) to use
when accessing the authentication server.
LDAP Search for DN
Indicate whether to perform an LDAP search retrieve the DN of the
user.
on Enables an LDAP search for the users group. The login name
of the user along with the LDAP Search Parameters will be
used as part of an LDAP search to retrieve the users DN.
off (Default) Disables an LDAP search for the users group. The

174 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 login name of the user along with the LDAP prefix and the
LDAP suffix will be used to construct the users DN.
v If on, the WebGUI displays the LDAP Search Parameters field.
Select the LDAP Search Parameters from the list. Refer to
Defining an LDAP Search Parameters object on page 286 for
detail.
v If off, the WebGUI removes the LDAP Prefix and LDAP Suffix
fields:
LDAP Prefix
Optionally specify an LDAP prefix name. The specified string is
prefixed to the identity that is extracted before submission to the
LDAP server. The default is cn=.
LDAP Suffix
Optionally specify an LDAP Suffix name. This specified string is
appended to the identity that is extracted before submission to the
LDAP server. For example, o=datapower.
Contact a SAML Server for a SAML Authentication Statement
The requester is authenticated by a SAML server. If authentication
succeeds, a SAML Authentication statement is returned and used for
further communication. If selected, the WebGUI displays the following
properties:
SAML signature validation credentials
Optionally select the Validation Credentials set used to validate a
digitally-signed SAML authentication statement. The AAA policy
validates the signature against these credentials. If the certificate
cannot be validated, authentication fails. Refer to Working with
Validation Credentials objects on page 21 for more information.
SAML Authentication Query Server URL
Specify the URL of the SAML Authentication server to use to retrieve
a SAML authentication statement.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
SAML Version
Select the SAML version. Versions 1.0, 1.1 (Default) and 2.0 are
supported. This version determines the protocol level of SAML
messages, which, in turn, affects the extraction of identity from the
original message and the format of messages to SAML authentication
and authorization entities.
Contact a WS-Trust Server for a WS-Trust Token
The requester is authenticated by a WS-Trust server. The server
authenticates the requester and returns a WS-Trust token that can be used
for further communication. If selected, the WebGUI displays the following
properties:
WS-Trust Server URL
Specify the URL used to access the WS-Trust server.

Chapter 6. Defining an AAA Policy 175

 SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
WS-Trust Compatibility Version
Select the WS-Trust/WS-SecureConversation version to use when
sending a request to a remote Security Token Service (STS). The
default is 1.2.

The following properties are relevant for attaching WS-Policy, not for AAA
authentication.
Require Client Entropy
Indicates whether to require client entropy as key material in the
WS-Trust request.
on Requires client entropy. The DataPower appliance sends an
entropy element to the WS-Trust server as part of the security
token request exchange. Use the WS-Trust Encryption
Certificate property to determine how to include the key
material in the request.
off (Default) Does not require client entropy.
When required, specify the size of the client entropy in bytes in the
Client Entropy Size field. The size refers to the length of the client
entropy before Base64 encoding. Use an integer in the range of 8
through 128. The default is 32.
Require Server Entropy
Indicates whether to require server entropy in the WS-Trust response.
on Requires server entropy. The WS-Trust server must return an
entropy element to the DataPower appliance as part of the
security token request exchange.
off (Default) Does not require server entropy.
When required, specify the minimum allowable size of the received
entropy material in bytes in the Server Entropy Size field. The size
refers to the length of the client entropy before Base64 encoding. Use
an integer in the range of 8 through 128. The default is 32.
Require RequestSecurityTokenCollection
Indicates whether to generate a WS-Trust RequestSecurityToken or a
WS-Trust RequestSecurityTokenCollection as part of the security
token request exchange.
on Generates a WS-Trust RequestSecurityTokenCollection.
off (Default) Generates a WS-Trust RequestSecurityToken.
Require AppliesTo SOAP Header
Indicates whether to generate a WS-Addressing AppliesTo header as
part of the security token request exchange.
on Generates a WS-Addressing AppliesTo header.
off (Default) Does not generate a WS-Addressing AppliesTo
header.
When required, specify the value for the AppliesTo header in the
AppliesTo Header field.

176 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 WS-Trust Encryption Certificate
Optionally select a Crypto Certificate to encrypt WS-Trust elements in
the request. If selected, he public key of the certificate encrypts the
client entropy key material for the recipient. If blank, the WS-Trust
BinarySecret element contains the entropy material. In this case, use
an SSL Proxy Profile to secure the message exchange with the
WS-Trust server.
Contact ClearTrust server
The requester is authenticated by a ClearTrust server. If selected, the
WebGUI displays the following properties:
ClearTrust Server URL
Specify the URL used to access the ClearTrust server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
Contact Netegrity SiteMinder
The requester is authenticated by a Netegrity server. If selected, the
WebGUI displays the following properties:
Host
Specify the IP address or host name of the Netegrity server.
Port Specify the port number of the Netegrity server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
Netegrity Base URI
Optionally specify a Base URI for the identified Netegrity server. The
Base URI consists of the concatenation of the combination of the
servlet-name and url-pattern from its web.xml file. Given the
following entries in a web.xml file, specify datapoweragent/.
<servlet-mapping>
<servlet-name>datapoweragent</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
Contact NSS for SAF Authentication
The requester is authenticated by the SAF. If selected, the WebGUI prompts
for the following property:
z/OS NSS Client Configuration
Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server for SAF authentication. Refer
toCreating the z/OS NSS Client on page 354 for more information.
Contact Tivoli Access Manager
The requester is authenticated by Tivoli Access Manager (TAM). This is a
licensed feature and is not available on all systems. To use this method, a
valid TAM object must exist. If selected, the WebGUI displays the
following property:
Tivoli Access Manager Configuration
Select a TAM object. Refer to Creating and configuring TAM objects
on page 271 for more information.

Chapter 6. Defining an AAA Policy 177

 Custom template
The requester is authenticated by an unlisted resource; for example, a style
sheet. If selected, the WebGUI displays the following property:
Specify a URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the resource is stored on a remote server, click Fetch to transfer
the file.
Pass Identity Token to the Authorize Step
The extracted identity is passed to the AAA authorization step for
disposition. Authentication, in effect, succeeds.
Retrieve SAML Assertions Corresponding to a SAML Browser Artifact
The requester is authenticated by the SAML Responder. If selected, the
WebGUI displays the following properties:
SAML Artifact Responder URL
Specify the issuer of the artifact.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authentication server. Retain the default value to use a non-SSL
connection.
SAML Version
Select the SAML version. Versions 1.0, 1.1 (Default) and 2.0 are
supported. The selected version determines the protocol level of
SAML messages, which, in turn, affects the extraction of identity
from the original message and the format of messages to SAML
authentication and authorization entities.
Use an Established WS-SecureConversation Security Context
The requester is authenticated by reference to an established
WS-SecureConversation security context. This context must already exist.
Use certificate from BinarySecurityToken
The requester is authenticated by a certificate included with a
BinarySecurityToken. If selected, the WebGUI displays the following
property:
X.509 BinarySecurityToken Validation Credential
Select the Validation Credentials set used to validate the X.509
certificate extracted from the WS-Security BinarySecurityToken
element. Refer to Working with Validation Credentials objects on
page 21 for more information.
Refer to the description in Defining identity extraction methods on page
167.
Use DataPower AAA Info File
The requester is authenticated by an XML AAA file. This file contains a list
of authenticated users. The XML file can authenticate user names,
passwords, IP hosts, distinguished names, or custom tokens. If selected, the
WebGUI displays the following property:

178 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 URL
Select or specify the location of the file:
v If the target file is stored in the local: or store: directory, select the
file.
v If the target file is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the target file is stored on a remote server, click Fetch to transfer
the file.
v If the target file is remote to the local: or store: directory, specify
the location of the target file.
Refer to AAA Info File on page 265 for more information.
Use specified RADIUS Server
The requester is authenticated by a RADIUS server. The AAA policy
automatically contacts RADIUS servers. At least one AAA RADIUS server
must be configured for use. A RADIUS Settings object can be created in the
default domain only. For details, refer to the IBM WebSphere DataPower
SOA Appliances: Administrators Guide.
If selected, the WebGUI displays the following property:
RADIUS Settings
Select a list of RADIUS servers. Without a list of AAA RADIUS
servers in an existing instance of the RADIUS Settings object, the
AAA policy uses the servers in the RADIUS servers list.
Validate a Kerberos AP-REQ for the Correct Server Principal
The requester is authenticated using a Kerberos AP-REQ that is in the
WS-Security header. If selected, the WebGUI displays the following
property:
Servers Kerberos Keytab
Select the Kerberos Keytab File. Refer to Kerberos Keytab File
objects on page 276 for more information.
Validate the Signer Certificate for a Digitally Signed Message
The requester is authenticated via the certificate passed as part of the
<X509/> element of a digitally signed message. If selected, the WebGUI
displays the following properties:
Signature Validation Credentials
Optionally select the Validation Credentials set used to validate the
certificate presented by document signer. If this certificate cannot be
validated, authentication fails. Refer to Working with Validation
Credentials objects on page 21 for more information.
XPath Expression
Specify an XPath expression to be applied to the incoming document
to extract the signed portion of the document.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression
by selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace/prefix data. Refer to Setting
namespace mappings (XPath bindings) on page 264 for more
information.

Chapter 6. Defining an AAA Policy 179

 Retrieve Remote Token
Select whether to retrieve the remote token. Refer to Security token
references on page 358 for details.
off Processes the signer DN as part of the map credentials phase.
on Retrieves the remote token. When enabled, the following
properties are available:
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection
to remote authentication server. Retain the default value to
use a non-SSL connection.
URL to Process the Remote Token
The remote token could be signed, encrypted, or encoded.
A firewall or proxy service with different actions must be
used to process the remote token. The processing could be
decrypting pieces of a remote SAML assertion, performing
a transform, or using an AAA policy to assert the token.
Specify the URL for the firewall or proxy service. This
service accepts the security token as the request of the
SOAP call. If the request is successful, the service
responds with the final security token.
Validate the SSL Certificate from the Connection Peer
The requester is authenticated via its client SSL credentials. If selected, the
WebGUI displays the following property:
SSL Credentials
Select the Validation Credentials set used to validate offered client
certificates. If the certificate cannot be validated, authentication fails.
Refer to Working with Validation Credentials objects on page 21 for
more information.

After select one authentication method, continue with the Map Credentials phase
of the AAA Policy definition.

Mapping authentication credentials

After obtaining a set of credentials that attest to the identity of the client, an AAA
policy can optionally map these credentials to a more useful format by performing
custom processing on the received credentials.

Select the credentials mapping method from the Method list.

Custom
Identifies a custom, credentials mapping resource; for example, a style
sheet. If selected, the WebGUI displays the following property:
Specify a URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.

180 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v If the resource is stored on a remote server, click Fetch to transfer
the file.
None (Default) Credential mapping is not performed.
TFIM Credentials are taken from a TFIM configuration. If selected, the WebGUI
prompts from the following property:
TFIM Configuration
Select a TFIM configuration. Refer to Creating the TFIM object on
page 272 for more information.
WS-SecureConversation
Credentials are taken from the WS-SecureConversation context token.
XML File
Identifies an XML file as the mapping resource. If selected, the WebGUI
displays the following property:
URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the resource is stored on a remote server, click Fetch to transfer
the file.
Refer to AAA Info File on page 265 for more information.
XPath Identifies an XPath expression as the mapping resource. If selected, the
WebGUI displays the following property:
XPath Expression
Specify an XPath expression to be applied to the value extracted
during the identity extraction phase.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression
by selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace or prefix data. Refer to Setting
namespace mappings (XPath bindings) on page 264 for more
information.

Changing the authentication caching policy

By default, authentication information from remote resources is cached for a period
of three seconds. On authentication failure, authentication information is removed
from the cache.

To modify the caching policy, use the following procedure:

1. Click Advanced to display the Authentication Caching Policy window.
2. Use the Policy radio buttons to specify the authentication caching strategy.
Absolute
(Default) Caches all authentication data with an explicit TTL (specified
in the TTL field)

Chapter 6. Defining an AAA Policy 181

 Disabled
Disables caching of authentication data
Maximum
Compares the explicit TTL with the received TTL, if any. If it is less
than the explicit TTL, use the data-specific TTL; otherwise, use the
explicit value.
Minimum
Compares the explicit TTL with the received TTL, if any. If it is greater
than the explicit TTL, use the data-specific TTL; otherwise, use the
explicit value.
3. Specify the explicit TTL in seconds in the TTL field.
4. Click Next to return to the AAA Policy configuration where you can define
resource extraction methods.

Defining resource extraction methods

After authenticating a service requester, the AAA Policy extracts information from
an incoming message and it protocol envelopes about the requested resource.

Use the Resource Extraction window to provide required details.

Use the check boxes to select one or more resource extraction methods.
URL sent to back end
The identity of the requested resource is extracted from the (possibly
rewritten) URL sent to the server. If the firewall has an active URL Rewrite
Policy in place, this value is likely to be different than the URL sent by the
client. For example:
https://server.insideservice.com/ProcessTransactions
URL sent by client
The identity of the requested resource is extracted from the original URL
sent by the client. For example:
https://www.consumerservice.com/PlaceOrder
URI of toplevel element in the message
The identity of the requested resource is extracted from the namespace of
the top-level application element. For example:
<?xml version="1.0" encoding="UTF-8"?>
<S11:Envelope
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/"
xmlns:S11="http://schemas.xmlsoap.org/soap/envelope/">
<S11:Header>...</S11:Header>
<S11:Body>...</S11:Body>
</S11:Envelope>
Local name of request element
The identity of the requested resource is extracted from the simple name of
the top-level application element. For example:
<?xml version="1.0" encoding="UTF-8"?>
<S11:Envelope
...
<S11:Header>...</S11:Header>
<S11:Body>
<i:getBalance xmlns:i="urn:develop-com:IBank">
...
</S11:Body>
</S11:Envelope>

182 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 HTTP operation (GET/POST)
The identity of the requested resource is the HTTP operation of the client
request. For example:
POST/InStock HTTP/1.1
Host: www.stock.org
Content-Type: application/soap+xml; charset=utf-8
Content-Length: nnn
XPath expression
The identity of the requested resource is extracted from the client request
by an XPath expression. If selected, the WebGUI displays the following
properties:
XPath expression
Specify an XPath expression to be applied to the value extracted
during the Resource Extraction step.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression
by selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace/prefix data. Refer to Setting
namespace mappings (XPath bindings) on page 264 for more
information.
For example, you could specify /*[local-name()="message"]/*[local-
name()="transitmethod"] for the following message:
<?xml version="1.0"?>
<message xmlns="http://www.example.com"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.example.com message.xml">
<to>Alice</to>
<from>Bob</from>
<subject>Important</subject>
<body>
Traveling to San Francisco, Honolulu, and Ashtabula.
See you in the sky.
</body>
<transitmethod>Fax</transitmethod>
</message>
Processing Metadata
Extract the resource from the processing metadata, such as protocol
headers, system variables, and other custom metadata sources. If selected,
the WebGUI displays the following property:
Processing Metadata Item
Select a Processing Metadata object to identify extracted items. Refer
to Processing Metadata on page 322 for more information.
You must use custom style sheet for authentication.

Mapping requested resources

After extracting the resource request, the AAA Policy can optionally map the
requested resource to a more useful format by performing custom processing on
the request.

Select the resource mapping method from the Method list.

Chapter 6. Defining an AAA Policy 183

 Custom
Identifies a custom mapping resource; for example, a style sheet. If
selected, the WebGUI displays the following property:
Specify a URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the resource is stored on a remote server, click Fetch to transfer
the file.
None (Default) Resource mapping is not performed.
tivoli Identifies a Tivoli style mapping resource. If selected, the WebGUI displays
the following properties:
Tivoli object space mapping
Indicates which style of object space prefix to concatenate to the
extracted resource:
Custom
Indicates that the output of the mapped resource uses a
user-defined prefix. If selected, the WebGUI displays the
following property:
Tivoli object space instance prefix
Specify a user-defined prefix. When implemented, the
mapped resource output is:
user_defined_prefix/mapped_resource_name
TAMBI prefix
Indicates that the output of the mapped resource uses the prefix
style from Tivoli Access Manager for Business Integration. If
selected, the WebGUI displays the following property:
Tivoli object space instance prefix
Specify the name of the queue manager and the queue
separated by a forward slash (/). When implemented, the
mapped resource output is:
/PDMQ/queue_manager/queue/mapped_resource_name
TFIM prefix
Indicates that the output of the mapped resource uses the prefix
style from Tivoli Federated Identity Manager (TFIM). If
selected, the WebGUI displays the following property:
Tivoli object space instance prefix
Specify the name of the TFIM domain. When selected, the
mapped resource output is:
/itfim-wssm/wssm-default/domain_name/mapped_resource_name
WebSEAL prefix
(Default) Indicates that the output of the mapped resource uses
the prefix style used by the WebSEAL component of Tivoli
Access Manager for e-business. If selected, the WebGUI displays
the following properties:

184 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Tivoli object space instance prefix
Specify the name of the WebSEAL instance. When
implemented, the mapped resource output is:
/WebSEAL/instance_name/mapped_resource_name
WebSEAL URL mapping file
Optionally specify the name of the WebSEAL DynURL
file. When configured and an entry is matched for a
request, the DynURL output replaces the output of the
extract resource string that is appended to the TAM object
space prefix.
xmlfile
Identifies an XML file as the mapping resource. If selected, the
WebGUI displays the following property:
URL
v If the resource is stored in the local: or store: directory, select
the resource.
v If the resource is remote to the local: or store directory,
specify the location of the resource.
v If the resource is stored on the WebGUI workstation, click
Upload to transfer the file.
v If the resource is stored on a remote server, click Fetch to
transfer the file.
Refer to AAA Info File on page 265 for more information.
XPath
Identifies an XPath expression as the mapping resource. If selected,
the WebGUI displays the following property:
XPath expression
Specify an XPath expression to be applied to the value extracted
during the Resource Extraction phase.
For assistance in creating the XPath expression, click XPath
Tool. This tool allows you to load an XML document and build
the expression by selecting the desired node.
If the defined expression contains namespace elements, click
XPath Binding to provide namespace/prefix data. Refer to
Setting namespace mappings (XPath bindings) on page 264
for more information.

Click Next to display the Authorization window.

Defining the authorization method

After authenticating a service requester and identifying the requested resource, an
AAA Policy references an external service or object to authorize the service
requester; that is determining whether or not this requester is cleared for access to
the requested resource.

Use the Authorization window to provide required details.

Use the radio buttons to select a single authorization method.

Chapter 6. Defining an AAA Policy 185

 Allow any authenticated client
All authenticated messages are forwarded to the backend server.
Always allow
All messages are passed to the backend server.
Contact Tivoli Access Manager
(a licensed feature) The requester is authorized by Tivoli Access Manager
(TAM). A TAM object must exist. If selected, the WebGUI displays the
following properties:
Tivoli Access Manager Configuration
Select a TAM object. Refer to Creating and configuring TAM objects
on page 271 for more information.
Default action
Select the default action. The default is T (Traverse).

[PDMQ]D (TAMBI c (Control) r (Read)

Dequeue)
[PDMQ]E (TAMBI d (Delete) s (Server Admin)
Enqueue)
[WebService]i (TFIM g (Delegate) T (Traverse)
Action)
A (Add) l (List Directory) t (Trace)
a (Attach) m (Modify) v (View)
B (Bypass) N (Create) W (Password)
b (Browse) R (Bypass AuthAZ) x (Execute)

Resource/Action map
Select an existing action map file.
This type of action map allows a single AAA policy to use different
ACL actions during authorization based on the requested resource.
For example, you could have a TAM action map with the entries
listed in Table 2.
Table 2. Example of TAM action map entries
Pattern Action
*one* x (execute)
*two* r (read)

When an authorization request, whose resources are /resource/one

and /resource/two, the first authorizes the use of the execute action
and the second entry authorizes the use of the read action.
For information about creating or editing this type of action map, use
the WebGUI online help.
Refer to IBM Tivoli Access Manager on page 270 for more information.
Contact Netegrity SiteMinder
The requester is authorized by a Netegrity SiteMinder server. If selected,
the WebGUI displays the following properties:
Host
Specify the IP address or host name of the Netegrity SiteMinder
server.

186 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Port Specify the port number of the Netegrity SiteMinder server. The
default is 389.
Netegrity Base URI
Optionally specify a base URI for the Netegrity SiteMinder server.
Contact NSS for SAF Authorization
The requester is authorized by the SAF. If selected, the WebGUI prompts
for the following property:
z/OS NSS Client Configuration
Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server for SAF authorization. Refer toCreating
the z/OS NSS Client on page 354 for more information.
Contact ClearTrust Server
The requester is authorized by a ClearTrust server. If selected, the WebGUI
displays the following properties:
ClearTrust Server URL
Specify the URL used to access the ClearTrust Server
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Custom template
The requester is authorized by an unlisted resource; for example, a style
sheet. If selected, the WebGUI displays the following properties:
Specify a URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the resource is stored on a remote server, click Fetch to transfer
the file.
Check for membership in an LDAP group
The requester is authorized by an LDAP server. If selected, the WebGUI
displays the following properties:
Host
Specify the IP address or host name of the LDAP server.
Port Specify the port number of the LDAP server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Group DN
Specify the name of LDAP group.
LDAP Bind DN
Specify the Distinguished Name for the LDAP Bind.

Chapter 6. Defining an AAA Policy 187

 LDAP Bind Password
Specify the password for the LDAP Bind.
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If a group is selected,
LDAP queries will be load balanced in accordance with the group
settings. Load balancing allows for failover service when using LDAP
authentication. Refer to Load Balancer Group on page 287 for more
information.
LDAP Group Attribute
Specify a Group Attribute string. The authorizing identity must be
present as the value corresponding to the attribute.
LDAP Version
Select the LDAP protocol version (v2, the default version, or v3) to
use when accessing the authentication server.
LDAP Search Scope
Select the depth of the LDAP search.
base
Specifies that the search matches only the input itself.
one-level
Specifies that the search matches the search input and any
object one-level below.
subtree
(Default) Specifies that the search matches the input and any
descendents.
LDAP Search Filter
Optionally specify an LDAP search filter to allow for customized
LDAP searches.
LDAP filter syntax is defined in RFC 2254, The String Representation of
LDAP Search Filters.
LDAP Search Attribute
Specify the name of the LDAP attribute that contains the cleartext
password. The default is userPassword.
This property is meaningful only when the identity extraction
method is Password-carrying UsernameToken Element from
WS-Security Header and the <Username> element in the header has
the Type attribute set to PasswordDigest. In this case, the LDAP
server returns the text in the specified LDAP attribute for the user in
the UsernameToken. If the hashed value of the returned text does not
match the value in the <Password> element, authentication fails.
Generate a SAML authorization query
The requester is authorized by a SAML authorization query. If selected, the
WebGUI displays the following properties:
SAML Server URL
Specify the URL of the target SAML server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.

188 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 SAML Name Qualifier
Optionally specify the SAML Name Qualifier to provide a Name
Qualifier as defined in Section 2.4.2.2 of Assertions and Protocol for the
OASIS Security Assertion Markup Language (SAML) V1.1.
SAML Version
Select the SAML version. Versions 1.0, 1.1 (Default) and 2.0 are
supported. This version determines the protocol level of SAML
messages, which, in turn, affects the extraction of identity from the
original message and the format of messages to SAML authentication
and authorization entities.
SAML signature validation credentials
Select a Crypto Validation Credential set to use for this transaction. If
a Crypto Validation Credential is selected here, then the certificate
used to sign the SAML message will be validated as part of the
authorization step.
For information on creating a Crypto Validation Credentials set, refer
to Working with Validation Credentials objects on page 21.
SAML message signing key
Select a Crypto Key to use for this transaction. For information on
creating a Crypto Key, refer to Defining Key objects on page 16.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. For information
on creating a Crypto Certificate, refer to Defining Certificate objects
on page 13.
SAML message signing algorithm
If the SAML message that is generated for this policy will be digitally
signed, select the SignatureMethod for the signing algorithm. The
default is rsa.
SAML signing message digest algorithm
If the SAML message that is generated for this policy will be digitally
signed, select the algorithm to calculate the message digest for
signing. The default is sha1.
Generate a SAML attribute query
The requester is authorized by a SAML attribute query. If selected, the
WebGUI displays the following properties:
SAML Server URL
Specify the URL of the target SAML server.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
SAML Version
Select the SAML version. Versions 1.0, 1.1 (Default) and 2.0 are
supported. This version determines the protocol level of SAML
messages, which, in turn, affects the extraction of identity from the
original message and the format of messages to SAML authentication
and authorization entities.
Type
Use the radio buttons to select a SAML match type.

Chapter 6. Defining an AAA Policy 189

 XPath expression
(Default) Specify an XPath expression to be used to match
SAML attributes (names or names and values).
For assistance in creating the XPath expression, click XPath
Tool. This tool allows you to load an XML document and build
the expression by selecting the desired node.
If the defined expression contains namespace elements, click
XPath Binding to provide namespace/prefix data. Refer to
Setting namespace mappings (XPath bindings) on page 264
for more information.
Must match at least one name
Any one Attribute name in the response from the SAML server
must match one configured on the SAML Attributes panel. To
define SAML attributes, refer to Defining SAML attributes on
page 264.
Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
define SAML attributes, refer to Defining SAML attributes on
page 264.
Must match at least one name and value
Any one Attribute name and corresponding value in the
response from the SAML server must match one name-value
pair configured on the SAML Attributes panel. To define SAML
attributes, refer to Defining SAML attributes on page 264.
Must match all names and values
All attribute names and corresponding values in the response
from the SAML server must match those configured on the
SAML Attributes panel. To define SAML attributes, refer to
Defining SAML attributes on page 264.
SAML signature validation credentials
Select a Crypto Validation Credential set to use for this transaction. If
a Crypto Validation Credential is selected here, then the certificate
used to sign the SAML message will be validated as part of the
authorization step. For information on creating a Crypto Validation
Credentials set, refer to Working with Validation Credentials
objects on page 21.
SAML message signing key
Select a Crypto Key to use for this transaction. For information on
creating a Crypto Key, refer to Defining Key objects on page 16.
SAML message signing certificate
Select a Crypto Certificate to use for this transaction. For information
on creating a Crypto Certificate, refer to Defining Certificate objects
on page 13.
SAML message signing algorithm
If the SAML message that is generated for this policy will be digitally
signed, select the SignatureMethod for the signing algorithm. The
default is rsa.

190 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 SAML signing message digest algorithm
If the SAML message that is generated for this policy will be digitally
signed, select the algorithm to calculate the message digest for
signing. The default is sha1.
Use SAML attributes from Authentication
The requestor is authorized using the SAML attributes obtained during the
authentication phase. These attributes are compared to the SAML
Attributes configured for this policy. If selected, the WebGUI displays the
following properties:
Type
Use the radio buttons to select a SAML match type.
XPath expression
(Default) Specify an XPath expression to be used to match
SAML attributes (names or names and values).
For assistance in creating the XPath expression, click XPath
Tool. This tool allows you to load an XML document and build
the expression by selecting the desired node.
If the defined expression contains namespace elements, click
XPath Binding to provide namespace/prefix data. Refer to
Setting namespace mappings (XPath bindings) on page 264
for more information.
Must match at least one name
Any one Attribute name in the response from the SAML server
must match one configured on the SAML Attributes panel. To
define SAML attributes, refer to Defining SAML attributes on
page 264.
Must match all names
All Attribute names in the response from the SAML server must
match those configured on the SAML Attributes panel. To
define SAML attributes, refer to Defining SAML attributes on
page 264.
Must match at least one name and value
Any one Attribute name and corresponding value in the
response from the SAML server must match one name-value
pair configured on the SAML Attributes panel. To define SAML
attributes, refer to Defining SAML attributes on page 264.
Must match all names and values
All attribute names and corresponding values in the response
from the SAML server must match those configured on the
SAML Attributes panel. To define SAML attributes, refer to
Defining SAML attributes on page 264.
Use XACML Authorization Decision
The requester is authorized by an internal or external XACML Policy
Decision Point (PDP). Refer to XACML Policy Decision Point on page
277 for information on creating an internal PDP.
If selected, the WebGUI displays the following properties:
XACML Version (list)
Select the XACML version (1.0 or 2.0, the default) to use for
communications between the PDP and this AAA Policy, acting as an
XACML Policy Enforcement Point (PEP).

Chapter 6. Defining an AAA Policy 191

 PEP Type
Select how the AAA Policy, acting as an XACML PEP processes the
PDP authorization response.
Base PEP
Select the response to the authorization request:
Deny-biased PEP
If the response to the request is permit, the client is authorized.
If the permit response is accompanied by obligations, the client
is authorized only if the AAA Policy, acting as a PEP, can
understand and discharge the conditions.
Any other XACML response results in a rejection.
Permit-biased PEP
If the response to the request is deny, the client is rejected. If the
deny response is accompanied by obligations, the client is
rejected only if the AAA Policy, acting as a PEP, can understand
and discharge the conditions.
Any other XACML response results in an authorization.
Use On Box PDP
Use this toggle to specify the location of the PDP.
on (Default) Specifies use of a local PDP. If selected, the WebGUI
displays the following property:
XACML PDP
Select the PDP to provide authorization services for the
AAA Policy. Refer to XACML Policy Decision Point on
page 277 for more information.
off Specifies the use of a remote XACML PDP. If selected, the
WebGUI displays the following property value:
External PDP URL
Specify the URL to which to send XACML-based
authorization requests.
PDP Requires SAML 2.0
Use this toggle to force the use of the SAML2.0 Profile.
Meaningful only when the XACML version is 2.0.
on Forces the use of the SAML2.0 profile.
off (Default) Does not require the use of the SAML2.0
profile.
SOAP Enveloping
Use the toggle to determine whether the external PDP
requires SOAP enveloping. If the custom binding style
sheet generated SOAP enveloping, retain the default
setting.
on Before the PEP posts the context request to the
external PDP with the HTTP POST method, the
SOAP Body of the content request is wrapped by
the <xacml-samlp:XACMLAuthzDecisionQuery> SAML
Profile element.
off (Default) The PEP posts the context request to the
external PDP with the HTTP POST method.

192 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 This property can be combined with the PDP Requires
SAML 2.0 property when the XACML request is wrapped
by the <xacml-samlp:XACMLAuthzDecisionQuery> SAML
Profile element.
AAA XACML Binding Method
Retain the default value, which is the only supported option.
Custom Stylesheet to Bind AAA and XACML
Select the custom style sheet that maps the AAA result or input
message to the XACML context request. This context request contacts
the PDP for an XACML decision.
Obligation Fulfillment Custom Stylesheet
Specify the custom style sheet to parse any obligation that
accompany an authorization decision that is received from the PEP.
Use DataPower AAA info file
The requester is authorized by an XML file. If selected, the WebGUI
displays the following property:
URL
v If the resource is stored in the local: or store: directory, select the
resource.
v If the resource is remote to the local: or store directory, specify the
location of the resource.
v If the resource is stored on the WebGUI workstation, click Upload
to transfer the file.
v If the resource is stored on a remote server, click Fetch to transfer
the file.
Refer to AAA Info File on page 265 for more information.

Changing the authorization caching policy

By default, authorization information from remote resources is cached for a period
of three seconds. On authorization failure, authorization information is removed
from the cache.

To modify the caching policy, use the following procedure:

1. Click Advanced to display the Authorization Caching Policy window.
2. Use the Policy radio buttons to specify the authorization caching strategy.
Absolute
(Default) Caches all authorization data with an explicit TTL (specified
in the TTL field).
Disabled
Disables caching of authorization data.
Maximum
Compares the explicit TTL with the received TTL, if any. If it is less
than the explicit TTL, use the data-specific TTL; otherwise, use the
explicit value.
Minimum
Compares the explicit TTL with the received TTL, if any. If it is greater
than the explicit TTL, use the data-specific TTL; otherwise, use the
explicit value.
3. Specify the explicit TTL in seconds in the TTL field.

Chapter 6. Defining an AAA Policy 193

 4. Click Next to return to the AAA Policy configuration where you can define
post processing activities.

Defining post processing activities

After authorizing the client, an AAA Policy can perform post processing activities.
You can define the following post processing activities:
v Define counters for authorized and rejected messages
v Define logging for authorizations and rejections
v Modify the message in one or more of the following ways:
Running a custom style sheet
Generating a SAML assertion that contains an authentication statement for the
authenticated identity
Including an AP-REQ token to act as Kerberos client
Processing a WS-Trust SecurityContextToken (SCT) request
Adding a WS-Security UsernameToken to the message
Generating an LTPA token
Generating a Kerberos SPNEGO token
Requesting a Tivoli Federated Identity Manager (TFIM) token map

Additionally, you can send a logout message to a SAML authority. However, this
post processing activity is available from the Object view only. For details, refer to
AAA Policy on page 239.

Defining counters for authorized and rejected messages

During post processing, you can define Count Monitors to record successful and
rejected authorizations.

Defining a counter for authorized messages

To define a Count Monitor for successful authorizations, select the Count Monitor
from the Authorized Counter list to monitor and control incoming messages that
the AAA Policy authorizes.

If you are defining a new monitor, select XPath from the Measure list. Refer to
Message Count Monitor on page 230 for information on creating message count
monitors.

Defining a counter for rejected messages

To define a Count Monitor for rejected authorizations, select the Count Monitor
from the Authorized Counter list to monitor and control incoming messages that
the AAA Policy rejects.

To define a new monitor, click Reject Counter Tool. This tool helps to create the
monitor.

Defining logging for authorizations and rejections

During post processing, you can control whether log entries are recorded for
authorized and for rejected access attempts. When enabled, log entries are recorded
at the specified level.

By default logging is enabled for both types of attempts.

v For authorized attempts, entries are at the information level.

194 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v For rejected attempts, entries are at the warning level.

Note: Log targets accepts log entries at a configured level. A log target accepts
only entries at or above the configured level. Setting this level too high
might not capture the desired log entries. Setting this level too low might
create too many log entries.

Defining logging for authorizations

By default, logging of authorized access attempts is enabled. Entries are logged at
the information level.

To change the level for the entry, select that level from the Log Level for Allowed
Access Attempts list.

To disable logging, change the setting of Enable Logging of Allowed Access

Attempts to off.

Defining logging for rejections

By default, logging of rejected access attempts is enabled. Entries are logged at the
warning level.

To change the level for the entry, select that level from the Log Level for Rejected
Access Attempts list.

To disable logging, change the setting of Enable Logging of Rejected Access

Attempts to off.

Running a custom style sheet

To run the actions that are defined in a custom style sheet, use the following
procedure:
1. Change the setting of Run Custom Post Processing Stylesheet to on. The
WebGUI displays additional fields.
2. Specify the location of the custom style sheet in the Specify a URL field.
v If the resource is stored in the local: or store: directory, select the resource.
v If the resource is remote to the local: or store directory, specify the location of
the resource.
v If the resource is stored on the WebGUI workstation, click Upload to transfer
the file.
v If the resource is stored on a remote server, click Fetch to transfer the file.

Generating a SAML assertion

During post processing, the AAA Policy can generate a SAML assertion that
contains a SAML authentication statement for the authenticated user identity. The
message that is sent to the server is placed in a SOAP envelop whose header
contains the generated SAML assertions.

The AAA Policy supports SAML versions 1.0, 1.1, and 2.0. The version determines
the protocol level of SAML messages. The version affects the extraction of the
identity from the original message and the format of messages.

If a custom style sheet successfully generates a SAML assertion, this post

processing activity will not generate additional SAML assertions.

To generate a SAML assertion, use the following procedure:

Chapter 6. Defining an AAA Policy 195

 1. Change the setting of Generate a SAML assertion to on. The WebGUI displays
additional fields.
2. Select the version from the SAML Version list.
3. Type the assertion originator in the Issuer Identity in SAML Assertion field.
4. Optionally type the value for the name qualifier attribute in the Name
Qualifier Attribute Value field. This value provides a name qualifier as defined
in Section 2.4.2.2 of Assertions and Protocol for the OASIS Security Assertion
Markup Language (SAML) V1.1.
5. Optionally define the key-certificate pair to generate digital signatures.
a. Select a Crypto Key from the SAML message signing key list.
b. Select a Crypto Certificate from the SAML message signing certificate list.

Including an AP-REQ token to act as Kerberos client

When the DataPower appliance acts as a gateway to a Kerberos-secured network,
the appliance can act as an authorized Kerberos client. When enabled, the
appliance:
1. Obtains a Kerberos ticket from the Kerberos Key Distribution Center (KDC).
2. Includes the Kerberos ticket that attests to the authenticity of the requesting
client. The WS-Security header includes an AP-REQ BinarySecurityToken for
the client and server principals.
3. Transmits the ticket with the authorized client request to the target server.

To have the DataPower appliance act as an authorized Kerberos client, use the
following procedure:
1. Change the setting of Include a WS-Security Kerberos AP-REQ Token to on.
The WebGUI displays additional fields.
2. Type the name part of the client identity in the Kerberos client principal field.
The client name is in the cname field of the unencrypted portion of the Kerberos
ticket.
3. Type the location of the Kerberos keytab file in the Kerberos client keytab
field.
4. Type the name part of the server identity in the Kerberos server principal
field. The server name is in the sname field of the unencrypted portion of the
Kerberos ticket.
5. Select the value type of the token from the Value Type for generated Kerberos
BinarySecurityToken list. The default is 1.1 (GSS).

Processing a WS-Trust SecurityContextToken request

For a valid WS-Trust SecurityContextToken (SCT) request, the AAA Policy can
generate the appropriate security token response. This processing works as an
on-box WS-Trust Secure Token Service (STS) that is backed by
WS-SecureConversation.

The WS-Trust token requires a symmetric shared secret key to initialize the security
context. This processing can handle Issue, Renew, Validate, and Cancel operations
against a request security token or request security token collection. You can define
the renewal behavior. During a token renewal, the processing locates
<wst:RenewTarget> and updates the referenced <wsc:SecurityContextToken> token
by resetting its created time. The renewed token is returned in the response
message.

196 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
To generate a WS-Trust token, use the following procedure:
1. Change the setting of Process WS-Trust SCT STS Request to on. The WebGUI
displays additional fields.
2. Determine whether to place the generated token in the SOAP body or as a
SOAP header.
v To place the token in the SOAP body, retain the setting of Return the
WS-Trust Token as SOAP Header. The generated token is in the
wst:RequestSecurityTokenResponse element.
v To return the token as a SOAP header, change the setting of Return the
WS-Trust Token as SOAP Header to on. The generated token is the
wst:RequestSecurityTokenResponse element but is wrapped in a
wst:IssuedToken element.
3. Type of validity duration in seconds for the SCT in the Security Context
Validity field.
v A negative integer makes the token never expire.
v A value of 0 uses the value of the var://system/AAA/defaultexpiry variable.
If not defined, the default is 14400 (4 hours)
v A positive integer makes the token after the specified duration.
The default is 0.
4. Determine whether to generate a WS-Trust token timestamp.
To generate the timestamp, retain the setting of Output WS-Trust Token
Timestamp. Otherwise, change the setting to off.
5. Select the source for the required symmetric shared key from the Source of
Shared Secret to Initialize Security Context list:
Use WS-Trust Client Entropy
The request message contains <wst:Entropy> with a Base64 encoded
binary or encrypted key that is used to initialize the security context.
Decrypt the Encrypted Key from Message
The request message contains an encrypted key from the client. The
STS can use the decrypted key to initialize the security context.
The Authenticated Kerberos Session Key
The request message contains a Kerberos token and the Kerberos
session key that can be used to initialize the security context.
Generate a Random Key
(Default) The STS generates a random key as the shared secret to
initialize the security context. The shared secret key is returned to the
client as <wst:RequestedProofToken>.
Use Static Shared Secret Object
The client and the STS have an out-of-band agreement to use a shared
secret key to initialize the security context. Although you can use a
static shared secret key, this method is less secure than the other
methods. If you select this method, the same shared secret key
initializes every security context.
6. If you selected Use Static Shared Secret Object, select a Shared Secret Key
from the Shared Secret Key list.
7. Determine how to process a WS-Trust request with a renew operation. If the
initial issue operation stated that tokens cannot be renewed, this setting is
ignored. When a token is renewed,
v To allow the renew operation and define the behavior:

Chapter 6. Defining an AAA Policy 197

 a. Change the setting of Allow WS-Trust Token Renewal to on. The
WebGUI displays additional fields.
b. Type the number of seconds to allow the STS to keep the expired security
context. After a token expires and is removed from the STS, it cannot be
renewed. Use a value in the range of 0 through 2678400 (31 days). The
default is 0.
c. Determine whether to create a new SCT instance.
To create a new instance:
1) Change the setting of Issue new Instance for WS-Trust Renewal to
on. The new instance uses the defined expiry setting.
2) Determine the source of the key material.
- To use the existing key material, retain the setting of Update
Context Key for WS-Trust Renewal.
- To use a randomly generated string, change the setting of
Update Context Key for WS-Trust Renewal to on.
To modify the existing instance, retain the setting of Issue new
Instance for WS-Trust Renewal
v To deny the renew operation, retain the setting of Allow WS-Trust Token
Renewal.
8. If you selected any method except Use Static Shared Secret Object from the
Source of Shared Secret to Initialize Security Context list, select the certificate
to encrypt the initial shared secret from the WS-Trust Encryption Key
Certificate list.

Adding a WS-Security UsernameToken

The AAA Policy can add the WS-Security UsernameToken to the message that is
forwarded to the server. The AAA Policy uses the user name and password from
the Mapped Credentials stage.

To add a WS-Security UsernameToken, use the following procedure:

1. Change the setting of Add WS-Security UsernameToken to on. The WebGUI
displays additional fields.
2. Optionally change the setting of Replace existing username token to on.
Enabling this option causes the generated token to replace any existing one.
The default is to retain the original token.
3. Type the identifier for the SOAP 1.1 actor or SOAP 1.2 role in processing a
WS-Security security header in the Actor/Role identifier field. This is effective
only when a SOAP message is being used for WS-Security 1.0 or 1.1. Use one
of the following well-known values:
http://schemas.xmlsoap.org/soap/actor/next
Everyone, including the intermediary and ultimate receiver, receives the
message and should be able to process the security header.
http://www.w3.org/2003/05/soap-envelope/role/none
No one should process the security header.
http://www.w3.org/2003/05/soap-envelope/role/next
Everyone, including the intermediary and ultimate receiver, receives the
message and should be able to process the security header.
http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
(Default) The ultimate receiver can process the security header.

198 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Blank or an empty string
No actor/role identifier is configured. The ultimate receiver is assumed
when processing the message, and no actor/role attribute is added when
generating the security header.

Note: There should not be more than one security header that omit the
actor/role identifier.
USE_MESSAGE_BASE_URI
Indicates that the actor/role identifier will be the base URI of the
message. If the SOAP message is transported using HTTP, the base URI is
the request-URI of the HTTP request.
Any other string
Indicates the actor or role of the security header.
4. Select whether to include the password in the token.
v To include the password:
a. Retain the default setting of Include Password.
b. Select the type of from the WS-Security UsernameToken Password Type
list.
Text The actual password for the user name, the password hash, or a
derived password.
Digest
(Default) The digest of the password as specified in the Web Services
Security: UsernameToken Profile 1.0.
v To exclude the password:
a. Change the setting of Include Password to off.
b. Select whether to use the Derived-Key variant. If enabled, adds a
WS-Security Derived-Key UsernameToken to the message and adds an
HMAC signature using the derived-key.
To use the variant:
1) Change the setting of Use Derived-Key variant of WS-Security
UsernameToken to on.
2) Type the number of rounds of hashing to use when generating a
derived key from a password in the Hashing iteration count field.
The minimum value is 2. The default is 1000.
3) Select the HMAC signing algorithm from the HMAC Signing
Algorithm list. The default is hmac-sha1.
4) Select the Message Digest algorithm from the Signing Message
Digest Algorithm list. The default is sha1.
To not use the variant, retain the setting of Use Derived-Key variant
of WS-Security UsernameToken.

Generating an LTPA token

The AAA Policy can generate an LTPA token and add it to the HTTP headers that
are sent to the server. To generate the token and add it to the headers, use the
following procedure:
1. Change the setting of Generate an LTPA Token to on. The WebGUI displays
additional fields.
2. Select the LTPA format from the LTPA Versions list.

Chapter 6. Defining an AAA Policy 199

 Domino LTPA
Used in Lotus Domino environments.
WebSphere Version 1 LTPA
Used in WebSphere environments.
WebSphere Version 2 LTPA
(Default) Used in WebSphere environments. This version was introduced
in WebSphere Application Server for z/OS version 5.1.0.2; for other
platforms, version 5.1.1.
WebSphere LTPA tokens can contain an extended attribute field. This field
consists of an arbitrary list of name-value pairs that can transmit information
about the cookie subject to applications that can decrypt the cookie. This type
of information can identify which server authenticated the user or specify
user-associated LDAP attributes. To add name-value pairs, refer to Adding
LTPA user attributes on page 265.
3. Type the name of the key file in the LTPA Key File field. This file contains the
cipher keys used for encryption and decryption.
4. Type the cleartext password for the key file in the LTPA Key File Password
field.
5. Type the lifetime for the token in the LTPA Token Expiry field. The lifetime is
the number of seconds from the cookie creation to its expiration. The default is
600.
6. Select whether to wrap the token in the standard <Security/> WS-Security
header. The generation of an LTPA token might not include this WS-Security
header.
To wrap the token, change the setting of Wrap Token in a WS-Security
Security Header to on. Otherwise, retain the default setting.

Generating a Kerberos SPNEGO token

The AAA Policy can generate a Kerberos SPNEGO token and add it to the HTTP
headers that are sent to the server. For information about SPNEGO, refer to
Understanding SPNEGO.

To generate the token, use the following procedure:

1. Change the setting of Generate a Kerberos SPNEGO Token to on. The
WebGUI displays additional fields.
2. Type the name part of the client identity in the Kerberos client principal field.
The client name is contained in the cname field of the unencrypted portion of
the Kerberos ticket.
3. Type the location of the Kerberos keytab file in the Kerberos client keytab
field.
4. Type the name part of the server identity in the Kerberos server principal
field. The server name is contained in the sname field of the unencrypted
portion of the Kerberos ticket.

Requesting a TFIM token map

The AAA Policy can request a TFIM token map.

To request a TFIM token map, use the following procedure:

1. Change the setting of Request TFIM Token Map to on. The WebGUI displays
additional fields.
2. Select a TFIM configuration from the TFIM Configuration list.

200 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 7. Managing files
The appliance contains no hard drive for file storage. As a result, the storage space
for files and other artifacts is limited.

Directories on the appliance

The file system contains many examples and critical configuration files. These
directories and their contents are as follows:
audit: This directory contains the audit logs. Each appliance contains only one
audit: directory. This directory cannot be the destination of a copy. This
directory is available from the command line in the default domain only.
To view the audit log from the WebGUI, select Status View Logs Audit
Log.
cert: This encrypted directory contains private key and certificate files that
services use in the domain. You can add, delete, and view files, but you
cannot modify these files while in the domain. Each application domain
contains one cert: directory. This directory is not shared across domains.
chkpoints:
This directory contains the configuration checkpoint files for the appliance.
Each application domain contains one chkpoints: directory. This directory
is not shared across domains.
config:
This directory contains the configuration files for the appliance. Each
application domain contains one config: directory. This directory is not
shared across domains.
dpcert:
This encrypted directory contains files that the appliance itself uses. This
directory is available from the command line in the default domain only.
export:
This directory contains the exported configurations that are created with
the Export Configuration utility. Each application domain contains one
export: directory. This directory is not shared across domains.
image: This directory contains the firmware images (primary and secondary) for
the appliance. This directory is where firmware images are stored typically
during an upload or fetch operation. Each appliance contains only one
image: directory. This directory is available in the default domain only.
local: This directory contains miscellaneous files that are used by the services
within the domain, such as XSL, XSD, and WSDL files. Each application
domain contains one local: directory. This directory can be made visible to
other domains. When viewed from other domains, the directory name
changes from local: to the name of the application domain.
logstore:
This directory contains log files that are stored for future reference.
Typically, the logging targets use the logtemp: directory for active logs. You
can move log files to the logstore: directory. Each application domain
contains one logstore: directory. This directory is not shared across
domains.

Copyright IBM Corp. 2002, 2009 201

 logtemp:
This directory is the default location of log files, such as the
appliance-wide default log. This directory can hold only 13 MB. This
directory cannot be the destination of a copy. Each application domain
contains one logtemp: directory. This directory is not shared across
domains.
pubcert:
This encrypted directory contains the security certificates that are used
commonly by Web browsers. These certificates are used to establish
security credentials. Each appliance contains only one pubcert: directory.
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. However, you must be in default
domain to create or upload keys and certificates.
store: This directory contains example style sheets, default style sheets, and
schemas that are used by the local 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. You can make changes to the contents of this
directory from the default domain only.
The store: directory has the following subdirectories:
meta This encrypted subdirectory contains files that are used by the
appliance itself.
msgcat
This subdirectory contains the message catalogs.
policies
This subdirectory contains the following subdirectories. The
contents of these subdirectories affect Web services policy.
custom
This subdirectory contains custom style sheets.
mappings
This subdirectory contains mapping style sheets.
templates
This subdirectory contains XML files.
profiles
This subdirectory contains style sheets that are used by DataPower
services.
schemas
This subdirectory contains schemas that are used by DataPower
services.
dp This encrypted subdirectory contains files that are used by the
appliance itself. This subdirectory is available from the command
line only.

202 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 pubcerts
This encrypted subdirectory contains files that are used by the
appliance itself. This subdirectory is available from the command
line only.
tasktemplates:
This directory contains the XSL files that define the display of specialized
WebGUI screens. Each appliance contains only one tasktemplates: directory.
This directory is visible to the default domain only.
temporary:
This directory is used as temporary disk space by processing rules. Each
application domain contains one temporary: directory. This directory is not
shared across domains.

Launching the File Management utility

To manage files, launch the File Management utility with one of the following
methods:
v Select the File Management icon from the Files and Administration section of
the Control Panel.
v Select Administration Main File Management.

Either method displays the File Management screen. The initial screen shows the
top level directories.

Displaying directory contents

To display (expand) the contents of a directory, perform the following procedure:
1. Launch the File Management utility. Refer to Launching the File Management
utility for details.
2. Select the directory to display its contents.

To hide (collapse) the content-view of a directory, select that directory again.

Creating a subdirectory
Subdirectories can only be creates under the local: directory or one of its
subdirectories.

Follow these steps to create a subdirectory under the local: directory or one of its
subdirectories:
1. Launch the File Management utility. Refer to Launching the File Management
utility for details.
2. From the Action column, click Actions aligned with the directory for the
subdirectory to be created.
3. Click Create Subdirectory. The File Management screen displays.
4. Enter the name of the new subdirectory in the directory Name field.
5. Click Confirm Create. The File Management screen refreshes.
6. Click Continue. The File Management screen displays the top-level directories
only.

Chapter 7. Managing files 203

Deleting a directory
Directories can only be deleted in the local: directory or one of its subdirectories.

Follow these steps to delete a directory under the local: directory or one of its
subdirectories:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. From the Action column, click Actions aligned with the directory to be deleted.
3. Click Delete Directory. The File Management screen displays.
4. Click Confirm Delete. The File Management screen refreshes.
5. Click Continue. The File Management screen displays the top-level directories
only.

Refreshing directory contents

To refresh contents, click the Refresh Page icon. The WebGUI redraws the File
Management screen. The screen displays the top-level directories only.

Uploading files from the workstation

Use the following procedure to upload a file from your workstation to the
appliance:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory into which you want to upload the file.
3. Click Actions in that row to open the Directory Actions menu.
4. Click Upload Files to display the File Upload screen.
5. Specify the path-qualified name of the workstation file in the File to upload
field, or click Browse to locate the file on the workstation.
6. Specify the file name in the Save as field.

Note: If you used browsing to select the file or if you navigated to this field
using the tab key, the field contains the file name.
7. To add another file to be uploaded:
a. Click Add.
b. Repeat steps 5 and 6.
8. If one of the files already exists in the selected directory and you want to
overwrite this file, check the Overwrite Existing Files check box. If you do
not select this check box and the file already exists, the file is not uploaded.
9. Click Upload.
10. When the appliance reports success (or an error is the file already existed),
click Continue to return to the File Management screen.

The target directory now contains the uploaded files. To verify, use the procedure
described in Displaying directory contents on page 203.

204 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Working with Java Key Stores
A Java Key Store (JKS) is a Sun-proprietary format file that contains private keys
and certificates. The java.security package and sub-packages access the data in
the JKS to carry out their cryptographic operations.

Required software
JKS support requires the following software on the WebGUI workstation:
v Version 1.4.2 of the Java runtime environment (j2re1.4.2)
v SDK (j2sdk1.4.2)
v Internet Explorer

Note: You must have the JRE or Java SDK /bin path name in the Windows PATH
environment variable on the WebGUI workstation. The Java Key Store file
cannot reside on any of the local directories. It must be uploaded from a
workstation.

Granting permissions
In addition, the user must have the grant permission for the upload in the
.java.policy file on the workstation that contains the Java Key Store files. The
following example .java.policy file should be defined on the workstation
computer before starting the upload:
grant {
permission java.io.FilePermission "<<ALL FILES>>","read";
permission java.util.PropertyPermission "*", "read";
permission java.lang.RuntimePermission "accessClassInPackage.sun.*";
};

You can grant read-only permission to the JKS file.

Types of key stores

Sun offers two common methods to support key store creation:
v Sun Java 2.1.4.2 runtime environment or SDK use a program called keytool to
create and manage a JKS-type file store with no provider name.
v SunJCE (Java Crypto Extension) generates a JCEKS-type (Java Crypto Extension
Key Store) file store with the provider name SunJCE.

You must know the key store type to successfully upload files from a JKS.

Uploading a file from a Java Key Store

Use the following procedure to upload a file from a Java Key Store (JKS) to the
appliance:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory into which you want to upload the file.
3. Click Actions in that row to open the Directory Actions menu.
4. Click Upload Files to display the File Upload screen.
5. Click the Java Key Store radio button to display the JKS Upload screen.

Note: When you click the Java Key Store radio button, the Java Console of
the browser opens and shows whether the Java Key Store Access

Chapter 7. Managing files 205

 Applet is running. If the applet cannot be accessed, you cannot upload
JKS files. Ensure that your browser is enabled to use the Java 1.4.2
applet.
6. Specify the full path to the target JKS in the Java key store field or click
Browse.
7. Specify JKS or JCEKS (the JKS type) in the Key store type field.
8. If the type is JCEKS, specify SunJCE (the provider name) in the Key store
provider field. Otherwise, leave blank.
9. Specify the JKS password in the Key store password field.
10. Identify the files to upload with the Key to upload list. Use the Refresh
button, if necessary.
11. Specify the key-specific password in the Key password field.
12. Specify the file name in the Save as field.
13. If the file already exists in the selected directory and you want to overwrite
this file, check the Overwrite Existing Files check box. If you do not select
this check box and the file already exists, the file is not uploaded.
14. Click Upload.
15. When the appliance reports success, click Continue to return to the File
Management screen.

The target directory now contains the uploaded key or certificate. To verify that the
file exists, use the procedure described in Displaying directory contents on page
203.

If the upload fails, look at the Java Console of the browser to determine whether
an exception was thrown.

Fetching files
Use the following procedure to retrieve a file from a remote URL (fetch) and store
that file in a specified directory on the appliance:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory into which you want to upload the file.
3. Click Actions in that row to open the Directory Actions menu.
4. Click Fetch Files to display the Fetch File screen.
5. Specify the location of the file in the Source URL field.
6. Specify the file name in the Save as field.
7. If the file already exists in the selected directory and you want to overwrite this
file, check the Overwrite Existing Files check box. If you do not select this
check box and the file already exists, the file is not uploaded.
8. Click Fetch.
9. When the appliance reports success, click Continue to return to the File
Management screen.

The target directory now contains the retrieved file. To verify, use the procedure
described in Displaying directory contents on page 203.

Copying files
Use the following procedure to copy a file from one directory to another:

206 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the files to be copied.
3. Select files by clicking the box adjacent to the file name.
4. Scroll to the top or bottom of the screen and click Copy to display the File
Copy screen.
5. From the New Directory Name list, select the target directory.
6. Specify the name for the file, if different, in the New File Name field.
7. If one of the selected files already exists in its associated target directory and
you want to overwrite this file, check the Overwrite Existing Files check box. If
you do not select this check box and the file already exists, the file is not
copied.
8. Click Confirm Copy to copy the files to the target directories.
9. When the appliance reports success, click Continue to return to the File
Management screen.

The target directories now contain the copied files. To verify that the files exist, use
the procedure described in Displaying directory contents on page 203.

Renaming files
Use the following procedure to rename a file:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the files to be copied.
3. Select files by clicking the box adjacent to the file name.
4. Click Rename to display the File Rename screen.
5. Specify the name of the file in the New File Name field.
6. If one of the selected files already exists in the target directory and you want to
overwrite this file, check the Overwrite Existing Files check box. If you do not
select this check box and the file already exists, the file is not copied.
7. Click Confirm Rename.
8. When the appliance reports success, click Continue to return to the File
Management screen.

The target directories now contain the renamed files. To verify that the files exist,
use the procedure described in Displaying directory contents on page 203.

Moving files
Use the following procedure to move a file from one directory to another:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the files to be moved.
3. Select files by clicking the box adjacent to the file name.
4. Click Move to display the Move File screen.
5. From the New Directory list, select the target directory.
6. If one of the selected files already exists in its directory and you want to
overwrite this file, select the Overwrite Existing Files check box. If you do not
select this check box and the file already exists, the file is not moved.

Chapter 7. Managing files 207

 7. Click Confirm Move.
8. When the appliance reports success, click Continue to return to the File
Management screen.

The target directories now contain the moved files. To verify that the files exist, use
the procedure described in Displaying directory contents on page 203.

Viewing files
Use the following procedure to view a text file:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the file.
3. Click the file to open a browser that contains the file.

When finished viewing the file, close the browser.

Editing files
Use the following procedure to edit a text file:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the files to be edited.
3. Select the file to be edited by clicking Edit in the row that is associated with
that file. The WebGUI displays a file preview.
4. Click Edit to change to Edit Mode.
5. Edit the file as required.
6. Click Submit to complete the edit process.
7. When the appliance reports success, click Close to return to the File
Management screen.

Deleting files
Use the following procedure to delete a file:
1. Launch the File Management utility. Refer to Launching the File Management
utility on page 203 for details.
2. Navigate to the directory that contains the files to be deleted.
3. Select files by clicking the box adjacent to the file name.
4. Scroll to the top or bottom of the screen and click Delete to display the Delete
File screen.
5. Click Confirm Delete to delete the files.
6. When the appliance reports success, click Continue to return to the File
Management screen.

The selected files were deleted. To verify that the files no longer exist, use the
procedure described in Displaying directory contents on page 203.

208 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 8. Managing the configuration of the appliance
This chapter provide information about managing the configuration of application
domains and importing and exporting configurations.

Creating Include Configuration File objects

Include Configuration File objects allow you to include configuration information
from an external configuration file in the local configuration information. This
external file can be stored on a centralized configuration server or another
DataPower appliance. The information in the Include Configuration File object is
appended to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart).

An Include Configuration File object can include configuration information only.

On the other hand, an Import Configuration File object is a configuration package
that can include both configuration information and supporting files.

To append configuration information from an external file to the local

configuration information, perform the following procedure:
1. Select Objects Configuration Management Include Configuration File to
display the catalog.
2. Click the name of an existing Include Configuration File object to edit it, or
click Add to create a new one. The Include Configuration File configuration
screen is displayed.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the URL of the configuration file in the URL of Configuration File
field. For example, specify https://config.server.com/datapower/
firewalls.cfg.
7. Use the Execute on Startup toggle to indicate whether to import the
configuration package at startup.
on (Default) Imports the configuration package at startup. The
configuration is marked external and cannot be saved to the startup
configuration. This behavior is equivalent to always importing the
configuration.
off Imports the configuration package when manually triggered. The
configuration is not marked external and can be saved to the startup
configuration. This behavior is equivalent to importing the
configuration one time.
8. When retrieving the configuration file, select when to retrieve the
configuration file with the Interface Detection toggle.
on Retrieves the configuration file after the local interface is up.
off (Default) Retrieves the configuration file at appliance reload without
waiting for the local interface to be up.

Copyright IBM Corp. 2002, 2009 209

 9. Click Apply to save the object to the running configuration.
10. Optionally, click Save Config to save the object to the startup configuration.

Note: Unless you click Save Config, the included configuration file will not take
affect when the appliance is started.

Creating Import Configuration File objects

Import Configuration File objects allow you to import a configuration package
from an external configuration file into the local configuration information. The
external file can be stored on a centralized configuration server or another
DataPower appliance. The configuration data and files in the configuration file is
added to the local configuration information when the configuration of the
DataPower appliance is reloaded (such as during appliance reboot, firmware
reload, or domain restart). The default configuration of an Import Configuration
File object does not provide warnings about conflicts with existing files and
objects.

An Import Configuration File object is a configuration package that can include

both configuration information and supporting files. On the other hand, an Include
Configuration File object can include configuration information only.

To import a configuration package from an external file to the local configuration

information, perform the following procedure:
1. Select Objects Configuration Management Import Configuration File to
display the catalog.
2. Click the name of an existing configuration package to edit it, or click Add to
create a new one. The Import Configuration File configuration screen is
displayed.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the URL of the configuration package in the URL of Configuration
Package field. For example, specify https://config.server.com/datapower/
firewalls.zip.

Note: You cannot use the SCP or SFTP protocol to retrieve a configuration
package. All other URL protocols are available; for example, HTTP,
HTTPS, or FTP.
7. Select the package format from the Format of Configuration Package list.
ZIP (Default) Indicates that the configuration package is in ZIP format. If
the format is ZIP, the bundle is unzipped automatically.
XML Indicates that the configuration package in XML format.
8. Use the Overwrite Files toggle to control the overwrite behavior.
on (Default) Overwrites files of the same name.
off Does not import the file if a file of the same name exists.
9. Use the Overwrite Objects toggle to control the overwrite behavior.
on (Default) Overwrites objects of the same name.
off Does not import the objects if an objects of the same name exists.

210 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 10. (Optional) Select a deployment policy that preprocesses the configuration
package from the Deployment Policy list. For more information, refer to
Configuring deployment policies on page 222.
11. Use the Local IP Rewrite toggle to indicate whether to rewrite local IP
addresses on import.
on (Default) Rewrites IP addresses to match the local configuration when
imported. For example, a service in the configuration package that
binds to eth1 is rewritten to bind to eth1 when imported.
off Retains the original IP address in the configuration package.
12. Use the Import on Startup toggle to indicate whether to import the
configuration package at startup.
on (Default) Imports the configuration package at startup. The
configuration is marked external and cannot be saved to the startup
configuration. This behavior is equivalent to always importing the
configuration.
off Imports the configuration package when manually triggered. The
configuration is not marked external and can be saved to the startup
configuration. This behavior is equivalent to importing the
configuration one time.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

Backing up and exporting configuration data

The backup and export utility copies specified configuration data from the
appliance to a file in the export: directory. You can optionally download the file to
your workstation.

Note: Exported configuration data should not be imported to an appliance with an

earlier release level. Between releases, configuration data for properties can
change. If you attempt to import configuration data from an appliance of a
later release level into an appliance of an earlier release level, the operation
might report success, but the configuration data might not be the same.
Therefore, use this utility to exchange configuration data among appliances
of the same release level.

You can use this utility to perform the following operations:

v Create a backup of the entire appliance
v Create a backup of one or more application domains
v Export select objects from the current domain
v Copy or move select objects between domains

Note: The following objects are never exported:

v User account objects
v Certificate objects
v Key objects (HSM appliances only)

The following files are never exported:

v Log files
v Firmware files

Chapter 8. Managing the configuration of the appliance 211

 To ensure that all other objects and files are exported, use the admin account.
For any other user, only objects and files that are accessible to that user are
included in the export package.

To start a back up or export operation, select Administration Configuration

Export Configuration to display the initial Export Configuration screen. This
screen provides the following export options:
v Create a backup of the entire system
v Create a backup of one or more application domains
v Export configuration and files from the current domain
v Copy or move configuration and files between domains

Backing up the entire appliance

Use the following procedure to back up (export) all configuration data for the
appliance.
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Create a backup of the entire system and click Next to display the File
Name screen.
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.zip). If a file of this name exists
in the export: directory, it is overwritten.
d. Click Next. The configuration of the entire appliance is backed up.
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.

Note: The Import Configuration utility requires that the export file resides on your
workstation.
3. Optionally click Download to download the file to your workstation.
4. Click Done to close this window and return to the Control Panel.

The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Backing up domains
Best practice is to periodically back up all domains individually.

To back up configuration information for one or more application domains, follow

this procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Create a backup of one or more application domains and click Next to
display the selection screen.
3. Provide the following inputs:
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.

212 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 c. The Export File Name defaults to export (.zip). If a file of this name exists
in the export: directory, it is overwritten.
d. Select the check boxes adjacent to each domain to export.
e. Click Next
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.

Note: The Import Configuration utility requires that the export file resides on your
workstation.
4. Optionally click Download to download the file to your workstation.
5. Click Done to close this window and return to the Control Panel.

The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Exporting select objects

The Export Configuration utility remains available from the initial Export
Configuration screen. To export select objects and files, use the following
procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Export configuration and files from the current domain and click Next
to display the Export Configuration screen.
3. Provide the following inputs:
a. Specify a descriptive object-specific summary in the Comment field.
b. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
c. The Export File Name defaults to export (.xml or .zip depending on the
selected export format). If a file of this name exists in the export: directory,
it is overwritten.
d. Use the To radio buttons to specify the export format.
XML Config
Exports configuration data as XML files. Include Configuration files
are referenced in the XML document only, they are not included.
ZIP Bundle
Exports configuration data in compressed ZIP format. Include
Configuration files are in the bundle.
e. Use the Configuration radio button to specify the data to export.
Currently running configuration
Exports the configuration data from the running configuration, not
the startup configuration.
Last persisted configuration
Exports the configuration data from the startup configuration, not
the current running configuration.
f. Use the Referenced Objects radio buttons to specify the scope of the data to
export.
Include only the selected base objects
Exports only the configuration data for the selected objects.

Chapter 8. Managing the configuration of the appliance 213

 Include all objects required by selected base objects
Exports configuration data for the selected objects and all objects
that are required by the selected objects. For example, if exporting an
XSL Proxy, the export includes configuration data for the XSL Proxy,
the assigned XML manager, and all associated matching rules,
processing policies, processing rules, cryptographic certificates,
credentials, and keys.
g. Use the Export Files radio buttons to specify the scope of the data to
export.
Export no files
No files are included in the export. If, for example, the selected
objects use files, such as a style sheet, those files are not included.
This option is useful when the configuration data itself is all that is
needed.
Export files referenced by exported objects
In addition to the selected objects (and possibly referenced objects),
exports public files that are associated with the selected objects.

Note: The export does not include private files. These files are in the
cert: and sharedcert: directories.
Export all local files
Exports public files that are associated with the selected objects and
all files that are in the following directories:
v config:
v local:
v pubcert:
v store:
v tasktemplates:
h. From the Objects list, select the type or class of configuration data to
export.
After selecting an entry, all instances of that type or class are listed in the
left-hand box.
1) Select the objects from the left-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click > to move the selected object to the Selected Base Objects list.
i. Adjust the Selected Base Objects list, if necessary.
1) Select objects in the right-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click < to remove the selected objects or click <<to remove all objects
from the Selected Base Objects list.
j. Click Show Contents at any time to display all contents marked for
inclusion in the export.
k. Click Next.
When the backup completes, the file is in the export: directory. You can optionally
download the export file to your workstation.

Note: The Import Configuration utility requires that the export file resides on your
workstation.
4. Optionally click Download to download the file to your workstation.
5. Click Done to close this window and return to the Control Panel.

214 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 The export file can be accessed from the export: directory. If downloaded, the
export file is on your workstation.

Copying or moving select objects

The copy or move utility is available from the initial Export Configuration screen.
To copy or move selected objects and files, use the following procedure:
1. Select Administration Configuration Export Configuration to display the
Initial Export Configuration screen.
2. Select Copy or move configuration and files between domains and click Next
to display the Export Configuration screen.
a. Optionally create or select the name of a Deployment Policy to accept, filter,
or modify a configuration during import.
b. Use the Delete After Export toggle to indicate whether the operation is a
copy operation or a move operation.
on Indicates a move operation.
off Indicates a copy operation.
c. Use the Configuration radio button to specify the data to export.
Currently running configuration
Exports the configuration data from the running configuration, not
the startup configuration.
Last persisted configuration
Exports the configuration data from the startup configuration, not
the current running configuration.
d. Use the Referenced Objects radio buttons to specify the scope of the data
to export.
Include only the selected base objects
Exports only the configuration data for the selected objects.
Include all objects required by selected base objects
Exports configuration data for the selected objects and all objects
that are required by the selected objects. For example, if exporting
an XSL Proxy, the export includes configuration data for the XSL
Proxy, the assigned XML manager, and all associated matching
rules, processing policies, processing rules, cryptographic
certificates, credentials, and keys.
e. Use the Export Files radio buttons to specify the scope of the data to
export.
Export no files
No files are included in the export. If, for example, the selected
objects use files, such as a style sheet, those files are not included.
This option is useful when the configuration data itself is all that is
needed.
Export files referenced by exported objects
In addition to the selected objects (and possibly referenced objects),
exports public files that are associated with the selected objects.

Note: The export does not include private files. These files are in the
cert: and sharedcert: directories.

Chapter 8. Managing the configuration of the appliance 215

 Export all local files
Exports public files associated with the selected objects and all files
contained in the following directories:
v config:
v image:
v pubcert:
v store:
v tasktemplates:
f. From the Objects list, select the type or class of configuration data to export.
After selecting an entry, all instances of that type or class are listed in the
left-hand box.
1) Select the objects from the left-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click the > button to move the selected objects to the Selected Base
Objects list.
g. Adjust the Selected Base Objects list, if necessary.
1) Select objects in the right-hand list. To select multiple objects, select
objects in combination with the Shift and Control keys.
2) Click < to remove the selected objects or click <<to remove all objects
from the Selected Base Objects list.
3. Click Show Contents at any time to display all contents marked for inclusion
in the export.
4. Click Next to display the Import File window.
a. From the Domain list, select the domain where the configuration data is to
imported.
b. Click Import to initiate file transfer.
5. Respond to WebGUI prompts.
6. Click Done to close the Import File screen.

Managing configuration checkpoints

A configuration checkpoint contains configuration data from a specific point in
time. The configuration checkpoint might be equivalent to the persistent
configuration, might be equivalent to the running configuration, or might be
different from the persisted configuration or running configuration.

Within each application domain, the administrator who is associated with the
admin account defines the number of configuration checkpoints to allow. You can
save up to the allowed number of configuration checkpoints.

When saved, a ZIP formatted file for the configuration checkpoint is written the
chkpoints: directory for that application domain.

Defining number configuration checkpoints to allow

The administrator who is associated with the admin account can define the number
of checkpoint configurations to allow for each application domain. To define the
number of checkpoint to allow for an existing domain, use the following
procedure:
1. Select Administration Configuration Application Domain to display the
Application Domain catalog.

216 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 2. Select the specific application domain to open the domain-specific configuration
screen.
3. Select the Configuration tab.
4. Specify the number of checkpoint configuration to allow in the Configuration
Checkpoint Limit field. Use an integer in the range of 1 through 5. The default
is 3.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Saving configuration checkpoints

Do not click Save Config to save a configuration checkpoint. This button does not
allow you the option of saving a configuration checkpoint.

To save a configuration checkpoint, use the following procedure:

1. Select Administration Configuration Configuration Checkpoints.
2. Specify the name of the configuration checkpoint in the Checkpoint Name
field.
3. Click Save Checkpoint.
4. Respond to WebGUI prompts.

A ZIP-formatted configuration file of the specified name is written to the

chkpoints: directory.

You cannot overwrite a configuration checkpoint. You must first delete the original
configuration checkpoint before saving a new configuration checkpoint of the same
name. For details, refer to Deleting configuration checkpoints on page 218.

Listing configuration checkpoints

You can view the list of saved configuration checkpoint in one of the following
ways:
v From the Configuration Checkpoints screen
v From the File Management screen

Listing from the Configuration Checkpoints screen

To view from the Configuration Checkpoints screen, select Administration
Configuration Configuration Checkpoints. This screen displays the list of saved
configuration checkpoints at the time by name and timestamp.

This section of the screen provides the following actions:

Rollback
Loads the configuration that is defined in the configuration checkpoint.
Remove
Deletes the checkpoint configuration from the chkpoints: directory.
Compare
Launches the Compare Configuration utility. For details, refer to
Comparing configurations on page 220.

Listing from the File Management utility

To view from the File Management utility, use the following procedure:
1. Select the File Management icon from the Control Panel.
2. Expand the chkpoints: directory.

Chapter 8. Managing the configuration of the appliance 217

 Rolling back to a configuration checkpoint
To load the configuration that is defined in the configuration checkpoint, use the
following procedure:
1. Select Administration Configuration Configuration Checkpoints. This
screen displays the list of saved configuration checkpoints at the time by name
and timestamp.
2. Click Rollback.
3. Respond to WebGUI prompts.

Deleting configuration checkpoints

You can delete configuration checkpoint in one of the following ways:
v From the Configuration Checkpoints screen
v From the File Management screen

Deleting from the Configuration Checkpoints screen

To delete from the Configuration Checkpoints screen, use the following procedure:
1. Select Administration Configuration Configuration Checkpoints. This
screen displays the list of saved configuration checkpoints at the time by name
and timestamp.
2. Click Remove.
3. Respond to WebGUI prompts.

Deleting from the File Management screen

To delete from the File Management screen, use the following procedure:
1. Select the File Management icon from the Control Panel.
2. Expand the chkpoints: directory.
3. Select the check box beside the configuration checkpoint file.
4. Click Delete.
5. Respond to WebGUI prompts.

Importing configuration data

The import utility copies specified configuration data from your workstation to the
DataPower appliance.

Note: Exported configuration data should not be imported to an appliance with an

earlier release level. Between releases, configuration data for properties can
change. If you attempt to import configuration data from an appliance of a
later release level into an appliance of an earlier release level, the operation
might report success, but the configuration data might not be the same.
Therefore, use this utility to exchange configuration data among appliances
of the same release level.

While importing a configuration, you can:

v Set the local address bindings of services contained in the export package to
match the equivalent interfaces of the local device with the Rewrite Local
Service Addresses toggle (optional).
v Add, modify or delete values in the configuration package being imported
whose values match the defined match statement in a Deployment policy with
the Use Deployment Policy list (optional).

218 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Best practice when the goal is to add, modify or delete values in a configuration
package is to use a Deployment policy while importing the configuration package.

Use the following procedure to import configuration data.

1. Select Administration Configuration Import Configuration to display the
Import Configuration window.
a. Use the From radio buttons to specify the import format.
XML Config
Imports configuration data as XML files.
ZIP Bundle
Imports configuration data in compressed ZIP format.
b. Retain the selection of the File radio button.
c. Click Browse to select the file to import.
d. Retain the selection of (none) for the Use Deployment Policy list. For more
information, refer to the Configuring deployment policies on page 222.
e. Use the Rewrite Local Service Addresses toggle to control whether to
substitute IP addresses:
on (Default) Allows local IP addresses to be rewritten.
off Does not allow local IP addresses to be rewritten.
2. Click Next to display the Select Application Domains for Import window. If
there are no objects in the configuration you are importing, skip to step 6c on
page 220.
When importing from any domain other than default, the imported
configuration applies only to the current domain. The WebGUI might display
an error message when importing data that was exported from the default
domain.
3. Select the desired domains. To select all domains, click All. To deselect selected
domains, click None. If a selected domain does not exist on the appliance, as
indicated, it will be created.
4. Click Next to display the Import Object Selection List window.
5. Select the objects to import.

Note: Click Save Config to save the configuration for each domain that
contains imported objects or files.

To effectively complete an appliance import (restore), use the admin

account. The appliance to be restored must also first be re-initialized
through the command line.
6. Click Next to display the Import Summary window, which details the contents
of the target file. In some cases, the summary might indicate differences in file
versions.

Note: Warnings can appear on this screen that alert you to a range of possible
conflicts that the imported configuration might cause. Depending on the
warning, you might want to create a new application domain, or you
might want to choose not to overwrite objects or files.
a. Select each item to overwrite. To select all item, click All. To deselect
selected items, click None. Only selected items are imported.
b. Click Import to initiate file transfer.

Chapter 8. Managing the configuration of the appliance 219

 At the completion of the import process, the WebGUI displays the Object
Import Results window, which details the results.
c. Click Done to close this window.

If more than one domain is being imported, the Import Summary window is
displayed for the next domain to import.

Managing changes in configuration data

You to create a report that lists the differences between two configurations.
Generally, the two configurations that are being compared are the persisted
configuration and the running configuration. However, you can compare either
configuration to a saved version of the configuration. These saved versions of the
configuration can be an exported configuration (XML format or ZIP format), a
backup configuration (ZIP format only), or a configuration checkpoint.

When you compare configurations, the report provides a list of objects that
changed between the two configurations and the changes that were made to these
objects. The report list how the configuration changed:
v An object was added
v An object was deleted
v An object was modified

Comparing configurations
To compare configurations, use the following procedure:
1. Select Administration Configuration Compare Configuration to display
the Configuration Comparison screen.
2. From the From list, select which configuration to be the first configuration
source; and from the To list, select which configuration to be the second
configuration source. The source for each of the configurations can be one of
the following:
Persisted Configuration
The last saved configuration on the appliance. This is the default in the
From list.
Running Configuration
The configuration that is currently running on the appliance. This is the
default in the To list.
Domain Configuration
The last saved or currently running domain configuration on the
appliance.
XML Configuration
The XML file that was created during an export operation. This file has
an .xcfg extension.
Export ZIP Bundle
A ZIP file that was created during an export operation. This file has a .zip
extension.
Backup ZIP Bundle
A ZIP file that was created during backup operation. This file has a .zip
extension.

220 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Checkpoint
A ZIP file that was created through a save checkpoint operation. This file
has a .zip extension and is in the chkpoint: directory.
3. When the source (From or To) is XML Configuration, Export ZIP Bundle, or
Backup ZIP Bundle, specify or browse for and select the configuration file.
Also, create or select a deployment Policy that can be used to accept, filter, or
modify a configuration.
4. When the source (From or To) is Checkpoint, select the checkpoint from the
Checkpoint list.
5. From the View list, select whether the report lists only changed objects between
the configurations or all objects in the configurations. The default is changed
objects only.
6. Click Run Comparison to generate the report.

The results are displayed below the horizontal rule.

Reading the change report

After running a comparison, the results are displayed below the horizontal rule.
Review the report to determine whether these changes should be saved to the
startup configuration, reverted to their original settings, saved to a configuration
checkpoint, or a combination of these operations.

Each item in the report contains the following data:

Type The object type
Name The name of the object
Property
The name of the property
From The value of the property as defined in the From source
To The value of the property as defined in the To source
Change
The type of change between the From source and the To source. The
change is one of the following values:
v modified
v added
v deleted

Beside each item is a check box.

Reverting changes
After running a comparison and reviewing the results, you can revert select
changes or all changes between the two configurations. You can revert changes at
the property level only. To revert changes to select properties for an object, use the
object-specific configuration screens.

To revert changes, use the following procedures:

1. Determine which objects to revert:
v To revert select objects, select the check box beside those objects.
v To revert all objects, click Select All.
2. Click Undo Selected.

Chapter 8. Managing the configuration of the appliance 221

 The results are displayed on a new screen.

If a selected object is a referenced object, it cannot be deleted until after the

deletion of its parent object. You might need to run the comparison multiple times
to delete referenced objects. For example, you cannot delete certificates that are
referenced by a validation credentials list until after the deletion of the validation
credentials list itself.

Configuring deployment policies

Deployment policies use fine-grained matching statements and clause types to
control the inclusion of configuration data from imported configuration packages.

Depending on the clause type, the deployment policy can perform the follow types
configuration management against the imported configuration package:
v Use an accepted configuration to include resources in the package that match
specified criteria.
v Use a filtered configuration to delete resources in the package that match specified
criteria.
v Use a modified configuration to modify resources in the package that match the
specified criteria. Modified configurations support the following actions:
Add Adds the property with the identified value during the import.
Changed
Substitutes the value for the identified property during the import.
Deleted
Deletes the property during the import.

The processing sequence is as follows:

1. Process the accepted configuration, the whitelist, to always include resources
that match.
2. Process the filtered configuration, the blacklist, to always delete resources that
match.
3. Process the modified configuration to change the resources based on the
defined action type.

Creating a Deployment Policy object

A deployment policy is a sequence of accepted, filtered, and modified
configurations that respectively include, delete, or change configuration data in the
configuration package during the import. When specifying the matching statement,
you can use the builder or manually specify the statement.
v For details about using the builder to define the statement, refer to Using the
deployment policy builder on page 223.
v For details about manually specifying the statement, refer to Specifying the
matching statement on page 224.

Note: You cannot modify the administrative state of Deployment Policy objects.

To create a Deployment Policy object, use the following procedure:

1. Select Objects Configuration Management Deployment Policy to display
the catalog.
2. Click Add to display the configuration screen.

222 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 3. Specify the name of the object in the Name field.
4. Specify a descriptive object-specific summary in the Comment field.
5. Define accept clauses.
a. Specify the matching statement in the Accepted Configuration field, or click
Build.
b. Click Add.
Repeat this step to define another accept clause.
6. Define filter clauses.
a. Specify the matching statement in the Filtered Configuration field, or click
Build.
b. Click Add.
Repeat this step to define another filter clause.
7. Define modify clauses on the Modified Configuration tab.
a. Click Add to display the Modified Configuration property window.
b. Specify the matching statement for the modify clause in the Configuration
Match field, or click Build.
c. Select the type of configuration modification from the Modification Type
list.
Add Configuration
Adds a configuration setting.
Delete Configuration
Deletes a configuration setting.
Change Configuration
Changes a configuration setting.
d. If adding a configuration, specify the name of the property to add in the
Configuration Property field.
e. If adding or changing a configuration, specify the value of the property to
add or modify in the Configuration Value field.
f. Click Save to return to the configuration screen.
Repeat this step to define another modify clause.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

Using the deployment policy builder

Deployment policies include a builder to help create matching statements in the
following format:
address/domain/resource[?Name=resource-name
&Property=property-name&Value=property-value]

To access the builder, click Build. This button is associated with the following
properties:
v Accepted Configuration on the Main tab
v Filtered Configuration on the Main tab
v Configuration Match in the properties Window that the WebGUI displays after
clicking Add on the Modified Configuration tab

To create a matching statement with the builder, use the following procedure:
1. Click Build to open the builder.

Chapter 8. Managing the configuration of the appliance 223

 2. Specify the IP address or host alias in the Device Address field. The value *
matches all IP addresses.
3. Select the name of the application domain from the Application Domain list.
The selection (none) matches all domains.
4. Select the resource type from the Resource Type list. The select (all resources)
matches all resource types.
5. Optionally specify a name match for a resource in the Name Match (PCRE)
field. This property limits the matching statement to resources of the specified
name. Use a PCRE to select groups of resource instances. For example, foo*
would match all resources with names that start with foo.
6. Optionally specify the name of the configuration property in the Configuration
Property field. This property limits the matching statement to resources of the
specified property.
7. Optionally specify the value for the configuration property in the
Configuration Value Match (PCRE) field. This property limits the matching
statement to resources of the specified value. Use a PCRE Match Expression to
select groups of configuration property values.
8. Click Save.

The statement is added to the list of matching statements.

Specifying the matching statement

Instead of using the builder, you can manually specify the matching statement.
Matching statements have the following format:
address/domain/resource[?Name=resource-name
&Property=property-name&Value=property-value]
address
Specifies the IP address or host alias. The value * matches all IP addresses.
domain Specifies the name of the application domain. The value * matches all
domains.
resource
Specifies the resource type. The value * matches all resource types.
Name=resource-name
Optionally specifies a name match for a resource. This property limits the
matching statement to resources of the specified name. Use a PCRE to
select groups of resource instances. For example, foo* would match all
resources with names that start with foo.
Property=property-name
Optionally specifies the name of the configuration property. This property
limits the matching statement to resources of the specified property.
Value=property-value
Optionally specifies the value for the configuration property. This property
limits the matching statement to resources of the specified property.

PCRE documentation is available at the following Web site:

http://www.pcre.org

224 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Chapter 9. Managing monitors
This chapter describes how to create and manage message Web services monitors.
You can create and manage the following types of traffic or error monitors
(message monitors) using the OBJECT Monitoring menu.
Message Count Monitor
Creates a count-based monitor
Message Duration Monitor
Creates a time-based monitor
Message Filter Action
Defines an administrative response to the overuse of resources
Message Matching
Creates a traffic definition
Message Type
Creates a monitored message type

You can create and manage Web services monitors by enabling statistics using the
Administration Device Statistic Settings menu and the configuring the
monitors using the OBJECT Monitoring Web Services Monitor menu.

Monitor types
Monitors enable the definition of a message set, the specification of a count-based
or time-based threshold, and the design of administrative controls imposed when
the message set exceeds configured threshold values.

Monitors are of the following types:

v Message count monitors which measure traffic volume. Using a message count
monitor, you, for example, can track all requests for a specific URL or URL set
originating from an identified subnet, and limit such requests to 100 per second.
For details, refer to Message Count Monitor on page 230.
v Message duration monitors which measure appliance processing time and latency.
Using a message duration, you, for example, can measure the average server
response time, and impose sanctions (temporarily deny service) if the average
time exceeds a configured value. For details, refer to Message Duration
Monitor on page 233.
v Web services monitors are WSDL-based and combine the properties of both
message count and message duration monitors. Web services monitors provide
the ability to watch, or observe traffic flowing to and from a particular Web
services endpoint. Web service monitors can implement a dual-threshold scheme
in which a first-level threshold could generate a log message while a
second-level threshold could throttle (drop) traffic.
Using a Web services monitor, you can, for example, observe all traffic flowing
to a particular endpoint, issue notification when a first-level error count is
exceeded, and then throttle operations if the error count continues to rise.
For procedural details, refer to Configuring Web services monitors on page
235.
v Service level monitors provide a much finer level of user control. For example, a
service level monitor enables the creation and assignment of monitors at the

Copyright IBM Corp. 2002, 2009 225

 WSDL service, port and operations level. User control also extends to the precise
definition of monitored users and monitored resources and the scheduling of
monitoring operations.
Using a service level monitor, you can, for example, create a peak-hours monitor
that provides strict monitoring of set of frequently-accessed resources, by a set or
sets of defined user groups, along with a companion off-hours monitor that
provides less-stringent controls over the same set of resources and user groups.
Unlike other monitor types, service level monitors can be applied across
multiple DataPower appliances thus allowing installations to enforce SLM
policies based on aggregated counts across peer appliances.

Configuring message monitors

In common with most other configuration objects, message monitors are
constructed from the ground up. This approach facilitates appliance
configuration by breaking down compound, and possibly complex, objects into
their simple constituent parts, which can then be reused and mixed and matched
to address site-specific concerns and requirements.

The initial step in configuring a message monitor is to identify the traffic streams
that are subject to administrative monitoring and control. Identification of a
specific traffic stream is accomplished using a traffic definition object, which is
essentially a template that describes a traffic stream in terms of source IP address,
requested URL, HTTP header field values, and HTTP methods. For procedural
details on creating traffic definitions, refer to Traffic definition on page 227.

You complete the traffic identification process by assigning one or more traffic
definitions to an aggregate object referred to as a message type, which is essentially
a list of traffic definitions. A message type enables a single message monitor to
exercise administrative control over multiple, possibly related, traffic streams. The
same message monitor, for example, could monitor the traffic stream originating
from subnet 10.10.10.0/24 along with the traffic stream originating from the
10.10.1.0/24 subnet. For procedural details on compiling message types, refer to
Message Type on page 229.

After identifying target traffic streams, proceed to define a filter that specifies the
administrative actions to take in response to the overuse of appliance or network
resources by a monitored message type. Policies might be relatively benign (the
simple generation of a logging message), or more stringent, possibly resulting in a
temporary denial of service to the offending message type. You can define
compound policies that activate an initial cautionary response when a message
type exceeds a low threshold value, and activate more stringent sanctions when
the same message type exceeds a higher threshold value For procedural details on
defining monitor policies, refer to Filter action on page 230.

You next create the message monitor object, which consists of a threshold value or
values, an associated message type, and an associated monitor filter. You can create
two types of message monitors.
v A message count monitor, as its name implies, uses an counter to track specific
occurrences. It activates a monitoring filter when the number of occurrences,
over a measured interval, exceeds a threshold value.
For procedural details, refer to Message Count Monitor on page 230.
v A message duration monitor, as its name implies, is clock-based and measures
how long it takes to complete certain transactions. It activates a monitoring filter
when the average completion times exceeds a threshold value.

226 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 For procedural details, refer to Message Duration Monitor on page 233.

After completing the configuration of a message monitor, activate the monitor by

associating it with one or more DataPower services.

Traffic definition
Traffic definitions, which identify raw traffic streams, are the most basic
components used by message monitors. A traffic definition can identify a target
message stream in terms of the following criteria:
v Included IP source address
v Excluded IP source address
v Requested URL
v HTTP method
v Included HTTP header field/value
v Excluded HTTP header field/value
1. Select OBJECT Monitoring Message Matching Navigation bar to display
the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
IP Addresses
Specify a contiguous range of IP source addresses included in this
traffic definition.
Leave blank if you do not want to use IP source address as a criterion
for inclusion in this traffic definition. Leaving the field blank includes
traffic from all IP source addresses in the current traffic definition.
Specify an address range by providing an IP network address followed
by a prefix length, inserting a slash (/) between the network address
and the prefix length.
For example, 10.10.100.0/28 specifies the address range 10.10.100.0
through 10.10.100.15, but 10.10.100.9/32 specifies a single host
address.
Excluded IP Addresses
Specify a contiguous range of IP source addresses excluded from this
traffic definition.
Leave blank if you do not want to use IP source address as a criterion
for exclusion from this traffic definition.
Specify an address range by providing an IP network address followed
by a prefix length, inserting a slash (/) between the network address
and the prefix length.
For example, 10.10.100.0/28 specifies the address range 10.10.100.0
through 10.10.100.15, but 10.10.100.9/32 specifies a single host
address.

Chapter 9. Managing monitors 227

 HTTP Method
Specify an HTTP method type (CONNECT, DELETE, GET, HEAD,
OPTIONS, POST, PUT, TRACE) to include in this traffic definition.
Retain the default value (any) to include all HTTP traffic (HTTP
method types).
To include only certain kinds of HTTP traffic, set this field to identify
the HTTP method.
Request URL
Specify a set of requested URLs included in this traffic definition. Leave
blank if you do not want to use the requested URL as a criterion for
inclusion in this traffic definition. Leaving this field blank includes all
URLs.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters.
For example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y]
would match x or y.

You can use any PCRE-compliant expression. For more information,

refer to http://www.pcre.org.

You can use the HTTP Headers and Excluded HTTP Headers panels to specify
HTTP-based criteria for inclusion to, or exclusion from the traffic definition. You
can:
v Specify HTTP header field and value pairs to be included in the traffic definition
v Specify HTTP header field and value pairs to be excluded from the traffic
definition
4. Use the following procedure to specify HTTP-based inclusion criteria:
a. Click the HTTP Headers tab to display the HTTP Headers panel.
b. Click Add to display the HTTP Headers window.
c. Provide the following inputs:
Name
Specify the name of the target HTTP header field.
Value Match
Specify a set of header field values included in this traffic definition.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric
characters. For example, [1-5] would match 1, 2, 3, 4, or 5,
and [x-y] would match x or y.

228 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 You can use any PCRE-compliant expression. For more information,
refer to http://www.pcre.org.
d. Click Save to return to the HTTP Headers panel, which now displays the
HTTP header inclusive criterion.
5. Use the following procedure to specify HTTP-based exclusion criteria:
a. Click the HTTP Headers tab to display the Excluded HTTP Headers panel.
b. Click Add to display the Excluded HTTP Headers window.
c. Provide the following inputs:
Name Specify the name of the target HTTP header field.
Value Match
Specify a set of header field values excluded from this traffic
definition.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of
any single character.
[] Indicates a delimited range of alphabetic or numeric
characters. For example, [1-5] would match 1, 2, 3, 4, or 5,
and [x-y] would match x or y.

You can use any PCRE-compliant expression. For more information,

refer to http://www.pcre.org.
6. Click Save to return to the Excluded HTTP Headers panel, which now displays
the HTTP header exclusion criterion.
7. Click Apply to save the object to the running configuration.
8. Optionally, click Save Config to save the object to the startup configuration.

Message Type
A message type is a list of traffic definitions and enables a message monitor to
exercise administrative control over multiple traffic streams. You should assign a
traffic definition to a message type, even if the type consists of a single definition.
1. Select OBJECT Monitoring Message Type to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Message Matchings
Add one or more traffic definitions to the message type.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Chapter 9. Managing monitors 229

 Filter action
Message monitors specify a response, a filter, to the overuse of appliance resources.
Filters can take the form of the generation of log messages or the temporary denial
of service to a specific message type. All filter actions generate log messages of a
configured priority; these log messages will appear only in a log if there is a log
target configured with an event subscription of class Monitor and a priority equal
to or lower than the priority set by the filter.
1. Select OBJECT Monitoring Message Filter Action to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Type Select the sanction type.
Notify Adds a log entry when a message type exceeds a threshold
value.
Shape Adds a log entry and buffers incoming traffic such that the rate
of flow is at or below the threshold. When the buffer overflows,
messages are dropped.
Reject Adds a log entry and drops all over-threshold traffic
originating from a message type; optionally imposes a blackout
period on the message type.
Log Priority
Select the priority of the log messages generated when threshold values
are exceeded by a message type.

Note: Log targets will not include messages generated by a monitor

unless the log target is configured with an Event Subscription
class of Monitor or All and a Priority level equal to or lower
than the value set here.
Block Interval
Specify an optional blackout period during which an over-threshold
message type is denied service.
Meaningful only when the sanction is of the reject type, specifies the
duration of service denial (from 1 to 500 milliseconds). The default
value (0) indicates that while over-threshold messages are dropped, no
service denial penalty is imposed.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Message Count Monitor

To configure a message count monitor, use the following procedure:
1. Select OBJECT Monitoring Message Count Monitor to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:

230 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Message Type
Select the message type for message count monitor to monitor.
Measure
Select how to increment the counter.
Requests
Indicates that the receipt of a client request of the monitored
message type increments the counter.
Responses
Indicates that the receipt of a server response of the monitored
message type increments the counter.
XPath Indicates that the a style sheet increments the counter. Use the
dp:increment-integer extension element in a style sheet. This
extension element increments the counter that the count
monitor maintains. For example, if the name of the count
monitor is monitor1, the style sheet must contain the following
statement:
<dp:increment-integer name="'/monitor-count/monitor1'"/>
Errors Indicates that the receipt of an HTTP error response increments
the counter. Processing the Error Rule can increment this
counter.
Source
Specify how this message count monitor aggregates IP address
information. This property is only meaningful when the monitored
message type contains inclusive or exclusive IP address criteria.
All Gathers and reports IP address information for the aggregate
address range.
Each IP
Gathers and reports IP address information for individual IP
addresses (up to a maximum of 10000) in the address range.
IP from Header
Gathers and reports IP address information for individual IP
addresses (up to a maximum of 10000) in the address range. IP
addresses are determined by the value of the HTTP Header
identified by the Header property.
Header
Specify the HTTP Header that contains IP address information.
Maximum Distinct Sources
Specify the number of distinct IP addresses to track. When too many
distinct counts are observed, the addresses not observed in the longest
amount of time are discarded. The default is 10000.
4. Click the Threshold/Filters tab to display the Filters panel, which contains the
Filters catalog.

Chapter 9. Managing monitors 231

 5. Click Add to display the Filters window. Use this window to assign a filter to
the message count monitor and to specify the threshold values that trigger the
filter.
6. Provide the following inputs:
Name
Specify the name of this threshold.
Interval
Specify the measurement interval (expressed as milliseconds). Interval
works with Rate Limit and Burst Limit to define the conditions that
activate a monitor filter.
The example, the following combination imposes administrative sanctions
when the monitored message type exceeds 50 transactions per second:
v The Interval property set to 1000
v The Rate Limit property set to 50
v The Burst Limit property set to 100
Rate Limit
Specify the threshold value (expressed as a number of messages).
Burst Limit
Specify the allowed burst value. A monitor accrues the number of
messages below the rate limit per interval. A burst can be as large as the
accrued number of unused messages during a single interval, up to the
limit set here.
For example, the rate limit is 100 and only 90 were received during each
of the first five intervals. In the sixth interval, the monitor allows a burst
of as many as 150 transactions. If the burst limit is 140 and 150
transactions occur, the monitor takes the configured action. The formula
to calculate burst is as follows:
L(t) = min( R + max( L(t-1) - M(t-1), 0 ), B )

In the formula, the symbols have the following meaning:

v L(t) is the limit at interval t
v R is the rate limit
v B is the burst limit
v M(t) is the number of messages received in interval t
Because the monitors have lower priority than processing, a busy
appliance might run monitor-checking as often as the interval set when
the interval is small. Set the Interval property to at least 1000 (1 second),
and set the allowed burst value to approximately twice the threshold
value.
Action
Select the monitor filter to be triggered when the monitored message type
exceeds threshold values. Refer to Filter action on page 230 for more
information.
7. Click Save to return to the Filters panel, which now lists the newly created
threshold and associated monitor policy.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

232 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 After creating a monitor, activate it by assigning it to one or more DataPower
services.

Message Duration Monitor

To configure a duration monitor, use the following procedure:
1. Select OBJECT Monitoring Message Duration Monitor to display the
catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Message Type
Select the message type monitored by this message duration monitor.
Refer to Message Type on page 229 for more information.
Measure
Select a portion of the transaction cycle to be measured.
Messages
Specifies the time interval between the receipt of a client
request and the transmission of the associated server response.
Requests
Specifies the time spent by the appliance in processing a client
request, that is the interval between the receipt of a client
request and its transmission to the target server.
Responses
Specifies the time spent by the appliance in processing a server
response, that is the interval between the receipt of a server
response and its transmission to the target client.
Server Specifies the server processing time, that is the interval between
the transmission of a client request to the server and the receipt
of the associated server response.
Each list item represents a portion of the client request-server response
roundtrip timeline.
v The Requests and Responses values are internal to the appliance.
Requests measures the time required to perform filtering,
cryptographic, and transformation operations on client requests,
while Responses measures the time required to perform similar
processing on server responses.
v The Server and Messages values deal with external processing,
specifically the processing performed by the a Web or application
server. Server measures the actual server processing time (including
network latency), while Messages approximates the sum of
Requests, Server, and Responses settings.
4. Click the Filters tab to display the Filters panel.
5. Click Add to display the Filters window.

Chapter 9. Managing monitors 233

 Use this window to assign a filter to the message duration monitor and to
specify the threshold values that trigger the filter.
6. Provide the following inputs:
Name
Specify the name of this threshold.
Type
Retain the default value.
Value
Specify the threshold value (in milliseconds).
This property works with the Measure property (defined on the Main
configuration panel) to define the conditions that activate a monitor filter.
For example the following combination imposes administrative sanctions
when the average interval between the receipt of a client request and the
transmission of the associated server response for the monitored message
type exceeds 100 milliseconds:
v The Measure property set to messages
v The Value property set to 100
Action
Select the monitor filter triggered when the monitored message type
exceeds threshold values. Refer to Filter action on page 230 for more
information.
7. Click Save to return to the Filters panel, which now lists the newly created
threshold and associated monitor policy.
8. Click Apply to save the object to the running configuration.
9. Optionally, click Save Config to save the object to the startup configuration.

After creating a monitor, activate it by assigning it to one or more DataPower

services.

Using Web services monitors

The DataPower appliance can monitor specific service level activity and provide
logging and alerts based on user-configured levels of errors and transactions. For
example, a bank might offer account query, loan processing and wire transfer
services to its business partners through a set of Web services interfaces. Every
business partners traffic passes through an XML Firewall service, which provides
security and validation services. The DataPower appliance can be configured to
monitor traffic for each particular service that the bank offers. When
user-configured levels of errors or transaction rates are met, the appliance can post
messages to the log. With this information, the bank can summarize and monitor
the health of its Web services offerings.

These monitors read a WSDL file that defines the Web services to monitor and that
offers the user the ability to configure monitors that are based on the services that
are defined in the WSDL file. The WSDL file must reside on the appliance or be
accessible over the network.

Note: Web services monitors require the activation of statistics on the appliance.
By default, statistics are administratively disabled.

234 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Enabling statistics
To enable statistics, use the following procedure:
1. Select Administration Device Statistics Settings to display the Statistics
Settings Configuration screen.
a. For Admin State, click the enabled radio button.
b. Click Apply.
c. Click Save Config.

Configuring Web services monitors

To configure a Web services monitor, use the following procedure:
1. Select Object Monitoring Web Services Monitor to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
WSDL URL
The URL of the WSDL file that defines the Endpoints, Transport Type,
and Operations watched by this monitor. The WSDL file can reside on
the appliance or elsewhere on the network. Example values include
local:///service.wsdl or https://www.service.com/Services/
service.wsdl.
Endpoint
Specify the name of the Endpoint, as defined in the WSDL file
identified above, this monitor will watch. For example, a WSDL file
might have the following definition:
<service name="BoodleSearchService">
<port name="BoodleSearchPort" binding="typens:BoodleSearchBinding">
<soap:address location="http://api.boodle.com/search/beta2"/>
</port>
</service>

This field would have a value of BoodleSearchService.

Endpoint URL
Specify the URL of the Endpoint that this monitor will watch. This URL
is defined in the WSDL file identified by the Endpoint property. Given
the example definition shown for the Endpoint property, this value
would be http://api.boodle.com/search/beta2/.
Front End URL
Specify the URL to be used by the client to access the Web Service
endpoint. This URL can be different from the Endpoint URL, which
might be the case when the firewall rewrites the URL during
processing. A wildcard (*) can be used in this value. For example, the
value could be /search/*.

Chapter 9. Managing monitors 235

 Transport Type
Select the transport type used by the identified Endpoint. This value
should match the transport type that is specified in the WSDL file. The
following values are available:
HTTP-GET
Employs HTTP GET operation
HTTP-SOAP
Employs HTTP POST to post SOAP documents
SOAP-document
Employs SOAP document transport
SOAP-RPC
Employs SOAP RPC transport
The following example definition uses SOAP-rpc as the value:
<soap:binding style="rpc"
transport="http://schemas.xmlsoap.org/soap/http"/>
4. Click the Operations to Monitor tab to display the Operations to Monitor
catalog.
5. Click Add to display the Operations to Monitor window.
6. Provide the following inputs:
Operation Name
Retain the default value. The current implementation supports the
monitoring of all operations that the WSDL file defines on the defined
endpoint.
Target to Monitor
Select the monitoring target.
Error Count
Errors occurring at the front end (or client request) URL
Transaction Rate
The rate of transactions for the entire Web service
To monitor both error-counts and transaction rate, create two operations.
Create one operation for monitoring error counts and create another for
monitoring transaction counts.
Threshold Level
Select the threshold level, and then define its value.
Threshold levels can be either Low or High. For example, as transaction
rates rise, the first (low) threshold could be reached at 100 transactions
per second, at which time some action would be taken. The second (high)
threshold could be reached at 300 transactions per second, at which time
some (potentially different) action would be taken.
Threshold Value
The count per second threshold value required to trigger an action.
Threshold Action
Select the action to take when a threshold is reached.
Send to Log
Post a message to a log target
Throttle Operations
Reject transactions over the threshold level

236 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 7. Click Apply to save the object to the running configuration.
8. Optionally, click Save Config to save the object to the startup configuration.

Specifying dual thresholds

By default, First Limit messages are sent to the log target as warning messages,
and Second Limit messages are sent to the log target as error messages. Logs can
be set to record messages of type error only. In which case, messages of type low
would not be included in the log. The default log accepts only messages of type
error.

To specify dual thresholds, use the following procedure:

1. Define the first (low) threshold:
a. Click Add to display the Operations to Monitor window.
b. Select First Limit in Threshold Level.
c. Provide the Threshold Value.
d. Select the Threshold Action.
e. Click Save to return to Operations to Monitor catalog.
2. Define the second (high) threshold
a. Click Add to re-display the Operations to Monitor window.
b. Select Second Limit in Threshold Level.
c. Provide the Threshold Value.
d. Select the Threshold Action.
e. Click Save to return to Operations to Monitor catalog.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Chapter 9. Managing monitors 237

238 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Appendix A. Referenced objects
AAA Policy
1. Select Objects XML Processing AAA policy to display the AAA Policy
catalog.
2. Click Add to display the AAA Policy Configuration (Main) screen. Use this
screen to provide policy-wide, global configuration data.
3. Click the Identify tab to define how to extract the identity.
4. Click the Authenticate tab to define how to authenticate the identity.
5. Click the Map Credentials tab to how to map the credential.
6. Click the Resource tab to define how to extract the resource.
7. Click the Map Resource tab to define how to map the resource.
8. Click the Authorize tab to define how to authorize the credential.
9. Optionally click the Post Processing tab to define post processing activities.
10. Optionally click the Namespace Mapping tab to define how to map
namespaces.
11. Optionally click the SAML Attributes tab to define SAML attributes.
12. Optionally click the LTPA User Attributes tab to define LTPA user attributes.
13. Optionally click the Transaction Priority tab to define the priority of
transactions.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

Main tab
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Authorized counter
Optionally select a message-count monitor. This object monitors and
controls incoming messages authorized by this AAA Policy. This counter
should Measure type XPath to allow the AAA Policy to increment the
counter on successful authorization. Refer to Message Count Monitor on
page 230 for more information.
Rejected counter
Optionally select a message-count monitor This object monitors and
controls incoming messages rejected by this AAA Policy. This counter
should Measure type XPath to allow the AAA Policy to increment the
counter on rejected authorization. Click Rejected Counter Tool to configure
a counter for this purpose. Refer to Message Count Monitor on page 230
for more information.
SAML Signature Validation Credentials
Optionally (and only if SAML-based identity extraction, authentication,

Copyright IBM Corp. 2002, 2009 239

 and authorization is used by this AAA policy), select the Crypto Validation
Credentials used to validate digitally-signed SAML assertions from the
Credentials list. Refer to Working with Validation Credentials objects on
page 21 for more information.
SAML Message Signing Key
Optionally if SAML-based identity extraction, authentication, or
authorization is used by this AAA Policy, select a crypto key used to sign
SAML assertions. Refer to Defining Key objects on page 16 for more
information.
SAML Message Signing Certificate
Optionally if SAML-based identity extraction, authentication, or
authorization is used by this AAA Policy, select the matching crypto
certificate that is the public certificate associated with the private key
designated by the SAML message signing key. Refer to Defining
Certificate objects on page 13 for more information.
SAML Signing Message Digest Algorithm
Select the hash algorithm for SAML signing message. The default is sha1.
SAML Message Signing Algorithm
Select the algorithm to sign SAML messages. RSA and DSA are supported
by older releases. rsa is same as rsa-sha1, and dsa is same as dsa-sha1. The
default is rsa.
LDAP Suffix
Optional if LDAP authentication or authorization is used by this AAA
policy. Specify an LDAP base DN.
LDAP-based authentication implementations require an X.500 DN (for
example, cn=Alice,dc=datapower,dc=com) and a password. When
configuring LDAP for authentication, it is typical to create a base DN (such
as dc=datapower,dc=com) and then create one entry under this base for each
user.
To make LDAP authentication more usable, the AAA policy provides the
LDAP suffix. Set the LDAP suffix to the base name under which user
entries are found. If the LDAP suffix is not an empty string, the AAA
Policy builds an X.509-compliant DN by prepending cn= to the surname
and appending a comma followed by the value of the LDAP suffix. Hence,
an LDAP suffix of dc=datapower,dc=com, the user name Alice is mapped to
the DN cn=Alice,dc=datapower,dc=com.
Log Allowed
By default, the AAA policy generates log messages at the indicated level
for every access allowed. Set to off to change this behavior.
Log Allowed Level
When Log Allowed set to on, change the default level. Log messages
generated for each access allowed by this AAA policy will be set at the
level selected.
Log Rejected
By default, the AAA policy generates log messages at the indicated level
for every access rejected. Set to off to change this behavior.
Log Rejected Level
When Log Rejected set to on, change the level. Log messages generated
for each access rejected by this AAA policy will be set at the level selected.

240 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Note: Log targets capture messages at or above the level configured for
the target. The higher the level, the more likely one or more log
targets will catch the message. To be sure log targets capture these
AAA messages, coordinate these levels.
WS-Trust Encryption Recipient Certificate
When generating a WS-Trust token for a secret key (such as a
WS-SecureConversation token), select the key to encrypt the initial secret.
SAML Artifact Mapping File
This file contains a map of SAML artifact source identifiers to artifact
retrieval endpoints. This property is required only when artifacts will be
retrieved from multiple endpoints and the source identifiers for these
endpoints are encoded in the artifact itself (per the SAML specification). If
there is only one artifact retrieval URL, it can be specified by the SAML
artifact responder URL in the authentication phase.
Ping Identity Compatibility
Select whether to enable (on) or disable (off) Ping Identity compatibility.
Enable Ping Identity compatibility when using SAML for authentication or
authorization.
SAML 2.0 Metadata File
This file contains information about the various SAML Authorities that
might be used for SAML 2.0 authentication and authorization. From the
list, select a file, and click Upload to upload a file.
The file must conform to the SAML 2.0 metadata schema
(xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata").
DoS Flooding-Attack Valve
Specifies the number of times to perform the same XML processing per
user request. Use a value in the range of 1 through 1000. The default is 3.
This property limits the number of times to perform the same XML
processing per user request. XML processing includes encryption,
decryption, message signing, and signature validation. At this time, the
AAA Policy supports this property in the following cases:
v Identity extraction when the method is Subject DN from Certificate in
the Messages signature
v Authentication when the method is Validate the Signer Certificate for a
Digitally Signed Message
When used with the value of 1, the AAA Policy extracts the first signature
and its first reference from the security header and ignores all other
signatures or signing references. If the security header contains more
signatures or a single signature contains more signing references, these
signatures and signing references are ignored. During signature
verification, the processing fails if the needed signature is not part of
extracted identity.
For example if dos-valve is 2 and the needed information to verify the
signature was the third signing reference, the verification would fail.
However if the information was the second signing reference, the
verification would succeed.
LDAP Version
Select the LDAP protocol version (2, the default version, or 3) used when
accessing the authorization server.

Appendix A. Referenced objects 241

 Enforce Actor/Role for WS-Sec Message
Most of the times a WS-Security message has a S11:actor or S12:role
attribute for its wsse:Security header, we can enforce those attributes
when AAA tries to use wsse:Security header, for example, there should be
only one wsse:Security element having same actor/role, and AAA should
only process the wsse:Security header for the designated Actor/Role
Identifier. This setting takes effect for all AAA processing except post
processing. The default is on.
WS-Sec Actor/Role Identifier
When enforcing WS-Security Actor/Role, specify the identifier.

Continue with defining the identity extraction method.

Identity tab
The initial processing performed by an AAA Policy consists of extracting
information from an incoming message and its protocol envelope(s) about the
claimed identity of the service requester.

Use the Identity panel to specify the method or methods used by the AAA Policy
to extract the identity claimed by the service requester. Click the Identity tab to
display the AAA Policy Configuration (Identity) screen.

Use the check boxes to enable (on) or disable (off) one or more identification
methods.
HTTPs Authentication header
The claimed identity of the requester is extracted from the HTTP
Authorization header (name and password).
If selected, the WebGUI prompts for the following property:
HTTPs Basic Authentication Realm
The name of the HTTP Basic Authentication Realm as described by
RFC 2617, HTTP Authentication: Basic and Digest Access Authentication.
A browser might display this name to help determine which
credentials to supply.
UserName element from WS-Security header
The claimed identity of the requester is extracted from the WS-Security
UserName element (name and password) contained in a SOAP header.
BinarySecurityToken element from WS-Security header
The claimed identity of the requester is extracted from the WS-Security
BinarySecurityToken element (using the tokens string value as the claimed
identity) contained in a SOAP header.
WS-SecureConversation Identifier
The claimed identity of the requester is extracted from a
WS-SecureConversation Identifier.
WS-Trust Base or Supporting Token
The claimed identity of the requester is extracted from a WS-Trust Base or
Supporting token.
Kerberos AP-REQ from WS-Security header
The claimed identity of the requester is extracted from a Kerberos AP-REQ
contained in the WS-Security header.

242 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Kerberos AP-REQ from SPNEGO token
The claimed identity of the requester is extracted from a Kerberos AP-REQ
contained in the SPNEGO token.
Subject DN of the SSL Client Certificate from the Connection Peer
The claimed identity of the requester is extracted from the SSL client
certificate presented during the SSL handshake. If this is checked, the
Validation Credentials for Signing Certificate appears.
Name from SAML attribute assertion
The claimed identity of the requester is extracted from a SAML assertion that
contains a SAML attribute statement. The name contained in the Subject
element of the attribute statement is used as the claimed identity.
Name from SAML authentication assertion
The claimed identity of the requester is extracted from a SAML assertion that
contains a SAML authentication statement. The name contained in the Subject
element of the authentication statement is used as the claimed identity.
SAML artifact
The claimed identity of the requester is extracted from a SAML artifact.
Client IP address
The clients IP address is used for identity extraction.
Subject DN from the certificate in the messages signature
The claimed identity of the requester is extracted from a certificate used to
validate a digitally-signed message verify the signature validity, if the
signature is valid, use the Subject DN extracted from the certificate associated
with the signature as the claimed identity. If this is checked, the Validation
Credentials for Signing Certificate field is displayed.
If selected, the WebGUI prompts for the following property:
Validation Credentials for Signing Certificate
Select the Validation Credentials List used to validate the presented
certificate. Refer to Defining Identification Credentials objects on
page 15 for more information.
Token extracted from the message
The claimed identity of the requester is extracted using an XPath expression.
If this is checked, the XPath Expression field is displayed. If selected, the
WebGUI prompts for the following property:
XPath expression
Provide the operative XPath expression. The XPath expression is
applied to the entire message.
If you require name spaces in the XPath expression, refer to
Namespace Mapping tab on page 262 for procedural and
configuration details.
Token extracted as Cookie value
The claimed identity of the requester is extracted from a Cookie value. If
selected, the WebGUI prompts for the following property:
Cookie name
Specify the cookie name.
LTPA Token
The claimed identity of the requester is extracted from an LTPA (Lightweight
Third Party Authentication) token value. LTPA tokens, which are opaque

Appendix A. Referenced objects 243

 signed and encrypted strings, are carried via HTTP, specifically in the
Set-Cookie response and Cookie request headers.
Refer to Understanding LTPA for more information.
Custom template
The claimed identity of the requester is extracted by a custom or proprietary
identification resource (for example, a style sheet). If selected, the WebGUI
prompts for the following property:
Custom URL
Specify the local or remote URL of the identification resource.

Click Apply to commit AAA Policy properties.

Optionally, click Save Config to save the object to the startup configuration.

Authenticate tab
After extracting the claimed identity of the service requester, an AAA Policy
authenticates the claimed identity. The authentication process can use internal or
external resources. Use the Authenticate panel to designate the authentication
method.
1. Click the Authenticate tab to display the AAA Policy Configuration
(Authenticate) screen.
2. From the Method list, select an authentication method.
Accept a SAML Assertion with a Valid Signature
The requester is authenticated by a SAML assertion with a valid
signature.
Accept an LTPA token
The requester is authenticated by an encrypted LTPA token. If selected,
the WebGUI prompts for the following property values:
LTPA Token Versions
Specifies the LTPA formats supported for authentication purposes.
Use the check boxes to specify the LTPA versions that are
supported for authentication. Select at least one version, or all
LTPA-based authentication will fail.
Because the LTPA token must be decrypted before authentication,
the following properties identify the needed cryptographic
resources.
LTPA Key File
Provide the name of the file that contains the cipher keys to be
used for encryption and decryption.
LTPA Key File Password and Confirm LTPA Key File Password
Provides the cleartext password to the LTPA key file.
Refer to Understanding LTPA for more information.
Bind to Specified LDAP Server
(Default) The requester is authenticated by an LDAP server. If selected,
the WebGUI prompts for the following properties:
Host Specify the IP address or domain name of the LDAP
authentication server.

244 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Port Specify the LDAP authentication server port number. If not
supplied, defaults to the canonical port number.
LDAP Prefix
Optionally specify an LDAP Prefix name. This string is prepended
to the identity extracted before submission to the LDAP server.
The default is cn=.
This property is relevant when the Search for DN is off.
LDAP Suffix
Optionally specify an LDAP Suffix name. This suffix string is
appended to the identity extracted before submission to the LDAP
server. For example, o=datapower.com.
This property is relevant when the Search for DN is off.
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If you select a group,
LDAP queries will be load balanced in accordance with the
settings in the group. Load balancing allows for failover. Refer to
Load Balancer Group on page 287 for more information.
When specified, this property overrides the settings for the Host
and Port properties.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
LDAP Bind DN
Specify the Distinguished Name for the LDAP bind operation.
LDAP Bind Password and Confirm LDAP Bind Password
Specify and confirm the password for the LDAP bind operation.
LDAP Search Attribute
Specify the name of the LDAP attribute that contains the cleartext
password. The default is userPassword.
This property is meaningful only when the identity extraction
method is Password-carrying UsernameToken Element from
WS-Security Header and the <Username> element in the header
has the Type attribute set to PasswordDigest. In this case, the
LDAP server returns the text in the specified LDAP attribute for
the user in the UsernameToken. If the hashed value of the
returned text does not match the value in the <Password> element,
authentication fails.
Search for DN
Indicate whether to perform an LDAP search retrieve the DN of
the user.
on Enables an LDAP search for the users group. The login
name of the user along with the LDAP Search Parameters
will be used as part of an LDAP search to retrieve the
users DN.
off (Default) Disables an LDAP search for the users group.
The login name of the user along with the LDAP prefix
and the LDAP suffix will be used to construct the users
DN.

Appendix A. Referenced objects 245

 v If on, the WebGUI displays the following field.
LDAP Search Parameters
Select the LDAP Search Parameters from the list. Refer to
Defining an LDAP Search Parameters object on page 286
for detail.
v If off, the WebGUI removes the following fields:
LDAP Prefix
LDAP Suffix
Contact a SAML Server for a SAML Authentication Statement
The requester is authenticated by issuing a SAML Authentication Query
to the appropriate server. If selected, the WebGUI prompts for the
following properties:
SAML Authentication Query Server
Specify the URL of the SAML Authentication Query Server that
can authenticate the requesting entity and supply a SAML
Authentication Assertion.
SAML Version
Select the SAML version used for authentication. Versions 1.0, 1.1
and 2.0 are supported. The version selected affects the format of
the messages sent to SAML authorities.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact a WS-Trust Server for a WS-Trust Token
The requester is authenticated by a WS-Trust token obtained from a
WS-Trust server. If selected, the WebGUI prompts for the following
properties:
WS-Trust Token Server
Specify the URL of the WS-Trust server that can authenticate the
requesting entity and supply a WS-Trust token.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.

The following properties are relevant for attaching WS-Policy, not for
AAA authentication.
Require Client Entropy
Indicates whether to require client entropy as key material in the
WS-Trust request.
on Requires client entropy. The DataPower appliance sends
an entropy element to the WS-Trust server as part of the
security token request exchange. Use the WS-Trust
Encryption Certificate property to determine how to
include the key material in the request.
off (Default) Does not require client entropy.
When required, specify the size of the client entropy in bytes in
the Client Entropy Size field. The size refers to the length of the

246 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 client entropy before Base64 encoding. Use an integer in the range
of 8 through 128. The default is 32.
Require Server Entropy
Indicates whether to require server entropy in the WS-Trust
response.
on Requires server entropy. The WS-Trust server must return
an entropy element to the DataPower appliance as part of
the security token request exchange.
off (Default) Does not require server entropy.
When required, specify the minimum allowable size of the
received entropy material in bytes in the Server Entropy Size
field. The size refers to the length of the client entropy before
Base64 encoding. Use an integer in the range of 8 through 128.
The default is 32.
Require RequestSecurityTokenCollection
Indicates whether to generate a WS-Trust RequestSecurityToken or
a WS-Trust RequestSecurityTokenCollection as part of the security
token request exchange.
on Generates a WS-Trust RequestSecurityTokenCollection.
off (Default) Generates a WS-Trust RequestSecurityToken.
Require AppliesTo SOAP Header
Indicates whether to generate a WS-Addressing AppliesTo header
as part of the security token request exchange.
on Generates a WS-Addressing AppliesTo header.
off (Default) Does not generate a WS-Addressing AppliesTo
header.
When required, specify the value for the AppliesTo header in the
AppliesTo Header field.
WS-Trust Encryption Certificate
Optionally select a Crypto Certificate to encrypt WS-Trust
elements in the request. If selected, he public key of the certificate
encrypts the client entropy key material for the recipient. If blank,
the WS-Trust BinarySecret element contains the entropy material.
In this case, use an SSL Proxy Profile to secure the message
exchange with the WS-Trust server.
Contact ClearTrust Server
The requester is authenticated via a ClearTrust server. If selected, the
WebGUI prompts for the following properties:
ClearTrust Server URL
Provide a local or remote URL that locates the authentication
resource.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact Netegrity SiteMinder
The requester is authenticated by a Netegrity server. If selected, the
WebGUI prompts for the following properties:

Appendix A. Referenced objects 247

 Host Specify the IP address or domain name of the Netegrity
authentication server.
Port Specify the Netegrity authentication server port number.
Netegrity Base URI
Specify the appropriate URI string.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.
Contact NSS for SAF Authentication
The requester is authenticated by the SAF. If selected, the WebGUI
prompts for the following property:
z/OS NSS Client Configuration
Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server. Refer to z/OS NSS Client on page
353 for more information.
Contact Tivoli Access Manager
The requester is authenticated by a Tivoli Access Manager. A Tivoli Access
Manager object must exist and be in an enabled state for this method to
succeed. Refer to IBM Tivoli Access Manager on page 270 for more
information.
Custom Template
The requester is authenticated by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Provide a local or remote URL that locates the authentication
resource.
Pass Identity Token to the Authorize Step
The requester is not authenticated by this AAA policy, the request is
passed to the authorization server for disposition.
Retrieve SAML Assertions Corresponding to a SAML Browser Artifact
The requester is authenticated by a SAML artifact. If selected, the WebGUI
prompts for the following properties:
SAML Artifact Responder
Specify the URL of the SAML Artifact Responder that can
authenticate the requesting entity using the artifact supplied.
SAML Version
Select the SAML version used for authentication. Versions 1.0, 1.1
and 2.0 are supported. The version selected affects the format of
the messages sent to SAML authorities.
SAML 2 Issuer
Specify a value that appears in the SAML <samlp:Issuer> element
after the SAML Artifact has been authenticated. This element is
included in the information delivered to the Authorize phase.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to
remote authentication server. Retain the default value to use a
non-SSL connection.

248 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Use an Established WS-SecureConversation Security Context
The requester is authenticated by a WS-SecureConversation token
contained in the request.
User certificate from BinarySecurityToken
The requester is authenticated by a certificate that is included with a
BinarySecurityToken. If selected, the WebGUI prompts for the following
property:
X.509 BinarySecurityToken Validation Credentials
Select the Validation Credentials to validate the X.509 certificate in
the BinarySecurityToken. Refer to Working with Validation
Credentials objects on page 21 for more information.
Use DataPower AAA Info File
The requester is authenticated by an XML file. If selected, the WebGUI
prompts for the following properties:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml. To
examine a sample AAA Info file, open store:///authfile.xml.
Use specified RADIUS Server
The requester is authenticated by a RADIUS server.
Validate a Kerberos AP-REQ for the Correct Server Principal
The requester is authenticated via a Kerberos AP-REQ contained in the
WS-Security header. If selected, the WebGUI prompts for the following
properties:
Kerberos principal name
Provide the name part of the server identity. This value is the
server name that is contained in the sname field of the
unencrypted portion of the Kerberos ticket.
Kerberos keytab
Select the Kerberos Keytab File object. This field is required.
Validate the Signer Certificate for a Digitally Signed Message
The signature requires validation. If selected, the WebGUI prompts for the
following properties:
Signature Validation Credentials
Use a Validation Credentials List.
XPath Expression
Use the specified XPath expression.
Validate the SSL Certificate from the Connection Peer
The requester is authenticated via its client SSL credentials. If selected, the
WebGUI prompts for the following property:
SSL Client Validation Credentials
Select the Validation Credentials List used to validate offered
client certificates. Refer to Working with Validation Credentials
objects on page 21 for more information.

The following inputs are displayed for all methods.

Appendix A. Referenced objects 249

 Cache authentication results
Select the caching strategy. By default, authentication information from
remote resources is cached for a period of three seconds. On
authentication failure, authentication information is removed from the
cache.
Absolute
(Default) Caches all authentication data with an explicit TTL
(time-to-live), specified by the Cache Lifetime property.
Disabled
Disables caching of authentication data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL specified by the Cache Lifetime
property with the received TTL (if any). Use the data-specific TTL
if it is greater than the explicit TTL. Otherwise, use the explicit
value.
Cache Lifetime
Specify the explicit TTL in seconds. This defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Map Credentials tab

After receiving authentication credentials, an AAA Policy can optionally map these
credentials. It might be necessary to map credentials presented by an
authentication method to a format congruent with a different authorization
method; for example, mapping an authenticated account name/password to an
LDAP group. To perform such credentials mapping, an AAA Policy uses custom
XML or XPath resources, which you identify during policy definition.

If credentials mapping is necessary, use the Map Credentials panel to designate the
mapping method and resource.
1. Click the MapCredentials tab to display the AAA Policy Configuration (Map
Credentials) screen.
2. From the Method list, select a credentials mapping method.
Custom
The authentication credentials are mapped by a custom/proprietary
resource (for example, a style sheet). If selected, the WebGUI prompts
for the following property:
Custom URL
Provide a local or remote URL that locates the mapping
resource.
None Authentication credentials are not mapped.
Credentials from Tivoli Federated Identity Manager
The authentication credentials are mapped by Tivoli Federated Identity
Manager (TFIM). If selected, the WebGUI prompts for the following
property:

250 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 TFIM Configuration
Select an existing TFIM object. Refer to IBM Tivoli Federated
Identity Manager on page 272 for more information.
Credentials from WS-SecureConversation Token
The authentication credentials are mapped via a
WS-SecureConversation exchange.
AAA Info File
The authentication credentials are mapped using an XML file as the
mapping resource. If selected, the WebGUI prompts for the following
property:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml.
Open store://authfile.xml to examine a sample AAA Info file.
Apply XPath Expression
The authentication credentials are mapped using an XPath expression
as the mapping resource. If selected, the WebGUI prompts for the
following property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Resource tab
After authenticating a client, an AAA policy identifies the specific resource being
requested by that client.

Use the Resource panel to designate the methods used to identify the resource
requested by an authenticated client.
1. Click the Resource tab to display the AAA Policy Configuration (Resource)
screen.
2. Use the check boxes to enable (on) or disable (off) one or more resource
identification methods.
URL sent to back end
The identity of the requested resource is extracted from the (possibly
rewritten) URL sent to the server. The URL can be rewritten by a URL
Rewrite Policy attached to the service or by another processing action
before the AAA Policy.
URL sent by client
The identity of the requested resource is extracted from the original URL
sent by the client. This URL has not been rewritten.
URI of toplevel element in the message
The identity of the requested resource is extracted from the namespace of
the top level application element
Local name of request element
The identity of the requested resource is extracted from the simple name
of the top level application element

Appendix A. Referenced objects 251

 HTTP operation (GET/POST)
The identity of the requested resource is extracted from the HTTP method
of the client request
XPath expression
The identity of the requested resource is extracted from the client request
by an XPath expression. If selected, the WebGUI prompts for the
following property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Map Resource tab

After identifying the requested resource, it might be necessary to map extracted
resource identities to a form compatible with the authorization method.

If resource identity mapping is necessary, use the Map Resource panel to designate
the mapping method.
1. Click the Map Resource tab to display the AAA Policy Configuration (Map
Resource) screen.
2. From the Method list, select a resource mapping method.
Custom
The identified resource is mapped by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Provide a local or remote URL that locates the mapping resource.
None
Identified resources are not mapped.
AAA Info File
The identified resource is mapped using an XML file as the mapping
resource. If selected, the WebGUI prompts for the following property:
AAA Info File URL
Specify the location of the XML file used for authentication
purposes.
To identify a local resource, use the form store:///authfile.xml. To
examine a sample AAA info file, open store:///authfile.xml.
Apply XPath Expression
The identified resource is mapped using an XPath expression as the
mapping resource. If selected, the WebGUI prompts for the following
property:
XPath Expression
Specify the operative XPath expression.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

252 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Authorize tab
After authenticating a service requester and extracting the identity of the requested
resource, an AAA Policy next authorizes the client, that is, determines if the
authenticated service requester is allowed access to the requested resource. The
authorization process can use internal or external resources. Use the Authorize
panel to designate the authorization method.
1. Click Authorize to display the AAA Policy Configuration (Authorize) screen.
2. From the Method list, select an authentication method.
Allow Any Authenticated Client
Any authenticated used is authorized.
Contact ClearTrust Server
The requester is authorized via a ClearTrust server. If selected, the
WebGUI prompts for the following properties:
ClearTrust Server URL
Specify a local or remote URL that locates the authorization
resource.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Custom Template
The requester is authorized by a custom/proprietary resource (for
example, a style sheet). If selected, the WebGUI prompts for the following
property:
Custom URL
Specify a local or remote URL that locates the authorization
resource.
Check for Membership in an LDAP Group
The requester is authorized by an LDAP server. If selected, the WebGUI
prompts for the following properties:
Host
Specify the IP address or domain name of the LDAP authentication
server.
Port Specify the LDAP authentication server port number. If not
specified, defaults to the canonical port number.
Group DN
Specify the Distinguished Name of the LDAP group.
LDAP Load Balancer Group
Optionally select a Load Balancer Group. If a group is selected,
LDAP queries will be load balanced in accordance with the settings
in the group. Load balancing allows for failover when using LDAP
for authorization.
LDAP Bind DN
Specify the Distinguished Name for the LDAP Bind.
LDAP Bind Password and Confirm Bind Password
Specify and confirm the password for the LDAP Bind.

Appendix A. Referenced objects 253

 LDAP Group Attribute
Specify a GroupAttribute string. The authorizing identity must be
presented as the value that corresponds to the attribute.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
LDAP Search Scope
Select the depth of the LDAP search.
Base
Specifies that the search matches only the input itself
One Level
Specifies that the search matches the search input and any
object that is one-level below
Subtree
(Default) Specifies that the search matches the input and any
descendents
LDAP Search Filter
Optionally enable the specification of an LDAP search filter which
allows tailored LDAP searches. LDAP filter syntax is defined in RFC
2254, The String Representation of LDAP Search Filters.
Contact Netegrity SiteMinder
The requester is authorized by a Netegrity server. If selected, the WebGUI
prompts for the following properties:
Host
Specify the IP address or domain name of the Netegrity
authorization server.
Port Specify the Netegrity authorization server port number.
Netegrity Base URI
Specify the appropriate URI string.
Netegrity Operation Name Extension
The Netegrity Base URI is combined with the Host, Port, and
Netegrity Operation Name Extension configuration items to form
the URL for attempting Netegrity authentication. The URL is of the
following form:
http://Host:Port/NetegrityBaseURI/operationNetegrityOpNameExtension

where NetegrityOpNameExtension is directly appended to the

operation name.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Contact NSS for SAF Authorization
The requester is authorized by the SAF. If selected, the WebGUI prompts
for the following properties:

254 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 z/OS NSS Client Configuration
Select the z/OS NSS Client object that specifies the details for
connecting to the NSS server. Refer to z/OS NSS Client on page
353 for more information.
Default Action
Select the default action to specify the access level to the resource.
The default is r (Read). The value specified by this property can
be programmatically overridden by setting the
var://context/AAA/az-zosnss-operation variable to one of the
valid values.

a (Alter) r (Read)
c (Control) u (Update)

Always Allow
All messages are forwarded to the backend server.
Generate a SAML Attribute Query
The requester is authorized by a SAML attribute query/response
exchange between the DataPower appliance and a SAML server. If
selected, the WebGUI prompts for the following properties:
URL
Specify the location of the SAML server.
SAML Match
Select the minimum authorization criteria.
All Authorization requires the presence of all configured SAML
attributes
All-Values
Authorization requires that all configured attribute names
and values be present in the SAML attribute statement
Any Authorization requires the presence of a single SAML
attribute
Any-Value
Authorization requires that a single configured attribute
name and value be present in the SAML attribute statement
XPath Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specify the operative XPath expression.
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.

Appendix A. Referenced objects 255

 SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Generate a SAML Authorization Query
The requester is authorized by a SAML authorization query/response
exchange between the DataPower appliance and a SAML server. If
selected, the WebGUI prompts for the following properties:
URL
Specify the location of the SAML server.
SAML Match
Select the minimum authorization criteria.
All Authorization requires the presence of all configured SAML
attributes
All-Values
Authorization requires that all configured attribute names and
values be present in the SAML attribute statement
Any Authorization requires the presence of a single SAML attribute
Any-Value
Authorization requires that a single configured attribute name
and value be present in the SAML attribute statement
XPath
Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specifies the operative XPath expression
SAML Name Qualifier
Optionally specify the value of the NameQualifier attribute of the
NameIdentifier in the generated SAML query. Some SAML
implementations require this value to be present.
SAML Version
Select the SAML protocol version to use when employing SAML for
authorization. Versions 1.0, 1.1 and 2.0 are supported. The version
selected affects the format of the messages sent to SAML authorities.
SSL Proxy Profile
Select an SSL Proxy Profile to provide a secure connection to remote
authorization server. Retain the default value to use a non-SSL
connection.
Contact Tivoli Access Manager
The requester is authorized by a Tivoli Access Manager (TAM). A TAM
object must exist for this method to succeed. Refer to IBM Tivoli Access
Manager on page 270 for more information.
Use SAML Attributes from Authentication
The requester is authorized by the same SAML authentication or attribute
statements used to authenticate the requester. If selected, the WebGUI
prompts for the following property:
SAML Match
Select the minimum authorization criteria.

256 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 All Authorization requires the presence of all configured SAML
attributes
All-Values
Authorization requires that all configured attribute names
and values be present in the SAML attribute statement
Any Authorization requires the presence of a single SAML
attribute
Any-Value
Authorization requires that a single configured attribute
name and value be present in the SAML attribute statement
XPath Authorization requires that SAML server responses are
evaluated with an XPath expression
SAML XPath
If SAML Match is XPath, specifies the operative XPath expression
Use XACML Authorization Decision
The requester is authorized by an XACML Policy Decision Point (PDP),
which might be configured and located on the DataPower appliance, or
which might reside on a remote network appliance. If selected, the
WebGUI prompts for the following properties:
XACML Version
Select the XACML version (1.0 or 2.0, the default) used for
communications between the PDP and this AAA Policy, acting as an
XACML Policy Enforcement Point (PEP).
PEP Type
Select how the AAA Policy, acting as an XACML PEP, processes the
PDP authorization response.
Base PEP
If the XACML response to the authorization request is
permit, the client is authorized; if the permit response is
accompanied by obligations, the client is authorized only if
the AAA Policy, acting as a PEP, can understand and
discharge the conditions.
If the XACML response to the authorization request is deny,
the client is rejected; if the deny response is accompanied by
obligations, the client is rejected only if the AAA Policy,
acting as a PEP, can understand and discharge the
conditions.
Deny-biased PEP
If the XACML response to the authorization request is
permit, the client is authorized; if the permit response is
accompanied by obligations, the client is authorized only if
the AAA Policy, acting as a PEP, can understand and
discharge the conditions.
Any other XACML response results in the clients rejection.
Permit-biased PEP
If the XACML response to the authorization request is deny,
the client is rejected; if the deny response is accompanied by

Appendix A. Referenced objects 257

 obligations, the client is rejected only if the AAA Policy,
acting as a PEP, can understand and discharge the
conditions.
Any other XACML response results in the clients
authorization.
Use On Box PDP
Use this toggle to specify the location of the PDP.
on (Default) Specifies use of a local PDP. If selected, the WebGUI
displays the following property:
Policy Decision Point
Select the PDP to provide authorization services for the
AAA Policy. Refer to XACML Policy Decision Point on
page 277 for more information.
off Specifies the use of a remote XACML PDP. If selected, the
WebGUI displays the following property value:
URL of External Policy Decision Point
Specify the URL to which to send XACML-based
authorization requests.
PDP Requires SAML 2.0
Use this toggle to force the use of the SAML2.0 Profile.
Meaningful only when the XACML version is 2.0.
on Forces the use of the SAML2.0 profile.
off (Default) Does not require the use of the SAML2.0
profile.
SOAP Enveloping
Use the toggle to determine whether the external PDP
requires SOAP enveloping. If the custom binding style
sheet generated SOAP enveloping, retain the default
setting.
on Before the PEP posts the context request to the
external PDP with the HTTP POST method, the
SOAP Body of the content request is wrapped by
the <xacml-samlp:XACMLAuthzDecisionQuery> SAML
Profile element.
off (Default) The PEP posts the context request to the
external PDP with the HTTP POST method.
This property can be combined with the PDP Requires
SAML 2.0 property when the XACML request is
wrapped by the <xacml-samlp:XACMLAuthzDecisionQuery>
SAML Profile element.
AAA XACML Binding Method
Retain the default value, which is the only supported option.
Custom Stylesheet to Bind AAA and XACML
Select the custom style sheet that maps the AAA result or input
message to the XACML context request. This context request
contacts the PDP for an XACML decision.

258 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Obligation Fulfillment Custom Stylesheet
Specify the custom style sheet to parse any obligation that
accompany an authorization decision that is received from the PEP.
AAA Info File
The requester is authorized by an XML file. If selected, the WebGUI
prompts for the following property:
AAA Info File URL
Specify the location of the XML file used for authorization purposes.
To identify a local resource, use the form store:///authfile.xml. To
example a sample AAA Info file, open store:///authfile.xml.

The following inputs appear for all methods.

Cache authorization results
Select the caching strategy. By default, authorization information from
remote resources is cached for a period of three seconds. On authorization
failure, authorization information is removed from the cache.
Absolute
(Default) Caches all authorization data with an explicit TTL
(time-to-live), specified by the Cache Lifetime property
Disabled
Disables caching of authorization data
Maximum
Compares the explicit TTL with the received TTL (if any). Use the
data-specific TTL if it is less than the explicit TTL. Otherwise, use
the explicit value.
Minimum
Compares the explicit TTL (specified by the Cache Lifetime
property) with the received TTL (if any). Use the data-specific TTL if
it is greater than the explicit TTL. Otherwise, use the explicit value.
Cache Lifetime
Specify the explicit TTL in seconds. Defaults to 3.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Post Processing tab

After authorizing the client, an AAA Policy can perform postprocessing activities.
For example, it could generate a SAML authentication assertion and place that
assertion in the header of the message.

Use the Post Processing panel to specify postprocessing behavior.

1. Click the Post Processing tab to display the AAA Policy Configuration (Post
Processing) screen.
2. Provide the following inputs:
Run custom post processing stylesheet
Select whether to enable (on) or disable (off) custom (style sheet-based)
postprocessing. If selected, the WebGUI prompts for the following
property:

Appendix A. Referenced objects 259

 Custom URL
If custom post processing is enabled, specify a local or remote
URL that locates the style sheet.
Generate SAML Authentication Assertion
Select whether to enable (on) or disable (off) the generation of SAML
authentication assertions. If selected, the WebGUI prompts for the
following properties:
Issuer for generated SAML assertions
If generation of SAML authentication assertions is enabled,
Optionally specify the assertion originator or retain the default
value, XS.
SAML Name Qualifier
If generation of SAML authentication assertions is enabled,
Optionally specify a NameQualifier as defined by the SAML
protocol version selected.
SAML Version
If generation of SAML authentication assertions is enabled,
select the SAML protocol version to use when employing
SAML for authentication. Versions 1.0, 1.1 and 2.0 are
supported. The version selected affects the format of the
messages sent to SAML authorities.
Include a WS-Security Kerberos AP-REQ token
Select whether to enable (on) or disable (off) the inclusion of a
WS-Security Kerberos AP-REQ token, attesting to the authenticity of the
requesting client, in the appliance transmission to the target server. If
selected, the WebGUI prompts for the following properties:
Kerberos client principal
Provide the name part of the clients identity (the client name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos client password
If obtaining a Kerberos ticket for the requesting client, specify
the client Kerberos password (the shared secret known only to
the requesting client and the Kerberos Key Distribution Center).
Specify the shared secret in the upper field and confirm the
entry in the lower field.
Kerberos server principal
Provide the name part of the servers identity (the server name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Client Keytab
Provide the location of the Kerberos keytab.
Generate requested WS-Trust token
Set to on to generate a WS-Trust token after authentication and
authorization has taken place. This token can serve as
WS-SecureConversation token. If selected, the WebGUI prompts for the
following properties:
Generate token timestamp
If generation of WS-Trust tokens is enabled, set to on to
generate a WS-Trust token timestamp.

260 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Allow WS-Trust token renewal
If generation of WS-Trust tokens is enabled, set to on to allow
for the renewal of the WS-Trust token.
Send SAML Logout Message (SAML 2.0 only)
Click on to enable SAML Version 2.0 Single Logout. If selected, the
WebGUI prompts for the following properties:
SAML Logout Message Session Authority
Specify the URL of the SAML authority to which to send the
logout message.
SSL Proxy Profile
Optionally select the SSL Profile to support a secure connection
to the SAML authority.
Add WS-Security UsernameToken
Select whether to enable (on) or disable (off, the default) the inclusion
of a WS-Security UsernameToken in the server-bound message. If
selected, the WebGUI prompts for the following properties:
WS-Security UsernameToken Password Type
Select the password type.
Text The actual password for the user name, the password
hash, or derived password
Digest The digest of the password as specified in Web Services
Security UsernameToken Profile 1.0
Include Password
Select whether to enable (on) or disable (off) the inclusion of
the password in the WS-Security Username Token.
Generate an LTPA Token
Add an LTPA Token to the HTTP headers transmitted to the server. If
selected, the WebGUI prompts for the following properties:
LTPA Token Version
Select the token version/type.
Domino LTPA
Used in Lotus environments
WebSphere Version 1 LTPA
Used in WebSphere environments
WebSphere Version 2 LTPA
(Default), Used in WebSphere environments (introduced
in WebSphere Application Server version 5.1.0.2, for
z/OS, and version 5.1.1, for other platforms)
LTPA Token Expiry
Specify the LTPA token lifetime (the number of seconds from
the cookie creation to its expiration).
LTPA Key File
Specify the name of the file that contains the cipher keys used
for encryption and decryption.
LTPA Key File Password and Confirm LTPA Key File Password
Provide and confirm the cleartext password to the LTPA key
file. Refer to Understanding LTPA for more information.

Appendix A. Referenced objects 261

 Generate a Kerberos SPNEGO Token
Add an Kerberos SPNEGO token to be inserted into the
WWW-Authenticate HTTP header sent to the target server. If selected,
the WebGUI prompts for the following properties:
Kerberos Client Principal
Specify the name part of the clients identity (the client name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Server Principal
Specify the name part of the server identity (the server name
contained in the cname field of the unencrypted portion of the
Kerberos ticket).
Kerberos Client Keytab
Specify the location of the Kerberos keytab. Refer to
Understanding SPNEGO for more information.
Request TFIM Token Mapping
Select whether to enable or disable token mapping by IBM Tivoli
Federated Identity Manager (TFIM). If enabled, the WebGUI prompts
for the following property:
TFIM Configuration
Select an existing TFIM object. Refer to IBM Tivoli Federated
Identity Manager on page 272 for more information.
3. Click Apply to commit AAA Policy properties.
4. Optionally, click Save Config to save the object to the startup configuration.

Namespace Mapping tab

An AAA Policy can use XPath expressions as it processes client requests
specifically XPath expressions can be used while:
v Identifying service requestors
v Mapping authentication credentials
v Identifying requested resources
v Mapping requested resources
v Authorizing an authenticated service requestor

Use the Namespace Mapping panel to provide namespace mappings that might be
required by XPath expressions.
1. Click the Namespace Mapping tab to display the AAA Policy Configuration
(Namespace Mapping).
2. Click Add to display the Namespace Mapping Property window.
3. Provide the following inputs:
Prefix Specify the namespace prefix.
URI Specify the namespace URI.
4. Click Save to return to the AAA Policy Configuration (Namespace Mapping).
5. Click Apply to commit AAA Policy properties.
6. Optionally, click Save Config to save the object to the startup configuration.

262 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
SAML Attributes tab
Use the SAML Attributes panel to provide SAML attribute namespace data. These
attribute name mappings and attribute values can be used for authentication and
authorization.
1. Click the SAML Attributes tab to display the AAA Policy Configuration
(SAML Attributes).
2. Click Add to display the SAML Attributes Property window.
3. Provide the following inputs:
Namespace URI
Specify the attribute namespace URI.
Local Name
Specify the attribute name.
Attribute Value
Specify the appropriate value.
4. Click Save to return to the AAA Policy Configuration (SAML Attributes).
5. Click Apply to commit AAA Policy properties.
6. Optionally, click Save Config to save the object to the startup configuration.

LTPA Attributes tab

The WebSphere Version 1 and Version 2 LTPA tokens, but not the Domino LTPA
token, can optionally contain an extended attribute field, consisting of an arbitrary
list of name-value pairs. Such pairs provide a means to transmit additional
information about the cookie subject to applications which can decrypt the cookie.
Such information, for example, can identify the server which authenticated the
user, or specify various user-associated LDAP attributes. If desired, you can use the
following procedure to add name-value pairs to the LTPA token.
1. Click the LTPA User Attributes tab to display the LTPA User Attributes catalog.
2. Click Add to display the LTPA User Attributes Property window.
a. Specify the attribute name in the LTPA User Attribute Name field.
b. Select the method to assign a value to this attribute from the LTPA User
Attribute Type field.
Static (Default) Use the value explicitly assigned by the value for the
LTPA User Attribute Static Value property
XPath Use an XPath expression to set the value dynamically
c. If XPath is selected, the expression specified in the LTPA User Attribute
XPath Value is evaluated against the input context of the AAA action with
the result of the evaluation assigned as the value portion of the name-value
pair at runtime.
d. Use the LTPA User Attribute Static Value property (meaningful only when
the attribute type is set to Static) to explicitly set the value assigned to
LTPA User Attribute Name
e. Use the LTPA User Attribute XPath Value property (meaningful only when
the attribute type is set to XPath) to provide the XPath expression used to
extract a value dynamically assigned to LTPA User Attribute Name.
To assist in creating the XPath expression, click XPath Tool. This tool allows
you to upload an XML document and build the expression by pointing at
the desired node.
If the defined expression contains namespace elements, you can click XPath
Binding to provide namespace/prefix data.

Appendix A. Referenced objects 263

 Refer to Setting namespace mappings (XPath bindings) for more
information.

Transaction Priority tab

Click the Transaction Priority tab to display the Transaction Priority catalog.

Click Add to display the Transaction Priority Property window.

1. Specify the name of the mapped credential in the Credential Name field.

Note: You might need to use the multistep probe to determine the string for
the mapped credential.
2. Select the priority of the transaction from the Transaction Priority list. The
default is Normal.
3. Select whether to require authorization with the Require Authorization toggle.
The default is off.
4. Click Save to return to the catalog.

Setting namespace mappings (XPath bindings)

If you need to provide namespace data for XPath expressions, use the following
procedure:
1. Click XPath Bindings to display the XPath Bindings catalog.
2. Click Add to display the Namespace Property window.
a. Specify the namespace prefix in the Prefix field.
b. Specify the namespace URI in the URI field.
c. Click Save to return to the XPath Bindings catalog.
3. If necessary, repeat the step 2 to add additional namespace mappings.
4. Click Done to complete the namespace mapping.
5. Click Commit. This commits all changes to the AAA Policy under construction
or modification.
6. Click Done to close the confirmation window.

Defining SAML attributes

To define SAML attributes, use the following procedure:
1. Click SAML Attributes to display the SAML Attributes catalog.
2. To create new SAML attribute, click Add.
3. Define the following properties:
Namespace URI
The URI for the namespace of the Local Name.
Local Name
The local attribute name. This name can be used for matching.
Attribute Value
The attribute value. This value can be used for matching.
All of these fields are optional, depending on the specific context or the SAML
Match Type selected.
4. Click Save to save the configuration.
5. Repeat step 2 through step 4 to create as many SAML attributes as needed.
6. After defining all SAML attribute, click Done.

264 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Adding LTPA user attributes
To add name-value pairs to the LTPA token, use the following procedure:
1. Click LTPA User Attributes to display the catalog.
2. Click Add to display the LTPA User Attributes window.
3. Provide the following inputs:
LTPA User Attribute Name
Specify the name of the attribute.
LTPA User Attribute Type
Select the type of attribute.
Static (Default) Use the explicitly assigned value.
XPath Use an XPath expression to set the value dynamically. If
selected, the expression is evaluated against the input context of
the AAA action with the result of the evaluation assigned as
the value portion of the name-value pair at runtime.
LTPA User Attribute Static Value
Meaningful only when the type is Static. The explicit value of the
attribute.
LTPA User Attribute XPath Value
Meaningful only when the type is XPath. The XPath expression used to
extract a value dynamically.
For assistance in creating the XPath expression, click XPath Tool. This
tool allows you to load an XML document and build the expression by
selecting the desired node.
If the defined expression contains namespace elements, click XPath
Binding to provide namespace/prefix data. Refer to Setting
namespace mappings (XPath bindings) on page 264 for more
information.

Using an AAA Info file

AAA Info File
An AAA Info file can be selected as the method for the following steps of an AAA
policy:
v Authenticate
v Map Credentials
v Map Resource
v Authorize

The AAA Info XML file has the following basic structure, which mirrors the steps
of an AAA Policy. The following is a reproduction of the AAAInfo.xsd file in the
store: directory.
<xsd:element name="Authenticate" type="tns:AuthenticateType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapCredentials" type="tns:MapCredentialsType"
maxOccurs="unbounded">
</xsd:element>
<xsd:element name="MapResource" type="tns:MapResourceType"
maxOccurs="unbounded">

Appendix A. Referenced objects 265

 </xsd:element>
<xsd:element name="Authorize" type="tns:AuthorizeType"
maxOccurs="unbounded">
</xsd:element>

Note: Any given XML File could be used for one or more of these operations.
Only the part of the file that supports the desired operation needs to be
completed. For example, if the file is only used for Map Credentials, it does
not need to include an Authenticate, Map Resource, or Authorize section.

The schema for an AAA Info file uses the AAAInfo.xsd file in the store: directory.

One or more XML files could be used for these operations. In each case, the field
that offers the ability to select an XML file has the + and ... buttons. These buttons
allow for the creation of a new XML file or the editing of an existing XML file,
respectively. Clicking either of these buttons launches the AAA Info File Editor.
Refer to AAA Info File editor on page 267 for more information.

Note: The AAA Info file can be edited outside of the AAA Info File Editor and
uploaded to the appliance.

Authenticate element: The Authenticate element or elements contain the

database of identities that can be authenticated by this file. Identities can be
identified by one or more of the following attributes:
v User name
v Password
v IP address or host name
v IP network
v Distinguished name (DN)
v Custom token

Each identity is given a credential by this element.

MapCredentials element: The MapCredentials element takes in a credential string

and maps it to another. The input can be matched by a PCRE regular expression.
This element can be fed directly from an Authenticate element contained in this
file. Usually, however, this element is used to map an identity extracted from a
message to another identity more meaningful to the authorization method.

MapResource element: The MapResource element takes in a resource string

extracted from the message and maps it to another, perhaps more meaningful to
the authorization method. Input resources can be one or more of the following
types:
v Original (client) URL
v URL sent to server (target URL)
v SOAP Operation Namespace (request URI)
v SOAP Operation Name (request operation)
v HTTP method
v Token extracted by XPath

These resource inputs map to Resource Extraction methods used by the AAA
Policy. The input resource name can be matched by a PCRE regular expression.

266 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Authorize element: The Authorize element takes in a Credential and a Resource
and returns an access status (allow or deny). Both the Credential and the Resource
can be matched by a PCRE regular expression.

AAA Info File editor

The AAA Info File Editor, launched by the WebGUI, steps through each of these
sections in an AAA Info file and helps to configure them. Click Next or Back to
move between pages.

The AAA Info File Editor has the following pages:

v Default credential (unauthenticated identity)
v Credentials (authenticated identities)
v Map credentials
v Map resources
v Authorized access to resources
v File information

At any point, click Cancel to abandon all changes and close the file editor.

Default credential (unauthenticated identity): The initial screen presents the

opportunity to set the default credentials for unauthenticated identities. This is the
credential assigned to identities for which no other credential can be found in the
Authenticate section. If left blank, all unauthenticated identities are denied access.

Credentials (authenticated identities): The authenticated identities page provides

a list of identities that are authenticated by this file. When creating a new file, none
are initially listed.

Click Next if this file will not be used for authentication. Click Add to create new
identities that this file can authenticate. A new window opens with a form for
adding identities.
Host Name or IP Address
The host name or IP address of the client that submitted the message. The
IP address takes dotted decimal form w.x.y.z. The entry 0.0.0.0 (or 0) is
not allowed.
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the IP Network field.
IP Network
The IP network of the client that submitted the message. This entry takes
the form x.y.z.a/b (for example 192.168.2.25/24).
v Use this field only when the identity extraction method is set to Client
IP address.
v If this field is used, you cannot use the Host Name or IP Address field.
User name
The user name extracted from the message. User names can be extracted
from messages in a number of ways, including HTTP Basic Authentication,
WS-Security UserName, and Name from SAML headers. If those AAA
Policy identity extraction methods are not used, do not use this field.
Password
The password extracted from the message. Passwords can be extracted
from messages by HTTP Basic Authentication and WS-Security UserName.

Appendix A. Referenced objects 267

 If the Identity Extraction method used by the AAA Policy does not use
either of these methods, do not use this field.
Distinguished Name
The DN extracted from the message. The AAA Policy identity extraction
methods Subject DN from SSL certificate or Subject DN from SAML
signature return this value. If those methods are not used, do not use this
field.
Custom token
A custom token is extracted from the message. The AAA Policy identity
extraction methods Token extracted from the message and Token extracted
as cookie value return this value. If those methods are not used for
extraction, do not use this field.
Credential Name
The credential returned by the authentication. This can be the same as the
extracted identity or different. The value should be meaningful either to
the AAA Policy Map Credentials method or to the AAA Policy Authorize
method.

All of the fields that contain information must be matched for the authentication to
succeed. If the identity extraction method returns only a user name (such as with
SAML) and the Authenticate Identity entry contains both user name and password,
authentication will fail. The AAA policy, however, tests an extracted identity
against all entries in the order in which they are listed, stopping after it finds a
complete match. It is possible to create one entry for user name Bob that also has a
password of foo and another with no password entry. Should the extraction
method only retrieve the user name and not the password, Bob will still
authenticate.

Map credentials: The Map Credentials page presents a list of all credential maps
contained in the file. When creating a new file, this list is empty.

Click Next to move to the next page if this file will not be used for mapping
credentials. Click Add to create a new credential map.
Input Credential
The credential input to the mapping. This field accepts PCRE expressions,
allowing a single expression to match more than one input credential.
Entering foo causes the AAA policy to match all input credentials that
contain the string foo.
Credential Name
The credential to output in place of the input credential. This is the value
to which the input credential is mapped. This is not a regular expression.

Click Submit to add the new map to the list of maps. Create as many mapping
entries as needed by clicking Add for each new entry.

Note: If this file is used for mapping credentials, any input credential that does
not match a map is converted to a blank credential for the purposes of
authorization.

Map resources: The Map Resource page presents a list of all resource mappings
contained in the file. Resource mapping is used to map the resource identifier
extracted from the message to something else. If the AAA Policy uses more than
one resource extraction method, all methods will be executed.

268 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Click Next if this file will not be used for resource identity mapping. Click Add to
create a new map.
Original URL
The URL sent by the client submitting the message. This is a PCRE
expression.
Target URL
The URL used to send the message to the back end server, after the
firewall URL Rewrite Policy has executed. This is a PCRE expression.
Request URI
The Namespace URI of the action or method requested in the body of the
SOAP message. This is identified as the topmost element in the SOAP:Body
element.
Request Operation
The name of the operation requested in the body of the SOAP message.
HTTP Method
Select the desired method. Select any to allow any method.
Result of XPath Expression
Any value that is extracted from the message by an XPath expression. This
is a PCRE expression.
Resource
The resource string to which the input resource is mapped. This field is
required.

Note: If this file is used for mapping resources, any resource that does not mapped
by the file will be converted to a blank resource for the purposes of
authorization.

Authorized access to resources: The Authorize page presents a list of all

authorization pairs contained in this file. Authorization is based on an input
credential (after mapping, if any) and an input resource (after mapping, if any).

If this file is not used for authorization, click Next. To create an authorization entry,
click Add.
Credential
The credential to match for authorization. This field accepts PCRE
expressions.
Resource
The resource to match for authorization. This field accepts PCRE
expressions.
Access
Select allow or deny as the authorization result.

Note: When this file is used for authorization, access is denied by default. Any
unmatched entries result in denied access. Access is allowed only if a match
is found and the Access for that match is allow.

File Information: The file information page provides a means to name the file
and add a comment if desired.

This file is typically placed in the local: directory.

Appendix A. Referenced objects 269

 Confirmation: The last page of the reflects the name of the file and offers the
opportunity to make changes or save the changes to the file.
v Click Cancel to abandon all changes and close the window.
v Click Back to move backward through the file to make any additional changes
needed.
v Click Commit to save the file and close the window.

IBM Tivoli Access Manager

Integrating with IBM Tivoli Access Manager (TAM) allows a user to be
authenticated using a simple user name and password. Authorization decisions are
made for an authenticated user on a resource and an operation. Only authenticated
users can receive an authorization decision. In this case, a resource is passed as a
string.

Note: Integration with TAM requires the presence of a license on the DataPower
appliance.

An AAA Policy object can use TAM for both authentication and authorization. The
AAA policy will not succeed with TAM without first configuring an instance of the
TAM object with at least one authorization server replica.

Tivoli Access Manager configuration

Configuration consists of creating a TAM client configuration file and configuring a
TAM object. The configuration files specify the network and security configuration
for the policy server, replica authorization servers, and the LDAP (directory) server.
During object configuration, the TAM configuration files must reside on the
appliance.

Although native TAM supports both local and remote clients, the appliance
supports only remote client operations. The TAM configuration supports only one
policy server and supports only LDAP directories. Although the configuration files
allow specifications for Microsoft Active Directory and Lotus Domino, the
appliance does not support these directory servers.

Tivoli Access Manager security

The TAM client supports LDAP along with the proprietary IBM protocol. SSL keys
and certificates must be in the proprietary IBM CMS database format and must be
uploaded to the appliance. The configuration files identify the location of these
files. You do not need to create Key objects or Certificate objects. The files can be
placed in the encrypted cert: or sharedcert: flash directories.

Creating TAM configuration files

Before configuring a TAM object, you need to have the TAM configuration files on
the appliance. Both the ASCII and obfuscated versions of the configuration files are
needed. You can create TAM configuration files either on the appliance or using
the native TAM configuration utilities.

The following files are needed to create the TAM object or are created using the
appliance:
v The ASCII version of the configuration file (.conf extension)
v The obfuscated version of the configuration file (.conf.obf extension) using the
same file name as the ASCII version
v The TAM SSL key file (.kdb extension)
v The TAM SSL stash file (.sth extension)

270 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Notes:
v If you use the native TAM configuration utilities to create the
configuration files, you might need to modify them before creating the
TAM object.
v During the creation of TAM object, you might need to upload the SSL
key file for the LDAP server (.kdb extension). When using secure
communication, ensure that this file is on the workstation.

Modifying native TAM configuration files: When the configuration files are
generated by the native TAM utilities, you might need to make the following
modifications:
v Unless the LDAP key stash file is uploaded to the appliance, modify the TAM
configuration file by defining the ssl-keyfile-pwd entry in the [ldap] stanza.
v The TAM object needs at least one authorization server replica. You can create
authorization server replicas during the creation of the TAM object, or you can
define replica entries in the [manager] stanza. When defined in the
configuration file, the replicas are not shown in the Authorization Server Replica
catalog.
v Ensure that the obfuscated version of the configuration file is on the workstation
and is the same name as the ASCII version. If not the same name, ensure that
the file entry in the [configuration-database] stanza defines the location of
the obfuscated version of the configuration file on the appliance.

Creating configuration files on the appliance: To create a TAM configuration file:

1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to
display the action screen.
2. Define the operational properties. Refer to the online help for details.
3. Click Create Tivoli Access Manager Configuration.
4. Follow the prompts.

The ASCII version and the obfuscated version of the TAM configuration files are
stored in the local: directory. The key file and the stash file that TAM uses are
stored in the cert: directory. If you set the Create File Copies to Download
property to on, copies of the key file and the stash file are stored in the temporary:
directory.

Creating and configuring TAM objects

After creating the TAM configuration, key, and stash files, you can now create and
configure a TAM object. Each TAM object requires at least one authorization server
replica. A replica indicates the network location of a remote TAM authorization
server. If necessary, configure additional replicas for failover purposes.

To create and configure a TAM object:

1. Select Objects Access IBM Tivoli Access Manager to display the catalog.
2. Click Add to display the configuration screen.
3. Define the operational parameters. Refer to the online help for details.
4. Define at least one authorization server replica.
a. Click the Authorization Server Replica tab.
b. Define a replica.
1) Click Add to display the properties window. Use this window to specify
the operational parameters.
2) Define the operational parameters. Refer to the online help for details.

Appendix A. Referenced objects 271

 3) Click Save.
c. If necessary, repeat the previous step to create another replica.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Refreshing certificates
Refreshing Tivoli Access Manager (TAM) certificates first refreshes the password of
the keystore associated with the TAM object and then refreshes the client certificate
in the keystore with the configured TAM server. The clients associated with this
configuration and any other configuration which use the same keystore will be
stopped if running and restarted when the refresh is complete.

To refresh certificates:
1. Select Administration Miscellaneous IBM Tivoli Access Manager Tools to
display the action screen.
2. Click the Refresh Tivoli Access Manager Client Certificate tab.
3. Define the operational properties. Refer to the online help for details.
4. Click Refresh Tivoli Access Manager Client Certificate.
5. Follow the prompts.

IBM Tivoli Federated Identity Manager

DataPower appliances integrate with IBM Tivoli Federated Identity Manager
(TFIM) through the exchange of WS-Trust SOAP messages. The TFIM management
object centralizes the configuration of the TFIM endpoint and prevents parameter
duplication between the Map Credential and the Post Processing phases in an
AAA Policy. During the Map Credential phase, an authenticated identity can be
mapped to the identity for authorization. During the Post Processing phase, an
authorized identity can be mapped to the output AAA identity.

When integrating with TFIM, the provided input credentials must be able to be
expressed in the request token format for the TFIM endpoint. For example, a
WS-Security Username token as the request token cannot be created when the
available user credential is an X.509 certificate.

Creating the TFIM object

To create and configure a TFIM object, use the following procedure:
1. Use the Objects Access Settings IBM Tivoli Federated Identity Manager
menu path to display the IBM Tivoli Federated Identity Manager catalog.
2. Click Add to display the IBM Tivoli Federated Identity Manager configuration
screen. Use this screen to specify operational parameters.
a. Specify the name for the object in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Specify the host name or IP address of the TFIM server in the Server field.
e. Specify the port number of the TFIM server in the Port field. The default is
9080.
f. Select the currently configured version of TFIM from the Compatibility
Mode list. The value determines the details for the namespace and WS-Trust
messages.

272 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Note: Selecting Version 6.2 as the compatibility mode will cause the TFIM
client/endpoint to generate WS-Trust messages using version 1.3 of
the WS-Trust specification. In this case, trust chains in the TFIM 6.2
server must use the Validate OASIS URI as the Request Type. To use
WS-Trust version 1.2 messages with a TFIM 6.2 server, select TFIM 6.1
as the compatibility mode. If the 6.1 compatibility mode is selected,
TFIM 6.2 will behave the same as TFIM 6.1.
Version 6.0
Indicates Tivoli Federated Identity Manager, version 6.0.
Version 6.1
(Default) Indicates Tivoli Federated Identity Manager, version 6.1.
Version 6.2
Indicates Tivoli Federated Identity Manager, version 6.2.
g. Select the format of the request token from the Request Token Format list.
The available formats depend on the selected value for Compatibility
Mode.
v If Version 6.0, the following formats are available:
Custom
Indicates a custom style sheet for generating the TFIM request.
When selected, requires the specification of a Custom Request.
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 1.1
Indicates a SAML Assertion 1.1.
Username Token
(Default) Indicates a WS-Security Username Token Type.
v If Version 6.1 or Version 6.2, the following formats are available:
Binary Security Token
Indicates a WS-Security BinarySecurityToken.
Custom
Indicates a custom token. When selected, requires the
specification of a Custom Request.
Custom Token
Indicates a custom token.
SAML 1.0
Indicates a SAML Assertion 1.0.
SAML 1.1
Indicates a SAML Assertion 1.1.
SAML 2.0
Indicates a SAML Assertion 2.0.
Kerberos Token
Indicates a WS-Security Kerberos Token.
Username Token
(Default) Indicates a WS-Security Username Token Type.
X.509 Token
Indicates a WS-Security X.509 Token.

Appendix A. Referenced objects 273

 h. When using TFIM 6.0, TFIM 6.1, or TFIM 6.2 and when Request Token
Format is Custom, select the location of the custom style sheet in the
Custom Request field. The custom style sheet file must be in the local: or
store: directory. Click Upload or Fetch to upload the custom style sheet file.
i. When Request Token Format is not Custom, define the following properties:
1) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the scope for this
security token in the Applies-To Address field. For example, specify the
services to which this token applies:
http://tfim.ibm.com:9080/EchoApplication/Services/EchoServiceUser
http://9.33.97.251:9080/EchoApplication/Services/EchoServiceUser
In the TFIM service, this information specifies the destination of the
request. The TFIM trust service uses this information to determine which
trust chain to invoke. To determine the correct value, consult your TFIM
administrator.
2) When using TFIM 6.0, TFIM 6.1, or TFIM 6.2, specify the identity that
issued the request in the Issuer field. For example, in the TFIM
WS-Security Management (WSSM) component, the Issuer is either the
WSSM token generator or the WSSM token consumer:
urn:itfim:wssm:tokenconsumer
The TFIM trust service uses this information to determine which trust
chain to invoke. To determine the correct value, consult your TFIM
administrator.
3) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the
Web services port type to use in the Port Type field. A port type is a
group of Web services operations. For example:
EchoService
The TFIM trust service uses this information to determine which trust
chain to invoke with finer granularity. If a value is not specified, a
default value of NotSpecified is used. To determine the correct value,
consult your TFIM administrator.
4) When using TFIM 6.1 or TFIM 6.2, optionally specify the name of the
Web services operation to use in the Operation field. For example:
echo
The TFIM trust service uses this information to determine which trust
chain to invoke with finer granularity. If a value is not specified, a
default value of NotSpecified is used. To determine the correct value,
consult your TFIM administrator.
j. From the SSL Proxy Profile list, select an SSL Proxy Profile to manage
secure communications with the peer.
k. Use the Schema Validate Response toggle to specify whether to
schema-validate responses from the TFIM server. When enabled, TFIM
responses are schema-validated with the WS-Trust version that is defined by
the compatibility mode.
on Responses are schema-validated.
off (Default) Responses are not schema-validated.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Working with Kerberos objects

A basic description of the Kerberos authentication protocol is helpful for
understanding the support provided by the DataPower appliance.

274 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
The Kerberos authentication protocol uses a star topology. The Key Distribution
Center (KDC) is at the center of the star. Each Kerberos principal (a human, a
computer client, or an instance of a service running a specific computer) is
registered with the KDC and has a shared secret known only to the principal and
to the KDC. This shared secret takes the form of a password for human principals
and a randomly generated keytab file for nonhuman principals.

When a Kerberos client (for example, Alice) wants to communicate securely with a
Kerberos server (for example, the FTP service), Alice must access KDC of her
Kerberos realm and request a ticket for the FTP service. At this point, the KDC has
the option of requiring pre-authentication before responding, or the KDC can
immediately issue the ticket to Alice.

The KDC response contains two items:

v A randomly generated session key encrypted with Alices shared secret
v A ticket for the FTP service

The ticket contains:

v The idobj for Alice
v The idobj for the FTP service
v A ticket lifetime
v Another copy of the session key

The ticket is encrypted with the shared secret of the FTP service principal.
Consequently, there are two encrypted copies of the session key (one for Alice, and
one for the FTP service).

At this point, Alice uses her shared secret to decrypt her copy of the session key
and generates an authenticator (which proves that the person talking to the FTP
service is the client for which this ticket was issued, and not a malicious user
replaying a previously issued ticket) that she sends along with her ticket to the
FTP service. The ticket plus authenticator is called an AP-REQ message.

When the FTP service receives the AP-REQ from Alice, it decrypts the ticket and
verifies the authenticator. At this point the FTP server has authenticated Alice, and
they share a session key which can be used to secure the rest of their
communications.

Points to remember when using Kerberos

When using Kerberos, keep the following points in mind:
v Both clients and servers are principals in the KDC database. More accurately,
services running on server computers are principals in the KDC database.
v A client principal must request a separate ticket for each server with which it
communicates.
v Services must have a name and shared secret registered with the KDC.
v A service must have access to its shared secret to decrypt Kerberos tickets.
v A Kerberos ticket that is issued by a KDC contains the cryptographic material
that allows both the client and the server to generate the same session key.
v All Kerberos cryptographic operations are symmetric in nature.
v In an AAA Policy, Kerberos is an idobj extraction, authentication protocol, or
both.
v Kerberos is not an authorization protocol.

Appendix A. Referenced objects 275

 There is no restriction in Kerberos that specifies which clients can request tickets
for a particular service.

Note: Microsoft Windows, when configured to use an Active Directory domain, is

based on a security infrastructure that is, at its core, Kerberos. As of
Windows 2000, authentication in a Windows domain is handled by
Kerberos. Such authentication is entirely transparent to the user. Refer to
Understanding SPNEGO for implementation details.

Kerberos KDC Server objects

Use the following procedure to configure a Kerberos KDC Server:
1. Select Objects Crypto Kerberos KDC server to display the Kerberos KDC
Server catalog.
2. Click Add to display the Kerberos KDC Server configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Kerberos realm name
Specify the name of the Kerberos realm that is serviced by this KDC.
There is exactly one KDC per Kerberos realm.
Kerberos KDC Server
Specify the host name or IP address of the KDC server. Click Ping to
verify connectivity.
Use TCP
Select whether to use UDP or TCP as the Transport Layer protocol to
access the KDC server.
on Use Transmission Control Protocol (TCP)
off (Default) Use User Datagram Protocol (UDP)
Server Port Number
Specify the UDP or TCP port that is monitored by the KDC for incoming
Kerberos requests. The default is 88.
UDP Timeout
When the Transport Layer protocol is UDP, specify the UDP timeout.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Kerberos Keytab File objects

A Kerberos Keytab file contains the keys needed to decrypt the ticket presented by
a client attempting to obtain services. Previously, only a password was required.
This has been changed to an encrypted key for added security. The Kerberos
Keytab File object identifies the file that contains the keys needed to decrypt the
ticket.

Use the following procedure to configure a Kerberos Keytab File:

276 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 1. Select Objects Crypto Kerberos Keytab to display the Kerberos Keytab
catalog.
2. Click Add to display the Kerberos Keytab Configuration screen.
3. Provide the following inputs:
Name
Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
File Name
Select the keytab file. This list includes files that are stored in the
encrypted and protected cert: directory of the appliance. If the file does
not reside on the appliance, click Upload or Fetch to transfer the file.

Note: This file is not generated on the DataPower appliance. It is

generated through the Kerberos system itself.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

XACML Policy Decision Point

During the authorization phase of an AAA Policy, you can select Use XACML
Authorization Decision. The AAA Policy acts as an XACML Policy Enforcement
Point (PEP). The PEP allows the XACML Policy Decision Point (PDP) to decide
whether or not to authorize access.

The DataPower appliance supports the mandatory to implement and optional

specifications that are listed in Section 10.2.8 of the OASIS Standard, eXtensible
Access Control Markup Language (XACML) Version 2.0, dated February 1, 2005.

Use the following procedure to configure an XACML Policy Decision Point (PDP).
1. Select Objects Access XACML Policy Decision Point to display the
XACML Policy Decision Point catalog.
2. Click Add to display the XACML Policy Decision Point Configuration screen.
a. Use the Name field to specify the name of this XACML PDP.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Use the Evaluate Individual Policies Equally toggle to signal the presence
of a comprehensive top-level XACML policy-set.
on Indicates the presence of multiple XACML policy-sets, each of
which will be used in the authorization decision
off (Default) Indicates the presence of a top-level XACML policy-set
that is specified by the General Policy File property
In the event of multiple authorization matches, a policy combining
algorithm, which defines a procedure for arriving at an authorization
decision given the individual results of evaluation by a set of policies, is
employed to render the final decision.

Appendix A. Referenced objects 277

 e. Specify the location of the top-level XACML policy-set in the General
Policy File field.
This property is meaningful only if the Evaluate Individual Policies
Equally radio button is set to off.
f. Specify the policy combining algorithm used by this XACML PDP in the
Dependent Policies Combining field.
This property is meaningful only if the Evaluate Individual Policies Equally
radio button is set to on.
The XACML Version 2.0 standard defines the following policy combining
algorithms:
Deny Overrides
The deny-overrides policy-combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to deny, the policy combination evaluates
immediately to deny. In other words a single deny takes precedence
over other policy evaluations. If all policies are determined to be
NotApplicable, the policy combination evaluates to NotApplicable.
First Applicable
(Default) The first-applicable policy combining algorithm evaluates
each policy in the order that it appears in the XACML policy set. For
an individual policy, if the target (resource) evaluates to TRUE and
the policy conditions evaluate unambiguously to permit or deny,
evaluation is immediately halted, and the policy combination
evaluates to the effect of that individual policy. If the individual
policy evaluates the target as FALSE or the policy conditions as
NotApplicable, then the next policy in the order is evaluated; if no
further policy exists in the order, the policy combination evaluates to
NotApplicable.
Only One Applicable
The only-one-applicable policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set; unlike
the other policy combining algorithms, only-one-applicable must
evaluate all policies to render a final evaluation. If after evaluating
all policies, no policy is considered applicable by virtue of its target
(the requested resource), the policy combination evaluates to
NotApplicable. If after evaluating all policies, more than one policy
is considered applicable by virtue of its target, the policy
combination evaluates to Indeterminate. If after evaluating all
policies, only one single policy is considered applicable by virtue of
its target, the policy combination evaluates to the result of
evaluating that single policy.
Permit Overrides
The permit-overrides policy combining algorithm evaluates each
policy in the order that it appears in the XACML policy set. If any
policy in the set evaluates to permit, the policy combination
evaluates immediately to permit. In other words a single permit
takes precedence over other policy evaluations. If all policies are
determined to be NotApplicable, the policy combination evaluates to
NotApplicable.
g. Use the Dependent Policy Files field with the Add and Delete buttons to
construct a list of dependent policy files.

278 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Policy sets can be local or remote to the appliance; use local or standard
URLs to locate files.
h. Optionally, use the Other Policy Files from Directory field with the Add
and Delete buttons to construct a list of local directories that contain
dependent files.
All files in noted directories with a .xml or .xacml extension are considered
as potentially available to the current XACML PDP.
i. Use the XACML Policies Cache Lifetime field to specify the policy
combining algorithm used by this XACML PDP. Specify an integer (in the
range from 0 to 2,678,400) that specifies the time, in seconds, that compiled
XACML policies are maintained in the PDP cache. The default value of 0
specifies that the cache is never expired.
There are several ways for users to control the XACML PDP policy caches.
Explicitly clear the cache
Use the clear pdp cache CLI command to clear the cache.
Specify the TTL for the PDP
During PDP configuration, use the WebGUI or CLI to specify a cache
lifetime.
Use the XML Manager
When the PDP is used by an AAA policy for authorization, users can
access the XML manager that is associated with the AAA policy with
the clear xsl cache CLI command. This command also clears the
compiled XACML policies that are referenced by AAA polices that
are supported by the XML manager.
Use a URL Refresh Policy
Use a URL Refresh Policy whose conditions match the internal URL
xacmlpolicy:///pdpName to perform periodic cache refreshes.
v When TTL for the PDP is 0 (cache never expires), the URL Refresh
Policy controls cache refresh
v When the URL Refresh Policy is no-cache, XACML policies are
never cached, regardless of any assigned TTL value
v When the URL Refresh Policy is protocol-specified, the TTL
setting for the PDP will govern cache refresh unless its value is 0
v When the URL Refresh Policy is default with a refresh interval,
the TTL for the PDP is ignored and the URL Refresh Policy refresh
interval controls cache refresh
v When the URL Refresh Policy is no-flush with a refresh interval,
the greater of the URL Refresh Policy refresh interval or the TTL
for the PDP controls cache refresh
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Conformance Policy
A Conformance Policy defines which profiles to use to validate whether received
messages are in conformance to the selected profiles. A Conformance Policy
supports the following profiles:
v Web Services Interoperability (WS-I) Basic Profile, version 1.0, at
http://www.ws-i.org/Profiles/BasicProfile-1.0.html
v WS-I Basic Profile, version 1.1, at http://www.ws-i.org/Profiles/BasicProfile-
1.1.html

Appendix A. Referenced objects 279

 v WS-I Attachments Profile, version 1.0, at http://www.ws-i.org/Profiles/
AttachmentsProfile-1.0.html
v WS-I Basic Security Profile, version 1.0, at http://www.ws-i.org/Profiles/
BasicSecurityProfile-1.0.html

A Conformance Policy is useful when a client generates non-conformant requests

for a conformant backend server. You can configure a Conformance Policy to fix
non-conformant requests during message processing. If the request contains signed
or encrypted data, a Conformance Policy cannot fix nonconformance issues unless
the cryptographic protection is removed before correction and replied afterward.

You can define whether all the requirements in a profile should be a conformance
check, or you can determine which requirements in a profile can be ignored. You
can also change conformance policy behavior by defining a distinct set of logging
and rejection parameters for responses or requests.

Note: When defining a Conformance Policy for a conformance filter, the

Conformance Policy cannot apply corrective style sheets or add WS-I Basic
Profile 1.0 assertions.

To define a Conformance Policy, use the following procedure:

1. Select Objects XML Processing Conformance Policy to display the
catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Use the Profiles check boxes to select the profiles against which to check
messages for conformance.
WS-I BP 1.0
Validates messages against the requirements that are defined in WS-I
Basic Profile, version 1.0.
WS-I BP 1.1
(Default) Validates messages against the requirements that are defined
in WS-I Basic Profile, version 1.1.
WS-I AP 1.0
(Default) Validates messages against the requirements that are defined
in WS-I Attachments Profile, version 1.0.
WS-I BSP 1.0
(Default) Validates messages against the requirements that are defined
in WS-I Basic Security Profile, version 1.0.
7. Use the Ignored Requirements controls to define which requirements to
ignore. Specify a string in the profile:reqid format to define the requirement:
profile
Specifies the literal representation for the name of the profile.
BP1.0
Indicates WS-I Basic Profile, version 1.0
BP1.1
Indicates WS-I Basic Profile, version 1.1

280 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 BSP1.0
Indicates WS-I Basic Security Profile, version 1.0
AP1.0
Indicates WS-I Attachment Profile, version 1.0
reqid
Specifies the identifier of the requirement in that profile. This identifier
follows the naming convention in the profile documentation.
To specify requirement R4221 in the WS-I Basic Security Profile, version 1.0,
add BSP1.0:R4221 to the list.
8. Use the Corrective Stylesheets controls to specify which style sheets to invoke
after conformance analysis. These style sheets can transform the analysis
results to repair instances of nonconformance. Corrective style sheets cannot
be applied to filter actions.
9. Select the degree of nonconformance to cause a conformance report to be
recorded from the Record Report list.
Never (Default) Never records conformance reports.
Failure
Records conformance reports that indicate conformance failures.
Warning
Records conformance reports that indicate conformance warnings or
conformance failures.
Always
Always records conformance reports.
10. For all nonconformance reporting levels except Never, specify the target URL
to which to send conformance reports in the Destination field.
11. Select the degree of nonconformance to cause the message to be rejected from
the Reject non-conforming messages list.
Never (Default) Never rejects messages.
Failure
Rejects messages with conformance failures.
Warning
Rejects messages with conformance warnings or with conformance
failures.
12. Use the Include error summary toggle to determine whether to include the
summary for the conformance analysis in the rejection message for requests.
This option is for all nonconformance rejection levels except Never.
on Includes the summary.
off (Default) Does not includes the summary.
13. Use the Use analysis as results toggle to determine whether to deliver a
conformance analysis.
on Delivers a conformance analysis as a results action.
off (Default) Does not deliver a conformance analysis as a results action.
14. Use the Distinct response behavior toggle to determine whether to define a
distinct set of logging and rejection parameters for responses or requests.
on Allows the definition of a distinct set of logging and rejection
parameters.

Appendix A. Referenced objects 281

 off (Default) Does not allow the definition of a distinct set of logging and
rejection parameters on request messages.
15. From the Record Report (response direction) list, select the degree of
nonconformance to cause a conformance report to be recorded for responses.
Never (Default) Never records conformance reports.
Failure
Records conformance reports that indicate conformance failures.
Warning
Records conformance reports that indicate conformance warnings or
conformance failures.
Always
Always records conformance reports.
16. (Optional) For all nonconformance reporting levels except Never, specify the
target URL to which to send conformance reports for responses in the
Destination field.
17. From the Reject non-confirming response messages list, selects the degree of
nonconformance to cause the response message to be rejected.
Never (Default) Never reject messages.
Failure
Rejects messages with conformance failures.
Warning
Rejects messages with conformance warnings or with conformance
failures.
18. Use the Include response error summary toggle to determine whether to
include the summary for the conformance analysis in the rejection message for
requests. This option is for all nonconformance rejection levels except Never.
on Includes the summary.
off (Default) Does not includes the summary.
19. Click Apply to save the object to the running configuration.
20. Optionally, click Save Config to save the object to the startup configuration.

Document Crypto Map

Document Crypto Maps enable partial (field-level) document encryption, and
corresponding document decryption, by providing a list of XPath-based rules
identifying XML document elements that are encrypted/decrypted.
1. Select Objects XML Processing Document Crypto Map to display the
Document Crypto Map catalog.
2. Click Add to display the Document Crypto Map Configuration (Main) screen.
Use this screen to add cryptographic operational rules to this Document Crypto
Map.
3. Provide the following inputs:
Name Specify the name of the Document Crypto Map.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.

282 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Operation
Select the cryptographic action for this rule.
Decrypt
Specifies that this rule decrypts elements
Encrypt
Specifies that this rule encrypts elements
Encrypt (WS-Security)
Specifies that this rule uses the Web Services Security
Specification to encrypt elements
Sign (WS-Security)
Specifies that this rule uses the Web Services Security
Specification to sign elements
XPath Expression
Add XPath expressions to this rule. The XPath expression defines one
or more document elements subject to this rule. These are the
encrypted elements, not the unencrypted elements.
Click XPath Tool to use the graphically oriented XPath tool to construct
these expressions. You will need to upload an example of an encrypted
document to use this tool. Then you can simply click on the encrypted
elements to decrypt. The XPath expression is constructed automatically.

Note: The XPath expressions cannot exceed 330 characters. Use

Namespace Mapping entries to enable the ability to omit the
namespace URIs from the XPath expression.

Namespace Mappings tab

To add XML namespace information, use the following procedure:
1. Click the Namespace Mappings tab to display the Document Crypto Map
Configuration (Namespace Mappings) screen.
2. Click Add to display the Namespace Mappings Property window.
3. Provide the following inputs:
Prefix Specify the namespace prefix.
URI Specify the namespace URI.
4. Click Save to return to the Document Crypto Map Configuration (Namespace
Mappings) screen, which now displays the namespace date.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

HTTP Input Conversion Map

HTTP Input Conversion Maps enable the translation of non-XML input (for
example, an HTML form) to XML format.
1. Select Objects XML Processing HTTP Input Conversion Map to display
the HTTP Input Conversion Map catalog.
2. Click Add to display the HTTP Input Conversion Map Configuration (Main)
screen.
3. Provide the following inputs:
Name Specify the name of the HTTP Input Conversion Map.

Appendix A. Referenced objects 283

 Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Default Input Encoding
Select the input document format. If you set this value and enable the
Conversion Map object, all input documents will be translated
according to this default and no specific inputs are needed.
Base 64
Input is treated literally. Processing adds an encoding="base64"
attribute to input element
Plain XML escape the input
URL-encoded
(Default) URL unescape, then XML escape the input
XML Input is treated literally, no processing

Input Encoding tab

1. Click the Input Encoding tab to display the HTTP Input Conversion Map
Configuration (Input Encoding) screen.
2. Click Add to display the Input Encoding Property window. Use this screen to
define conversion rules.
3. Provide the following inputs:
Input Match
Select the input content subject to this conversion rule. Specify a PCRE
(Perl-compatible regular expression). PCRE documentation is available
at http://www.pcre.org.
Encoding
Select the input format.
Base 64
Input is treated literally. Processing adds encoding="base64"
attribute to input element
Plain XML escape the output
URL-encoded
URL unescape, then XML escape the output
XML (Default) Input is treated literally, no processing
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

IMS Connect
An IMS Connect object handles IMS protocol communications from the
Multi-Protocol Gateway to IMS applications. This object contains settings that
affect the behavior of the connection.

To configure an IMS Connect object, use the following procedure:

1. Select Objects Network IMS Connect to display the IMS Connect catalog.
2. Click Add to display the IMS Connect configuration screen.

284 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the host name or IP address of the remote IMS Connect server in the
Host field.
7. Specify the port that the IMS Connect server monitors in the Port field.
8. Use the EBCDIC Header Conversion toggle to control EBCDIC header
conversion. Conversion affects only the header, not the payload. To convert
the payload, use a transformation in a processing policy. The user message
exit should be able to process EBCDIC data. Some use message exits can
handle both UTF-8 and EBCDIC.
on Converts IMS headers to EBCDIC.
off (Default) Does not convert IMS headers to EBCDIC.
9. Specify the two-letter prefix for the generated client ID in the Generate Client
ID Prefix field. If not specified, the prefix is set to DP.
10. Override default IMS Connect configuration value. All the properties on the
Default Headers tab are default values. Some of them can be overridden in
the URL, and others through header injection.
a. Click the Default Headers tab.
b. Specify the exit program to use for all IMS connections in the Exit
Program field.
c. Specify the name of the IMS client identifier in the Client ID field. If
blank, the user exit must generate it.
d. Specify the transaction code to invoke in the Transaction Code field. This
value can be overridden by specifying it in the backend URL. Refer to
Building an IMS Connect URL on page 52 for more information.
e. Specify the name of the data store (IMS destination ID) in the Data Store
field. This property must be specified by the client. The IMS Connect
returns the data store name from the exit in the OMUSR_DESTID OTMA
header field. This value can be overridden by specifying it in the backend
URL. Refer to Building an IMS Connect URL on page 52 for more
information.
f. Specify an override value in the Logical Terminal Name field. OTMA
places this value in the IOPCB field. If you do not specify an override value,
OTMA places the IMS Connect-defined TPIPE name in the IOPCB field. The
TPIPE name is set to one of the following values based on the commit
mode:
v If the commit mode is 0, sets the value to the client identifier (CLIENT
ID).
v If the commit mode is 1, sets the value to the port identifier (PORT ID.
If you use the LTERM value in the IOPCB to make logic decisions, be aware
of the naming conventions of the IOPCB LTERM name.

Note: For IMS host applications, the value for this property is set by the
user message exit. The user exit message either moves this value to
the OMHDRLTM OTMA field or sets OMHDRLTM with a predetermined
value.
g. Specify the plaintext string sent to the server to identify the client in the
RACF ID field.

Appendix A. Referenced objects 285

 h. Specify the RACF password in the RACF Password field.
i. Specify the RACF password again in the Confirm RACF Password field.
j. Specify the group to which the security ID belongs in the RACF Group
field.
k. Select the Unicode encoding scheme of the data from the Encoding
scheme list.
(none) (Default) Uses the encoding that is set by the IMS Connect
Handler object or by a transform action in the processing policy.
Default
Uses the encoding that is set by the message.
UCS2 Uses UCS-2 encoding.
UTF8 Uses UTF-8 encoding.
UTF16 Uses UTF-16 encoding.
l. Specify an appropriate wait time for IMS server to return data to IMS
Connect in the IRM Timer field. This value sets the IRM_TIMER. Refer to the
IMS Connect documentation for details. For example, a value of 21 sets the
value to 0.21 seconds.
11. Click Apply to save the object to the running configuration.
12. Optionally, click Save Config to save the object to the startup configuration.

Defining an LDAP Search Parameters object

The LDAP Search Parameters object serves as a container for the parameters that
are used to perform an LDAP search operation.
Authentication
The parameters for an LDAP search to retrieve the DN of the user.
Credentials mapping
The parameters for an LDAP search to retrieve the group name (DN or
attribute) based on the DN of the authenticated user.

You need to add a prefix and optionally add a suffix to create the LDAP filter. The
prefix and suffix are constructs of the LDAP filter expression, as defined in LDAP:
String Representations of Search Filters. This filter is used to perform the LDAP
search and return matching entries.

To create an LDAP Search Parameters object, use the following procedure:

1. Select Objects Access Settings LDAP Search Parameters to display the
catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Specify the base DN to begin the search in the LDAP Base DN field. This
value identifies the entry level of the tree used by the LDAP Scope property.
7. Specify the name of the attribute to return for each entry that matches the
search criteria in the LDAP Returned Attribute field. The default is the dn
attribute.

286 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 8. Specify the prefix of the LDAP filter expression in the LDAP Filter Prefix
field.
If the prefix is mail= and the user name is bob@example.com, the LDAP search
filter would be mail=bob@example.com.
9. Optionally specify the suffix of the LDAP filter expression in the LDAP Filter
Suffix field.
If the prefix is mail=, the suffix is )(c=US)), and the user name is
bob@example.com, the LDAP search filter would be
(&(mail=bob@example.com)(c=US)).
10. Select the depth of the search from the LDAP Scope list:
Base Searches the entry level of the tree only.
One level
Searches the entry level of the tree and any object that is one-level
below the input.
Subtree
(Default) Search the entry level of the tree and all of its descendents.
11. Click Apply to save the object to the running configuration.
12. Optionally, click Save Config to save the object to the startup configuration.

Load Balancer Group

A Load Balancer Group is a server pool that can provide redundancy among a
collection of servers. A Load Balancer Group can be used as the backend server for
a DataPower service or can be used to provide LDAP or IMS Connect server
failover protection. A request to connect to a Load Balancer Group results in the
selection of a healthy server to receive an incoming client request.

Each instance of a Load Balancer Group can support 512 members.

Health of member servers

The health of each member of the group is considered one of the following :
v Healthy or up
v Quarantined or softdown
v Convalescent or down

Healthy
By default, all servers are considered healthy and are eligible to receive forwarded
client requests. When healthy, the health state is up.

Quarantined
During a normal HTTP transaction or the TCP ping, a failure to connect to a server
causes the server to be quarantined until a dampening period elapses. When the
dampening period elapses, the server returns to the healthy state and becomes
eligible to receive forwarded client requests. When quarantined, the health state is
softdown.

While quarantined, the server is:

v Removed from the server pool
v Ineligible to receive forwarded client requests
v Excluded from the optional health check

Appendix A. Referenced objects 287

 Convalescent
Optionally, you can associate a periodic health check with a Load Balancer Group.
If the health check fails, the server is deemed convalescent. The server is not
considered to be healthy until it passes a health check. When deemed convalescent,
the health state is down.

While deemed convalescent, the server is:

v Removed from the server pool
v Ineligible to receive forwarded client requests

Setting the health state with a variable

The health state for each server can be set with the service/lbhealth/ service
variable. This variable takes one of the following syntax statements:
var://service/lbhealth/group/server/state
var://service/lbhealth/group/server:port/state

Where:
group The name of the Load Balancer Group
server The IP address or host name of the member
port The port of the member
state The state of the server, which is one of the following values:
v up
v down
v softdown
Refer to Health of member servers on page 287 for details.

Configuring Load Balancer Group objects

The configuration of a Load Balancer Group consists of the following activities:
1. Providing basic configuration properties on the Main tab
2. Defining server members on the Members tab
3. Optionally defining health check criteria on the Health tab

Providing basic configuration

To start the configuration, perform the following procedure:
1. Select Objects Network Load Balancer Group to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name for the Load Balancer Group.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Algorithm
Select the algorithm to select the actual server. The following values are
available:
First Alive
Uses the concept of a primary server and backup servers. When
288 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 the primary server is healthy, all connections are forwarded to
this server. When the primary server is quarantined or
convalescent, connections are forwarded to backup servers. The
primary server is the first server in the members list.
Hash Uses the IP address of the client or the value of an HTTP
header as the basis for server selection.
When using an HTTP header, use the Load Balancer Hash
Header property to identify the header to read. This property is
available for Multi-Protocol Gateway and Web Service Proxy
services only. Additionally, this property is available only in the
object view, and this property is on the Main tab.
The same client is served by the same server. This algorithm is
used in applications that require the storage of server-side state
information, such as cookies.
Least Connections
Maintains a record of active server connections and forward a
new connection to the server with the least number of active
connections.
Round Robin
(Default) Maintains a list of servers and forwards a new
connection to the next server on the list.
Weighted Round Robin
Maintains a weighted list of servers and forwards new
connections in proportion to the weight (or preference) of each
server.
Damp Time
Specify the number of seconds that a server remains in an softdown
state. Use a value in the range of 1 through 86400. The default is 120.
This property does not impact servers that are in the down state.
Do not Bypass Down State
Select the connection-behavior when no member is up.
on Does not forward the connection to any member. Makes the
next attempt when at least one members is in the up state.
off (Default) Selects the first member in the down state and
forwards the connection to this server.
Try Every Server Before Failing
Select the retry-behavior for a failed attempt.
on Sends the requests to each server until one responds or all fail.
Each server that fails is set to the softdown state.
off (Default) Does not attempt to contact other members.
Masquerade as Group Name
Select which name to present in the message header.
on Uses the name of the Load Balancer Group. If
appserver1.domain.com is a member of the Appsters Load
Balancer Group, the message header contains Appsters.
off (Default) Use the host name of the member. If

Appendix A. Referenced objects 289

 appserver1.domain.com is a member of the Appsters Load
Balancer Group, the message header contains
appserver1.domain.com.
4. Continue with procedure that is provided in Defining server members.

Defining server members

Use the following procedure to add members or assign weight to members. For all
algorithms except First Alive, the order of members is not important.
1. Select the Members tab to display the catalog.
2. Click Add to display the property window.
3. Provide the following inputs:
Actual Host
Specify the IP address or the domain-qualified host name of the
member.
Weight
If the algorithm is Weighted Round Robin only, specify the relative
weight (preference). Use a value in the range of 1 through 65000. The
default is 1.
The greater the value, the more likely this server is to receive a
connection request. For example there are three members (A, B, and C)
that have the assigned weights of 100, 60, and 40, respectively. Because
of the weighting, A receives 50% of requests, B receives 30% of requests,
and C receives 20% of requests.
Mapped Server Port
Specify the member-specific target port or retain the default value (0) to
use the DataPower service-defined port. Use a value in the range of 0
through 65535. The default is 0.
By default, member servers are contacted on the DataPower
service-defined port. However, if you have services running on
different ports for different member servers, explicitly identify the
member-specific target port. If you specify a nonzero value, that
member server will always be contacted on this port.
Health Port
Specify the member-specific health port or retain the default value (0)
to use the Load Balancer Group-defined port. Use a value in the range
of 0 through 65535. The default is 0.
A nonzero value overrides the value for the Remote Port property of
the health check. This property is available during the configuration of
the health check on the Health screen.
4. Click Save to return to the catalog.

Assignment of all members to a Load Balancing Group completes the required

configuration.
v To associate a periodic health check with the new Load Balancer Group, refer to
Defining health checks on page 291.
v If you are completed with the configuration, click Apply to save the object to the
running configuration and return to the object catalog.
v Optionally, click Save Config to save the object to the startup configuration.

290 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Defining health checks
A health check is essentially a scheduled rule that sends the same request to each
server member. The successful completion of the health check requires that the
server passes normal TCP and HTTP connection criteria. Optionally, the health
check contains a filter to test the response from the server. If the filter accepts the
response, the server is considered to be healthy; otherwise, it is considered to be
convalescent.

Use the following procedure to define the health check:

1. Click the Health tab to display the configuration screen.
2. Provide the following inputs:
Enabled
Controls whether to perform the periodic health check.
on Enables the health check.
off (Default) Disables the health check.
URI When the check type is Standard, specify the non-server (file path)
portion of the target URI. That is, specify the URI to receive the client
request that is generated by the rule. The default is /.
This URI is used with the specified remote port.
Remote Port
Specify the port on the target server to receive the query. The default is
80.
You can override this value for one or more members of the Load
Balancer Group with the Health Port property. This property is
available during the configuration of member servers in the group.
The response from the server is evaluated to determine the health
status of each member server in the group. The request is sent to the
target URI and remote port.
Health Check Type
Select the type of check to perform.
Standard
(Default) Select if the group does not consist of LDAP servers.
LDAP Select if the group consists of LDAP servers.
IMS Connect
Select if the group consists of IMS Connect servers.
Send SOAP Request?
When the check type is Standard, specify the HTTP method to access
the target URI.
on (Default) Click to access the target URI with an HTTP POST
operation (by posting a SOAP message).
off Click to access the target URI with an HTTP GET operation.
SOAP Request Document
When Send SOAP Request? is on, specify the SOAP message to send
as a client request. The default is the healthcheck.xml file in the store:
directory (store:///healthcheck.xml).

Appendix A. Referenced objects 291

 Timeout
Specify the number of seconds for the completion of the health check.
Use a value in the range of 2 through 86400. The default is 10.
If successful, the server is deemed healthy and is marked as up;
otherwise, the server is deemed convalescent and is marked as down.
Frequency
Specify the number of seconds between health checks. Use a value in
the range of 5 through 86400. The default is 180.
XPath Expression
When the check type is Standard, use with the XSL Health Check
Filter property to specify the XPath expression that must be found in a
valid server response. If necessary, click XPath Tool to define an XPath
expression.
XSL Health Check Filter
When the check type is Standard, specify the style sheet to filter the
server response. The default is the healthcheck.xsl file in the store:
directory (store:///healthcheck.xsl).
This style sheet uses the specified XPath Expression value as input and
scans the server response for its presence. If found, the server is
deemed healthy and is marked as up; otherwise, the server is deemed
convalescent and is marked as down.
SSL proxy profile
Optionally, when the check type is Standard, select an SSL Proxy
Profile to provide the resources for a secure connection.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

Matching Rule
Matching Rule objects support the implementation of processing policies and XML
manager-based schema validation rules. Both use a Matching Rule to determine if
a candidate XML document is subject to a particular processing or validation
action in a processing policy.

A Matching Rule contains one or more match expressions. Match expressions are
of the following types:
v Error code expressions define an error set that is subject to a specific error-rule.
As error codes are written as hexadecimal integers, the error code expression
matches one or more hexadecimal integers.
v HTTP expressions work with a specified HTTP header to define a group of
HTTP headers. An HTTP expression can define, for example, an HTTP header
that contains a specific header field or an HTTP header that contains a defined
value in a specific header field.
v URL expressions define a group of URLs. For example, a URL expression could
define all URLs or only URLs that contain a specific domain name.
v XPath expressions define content in the XML document. For example, an XPath
expression could define all attributes of a specific name.

292 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Note: Candidate documents are evaluated against all match expressions in the
Matching Rule. A document matches the rule only if it conforms to all
expressions in the rule. Documents that fail to match all expressions do not
match the rule.

To configure a Matching Rule, use the following procedure:

1. Select Objects XML Processing Matching Rule to display the catalog.
2. Click Add to display the configuration screen.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Use the Match with PCRE toggle to indicate whether match patterns use
PCRE expression or shell-style expressions.
on Uses PCRE expressions.
off (Default) Uses shell style expressions.
7. Use the Boolean Or Combinations toggle to indicate whether to combine the
match criteria with OR semantics or with AND semantics.
on Uses OR semantics to evaluate the criteria. Only a single match
condition needs to be true for the match to succeed.
off (Default) Uses AND semantics to evaluate the criteria. All match
conditions must be true for the match to succeed.
8. Define matching rules on the Matching Rule tab
a. Click Add to display the Property window.
b. Select the desired match type from the Matching Type list.
Error Code
Bases the match on an error code. This type is for use in the
processing of error rules.
Full URL
Deprecated. Use URL.
This legacy type creates a match that uses a shell-style match
pattern against the full inbound URL.
Host Deprecated. Use HTTP.
This legacy type creates a match that uses a shell-style match
pattern against the Host: header in HTTP 1.1 requests.
HTTP Bases the match on HTTP header fields.
URL Bases the match on the inbound URL after any URL rewrite.
XPath Bases the match on an XPath expression. The expression is applied
to the inbound document. When the XPath expression evaluates to
true, a match is made.
c. Define the matching criteria:
v When HTTP:
1) Specify the target HTTP header field in the HTTP Header Tag field.
2) Specify the HTTP expression in the HTTP Value Match field.
Wildcards are allowed.
v When URL, specify the URL match expression in the URL Match field.

Appendix A. Referenced objects 293

 You can use wildcards to define a match pattern as follows:
* The string wildcard matches 0 or more occurrences of any
character.
For a PCRE expression, use .* rather than * to match any number
of any characters.
? The single character wildcard matches one occurrence of any single
character.
[] The delimiter pair to bracket a character or numeric range.
[1-5] Matches 1, 2, 3, 4, or 5
[xy] Matches x or y
You can use any PCRE-compliant expression. For more information,
refer to http://www.pcre.org.
v When Error Code, identify the target error code in the Error Code field.
Click Select to view a list of selectable error codes.
v When XPath, specify the XPath expression in the XPath Expression
field. Click XPath Tool for help creating this expression.
d. Click Save.
Repeat this step to define another matching rule.
9. Click Apply to save the object to the running configuration.
10. Optionally, click Save Config to save the object to the startup configuration.

Multi-Protocol Gateway object

Select Objects Service Configuration Multi-Protocol Gateway to display the
Multi-Protocol Gateway catalog.

Click Add to display the Configure Multi-Protocol Gateway screen. Use this screen
to specify basic operations.

Main tab
Provide the following inputs:
Name Specify the name of this Gateway.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Front Side Protocol
Select an existing Front Side Handler and click Add. Front Side Handlers
determine the network communication protocol, address, port, and other
protocol-specific settings. Refer to Chapter 4, Configuring handler
objects, on page 57 for more information.

Note: To use a Raw XML Front Side Handler, Type must be Dynamic
Backend.
XML Manager
Select an XML Manager. Refer to XML Manager on page 352 for more
information.

294 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Backend URL
If Type is Static Backend, specify the URL of the backend server.
The URL determines the protocol and endpoint of the backend server. To
use a load balancer, specify the name of an existing Load Balancer Group
instead of the address-port pair in the URL.
For example, the service uses the HTTP protocol for a URL that starts with
http:// but uses the MQ protocol for a URL that start with dpmq://. To
construct an MQ URL, use the builder.
Propagate URI
Control the behavior of URI propagation: on (default) or off.
If the backend URL is in an MQ, TIBCO EMS, or WebSphere JMS format,
disable URI propagation (set to off).
Enabling URI propagation is meaningful in the following situations only:
v When the service is configured to use a static backend.
v When the service is configured to use a dynamic backend and dynamic
routing is set with a route with style sheet (route-action) action in the
processing policy. In this case, use the dp:set-target() extension
element to define that target backend server.
For the other dynamic routing options that are available with the
route-action and route-set actions, the URI is absolute.
When enabled, the service rewrites the URI of the backend URL to the URI
in the client request. If URI propagation is enabled and the client submits
http://host/service and the backend URL is http://server/listener, the
URL is rewritten to http://server/service.

Notes:
v When enabled, any Matching Rule in a response processing rule
must match the rewritten URL.
v Any action in the Processing Policy can change the URI that is
sent to the backend server. The rewritten URI could override the
intended effect of this setting.
Load Balancer Hash Header
Specify the name of the HTTP header to use for calculating the hash for
load balancing traffic to the backend servers.
v When defined, the hash algorithm uses the value of the identified HTTP
header.
v When not defined, the hash algorithm uses the IP address of the client.
This property is relevant only when the value defined by the algorithm for
the Load Balancer Group is hash.
Processing Policy
Select a Processing Policy. Refer to Processing Policy on page 323 for
more information.
Type Select the proxy type.
Dynamic Backend
Specifies support for multiple backend servers. Server addresses
and port numbers are extracted from incoming client requests.

Appendix A. Referenced objects 295

 Static Backend
Specifies support for a single backend server. Requires the
specification of a backend URL.

Proxy Settings tab

Provide the following inputs:
URL Rewrite Policy
Optionally assign a URL Rewrite Policy.
This policy defines rules to rewrite the entire URL or a portion of the URL,
to replace a header value in the message, or to rewrite the HTTP POST
body in the message. The rewrite rules are applied before document
processing. Therefore, the evaluation criteria in the Matching Rule is
against the rewritten value.
Refer to URL Rewrite Policy on page 339 for more information.
SSL Proxy
Optionally assign an SSL Proxy Profile to this Gateway. Refer to Defining
SSL Proxy Profile objects on page 19 for more information.
Crypto Credentials
Optionally assign a Firewall Credentials List. Refer to Defining Firewall
Credentials objects on page 14 for more information.
Default parameter namespace
Optionally identify the default XML namespace for parameters made
available to this Gateway from the command line or WebGUI.
The default namespace is http://www.datapower.com/param/config.
Query parameter namespace
Optionally identify the default XML namespace for parameters made
available to this Gateway from a URL query string.
The default namespace is http://www.datapower.com/param/query.
Request attachments processing mode
When the request type is SOAP or XML, select how to process client
requests with attachments.
Allow Processes the message root and needed XML and non-XML
attachments. Needed attachments are buffered. Attachments that
are not needed might be streamed directly to output.
Reject Rejects messages that contain attachments.
Strip (Default) Removes attachments from the message and changes the
value of the Content-Type header to that of the root part.
Streaming
Provides limited processing of XML attachments, and streams XML
and non-XML attachments to output.
Unprocessed
Allows messages that contain attachments, but does not process
attachments.
For additional information about streaming attachments, refer to
Optimizing through Streaming.

296 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Response attachment processing mode
When the response type is SOAP or XML, select how to process server
responses with attachments.
Allow Processes the message root and needed XML and non-XML
attachments. Needed attachments are buffered. Attachments that
are not needed might be streamed directly to output.
Reject Rejects messages that contain attachments.
Strip (Default) Removes attachments from the message and changes the
value of the Content-Type header to that of the root part.
Streaming
Provides limited processing of XML attachments, and streams XML
and non-XML attachments to output.
Unprocessed
Allows messages that contain attachments, but does not process
attachments.
For additional information about streaming attachments, refer to
Optimizing through Streaming.
Action when required root part is not first
When the attachment processing mode for requests or for responses is
Streaming, select the action to take when the MIME message root part is
not first.
Abort Stops the transaction and return an error.
Buffer To Root
Buffers attachments before the root part into memory. Then
processes the root part, buffered attachments, and subsequent
attachments.
Process In Order
(Default) Processes the attachments and root part in the order that
they appear in the original message. All parts are still processed in
streaming mode even though only attachments after the root will
be streamed from the network.
Front attachment processing format
Select how to interpret client requests with attachments.
Dynamic
(Default) The appliance reads the message and determines the
attachment format (DIME or MIME) from the content-type header.
Conversion between MIME and DIME is possible provided that
attachments are buffered.
MIME Messages adhere to the MIME format. Conversion to DIME is
possible provided that attachments are buffered.
DIME Messages adhere to the DIME format. Conversion to MIME is
possible provided that attachments are buffered.
Detect The appliance reads the message and determines the attachment
format (DIME or MIME) from message data. Conversion between
MIME and DIME is possible provided that attachments are
buffered.
Back attachment processing format
Select how to interpret server responses with attachments.

Appendix A. Referenced objects 297

 Dynamic
(Default) The appliance reads the message and determines the
attachment format (DIME or MIME) from the content-type header.
Conversion between MIME and DIME is possible provided that
attachments are buffered.
MIME Messages adhere to the MIME format. Conversion to DIME is
possible provided that attachments are buffered.
DIME Messages adhere to the DIME format. Conversion to MIME is
possible provided that attachments are buffered.
Detect The appliance reads the message and determines the attachment
format (DIME or MIME) from message data. Conversion between
MIME and DIME is possible provided that attachments are
buffered.
Front Side MIME Header Processing
Use the toggle to enable (on) or disable (off) MIME (Multi-Purpose
Internet Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
before the first MIME boundary in the body of the message. These MIME
headers can contain important information that is not available in the
protocol headers, such as a string that identifies the MIME boundary.
v If on, MIME headers are processed.
v If on and there are no MIME headers in the message, the appliance
continues to try and parse the message with the available protocol
header information.
v If off and MIME headers are in the body of the message, these MIME
headers are considered part of the preamble and not used to parse the
message. If the protocol headers (such as HTTP) indicate MIME
boundaries, the appliance can parse and process individual attachments.
If such information is not available, no attachments can be parsed from
the body of the message.
MIME support is enabled by default.
Back Side MIME Header Processing
Use the toggle to enable (on) or disable (off) MIME (Multi-Purpose
Internet Mail Extensions) header processing support.
The body of a message (that is, the payload, independent of any protocol
headers) can sometimes contain MIME headers before any preamble and
before the first MIME boundary in the body of the message. These MIME
headers can contain important information that is not available in the
protocol headers, such as a string that identifies the MIME boundary.
v If on, MIME headers are processed.
v If on and there are no MIME headers in the message, the appliance
continues to try and parse the message with the available protocol
header information.
v If off and MIME headers are in the body of the message, these MIME
headers are considered part of the preamble and not used to parse the
message. If the protocol headers (such as HTTP) indicate MIME
boundaries, the appliance can parse and process individual attachments.
If such information is not available, no attachments can be parsed from
the body of the message.

298 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 MIME support is enabled by default.
Stream Output to Back
Select the desired streaming behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the
appropriate backend.
Stream Messages
Begins to send the message to the backend before all processing is
complete. This behavior potentially increases processing speed.
Select this option when the selected XML Manager has streaming
enabled or when streaming of attachments is enabled.
Stream Output to Front
Select the desired streaming behavior.
Buffer Messages
Buffers submitted messages until all processing is verified as
complete. After verification, forward the message to the
appropriate requesting client.
Stream Messages
Begins to send the message to the requesting client all processing is
complete. This behavior potentially increases processing speed.
Select this option when the selected XML Manager has streaming
enabled or when streaming of attachments is enabled.
Characterize Client Traffic Type
Characterize the client-generated request.
Non-XML
Does not directly characterize the message. The message body is
not filtered or transformed. The service can take other actions, such
as determining a route or authenticating the message, before
passing it to the backend.
SOAP Identifies the message as a SOAP message.
Pass-Thru
Does not directly characterize the message, but indicates that the
message is not filtered or transformed by the service. The message
is passed as is to its target.
XML Identifies the message as unencapsulated XML.
Characterize Server Traffic Type
Characterize the server-generated response.
Non-XML
Does not directly characterize the message. The message body is
not filtered or transformed. The service can take other actions, such
as determining a route or authenticating the message, before
passing it to the backend.
SOAP Identifies the message as a SOAP message.
Pass-Thru
Does not directly characterize the message, but indicates that the
message is not filtered or transformed by the service. The message
is passed as is to its target.

Appendix A. Referenced objects 299

 XML Identifies the message as unencapsulated XML.
SOAP Schema URL
When the traffic type is SOAP, the SOAP Schema URL field appears. Use
this field to specify the full URL to the schema to validate the SOAP
schema for SOAP-formatted messages. When a service is in SOAP mode,
either on the request or response side, it validates incoming messages
against a W3C Schema for SOAP messages. You can customize the schema
to use by changing this property. Change the schema to accommodate
nonstandard configurations or special cases.
Front Side Timeout
Specify an integer between 10 and 86400 indicating the number of seconds
a connection with a client can remain idle during a transaction before it
times out and is closed. The default is 120 (2 minutes). When using an
Stateful Raw XML connection, set this value higher to ensure that the
connection is not closed due to a timeout.
Back Side Timeout
Specify an integer between 10 and 86400 indicating the number of seconds
a connection with a server can remain idle during a transaction before it
times out and is closed. The default is 120 (2 minutes). When using an
Stateful Raw XML connection, set this value higher to ensure that the
connection is not closed due to a timeout.
Front Persistent Connection Timeout
Specify an integer that sets the amount of time, in seconds, a persisted
connection can remain idle before the appliance closes the connection. This
is idle time between connections.
Back Persistent Connection Timeout
Specify an integer that sets the amount of time, in seconds, a persisted
connection can remain idle before the appliance closes the connection. This
is idle time between connections.
Include char-set in response type
Use the toggle to enable (on) or disable (off) including the character set
encoding in any content-type header or description produced. For example,
when sending a UTF-8 encoded XML document. If this property is
disabled, text/xml will be sent. If this property is enabled, text/xml;
charset=UTF-8 will be sent.
Message Processing Modes
Optionally select the check box for one or more message processing modes.
Request rule in order
Enforces first-in first-out serial processing of messages for actions
in the request rule. The appliance initiates and completes request
rule processing for messages in the order that they were pulled
from the frontend request queue. The appliance starts the request
rule for the second message in the request queue only after it
completes the processing of the first message. The backend request
queue accepts whatever message arrives first, except when you
enforce Backend in order serial processing. In that case, the
appliance buffers messages so that it sends messages to the
backend request queue in the same order that they were pulled
from the frontend request queue.
Backend in order
Enforces the serial processing of messages delivered to the backend

300 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 request queue. If needed, the appliance will buffer messages that
complete request rule processing out of order and only deliver
messages to the backend request queue in the same order that they
were pulled from the frontend request queue.
Response rule in order
Enforces serial processing of messages for actions in the response
rule. The appliance initiates and completes response rule
processing for messages in the order that they were pulled from
the backend reply queue. The appliance starts the response rule for
the second message in the reply queue only after it completes the
processing of the first message. The appliance always buffers
messages so that it sends messages to the frontend reply queue in
the same order that they were pulled from the backend reply
queue.

Monitors tab
Service Monitors
Optionally use the list with the Add and Delete buttons to assign one or
more Service Monitors to this Gateway. Refer to configureSLMTask for more
information.
Count Monitors
Optionally use the list with the Add and Delete buttons to assign one or
more Message-Count Monitors to this Gateway. Refer to
countMonitorsObject for more information.
Duration Monitors
Optionally use the list with the Add and Delete buttons to assign one or
more Message-Duration Monitors to this Gateway. Refer to
durationMonitorsObject for more information.
Monitors Evaluation Method
When a service uses more than one monitor, it is possible to determine
how the monitors interact with each other. Select one of the following:
Terminate at First Throttle
(Default) Allows all monitors to take effect on a message until a
monitor takes a Shape or Reject action. No further monitors will
take effect after this point. The order of monitors thus matters. If
three monitors are included, and the first monitor in the list either
Shapes or Rejects a message, no other monitors will execute.
Terminate at First Match
Allows all monitors to take effect until a monitor matches a
message. At that point, all monitor processing of the message
stops. In this way, only one monitor increments its counters.

Parser Limits tab

Provide the following inputs:
Maximum Message Size
Optionally specify the maximum size (in Kilobytes) of SOAP or XML
messages accepted by this Gateway.
This property limits the SOAP or XML payload, not the size of the
incoming IP packet. This value overrides the corresponding value in the
XML Manager.

Appendix A. Referenced objects 301

 Messages in excess of the specified limit are rejected and an error is
reported.
Use an integer in the range of 0 through 2097151. The default is 0. A value
of 0 specifies unlimited size.
Gateway Parser Limits
Use the toggle to control whether to impose limits on the size and depth of
XML documents and elements. Enable (on) or disable (off) service-level
limits. service-level limits override any similar limits set by the assigned
XML Manager.
XML Bytes Scanned
Specify the maximum number of bytes that canned be scanned in one
document. The default is 4194304. Only available when parser limits are
enabled.
XML Element Depth
Specify the maximum allowed element depth of a single document. The
default is 512. Only available when parser limits are enabled.
XML Attribute Count
Specify the maximum allowed number of attributes. The default is 128.
Only available when parser limits are enabled.
XML Maximum Node Size
Specify the maximum allowed number of bytes of a single element. The
default is 33554432. For optimal performance, set this value to a power of
2. Only available when parser limits are enabled.
XML External References
Specify how the XML parser continues processing when an input
document seeks to resolve an external reference such as an external entity
or external DTD definition. The default is Forbid. Only available when
parser limits are enabled.
Attachment Byte Count Limit
Specify the maximum allowed number of bytes in an attachment. The
default is 2000000000. Only available when parser limits are enabled.
Attachment Package Byte Count Limit
Specify the maximum number of bytes allowed for all parts of an
attachment package, including the root part. Attachment packages that
exceed this size will result in a failure of the whole transaction. If the value
is 0, no limit is enforced. The default is 0. Only available when parser
limits are enabled.

HTTP Options tab

Server Side HTTP Version
Select the HTTP protocol version (HTTP 1.0 or HTTP 1.1) used for
server-side connections. By default, HTTP/1.1 is used for server-side
connections.
Compression
Enable (on) or disable (off) GZIP compression negotiation with the
backend server. By default, compression negotiation is disabled.
Persistent Connections
Enable (on) or disable (off) HTTP persistent connections with the backend
server. By default, persistent connections are enabled.

302 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Loop Detection
Use the toggle to enable (on) or disable (off, the default) gateway loop
detection. Some protocols allow for the detection of loops between
gateways. Enable loop detection to include the HTTP Via header.
Follow Redirects
Use the toggle to enable (on) or disable (off) the following of server-side
redirects (such as HTTP 302) by the appliance. By default, the appliance
will not follow redirects. The number of redirects followed can be limited
by a User Agent that applies to the backend URL.
Rewrite Host Names When Gatewaying
Use the toggle to enable (on) or disable (off) host rewriting.
Some protocols have distinct name-based elements, separate from the URL,
that are used to demultiplex. HTTP uses the Host header for this purpose.
If this feature is enabled, the backside server will receive a request
reflecting the final route, otherwise it will receive a request reflecting the
information as it arrived at the appliance. Web servers that issue redirects
might want to disable this feature, as they often depend on the host header
for the value of their redirect.
Allow Chunked Uploads
Use the toggle to enable (on) or disable (off) the ability to send
Content-Type Chunked Encoded documents to the backend server.
When the appliance employs the HTTP 1.1 protocol, the body of the
document can be delimited by either Content-Length or chunked encoding.
While all servers will understand how to interpret Content-Length, many
applications will fail to understand chunked encoding. For this reason,
Content-Length is the standard method used. However doing so interferes
with the ability of the appliance to fully stream. To stream full documents
towards the backend server, this property should be turned on. However,
the backend server must be RFC 2616 compatible, because this feature
cannot be renegotiated at run time, unlike all other HTTP 1.1 features
which can be negotiated down at runtime if necessary. This property can
also be enabled by configuring a User Agent to enable it on a per-URL
basis.
Process Backend Errors
Indicates whether to processing errors from the backend server.
Depending on the protocol, the backend service might return a response
code that indicates an error condition. For HTTP messages, the response
from the backend server might include a response body that contains XML
that provides more details about the error. For MQ messages, the response
from the backend MQ server does not provide a response message.
on (Default) Ignores the error condition, and processes the response
rule.
off Notices the error condition during request processing, and
processes the error rule.
HTTP Client Label
Specify the name of an HTTP Header to read to determine the IP address
of the requesting client (for example X-Forwarded-For). This value defaults
to X-Client-IP.

Appendix A. Referenced objects 303

 HTTP Header Injection tab
To add a proprietary header to the message stream, click HTTP Header Injection
and then click Add to display the HTTP Header Injection panel.

Click Add to display the Header Injection Property window.

Provide the following inputs:

Direction
Select the direction of the message.
Back
(Default) Indicates a request that travels from the appliance to the
server.
Front
Indicates a response that travels from the appliance to the client
Header Name
Specify the name of the proprietary header.
Header Value
Specify the contents of the proprietary header.

Click Save to return to the Header Injection Panel.

HTTP Header Suppression tab

To delete a header from the message stream, click HTTP Header Suppression to
display the Gateway Header Suppression panel.

Click Add to display the HTTP Header Suppression Property window.

Provide the following inputs:

Direction
Select the direction of the message.
Back
(Default) Indicates a request that travels from the appliance to the
server.
Front
Indicates a response that travels from the appliance to the client
Header Tag
Specify the name of the target header to delete.

Click Save to return to the Gateway Header Suppression Panel.

WS-Addressing tab
For information about configuring Web Services Addressing (WS-Addressing), refer
to Configuring Web Services Addressing on page 36.

WS-ReliableMessaging tab
WS-ReliableMessaging
Enable or disables Web Services Reliable Messaging.
on Enables Reliable Messaging.

304 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 off (Default) Disables Reliable Messaging

When enabled, the WebGUI displays the following inputs:

Target Sequence Expiration Interval
Sets the target expiration lifetime in seconds for all Reliable Messaging
sequences.
If an incoming CreateSequence SOAP message has an Expires lifetime that
is longer than this value, the value in the SequenceResponse SOAP message
is reduced to this value. The same process applies to the Expires lifetime
in any accepted Offer in an incoming CreateSequence and for the
requested Expires value in any CreateSequence SOAP call that is made to
the client or server from a Reliable Messaging source. This implementation
never requests or accepts a non-expiring sequence (a value of PT0S that
represents zero seconds).
The default is 3600.
AAA Policy
Selects the AAA Policy to perform authentication of incoming Reliable
Messaging messages. This AAA Policy can be the same one that is used in
later processing by the request or response rule. The results are cached, so
it is not evaluated again.
While this is focused on protecting the Reliable Messaging control
messages, such as CreateSequence and TerminateSequence, it is also run on
incoming Reliable Messaging data messages, with a Sequence header. This
prevents unauthorized clients from using appliance resources by issuing
CreateSequence requests, or from disrupting existing Reliable Messaging
sequences with CloseSequence or TerminateSequence messages, or from
falsely acknowledging messages with SequenceAcknowledgement messages.
SSL session binding
Indicates whether to use an SSL session binding to protect sequence
lifecycle messages.
All Reliable Messaging control messages and sequence messages are bound
to the original SSL/TLS session that is created by the Reliable Messaging
source to transmit the CreateSequence control message. Sequence messages
that are received by the Reliable Messaging destination with the correct
identifier but on a different SSL/TLS session are rejected.
The lifetime of a SSL/TLS protected sequence is bound by the lifetime of
the SSL/TLS session this is used to protect that sequence.
on Uses an SSL session binding.
off (Default) Does not use an SSL session binding.
Destination Accept Incoming CreateSequence
Indicates whether to accept incoming CreateSequence SOAP requests and
create a Reliable Messaging destination when one is received.
on (Default) Enables this feature. If enabled, both the client and the
server can use Reliable Messaging to send messages to this
DataPower service.
off Disables this feature. If disabled, the client cannot use Reliable
Messaging to communicate with this DataPower service. If
disabled, the only way that a Reliable Messaging destination can
be created on this DataPower service is when the Reliable

Appendix A. Referenced objects 305

 Messaging source is configured to make offers. In this case an
Offer and Accept can create a Reliable Messaging destination for
the server to send Reliable Messaging messages to the client.
Destination Maximum Simultaneous Sequences
Sets a limit on the maximum number of simultaneously active sequences to
Reliable Messaging destinations of this DataPower service. Attempts by
clients to create sequences in excess of this limit result in a SOAP Faults.
This property controls memory resource utilization.
The default is 400.
Destination InOrder Delivery Assurance
Indicates whether to enable InOrder delivery assurance for Reliable
Messaging destinations in addition to the standard ExactlyOnce delivery
assurance. No messages will be passed from the receive queue for further
processing unless their sequence number as assigned by the client is one
greater than the last one that was processed. InOrder delivery assurance
increases memory and resource utilization by the Reliable Messaging
destination.
on Enables InOrder and ExactlyOnce delivery assurance.
off (Default) Enables ExactlyOnce delivery assurance only.
When enabled, the WebGUI displays the following input:
Destination Maximum InOrder Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue beyond a gap in the received sequence numbers.
Use an integer in the range of 1 through 256. The default is 10.
This property controls memory utilization.
Destination Accept Two-Way Offers
Indicates whether to accept offers for two-way Reliable Messaging in
CreateSequence SOAP requests. If the request includes an offer, the
creation of a Reliable Messaging destination creates a Reliable Messaging
source to send responses to the client.
on Accepts two-way requests.
off (Default) Does not accept two-way requests.
When enabled, the WebGUI displays the following inputs:
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets the initial timeout.

306 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.
The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 30.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.
The default is 3.
Required on Request
Indicates whether to require the use of Reliable Messaging for all SOAP
messages that request rules process. The client must establish a sequence
with a CreateSequence SOAP call and must include a Sequence in each
SOAP header. Any SOAP message without a Sequence results in a SOAP
fault.
on Requires Reliable Messaging for all requests.
off (Default) Does not require Reliable Messaging for all requests.
Required on Response
Indicates whether to require the use of Reliable Messaging for all SOAP
messages that response rules process. Any SOAP message without a
Sequence results in a SOAP fault.

Note: When WS-Addressing is in use, SOAP messages without a

WS-Addressing RelatesTo SOAP Header are processed by the
request rule, not the response rule, even if the message come from
the backend server.
on Requires Reliable Messaging for all responses.
off (Default) Does not require Reliable Messaging for all responses.
Source Create Sequence on Request
Indicates whether to create a Reliable Messaging source from the back side
to the server when there is SOAP data to sent to the server and when there
is no Reliable Messaging source that was created by a MakeOffer from the
server. The Reliable Messaging source is created by sending a
CreateSequence SOAP request to the server address.
on Creates a Reliable Messaging source.

Appendix A. Referenced objects 307

 off (Default) Does not create a Reliable Messaging source.
When enabled, the WebGUI displays the following inputs:
Source Make Two-Way Offer
Indicates whether to include an offer for two-way Reliable
Messaging in CreateSequence SOAP requests that are made as the
result of request processing. Including an offer can result in the
creation of a Reliable Messaging destination for the server to send
responses on when the DataPower service creates a Reliable
Messaging source to send requests to the server. If the server does
not accept the offer, DataPower server does not create a Reliable
Messaging destination.
on Include an offer.
off (Default) Does not include an offer.
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets with the initial
timeout.
off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.
The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 10.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.

308 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 The default is 3.
Source Create Sequence on Response
When the WS-Addressing mode is WS-Addressing Gatewayed to
Synchronous or Pure WS-Addressing indicates whether to create a
Reliable Messaging source from the front side to the client when there is
SOAP data to send to the client and there is no Reliable Messaging source
that was created by a MakeOffer from the client by sending a
CreateSequence SOAP request to the WS-Addressing ReplyTo address.
on Creates a Reliable Messaging source.
off (Default) Does not create a Reliable Messaging source.
When enabled, the WebGUI displays the following inputs:
Source Retransmission Interval
Specifies the duration in milliseconds that a Reliable Messaging
source waits for an Ack before retransmitting the message. This
property also applies to the retransmission of the CreateSequence
SOAP message.
The default is 2000.
Source Exponential Backoff
Indicates whether to use the exponential back off to increase the
interval between retransmissions on unacknowledged messages by
a Reliable Messaging source.
on (Default) Uses the exponential back off to increase the
interval between retransmissions. The value of the Source
Retransmission Interval property sets with the initial
timeout.
off Does not use the exponential back off to increase the
interval between retransmissions.
Source Maximum Retransmissions
Specifies the number of times a Reliable Messaging source
retransmits a message before declaring a failure. This property also
controls the retransmission of CreateSequence requests.
The default is 4.
Source Maximum Queue Length
Specifies the maximum number of messages held in the Reliable
Messaging queue while waiting for Ack messages. This property
controls memory utilization.
The default is 10.
Source Request Ack Count
Specifies the number of messages that the a Reliable Messaging
source sends before including the AckRequested SOAP header to
request an acknowledgement.
The default is 1.
Source Inactivity Close Interval
Specifies the duration in seconds that a Reliable Messaging source
waits for an another message to be sent before closing the sequence
by sending a CloseSequence SOAP message.
The default is 3.

Appendix A. Referenced objects 309

 Source Front Reply Point
Identifies the Front Side Protocol Handler to receive the asynchronous
Reliable Messaging SequenceAcknowledgement SOAP responses from the
client. The Front Side Protocol Handler must be associated with the same
DataPower service where the corresponding Reliable Messaging sequence
is occurring.
This property controls whether a front-side Reliable Messaging source uses
a unique URL to receive asynchronous Acks from the client Reliable
Messaging destination or whether Acks are sent synchronously in future
requests to the front-side client.
v With a specified Front Side Protocol Handler and the client includes an
Offer in a CreateSequence SOAP message sent due to response
processing, there will be a non-anonymous URL specified in the AcksTo
element of the Accept element of the CreateSequenceResponse SOAP
reply.
v With a specified Front Side Protocol Handler and the front-side sends a
CreateSequence SOAP message to establish a reliable back channel, there
will be a non-anonymous URL specified in the AcksTo element of the
CreateSequence SOAP request.
v Without a Front Side Protocol Handler, the AcksTo elements has the
value http://www.w3.org/2005/08/addressing/anonymous, which
indicates synchronous Acks.
Source Back AcksTo Reply Point
Identifies the Front Side Protocol Handler to receive the asynchronous
Reliable Messaging SequenceAcknowledgement SOAP responses from the
server. The Front Side Protocol Handler must be associated with the same
DataPower service where the corresponding Reliable Messaging sequence
is occurring.
This property controls whether the backside Reliable Messaging source
uses a unique URL to receive asynchronous Acks from the server Reliable
Messaging destination, or whether Acks are sent synchronously in future
responses to the backside server.
v With a specified Front Side Protocol Handler and the response process
causes a CreateSequence SOAP message to be sent, the AcksTo element
of the CreateSequence SOAP message will be set to the URL that is
specified in back AcksTo.
v Without a Front Side Protocol Handler, the AcksTo element has the value
http://www.w3.org/2005/08/addressing/anonymous, which indicates
synchronous Acks.
Source Maximum Simultaneous Sequences
Sets a limit on the maximum number of simultaneously active sequences
from Reliable Messaging sources of this DataPower server. Each remote
Reliable Messaging destination endpoint reference (URL) requires one
sequence. Transactions that request the creation of sequences in excess of
this limit result in a SOAP Fault. This property controls memory resource
utilization.
The default is 400.

Stylesheet Parameter tab

To pass parameter-value pairs to the style sheets that support this Gateway, click
Stylesheet Parameter to display the Stylesheet Parameter panel.

310 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Click Add to display the Stylesheet Parameter Property window.

Provide the following inputs:

Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.

Click Save to return to the Stylesheet Parameter Panel.

Peer Group
Peer Groups enable the exchange of SLM data among a group of DataPower
appliances. This exchange provides for the enforcement of SLM policies across
multiple appliances. Group members use SOAP over HTTPS to exchange SLM data
at periodic intervals, must be running identical SLM configurations, and must be
clock-synchronized. The update messages with the newly received update
information is aggregated in the information store of each group member.

Note: You can use the NTP service to synchronize the clocks among a group of
DataPower appliances. For information about enabling the NTP service,
refer to IBM WebSphere DataPower SOA Appliances: Administrators Guide.

To create or edit Peer Groups, select Objects Network Peer Groups to display
the Peer Groups catalog.

To edit an existing Peer Group, click the name of the group. To create a new Peer
Group, click Add to display the Peer Groups configuration screen.

Provide the following inputs:

Name Specify a unique name for this Peer Group.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
Type Retain the default value, SLM.
URL Use with the Add and Delete buttons to compile a membership list of
members by IP address. For example, https://192.168.12.100:5550 is a
typical entry for another DataPower appliance. The port number 5550 is
the default port for the XML Management Interface on the DataPower
appliance. If this port was changed on any of the peers, this entry must
reflect the correct port.

Note: The membership list must be identical across all group members.
When creating the membership list, include the current appliance.

Click Apply to save the object to the running configuration and return to the object
catalog.

Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects 311

Policy Parameters
A Policy Parameters object defines policy parameters as key-value pairs for use in
a policy mapping style sheet. Specify the key with the {policy-domain-ns}key
format.

A policy parameters is the way that you must map the needed parameters that are
defined in or referenced by the WSDL policy or that are defined in an attached
source to the specific DataPower object. If you do not define all the needed
parameters, processing a message with the defined WS-Policy generates errors.

For example, you might need an X.509 token to use the defined WS-Policy. If you
need an X.509 token, you need to define which certificate that is stored on the
DataPower appliance to use. If the certificate is alice, you would need to set the
{http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702}ws-secpol-
Certificate parameter to alice.

Note: If you defined a policy parameters at the port or port-operation level, these
parameters are not applied to its parallel synthesize port or operation. The
policy parameters for synthesized ports and operations must be inherited
from the service level or redefined at the synthesized level.

To define policy parameters, use the following procedure:

1. Select Objects Policy Policy Parameters to display the Policy Parameters
catalog.
2. Define the properties on the Main tab.
3. Define the properties on the Policy Parameters tabs.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Main tab
To define policy parameters, use the following procedure:
1. Select Objects Policy Policy Parameters to display the Policy Parameters
catalog.
2. Click the Main tab.
3. Provide the following inputs:
Name Specify the name of the object.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
4. Continue to the Policy Parameters tab to define the policy parameters.

Policy Parameters tab

To continue the definition of policy parameters, use the following procedure:
1. Click Policy Parameters tab to display the Policy Parameters (Policy Parameter)
configuration screen.
2. Define a policy parameter.
a. Click Add to display the Policy Parameters Property window.

312 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 b. Provide the following inputs:
Name Specify the name of the policy key with the {policy-domain-ns}key
format.
Value Specify the value of the key.
c. Click Submit.
3. Repeat the previous step for each required policy parameter.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Processing Action
Use the following procedure to define global, reusable Processing Actions. For a
more complete discussion of Processing Actions, refer to Chapter 5, Defining
processing policies, on page 87.
1. Select Objects XML Processing Processing Action to display the Processing
Action catalog.
2. Click Add to display the Processing Action Configuration (Main) screen.
3. Provide the following inputs:
Name Specify the name of this Processing Action.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Action Type
Select an action to be performed by the processing rule. After making
the selection, the screen redraws with properties that are relevant to the
selected action. The following actions are available:
AAA Implements an AAA Policy specified by the AAA Policy
property.
An aaa action also requires that the Input context be identified,
and optionally allows for Output context identification. If the
output context is not identified, OUTPUT is used.
Call Processing Rule
Calls a named, reusable processing rule.
A call action requires that Input (document source) and
Output (document destination) contexts be identified, as well
as the target Processing Rule.
Checkpoint Event
Adds an administrative checkpoint. This action is available only
with Web Service Proxy services.
A checkpoint action requires that Input (document source)
context be identified as well as the Event that triggers the
action.
Conditional
Selects an action for processing based on an XPath match.

Appendix A. Referenced objects 313

 A conditional action requires that the Input (document source)
context be identified as well as the Match Condition that
triggers the action.
Convert Query Parameters to XML
Converts non-XML input (for example, an HTTP POST or an
HTTP form) into XML format.
A convert-http action requires that Input (document source)
and Output (document destination) contexts be identified, and
optionally allows selection of an HTTP Input Conversion Map
(specifying document encoding rules) with the Input
Conversion property.
Extract using XPath
Applies an XPath expression (defined by the XPath property) to
a source context (identified by the Input property) and stores
the result in a destination context (identified by the Output
property). The result can optionally be stored in a named
variable in the destination context.
Fetch Obtains a remote resource via HTTP
A fetch action requires that an External URL (the document
location) and Output context (the document destination) be
identified. You can Optionally use the Output Type property to
characterize the fetched data.
Filter Applies a filtering style sheet, resulting in an accept/reject
decision.
A filter action requires that an Input context (the source of
the document to be filtered) and Transform style sheet be
identified.
Specification of an Output context and a Dynamic Stylesheet is
optional.
For Each
Implements a programmatic loop for each of the defined
actions. Each time an XPath expression returns true, a
designated action runs. The for-each action can be used to
apply a series of style sheets to input data, if desired. Instead of
using XPath expressions, the loop can be processed a specific
number of times. Each iteration of the loop stores its results in
a separate output context. These output contexts are available
to any other action in the processing policy.
Log Generates a log message that contains the entire contents of a
context and send the message to a remote logging facility
The log action requires an Input context and an External URL,
to which the context contents are sent.
Specification of an Output context, an Output Type, a Log
Level, and a Log Type is optional.
On Error
Specifies a nondefault error handling procedure.
An on-error action requires only the selection of an Error
Mode. Optionally identify an error-rule and specify input and
output contexts for that rule.

314 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Results
Sends the contents of a named context to another context or to
a remote location.
A results action requires that an Input context (the source of
the content to be sent) be identified, and optionally allows the
identification of an External URL (the content destination), the
identification of an Output context (which receives an expected
response from the content recipient), and characterization of the
Output Type.
You can use the Output Type property to characterize the type
of output data (in this case, the response from the destination
that received the results).
Results Asynchronous
Asynchronously sends the contents of a named context to
another context.
A results-async action requires that an Input context (the
source of the content to be sent) and an External URL (the
content destination) be identified.
Rewrite Header
Implements a URL Rewrite Policy.
A rewrite action requires that a URL Rewrite Policy be
identified.
Route using Stylesheet or XPath Expression
Performs dynamic, style sheet-based routing.
A route-action requires that an Input context (the source of
the document to be routed) and either a Transform style sheet
be identified or an XPath Map be identified.
Route using Variables
Routes message to an explicit destination.
A route-set action requires that an External URL (the routing
destination) be identified, and optionally allows the
identification of SSL Credentials to support a secure
connection to the destination.
Set Variable
Sets a variable.
A setvar action requires that a Variable Name, a Variable
Assignment, and an Output context (the context that contains
the variable) be identified. The variable name should take the
form var://context/somecontextname/somevarname.
Enforce SLM Policy
Implements an SLM Policy specified by the SLM Policy
property.
An slm action also requires that the Input context be identified,
and optionally allows for Output context identification. If the
output context is not identified, OUTPUT is used.
Strip Attachments
A strip-attachments action requires that an Input context (the
source of the document to be stripped) be identified, and

Appendix A. Referenced objects 315

 optionally allows the identification of an Attachment URI,
which specifies a single attachment to be deleted.
Deletes attachments (transmitted as part of a SOAP with
Attachments message package) from a named context.
Validate
Performs XML schema validation.
A validate action requires that an Input context (the source of
the document to be validated) and XML schema be identified.
The schema document can be specified either as a Schema URL
or Dynamic Schema. Schema validation optionally allows the
identification of an Output context, which stores the possibly
altered original document after validation, and of a URL
Rewrite Policy.
Transform
Applies a transformation style sheet to a named context
An xform action requires that an Input context (the source of
the document to be transformed), Output context (the
destination of the transformed document), and style sheet be
identified. The style sheet can be specified by either the
Transform or Dynamic Stylesheet property.
Specification of a URL Rewrite Policy and characterization of
the Output Type is optional.
Transform Binary
Applies a transformation style sheet that performs
binary-to-XML conversion to a named context
An xformbin action requires that an Input context (the source
of the document to be transformed), Output context (the
destination of the transformed document), and style sheet be
identified. The style sheet can specified as either Transform or
Dynamic Stylesheet. Only appears if licensed for DataGlue.
Transform using Processing Instruction
Performs transformation services based on instructions internal
to the candidate document
An xformpi action requires that an Input context (the source of
the document to be transformed), Output context (the
destination of the transformed document), and default style
sheet be identified. The default style sheet (which is used only
if the candidate document lacks internal processing
instructions) can specified by either the Transform or Dynamic
Stylesheet property.
Specification of a URL Rewrite Policy and characterization of
the Output Type is optional.
Input Use when the Action Type is aaa, call, convert-http, extract, filter,
log, results, results-async, route-action, setvar, slm,
strip-attachments, validate, xform, xformbin, or xformpi. In all of
these cases, specify the name of the context that contains the document
or service request on which the action will operate. When the action is
not the first action in a multistep rule, this value is very likely not
going to be INPUT but rather a context-sensitive name (such as
tempvar1, for example).

316 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Use the reserved word INPUT to identify the original input to the
Processing Policy. That is, the original client request or server response.
Leave blank if the Action Type is call, fetch, rewrite, route-set, or
setvar. These actions do not operate on the Input context.
Refer to Chapter 5, Defining processing policies, on page 87 for more
information about contexts and actions.
Transform
Use when the Action Type is filter, route-action, xform, xformbin, or
xformpi.
Specify the location of the style sheet that performs document filtering,
transformation, or routing.
You can specify the style sheet location as a URL or as a var:// URL
that expands to a URL.
If using a dynamic style sheet to perform filtering, routing, or
transformation, specify dynamic-stylesheet and use the Dynamic
Stylesheet property to specify the object (for example, a Document
Crypto Map) from which the dynamic style sheet is generated.
WTX Map File
Specify the WTX-generated map file that the Binary Transform
(xformbin) action uses to determine the input contexts and the output
contexts of the transform. For additional information, refer to IBM
WebSphere DataPower SOA Appliances: Integrating with WebSphere
Transformation Extender.
Top-Level Map Name
Specify which map in the WTX-generated map file that the Binary
Transform (xformbin) action uses this property to determine the input
contexts and the output contexts of the transform. For additional
information, refer to IBM WebSphere DataPower SOA Appliances:
Integrating with WebSphere Transformation Extender.
WTX Map Mode
Indicates whether to use mapping logic in XML-to-binary or
binary-to-XML WTX maps. Use when the Action Type is xformbin. For
additional information, refer to IBM WebSphere DataPower SOA
Appliances: Integrating with WebSphere Transformation Extender.
Output
Specify the name of the context that contains the results of the action
selected. Use when the Action Type is call, convert-http, extract,
fetch, setvar, xform, xformbin, or xformpi. Optional when the Action
Type is aaa, filter, log, results, results-async, route-action, slm, or
validate.
In each applicable case, the specified context contains the results of the
action. The results vary depending upon the action selected.
This context can be used, and usually is used, as the Input context to
the next action in a rule.
Use the reserved word OUTPUT to designate the context that contains the
content that is emitted by the service. This is the content that is sent
out on the wire. Typically, the last action in a rule sets Output to
OUTPUT.

Appendix A. Referenced objects 317

 If more than one action in a single rule sets Output to OUTPUT, the
results of all of those actions are emitted by the service. This is not a
recommended practice.
If both the Output and External URL properties are blank (the default
condition), the contents of the Input context are sent to the OUTPUT
context. OUTPUT identifies the final output from the Processing Policy.
That is, the processed client request or server response.
External URL
Use when the Action Type is fetch, log, results, results-async, or
route-set.
v If the Action Type is fetch, identify the location of the document to
fetch.
v If the Action Type is log, identify the destination of the generated
log message. You can specify the document location as a URL or as a
var:// URL that expands to a URL.
v If the Action Type is results or results-async, optionally identify
the remote destination that receives the transmitted context.

If both Output and External URL are blank (the default condition), the
contents of the Input context are sent to the OUTPUT context. OUTPUT
identifies the final output from the Processing Policy. That is, the
filtered, transformed, or otherwise-processed client request or server
response.

You can specify the destination as a protocol-specific transport URL or

as a var:// URL that expands to a URL.
v If the Action Type is route-set, identify the routing destination. You
can specify the destination as a protocol-specific transport URL or as
a var:// URL that expands to a URL.
Schema URL
When the Action Type is validate, specify the location of the schema
that performs document validation.
You can specify the schema location as a URL or as a var:// URL that
expands to a URL.
If using a dynamic schema to perform validation, specify
dynamic-schema for the Schema URL property and use the Dynamic
Schema property to specify the object (for example, a Schema
Exception Map) from which the dynamic schema is generated.
Locate Named Inputs and Outputs
Use when the Action Type is xformbin to select how the transform
determines the input contexts and the output contexts. For additional
information, refer to IBM WebSphere DataPower SOA Appliances:
Integrating with WebSphere Transformation Extender.
URL Rewrite Policy
When the Action Type is rewrite, validate, xform, or xformpi, select
the URL Rewrite Policy implemented by this Processing Action.

Note: This URL Rewrite Policy rewrites the URLs found in the
document being processed. This affects the location of additional
resources, such a schema identified in a namespace declaration

318 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 in the XML payload, used during processing. This does not
change the destination of the output.
Refer to URL Rewrite Policy on page 339 for more information.
AAA Policy
Use when the Action Type is aaa to select the AAA Policy
implemented by this Processing Action. Refer to AAA Policy on page
239 for more information.
SLM Policy
Use when the Action Type is slm to select the SSL Policy implemented
by this Processing Action. Refer to SLM policies on page 328 for
more information.
Dynamic Schema
Optional when the Action Type is validate. Select the object (Schema
Exception Map) from which the dynamic schema is generated.
If using a dynamic schema to perform validation, first specify
dynamic-schema for the Schema URL property.
Refer to Schema Exception Map on page 327 for more information.
Dynamic Stylesheet
Optional when the Action Type is filter, route-action, xform,
xformbin, or xformpi. Select the object (for example, a Document
Crypto Map) from which the dynamic style sheet is generated.
If using a dynamic style sheet to perform filtering, routing, or
transformation, first specify dynamic-stylesheet for the Transform
property.
Refer to Document Crypto Map on page 282 for more information.
Output Type
Optional when the Action Type is fetch, log, results, xform, or
xformpi to specify the format of the output. The following output types
are available:
Default
Read the content-type from the resulting document. If the
content-type is XML or not declared, the content is treated as
XML, otherwise as binary.
XML The content is treated and parsed as XML.
Binary
The content is treated as binary and not parsed.
Event Use when the Action Type is checkpoint to select the type of event that
triggers the checkpoint. The following events are available:
Authentication Complete
(Default) Signifies the completion on an authentication process.
Fault Signifies a fault condition.
Request
Signifies the input as a server-originated document.
Response
Signifies the input as a client-originated document.

Appendix A. Referenced objects 319

 Input Conversion
Optionally use when the Action Type is convert-http to select the
Input Conversion Map used by this Processing Rule to perform
HTTP-to-XML conversion. Refer to HTTP Input Conversion Map on
page 283 for more information.
XPath Use when the Action Type is extract. Specify the XPath expression
that is applied to the context identified by the Input property.
You can specify the expression in standard XPath format or as a var://
URL that expands to an XPath expression.
XPath Map
Use when Action Type is route-action, select an XPath Map.
Variable Name
Use with the Variable Assignment property when Action Type is
setvar or extract.
v For setvar, specify the variable to be created.
v For extract, Optionally specify the variable in which to store the
results of the XPath operation.
Variable Assignment
Use with the Variable Name property when Action Type is setvar or
extract. Specify the variable value.
SSL Cred
Optionally use when the Action Type is route-set. Specify the name of
the SSL Proxy Profile used to establish a secure connection with the
routing destination.
Refer to Defining SSL Proxy Profile objects on page 19 for more
information.
Attachment URI
Optionally use when the Action Type is strip-attachments. Specify the
URI of the specific attachment to be discarded.
Error Mode
When the Action Type is on-error, select the action to take upon an
error condition .
Abort Stop executing the current rule
Continue
Continue executing the current rule
Error Input
Use when the Action Type is on-error to optionally identify the input
context to the error-rule identified by Style Policy Rule.
If no input context is identified, the input context of the failed action is
used as the default input context for the invoked error-rule.
Error Output
Use when the Action Type is on-error to optionally identify the output
context from the error-rule identified by Style Policy Rule.
If no output context is identified, the output context of the failed action
is used as the default output context for the invoked error-rule.
Use OUTPUT to transmit the error message to the requesting client.

320 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Processing Rule
Use when the Action Type is call or on-error.
Specify the name of the Processing Rule or error-rule invoked by the
action.
Log Level
When the Action Type is log, select the priority of the generated log
message. Defaults to notice.
Log Type
Optional when the Action Type is log. Characterize log contents.
Defaults to none.
After completing basic Processing Action configuration, you can
optionally identify parameter/value pairs that are available to style
sheets used by this action.
Asynchronous
Determine whether the action is asynchronous:
on Marks the action as asynchronous. This action does not need to
complete for the next action in the processing rule to begin.
When asynchronous, you can cause processing to wait for the
action to complete by adding this action to a subsequent
event-sink action in the same processing rule.
off (Default) Marks the action as synchronous. This action must
complete for the next action in the processing rule to begin.

Named Inputs tab

Click the Named Inputs tab to explicitly determine the Named Inputs for the
action. This screen is blank unless the Locate Named Inputs and Outputs property
is set to Explicit.

For additional information, refer to IBM WebSphere DataPower SOA Appliances:

Integrating with WebSphere Transformation Extender.

Named Outputs tab

Click the Named Outputs tab to explicitly set the output contexts for the action.
This tab is blank unless the Locate Named Inputs and Outputs property is set to
Explicit.

For additional information, refer to IBM WebSphere DataPower SOA Appliances:

Integrating with WebSphere Transformation Extender.

Stylesheet Parameters tab

To configure stylesheet parameters, use the following procedure:
1. Click Stylesheet Parameter to display the Processing Action Configuration
(Stylesheet Parameter) screen.
2. Click Add to display the Stylesheet Parameter Property window.
3. Provide the following inputs:
Parameter Name
Specify the name of the parameter.
Parameter Value
Specify the value of the parameter.

Appendix A. Referenced objects 321

 4. Click Save to return to the Processing Action Configuration (Stylesheet
Parameter) screen.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Processing Metadata
A Processing Metadata object identifies items of metadata information from or
about a transaction, such as the value of a protocol header (such as HTTP Host) or
the size of the message. These items of information will be retrieved and returned
to the object referencing the Processing Metadata object, such as a AAA Policy.

For example, a business use case might require the DataPower appliance to
authenticate a user based on the user identity in an MQ protocol header, coupled
with the name of the MQ Queue Manager that holds the request message. The
AAA Policy that implements this solution would use a Processing Metadata object
to retrieve those two meta-items and return them in a nodeset to the AAA Extract
Identity step.

To add a Processing Metadata object, use the following procedure:

1. Select Objects XML Processing Processing Metadata to display the
Processing Metadata catalog.
2. Click Add to display the Processing Metadata object configuration screen.
3. Use the properties on the Main tab to define name of the object.
4. Use the controls on the Metadata Item tab to define the metadata items that
this object retrieves.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Note: Refer to the store:///ProcessingMetadata.html file on the appliance for

complete information about the items available.

Main tab
Use the properties on the Main tab to provide the following inputs:
Name Specify an alphanumeric string for the name. Other objects can use this
name to reference this object.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.

Continue to the Metadata Item tab to configure the items retrieved by this object.

Metadata Items tab

Use the Metadata Item tab to configure the items retrieved by this object. Use the
controls to select the metadata item to include in the list of items that the
Processing Metadata object retrieves. The controls allow you to all or remove
metadata items.

322 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Adding metadata items
To add a metadata item, use the following procedure:
1. Click the Metadata Item tab.
2. Select the desired category from the Meta Category list. The list of available
metadata items depends on the category.
To configure custom metadata for a protocol header, select Custom Header.
To configure custom metadata for a system variable, select Custom Variable.
3. Select or specify the name of the metadata item. This name is the element name
of the item in the XML nodeset that is delivered to the referring object.
Whether you select or specify the name depends on the selected category.
v For all categories except Custom Header and Custom Variable, select the
desired metadata item from the Metadata Item list.
v For Custom Header and Custom Variable, specify the alphanumeric name of
the metadata item in the Metadata Item field.
4. For Custom Header and Custom Variable only, specify the exact name of the
protocol header or system variable to examine for the custom item in the
Custom Data Source field. For example, the desired custom HTTP header can
be ASN-Ob1.
5. Click Add.

Removing metadata items

To remove a metadata item, use the following procedure:
1. Click the Metadata Items tab.
2. Click the Remove link adjacent to the item in the list.

Processing Policy
A Processing Policy consists of a list of processing rules. Each Processing Rule is
associated with a Matching Rule that specifies a document set subject to the rules
directives.

Candidate documents presented to the Processing Policy are sequentially evaluated

against each policy rule. Consequently the order of rule placement in a policy can
be critical to ensuring intended behavior.
1. Select Objects XML Processing Processing Policy to display the Processing
Policy catalog.
2. Click Add to display the Processing Policy Configuration (Main) screen.
3. Provide the following inputs:
Name Specify the name of this Processing Policy.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Default Stylesheet for SOAP
Identify the default filter for the policy. The default filter is used to
accept or reject any offered content that does not conform to any of the
match criteria in the processing rules of the processing policy. Specify

Appendix A. Referenced objects 323

 the style sheet URL or retain the default value, store:///
filter-reject-all.xsl. As its name implies, filter-reject-all.xsl rejects all
offered content.
Default Stylesheet for XSL Transforms
Identify the default transform style sheet for the policy. The default
transform style sheet is used to transform any offered content that does
not conform to any of the match criteria contained with the processing
rules for the policy. Specify the URL of the style sheet or retain the
default value, store:///identity.xsl.

Policy Maps tab

1. Click the Policy Maps tab to display the Processing Policy Configuration
(Policy Maps) screen.
2. Click Add to display the Policy Maps Property window. Use this window to
add one or more Processing Rule/Matching Rule pairs to the Processing Policy.
3. Provide the following inputs:
Match Select a Matching Rule. The selected Matching Rule is used with a
Processing Rule to determine if a candidate document is subject to the
Processing Rule.
A candidate document that matches all of the Matching Rule criteria is
processed according to the directives defined by the associated
Processing Rule. The filtered/transformed/or otherwise-processed
document is then passed to the next sequential Processing Rule (if one
exists) for additional manipulation or output to the intended recipient.
A candidate document that does not match all of the Matching Rule
criteria is passed to the next sequential rule for evaluation using that
rules criteria, and so on. A candidate failing to match any criteria is
filtered or transformed using the default filtering and transformation
style sheets.
Refer to Matching Rule on page 292 for more information.
Rule Select a Processing Rule. Refer to Processing Rule for more
information.
4. Click Save to return the Processing Policy Configuration (Policy Maps) screen.
5. If necessary, repeat the procedure to add additional rules to the Processing
Policy.
6. Click Apply to save the object to the running configuration.
7. Optionally, click Save Config to save the object to the startup configuration.

Processing Rule
You can create global, reusable processing rules which can later be assigned to one
or more processing policies.
1. Select Objects XML Processing Processing Rule to display the catalog.
2. Click Add to display the configuration screen.
3. Provide the following inputs:
Name Specify the name of this Processing Rule.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.

324 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Comments
Specify a descriptive object-specific summary.
Rule Direction
Select the rule type or direction.
Error A specialized bidirectional rule used for error handling
Client to Server
A rule applied only to client-originated documents
Server to Client
A rule applied only to server-originated documents
Both Directions
A bidirectional rule applied to both client- and
server-originated documents
Input Filter
Select a decompression algorithm to apply to the entire message
payload prior to the first action of the rule executing.
gzip The message will be decompressed using the gzip algorithm.
PKZIP
The message will be decompressed using the pkzip algorithm.
If the message is not compressed using the selected algorithm, an error
will result. This is, in effect, a filter.
Output Filter
Select a compression algorithm to apply to the entire message payload
after the last action of the rule executes.
gzip The message will be decompressed using the gzip algorithm.
PKZIP
The message will be decompressed using the pkzip algorithm.
The created archive contains only one file. If the message contains
attachments, the attachments are contained in the one file.
Non-XML Processing
Select whether to enable or disable the processing of non-XML
documents.
on Enables the processing of non-XML documents.
off (Default) Disables the processing of non-XML documents.
Unprocessed
Select whether to determine whether the actions of the rule will take
effect on the message. This duplicates the Request Type and Response
Type properties of the services.
Actions
Use the Add and Delete buttons, with the list of available processing
actions, to manage actions for this processing rule.
4. Click Apply to save the object to the running configuration.
5. Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects 325

RADIUS Settings
RADIUS settings define RADIUS servers. RADIUS settings can be defined in the
default domain only.

Within the DataPower appliance, RADIUS servers can be used for the following
purposes:
v On any appliance, to authenticate access using RBM.
v On all appliances except XML Accelerator XA35, to authenticate access in AAA
Policy objects.

Each RADIUS server has a positional value that the DataPower appliance uses to
determine the order in which to contact the servers. The appliances contacts the
servers from most preferred (lowest number) to least preferred (highest number).
The appliance sends the request to the next server based on the global timeout
value and the global retry value.

If the configuration defines three RADIUS servers with positional values of 10, 20,
and 30, the appliance contacts the servers in the following sequence:
1. Requests are always first sent to server 10.
2. If the request times out, it is sent to server 20.
3. If the request times out, it is sent to server 30.

NAS-identifier
The DataPower appliance is a client to RADIUS servers. The NAS-identifier is a
RADIUS attribute that the client uses to identify itself to a RADIUS server. The
NAS-Identifier, as defined in Section 5.32 of RFC 2865, can be used instead of an IP
address to identify the client. The NAS-identifier consists of one or more octets and
must be unique in the scope of the RADIUS server. The NAS-identifier is often the
fully qualified domain name (FQDN) of the RADIUS client.

Configuring RADIUS Settings

To configure RADIUS settings, use the following procedure:
1. Select Administration Access RADIUS Settings.
2. Configure global settings for all RADIUS servers.
a. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
b. Specify a descriptive object-specific summary in the Comment field.
c. Specify the NAS-identifier in the Identifier field.
d. Specify the interval in milliseconds that the appliance waits for a reply from
a RADIUS server before retransmitting the outstanding request in the
Timeout field. Use an integer in the range of 1 through 5000. The default is
1000.
e. Specify the number of times that the appliance retransmits an unanswered
request to a RADIUS server before contacting another server in the list in
the Retries field.
3. Do not define RADIUS servers to authentication CLI access without the use of
RBM. In other words, do not define any RADIUS servers on the CLI Servers
tab. This functionality is deprecated. If using RADIUS for authentication, define
RADIUS as the RBM method and define the appropriate RADIUS servers on
the AAA/RBM Servers tab.

326 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 4. Define RADIUS servers for use by AAA Policy objects or by the RBM policy.
a. Click the AAA/RBM Servers tab.
b. Define a server.
1) Click Add.
2) Specify the relative position of this server in the list in the Number
field.
3) Specify the IP address or domain name of the server in the Server
Address field,
4) Specify the listening port on the remote server in the Server Port field.
The default is 1812.
5) Specify the password to log in to the server in the Secret field.
6) Reenter the password in the Confirm Secret field.
7) Click Save.
c. Repeat the previous step to add additional servers to the list.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Schema Exception Map

A Schema Exception Map enables the validation of partially encrypted documents
by providing a list of XPath expression-based rules that identify XML document
elements to encrypt.
1. Select Objects XML Processing Schema Exception Map to display the
Schema Exception Map catalog.
2. Click Add to display the Schema Exception Map Configuration (Main) screen.
3. Provide the following inputs:
Name Specify the name of the Schema Exception Map.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.
Original Schema URL
Specify the location of the base schema. The base schema is used with
this Schema Exception Map to validate partially encrypted documents.
Validation is performed by an internal dynamic schema that combines
the schema-based validation requirements with the exception rules in
this Schema Exception Map.

Rules tab
1. Click the Rules tab to display the Schema Exception Map Configuration (Rules)
screen.
2. Click Add to display the Rules Property window. Use this window to define
schema exception rules.
3. Provide the following inputs:
XPath Expression
Specify an XPath expression. This expression defines a schema element
or elements subject to this rule. Click XPath Tool to launch the
graphically-oriented XPath expression builder. You will need to upload
Appendix A. Referenced objects 327
 an example document. The tool then allows you to click on an element
to construct the corresponding XPath expression.
Type Identify the exception type.
Allow Encrypted
Specifies that elements defined by the XPath expression can be
encrypted
Require Encrypted
Specifies that elements defined by the XPath expression must
be encrypted
4. Click Save to return to the Schema Exception Map Configuration (Rules)
screen, which now displays the exception rule.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

SLM policies
An SLM policy provides precise specification of user and resource groups subject
to administrative control and possible sanctions. An SLM is implemented by an
instance of an SLM Policy object that consists of one or more policy statements.
Policy statements are sequentially processed in their configured order. If a policy
statement generates a rejection, the message is filtered (dropped) and policy
execution terminates.

Each SLM statement consists of:

v An instance of the SLM Credential Class object, which defines a user group
subject to policy restrictions
v An instance of the SLM Resource Class object, which identifies a resource group
subject to policy restrictions
v An instance of the SLM Schedule object, which specifies the time frame during
which the policy is enforced
v An instance of the SLM Action object, which specifies administrative operations
or sanctions
v A threshold, which specifies the level to trigger the SLM Action

Unlike Message monitors and Web services monitors, SLM monitors are not
directly assigned to a DataPower service. SLM monitors are implemented as part
of a processing policy.

SLM Credentials Class

An SLM Credentials Class defines the user group that is subject to an SLM Policy.
An SLM Credentials Class consists of:
v A credential type to specify the method to use to obtain user credentials
v A match type to specify whether all or only select members of the group that is
identified by the credential type are subject to this SLM Policy
v Optionally, a credential value to use to identify specific instances of a credential
type to subject to this SLM Policy

To create a Credentials Class, use the following procedure:

1. Select Objects Monitoring SLM Credential Class to display the SLM
Credential Class catalog.
2. Click Add to display the SLM Credential Class Configuration screen.

328 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
a. Specify a class name in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Select the type of credentials from the Credential Type list
Client IP
Specifies that this Credentials Class is defined by IP Address.
Custom Stylesheet
Specifies that membership in this Credentials Class is defined by an
XSLT style sheet.
Extracted Identity
Specifies that the user identities extracted by an AAA Policy are
members of this Credentials Class.
IP from Header
Specifies that membership in this Credentials Class is defined by an IP
address taken from the value of an HTTP header. The Header
property field appears when this option is selected.
Mapped Credential
(Default) Specifies that credentials returned by an AAA map credential
operation are members of the Credentials Class.
MQ Application
Specifies that membership in this Credentials Class is defined by MQ
application name.
Request Header
Specifies that membership in this Credentials Class is defined by the
value of an HTTP header. The Header property field appears when
this option is selected.

Note: The Mapped Credential and Extracted Identity methods can be used
only if the processing policy that uses Credentials Class implemented
an AAA Policy that provides the needed credentials.
e. If the credential type is Custom Stylesheet, use the Custom Stylesheet field
to specify the location of the style sheet.
f. Use the Match Type list to specify match criteria.
Exact
(Default) Specifies that only a subset of the group that is defined by
Credential Type is subject this SLM Policy. The subset is defined by
one or more entries specified by Credential Value. The policy
statement is evaluated only in the event of an exact match.
Per Extracted Value
Specifies that the appliance extracts and keeps a list of all unique
credentials of the specified type. All configured policies apply to each
of the extracted credentials.
Regular Expression
Specifies that only PCRE-style expressions that match the values are
subject to the SLM policy. The subset is defined by one or more entries
specified by Credential Value. The policy statement is evaluated only
in the event of a match.

Appendix A. Referenced objects 329

 g. If the Match Type is Exact or Regular Expression, use the Add and Delete
buttons and the adjacent field to specify one or multiple credential values.
3. Click Apply to save the object to the running configuration.
4. Optionally, click Save Config to save the object to the startup configuration.

SLM Resource Class

An SLM Resource Class identifies a set of resources subject to an SLM Policy. An
SLM Resource Class consists of:
v A resource type, which specifies a method used to obtain the resource value
v A match type, which specifies if all or selected members of the group identified
by the resource type are subject to this SLM Policy
v A resource value, which can be used to identify specific instances of a resource
type that is subject to this SLM Policy

To create a Resource Class object, use the following procedure:

1. Select OBJECT Monitoring SLM Resource Class to display the SLM
Resource Class catalog.
2. Click Add to display the SLM Resource Class Configuration screen.
3. Specify a class name in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.
6. Select the method to obtain the resource value from the Resource Type list.
Concurrent Connections
Defines membership by concurrent TCP connections. The TCP
connection is from the requesting client to the DataPower appliance.
Generally, a client opens only one connection to the appliance at a time.
Concurrent connections are not specific to user credentials.
Concurrent Transactions
Defines membership by concurrent transactions.
Custom Stylesheet
Defines membership by an XSLT style sheet.
Destination URL
Defines membership by the destination URL. The destination URL is the
URL output to the destination server. The destination URL might be
identical to the URL that was requested by the client.
Error Code
Defines membership by error code values.
Front URL
Defines membership by a client-requested URL or by a rewritten
client-requested URL.
Mapped Resource
(Default) Defines membership by the identities that are returned from an
AAA map resource operation.
This method can be used only when the processing policy implements
an AAA Policy that provides the required resource mapping.
MQ Reply Queue
Defines membership by the MQ reply queue.

330 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 MQ Request Queue
Defines membership by the MQ request queue.
Requests only
Restricts membership to all client requests.
Responses Only
Restricts membership to all server requests.
SOAP Faults
Restricts membership to SOAP fault messages.
UDDI Subscription
Defines membership by a UDDI Subscription key.
WSDL
Defines membership by a WSDL file.
WSDL Operation
Defines membership by the name of a WSDL operation.
WSDL Port
Defines membership by the name of a WSDL port.
WSDL Service
Defines membership by the name of a WSDL service.
WSRR Subscription
Defines membership by a WSRR subscription.
XPath Expression
Defines membership by an XPath expression.
7. If the resource types is Mapped Resource, Destination URL, Error Code,
Front URL, MQ Reply Queue, MQ Request Queue, WSDL, WSDL
Operation, WSDL Port, or WSDL Service, select the match criteria from the
Match Type list. The following choices are available:
Exact
(Default) Specifies that only exact matches to resource values are subject
to the SLM policy. Resources that do not match the values provided in
the Resource Value list are not subject to the SLM policy.
Per Extracted Value
Specifies that the appliance extracts and keeps a list of all unique
resources of the specified type. All configured policies apply to each of
the extracted resources.
Regular Expression
Specifies that only PCRE-style expression matches to resource values are
subject to the SLM policy. Resources that do not match the values
provided in the Resource Value list are not subject to the SLM policy.
8. If the match criteria is Exact or Regular Expression, use the Add and Delete
buttons with the adjacent field to create a Resource Value list that defines one
or more resource values.
9. If the resource type is Custom Stylesheet, specify the location of the XSLT
style sheet in the Custom Stylesheet field.
10. If the resource type is UDDI Subscription, specify the subscription key in the
UDDI Subscription field.
11. If the resource type is WSRR Subscription, select the subscription from the
WSRR Subscription list.

Appendix A. Referenced objects 331

 12. If the resource type is XPath Expression, specify the XPath expression is the
XPath Filter filter or click XPath Tool to define the XPath expression.
13. Click Apply to save the object to the running configuration.
14. Optionally, click Save Config to save the object to the startup configuration.

SLM Action
An SLM Policy Action defines a procedure triggered when a threshold value is
attained. To create an SLM Action, use the following procedure:
1. Select OBJECT Monitoring SLM Action to display the SLM Action catalog.
2. Click Add to display the SLM Action Configuration screen.
a. Specify an action name in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Use the Type list to specify the action type.
Log Only
After the action is triggered, write a log entry; continue to process
subsequent transactions
Reject
After the action is triggered, write a log entry; drop traffic until
monitored entity is in conformance levels
Shape
After the action is triggered, write a log; next 2500 transactions are
queued for later transmission when the monitored entity is in
conformance levels; after 2500 transactions have been queued, further
transactions are rejected
e. Use the Log Priority list to specify the log priority.
3. Click Apply.

SLM Schedule
An SLM Schedule specifies a time period during which the associated SLM Policy
is enforced. To create an SLM Schedule, use the following procedure:
1. Select OBJECT Monitoring SLM Schedule to display the SLM Schedule
catalog.
2. Click Add to display the SLM Schedule Configuration screen.
a. Specify a schedule name in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Use the Week Day check boxes to specify the days of the week on which
this SLM Policy is enforced, For example, check Saturday and Sunday to
specify weekend scheduling.
e. Using 24-hour time format (hh:mm:ss), specify the start time for this
schedule in the Start Time field. For example, if the schedule is to be
enforced for 8:00 AM to 8:30 PM, specify 08:00:00.
f. Specify the number of minutes that the schedule is enforced in the Duration
field. For example, if the schedule is to be enforced for 8:00 AM to 8:30 PM,
specify 750.
3. Click Apply

332 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
SLM Policy
Use the following procedure to create an SLM Policy from the Configure SLM Rule
Action Window. To create an SLM Policy, perform the following procedure:
1. Select OBJECT Monitoring SLM Policy to display the SLM Policy catalog.
2. Click Add to display the SLM Policy Configuration (Main) screen.
a. Specify the name of this SLM Policy in the Name field.
b. Retain the default setting for the Admin State toggle. To place the object in
an inactive administrative state, click disabled.
c. Specify a descriptive object-specific summary in the Comment field.
d. Use the Evaluation Method list to specify the Policys operational mode.
Terminate at First Reject
(Default). Policy execution ceases once an incoming document is
filtered
Terminate at First Action
Policy execution ceases once a policy action is invoked
Execute All Statements
Policy execution ceases only when all policy statements have been
evaluated
e. Use the Peer Group list to enable a multi-appliance SLM and to specify the
appliance group.
An SLM Policy can be enforced across a group of appliances to handle
load-balanced traffic that is destined for the same resources. A Peer Group
establishes a data sharing protocol among these appliances, such that each
appliance includes the traffic that has passed through the other peers when
calculating whether or not a threshold was reached.
Refer to Peer Group on page 311 for more information.
3. Click the Statement tab to display the SLM Statement catalog.
4. Click Add to display the Statement Property window.
a. Specify a unique, positive integer in the Identifier field. This value is the
index and indicates the order in which the statement is executed.
Statements are executed from least to greatest.
b. Optionally specify a descriptive string in the User Annotation field.
c. Select the group of users that is subject to this SLM Policy from the
Credential Class list. Without an SLM Credential Class, all users and
transactions are subject to this policy. Refer to SLM Credentials Class on
page 328 for more information.
d. Select the group of resources that are subject to this SLM Policy from the
Resource Class list. Without an SLM Resource Class, all requested resources
are subject to this policy. Refer to SLM Resource Class on page 330 for
more information.
e. Select the time frame when this SLM Policy is enforced from the Schedule
list. Without an SLM Schedule, the policy is enforced at all times. Refer to
SLM Schedule on page 332 for more information.
f. Select the administrative action that the SLM Policy invokes from the SLM
Action list. Refer to SLM Action on page 332 for more information.
g. Specify the length of the measurement interval in seconds in the Threshold
Interval Length field. The default is 0, which allows all messages and never
triggers the threshold to enforce the SLM Action.
h. Select how to measure intervals from the Threshold Interval Type list.

Appendix A. Referenced objects 333

 Fixed (Default) Use a fixed interval. A fixed interval is a discrete block of
time. For example, from 8:00 A.M. to 9:00 A.M. Fixed intervals are
calculated from the start of the assigned SLM Schedule. Without an
SLM Schedule, fixed intervals are calculated from 12:00 A.M.
Moving
Use a moving interval in seconds. A moving interval is a
sliding-window; for example, the last 60 minutes.
i. Define the threshold execution methodology.
v If Greater Than or Less Than, the threshold is triggered and an SLM
Action enforced when the threshold level is greater than or less than,
respectively, the defined value. Enforcement continues until the value
specified by this low threshold is reached.
1) Select Greater Than or Less Than from the Threshold Algorithm list.
2) Select how to characterize the monitored count from the Threshold
Type list.
Count All
(Default) The threshold level is applied to the resources specified
by the SLM Resource Class.
Count Errors
The threshold is based on errors.
Backend Latency
The threshold is based on server latency.
Internal Latency
The threshold is based on internal latency (processing time).
Total Latency
The threshold is based on the sum of measured latencies.
3) Specify the threshold that triggers the SLM Action in the Threshold
Level field. The units of measure depends on the threshold type.
If the threshold is a count, specify an integer for the aggregate
count.
If the threshold is latency, specify an integer for the latency in
seconds.
The default is 0, which means that no message is accepted.
v If High-Low, the threshold is triggered and an SLM Action enforced when
the threshold level is reached. Enforcement continues until the value
specified by this low threshold is reached.
1) Select High-Low from the Threshold Algorithm list.
2) Select how to characterize the monitored count from the Threshold
Type list.
Count All
(Default) The threshold level is applied to the resources specified
by the SLM Resource Class.
Count Errors
The threshold is based on errors.
Backend Latency
The threshold is based on server latency.
Internal Latency
The threshold is based on internal latency (processing time).

334 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Total Latency
The threshold is based on the sum of measured latencies.
3) Specify the high threshold in the Threshold Level field. The units of
measure depends on the threshold type.
If the threshold is a count, specify an integer for the aggregate
count.
If the threshold is latency, specify an integer for the latency in
seconds.
The default is 0, which means that no message is accepted.
4) Specify the low threshold in the High Low Release Level field
v If Token Bucket, the algorithm consists of a bucket with a maximum
capacity of N tokens that refills at a rate of R tokens per second. Each
token typically represent a quantity of whatever resource is being
rate-limited.
1) Select Token Bucket from the Threshold Algorithm list.
2) Select how to characterize the monitored count from the Threshold
Type list.
Count All
(Default) The threshold level is applied to the resources specified
by the SLM Resource Class.
Count Errors
The threshold is based on errors.
Backend Latency
The threshold is based on server latency.
Internal Latency
The threshold is based on internal latency (processing time).
Total Latency
The threshold is based on the sum of measured latencies.
3) Specify the threshold that triggers the SLM Action in the Threshold
Level field. The units of measure depends on the threshold type.
If the threshold is a count, specify an integer for the aggregate
count.
If the threshold is latency, specify an integer for the latency in
seconds.
The default is 0, which means that no message is accepted.
4) Specify the size of the committed burst in the Burst Limit field.
The committed burst defines how much traffic can be send during a
reporting interval. The burst size should be at least twice the value of
the threshold level. The default is 0, which means the burst limit is the
configured threshold level.
j. Specify the reporting interval in minutes in the Reporting Aggregation
Interval field. This property determines the interval at which to report
statistics. This property has no effect on threshold intervals.
k. Specify the maximum aggregation of reporting records in the Maximum
Records Across Intervals field. A single aggregation interval could contain
multiple records; for example, one record per resource or credential. Use
this property to configure the maximum number of total records to save
across the maximum number of saved intervals.

Appendix A. Referenced objects 335

 l. The Auto Generated by GUI toggle indicate whether this statement was
auto-generated as part of a default SLM configuration. This property is
read-only.
m. Specify the number of records for the combination of credentials and
resources in the Maximum Credentials-Resource Combinations field. This
property limits the maximum number of combinations and allows a
maximum memory-consumption threshold to be set. The default is 5000.
5. Click Save.

SOAP Header Disposition Table

A SOAP Header Disposition Table contains a list of instructions that controls how
to handle SOAP headers, children elements, or both SOAP headers and child
elements. This object is used by a transform action that specifies the
store:///soap-refine.xsl style sheet.
1. Select Objects XML Processing SOAP Header Disposition Table to display
the SOAP Header Disposition Table catalog.
2. Click Add to display the SOAP Header Refine Instruction configuration (Main)
screen.
3. Provide the following inputs:
Name Specify the name of the SOAP Header Disposition Table.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
Comments
Specify a descriptive object-specific summary.

SOAP Header Refine Instruction tab

1. Click the SOAP Header Refine Instruction tab to display the SOAP Header
Disposition Table configuration (SOAP Header Refine Instruction) screen.
2. Click Add to display the SOAP Header Refine Instruction Property window.
Use this window to define refinement instructions.
3. Provide the following inputs:
Namespace URI
Specify the namespace URI of the SOAP header element. The default is
a blank string, which indicates no restriction.
Header Local Name
Specify the local name of the SOAP header element. The default is a
blank string, which indicates no restriction.
Child Element Local Name
Specify the local name of the direct child element of the SOAP header.
The default is a blank string, which indicates no restriction.
Refine Action
Select the refinement action to take. By default the processing rule,
defined by the SOAP specification, is used to remove the SOAP header,
to keep the SOAP header, or to issue a SOAP fault with the assumption
that all SOAP headers were processed by previous actions.
Processed
Take the default SOAP action, because the specified element
was processed.
336 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Unprocessed
Take the default SOAP action, because the specified element
was not processed.
Keep Keep this SOAP header or child element.
Remove
Remove this SOAP header or child element.
Fault Generate a SOAP fault if the element exists.
4. Click Save to return to the SOAP Header Disposition Table configuration
(SOAP Header Refine Instruction) screen, which now displays the refinement
instruction.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

SQL Data Source

The use of a SQL data source requires the SQL-ODBC license. The SQL data source
is used by the SQL action in a processing rule.

Note: SQL-ODBC is a licensed feature that is not available on all DataPower

appliances.

An SQL Data Source object provides the configuration to establish a direct

connection to a data server. When configured, it is possible to dynamically perform
database operations (such as SELECT and INSERT) on the remote database
instance. The SQL action performs these dynamic operations. The data that is
retrieved can then be used in a processing policy. Conversely, the data that is
obtained by the processing policy can be stored in the configured database
instance.

High-level configuration
To configure an SQL Data Source, use the following procedure:
1. Select Objects Network Setting SQL Data Source to open the SQL Data
Source catalog.
2. Click Add to display the SQL Data Source configuration (Main) screen.
3. On the Main tab, define the basic configuration. Refer to Defining the base
configuration for details.
4. On the Data Source Configuration Parameters tab, define the optional but
valid ODBC (or CLI) configuration parameters. Refer to Defining
configuration parameters on page 338 for details.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

Defining the base configuration

To define the base configuration of an XML Manager, use the following procedure:
1. Specify the name of the object in the Name field.
2. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
3. Specify a descriptive object-specific summary in the Comment field.
4. Select a database vendor (and version) from the Database type list. The remote
data source must agree with this selection.

Appendix A. Referenced objects 337

 5. Define the connection details:
a. Specify the user name or account to establish the data source connection in
the Connection Username field. This user name is maintained by the
database server, not the appliance.
b. Specify the password to establish the data source connection in the
Connection Password field.
c. Specify the appropriate data source identifier (for example, Oracle SID) in
the Data Source ID field.
d. Specify a domain name or IP address for the host where the data source
resides in the Data Source Host field.
e. Specify the port on which the data source listens in the Data Source Port
field.
6. Determine whether to set a limit on size of the data that is returned from a
SQL SELECT statement:
a. Use the Limit Returned Data toggle to enable or disable the limit. When
disabled, the default size of returned data is 128 kilobytes.
on Sets a size limit. The default is 128.
off (Default) Does not set a limit.
b. When enabled, specify an integer for the maximum size (in kilobytes) of
data to return in the Returned Data Size Limit field.
7. Use the Allow Read-Only Access toggle to indicate whether to allow read-only
access to the data source.
on Allows read-only access, which is SELECT statements only.
off (Default) Allows read-write access, which are SELECT, UPDATE,
MODIFY, and DELETE statements as well as the execution of stored
procedures or functions.
8. Specify the maximum number of concurrent connections to allow in the
Maximum Connections field. The default is 10.
9. Optionally continue the configuration with Defining configuration
parameters.

Defining configuration parameters

Use this page to define optional but valid ODBC (or CLI) configuration parameters
for your data server connection. Configuration parameters modify the behavior of
the services that run with a data server. Some configuration parameters in the
configuration file are informational and define characteristics about the
environment. These configuration parameters cannot be modified.

To define configuration parameters, use the following procedure:

1. Click the Data Source Configuration Parameters tab.
2. Define a configuration parameter:
a. Click Add to display the Data Source Configuration Parameters Property
window.
b. Specify the name of the parameter in the Name field.
c. Specify the value for the parameter in the Value field.
d. Click Save to return to the catalog.
3. Repeat step 2 to define another configuration parameter.

338 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
URL Rewrite Policy
You can design a URL Rewrite Policy that defines rules for the following rewrite
and replacement operations:
v Rewrite the entire URL or a portion of the URL
v Replace a header value in the message
v Rewrite the HTTP POST body in the message

The rewrite rules in the URL Rewrite Policy are applied before document
processing. Therefore, the evaluation criteria in the Matching Rule is against the
rewritten value.

Use the following method to create a URL Rewrite Policy:

1. Select Objects XML Processing URL Rewrite Policy to display the URL
Rewrite Policy catalog.
2. Click Add to display the URL Rewrite Policy Configuration (Main) screen.
3. Provide the following inputs:
Name Specify the name of this URL Rewrite Policy.
Admin State
Retain the default setting. To place the object in an inactive
administrative state, click disabled.
URL Rewrite Direction
Select the direction of the URL Rewrite Policy. Direction is applied at
the service level and has no effect on other policies.
Both Applies to both client requests and server responses.
Request
Applies to client requests only.
Response
Applies to server responses only.
4. Continue with URL Rewrite Rule tab.

URL Rewrite Rule tab

1. Click the URL Rewrite Rule tab to display the URL Rewrite Policy Rule
Configuration (URL Rewrite Rule) screen.
2. Click Add to display the URL Rewrite Policy Property window.
3. Provide the following inputs:
URL Rewrite Type
Select the rule type.
absolute-rewrite
Rewrites the entire URL or a portion of the URL based on a
URL match.
content-type
Replaces the value of the Content-Type header based on a URL
match.
header-rewrite
Replaces the value of an arbitrary header based on its value.

Appendix A. Referenced objects 339

 post-body
Rewrites the body of an HTTP POST request. The POST body
contains the input values for a basic HTTP POST request.
rewrite
This rule type is deprecated.
Match Expression
Specify a PCRE (Perl-compatible regular expression) that defines the
match condition that triggers the rewrite rule. Depending on the rule
type, a candidate URL or specific HTTP header field is matched against
the expression.
v For absolute-rewrite, content-type, and post-body, defines the
expression to be matched against the URL.
.* or *
Matches any string.
(.*)xsl=(.*)\?(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by xsl=.
c. Followed by a text subpattern.
d. Followed by ?. The backward slash (\) in the PCRE is a
URL escape.
e. Followed by a text subpattern.
(.*)&[Xx][Ss][Ll]=([^&]+)(.*)
Matches a string of the following format:
a. A text subpattern.
b. Followed by &.
c. Followed by X or x.
d. Followed by S or s.
e. Followed by L or l.
f. Followed by =.
g. Followed by a text subpattern that does not contain an
ampersand (&) character.
h. Followed by a text subpattern.
v For header-rewrite, defines the expression to be matched against the
contents of a specific HTTP header field. For example *.* matches
any value.
PCRE documentation is available at http://www.pcre.org.
Input Replace Expression
Specify a PCRE-style replacement that defines the rewritten URL, HTTP
header field, or HTTP POST body.
v For absolute-rewrite, defines the rewritten URL.
If the match pattern is .* or *, specify the complete replacement.
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain
the second text subpattern, specify $2, and so forth. To replace the
second text subpattern only, specify $1xsl=ident.xsl?$3.
If a rewritten URL begins with a host name or port that is different
from the configured remote address, the host name or port portion of
the rewritten URL is ignored.

340 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 v For content-type, defines the replacement value for the Content-Type
header.
v For header-rewrite, defines the replacement value for the specified
header.
v For post-body, defines the rewritten body of the HTTP POST. For
example:
If the match pattern is .* or *, specify the complete replacement.
If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain
the second text subpattern, specify $2, and so forth. To omit the
second text subpattern only, specify $1$3.
Stylesheet Replace Expression
Specify a PCRE-style replacement that identifies the replacement style
sheet. This option is available for absolute-rewrite or post-body only.
v If the match pattern is .* or *, specify the complete replacement.
v If the match pattern is (.*)xsl=(.*)\?(.*), specify the evaluation
replacement for any text subpattern or retain the original text
subpattern. To retain the first text subpattern, specify $1; to retain the
second text subpattern, specify $2, and so forth. To retain the second
text subpattern only and not use the third text subpattern, specify
http://mantis:8000/$2.
Input URL Unescape
Select whether URL-encoded characters (for example, %2F) that occur in
the rewritten URL are replaced with literal character equivalents. This
option is available for absolute-rewrite or post-body only.
on Enables the substitution of literal characters for URL-encoded
characters.
off (Default) Disables the substitution of literal characters for
URL-encoded characters.
Stylesheet URL Unescape
Select whether URL-encoded characters (for example, %2F) that occur in
the replacement URL are replaced with literal character equivalents.
This option is available for absolute-rewrite or post-body only.
on (Default) Enables the substitution of literal characters for
URL-encoded characters.
off Disables the substitution of literal characters for URL-encoded
characters.
Header Name
Identifies the name of the header to have its value rewritten. The
header name must be entered exactly as it is defined in the message.
This option is for header-rewrite only.
URL Normalization
Select whether to enable normalization of URL strings. Normalizing a
URL compresses "." and ".." and converts backward slashes (\) to
forward slashes (/).
on (Default) Enables normalization.
off Disables normalization.
4. Click Save to return to the URL Rewrite Policy Configuration (Main) screen.

Appendix A. Referenced objects 341

 5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

User Agent
A User Agent is a client that initiates a request for a local service. An XML
Manager uses a User Agent, for example, to retrieve resources from elsewhere on
the network. The settings of a User Agent can affect messages that sent out by a
specific DataPower service when its XML Manager employs a User Agent.

Select Network User Agent to display the User Agent catalog.

Click Add to display the User Agent configuration (Main) screen.

Provide the following inputs:

Name Specify the User Agent name.
Admin State
Retain the default setting. To place the object in an inactive administrative
state, click disabled.
Comments
Specify a descriptive object-specific summary.
HTTP Request-Header
Optionally, include the User Agent HTTP request-header field in client
requests issued by this User Agent, and to specify the contents of the field.
The field contains information about the user agent that sends the request.
The HTTP specification does not require this field.
By default, the appliance does not include the request-header field. Leave
blank to suppress the inclusion of this field in client requests that the User
Agent issues.
Maximum Redirects
Specify the maximum number of HTTP redirect messages that this User
Agent can receive before the it declares the target URL as unreachable.
Timeout
Specify the amount of time, in seconds, that the connection can be idle
before the User Agent times out and closes the connection. Use an integer
in the range of 1 through 86400. The default is 300.

Note: The default timeout for a connection failure is 10 seconds, which

cannot be changed. The timeout applies when a specified server
cannot be contacted.

Click Apply to save the object to the running configuration and return to the object
catalog.

Optionally, click Save Config to save the object to the startup configuration.

Proxy Policy
The User Agent will forward all requests that meet the URL Matching Expression
to an HTTP server instead of to the host that is identified in the target URL. When
there are multiple proxy policies, candidate URLs are evaluated against each proxy
policy in the order in which it was created. Consequently, the sequence of proxy
policies is important.

342 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 1. Click the Proxy Policy tab to display the User Agent configuration (Proxy
Policy) screen.
2. Click Add to display the Proxy Policy Property window.
3. Provide the following inputs:
URL Matching Expression
Define the target URL sets associated with this Proxy Policy.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters.
For example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y]
would match x or y.

You can use any PCRE-compliant expression. For more information,

refer to http://www.pcre.org.
Skip Use the toggle to specify whether requests for an identified URL (that
is, a member of the target URL set) are forwarded to the specified
HTTP server.
on Does not forward requests.
off (Default) Forwards requests to the specified HTTP server. When
selected, provide the following inputs.
Remote Host
Specify the host name or IP address of the HTTP server
to which to forward requests.
Remote Port
Specify the port on the HTTP server to which to
forward requests.
4. Click Save.
5. Click Apply to save the object to the running configuration.
6. Optionally, click Save Config to save the object to the startup configuration.

SSL Proxy Profile

Certain User Agent requests require a secure (SSL-enabled) connection. The
resources required for SSL support are provided by an SSL Proxy Profile. Refer to
Defining SSL Proxy Profile objects on page 19 for more information.

To assign an instance of an SSL Proxy Profile object to the User Agent, use the
following procedure:
1. Click the SSL Proxy Profile Policy tab.
2. Click Add.
3. In the URL Matching Expression field, define the target URL sets associated
with this policy. If the target URL matches this expression, the communication
will use SSL employing the SSL Proxy Profile specified.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any character.

Appendix A. Referenced objects 343

 ? Indicates a single character that matches one occurrence of any single
character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would match x
or y.

You can use any PCRE-compliant expression. For more information, refer to
http://www.pcre.org.
4. From the SSL Proxy Profile list, select an instance of the SSL Proxy Profile
object to support secure access to the HTTP Proxy Server. The SSL Proxy Profile
must be either a client or two-way profile.
5. Click Save.

Basic HTTP Authentication

Certain User Agent requests require basic HTTP authentication (user name and
password). Click the Basic-Auth Policy tab to display the User Agent configuration
(Basic-Auth Policy) screen, which lists all user name/password pairs.

Click Add to display the Basic-Auth Policy Property window.

Provide the following inputs:

URL Matching Expression
Define the target URL(s) set associated with this policy. If the target URL
matches this expression, an HTTP Authorization header will be added,
using the User Name and Password supplied.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
The URL set defined by this matching expression could be identical to the
set defined by the HTTP Proxy Policy, or it could be a subset.
User name
Specify the user name.
Password
Specify the associated password.
Confirm Password
Specify the associated password again.

Click Save to complete basic authentication and return to the User Agent
configuration (Basic-Auth Policy) screen, which now lists the newly created user
name-password pair.

Optionally, click Save Config to save the object to the startup configuration.

344 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
SOAP Action Policy
Certain User Agent requests require that the contents of the SOAPAction HTTP
request header field be supplied. Click the Soap-Action Policy tab to display the
User Agent configuration (SOAP-Action Policy) screen, which lists all SOAP
actions.

Click Add to display the SOAP Action Property window.

Provide the following inputs:

URL Matching Expression
Define the target URL set that is associated with this policy. If the target
URL matches this expression, the corresponding header will be inserted in
the request to the resource.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Soap Action
Specify the SOAP action (a URI that identifies the intent of the SOAP
HTTP request). In the following example, the Soap Action is:
GetCatalogList
POST /webServices/soap/endpoint HTTP/1.1
Host: www.somedomain.info
Content-Type: text/xml; charset="utf-8"
Content-Length: <length of HTTP request>
SOAPAction: GetCatalogList

Click Save to complete specification of the header field contents and return to the
User Agent configuration (Soap-Action Policy) screen, which now lists the newly
created SOAP action.

Optionally, click Save Config to save the object to the startup configuration.

Public Key Authentication Policy

A User Agent can use public key authentication in its communications with remote
resources. This feature is useful when the agent uses the SCP or SFTP protocol for
communication. Click the PubKey-Auth Policy tab to set the configuration values
for this feature.

Click any existing policy to edit the policy, or click Add to create a new policy. The
Public Key Property window is displayed.

Provide the following inputs:

URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.

Appendix A. Referenced objects 345

 Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Examples include the following:
v https://server.domain.com/transactions/*
v sftp://user@server.com/images/*
v scp://user[a-c]@10.10.[0-4].23/inbound/*
Private Key
Select the desired private key. If the Crypto Key object needed is not
presented in the list, click the + button to create the object. The Private Key
file must be uploaded to the local appliance to create the Crypto Key
object.
The remote server must also possess the appropriate certificate. This
certificate must reside in $HOME/.ssh/authorized_keys on the remote
server.

Click Save to add this policy to the list.

Allow Compression Policy

A User Agent can compress the payload of its communications with remote
resources. This feature is useful when the payload is large.

Click the Allow-Compression Policy tab to set the configuration values needed for
this feature.

Click any existing policy to edit the policy, or click Add to create a new policy. The
Allow Compression Property window is displayed.

Provide the following inputs:

URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.

346 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Allow Compression
Use the toggle to enable (on) or disable (off) compression.

Click Save to add this policy to the list.

Restrict to HTTP 1.0 Policy

The User Agent can restrict HTTP communications to the HTTP 1.0 specification, if
so desired. Use this Policy to control this behavior. Click the Restrict to HTTP 1.0
Policy tab.

Click any existing policy to edit the policy, or click Add to create a new policy. The
Restrict to HTTP 1.0 Policy Property window is displayed.

Provide the following inputs:

URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Restrict to HTTP/1.0
Use the toggle to enable (on) or disable (off) HTTP protocol restriction.

Click Save to add this policy to the list.

Inject Header Policy

The User Agent can inject an HTTP Header and corresponding value into the
communication with the remote server. Click the Inject Header Policy tab.

Note: A Multi-Protocol Gateway can also inject HTTP headers. The User Agent
operates on the communication after the gateway.

Click any existing policy to edit the policy, or click Add to create a new policy. The
Inject Header Property window is displayed.

Provide the following inputs:

URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.

Appendix A. Referenced objects 347

 [] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Header Name
Specify the name of the HTTP Header to inject.
Header Value
Specify the corresponding value string for the injected header.

Click Save to add this policy to the list.

Chunked Uploads Policy

The User Agent can use HTTP 1.1 Chunked content encoding. This is useful for
streaming large documents. When the appliance employs the HTTP 1.1 protocol,
the body of the document can be delimited by either Content-Length or chunked
encoding. While all servers will understand how to interpret Content-Length,
many applications will fail to understand Chunked encoding. For this reason,
Content-Length is the standard method. However doing so interferes with the
ability of the appliance to fully stream. To stream full documents towards the
backend server, this property should be enabled. However, the backend server
must be RFC 2616 compatible, because this feature cannot be renegotiated at run
time, unlike all other HTTP 1.1 features that can be negotiated down at runtime if
necessary.

Click the Chunked Uploads Policy tab.

Note: A Multi-Protocol Gateway can also control Chunked Uploads. The User
Agent operates on the communication after the Multi-Protocol Gateway.

Click any existing policy to edit the policy, or click Add to create a new policy. The
Chunked Uploads Property window is displayed.

Provide the following inputs:

URL Matching Expression
Specify a URL Match expression in the URL Matching Expression field.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Enable/Disable HTTP 1.1 Chunked Request Bodies
Use the toggle to enable (on) or disable (off) chunked encoding.

348 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Click Save to add this policy to the list.

FTP Client Policies

The User Agent can associate a set of FTP URLs with a specified policy that
controls the default values of many FTP client options for outgoing FTP
connections. These controls can be further overridden by query parameters in the
URL that is used to initiate the file transfer.

Click the FTP Client Policies tab to display the User Agent configuration (FTP
Client Policies) screen.

Click any existing policy to edit or click Add to create a new policy to display the
FTP Client Policies Property window.

Provide the following inputs:

URL Matching Expression
Specify a shell-style expression that defines a URL set.
Match patterns can contain the following wildcard syntax:
* Indicates a string that matches 0 or more occurrences of any
character.
? Indicates a single character that matches one occurrence of any
single character.
[] Indicates a delimited range of alphabetic or numeric characters. For
example, [1-5] would match 1, 2, 3, 4, or 5, and [x-y] would
match x or y.

You can use any PCRE-compliant expression. For more information, refer
to http://www.pcre.org.
Passive Mode
Select how the use of FTP passive mode to control the direction in which
FTP data connections are made.
Passive Mode Not Requested
Do not use the FTP PASV command to allow the client to open
FTP data connections. The FTP server will open all data
connections to the FTP client. Often, this mode is incompatible
with firewalls.
Request Passive Mode
Use the FTP PASV command to request that the FTP client be
allowed to open all data connections to the FTP server, but do not
fail if the server does not support PASV.
Require Passive Mode
(Default) Use the FTP PASV command to request that the FTP
client be allowed to open all data connections to the FTP server,
and fail if the server does not support PASV.
Encrypt Command Connection
Select how to control the use of TLS to secure the FTP command
connection.

Appendix A. Referenced objects 349

 No Authentication Requested
(Default) Do not use the FTP AUTH command to allow encrypt
the command connection. The user name and password will be
passed in the clear.
Request TLS Authentication
Use the FTP AUTH TLS command to encrypt the command
connection, if available.
Require TLS Authentication
Use the FTP AUTH TLS command to encrypt the command
connection. If not available, fail.
Stop Command Encryption After Authentication
Select how to control the cessation of FTP command channel encryption
after user authentication. Encryption must be stopped for compatibility
with NAT (Network Address Translation) and other firewall applications.
Although this behavior might be a security risk, this behavior is the only
option when a NAT is in use.
Leave Encrypted
(Default) Leave the FTP command connection encrypted after
(optional) authentication of the USER and PASS commands. The
command connection remains secure. This setting is not compatible
with NAT and many firewalls.
Request Stop Encryption
Use the FTP CCC command to request the end of encryption of the
command channel using TLS, if supported by the server.
Require Stop Encryption
Use the FTP CCC command to request the end of encryption of the
command channel using TLS. If not supported, fail. Some servers
do not support CCC. This setting is required for compatibility with
NAT and many firewall.
Encrypt File Transfers
Select how to control the encryption of file transfers. All setting are
compatible with NAT.
Unencrypted Data
(Default) Do not encrypt FTP data connections, even if the
command channel is encrypted. Use the FTP PROT C command if
command channel is encrypted or has been encrypted.
Request Data Encryption
Request encryption of FTP data connections using the FTP PROT P
command. This setting requires that the command change is
encrypted or has been encrypted. Do not fail if the server does not
support data encryption.
Require Data Encryption
Request encryption of FTP data connections using the FTP PROT P
command. This setting requires that the command change is
encrypted or has been encrypted. Fail if the server does not
support data encryption.
Data Type
Select the default data type of file transfers. In most cases, the default
value of binary is appropriate.

350 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 ASCII Data
Transfer files in ASCII mode. This setting allows for the
standardizations of end-of-line conventions between different
operating systems. This setting increases the overhead at both ends
of the transfer. This setting uses the FTP TYPE A command.
Image (Binary) Data
(Default) Transfer files in image mode, which transfers data as
binary 8-bit bytes. This setting is more efficient and has less
overhead at both ends of the transfer. Some XML files, such as
ones that are signed, must be transferred in image mode. This
setting uses the FTP TYPE I command.
Write Unique Filename if Trailing Slash
Select whether the FTP server creates unique file names. Some FTP servers
provide the STOU command. The STOU command causes the FTP server
to choose a unique file name to write to in the current directory, instead of
having the FTP client choose a unique name. When enabled and the URL
end in a slash, the STOU command is used instead of the STOR
command. Before enabling, ensure that the FTP server support the STOU
command.
Request Unique File Name When Trailing Slash
(Default) If the supplied file name ends in a slash (before the
question mark (?) character that initiates the query parameter, or
the semicolon (;) character that begins the suffix), use the STOU
command to request that the server generates a unique file name
in the target directory. This behavior allows multiple systems to
write files to the same directory without any risk of duplicate file
names that overwrite each other. The transfer fails if the FTP server
does not support the STOU command.
Use Supplied File name
Always uses the supplied file name to generate the target file name
that is requested on the server. This setting uses the STOR
command to initial the transfer. If the URL ends in a slash, the
transfer generally fails, because there is only a directory
specification (no file name).
Quoted Commands
Select an FTP Quoted Command to send to the FTP server before each
STOU, STOR, or RETR command.
Size Check
Select whether to perform a size check after a transfer.
Disabled
Do not perform this check.
Optional
(Default) If the FTP SIZE command is available, use it to check the
size of the file after transfer. The SIZE command compares the
returned value to the number of bytes that were transferred. If not
equal, the transfer is marked as failing.

Click Save to add this policy to the list.

Appendix A. Referenced objects 351

XML Manager
The firmware creates a default XML Manager object in the default domain and in
each application. The default instance in each domain can be edited like any other
instance of an XML Manager object. The default instance in each domain operates
independently of each other.

An XML Manager object obtains and manages XML documents, style sheets, and
other document resources on behalf of one or more services. An XML Manager
also provides the following capabilities:
v Basic network configuration, such as load balancing and accessing remote
servers.
v Set manager-associated limits on the parsing of XML documents. By default, the
appliance imposes limits on various characteristics of XML documents. These
limitations provide for increased security and stability to protect against DoS
attacks or runaway data. Parser limits defined by the XML Manager object that
is associated with a service can be overridden by service-specific settings.
v Enable the caching of documents that this XML Manager object obtains. XML
Manager objects obtain documents via HTTP. The number of documents in the
cache depends on the availability of allocated memory.
v Define extension function mapping. An XML Manager object can automatically
map custom style sheet extension functions to DataPower extension functions.
This ability removes the need to alter or rewrite a style sheet for use by the
appliance. The most common example is the node-set() extension function. If a
service uses style sheets that reference the Microsoft node-set, Oracle node-set,
or Salon nodeset XSLT extension functions, you must map these extensions to
their DataPower equivalent. It is possible to map any extension function to a
DataPower extension function.
v Define the caching policy for documents. This policy allows an administrator to
determine how to cache documents. The policy defines the time-to-live, the
priority, and the type.
v Enable schema validation by defining schema-validation rules. These rules apply
to all documents that match predefined criteria. Alternatively, the appliance can
validate documents with a validate action in a processing rule. Do not mix and
match schema validation strategies. Policy-based schema validation is the
preferred strategy.
v Schedule processing rules. Certain applications might require the running of a
scheduled processing rule. Integration with a CA Unicenter Manager is
facilitated by a regularly scheduled processing rule that obtains relationship data
from the Unicenter Manager.

Configure XML Manager objects

The specification of the name completes the required configuration. The remaining
properties modify default values or implement enhanced behavior. For information
about the configuration properties, refer to the online help.

To configure an XML Manager:

1. Select Objects XML Processing XML Manager to display the catalog.
2. Click Add to display the configuration screen.
3. On the Main tab, define the basic configuration.
4. On the XML Parser Limits tab, define the limits to impose when parsing XML
documents.

352 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 5. On the Document Cache tab, define the caching of documents that are
obtained via HTTP.
6. On the Extension Functions tab, define the maps for custom extension
functions to DataPower extension functions.
7. On the Document Cache Policy tab, define the documents to store in the
document cache.
8. On the Schema Validation Rules tab, define rules to enforce validation of all
documents that match the defined criteria.
9. On the Scheduled Processing Policy Rule tab, define scheduled processing
rules.
10. Click Apply to save the object to the running configuration.
11. Optionally, click Save Config to save the object to the startup configuration.

Flushing the document cache

The appliances maintains a cache of documents. To flush the cache, click Flush
Document Cache.

This function is available from the following screens:

v The configuration screen for an XML Manager object (Objects XML Processing
XML Manager)
v The status screen for the document cache (Status XML Processing
Document Cache)

Flushing the stylesheet cache

The appliances maintains a cache of style sheets. To flush the cache, click Flush
Stylesheet Cache.

Note: After a change to a Compile Options Policy object, flush the stylesheet
cache. Otherwise, the XML Manger object continues to use the previous
compiled style sheets until they are recompiled.

This function is available from the following screens:

v The configuration screen for an XML Manager object (Objects XML Processing
XML Manager)
v The status screen for the stylesheet cache (Status XML Processing Stylesheet
Cache)

z/OS NSS Client

The z/OS NSS client enables integration with RACF on the z/OS
Communications Server. The z/OS NSS Client object specifies the authentication
information required to allow the DataPower appliance to function as an NSS
client. The z/OS NSS Client object specifies the following properties:
v Remote Address
v Remote Port
v SSL Proxy Profile
v Client ID
v System Name
v User Name
v Password

Appendix A. Referenced objects 353

 Based on these properties and the request type, the following actions occur:
v DataPower requests a secure connection to the z/OS Communications Server
v RACF performs authentication of users
v RACF performs authorization to resources
v RACF logs authorized and unauthorized attempts to access RACF-protected
resources
v z/OS Communications Server NSS protocol provides return codes and reason
codes for connectivity requests

To support this functionality, the NSS server must be configured to support the
NSS client. See the following z/OS Communications Server documentation for
these configuration steps:
v Enable the XMLAppliance discipline support. For further information, refer to the
section on network security services server in the z/OS Communications Server: IP
Configuration Reference.
v Authorize the client userid to SAF profiles representing security services and
resources. For further information, refer to the section on preparing to provide
network security services in the z/OS Communications Server: IP Configuration
Guide.
v Configure SSL for the TCP connection between the client and server. For further
information, refer to the section on configuring the NSS server in the z/OS
Communications Server: IP Configuration Guide.

Only one physical connection per Remote Address, Remote Port, and Client ID is
allowed. Additional z/OS NSS Client objects might be configured, but if more than
one client with the same tuple try to connect, the connection will fail. If the
connection is not established or the provided parameters are not valid, the object
operational state is down and shows one of the following event codes:
v Invalid registration parameters
v TCP connection retry (interval is 1 minute)
v TCP connection in progress
v Communication failed
v Cannot connect to host
For additional information on logged NSS protocol return codes and reason codes,
refer to http://www.ibm.com/support/docview.wss?rs=852&uid=swg21329236 for
z/OS Communications Server: IP Diagnosis Guide updates.

Contact NSS for SAF Authentication is selected as the Authenticate method in the
AAA policy configuration and Contact NSS for SAF Authorization is selected for
the Authorization method.

Creating the z/OS NSS Client

To configure a z/OS NSS client, use the following procedure:
1. Select OBJECTS z/OS Configurations z/OS NSS Client to display the
catalog.
2. To display the configuration screen, click Add.
3. Specify the name of the object in the Name field.
4. Retain the default setting for the Admin State toggle. To place the object in an
inactive administrative state, click disabled.
5. Specify a descriptive object-specific summary in the Comment field.

354 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 6. Specify the IP address or hostname of the NSS server in the Remote Address
field.
7. Specify the port on which the NSS server listens in the Remote Port field.
8. Select an SSL Proxy Profile in the SSL Proxy field to provide a secure
connection to the remote authentication server.
9. Specify the client ID to be used for registration with the NSS server in the
Client ID field.
10. Specify the system name to identify the NSS client to the NSS server in the
System Name field.
11. Specify the user name to use to authenticate with the SAF in the User Name
field.
12. Specify the password to use to authenticate with the SAF in the Password
field.
13. Reenter the password in the Confirm Password field.
14. Click Apply to save the object to the running configuration.
15. Optionally, click Save Config to save the object to the startup configuration.

Appendix A. Referenced objects 355

356 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Appendix B. Cryptographic support in actions
This section provides information about cryptographic support in processing
actions.

ID references
The DataPower appliance, when acting as a message receiver, can process any
reference that uses one of the following attribute formats:
v @wsu:Id
v @xml:Id
v local @Id

References in these attribute formats can be used by processing policies in the

following situations:
v Implementing an AAA policy
v Performing message-level encryption or field-level encryption
v Performing signature operations with one of the following algorithms:
wssec
hmac
kerberos-hmac

Note: Receiver-side support requires no additional configuration.

When encrypting or signing messages, the DataPower service acts as a message

sender. Message-sender operations are supported by the WS-Sec ID Reference
Type property. For this property, select one of the following values as the ID
attribute type:
v wsu:Id
v xml:Id

The default is wsu:Id. This ID attribute type was the only type that was allowed in
early versions of the specification.

This property is available on the Advanced tab of the encrypt and sign actions.

EncryptedData tokens
The <xenc:EncryptedData> element can be included as a child of a
<wsse:Security> header. The <xenc:EncryptedData> element contains an encrypted
UsernameToken or BinarySecurityToken.

For the encrypt action, the DataPower appliance automatically includes the
appropriate token during field-level WS-Security encryption. For the decrypt
action, the appliance automatically decrypts the token during field-level or
message-level decryption.

Copyright IBM Corp. 2002, 2009 357

Security token references
The <wsse:SecurityTokenReference> element provides a uniform reference
mechanism that is guaranteed to work with all of the supported formats. This
mechanism is known as the Security Token Reference (STR) Dereference Transform.
This mechanism is used to ensure that the output of the
<wsse:SecurityTokenReference> element is not the literal token reference
(contained with the element) but the actual tokens themselves.

Token reference mechanisms are available for the following token types. For
normative information, refer to the cited document:
X.509 certificates
Refer to Web Services Security: X.509 Certificate Token Profile 1.1, the OASIS
Standard incorporating approved errata dated November 1, 2006
Kerberos AP-REQ tokens, version 5
Refer to Web Services Security: Kerberos Token Profile 1.1, the OASIS Standard
incorporating approved errata dated November 1, 2006
SAML assertions
Refer to Web Services Security: SAML Token Profile 1.1, the OASIS Standard
incorporating approved errata dated November 1, 2006

X.509 certificates
The DataPower appliance supports STR Dereference Transform with X.509 tokens
as follows:
v Within a verify action
v During the Identity Extraction phase of an AAA policy when the method is
Subject DN from Certificate in the Messages signature
v During the Authentication phase of an AAA policy when the method is Validate
the Signer Certificate for a Digitally Signed.

For this transform, the token type can be as follows:

Binary Security Token
A <wsse:SecurityTokenReference> element contains a
<wsse:Reference/@URI> element that references a local
<wsse:BinarySecurityToken> element or a remote data source that contains
the token data.
PKCS#7
A <wsse:SecurityTokenReference> element contains a
<wsse:Reference/@URI> element that references a local
<wsse:BinarySecurityToken> element or a remote data source that contains
the token data.
PKIPath Binary Security Token
A <wsse:SecurityTokenReference> element contains a
<wsse:Reference/@URI> element that references a local
<wsse:BinarySecurityToken> element or a remote data source that contains
the token data.
Subject Key Identifier
A <wsse:SecurityTokenReference> element contains a
<wsse:KeyIdentifier> element that identifies the token with the value of
the X.509 version 3 Subject Key Identifier extension for the certificate. A

358 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Subject Key Identifier can be used only to reference a X.509 version 3
certificate. Versions earlier than version 3 are not supported.
Thumbprint SHA-1A
A <wsse:SecurityTokenReference> element contains a
<wsse:KeyIdentifier> element that identifies the token with the value of
the X.509 version 3 Subject Key Identifier extension for the certificate. A
Subject Key Identifier can be used only to reference a X.509 version 3
certificate. Versions earlier than version 3 are not supported.
X.509 Thumbprint SHA-1A
A <wsse:SecurityTokenReference> element contains a
<wsse:KeyIdentifier> element that identifies the token with the value of
the X.509 version 3 Subject Key Identifier extension for the certificate. A
Subject Key Identifier can be used only to reference a X.509 version 3
certificate. Versions earlier than version 3 are not supported.

Kerberos AP-REQ tokens

The DataPower appliance supports STR Dereference Transform with Kerberos
tokens within a verify action. For this transform, the token type can be as follows:
BinarySecurityToken
A <wsse:SecurityTokenReference> element contains a
<wsse:Reference/@URI> element that references a local
<wsse:BinarySecurityToken> element or a remote data source that contains
the token data.
Subject Key Identifier
A <wsse:SecurityTokenReference> element contains a
<wsse:KeyIdentifier> element that identifies the token with the value of
the X.509 version 3 Subject Key Identifier extension for the certificate. A
Subject Key Identifier can be used only to reference a X.509 version 3
certificate. Versions earlier than version 3 are not supported.

SAML assertions
The DataPower appliance supports STR Dereference Transform with SAML
assertions as follows:
v Within a verify action
v During the Identity Extraction phase of an AAA policy when the method is
Subject DN from Certificate in the Messages signature
v During the Authentication phase of an AAA policy when the method is Validate
the Signer Certificate for a Digitally Signed.

For this transform, the token type can be as follows:

SAML version 1.1 or version 2.0 local token
The local token is either the holder of the key or the sender of vouches.
SAML version 1.1 or version 2.0 remote token
The remote token is either the holder of the key or the sender of vouches.

Signature confirmation
The <wsse11:SignatureConfirmation> element is available when using WS-Security
1.1. This element is not available when using WS-Security 1.0.

Appendix B. Cryptographic support in actions 359

 The DataPower appliance does not automatically save the signature information
for sign and verify actions. Saving the signature information requires a
modification to the configuration for these actions. The change in configuration
depends on whether the action is generating or is verifying a signature
confirmation.

Generating a signature confirmation

On the frontend, you might need to generate a signature confirmation with the
sign or verify action. The sign action applies to the request. The verify action
applies to the response.
v For the request, use the verify action to save the verified signature. A sign
action can process the response message to insert the SignatureConfirmation
element in the reply to the client. Use this action if the client sends a signed
request and expects to receive signature confirmation that ensures that the
signed request from the client is the original, verified signature.
v For the response, use the sign action to set include the SignatureConfirmation
element.

Verifying a signature confirmation

On the backend, you might need to verify a signature confirmation with the sign
or verify action. The sign action applies to the response. The verify action applies
to the request.
v For the request, use the sign action to save the generated signature confirmation.
The verifier expects the response to include a signature confirmation. A verify
action can process the response to verify the returned signature confirmation.
v For the response, use the verify action to require a signature confirmation.

360 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Appendix C. Working with variables
Variables can be used in most context, except PIPE. To use a variable, you must
create it with the Set Variable action. This action creates a variable in a specified
context and assigns it a value.

There are the following distinct variable types, each expressed in the var://URL
format:
var://local/variable
A local context variable to addresses a variable called variable in the default
(current) context. The following example transforms the document in the
tmp1 context with a style sheet that is referenced by the stylesheet-1
variable (also in the tmp1 context) and stores the transformed document in
the tmp2 context:
xform tmp1 var://local/stylesheet-1 tmp2

The local context does not persist beyond the scope of the multistep
transaction. A multistep transaction can include both a request component
and a response component. The local context cannot be accessed by any
object outside of the scope of the multistep transaction. In other words, the
service cannot read and use the variable.
A local context variables can be user-defined or based on an extension
variable. For a complete list of the available extension variables, refer to
Extension variables on page 370.
var://context/context/variable
Addresses a variable called variable in a context called context. The
following example transforms the document in the tmp1 context with a
style sheet that is referenced by the stylesheet-1 variable (in the apple
context) and stores the transformed document in the tmp2 context:
xform tmp1 var://context/apple/stylesheet-1 tmp2

A named context does not persist beyond the scope of the multistep
transaction. A multistep transaction can include both a request component
and a response component. The local context cannot be accessed by any
object outside of the scope of the multistep transaction. In other words, the
service cannot read and use the variable.

Note: Creating variables in a named context is the recommended

approach. This form decouples the variable from the input and
output contexts and allows the variable to be accessed from any step
in a multistep scope.
A named context variables can be user-defined or based on an extension
variable. For a complete list of the available extension variables, refer to
Extension variables on page 370.
var://service/variable
Address a variable that is made available to a service (such as HTTP or
XSL Co-Processor) that is attached to a multistep session. The majority of
service variables are read-only and cannot be set.

Copyright IBM Corp. 2002, 2009 361

 For a complete list of the available service variables, refer to Service
variables.
var://system/variable
Addresses a global variable that is available in all contexts. System
variables persist beyond the multistep scope and can be read by other
objects in the system. If the content of a variable needs to be read or set
outside the scope of the multistep process, use a system variable.
For a complete list of the available global system variables, refer to
System variables on page 372.

Note: Refer to List of available variables on page 373 for the list of variables that
you can define for document processing.

Service variables
Service variables enable the setting and retrieval of pieces of state that usually
reflect the state of the current transaction.

The available service variables are separated alphabetically into the following
categories:
v Service variables that are available to all DataPower services
v Service variables that are available to only Multi-Protocol Gateway and Web
Service Proxy services
v Configuration services
v Load balancer service
v Legacy MQ-specific services

General service variables

This section contains information about general variables in alphabetic order by
permission category. General variables are available to all services. Table 3 lists the
names and permission for these variables.
Table 3. Names and permissions for variables that are available to all DataPower services
Variable name Permission
var://service/soap-fault-response Read-write

Read-write variables
var://service/soap-fault-response
Set when the response input rule is treated as a SOAP fault.

Multi-Protocol Gateway and Web Service Proxy service

variables
This section contains information about general service variables for Multi-Protocol
Gateway and Web Service Proxy services in alphabetic order by permission
category. Table 4 lists the names and permission for these variables.
Table 4. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services
Variable name Permission
var://service/mpgw/backend-timeout Read-write

362 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Table 4. Names and permissions for general service variables that are available to only
Multi-Protocol Gateway and Web Service Proxy services (continued)
Variable name Permission
var://service/mpgw/skip-backside Write-only
var://service/reply-to-q Write-only
var://service/reply-to-qm Write-only

Write-only variables
var://service/mpgw/skip-backside
For Multi-Protocol Gateway and Web Service Proxy services only, indicates
that the service skips backside processing.
Set this variable to 1 to prevent backside processing. Use this variable as a
custom redirect implementation, not as the point of the service. Because
the service is not aware of the processing flow, unusual messages might be
written to the event log.

Read-write variables
var://service/mpgw/backend-timeout
For Multi-Protocol Gateway and Web Service Proxy services only, gets or
sets the backend timeout, in seconds. Setting this variable overrides the
default timeout. Use an integer in the range of 1 through 86400.
var://service/reply-to-q
Read and write the value in the ReplyToQ (Reply to Queue) MQ header.
When read, shows the input message value. When write, changes the
dynamic routing.
var://service/reply-to-qm
Read and write the value in the ReplyToQMgr (Reply to Queue Manager)
MQ header. When read, shows the input message value. When write,
changes the dynamic routing.

Configuration services service variables

This section contains information about variables for configuration services in
alphabetic order by permission category. Table 5 lists the names and permission for
these variables.
Table 5. Names and permissions for variables that are available for configuration services
Variable name Permission
var://service/config-param Write-only
var://service/max-call-depth Read-write

Write-only variables
var://service/config-param/parameterName value
Sets the specified stylesheet parameter to the specified value.

Read-write variables
var://service/max-call-depth
Gets or sets the maximum call depth for each transaction. This variable
controls how many levels of called rules can be layered before an error is
thrown. The default is 128.

Appendix C. Working with variables 363

 Load balancer service variables
This section contains information about load balancer variables in alphabetic order
by permission category. Table 6 lists the names and permission for these variables.
Table 6. Names and permissions for variables that are available for load balancers
Variable name Permission
var://service/lbhealth/ Write-only

Write-only variables
var://service/lbhealth/
Sets the member and state of a load balancer group.

Legacy MQ-specific service variables

This section contains information about MQ-specific variables in alphabetic order
by permission category. MQ-specific variables are available to only the legacy MQ
Host and MQ Proxy services. Table 7 lists the names and permission for these
variables.
Table 7. Names and permissions for service variables that are available to MQ Host and
MQ Proxy services
Variable name Permission
var://service/correlation-identifier Read-write
var://service/expiry Read-write
var://service/format Read-write
var://service/message-identifier Read-write
var://service/message-type Read-write
var://service/mq-ccsi Write-only
var://service/mqmd-reply-to-q Write-only
var://service/mqmd-reply-to-qm Write-only
var://service/persistence Read-write
var://service/priority Read-write
var://service/reply-to-q Read-write
var://service/reply-to-qm Read-write
var://service/report Read-write

Write-only variables
var://service/mq-ccsi
Sets the MQ message descriptor character set for an MQ Host or MQ
Proxy service.
var://service/mqmd-reply-to-q
Sets the output MQ message descriptor.ReplyToQ value for an MQ Host
or MQ Proxy service.
var://service/mqmd-reply-to-qm
Sets the output MQ message descriptor.ReplyToQMgr value for an MQ
Host or MQ Proxy service.

364 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Read-write variables
var://service/correlation-identifier
Read and write the MQ value in the Correlation Identifier header for
MQ Host and MQ Proxy services.
var://service/expiry
Read and write the MQ value in the Expiry header for MQ Host and MQ
Proxy services.
var://service/format
Read and write the MQ value in the Format header for MQ Host and MQ
Proxy services.
var://service/message-identifier
Read and write the MQ value in the Message Identifier header for MQ
Host and MQ Proxy services.
var://service/message-type
Read and write the MQ value in the Message Type header for MQ Host
and MQ Proxy services.
var://service/persistence
Read and write the MQ value in the Persistence for MQ Host and MQ
Proxy services.
var://service/priority
Read and write the MQ value in the Priority header for MQ Host and
MQ Proxy services.
var://service/reply-to-q
Read and write the MQ value in the ReplyToQ (Reply to Queue) header for
MQ Host and MQ Proxy services. When read, shows the input message
value. When write, changes the dynamic routing.
var://service/reply-to-qm
Read and write the MQ value in the ReplyToQMgr (Reply to Queue
Manager) header for MQ Host and MQ Proxy services. When read, shows
the input message value. When write, changes the dynamic routing.
var://service/report
Read and write the MQ value in the Report header for MQ Host and MQ
Proxy services.

Multistep variables
This section contains information about system variables in alphabetic order by
permission category. Multistep variables usually impact the behavior of specific
actions in the context of a processing rule. Table 8 lists the names and permission
for these variables.
Table 8. Names and permissions for variables that are available to all services
Variable name Permission
var://service/log/soapversion Read-write

Read-write variables
var://service/log/soapversion
Gets or sets the version of SOAP for use by a SOAP log targets. Use a
setvar action before a log action to change the version of SOAP to use
when logging this message.

Appendix C. Working with variables 365

 Supports the following values:
soap11 Uses SOAP 1.1.
soap12 (Default) Uses SOAP 1.2.

Transaction variables
The available transaction variables are separated alphabetically into the following
categories:
v Asynchronous transactions
v Error handling
v Headers
v Persistent connections
v Routing
v URL
v Web Services Management (WSM)

Asynchronous transaction variables

This section contains information about asynchronous transaction variables in
alphabetic order by permission category. Table 9 lists the names and permission for
these variables.
Table 9. Names and permissions for variables that are available for asynchronous
transactions
Variable name Permission
var://service/soap-oneway-mep Read-write
var://service/transaction-key Write-only
var://service/transaction-name Write-only
var://service/transaction-timeout Write-only

Write-only variables
var://service/transaction-key
Sets the token for asynchronous transactions.
var://service/transaction-name
Sets the name for asynchronous transactions.
var://service/transaction-timeout
Sets the timeout for asynchronous transactions.

Read-write variables
var://service/soap-oneway-mep
Gets or sets the SOAP one-way Message Exchange Pattern (MEP)
notification.
v When true, notifies the service layer that this transaction is performing a
one-way MEP operation. This setting enables the service layer to
optimize resource usage while preventing Web Services Addressing
(WSA) from waiting for and faulting on a response that will never
arrive.
v When false, no notification is sent. When using WSA and one-way
MEPs, the service layer will time out waiting for a response.
When a DataPower service is configured for WSA-to-WSA and it receives a
WSA annotated message without the wsa:MessageId, the DataPower service

366 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 assumes that this is a one-way MEP and notifies the service layer by
setting this value of this variable to true.
This variable is not needed for Web Service Proxy services, as one-way
MEPs are identified by reviewing the specifics of the port operation.

Error handling transaction variables

This section contains information about error handling variables in alphabetic
order by permission category. Table 10 lists the names and permission for these
variables.
Table 10. Names and permissions for variables that are available for error handling
Variable name Permission
var://service/error-code Read-write
var://service/error-ignore Read-write
var://service/error-message Read-write
var://service/error-protocol-reason-phrase Write-only
var://service/error-protocol-response Write-only
var://service/error-subcode Read-write
var://service/strict-error-mode Read-write

Write-only variables
var://service/error-protocol-reason-phrase
Sets the protocol-specific reason phrase for an error. This variable
overwrites the reason phrase in the response to provide a short description
that an be understood by people.
var://service/error-protocol-response
Sets the protocol-specific response for an error. This variable overwrites the
protocol-specific response code in an error condition.

Read-write variables
var://service/error-code
Gets or sets the assigned error code from the Result Code table.
var://service/error-ignore
Gets or sets a flag that controls how the Front Side Handler processes error
condition. If the value is set and greater than zero, it does not run any
error handling action and produces a regular response. The content of the
message is produced by an error rule.
The default value is 0.
Currently, on the TIBCO EMS and WebSphere JMS Front Side Handler use
this variable. If any error happens and the variable is set, the Front Side
Handler acknowledges a request message and puts the response message
in the PUT queue. This response message will be a SOAP-fault or any
output that error rule generates.
var://service/error-message
Gets or sets the generic error message that is sent to the client. This
variable contains the error condition that stopped multistep processing.
Setting this variable overwrites the error response that is sent to the client
in an error condition. To set the error message that is written to the log
file, use the var://service/formatted-error-message variable.

Appendix C. Working with variables 367

 var://service/error-subcode
Gets or sets the error sub-code. This variable can help to disambiguate the
reason for which the error rule was invoked. Often, the sub-code is the
same as the value of the var://service/error-code variable. Sometimes,
the sub-code is a more specific result code.
var://service/strict-error-mode
Gets or sets the strict error mode. This variable controls the error mode for
multistep processing.
v If the value is set, an invocation of the dp:reject extension element
stops multistep processing.
v If the value is not set, an invocation of the dp:reject extension element
logs a message but does not stop multistep processing.

Headers transaction variables

This section contains information about header variables in alphabetic order by
permission category. Table 11 lists the names and permission for these variables.
Table 11. Names and permissions for variables that are available for headers
Variable name Permission
var://service/append-request-header/ Write-only
var://service/append-response-header/ Write-only
var://service/set-request-header/ Write-only
var://service/set-response-header/ Write-only

Write-only variables
var://service/append-request-header/
Appends to the protocol request header.
var://service/append-response-header/
Appends to the protocol response header.
var://service/set-request-header/
Sets the protocol request header. This variable directly correlates to the
dp:set-request-header() extension function. Setting the
var://service/set-request-header/FOO variable to the value BAR would
set the request header FOO to BAR.
var://service/set-response-header/
Sets the protocol response header. This variable directly correlates to the
dp:set-response-header() extension function. Setting the
var://service/set-response-header/FOO variable to the value BAR would
set the response header FOO to BAR.

Persistent connection transaction variables

This section contains information about persistent connection variables in
alphabetic order by permission category. Table 12 lists the names and permission
for these variables.
Table 12. Names and permissions for variables that are available for persistent connections
Variable name Permission
var://service/connection/note Read-write

368 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
 Read-write variables
var://service/connection/note
Gets or sets the annotation for the current connection. This variable allows
the user to annotate the current protocol session. The value could be an
identifier that could be used to maintain the state based on an existing
protocol session.

Routing transaction variables

This section contains information about routing variables in alphabetic order by
permission category. Table 13 lists the names and permission for these variables.
Table 13. Names and permissions for variables that are available for routing
Variable name Permission
var://service/routing-url Write-only
var://service/routing-url-sslprofile Write-only

Write-only variables
var://service/routing-url
For XML Firewall, Multi-Protocol Gateway, and Web Service Proxy
services, sets the routing URL. This variable can be set one time only and
takes the following format:
<dp:set-variable name="var://service/routing-url"
value="'protocol://target/URI'" />
v For XML Firewall services:
The protocol must be HTTP or HTTPS. If any other protocol, the
service generates an error.
The URI is stripped. To specify the URI, use the var://service/URI
variable, as shown in the following excerpt:
<dp:set-variable name="'var://service/routing-url'"
value="'http://10.10.36.11:2064'" />
<dp:set-variable name="'var://service/URI'"
value="'/service'" />
v For Multi-Protocol Gateway and Web Service Proxy services:
The protocol can be any valid backend protocol.
The URI is absolute and cannot be controlled with the Propagate URI
toggle (WebGUI) or propagate-uri command.
The var://service/routing-url variable is an addition to the
dp:set-target and dp:xset-target extension elements. These extension
elements do not allow the specification of a protocol. These extension
element, if provided, overrides the value of the target server that is
specified in this variable.
var://service/routing-url-sslprofile
Sets the SSL proxy profile for the routing URL (dynamic route). Use this
variable when the ssl property for the DataPower service is not sufficient
for the route to be selected. Use this variable before using the
var://service/routing-url variable.

URL-based transaction variables

This section contains information about URL-based transaction variables in
alphabetic order by permission category. Table 14 on page 370 lists the names and
permission for these variables.
Appendix C. Working with variables 369
 Table 14. Names and permissions for variables that are available for URL-based
transactions
Variable name Permission
var://service/URI Read-write

Read-write variables
var://service/URI
Gets or sets the request URI of the transaction.

Web Services Management transaction variables

This section contains information about Web Services Management (WSM)
variables in alphabetic order by permission category. Table 15 lists the names and
permission for these variables.
Table 15. Names and permissions for variables that are available to WSM
Variable name Permission
var://service/wsa/timeout Read-write
var://service/wsa/genpattern Read-write
var://service/wsm/wsdl-error Write-only
var://service/wsm/wsdl-warning Write-only

Write-only variables
var://service/wsm/wsdl-error
Sets the WSDL error.
var://service/wsm/wsdl-warning
Sets the WSDL warning.

Read-write variables
var://service/wsa/timeout
Gets or sets the timeout value for the WS-Addressing asynchronous reply.
var://service/wsa/genpattern
Gets or sets the pattern for the WS-Addressing asynchronous reply.

Extension variables
This section contains information about system variables in alphabetic order by
permission category. Extension variables usually impact the behavior of specific
actions, particularly fetch, results, and results-async actions. Table 16 lists the
names and permission for these variables.
Table 16. Names and permissions for extension variables
Variable name Permission
var://local/_extension/allow-compression Write-only
var://local/_extension/donot-follow-redirect Write-only
var://local/_extension/header/ Write-only
var://local/_extension/http-10-only Write-only
var://local/_extension/prevent-persistent-connection Write-only
var://local/_extension/sslprofile Write only

370 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Write-only variables
var://local/_extension/allow-compression
Enables compression of HTTP requests. Set this variable to allow
compression of outgoing results content and negotiate the returned
document to be compressed if the underlying protocol supports it. For
HTTP, this means the content-encoding and accept-encoding headers.
var://local/_extension/donot-follow-redirect
Disables HTTP redirects. Set this variable to prevent the following of
protocol-level redirect sequences on the outgoing results and fetch calls
that are associated with this context. By default, redirects are followed.
var://local/_extension/header/
Appends the specified header field to the protocol connection. Variables of
the following form can be set to append headers to the dp:url-open()
extension function or results action or fetch action connection when a
context that contains them is used as the input context:
_extension/header/*

The following example would add the HTTP header X-foo: bar to the
HTTP request:
setvar tmpvar2 var://local/_extension/header/X-foo bar
results tmpvar2 http://foo.bar.com/foome.asp tmpvar3"
var://local/_extension/http-10-only
Restricts HTTP to version 1.0. Set this variable to prevent the use of
HTTP/1.1 on the related context of a results action or fetch action.
var://local/_extension/prevent-persistent-connection
Disables HTTP persistent connection. Set this variable to prevent persistent
connections of the outgoing a results action call or fetch action call that is
associated with this context. Persistent connections are supported by
default, where appropriate.
var://local/_extension/sslprofile
Sets the SSL proxy profile for the request. This variable can be set on the
input context to a dp:url-open() extension function or to a results action or
to a fetch action to override the selection of an SSL Proxy Profile. For
instance:
results tmpvar2 https://foo.bar.com/foome.asp tmpvar3

would normally use the SSL Proxy Profile that is associated with any
user-agent configuration for the URL
https://foo.bar.com/foome.asp

If the profile needed to be determined programmatically, perhaps based on

AAA, it could be set up as follows to dynamically resolve the value of
*sslprofiletouse:
setvar tmpvar2 var://local/_extension/sslprofile
var://context/notepad/sslprofiletouse
results tmpvar2 https://foo.bar.com/foome.asp tmpvar3
var://local/_extension/timeout
Sets the request timeout on an input context to override any previously set
timeout parameter. Set the value in seconds.

Appendix C. Working with variables 371

System variables
This section contains information about system variables in alphabetic order by
permission category. Table 17 lists the names and permission for these variables.
Table 17. Names and permissions for system variables
Variable name Permission
var://system/map/debug Read-write
var://system/tasktemplates/debug Read-write

Read-write variables
var://system/map/debug
Gets or sets the debugging level for role-based management (RBM).
var://system/tasktemplates/debug
Gets or sets the debugging level for task templates.

372 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
List of available variables
Table 18 lists the variables that you can define for document processing.
Table 18. All available variables
Short variable name Full variable name Category
allow-compression var://local/_extension/allow-compression Extension
append-request-header var://service/append-request-header Transaction,
headers
append-response-header var://service/append-response-header Transaction,
headers
backend-timeout var://service/mpgw/backend-timeout Service, general
config-param var://service/config-param Service,
configuration
correlation-identifier var://service/correlation-identifier Service, MQ
debug var://system/map/debug System
var://system/tasktemplates/debug
donot-follow-redirect var://local/_extension/donot-follow-redirect Extension
error-code var://service/error-code Transaction, error
handling
error-ignore var://service/error-ignore Transaction, error
handling
error-message var://service/error-message Transaction, error
handling
error-protocol-reason-phrase var://service/error-protocol-reason-phrase Transaction, error
handling
error-protocol-response var://service/error-protocol-response Transaction, error
handling
error-subcode var://service/error-subcode Transaction, error
handling
expiry var://service/expiry Service, MQ
format var://service/format Service, MQ
genpattern var://service/wsa/genpattern Transaction, WSM
header var://local/_extension/header Extension
http-10-only var://local/_extension/http-10-only Extension
lbhealth var://service/lbhealth Service, load
balancer
max-call-depth var://service/max-call-depth Service,
configuration
message-identifier var://service/message-identifier Service, MQ
message-type var://service/message-type Service, MQ
mq-ccsi var://service/mq-ccsi Service, MQ
mqmd-reply-to-q var://service/mqmd-reply-to-q Service, MQ
mqmd-reply-to-qm var://service/mqmd-reply-to-qm Service, MQ
note var://service/connection/note Transaction,
persistent
connection

Appendix C. Working with variables 373

Table 18. All available variables (continued)
Short variable name Full variable name Category
persistence var://service/persistence Service, MQ
prevent-persistent-connection var://local/_extension/prevent-persistent- Extension
connection
priority var://service/priority Service, MQ
reply-to-q var://service/reply-to-q Service, MQ
reply-to-qm var://service/reply-to-qm Service, MQ
report var://service/report Service, MQ
routing-url var://service/routing-url Transaction,
routing
routing-url-sslprofile var://service/routing-url-sslprofile Transaction,
routing
set-request-header var://service/set-request-header Transaction,
headers
set-response-header var://service/set-response-header Transaction,
headers
skip-backside var://service/mpgw/skip-backside Service, general
soap-fault-response var://service/soap-fault-response Service, general
soap-oneway-mep var://service/soap-oneway-mep Transaction,
asynchronous
soapversion var://service/log/soapversion Service, multistep
sslprofile var://local/_extension/sslprofile Extension
strict-error-mode var://service/strict-error-mode Transaction, error
handling
timeout var://service/wsa/timeout Transaction, WSM
transaction-key var://service/transaction-key Transaction,
asynchronous
transaction-name var://service/transaction-name Transaction,
asynchronous
transaction-timeout var://service/transaction-timeout Transaction,
asynchronous
URI var://service/URI Transaction, URL
wsdl-error var://service/wsm/wsdl-error Transaction, WSM
wsdl-warning var://service/wsm/wsdl-warning Transaction, WSM

374 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Appendix D. Getting help and technical assistance
This section describes the following options for obtaining support for IBM
products:
v Searching knowledge bases
v Getting a fix
v Contacting IBM Support on page 376

Searching knowledge bases

If you encounter a problem, you want it resolved quickly. You can search the
available knowledge bases to determine whether the resolution to your problem
was already encountered and is already documented.
Documentation
The IBM WebSphere DataPower documentation library provides extensive
documentation in Portable Document Format (PDF). You can use the
search function of Adobe Acrobat to query information. If you download
and store the documents in a single location, you can use the search facility
to find all references across the documentation set.
IBM Support
If you cannot find an answer in the documentation, use the Search Support
feature from the product-specific support page.
From the Search Support (this product) area of the product-specific
support page, you can search the following IBM resources:
v IBM technote database
v IBM downloads
v IBM Redbooks
v IBM developerWorks

Getting a fix
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM product, check the product support site by performing
the following steps:
1. Go to the IBM Support site at the following Web address:

http://www.ibm.com/support
2. Select Support & Downloads Download to open the Support & downloads
page.
3. From the Category list, select WebSphere.
4. From the Sub-Category list, select WebSphere DataPower SOA Appliances.
5. Click the GO icon to display the list of most recent updates.
6. Click the link for the firmware and documentation download that is specific to
your WebSphere DataPower product.
7. Follow the instructions in the technote to download the fix.

Copyright IBM Corp. 2002, 2009 375

Contacting IBM Support
IBM Support provides assistance with product defects. Before contacting IBM
Support, the following criteria must be met:
v Your company has an active maintenance contract.
v You are authorized to submit problems.

To contact IBM Support with a problem, use the following procedure:

1. Define the problem, gather background information, and determine the severity
of the problem. For help, refer to the Software Support Handbook. To access the
online version of this handbook, use the following procedure:
a. Access the IBM Software Support Web page at the following Web address:

http://www.ibm.com/software/support
b. Scroll down to the Additional support links section of the page.
c. Under Support tools, click the Software Support Handbook link.
d. Bookmark this page for future reference.
From this page, you can obtain a PDF copy of the handbook.
2. Gather diagnostic information.
a. Access the product support at the following Web address:

http://www.ibm.com/software/integration/datapower/support
b. Locate the Assistance area of the product support page.
c. Click Information to include to access that technote that lists the
information that is required to report a problem.
3. Submit the problem in one of the following ways:
Online
From the IBM Support Web site (http://www.ibm.com/support), select
Support & Downloads Open a service request. Following the
instructions.
By phone
For the phone number to call in your country, refer to Contacts in the
Software Support Handbook. From the Software Support Handbook Web
site, click Contacts. In the U.S. and Canada, call 1800IBM-SERV
(18004267378) and select option 2 for software.

If the problem you should submit is for a software defect or for missing or
inaccurate documentation, IBM Support creates an authorized program analysis
report (APAR). The APAR describes the problem in detail. Whenever possible, IBM
Support provides a workaround that you can implement until the APAR is
resolved and a fix is delivered.

376 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Notices and trademarks
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 about 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 users 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.

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 or
changes in the product(s) or the program(s) described in this publication at any
time without notice.

Trademarks
IBM, the IBM logo, CICS, developerWorks, DB2, DataPower, IMS, RACF,
Redbooks, Tivoli, WebSphere, and z/OS are registered trademarks of the
International Business Machines Corporation in the United States or other
countries.

Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.

Microsoft and Windows are trademarks of Microsoft Corporation in the United

States, other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.
Copyright IBM Corp. 2002, 2009 377
 Other company, product, and service names may be trademarks or service marks
of others.

378 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
Index
Special characters AAA Policy (continued)
authentication (continued)
AAA Policy (continued)
file editor (continued)
... button Kerberos AP-REQ 179 credentials 267
list of referenced object 3 LDAP 174 default credential 267
referenced object 2 LTPA token 173 file information 269
.java.policy file 205 Netegrity 177 map credentials 268
[configuration-database] stanza, file none 178 map resources 268
entry 271 RADIUS 179 overview 267
[ldap] stanza, ssl-keyfile-pwd entry 271 SAML assertion, artifact 178 unauthenticated identity 267
[manager] stanza, replica entry 271 SAML assertion, valid identity extraction
<results> element 161 signature 173 BinarySecurityToken, WS-Security
<url> element 161 SAML assertions, remote 359 Header 168
+ button SAML server 175 client IP address 170
list of referenced object 3 signer certificate 179 custom 172
referenced object 2 SSL certificate, connection derived-key UsernameToken,
peer 180 WS-Security Header 167
TAM 177 extracted token, cookie value 172
A WS-SecureConversation extracted token, message 172
AAA context 178 HTTP Authentication Header 167
authentication WS-Trust server 175 Kerberos AP-REQ, SPNEGO 169
search parameters 286 X.509 certificates, remote 358 Kerberos AP-REQ, WS-Security
search parameters 286 z/OS NSS authentication 177 Header 169
TFIM 272 authorization LTPA token 172
aaa action AAA Info File 193 name, SAML
defining 94 always 186 AttributeStatement 169
dictionary attack, protection 52 any authenticated 185 name, SAML authentication
purpose 88 ClearTrust 187 assertion 170
AAA Info File custom 187 password-carrying
Authenticate element 266 LDAP 187 UsernameToken, WS-Security
authentication 178 Netegrity 186 Header 167
authorization, AAA 193 SAML attribute from Processing Metadata 172
Authorize element 267 authentication 191 SAML artifact 170
credentials mapping, AAA 181 SAML attribute query 189 SAML assertions, remote 359
editor SAML authorization query 188 subject DN, certificate in message
authenticated identities 267 TAM 186 signature 170
authorized access to XACML PDP 191 Token Subject DN (SSL),
resources 269 z/OS NSS authorization 187 connection peer 169
confirmation 270 changing authentication caching WS-SecureConversation
credentials 267 policy 181 Identifier 168
default credential 267 changing authorization caching WS-Trust Base 169
file information 269 policy 193 WS-Trust Supporting 169
map credentials 268 configuring 165 X.509 certificates, remote 358
map resources 268 creating 166 LTPA, adding user attributes 265
overview 267 credentials mapping mapping authentication
unauthenticated identity 267 AAA Info file 181 credentials 180
MapCredentials element 266 custom 180 mapping resources 183
MapResource element 266 from identity extraction 181 namespace mappings
overview 265 none 181 XPath bindings 264
resources mapping, AAA 185 TFIM 181 object pages
AAA Policy WS-SecureConversation 181 Authenticate 244
AAA Info File defining authentication method 173 Authorize 253
Authenticate element 266 defining authorization method 185 Identity 242
Authorize element 267 defining identity extraction LTPA Attributes 263
MapCredentials element 266 method 167 Main 239
MapResource element 266 defining resource extraction Map Credentials 250
overview 265 methods 182 Map Resource 252
authentication file editor Namespace Mapping 262
AAA info file 178 authenticated identities 267 Post Processing 259
BinarySecurityToken 178 authorized access to Resource 251
ClearTrust 177 resources 269 SAML Attributes 263
custom 178 confirmation 270 Transaction Priority 264

Copyright IBM Corp. 2002, 2009 379

AAA Policy (continued) actions (continued) actions (continued)
post processing decrypt (continued) results (continued)
Authorized Counter 194 purpose 89 locating remote resources 159
available activities 194 defining 94 purpose 90
Count Monitors 194 encrypt query parameters 160
custom 195 defining 110 specifying multiple URLs 159
Kerberos AP-REQ 196 Encrypted tokens 357 specifying remote locations 159
logging access attempts 194 ID references 357 results-async
LTPA 199 purpose 89 attachment protocol 160
Rejected Counter 194 SOAP message with defining 141
SAML assertion 195 WS-Security 110 locating remote resources 159
SPNEGO 200 SOAP message with XML purpose 90
TFIM 200 encryption 120 query parameters 160
WS-Security UsernameToken 198 XML message with XML specifying multiple URLs 159
WS-Trust 196 encryption 121 specifying remote locations 159
resource extraction event-sink 124 rewrite
HTTP operations 183 purpose 89 purpose 90
local name of request element 182 extract rewrite header (rewrite)
Processing Metadata 183 defining 125 defining 142
URI of top-level element 182 purpose 89 route-action
URL from client 182 fetch defining with style sheet 143
URL to backend 182 attachment protocol 160 defining with XPath
XPath from request 183 defining 125 expression 143
resources mapping locating remote resources 159 purpose 90
AAA Info File 185 purpose 89 route-set
custom 183 query parameters 160 defining 144
none 184 specifying remote locations 159 locating remote resources 159
TAM 184 filter purpose 90
TFIM 184 conformance filter 129 specifying remote location 159
XPath from resource defining 126 setvar
extraction 185 purpose 89 defining 145
SAML attributes replay filter 127 purpose 90
defining 264 required elements filter 128 variable builder 162
SFTP Server Front Side Handler 78 standard filter 126 sign
z/OS NSS Client 353 WS-Security message layout defining 145
AAAInfo.xsd file 265 filter 128 generating signature
accepted configuration for-each 130 confirmation 360
deployment policy 222 purpose 89 ID references 357
actions for-each action purpose 90
aaa specifying multiple URLs 159 verifying signature
defining 94 log confirmation 360
purpose 88 defining 133 slm
antivirus locating remote resources 159 defining 147
defining 94 purpose 89 purpose 90
purpose 88 specifying remote locations 159 sql
call MQ Header defining 147
defining 96 modifying reply queue 137 purpose 91
defining reusable rules 158 modifying reply queue strip-attachments
purpose 88, 162 manager 137 defining 148
checkpoint modifying request message purpose 91
defining 97 headers 134 supported protocols 159
purpose 88 modifying response message validate 155
conditional headers 136 purpose 91
defining 97 overview 133 verify 157
purpose 88 retrieving responses with generating signature
contexts correlation ID 135 confirmation 360
input 91 retrieving responses with message Kerberos AP-REQ tokens,
output 91 ID 135 remote 359
convert-http on-error purpose 91
defining 99 defining 138 SAML assertions, remote 359
purpose 88 defining reusable rules 158 verifying signature
cryptobin purpose 90 confirmation 360
defining 100 variable builder 162 X.509 certificates, remote 358
purpose 89 purpose 88 xform
decrypt results defining 149
defining 108 attachment protocol 160 defining buffer attachment
Encrypted tokens 357 defining 140 transform 154

380 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
actions (continued) authentication builder
xform (continued) configuring RADIUS settings 326 deployment policy 223
defining conformance LDAP 286 buttons
transform 155 search parameters 286 ... 2
defining SOAP refinement authentication caching policy, + 2
transform 152 changing 181 Apply 4
purpose 91 authentication, AAA Cancel 4
xformbin AAA info file 178 Delete 5
defining 150 available methods 173 Edit 3
purpose 91 BinarySecurityToken 178 Logout 1
xformpi ClearTrust 177 Save Config 1, 4
defining 151 connection peer Undo 5
purpose 91 SSL certificate 180 View 3
Add button custom 178
list of referenced object 3 Kerberos AP-REQ 179
admin account
exporting configuration data 211
LDAP 174
LTPA token 173
C
CA Unicenter Manager 352
Administration menu 1 Netegrity 177
caches
administrative states, objects 6 none 178
flushing
antivirus (antivirus) action RADIUS 179
document cache 353
defining 94 SAML assertion
stylesheet cache 353
antivirus action artifact 178
caching policy
purpose 88 valid signature 173
AAA Policy
AP-REQ message, Kerberos 274 SAML assertions, remote 359
authentication 181
appliance configuration SAML server 175
authorization 193
backing up 211, 212 signer certificate 179
call action
comparing 220 TAM 177
defining 96
configuration checkpoints 216 WS-SecureConversation context 178
defining reusable rules 158
copying WS-Trust server 175
purpose 88
files 215 X.509 certificates, remote 358
call processing rule (call) action
objects 215 z/OS NSS authentication 177
variable builder 162
exporting 211 authorization caching policy,
call processing rule action
select objects and files 213 changing 193
See call action
importing configuration 218 authorization, AAA
Cancel button 4
managing configuration changes 220 AAA Info File 193
cert: directory 201
moving always 186
certificate files
files 215 any authenticated 185
location 201
objects 215 available methods 185
Certificate objects
reading change report 221 ClearTrust 187
export packages 211
reverting changes 221 custom 187
certificates
undoing changes 221 LDAP 187
DER 9
appliance-wide log Netegrity 186
exporting 11
location 201 SAML attribute from
generating 10
application domains authentication 191
importing 12
backing up configuration 212 SAML attribute query 189
PEM 9
Apply button 4 SAML authorization query 188
PKCS #12 9
asynchronous transaction variables TAM 186
PKCS #8 9
service/transaction-timeout 366 XACML PDP 191
security
asynchronous transactions variables z/OS NSS authorization 187
location, shared 202
listing 366 Authorize element, AAA Info File 267
location, Web browsers 202
service/transaction-key 366 auto-config.cfg file 4
supported formats 9
service/transaction-name 366
uploading 205
asynchronous variables
checkpoint action
service/soap-oneway-mep 366
attachment protocol
B purpose 88
backend-timeout variable 363 checkpoint configuration files
actions 160
Basic Profile 1.0 location 201
query parameters 160
Conformance Policy 279 checkpoint event (checkpoint) action
attachments
Basic Profile 1.1 defining 97
buffering transform 154
Conformance Policy 279 chkpoints: directory 201
Attachments Profile 1.0
Basic Security Profile 1.0 clear pdp cache CLI 279
Conformance Policy 279
Conformance Policy 279 clear xsl cache CLI 279
audit log
BinarySecurityToken ClearTrust
location 201
authentication, AAA 178 authentication, AAA 177
viewing 201
identity extraction, AAA 168 authorization, AAA 187
audit: directory 201
bold typeface xi client-to-server rule 87
Authenticate element, AAA Info File 266
buffer-attachments.xsl style sheet 154 Clone link 6

Index 381
commands Conformance Policy (continued) Crypto Profile
clear pdp cache 279 WS-I Basic Security Profile 279 configuring 17
clear xsl cache 279 conformance transform 155 creating 17
web-mgmt 1 conformance-filter.xsl style sheet 129 object pages 17
conditional action conformance-xform.xsl style sheet 155 Crypto Shared Secret Key
defining 97 contexts configuring 18
purpose 88 actions creating 18
config: directory 201 input 91 object pages 18
configuration output 91 Crypto Tools
managing appliance keywords exporting certificates 11
configuration 209 INPUT 92 exporting keys 11
configuration checkpoints NULL 92 generating certificates 10
defining number to allow 216 OUTPUT 92 generating keys 10
deleting 218 PIPE 92 importing certificates 12
listing 217 processing policies 91 importing keys 12
loading 218 processing rules 92 Crypto Validation Credentials
overwriting 217 Control Panel object pages 21
rolling back 218 File Management 203 cryptobin action
saving 217 convert query parameters to XML defining 100
configuration data (convert-http) action purpose 89
applying 4 defining 99 cryptography
backing up convert query parameters to XML action Multi-Protocol Gateway 31
WebGUI 211, 212 See convert-http action customer support
backing up application domains 212 convert-http action contacting 376
comparing defining 99 obtaining fixes 375
WebGUI 220 purpose 88 searching knowledge bases 375
configuration checkpoints 216 Count Monitor
copying Authorized Counter 194
files 215
objects 215
dictionary attack, protection 52
post processing, AAA 194
D
dashboard 1
different release level 211 Rejected Counter 194
debugging
exchanging 211 count monitors
processing policies 163
exporting configuring 230
decrypt action
location of files 201 Count Monitors
defining 108
select objects and files 213 Multi-Protocol Gateway 301
Encrypted tokens 357
WebGUI 211 credentials
purpose 89
files not included 211 identification
decrypt.xsl file 109
importing configuring 15
default log
WebGUI 211, 218 creating 15
location 201
managing changes 220 credentials mapping
Delete button 5
moving LDAP 286
list of referenced object 3
files 215 search parameters 286
denial-of-service, protection
objects 215 credentials mapping, AAA
multiple message (MMXDoS) 50
objects not included 211 AAA Info file 181
single message (XDoS) 49
reading change report 221 available methods 180
deployment policy
reading changes 221 custom 180
accepted configuration 222
saving 4 from identity extraction 181
creating 222
undoing changes 221 none 181
filtered configuration 222
configuration files TFIM 181
modified configuration 222
exported, location 201 WS-SecureConversation 181
using the builder 223
location 201 crypto binary (cryptobin) action
Deployment Policy
TAM defining 100
object pages 222
ASCII 270 crypto binary action
deployment policy builder
creating 271 See cryptobin action
creating matching statements 223
modifying 271 Crypto Certificate
DER
obfuscated 270 configuring 13
certificate format 9
configuration service variables creating 13
key format 9
listing 363 object pages 13
dictionary attack, protection 52
service/config-param/ 363 Crypto Firewall Credentials
directories
service/max-call-depth 363 object pages 14
audit: 201
configuration states, objects 6 Crypto Identification Credentials
available 201
conformance filter 129 object pages 15
cert: 201
Conformance Policy Crypto Key
chkpoints: 201
filter actions 280 configuring 16
config: 201
object pages 279 creating 16
displaying contents 203
WS-I Attachments Profile 279 object pages 16
dpcert: 201
WS-I Basic Profile 279
export: 201

382 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
directories (continued) error rule 87 files (continued)
hiding contents 203 event-sink action deleting 208
image: 201 defining event-sink 124 editing
local: 201 purpose 89 during configuration 4
logstore: 201 examples File Management utility 208
logtemp: 201 specifying dual thresholds 237 encrypt-soap.xsl 120
managing 201 Export link 5 encrypt-wssec.xsl 110
pubcert: 202 export packages encrypt.xsl 121
refreshing contents 204 admin account 211 exported, location 201
sharedcert: 202 files not included 211 fetching 206
store: 202 objects not included 211 healthcheck.xml 291
tasktemplates: 203 permission 211 healthcheck.xsl 292
temporary: 203 export: directory 201 managing 201
disabled administrative state 6 Extensible Access Control Markup moving 207
Document Crypto Map Language not in export packages
object pages See XACML PDP firmware files 211
Main 282 extension functions log files 211
Namespace Mappings 283 node-set() 352 pkcs7-decrypt.xsl 107
documentation conventions, typefaces xi set-target() 143 pkcs7-encrypt.xsl 106
Domain list 1 extension variables pkcs7-sign.xsl 101
down operation state 6 listing 370 pkcs7-verify.xsl 103
dpcert: directory 201 local/_extension/allow- private keys
dpmq protocol 159 compression 371 location 201
dptibems protocol 159 local/_extension/donot-follow- renaming 207
dptibemss protocol 159 redirect 371 SQL-Injection-Filter.xsl 50
dpwasjms protocol 159 local/_extension/header/ 371 SQL-Injection-Patterns.xml 50
dpwasjmss protocol 159 local/_extension/http-10-only 371 TAM
duration monitors local/_extension/prevent-persistent- ASCII configuration 270
configuring 233 connection 371 creating configuration 271
Duration Monitors local/_extension/sslprofile 371 modifying configuration 271
Multi-Protocol Gateway 301 local/_extension/timeout 371 obfuscated configuration 270
extract action SSL key 270
defining 125 SSL stash 270
E purpose 89
extract using XPath (extract) action
uploading
JKS 205
Edit button 3
defining 125 remote 206
elements
extract using XPath action workstation 204
EncryptedData element 357
See extract action viewing
SecurityTokenReference 358
during configuration 4
SignatureConfirmation 359
File Management utility 208
enabled administrative state 6
encrypt action F filter action
conformance filter 129
defining 110 fetch action
Conformance Policy 280
Encrypted tokens 357 attachment protocol 160
defining 126
ID references 357 defining 125
purpose 89
purpose 89 locating remote resources 159
replay filter 127
SOAP message with WS-Security 110 purpose 89
required elements filter 128
SOAP message with XML query parameters 160
SQL injections, protection 50
encryption 120 specifying remote locations 159
standard filter 126
XML message with XML supported protocols 159
WS-Security message layout
encryption 121 file entry, [configuration-database]
filter 128
encrypt-soap.xsl file 120 stanza 271
filter-accept-all.xsl style sheet 126
encrypt-wssec.xsl file 110 File Management utility, launching 203
filter-reject-all.xsl style sheet 126
encrypt.xsl file 121 file system
filtered configuration
encrypted tokens See directories
deployment policy 222
EncryptedData element 357 files
Firewall Credentials
EncryptedData element 357 .java.policy 205
configuring 14
error code rule 87 AAAInfo.xsd 265
creating 14
error handling variables auto-config.cfg 4
firmware files
listing 367 certificates
between release levels 211
service/error-code 367 location 201
export packages 211
service/error-ignore 367 checkpoint configurations
firmware images
service/error-message 367 location 201
location 201
service/error-protocol-reason- configurations
fixes, obtaining 375
phrase 367 location 201
flash drive
service/error-protocol-response 367 copying 206
See directories
service/error-subcode 367 remote URL 206
service/strict-error-mode 368 decrypt.xsl 109

Index 383
for-each
purpose 89
I intermediary service provider,
SOAP 152
for-each action IBM Tivoli Access Manager italics typeface xi
defining for-each 130 See TAM
locating remote resources 159 IBM Tivoli Federated Identity Manager
See TFIM
specifying multiple URLs 159
use cases 130 ID references J
encrypt action 357 J2RE (j2re1.4.2) 205
Front Side Handler
sign action 357 j2re1.4.2 (J2RE) 205
object pages
Identification Credentials j2sdk1.4.2 (SDK) 205
FTP Poller 57
configuring 15 Java Crypto Extension
FTP Server 60
creating 15 See SunJCE
HTTP 70
identity extraction Java Crypto Extension Key Store
HTTPS 71
AAA See JCEKS
IMS Connect 72
BinarySecurityToken, WS-Security Java Key Store
MQ 73
Header 168 See JKS
NFS Poller 75
identity extraction, AAA java.security package 205
SFTP Server 77
available methods 167 JCE
Stateful Raw XML 80
client IP address 170 See SunJCE
Stateless Raw XML 81
connection peer JCEKS 205
TIBCO EMS 82
Token Subject DN, SSL 169 JKS
WebSphere JMS 84
custom 172 crypto extension 205
FTP Poller
extracted token granting permissions 205
Front Side Handler 57
as cookie value 172 java.security package 205
ftp protocol 159
from message 172 keytool utility 205
FTP Server
HTTP Authentication Header 167 managing 205
Front Side Handler 60
LTPA token 172 required software 205
Processing Metadata 172 uploading certificates 205
SAML artifact 170 working with 205
G SAML assertion
general variables AttributeStatement 169
listing 362
service/soap-fault-response 362
AuthenticationStatement 170 K
SPNEGO KDC, Kerberos 274
Kerberos AP-REQ 169 Kerberos
subject DN AP-REQ message 274
H certificate in message configuring KDC server 276
health check signature 170 KDC 274
filter 292 SAML assertions, remote 359 keytab 274
SOAP request 291 SSL certificate 169 principal 274
healthcheck.xml file 291 X.509 certificates, remote 358 Kerberos AP-REQ
healthcheck.xsl file 292 WS-SecureConversation authentication, AAA 179
HTTP Front Side Handler 70 Identifier 168 identity extraction, AAA
HTTP header WS-Security Header SPNEGO 169
identity extraction, AAA 167 Kerberos AP-REQ 169 WS-Security Header 169
HTTP Header Injection UsernameToken, derived-key 167 post processing, AAA 196
Multi-Protocol Gateway 304 UsernameToken, verify action 359
HTTP header parameters password-carrying 167 Kerberos AP-REQ tokens, remote 359
Multi-Protocol Gateway WS-Trust Kerberos KDC server
configuring 34 Base 169 configuring 276
injection parameters 34 Supporting 169 creating 276
suppression parameters 35 image: directory 201 object pages 276
HTTP Header Suppression Import Package Kerberos keytab
Multi-Protocol Gateway 304 creating 210 configuring 276
HTTP Input Conversion Map IMS Connect definition 274
object pages object pages Kerberos Keytab File
Input Encoding 284 Main 284 object pages 276
Main 283 URL builder 52 Key Distribution Center
HTTP matching rule 87 IMS Connect Handler 72 See KDC
HTTP operations ims protocol 159 Key objects
resource extraction, AAA 183 imsssl protocol 159 export packages 211
HTTP Options Include Configuration File key-certificate pairs
Multi-Protocol Gateway 302 creating 209 creating 9
http protocol 159 object pages 209 keys
HTTPS Front Side Handler 71 input context, actions 91 DER 9
https protocol 159 INPUT keyword 92 exporting 11
installation images generating 10
See firmware images importing 12
intellectual property 377

384 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
keys (continued) local/_extension/prevent-persistent- modified configuration
PEM 9 connection variable 371 deployment policy 222
PKCS #12 9 local/_extension/sslprofile variable 371 Modified configuration state 6
PKCS #7 9 local/_extension/timeout variable 371 monitoring statistics, enabling 235
supported formats 9 log action monitors
keywords defining 133 count monitors
contexts locating remote resources 159 configuring 230
INPUT 92 purpose 89 duration monitors
NULL 92 specifying remote locations 159 configuring 233
OUTPUT 92 supported protocols 159 message monitors
PIPE 92 log files configuring 226
knowledge bases export packages 211 count monitors 230
searching 375 log/soapversion variable 365 duration monitors 233
logging filter action 230
post processing, AAA message type 229
L access attempts 194
Logout button 1
traffic definition 227
Multi-Protocol Gateway 35, 301
LDAP
logs types 225
authentication
appliance-wide Web services monitors
search parameters 286
location 201 configuring 235
authentication, AAA 174
audit enabling 235
authorization, AAA 187
location 201 overview 234
credentials mapping
viewing 201 specifying dual thresholds 237
search parameters 286
default monospaced typeface xi
search parameters 286
location 201 MQ
licensing
viewing from catalog 5 URL builder 53
sending inquiries 377
viewing from configuration screen 5 MQ Front Side Handler 73
links
viewing object-specific logs 5 MQ Get Message Options (GMO)
Clone 6
logstore: directory 201 MQGET options 73
Export 5
logtemp: directory 201 MQGMO_* 73
Show Probe 7
LTPA MQ header action
View Logs 5
adding user attributes, AAA modifying
View Status 6
Policy 265 reply queue 137
load balancer group
authentication, AAA 173 reply queue manager 137
creating 287
identity extraction, AAA 172 request message headers 134
server state 287
post processing, AAA 199 response message headers 136
Load Balancer Group
overview 133
adding members 290
retrieving responses
assigning weight 290
configuring, basic 288 M with correlation ID 135
with message ID 135
example MapCredentials element, AAA Info
MQ Host variables
DataPower service 55 File 266
listing 364
health MapResource element, AAA Info
service/correlation-identifier 365
convalescent (down) 288 File 266
service/expiry 365
healthy (up) 287 Matching Rule
service/format 365
quarantined (softdown) 287 object pages 292
service/message-identifier 365
health checks matching rules
service/message-type 365
enabling 291 error code 87
service/mq-ccsi 364
overriding port 290 HTTP 87
service/mqmd-reply-to-q 364
health of members 287 processing policies 87
service/mqmd-reply-to-qm 364
object pages URL 87
service/persistence 365
Health 291 XPath 87
service/priority 365
Main 288 matching statements
service/reply-to-q 365
Members 290 deployment policy builder 223
service/reply-to-qm 365
replacing backend server 55 deployment policy, manual 224
service/report 365
service/lbhealth/ variable 288 message catalogs 202
mq protocol 159
load balancer service variables message layout filter, WS-Security 128
MQ Proxy variables
listing 364 message monitors
listing 364
service/lbhealth/ 364 configuring 226
service/correlation-identifier 365
local: directory 201 count monitors 230
service/expiry 365
local/_extension/allow-compression duration monitors 233
service/format 365
variable 371 filter action 230
service/message-identifier 365
local/_extension/donot-follow-redirect message type 229
service/message-type 365
variable 371 traffic definition 227
service/mq-ccsi 364
local/_extension/header/ variable 371 message tampering, protection 50
service/mqmd-reply-to-q 364
local/_extension/http-10-only messages
service/mqmd-reply-to-qm 364
variable 371 validating conformance 279
service/persistence 365
MMXDoS, protection 50

Index 385
MQ Proxy variables (continued) navigation (continued) object pages (continued)
service/priority 365 Status menu 1 Matching Rule 292
service/reply-to-q 365 Netegrity Multi-Protocol Gateway
service/reply-to-qm 365 authentication, AAA 177 HTTP Header Injection 304
service/report 365 authorization, AAA 186 HTTP Header Suppression 304
MQ request messages Network HTTP Options 302
modifying message headers 134 Multi-Protocol Gateway 31 Main 294
specifying correlation ID 135 Network menu 1 Monitors 301
specifying message ID 135 New configuration state 6 Parser Limits 301
MQ response messages NFS Poller Front Side Handler 75 Proxy Settings 296
modifying headers 136 node-set() extension function 352 Stylesheet Parameter 310
modifying reply queue 137 notices 377 WS-Addressing 304
modifying reply queue manager 137 NULL keyword 92 WS-ReliableMessaging 304
Multi-Protocol Gateway Peer Group 311
advanced configuration 31 Policy Parameters
basic settings 27
changing cryptographic behavior 31
O Main 312
Policy Parameters 312
object pages
changing network behavior 31 Processing Action
AAA Policy
configuring 25 Main 313
Authenticate 244
configuring monitors 35 Named Inputs 321
Authorize 253
configuring Multi-Protocol Gateway Named Outputs 321
Identity 242
objects 294 Stylesheet Parameters 321
LTPA Attributes 263
configuring processing Processing Metadata
Main 239
parameters 34 Main 322
Map Credentials 250
creating 26 Metadata Items 322
Map Resource 252
creating Multi-Protocol Gateway Processing Policy
Namespace Mapping 262
objects 294 Main 323
Post Processing 259
HTTP header Policy Maps 324
Resource 251
configuring parameters 34 Processing Rule 324
SAML Attributes 263
injection parameters 34 Schema Exception Map
Transaction Priority 264
suppression parameters 35 Main 327
Conformance Policy 279
object pages Rules 327
Crypto Certificate 13
HTTP Header Injection 304 SLM Action 332
Crypto Firewall Credentials 14
HTTP Header Suppression 304 SLM Credentials Class 328
Crypto Identification Credentials 15
HTTP Options 302 SLM Policy 333
Crypto Key 16
Main 294 SLM Resource Class 330
Crypto Profile 17
Monitors 301 SLM Schedule 332
Crypto Shared Secret Key 18
Parser Limits 301 SOAP Header Disposition Table
Crypto Validation Credentials 21
Proxy Settings 296 Main 336
Deployment Policy 222
Stylesheet Parameter 310 SOAP Header Refine
Document Crypto Map
WS-Addressing 304 Instruction 336
Main 282
WS-ReliableMpessaging 304 SQL Data Source
Namespace Mappings 283
service description 294 Data Source Configuration
Front Side Handler
service variables Parameters 338
FTP Poller 57
backend-timeout 363 Main 337
FTP Server 60
service/reply-to-q 363 SSL Proxy Profile 19
HTTP 70
service/reply-to-qm 363 TAM 271
HTTPS 71
skip-backside 363 TFIM 272
IMS Connect 72
threat protection 48 URL Rewrite Policy
MQ 73
WS-Addressing Main 339
NFS Poller 75
configuring 36 URL Rewrite Rule 339
SFTP Server 77
multistep variables User Agent
Stateful Raw XML 80
log/soapversion 365 Allow-Compression Policy 346
Stateless Raw XML 81
multistep/loop-count service Basic-Auth Policy 344
TIBCO EMS 82
variable 133 Chunked Uploads Policy 348
WebSphere JMS 84
multistep/loop-iterator service FTP Client Policies 349
HTTP Input Conversion Map
variable 132 Inject Header Policy 347
Input Encoding 284
Main 342
Main 283
Proxy Policy 342
IMS Connect
N Main 284
Pubkey-Auth Policy 345
Restrict to HTTP 1.0 Policy 347
namespace mappings, AAA Policy 264 Include Configuration File 209
Soap-Action Policy 345
NAS-identifier 326 Kerberos KDC server 276
SSL Proxy Profile 343
navigation Kerberos Keytab File 276
XACML PDP 277
Administration menu 1 Load Balancer Group
XML Manager 352
Network menu 1 Health 291
objects
Objects menu 1 Main 288
administrative state 6
Services menu 1 Members 290

386 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
objects (continued)
configuration state 6
post processing, AAA
Authorized Counter 194
Q
not in export packages available activities 194 query parameters
Certificate 211 Count Monitors 194 actions 160
Key 211 custom 195 attachment protocol 160
User 211 Kerberos AP-REQ 196 queues
operational state 6 logging access attempts 194 TIBCO EMS 82
referenced LTPA 199 WebSphere JMS 84
... button 2 Rejected Counter 194
+ button 2 SAML assertion 195
creating 2 SPNEGO 200 R
modifying 2 TFIM 200 RADIUS
selecting 2 WS-Security UsernameToken 198 authentication, AAA 179
status 6 WS-Trust 196 NAS-identifier 326
TFIM 272 principal, Kerberos 274 purpose 326
Objects menu 1 private key files referenced objects
on-error location 201 ... button 2
variable builder 162 private keys + button 2
on-error action uploading 205 creating 2
defining 138 Processing Action modifying 2
defining reusable rules 158 object pages selecting 2
purpose 90 Main 313 referenced objects, lists
operational states, objects 6 Named Inputs 321 ... button 3
output context, actions 91 Named Outputs 321 + button 3
OUTPUT keyword 92 Stylesheet Parameters 321 Add button 3
Processing Metadata adding 3
identity extraction, AAA 172 creating 3
P object pages
Main 322
Delete button 3
parameters, HTTP header deleting 3
Metadata Items 322 modifying 3
Multi-Protocol Gateway
resource extraction, AAA 183 selecting 3
configuring 34
ssh-password-metadata 78 Rejected Counter Tool 194
injection parameters 34
ssh/password variable 78 replay filter 127
suppression parameters 35
ssh/publickey variable 78 replay-filter.xsl style sheet 127
Parser Limits
ssh/username variable 78 replica entry, [manager] stanza 271
Multi-Protocol Gateway 301
processing parameters required-elements-filter.xsl style
patents 377
Multi-Protocol Gateway 34 sheet 128
Peer Group
processing policies resource extraction, AAA
object pages 311
contexts 91 available methods 182
PEM
creating 92 HTTP operations 183
certificate format 9
debugging 163 local name of request element 182
key format 9
defining 87 Processing Metadata 183
persistent connections variables
matching rules 87 URI of top-level element 182
listing 368
processing rules 87 URL from client 182
service/connection/note 369
Processing Policy URL to backend 182
PIPE keyword 92
object pages XPath from request 183
PKCS #12
Main 323 resources mapping, AAA
certificate format 9
Policy Maps 324 AAA Info File 185
key format 9
Processing Rule available methods 183
PKCS #7
object pages 324 custom 183
certificate format 9
processing rules none 184
decrypting documents 107
client-to-server 87 TAM 184
encrypting documents 105
contexts 92 TFIM 184
signing documents 100
direction 87 XPath from resource extraction 185
verifying signed documents 103
error 87 results action
PKCS #8
processing policies 87 <results> element 161
key format 9
server-to-client 87 <url> element 161
pkcs7-decrypt.xsl file 107
two way 87 attachment protocol 160
pkcs7-encrypt.xsl file 106
protocols defining 140
pkcs7-sign.xsl file 101
supported 159 locating remote resources 159
pkcs7-verify.xsl file 103
Proxy Settings purpose 90
Policy Decision Point
Multi-Protocol Gateway 296 query parameters 160
See XACML PDP
pubcert: directory 202 specifying multiple URLs 159
Policy Parameters
defining 312 supported protocols 159
object pages results asynchronous action
Main 312 See results-async action
Policy Parameters 312

Index 387
results-async Saved configuration state 6 service/soap-fault-response variable 362
defining 141 Schema Exception Map service/soap-oneway-mep variable 366
results-async action object pages service/strict-error-mode variable 368
<results> element 161 Main 327 service/transaction-key variable 366
<url> element 161 Rules 327 service/transaction-name variable 366
attachment protocol 160 schemas service/transaction-timeout variable 366
locating remote resources 159 location 202 service/URI variable 79, 370
purpose 90 SDK (j2sdk1.4.2) 205 service/wsa/genpattern variable 370
query parameters 160 search parameters, LDAP 286 service/wsa/timeout variable 370
specifying multiple URLs 159 security certificates service/wsm/wsdl-error variable 370
supported protocols 159 shared service/wsm/wsdl-warning
rewrite action location 202 variable 370
purpose 90 Web browsers Services
rewrite header (rewrite) action location 202 Multi-Protocol Gateway Service 294
defining 142 Security Token Reference Services menu 1
rewrite header action See STR set variable (setvar) action
See rewrite action SecurityContextToken, WS-Trust defining 145
route action post processing, AAA 196 variable builder 162
overview 142 SecurityTokenReference element 358 set variable action
with style sheet 143 server pool See setvar action
with variables 144 See load balancer group set-target() extension function 143
with XPath expression 143 server state setvar action
route with style sheet action load balancer group 287 <results> element 161
See route-action action server-to-client rule 87 <url> element 161
route with variables action Service Monitors defining 145
See route-set action Multi-Protocol Gateway 301 purpose 90
route with XPath expression action service variables variable builder 162
See route-action action listing 362 SFTP Server
route-action action multistep/loop-count 133 Front Side Handler 77
defining multistep/loop-iterator 132 SFTP Server Front Side Handler
with style sheet 143 types 362 AAA Policy 78
with XPath expression 143 service/append-request-header/ authentication 78
purpose 90 variable 368 authorization 78
route-set action 159 service/append-response-header/ configuration considerations 78
defining 144 variable 368 metadata variables 78
locating remote resources 159 service/config-param/ variable 363 routing 79
purpose 90 service/connection/note variable 369 URI propagation 79
supported protocols 159 service/correlation-identifier URL specifications 79
variable 365 sharedcert: directory 202
service/error-code variable 367 Show Probe link 7
S service/error-ignore variable 367
service/error-message variable 367
sign action
defining 145
S11:actor SOAP attribute 152
service/error-protocol-reason-phrase generating signature
S11:mustUnderstand SOAP attribute 152
variable 367 confirmation 360
S12:mustUnderstand SOAP attribute 152
service/error-protocol-response ID references 357
S12:notUnderstood SOAP attribute 152
variable 367 purpose 90
S12:relay SOAP attribute 152
service/error-subcode variable 367 verifying signature confirmation 360
S12:role SOAP attribute 152
service/expiry variable 365 signature confirmation 359
SAML assertion
service/format variable 365 SignatureConfirmation element 359
authentication, AAA
service/lbhealth/ variable 288, 364 signed documents, PKCS #7
artifact 178
service/max-call-depth variable 363 decrypting 107
valid signature 173
service/message-identifier variable 365 encrypting 105
identity extraction, AAA
service/message-type variable 365 signing 100
AttributeStatement 169
service/mq-ccsi variable 364 verifying 103
AuthenticationStatement 170
service/mqmd-reply-to-q variable 364 skip-backside variable 363
post processing, AAA 195
service/mqmd-reply-to-qm variable 364 slm action
SAML assertions 359
service/persistence variable 365 defining 147
AAA Policy
service/priority variable 365 purpose 90
authentication 359
service/reply-to-q variable 363, 365 SLM action
identity extraction 359
service/reply-to-qm variable 363, 365 See slm action
verify action 359
service/report variable 365 SLM Action
SAML attributes
service/routing-url variable 79, 369 creating 332
defining, AAA Policy 264
service/routing-url-sslprofile object pages 332
SAML server
variable 369 SLM Credentials Class
authorization, AAA
service/set-request-header/ variable 368 creating 328
attribute query 189
service/set-response-header/ object pages 328
authorization query 188
variable 368
Save Config button 1, 4

388 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
SLM Policy
configuring
SSH (continued)
URL specifications 79
T
overview 328 ssh-password-metadata Processing TAM
creating 333 Metadata 78 ASCII configuration file 270
creating SLM Action objects 332 ssh/password variable 78 authentication, AAA 177
creating SLM Credentials Class ssh/publickey variable 78 authorization server replicas 271
objects 328 ssh/username variable 78 authorization, AAA 186
creating SLM policy objects 333 SSL configuration, general 270
creating SLM Resource Class client proxy, creating 19 configuring TAM objects 271
objects 330 forward proxy, creating 19 creating configuration files 271
creating SLM Schedule objects 332 reverse, proxy, creating 19 creating TAM objects 271
object pages 333 server proxy, creating 19 licensing 270
SLM Resource Class two-way proxy, creating 20 modifying configuration files 271
creating 330 SSL authentication 17 obfuscated configuration file 270
object pages 330 SSL Proxy Profile object pages 271
SLM Schedule creating refreshing certificates 272
creating 332 client proxy 19 resources mapping, AAA 184
object pages 332 forward proxy 19 security 270
smtp protocol 159 reverse proxy 19 SSL key file 270
SOAP attributes server proxy 19 SSL stash file 270
S11:actor 152 two-way proxy 20 tasktemplates: directory 203
S11:mustUnderstand 152 object pages 19 tcp protocol 159
S12:mustUnderstand 152 ssl-keyfile-pwd entry, [ldap] stanza 271 tcps protocol 159
S12:notUnderstood 152 Stateful Raw XML Handler 80 temporary: directory 203
S12:relay 152 Stateless Raw XML Handler 81 TFIM
S12:role 152 statistics, enabling 235 AAA 272
SOAP Header Disposition Table Status menu 1 credentials mapping, AAA 181
object pages store: directory 202 object 272
Main 336 STR dereference transform 358, 359 object pages 272
SOAP Header Refine strip-attachments action post processing, AAA 200
Instruction 336 defining 148 resources mapping, AAA 184
SOAP refinement transform 152 purpose 91 TFIM endpoint
SOAP request style sheets WS-Trust messages 272
healthcheck.xml 291 buffer-attachments.xsl 154 threat protection
SOAP service provider type 152 conformance-filter.xsl 129 denial-of-service
soap-refine.xsl style sheet 152 conformance-xform.xsl 155 multiple message 50
specifying remote locations 159 filter-accept-all.xsl 126 single message 49
specifying multiple URLs 159 filter-reject-all.xsl 126 dictionary attack 52
SPNEGO flushing the cache 353 message tampering 50
identity extraction, AAA 169 healthcheck.xsl 292 SQL injections 50
Kerberos AP-REQ 169 location 202 XML virus (X-Virus) 51
post processing, AAA 200 replay-filter.xsl 127 TIBCO EMS
sql action required-elements-filter.xsl 128 URL builder 54
defining 147 soap-refine.xsl 152 TIBCO EMS Front Side Handler
purpose 91 wssecurity-message-layout- purpose 82
SQL action filter.xsl 128 queues 82
See sql action Stylesheet Parameter support 82
SQL Data Source Multi-Protocol Gateway 310 topic spaces 82
defining 337 subdirectories TIBCO Rendezvous 82
high-level configuration 337 creating 203 TIBCO SmartSockets 82
object pages deleting 204 Tivoli Access Manager
Data Source Configuration SunJCE See TAM
Parameters 338 JCEKS 205 topic spaces
Main 337 support TIBCO EMS 82
SQL injections, protection 50 See customer support WebSphere JMS 84
sql protocol 159 Synchronous to WS-Addressing trademarks 377
SQL-Injection-Filter.xsl style sheet 50 Mode 37 transaction headers variables
SQL-Injection-Patterns.xml file 50 system variables listing 368
SSH listing 372 service/append-request-header/ 368
AAA Policy 78 system/map/debug 372 service/append-response-header/
authentication 78 system/tasktemplates/debug 372 368
authorization 78 system/map/debug variable 372 service/set-request-header/ 368
metadata variables 78 system/tasktemplates/debug service/set-response-header/ 368
routing 79 variable 372 transaction routing variables
streaming 78 listing 369
timeout 78 service/routing-url 369
URI propagation 79 service/routing-url-sslprofile 369

Index 389
transaction URL variables User objects variables (continued)
listing 369 export packages 211 MQ Host (continued)
service/URI 370 UsernameToken service/expiry 365
transaction variables identity extraction, AAA service/format 365
listing 366 derived-key 167 service/message-identifier 365
types 366 password-carrying 167 service/message-type 365
transform action post processing, AAA 198 service/mq-ccsi 364
See also xform action utilities service/mqmd-reply-to-q 364
attachments keytool 205 service/mqmd-reply-to-qm 364
buffering 154 service/persistence 365
defining buffer attachment service/priority 365
transform 154
defining conformance transform 155
V service/reply-to-q 365
service/reply-to-qm 365
validate action 155
defining SOAP refinement service/report 365
message tampering, protection 50
transform 152 MQ Proxy
purpose 91
defining standard transform listing 364
Validation Credentials
non-XML messages 150 service/correlation-identifier 365
creating
XML messages 149 service/expiry 365
non expiring, non-password-
overview 149 service/format 365
protected certificates 21
processing instruction-based service/message-identifier 365
select certificates 21
transform 151 service/message-type 365
types of lists 21
SOAP messages service/mq-ccsi 364
variable builder 162
refinement transform 152 service/mqmd-reply-to-q 364
variables
XML messages service/mqmd-reply-to-qm 364
asynchronous
conformance 155 service/persistence 365
service/soap-oneway-mep 366
defining 149 service/priority 365
asynchronous transactions
processing instruction-based 151 service/reply-to-q 365
listing 366
Transform binary action service/reply-to-qm 365
service/transaction-key 366
See xformbin action service/report 365
service/transaction-name 366
Transform using processing instruction Multi-Protocol Gateway
service/transaction-timeout 366
action backend-timeout 363
configuration service
See xformpi action service/reply-to-q 363
listing 363
two way rule 87 service/reply-to-qm 363
service/config-param/ 363
typeface conventions xi skip-backside 363
service/max-call-depth 363
multistep
error handling
log/soapversion 365
listing 367
U service/error-code 367
persistent connections
listing 368
ultimate service provider, SOAP 152 service/error-ignore 367
service/connection/note 369
Undo button 5 service/error-message 367
service
up operational state 6 service/error-protocol-reason-
listing 362
URL builder phrase 367
type 362
IMS Connect 52 service/error-protocol-
service/routing-url 79
MQ 53 response 367
service/URI 79
TIBCO EMS 54 service/error-subcode 367
ssh/password 78
WebSphere JMS 54 service/strict-error-mode 368
ssh/publickey 78
URL matching rule 87 extension
ssh/username 78
URL Rewrite Policy listing 370
system
object pages local/_extension/allow-
listing 372
Main 339 compression 371
system/map/debug 372
URL Rewrite Rule 339 local/_extension/donot-follow-
system/tasktemplates/debug 372
use cases redirect 371
transaction
for-each action 130 local/_extension/header/ 371
listing 366
User Agent local/_extension/http-10-only 371
type 366
object pages local/_extension/prevent-
transaction headers
Allow-Compression Policy 346 persistent-connection 371
listing 368
Basic-Auth Policy 344 local/_extension/sslprofile 371
service/append-request-header/
Chunked Uploads Policy 348 local/_extension/timeout 371
368
FTP Client Policies 349 general
service/append-response-header/
Inject Header Policy 347 listing 362
368
Main 342 service/soap-fault-response 362
service/set-request-header/ 368
Proxy Policy 342 list, all available 373
service/set-response-header/ 368
Pubkey-Auth Policy 345 load balancer service
transaction routing
Restrict to HTTP 1.0 Policy 347 listing 364
listing 369
Soap-Action Policy 345 service/lbhealth/ 288, 364
service/routing-url 369
SSL Proxy Profile 343 MQ Host
service/routing-url-sslprofile 369
user authentication listing 364
RADIUS 326 service/correlation-identifier 365

390 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide
variables (continued) WebGUI (continued) WTX (continued)
transaction URL Status menu 1 output contexts 318
listing 369 viewing object status 6 xformbin action 150, 318
service/URI 370 viewing object-specific logs 5
types 361 viewing probe data 7
using 361
Web Service Proxy
Welcome screen 1
WebSphere JMS
X
X-Virus, protection 51
backend-timeout 363 URL builder 54
X.509 certificates 358
service/reply-to-q 363 WebSphere JMS Front Side Handler
AAA Policy
service/reply-to-qm 363 purpose 84
authentication 358
skip-backside 363 queues 84
identity extraction 358
WSM support 84
verify action 358
listing 370 topic spaces 84
XACML PDP
service/wsa/genpattern 370 WebSphere Transformation Extender
authorization, AAA 191
service/wsa/timeout 370 See WTX
configuring 277
service/wsm/wsdl-error 370 Welcome screen 1
object pages 277
service/wsm/wsdl-warning 370 workstation
XDoS, protection 49
verify action 157 uploading files 204
xform
generating signature WS-Addressing
defining standard transform 149
confirmation 360 Multi-Protocol Gateway 304
XML messages 149
Kerberos AP-REQ tokens, remote 359 configuring 36
xform action
purpose 91 Synchronous to WS-Addressing 37
defining 149
SAML assertions, remote 359 WS-Addressing to Synchronous 38
defining buffer attachment
verifying signature confirmation 360 WS-Addressing to
transform 154
X.509 certificates, remote 358 WS-Addressing 40
defining conformance transform 155
View button 3 WS-Addressing to Synchronous
defining SOAP refinement
View Logs link 5 Mode 38
transform 152
View Status link 6 WS-Addressing to WS-Addressing 40
purpose 91
WS-ReliableMessaging
xformbin action
Multi-Protocol Gateway 304
defining 150
W Web Service Proxy
configuring 42
purpose 91
Web Management Interface 1 xformpi action
WS-SecureConversation
Web Service Proxy defining 151
authentication, AAA 178
defining policy parameters 312 purpose 91
credentials mapping, AAA 181
service variables XML Manager
identity extraction, AAA 168
backend-timeout 363 caches
WS-Security
service/reply-to-q 363 flushing the document cache 353
message layout filter 128
service/reply-to-qm 363 flushing the stylesheet cache 353
WS-Security Header
skip-backside 363 configuring 352
identity extraction, AAA
WS-ReliableMessaging document cache, flushing 353
BinarySecurityToken 168
configuring 42 Load Balancer Group
UsernameToken, derived-key 167
Web services monitors DataPower service 55
UsernameToken,
configuring 235 modifying 352
password-carrying 167
enabling 235 object pages 352
WS-Security Management
overview 234 XML virus, protection 51
See WSSM
specifying dual thresholds 237 XPath bindings
WS-Trust
web-mgmt command 1 AAA Policy 264
authentication, AAA 175
WebGUI XPath matching rule 87
identity extraction, AAA 169
accessing 1
post processing, AAA 196
Administration menu 1
WS-Trust messages
applying configuration changes 4
canceling changes 4
TFIM endpoint 272 Z
WSM variables z/OS NSS authentication
cloning services 6
listing 370 authentication, AAA 177
common tasks 4
service/wsa/genpattern 370 z/OS NSS authorization
dashboard 1
service/wsa/timeout 370 authorization, AAA 187
deleting objects 5
service/wsm/wsdl-error 370 z/OS NSS Client
Domain list 1
service/wsm/wsdl-warning 370 creating 354
exporting objects 5
wssecurity-message-layout-filter.xsl style overview 353
logging in 1
sheet 128
Logout button 1
WTX
Network menu 1
DPA 317
Objects menu 1
Exported Files 317
resetting configuration 5
input contexts 318
reverting changes 5
Mapping Logic Disabled 317
Save Config button 1
Named Inputs 321
saving configuration changes 4
Named Outputs 321
Services menu 1

Index 391
392 IBM WebSphere DataPower SOA Appliances: Multi-Protocol Gateway Developers Guide



Printed in USA